00. 怎么读这份文档

名称、路径与服务商

同一份二进制里有三套命名。混在一起时，人们往往会去找并不存在的 MatchaCode 账号，或把 xAI 当成产品本身。请把它们分开。

怎么分

种类	它在命名什么	例子
产品	你运行的 CLI 以及它写入的文件	MatchaCode（家族）、Matcha CLI、`matcha`、`~/.matcha`、`MATCHA_*`
服务商	你自行选择接入的第三方模型 API	`xai`、`openai`、`anthropic`、`openai_compatible`、`ollama`
兼容	旧的 Grok Build 名称，只读	`grok` shim、`GROK_*`、`~/.grok`、`.grok/`

xAI 只是可选的服务商。Matcha CLI 不会让你登录 grok.com，也不会创建 MatchaCode 账号。服务商模型 id（例如 grok-4.5）保持服务商自己的真实 id — 本指南不会改名。

家族 / 产品名：MatchaCode
CLI 展示名：Matcha CLI
命令：matcha
用户主目录：~/.matcha（用 MATCHA_HOME 覆盖）
项目目录：仓库根下的 .matcha/（workflows、项目自己的本地配置）
环境变量前缀：MATCHA_*（MATCHA_HOME、MATCHA_MEMORY、MATCHA_AGENT_SECRET、MATCHA_LOG_FILE……）

新的写入走这些名称。在 shell 配置和发给同事的说明里优先用它们。

echo "$MATCHA_HOME"          # empty means the default ~/.matcha
matcha inspect               # layers Matcha CLI discovered for this directory

凭证存放在 Matcha 凭证库（Credential Vault；可用时用操作系统钥匙串，否则是权限为 0600 的 ~/.matcha/credentials/secrets.json）。~/.matcha/auth.json 是元数据（配置了哪个服务商），不是密钥本身。

你自带 API Key。首次启动不会打开浏览器。

`--provider` id	显示名	官方密钥环境变量
`xai`	xAI	`XAI_API_KEY`
`openai`	OpenAI	`OPENAI_API_KEY`
`anthropic`	Anthropic	`ANTHROPIC_API_KEY`
`openai_compatible`（别名 `openai-compatible`）	OpenAI-compatible	该端点要求的密钥
`ollama`	Ollama	无（本地；loopback）

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

密钥绝不能作为 matcha login 的参数传入。--from-env 导入该服务商的官方环境变量。--validate 可在写入前探测端点（需要网络）。

不要给服务商密钥发明 Matcha 形状的名字（MATCHA_API_KEY 不能代替 OPENAI_API_KEY）。服务商官方变量保持服务商自己的名字，不会被改写成 MatchaCode 密钥。

/model 和 matcha -m 接受的是服务商模型 id，不是 MatchaCode 品牌。/docs Custom Models 讲 Ollama 和 OpenAI-compatible 的 base URL。

如果 Matcha CLI 导入了旧的 xAI token，它只作为 xAI 服务商凭证存放。绝不会变成 MatchaCode 账号。

如果你以前用过 Grok Build（grok）：

旧名称	Matcha CLI 会做什么
`grok` 二进制	与 `matcha` 同一套代码；弃用提示只走 stderr（stdout，包括 `--version` / JSON，保持干净）
`GROK_*`	匹配的 `MATCHA_*` 未设置时才会读取。两者都设置时，以 Matcha CLI 为准，诊断只报变量名，绝不报变量值
`~/.grok`	会被发现并复制迁移到 `~/.matcha`。绝不会自动删除
`.grok/`	读取并迁移到 `.matcha/`。冲突文件不会被悄悄合并
主题 `groknight` / `grokday`	仍会作为 MatchaNight / MatchaDay 加载
助手 id `grok-build*`	会映射；新的写入使用 `matcha-build` / `matcha-build-plan`

# Prefer:
export MATCHA_HOME="$HOME/.matcha-work"
# Still works if MATCHA_HOME is unset:
export GROK_HOME="$HOME/.matcha-work"

shim、已注册的 GROK_* 名称，以及对 ~/.grok 的只读发现，至少会保留两个 Matcha CLI 稳定版或 6 个月（以更长者为准）。之后可能撤掉；不要用 grok 写新脚本。

TUI 里的 /login 不出现在菜单中。如果你输入它，它只打印 BYOK 示例，不会打开浏览器。/logout 只清除本地凭证库。