参考
遇到问题 /doctor
heng-agent 出问题先运行 /doctor：一项项检查配置、服务商连接（真的连一次）、密钥、代理、终端、git、说明文件、钩子、MCP；反馈问题用 /doctor copy。附常见问题的原因与处理：找不到命令、升级失败、连不上服务商、中转站 401、Shift+Enter 不换行、MCP 连不上。
- 预计用时
- 约 3 分钟
- 适用版本
- v0.5.0 及以上
先运行 /doctor
在 heng-agent 里输入 /doctor，它一项项检查，哪一环出了问题一眼就能看到：
- 版本、配置文件、服务商连接（会真的连一次）、密钥、代理（请求实际走的是哪个）；
- 终端（Shift+Enter 换行）、外部编辑器、git；
- 说明文件、钩子、MCP、会话目录、兼容加载的 Claude Code 配置。
对照常见问题
| 现象 | 原因与处理 |
|---|---|
敲 heng-agent 提示找不到命令 |
安装时改了 PATH，要重开一个终端才生效；还不行就运行 uv tool update-shell 再重开 |
一启动就报 ModuleNotFoundError: heng_agent |
多半是 Windows 上 heng-agent 开着时升级 / 重装：文件被占用，装到一半失败。关掉所有 heng-agent 窗口，重新运行一键安装命令 |
heng-agent upgrade 说已是最新，但刚发了新版本 |
uv 缓存了旧的版本列表（0.3.2 起升级时会刷新）。旧版本手动运行 uv tool install --force --upgrade --refresh-package heng-agent heng-agent |
| 连不上服务商 | 看 /doctor 的「服务商连接」与「代理」两行：地址、密钥、请求实际走的代理。要单独指定或不走代理，见 服务商与配置文件 |
| 中转站报 401 | 配置档里试试改 auth：bearer 或 x-api-key |
| Shift+Enter 不能换行 | Windows Terminal 里运行 /terminal-setup；任何终端里 Ctrl+J、Alt+Enter 都能换行 |
| 配了 MCP 服务，有的连不上 | 欢迎页与 /mcp 会列出原因；改好后 /mcp reconnect 服务名，不用重启 |
| 出现「内部错误」 | 程序的 bug：这一问作废、会话照常。运行 /doctor copy 反馈 |
反馈问题：/doctor copy
/doctor copy 把检查结果连同最近的日志复制到剪贴板，用户目录换成了 ~，反馈问题时直接贴上去，不会带出本机用户名。
运行日志在数据目录的 logs/heng-agent.log：正式版 ~/.heng-agent/logs/，开发版 ~/.heng-agent-dev/logs/。
做完是这样
/doctor 每一项都是通过；有一项不对时，它写明是哪一环、原因是什么，照上表处理后再运行一次确认。