疑难排解

第一站: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-flash / deepseek-v4-pro(不要用营销日期后缀)。原生联网优先渠道 deepseek-anthropic。
• 识图走 deepseek-flash（原生多模态）。像素走 Files API。不再绕行到单独的 vision SKU。deepseek-v4-pro 不接受图片。

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 缓冲配置)—— 调大代理超时、给流式响应关闭缓冲。

LM Studio / 本地 OpenAI 兼容服务卡住或不调工具（v1.0.5）

粘贴 http://host:1234 —— hipmmcode 会自动补 /v1。工具 schema 始终带 properties。本地预填充最多等 10 分钟；首个文本之后空闲 5 分钟；HTTP 空闲读 10 分钟。Auto 模式下，kb_status、kb_search 这类只读 MCP 工具会跳过分类器；单卡本地 GPU 上 Bash / Write 仍可能被拒绝。

关掉 VPN 后什么都用不了

两个常见原因：

1. 当前渠道连的是官方地址。 xai-oauth、或者没设 XAI_BASE_URL 的 xai，都连 api.x.ai，国内需要 VPN。第三方网关要写在 XAI_BASE_URL 里，GROK_MODELS_BASE_URL 不生效。绑定平台套餐后，用 /model 切到 inclusive-grok / premium-grok / vip-grok。/status 里能看到当前渠道实际请求的地址。
2. shell 里留着本机代理。 v1.3.1 起本机代理没开时会自动直连；更早的版本请先 unset https_proxy http_proxy all_proxy HTTPS_PROXY HTTP_PROXY ALL_PROXY 再启动。

详见第三方 Grok 网关与 VPN。

手机连不上 /rcl

确认手机和电脑在同一网络（或同在 Tailscale 里），二维码里的地址是电脑的局域网地址。旧版本可能把 VPN 的 198.18.0.1 放进二维码，升级到 v1.3.1 即可。hipmmcode remote-control --list 看远程会话和本机中转的状态。见远程控制。

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 去哪了。

重命名后 @ 看不到那个会话

@ 只列出自定义标题或符合别名规则的名字（字母开头，字母数字 ._-）。自动生成的第一句标题不会出现。桌面端在侧边栏改成 alpha 这类名字即可，不必再跑 /peer。两边会话都要处于运行中。

桌面端添加 MCP 失败

公开 HTTP 通常只填 URL。需要鉴权时补 Authorization 或自定义头；本地进程选 STDIO，填写命令、参数和环境变量。保存后到设置页确认服务器已连接。

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

无头 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。