rpc-secret配置错误是webui无法连接aria2的主因，必须在aria2.conf中设置且webui填写时带token:前缀；同时需检查监听地址、防火墙、下载目录权限、磁盘空间及systemd自启配置。
rpc-secret 配置不对，WebUI 就连不上
绝大多数“无法连接到 Aria2 RPC 服务器”的报错，根源都在 rpc-secret 不匹配。WebUI（如 AriaNg、webui-aria2）连接时必须填对这个 token，它不是用户名密码，也不是空值，更不能漏掉前缀 token:。
实操建议：
在无 root/sudo 权限的环境（云容器、VPS、隔离主机）中安装并配置 OpenClaw 浏览器工具的 headless Chrome。适用场景：...
-
rpc-secret=MySuperSecret123写在/etc/aria2/aria2.conf里后，WebUI 的「RPC 密钥」栏必须填token:MySuperSecret123（注意token:前缀不能少） - 如果用命令行临时启动，
aria2c --enable-rpc --rpc-secret=abc --rpc-listen-all，那 WebUI 就得填token:abc - 浏览器控制台若报
403 Forbidden或Unauthorized，八成是密钥没带token:，或大小写/空格抄错了
监听地址 bind 和防火墙端口要同步放开
rpc-listen-all=true 并不等于“自动穿透防火墙”。它只是让 aria2 绑定到 0.0.0.0:6800，但系统防火墙（iptables/firewalld）默认会拦掉外部访问。
常见错误现象：本地浏览器能连 http://localhost:6800/jsonrpc，但手机或另一台电脑打不开 WebUI 页面。
实操建议：
- 确认 aria2 真正监听的地址：
ss -tlnp | grep :6800，输出中应含0.0.0.0:6800或*:6800；若只有127.0.0.1:6800，说明rpc-listen-all没生效或被覆盖 - Debian/Ubuntu：
ufw allow 6800；CentOS/RHEL：firewall-cmd --permanent --add-port=6800/tcp && firewall-cmd --reload - 云服务器（阿里云/腾讯云）务必去控制台安全组补上
6800/tcp入方向规则，光配系统防火墙没用
下载目录权限和磁盘空间不足直接导致任务静默失败
aria2 不会主动弹窗报错，dir=/mnt/downloads 路径若不可写、属主不对、磁盘满，任务状态可能卡在 “waiting” 或瞬间变成 “error”，日志里只有一行 Exception: [AbstractCommand.cc:351] CUID#X - Failed to open file。
实操建议：
- 运行
sudo -u aria2 ls -ld /mnt/downloads（假设 aria2 以用户aria2运行），确保该用户对目录有rwx权限 - 检查磁盘剩余：
df -h /mnt/downloads，低于 5% 容易触发 aria2 的写入保护 - 避免把
dir设为 root 用户家目录（如/root/downloads），普通服务账户通常无权写入 - 若用 NFS 或挂载的 NTFS 分区，需确认挂载参数含
uid=gid=，否则权限继承异常
开机自启失败，多半是 session 文件路径或依赖顺序没对齐
systemd 启动 aria2 时若提示 Failed to start aria2c download daemon，常因 aria2.session 文件不存在、路径写错，或 After=network.target 不够——有些 NAS 或树莓派网络初始化慢，aria2 启动太快连不上网关。
实操建议：
-
session=/var/lib/aria2/aria2.session必须是绝对路径，且该文件需提前创建：sudo touch /var/lib/aria2/aria2.session && sudo chown aria2:aria2 /var/lib/aria2/aria2.session - 在 systemd service 文件里加两行：
After=network-online.target和Wants=network-online.target，强制等网络就绪 - 不要把
rpc-secret写在命令行参数里（如ExecStart=... --rpc-secret=xxx），systemd 日志会明文泄露；务必放配置文件中 - 验证启动逻辑：
sudo systemctl daemon-reload && sudo systemctl start aria2 && sudo systemctl status aria2，看 Active 是否为 active (running)
WebUI 连接成功只是第一步，真正容易被忽略的是 continue=true 和 input-file 的组合使用——断电重启后，没配这两项，所有未完成任务就真丢了。
