配置服务商（BYOK）

MatchaCode 不是模型厂商。请求发往你选择的服务商：xAI、OpenAI、Anthropic、Ollama，或 OpenAI-compatible 端点。xAI 是服务商，不是产品。像 grok-4.5 这样的模型 id 仍是该服务商的真实 id。

密钥存在哪里

matcha login --provider <id> 读取密钥（安全 TTY 提示、stdin 管道，或该服务商的官方环境变量），做本地检查，可选地经网络探测服务商，然后把秘密写入密钥库：

1. 操作系统钥匙串（若可用：macOS Keychain、Windows Credential Manager、Linux Secret Service）。
2. 文件回退：~/.matcha/credentials/secrets.json，Unix 上属主独占模式 0600。

~/.matcha/auth.json 保存元数据（已配置哪个服务商）。它不是 API Key 的明文转储。

服务商 id

--provider 也接受若干带连字符的别名（x-ai、x.ai、open-ai），映射到同一套 id。未知 id 会失败，并列出内置项。

推理时的凭证优先级，从高到低：

1. ~/.matcha/config.toml 里按模型的 api_key 或 env_key
2. 来自 matcha login 的密钥库秘密
3. 该服务商的官方环境变量

服务商官方变量没有 MATCHA_* 别名。优先用 MATCHA_HOME，而不是已登记的 GROK_HOME；若 Matcha 名与已登记的 GROK_* 别名同时设置，Matcha CLI 胜出，诊断只点名变量、不打印值。

交互式提示

在能运行你构建的 matcha 二进制的终端里操作。这是常见路径：

matcha login --provider xai

你应看到：

Enter xAI API key (input hidden; Ctrl-C to cancel):

输入密钥并按 Enter。Unix TTY 上关闭回显。成功时，stderr 会报告类似：

Stored xAI API key for Provider `xai` (source: prompt).

若该服务商已存过密钥：Replaced the previous key for this Provider. 用 --provider openai 或 --provider anthropic 再跑一次，可存储另一个服务商。密钥彼此隔离；存 OpenAI 不会覆盖 xAI。

除非配置、环境或密钥库里已经选好服务商，否则必须带 --provider。若都未选定：

Specify a Provider with `--provider <id>` (one of: xai, openai, anthropic, openai_compatible, ollama).
Example: matcha login --provider xai

从服务商环境变量导入

export OPENAI_API_KEY="sk-..."          # example shape only — use your real key
matcha login --provider openai --from-env

--from-env 读取该服务商的官方变量，不打印值。来源报告为 env。

若变量未设置或为空，命令失败，且不改动已有密钥库条目：

Environment variable `OPENAI_API_KEY` is not set or empty. Existing credentials were not changed.

从 stdin 管道传入

stdin 不是终端时，用管道：

printf 'KEY' | matcha login --provider anthropic

不要把密钥 echo 进交互式提示（历史记录）。若 stdin 是 TTY 且未传 --from-env，Matcha CLI 使用安全提示。若 stdin 不是 TTY 且未传 --from-env，它从管道读取第一行。

可选的网络探测

matcha login --provider xai --validate

--validate 默认关闭，以便离线配置。打开后，Matcha CLI 在存储前探测服务商端点（约五秒）：

• xAI：GET {base}/api-key，带 Authorization: Bearer
• Anthropic：GET {base}/v1/models，带 x-api-key
• 其他密钥服务商：GET {base}/models，带 Bearer

200–299 探测打印 Online validation succeeded. 401 / 403 是 Provider rejected the API key. Existing credentials were not changed. 网络或其他 HTTP 失败则结论不定，且不覆盖已有的有效密钥。openai_compatible 需要已配置的 base URL，否则 --validate 失败并报 Online validation requires a Provider base URL。

OpenAI-compatible 与 Ollama

对 OpenAI-compatible 网关，用提示或管道存储密钥，然后在 ~/.matcha/config.toml 里设置 base URL。不要为该密钥发明 Matcha 品牌的环境变量。

对 Ollama，不要期望 matcha login --provider ollama 会存储秘密。Ollama 是本地 / 无需鉴权。命令会失败并报：

Provider `Ollama` does not use an API key (local / no-auth). Nothing to store.

改为在配置里把 Matcha CLI 指向回环上的 Ollama 守护进程（选中该服务商时，默认 base 是 http://127.0.0.1:11434/v1）。

在 TUI 里输入 /login

/login 对斜杠菜单隐藏。若你输入它，不会打开浏览器，也不会启动向导。它打印同一套 BYOK 示例：

Account login is unavailable in this Matcha build (Mode A). Configure a Provider API key from a terminal:
  matcha login --provider xai
  matcha login --provider openai --from-env
  printf 'KEY' | matcha login --provider anthropic

离开 TUI，在终端里运行其中一条命令。

登出

matcha logout

在 TUI 里输入 /logout 会让运行时清除已存凭证，并回到未配置服务商的配置状态。它不会打开产品登录屏。登出不会在服务商侧吊销密钥；若密钥可能已泄漏，到该服务商控制台轮换。

不能当作流程来用

这些标志存在，是为了让遗留脚本得到明确错误。不要去配置它们：

matcha login --oauth
matcha login --oidc
matcha login --device-auth
matcha login --device-code

预期的 stderr：

Account login is unavailable in this Matcha build (Mode A). Configure a Provider API key instead, for example:
  matcha login --provider xai
  matcha login --provider openai --from-env

--oauth 与 --device-auth 彼此冲突。没有 grok.com 登录，没有产品 OAuth，没有 device-code 轮询，没有 SSO / 企业 OIDC，也没有 SuperGrok 计费。

若出错了