04. 模型与推理力度

切换模型

选定本会话使用的服务商模型，让助手接下来这一段工作对着合适的工具跑。Matcha CLI 不托管模型市场。它对着你配置的服务商做推理，列出该服务商暴露的模型，并在现场列表不可达时复用本地目录缓存。

模型列表怎么组装

Matcha CLI 同一时间只对接一个当前服务商。内置服务商 id 有五个：

`--provider` id	显示名	常用凭证
`xai`	xAI	`XAI_API_KEY`
`openai`	OpenAI	`OPENAI_API_KEY`
`anthropic`	Anthropic	`ANTHROPIC_API_KEY`
`openai_compatible`	OpenAI-compatible	网关要求的密钥
`ollama`	Ollama	通常没有（本地守护进程）

当前服务商的列表由三部分拼成：~/.matcha/config.toml 里自定义的 [model.*] 行；远程模型列表（请求成功时）；以及远程列表失败时、按来源与鉴权匹配的磁盘缓存。从缓存加载的行在 matcha models 和选择器里标 (cached)。损坏的缓存会被忽略；Matcha CLI 不会从它再抓第二次。

当前服务商的列表组装完成后，默认挑选顺序是：

CLI -m / --model
MATCHA_DEFAULT_MODEL（仅当 Matcha 名未设置时，才读取旧名 GROK_DEFAULT_MODEL）
~/.matcha/config.toml 里的 [models].default
列表里第一条可选条目

先配置服务商

在指望看到列表之前，先存好密钥（或指向本地守护进程）。不要把秘密写在 matcha 命令行上。

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

BYOK 细节见「安装、凭证与第一次跑通」。本篇假定已经选好服务商。

列出当前服务商提供的模型

matcha models

命令会打印鉴权横幅、当前服务商为 Display (id)、默认模型 id、可选的 Catalog source 行，然后每一行是 id — Name (Provider)；来自磁盘时带 (cached)。当前默认标为 * … (default)。

未选定服务商时列表为空，命令会指向 matcha login --provider <id> 或 [model_providers]。

在会话里切换

斜杠命令

输入 / 并运行 /model（别名 /m）。必须带名称：

/model grok-4.5
/model Grok 4.5
/m gpt-4o

Matcha CLI 按模型 id 或显示名解析，不区分大小写。显示名可以含空格（Grok 4.5）；命令优先做整串目录匹配，避免较短的名字抢走前缀。

单独的 /model <name> 会切换本会话，并写入 [models].default 供之后的会话使用。Toast 确认 Default model: <display name>。只打 /model 不带名称会打印 Usage: /model <name> [effort] —— 不会打开选择器。

对支持推理的模型，可以再跟一个力度等级作为第二参数。这种形式只作用于本会话（不会走默认模型写入）。见「推理力度」。

/model Reasoning X high

自动补全：/model 之后，菜单列出 Name (Provider)，并标记 (cached) / (current)。推理模型会插入尾随空格，以便第二个菜单提供该模型的力度等级。

从回看区打开选择器

在回看区（不是输入栏）按 Ctrl+M。选择器列出与 /model 相同的目录，包括自定义 [model.*] 行。插入的文本仍是模型名，所以离开选择器后 /model grok-4.5 仍然可用。

在配置里钉死默认

[models]
default = "grok-4.5"

用当前服务商实际提供的 id。缺失的 [models].default / -m / MATCHA_DEFAULT_MODEL 值会打出上面的缺失 id 提示。

无界面与一次性调用

matcha -p "Hello" -m grok-4.5
matcha --model gpt-4o
matcha agent -m claude-opus-4-6

对该进程，-m / --model 优先于环境和 [models].default。

核对当前会话

/session-info（别名 /status、/info）显示鉴权方式、当前模型、轮次计数和上下文用量。

Matcha CLI 不会做什么

没有独立于服务商、由 MatchaCode 自有的默认模型目录。
没有 Matcha 托管的模型市场、账号档位目录，或会静默替换你默认项的远程活动。
模型 id 从不因品牌而改名。
图片生成、视频生成和产品网页搜索不可用。[models] web_search 与 MATCHA_WEB_SEARCH_MODEL 不会启用 MatchaCode 搜索服务。