11. 诊断

常见失败

这些是你实际会碰到的失败。每一项都能在这台机器上恢复。都不需要 MatchaCode 账号、反馈上传或应用内更新器。

先读报错，修好点名的文件、密钥或模式，再跑同一条命令。排查就是看失败、修测试，不是独立的 Debug 产品。

没有模型服务商

**你会看到：** 首屏写着 **No model Provider is configured**。主操作是 **Configure a model Provider**（c；l 仍可作为别名）。在设置服务商之前没有输入框。没有浏览器 OAuth、设备码或 grok.com 登录。

**这意味着：** Matcha CLI 没有用于推理的 BYOK 凭证。xAI 是可选项，默认不配置。MatchaCode 不是模型厂商。

**该怎么做：**

matcha login --provider xai
matcha login --provider openai --from-env
printf 'KEY' | matcha login --provider anthropic

服务商 id：xai、openai、anthropic、openai_compatible（别名 openai-compatible）、ollama。密钥从不接受写在命令行上。

在 TUI 里输入 /login **不会**打开向导。它会打印同样的 CLI 示例，并说明账号登录不可用。

也可以设置该服务商的官方环境变量（XAI_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY 等），或在 ~/.matcha/config.toml 里加一条 [model_providers.<id>]。

无界面 / ACP 文本用更长的说法：运行 matcha login --provider xai（或其他 id），设置官方环境变量，或加上配置条目。

API Key 无效

**你会看到：** 这一轮因鉴权错误失败。Toast 会去掉 Authentication failed: 前缀，所以你可能只看到服务商的原文（例如 **Incorrect API key provided**）。

**这意味着：** 本地已存储或已导出密钥，但服务商拒绝了它。这不是「没有服务商」。

**该怎么做：**

  1. matcha logout — 清除本地保险库条目。它不会在服务商那边吊销密钥。
  2. 再跑一次 matcha login --provider <id>。用安全提示、--from-env 或管道。
  3. 可选：matcha login --provider <id> --validate 在写入前探测。探测失败**不会覆盖**已有的有效密钥。

--oauth 和 --device-auth 失败是预期的。用 --provider。

能力被拒绝

**你会看到：** 一行拒绝，常见是 **… is unavailable in this Matcha build (Mode A).** 例如：

  • /feedback — Feedback submission is unavailable…
  • /usage manage — Account billing is unavailable…
  • /release-notes — Remote release notes are not published… Use /docs…
  • matcha update — Self-update is unavailable…
  • /share、/marketplace、/login（账号路径）— 同一模式

**这意味着：** 那个界面已关掉。二进制里仍保留这个名字，好让报错清楚。重试、设置 MATCHA_TELEMETRY_*，或把配置指到残留的产品 URL，都不会打开该功能。

**该怎么做：** 用本地替代。

被拒绝的改用
账号登录 / OAuthmatcha login --provider <id>
/usage manage、计费/usage 看**本地**会话计数
/release-notes、/announcements/docs、matcha --version
/feedback在本地修好；不要指望会上传
matcha update从源码重新构建
matcha trace 上传不要打开；若你自己导出，traces 仍留在本地
/share/export / matcha export

极简模式里的全屏专用命令

**你会看到：**

/theme isn't available in minimal mode (minimal renders with your
terminal's own palette). Run /fullscreen to switch this session.

其他全屏专用名字形状相同，理由不同：

命令极简模式拒绝的原因
/theme极简模式使用终端自己的色板
/find没有 Matcha CLI 回滚窗格——用终端自己的搜索
/jump、/timeline原生终端回滚
/dashboard、/workflows极简模式是单会话
/tutorial没有模态宿主

**这意味着：** 你在 --minimal / /minimal。--no-alt-screen 仍是全屏 TUI（内联），不是极简。那些命令在那里可用。

**该怎么做：**

/fullscreen

别名：/full。会话会以完整 TUI 重新启动。然后再跑那条命令。

反过来（已在完整 TUI 里输入 /minimal）会以极简模式重新启动。只存在于极简模式的命令（/expand、/edit-prompt）在全屏里会拒绝，并写 **Run /minimal to switch this session.**

配置无效

**你会看到：** Matcha CLI 仍能启动，但有些内容被忽略。或者一次设置写入说它在 **refusing to overwrite unparseable** config.toml（TOML 解析错误；消息不含密钥行）。

**这意味着：** 一个文件或一张表解析失败。加载器能跳过坏条目时就会跳过，所以一处笔误不会清掉其余配置。无效的 MCP 服务行不会阻止启动；它们会出现在 inspect 里。

**该怎么做：**

matcha inspect
matcha inspect --json

看这些：

  • **Config Sources** — (parse error) 对 (empty) 对一条生效路径
  • **Config Warnings** — 未知字段、无效值、冲突的键
  • **MCP Config Problems** — 某条服务条目上的 [error] / [warning]
  • **Config schema** — 未来的 schema_version 仍会加载已知字段；别名冲突点名的是键，不是值

matcha doctor 也会打印 config-schema、config-conflict 和 env-conflict（规范的 MATCHA_* 覆盖已登记的 GROK_* 别名；**不显示值**）。

修好点名的文件（通常是 ~/.matcha/config.toml，或项目 .matcha/ / .grok/ 配置）。存成有效的 TOML，再 inspect 一次。如果现场会话已经加载过旧文件，重启 matcha，让内存里用上新的解析结果。

还是卡住

  1. 终端用 /doctor 或 matcha doctor。
  2. 已发现的项目配置用 matcha inspect。
  3. How-to Guides 用 /docs。
  4. 推理一直起不来时，用 matcha login --provider <id> 确认服务商。

就对着眼前的报错处理：修测试、改点名的配置行，或换服务商密钥。不要把 /feedback 或 /announcements 当成下一步——在这份 Matcha CLI 里，它们不是用户排障流程。