自定义接口

可以在 ~/.matcha/config.toml 的 [model.<name>] 下附加额外模型，在 [model_providers.<id>] 下共享网关设置，或用 [endpoints].models_base_url / MATCHA_MODELS_BASE_URL 覆盖目录/推理基址。

API 后端

api_backend 为自定义 [model.*] 行选择线上协议：

[model.*] 行省略 api_backend 时默认为 chat_completions。这是自定义行的默认，不是说每个内置服务商都走 Chat Completions。内置 xAI 描述符用 responses；Anthropic 用 messages。

凭证解析顺序

每次请求，Matcha CLI 按此顺序解析 API Key：

1. [model.*] 行上的 api_key
2. env_key —— 字符串或名称数组；第一个已设置且非空的值胜出（便于 SSH LC_* 转发）
3. 当前服务商在密钥库里的秘密（matcha login --provider …）
4. 该服务商的官方环境变量（XAI_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY，…）

目录 URL 与推理 URL

目录抓取用 {base_url}/models（列表 URL 不同时，用 MATCHA_MODELS_LIST_URL / [endpoints].models_list_url）。推理用同一基址，除非某条 [model.*] 行设了自己的 base_url。现场列表失败时，本地磁盘缓存可能提供按来源与鉴权匹配的副本，并标 (cached)。

设置 models_base_url 会选中自定义 OpenAI-compatible 槽位，并用 API Key 鉴权。没有浏览器登录。

OpenAI-compatible 网关

matcha login --provider openai_compatible

然后加一条模型行（该服务商 id 没有默认 URL）：

[model.together-mixtral]
model = "mistralai/Mixtral-8x7B-Instruct-v0.1"
base_url = "https://api.together.xyz/v1"
name = "Mixtral 8x7B"
env_key = "TOGETHER_API_KEY"

或者把网关设一次，再让模型指向它：

[model_providers.gateway]
base_url = "https://gateway.example/v1"
# extra_headers / query_params / env_http_headers inherit onto models
# that set model_provider = "gateway" and omit their own copies

若某个键也出现在 base_url 查询串里，会被覆盖（后值胜出），而不是重复。

Ollama（本地）

ollama serve
ollama pull codellama
matcha login --provider ollama

[model.ollama-codellama]
model = "codellama"
base_url = "http://127.0.0.1:11434/v1"
name = "CodeLlama (Ollama)"

给官方服务商写一条显式行

也可以写一条 [model.*]，直接对接 Anthropic 或 OpenAI。需要额外头、覆盖上下文窗口，或走 Responses API 时有用：

[model.claude-opus]
model = "claude-opus-4-6"
base_url = "https://api.anthropic.com/v1"
name = "Claude Opus 4.6"
api_backend = "messages"
context_window = 200000
env_key = "ANTHROPIC_API_KEY"
extra_headers = { "anthropic-version" = "2023-06-01" }

[model.gpt-4o]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
name = "GPT-4o"
env_key = "OPENAI_API_KEY"

[model.gpt-4o-responses]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
name = "GPT-4o (Responses)"
api_backend = "responses"
env_key = "OPENAI_API_KEY"

或者把密钥存进密钥库，跳过 env_key：

matcha login --provider anthropic
matcha login --provider openai --from-env

自定义 `/models` 基址

当每个请求都应打到同一个网关时：

export MATCHA_MODELS_BASE_URL="https://api.acme.com/v1"
# Provider key as that gateway expects, for example:
export XAI_API_KEY="xai-..."
matcha

GROK_MODELS_BASE_URL 仅在 Matcha 名未设置时读取。可选的 MATCHA_MODELS_LIST_URL 会覆盖 {base_url}/models。

配置等价写法：

[endpoints]
models_base_url = "https://api.acme.com/v1"

[model.grok-4.5]
env_key = "XAI_API_KEY"

设置了 [endpoints].models_base_url 时，部分填写的 [model.*] 覆盖会继承该基址。这里的 XAI_API_KEY 只是「网关要什么密钥」的例子 —— 不是说推理默认走 xAI。

常见 `[model.*]` 字段

[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "Display Name"
description = "Optional description"
env_key = "GATEWAY_API_KEY"
api_backend = "chat_completions"
temperature = 0.7
top_p = 0.95
max_completion_tokens = 8192
context_window = 128000
extra_headers = { "X-Request-Tags" = "team=example" }
query_params = { api-version = "2026-07-22" }
env_http_headers = { "X-Tenant-Token" = "GATEWAY_TENANT_TOKEN" }

context_window 驱动自动压缩。新模型省略它时默认为 200,000 token —— 请设成与服务器一致。

作用于每一行目录（内置、预取或自定义）的全局默认在 [models] 下。按模型的值始终胜出：

[models]
default = "my-model"
temperature = 0.7
top_p = 0.95
max_completion_tokens = 8192
max_retries = 8
inference_idle_timeout_secs = 600
stream_tool_calls = true
extra_headers = { "X-Request-Tags" = "team=example,env=prod" }

stream_tool_calls 会改变请求形态。若某个 BYOK 网关拒绝全局 true，在该 [model.<id>] 上设 stream_tool_calls = false。

用来标识特定模型的设置（model、base_url、api_key、context_window，…）不能在 [models] 下给默认。推理力度仍放在 [models].default_reasoning_effort。

覆盖某个目录 id 时，只写你要改的字段。优先级：你的 [model.*] > 预取的 /v1/models > 硬编码的服务商默认。

使用自定义 id

matcha models

/model my-model

matcha -p "Hello" -m my-model

列表为空或调用失败时

matcha models

确认当前服务商确实提供该 id。检查 [model.*] 是否写错。按服务商的头方案探测网关（Bearer 对 x-api-key）；不要把密钥贴进工单。

RUST_LOG=debug MATCHA_LOG_FILE=/tmp/matcha.log matcha

找 model / sampling 行。日志里不得出现 API Key。

Matcha CLI 不会做什么

• 没有 MatchaCode 产品推理 URL，没有浏览器 OAuth，没有设备码登录。
• 产品网页搜索、图片生成和视频生成不可用。[models] web_search 不会启用它们。需要类似搜索的工具时，用本地 MCP 服务器。
• Ollama 不是远程 GPU 市场；内置服务商要求回环。