故障排查

Agent 检测不到

新会话菜单里 Agent 标灰，鼠标悬停会给出原因。按原因对号入座：

原因	解决
没装	参考各 CLI 官方文档安装
不在 PATH 里	确认 codex --version / claude --version 在普通系统终端里能跑
版本太旧	升级；也可在「关于」设置页一键升级

装的是第三方镜像包（如 @cometix/claude-code）时，「关于」页会提示官方版本，但升级只针对你已装的包，不会替换。

macOS 打不开 / 提示已损坏

安装包是 ad-hoc 签名、未经 Apple 公证。详见 安装：

• Finder 中右键应用 → 「打开」
• 或「系统设置 → 隐私与安全性」→ 「仍要打开」

Windows 提示「未知发布者」

SmartScreen 拦截，点「更多信息」→「仍要运行」。详见 安装。

终端颜色不对（Windows 上输入框变黑块）

这是 Codex 这类 TUI 查询终端颜色的 OSC 10/11 超时导致的。Belfry 已在 Rust 侧直接应答来规避。如果仍遇到，多半是 ConPTY 调色板读取问题——试试切换主题（亮/暗），主题色会同步喂给终端调色板。

用量数字对不上账单

用量面板来自 Agent 自己写的本地日志，只能当参考，不是账单。差异常见原因：

• 缓存命中的计费率不同（input 与 cachedInput 已分开统计）
• 套餐打折、免费额度未计入
• 以服务商控制台为准

协作派活失败

协作依赖 Belfry skill、CLI 登录态与协作通道。去设置页跑环境诊断：

• 检查 Belfry skill 是否就位且为最新
• 检查 Codex / Claude 的登录与功能状态
• 查看 doctor 结果与协作通道连通性

诊断保留部分成功结果：一个客户端失败不会掩盖另一个的成功。按报告逐项修复即可。

清除已保存的 SSH 密码

SSH 表单里可以随时清除已保存的密码（存在系统钥匙串里）。打开 SSH 会话设置即可操作。

还是没解决

在 GitHub Issues 开一个 issue，附上：

• 操作系统与版本
• Belfry 版本（「关于」设置页可查）
• 复现步骤
• 看到的现象与预期

免责声明

Belfry 是终端与会话的托管层，不对 Agent 在你机器上执行的命令负责。Agent 的权限就是你 Shell 的权限：给它读写文件、跑构建、装依赖的能力，它就有能力删掉不该删的东西。请在有版本控制的目录里用它，重要操作自己过一眼。

用量面板的数字来自 Agent 自己写的本地日志，只能当参考，不是账单。请以服务商控制台为准。