常见问题与故障排查

先收集安全诊断

cocode doctor
cocode host status --json

反馈时附上 OS、Cocode 版本、GUI/TUI 入口、发生时间和脱敏后的输出。不要上传 API Key、OAuth 链接、Cookie、provider secret 或完整 session log。

安装后无法启动

确认安装包与你的操作系统和架构匹配，并重新打开终端或应用。命令行问题可以先运行：

cocode --help

TUI 还需要 Node.js 22.19.x+ 和真实 TTY；在 CI、IDE 假终端或管道中运行可能无法工作。

登录失败或停在浏览器页面

确认浏览器已完成登录，回到 Cocode 后等待授权状态更新。设备码过期或被拒绝时重新执行登录；不要把授权链接、Cookie 或 API Key 复制到公开 issue。

Supervisor unavailable、RUNTIME_* 或 TUI 卡在 starting 时，先执行 cocode host status --json，必要时 cocode host stop --force 后重试。

模型调用失败

先确认当前账号有可用额度，再检查模型是否仍在套餐和模型目录中。若出现 interactive_session_required，改用支持交互会话的入口；若出现限流，等待窗口恢复或降低并发。错误码按 AUTH_*、RUNTIME_*、COMMAND_*、SESSION_*、CONFIG_*、IO_* 分类，保留 code、时间和脱敏上下文即可。