第17章 排查问题 · Codewhale 文档

排查问题先运行一条诊断命令，再在下面找到你遇到的症状。每条解决办法都写明了你会看到的确切报错。运行诊断codewhale --version codewhale doctor codewhale doctor --probe-api # one real test call to your provider codewhale auth status --provider deepseek # which key is in usecodewhale doctor --json 会生成一份不含任何密钥的诊断包，可以直接附到 issue 上。单独运行 doctor 不会告诉你当前用的是哪把密钥，即使没有密钥也会正常退出；查密钥请用 auth status。安装与更新codewhale: command not found当前终端的 PATH 中没有 ~/.local/bin。把 export PATH="$HOME/.local/bin:$PATH" 加入 shell 配置文件，然后打开一个新终端。npm error code EACCES你的 Node 由系统管理。不要用 sudo：用 npm config set prefix "$HOME/.npm-global" 让 npm 安装到你自己的目录，把其中的 bin 加入 PATH，再重新安装。refusing to replace existing ~/.local/bin/codewhale那里已经装了另一个版本。运行 codewhale update，或者先删除旧的二进制文件。checksum mismatch下载的文件损坏或被篡改，因此没有安装任何东西。请重试；如果一再出现，不要使用镜像源。The package-managed executable was not changed.你是通过 npm、Cargo 或 Homebrew 安装的，请用对应的工具更新，例如 npm install -g codewhale。没有回复，或密钥被拒消息发出后一直没有回复没有配置密钥，而 v0.10.0 不会提示你。按 F3，选择你的提供商，粘贴密钥。API key not found哪里都找不到密钥。用 codewhale auth set --provider <名称> 保存一把。Authentication Fails … is invalid密钥错误或已被吊销。运行 auth status 查看用的是哪个来源——已保存的密钥优先于环境变量——然后保存正确的密钥，或运行 codewhale auth clear --provider <名称>。Network error: SSE stream request failed …通常是连不上提供商。用 curl -sI https://api.deepseek.com 检查（返回 401 说明能连通）。在代理后面时请导出 HTTPS_PROXY；在 Windows 或限制严格的代理环境下，可以试试 CODEWHALE_FORCE_HTTP1=1。回合卡住了按 Esc 取消当前回合。Esc 会先关闭已打开的菜单，所以如果开着菜单，需要再按一次。如果是一条耗时很长的 shell 命令拖住了回合，按 Ctrl-B 把它移到后台。回合会继续进行，/jobs 中可以看到这条命令。/retry 会重新发送上一次请求。需要详细记录时，用 RUST_LOG=codewhale_tui=debug 启动 Codewhale（排查连接重试用 RUST_LOG=codewhale_tui::client=debug）。日志写在 ~/.codewhale/logs/ 下。恢复会话codewhale sessions # list saved sessions codewhale resume # an id or a unique prefix codewhale -c # the latest session in this folder在 Codewhale 中按 Ctrl-R 可以打开会话选择器。如果 codewhale exec --continue 报出 No saved sessions found for workspace，说明之前那次是普通的 exec 运行，它不会被保存；想接着运行的任务请使用 --output-format stream-json。离线时发送的消息会随会话一起保存在队列中，/queue list 可以查看。网络恢复后，用 /queue edit 打开其中一条，按 Enter 发送。MCP 工具不见了修改 mcp.json 或服务器凭据后，运行 /mcp reload。/mcp validate 只会刷新界面上显示的内容。在 shell 中亲自运行一遍服务器命令，确认它能启动。如果配置文件丢失或损坏，codewhale mcp init --force 会重新生成一份。在 Docker 中运行docker volume create codewhale-home docker run --rm -it \ -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \ -v codewhale-home:/home/codewhale/.codewhale \ -v "$PWD:/workspace" -w /workspace \ ghcr.io/hmbown/codewhale:latest镜像以非 root 用户运行，把你的设置和会话保存在命名卷里。想要可重复的环境，请固定某个发布标签而不是 latest；每个项目使用单独的卷；永远不要把密钥打包进镜像。下一步连接模型提供商保存密钥、查看当前使用的是哪一把，或改用本地模型。安装 Codewhale所有安装方式，以及每一步应有的输出。查看改动把文件回滚到出问题之前那个回合的快照。