疑难排解

第一站:doctor

hipmmcode doctor          # 密钥、配置路径、home 目录、MCP/技能计数、常见问题
hipmmcode doctor --json   # 机器可读

REPL 里 /doctor 跑同样的检查。

常见问题

"No API key" / 首回合模型报错

• hipmmcode doctor 显示各渠道密钥有无。设置:hipmmcode config set <provider>.apiKey=… 或对应环境变量。
• OAuth 渠道(openai-codex、xai-oauth、qwen-oauth):跑 hipmmcode model <channel> 完成设备码登录(或确保外部 CLI 凭证文件存在:~/.codex/auth.json、~/.grok/auth.json、~/.qwen/oauth_creds.json)。
• 代理渠道拒绝模型名时,看 /model —— 选择器只列该渠道真正提供的模型。hipmmcode models -p <channel> 显示实时列表。
• DeepSeek:API id 用 deepseek-v4-flash / deepseek-v4-pro(不要用营销日期后缀)。原生联网优先渠道 deepseek-anthropic。

WebSearch 提示关闭或需要 key

• Anthropic / deepseek-anthropic / Gemini / xai / xai-oauth 为渠道原生搜索 —— 确认 nativeSearchEnabled 开启(/nativesearch on)。
• 其他渠道配置 AnySearch:/anysearch key=as_sk_… 然后 /anysearch on。见联网搜索。

Grok 上 GenerateImage 返回 HTTP 400

xAI Imagine 会拒绝 OpenAI 专有字段。hipmmcode 会映射 size/quality;若你自己打 API,请用 Imagine 参数(aspect_ratio、response_format: b64_json)。渠道用 xai 或 xai-oauth。

自定义代理报错或回空响应

先直接测端点,再怀疑配置:

curl -sS -X POST "$BASE_URL/v1/messages" -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"…","max_tokens":32,"messages":[{"role":"user","content":"hi"}]}' -v

空响应、固定间隔(~3 秒)断连、间歇性 5xx 风暴都是代理侧问题(上游超时、缺 SSE 缓冲配置)—— 调大代理超时、给流式响应关闭缓冲。

TUI 显示错乱 / 颜色不对

• 用现代终端(Windows 上用 Windows Terminal,别用老控制台)。
• hipmmcode config set tui=inline 切经典渲染器。
• /color 选适配你配色的主题;无头输出遵守 NO_COLOR 与哑终端降级。

Shift+Enter 没反应 / 直接发送了

跑一次 /terminal-setup —— 它为你的终端装好键位映射(Apple Terminal 上是 Option+Enter)。

安装后没有默认技能包

hipmmcode skill install-defaults
hipmmcode skills

若提示找不到 pack:保持 default-skills/ 与二进制同级(发布包布局),或设置 HIPMMCODE_DEFAULT_SKILLS_DIR。见技能 — 默认包。

权限弹窗太多 / allow 列表膨胀

新安装默认 defaultMode: auto。优先用 Auto,不要把超长 permissions.allow 塞进 config.json。规则写在 ~/.hipmmcode/settings.json。可重置为精简默认:

{
  "permissions": {
    "defaultMode": "auto"
  }
}

某个技能 / hook / MCP 服务器行为异常

hipmmcode --safe-mode      # 禁用全部自定义运行
hipmmcode --bare           # 快速启动:完全跳过发现

safe mode 能修好的话,逐个恢复(/reload-skills、/mcp、/hooks)排查。

接近上下文上限时变慢

盯 HUD 压力表。/compact 拿回大部分窗口;微压缩与自动压缩默认开。/context 精确显示 token 去哪了。

无人值守运行里的权限弹窗

无头 ask 决策失败关闭。选个策略:--permission-mode acceptEdits、--permission-webhook,或(仅限可信沙箱)--dangerously-skip-permissions。见权限。

调试日志

RUST_LOG=hipmmcode=debug hipmmcode …      # tracing 输出
hipmmcode config set showWarnings=true    # REPL 里显示 WARN(或 /warnings on)

状态位置

路径	内容
<原生配置根目录>/config.json	模型、密钥、MCP、UI(0600)
<原生配置根目录>/settings.json	权限 defaultMode + allow/deny/ask(规则优先写这里)
<原生配置根目录>/sessions/	会话快照
<原生配置根目录>/projects/<key>/memory/	持久记忆
<原生配置根目录>/{agents,skills,legions,teams,plugins}/	你的资产(L1 默认技能在 skills/)
<原生配置根目录>/direct-connect.json	serve 发现锁文件

<原生配置根目录> 按 HIPMMCODE_CONFIG_DIR → 否则 CLAUDE_CONFIG_DIR（v0.16.0+）→ 否则 HIPMMCODE_HOME → 否则 ~/.hipmmcode 解析。净室运行可用 HIPMMCODE_CONFIG_DIR=$(mktemp -d) hipmmcode。CLAUDE_CONFIG_DIR 始终选择独立 Claude 兼容树用于导入；未设 HIPMMCODE_CONFIG_DIR 时也作为原生根回退。

还没解决?

• hipmmcode integration —— 内嵌集成手册。
• /release-notes —— 最近改了什么。
• GitHub issues。