故障排查

接入后机器一直显示「离线」，或网页里没有出现

可能原因： 目标机上的接入程序没有运行，或者出站网络被防火墙或网络策略阻挡；机器重装后， 机器码也可能已经变化。

怎么处理：

1. 确认目标机上的接入程序正在运行；系统服务通常会在它意外退出后重新拉起。
2. 确认目标机能正常出站访问网络。
3. 仍未恢复时，在「机群」页重新走一次「接入新机」。

智能体显示「未登录」，无法打开会话

可能原因： Claude Code 或 Codex 使用了第三方中转站，凭据不在默认位置；或者环境变量只写在 某个临时 shell 配置里，后台接入程序无法读取。

怎么处理：

1. 先在目标机命令行确认智能体本身能正常启动。
2. 使用中转站时，将 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN，或 Codex 使用的 OPENAI_API_KEY 放在系统或用户级环境变量中；Claude Code 也可使用 ~/.claude/settings.json 的 env。
3. 不要只写入 PowerShell 的临时 profile；修改后重启接入程序。

终端频繁断开，刚连接就掉线

可能原因： 本机网络代理的 TUN 或透明代理模式拦截并切断了终端二进制数据流。

怎么处理： 让代理对云鸢域名走直连，或临时切换到兼容的 Base64 传输模式后重连。 切换普通网络或关闭透明代理也可用于快速判断。

粘贴或拖入图片上传失败

可能原因： 临时网络异常，或当前部署的文件存储不可用。

怎么处理： 先重试并检查网络；持续失败时切换网络，或联系管理员检查存储状态。

Windows 弹出黑色命令行窗口，关闭后机器就离线

可能原因： 后台服务安装失败，接入程序降级成前台进程；黑色窗口就是正在运行的接入程序。

怎么处理： 升级到最新版客户端并重新安装后台服务。新版会以无窗口后台进程运行。

控制台版本不对，或自动更新没有生效

可能原因： 正在运行的旧版客户端无法替换自身，Windows 上尤其常见。

怎么处理： 手动更新一次到最新版。完成这次更新后，后续自动更新即可恢复。