Troubleshooting

故障排查

文档首页 · 安装 · CLI 参考

先确认使用的是发行包还是源码环境，再记录软件版本、操作系统和具体功能。尽量保留错误信息与失败时间，避免直接重试会修改目标的操作。

第一轮检查

源码环境在仓库根目录运行：

uv run argusai version --json
uv run argusai doctor --json

doctor 会检查环境、受管运行时、浏览器和渠道配置等项目。某个按需工具“未安装”并不代表所有功能不可用，先看它是否是当前任务所需的依赖。

桌面启动使用 uv run argusai --gui。交互终端中裸 argusai 会进入 ops 控制台，这是正常分流。

GUI 无法启动、白屏或前端不存在

1. 确认 Python 环境已经安装项目依赖，且 Windows WebView2 或 Linux GTK/WebKitGTK 已准备好。 Linux 还要确认应用所用 Python 环境能加载所选 GTK/Qt 后端；只安装系统库不一定能让 uv 虚拟环境导入 gi。检查方法见 安装与环境。
2. 源码环境确认 argusai/webui/dist/index.html 存在。重新执行：

npm --prefix argusai/webui ci
npm --prefix argusai/webui run build
uv run argusai --gui

3. 用终端显式启动，保留启动错误信息。设置中的日志诊断可帮助定位数据目录与日志位置；分享前脱敏。
4. 如果只有某个功能面板失败，记录面板名称、最近操作与错误，而不是先清空整个数据目录。

AI 无响应或模型不可用

先检查端点是否启用、模型名是否存在、接口协议和地址是否匹配，以及服务是否可达。HTTP 401/403 通常需要核对认证和服务权限；429 与服务限额有关，5xx 或超时需要结合服务状态判断。

每个对话保存自己的模型选择。全局端点默认值改变，不会自动替换已有对话的选择。若原端点或模型已移除，在当前对话的模型列表中重新选择。

API key、授权头或完整模型请求不要贴到公开 Issue。提供脱敏后的状态码、错误摘要、模型名与复现步骤即可。

两个对话的开关或模型看起来不同

这是预期行为：对话工具栏设置只作用于当前对话。设置页的审批默认值用于新对话。切换后以当前对话展示的配置为准。

如果 UI 状态与实际行为不符，记录会话是否为新建、是否从历史恢复、是否正在运行，以及通过哪个入口修改设置。不要通过扩大自动审批范围来掩盖工具错误。

浏览器无法使用

检查 doctor 的浏览器结果，并核对系统 Chrome、设置的浏览器路径和所需运行时。首次使用可能需要确认安装受管 Node 环境。

附着浏览器时核对连接目标及登录态；托管浏览器与用户自己的浏览器是不同的工作环境。浏览器实况面板中的观看和控制权交接需按当前状态操作，详见 Agent 与会话。

代理访问 HTTPS 失败

确认客户端代理地址与端口、代理是否启动、scope 与排除规则，以及代理 CA 是否按测试环境要求受信任。不要先全局关闭证书校验。

如页面一直等待，检查是否启用了断点或改写规则，先查看挂起请求。代理支持超时处理，但主动规则仍可能影响请求。操作流程见 Web 审计与代理。

逆向工具缺失或设备不可见

在逆向工具链设置中扫描 PATH 或配置工具的绝对路径。工具有各自的依赖：例如 adb、JADX、APKTool、Ghidra 和 Frida 并非所有功能都默认随应用安装。

移动动态分析需要设备已出现在 adb 中。不要把设备未连接误认为 Agent 应当自动启动模拟器。先完成静态分诊，再按需要准备动态环境。

受管运行时下载或校验失败

检查网络、离线状态、镜像配置、磁盘空间与安装目录权限。离线环境只能复用已安装好的对应运行时。

哈希或依赖 integrity 不匹配时，安装会停止。不要通过删掉校验或手工信任来源不明文件来继续；记录来源与错误后，使用受管修复或配置可信镜像。

定时任务没有按预期运行

逐项核对：

• 托管进程是否在线，使用 GUI 还是 argusai serve run。
• 任务是否启用，触发规则、文件路径或 Webhook 地址是否正确。
• 执行目的地是新对话、专属对话还是继续现有对话。
• 当前对话是否忙碌、等待人工处理，或存在延期原因。
• 是否达到有限次数上限，模型与工具是否可用，是否缺少相应高风险授权。

不要在 GUI 和无界面服务间同时争用同一个数据根目录。先看该任务的运行记录，再判断是没有触发、被延期，还是触发后执行失败。详见 自动化。

渠道凭据或配对异常

检查渠道启用状态、适配器状态、私聊配对流程和当前绑定的会话。跨设备或系统用户复制渠道凭据后，加密内容可能无法解密，需要在目标环境重新配置。

对只在本机允许确认的敏感操作，应回本机处理。不要因为远程渠道没有响应，就把服务监听改成任意公网地址。见 集成。

打包失败

先运行 python build.py --dry-run 检查目标平台与模式，再确认编译器、NSIS、Xcode 或 patchelf 等平台依赖。--skip-webui 要求已有前端产物，不能代替前端构建。

如果旧产物正在运行，先正常退出该程序，再重建。原生包应在目标系统和架构环境中编译。详见 构建与发布。

提交一个有用的问题报告

提供版本、系统、安装方式、复现步骤、预期行为、实际行为和脱敏日志。说明是否使用了外部模型、工具或远程渠道，以及问题是否只出现在某个会话。

如果可以，用一份可以公开的最小材料复现。删除 API key、Cookie、个人信息、企业域名和未经允许的样本内容后再提交。