Troubleshooting

故障排查

先运行完整诊断

better-codex doctor

诊断会检查 Core、后台服务、Runtime、数据库、Codex 安装、兼容层、页面集成、Skill、MCP 和更新验证密钥。排障时应先确认具体失败项，不要只根据侧边栏是否出现判断整个安装状态。

侧边栏没有任务看板或智能体

1. 确认是从 Better Codex 启动入口打开 Codex。
2. 运行 better-codex launcher status。
3. 运行 better-codex mcp status。
4. 运行 better-codex status，检查 Runtime、injection 和 injector。
5. 运行 better-codex launch --restart 重新启动并接入。

如果刚刚更新过 Codex Desktop，运行 better-codex update compatibility 检查兼容层更新。

Runtime 不可用

运行：

better-codex service status
better-codex service logs --lines 100
better-codex start

macOS 正式版使用系统后台服务；源码开发实例使用隔离的开发运行目录。不要同时手动启动多个相同配置档的 Runtime。

MCP 未注册

better-codex mcp install
better-codex mcp status

修复后重新打开 Codex。MCP 用于向 Codex 注册 Better Codex 应用入口和路由，本身不存储任务数据。

更新失败

1. 运行 better-codex update check 查看当前通道和可用版本。
2. 运行 better-codex doctor 确认更新验证密钥存在。
3. 查看 ~/.better-codex/logs/update.log。
4. 必要时运行 better-codex update rollback 回滚托管更新。

不要通过手动覆盖版本目录绕过签名、归档校验或暂存验证。

Windows 找不到 Node.js 或 Codex CLI

Better Codex 需要 Node.js 22.5 或更新版本。重新运行正式版或 Beta 安装器，它会检查 Node.js，并解析当前用户可执行的 Codex CLI。Microsoft Store 的占位路径不一定能被后台 Runtime 直接执行，因此应以 better-codex doctor 的 Codex 检查结果为准。

任务一直不自动运行

检查：

• 看板是否已切换到自动运行
• 任务是否分配给 Agent
• 任务是否仍在 待规划
• Agent 是否已达到最大并发数
• 任务是否正在等待用户审核或解除阻塞
• 是否已经存在活动运行

手动模式下，必须点击立即开始或在已完成的关联会话中发送后续消息。

日志与本地路径

macOS 默认路径：

• Runtime 日志：~/.better-codex/logs/runtime.log
• 页面集成日志：~/.better-codex/logs/injector.log
• 更新日志：~/.better-codex/logs/update.log
• Worker 日志：~/.better-codex/logs/worker.log
• 单次运行日志：~/.better-codex/logs/runs/

Windows 对应目录位于 %USERPROFILE%\.better-codex\logs\。

公开提交 Issue 前请删除本地用户名、绝对路径、任务内容、访问令牌和其他敏感信息。

仍未解决

提交 GitHub Issue 时，请提供操作系统、Codex 来源、Better Codex 版本、doctor 中失败的检查项和最小复现步骤。不要上传完整数据库或未脱敏日志。