模型提供商

LLM/模型提供商（不是 WhatsApp/Telegram 之类的聊天渠道）的参考文档。关于模型选择规则，请参见 Models。

快速规则

模型引用与 CLI 辅助工具

模型引用使用 provider/model（示例：opencode/claude-opus-4-6）。
agents.defaults.models 存储别名和按模型设置；agents.defaults.modelPolicy.allow 是可选的显式覆盖白名单。
CLI 辅助工具：openclaw onboard、openclaw models list、openclaw models set <provider/model>。
models.providers.*.contextWindow / contextTokens / maxTokens 设置提供商级默认值；models.providers.*.models[].contextWindow / contextTokens / maxTokens 按模型覆盖它们。
回退规则、冷却探测，以及会话覆盖持久化：模型故障转移。

openclaw configure 在你添加或重新认证某个提供商时，会保留现有的 agents.defaults.model.primary。openclaw models auth login 也会这样做，除非你传入 --set-default。提供商插件仍可能在其认证配置补丁中返回一个推荐的默认模型，但当主模型已存在时，OpenClaw 会把这理解为“让该模型可用”，而不是“替换当前主模型”。若要有意切换默认模型，请使用 openclaw models set <provider/model> 或 openclaw models auth login --provider <id> --set-default。

OpenAI 提供商/运行时拆分

OpenAI 模型引用和代理运行时是分开的：

openai/<model> 选择规范的 OpenAI 提供商和模型。仅此前缀本身绝不会选择 Codex。
当提供商/模型运行时策略未设置或设置为 auto 时，只有在确切匹配官方 HTTPS Platform Responses 或 ChatGPT Responses 路由，且没有手动指定的提供商请求覆盖时，OpenAI 才可能隐式选择 Codex。有效的模型范围快速模式控制不算作手动指定的请求参数。
手动指定的 Completions 适配器、自定义端点，以及带有手动指定请求行为的路由，都会继续使用 OpenClaw。纯文本官方 HTTP 端点会被拒绝。
旧版 Codex 模型引用属于旧版配置，doctor 会将其重写为 openai/<model>。
提供商/模型的 agentRuntime.id: "openclaw" 会明确让原本符合条件的路由继续使用 OpenClaw。agentRuntime.id: "codex" 要求使用 Codex；当生效路由不兼容 Codex 时会安全失败。

参见 OpenAI 隐式代理运行时和 Codex 运行环境。如果 provider/runtime 的拆分令人困惑，请先阅读代理运行时。插件自动启用遵循相同边界：隐式兼容 Codex 的实际路由可以启用 Codex 插件，而显式的 provider/model agentRuntime.id: "codex" 或旧式 codex/<model> 引用则需要它。仅有 openai/* 前缀本身并不会触发。全新的 OpenAI API-key 和 ChatGPT/Codex OAuth 设置会选择规范的 openai/gpt-5.6-sol 引用。裸的直接 API openai/gpt-5.6 别名仍受支持，并会解析为 Sol。添加或刷新 OpenAI 认证时，包括 openai/gpt-5.5 在内的现有显式主模型都会被保留。在无法访问 GPT-5.6 的账户中，GPT-5.5 仍可通过任一运行时作为显式恢复选项使用。

CLI 运行时

CLI 运行时使用相同的拆分方式：先选择规范模型引用，例如 anthropic/claude-* 或 google/gemini-*，然后在你想使用本地 CLI 后端时，将 provider/model 运行时策略设置为 claude-cli 或 google-gemini-cli。旧式 claude-cli/* 和 google-gemini-cli/* 引用会迁移回规范的提供商引用，同时把运行时单独记录。旧式 codex-cli/* 引用会迁移为 openai/* 并使用 Codex app-server 路由；OpenClaw 不再保留捆绑的 Codex CLI 后端。

在 Control UI 中配置提供方

在 Control UI 中打开 Settings → Model Providers，以添加、替换或移除存储在 models.providers.<id>.apiKey 中的提供方 API 密钥。页面会显示每个 API 密钥是来自 OpenClaw 配置还是环境变量，但不会显示凭据本身。通过环境提供的密钥仍由网关进程环境管理。使用 Test connection 运行实时提供方探测，并查看延迟，或查看分类后的身份验证、速率限制、计费、超时或响应错误。探测会向提供方发起真实请求，可能会消耗少量 token。也可以从提供方卡片中注销 OAuth 和 token 配置文件。 Default models 卡片用于管理主模型、按顺序的回退模型，以及来自已配置模型目录的实用模型。选择模型后，将它们一起保存到现有的 agents.defaults.model 和 agents.defaults.utilityModel 设置中。对于实用模型，Automatic 会保持该设置未定义，而 Disabled 会存储一个空字符串以关闭实用路由。

提供商专属行为

大多数特定于提供商的逻辑都位于提供商插件（registerProvider(...)）中，而 OpenClaw 则保留通用的推理循环。插件负责引导流程、模型目录、身份验证环境变量映射、传输／配置规范化、工具模式清理、故障转移分类、OAuth 刷新、使用情况报告、思考／推理配置文件等。有关提供商 SDK 钩子和捆绑插件示例的完整列表，请参阅提供商插件。需要完全自定义请求执行器的提供商属于更深层次的扩展领域。

提供商专属的运行器行为位于显式的提供商钩子上，例如重放策略、工具模式规范化、流包装器以及传输／请求辅助函数。传统的 ProviderPlugin.capabilities 静态集合仅用于兼容性，共享运行器逻辑已不再读取它。

API 密钥轮换

密钥来源与优先级

通过以下方式配置多个密钥：

OPENCLAW_LIVE_<PROVIDER>_KEY（单个实时覆盖，优先级最高）
<PROVIDER>_API_KEYS（逗号或分号分隔列表）
<PROVIDER>_API_KEY（主密钥）
<PROVIDER>_API_KEY_*（编号列表，例如 <PROVIDER>_API_KEY_1）

对于 Google 提供商，也会将 GOOGLE_API_KEY 作为回退项。密钥选择顺序会保留优先级并去重。

何时触发轮换

只有在速率限制响应时才会使用下一个密钥重试请求（例如 429、rate_limit、quota、resource exhausted、Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded，或周期性的用量限制消息）。
非速率限制失败会立即失败；不会尝试密钥轮换。
当所有候选密钥都失败时，返回最后一次尝试的最终错误。

官方提供商插件

官方提供商插件会发布自己的模型目录条目。这些提供商不需要models.providers模型条目；只需启用提供商插件、完成身份验证并选择模型。仅当你需要明确自定义提供商或设置更严格的请求参数（例如超时时间）时，才使用models.providers。

OpenAI

提供商：openai
认证：OPENAI_API_KEY
可选轮换：OPENAI_API_KEYS、OPENAI_API_KEY_1、OPENAI_API_KEY_2，以及 OPENCLAW_LIVE_OPENAI_KEY（单一覆盖）
全新设置默认值：openai/gpt-5.6-sol。
示例模型：openai/gpt-5.6-sol、openai/gpt-5.6-terra、openai/gpt-5.6-luna、openai/gpt-5.5；裸的直接 API openai/gpt-5.6 别名仍受支持。
如果特定安装或 API 密钥的行为有所不同，请使用 openclaw models list --provider openai 验证账户／模型可用性。
CLI：openclaw onboard --auth-choice openai-api-key
直接 OpenAI API-key Responses 请求默认为 "sse"。
通过 agents.defaults.models["openai/<model>"].params.transport 按模型覆盖（"sse"、"websocket"、"websocket-cached" 或 "auto"）。缓存 WebSocket 会复用会话连接，并在历史记录仍然匹配时仅发送带有 previous_response_id 的新输入。
使用 params.serviceTier 或 params.service_tier 设置明确的 OpenAI API 服务层级；快速模式（以前称为 Priority processing）使用 service_tier=priority。
在原生公开 OpenAI 和 ChatGPT/Codex Responses 请求中，优先级为 payload／传输层的 service_tier，然后是有效的显式模型参数，最后是快速模式默认值。
/fast 和有效的 params.fastMode／params.fast_mode 值是共享的代理运行时控制项；对于直接嵌入的 openai/* Responses 请求，仅当不存在更高优先级的层级时，它们才会提供 service_tier=priority。
隐藏的 OpenClaw 归因请求头（originator、version、User-Agent）仅适用于发往 api.openai.com 的原生 OpenAI 流量，不适用于通用的 OpenAI 兼容代理
原生 OpenAI 路由还会保留 Responses store、提示缓存提示和 OpenAI reasoning-compat 负载整形；代理路由不会
openai/gpt-5.3-codex-spark 仅可通过 ChatGPT/Codex OAuth 使用；直接 OpenAI API-key 和 Azure API-key 路由会拒绝它

{
  agents: { defaults: { model: { primary: "openai/gpt-5.6-sol" } } },
}

如果 API 组织未公开 GPT-5.6，请显式设置为 openai/gpt-5.5。正常的 onboarding 和重新认证会保留已有的显式主模型；models auth login --set-default 和 models set 是有意进行替换的路径。

Anthropic

提供商：anthropic
认证：ANTHROPIC_API_KEY
可选轮换：ANTHROPIC_API_KEYS、ANTHROPIC_API_KEY_1、ANTHROPIC_API_KEY_2，以及 OPENCLAW_LIVE_ANTHROPIC_KEY（单一覆盖）
示例模型：anthropic/claude-opus-5
CLI：openclaw onboard --auth-choice apiKey
直接的公开 Anthropic 请求支持共享的 /fast 开关和 params.fastMode，包括发送到 api.anthropic.com 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic 的 service_tier（auto 与 standard_only）
首选的 Claude CLI 配置会保持模型引用规范化，并单独选择 CLI 后端：anthropic/claude-opus-5，并设置模型范围的 agentRuntime.id: "claude-cli"。旧版 claude-cli/claude-opus-4-7 引用仍可用于兼容性。

Claude CLI 复用（claude -p）是 OpenClaw 认可的集成路径。仍然支持 Anthropic 的 setup-token 认证，但在可用时 OpenClaw 更倾向于使用 Claude CLI 复用。

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-5" } } },
}

OpenAI ChatGPT/Codex OAuth

提供商：openai
认证：OAuth（ChatGPT）
全新的原生 Codex app-server harness ref：openai/gpt-5.6-sol
原生 Codex app-server harness 文档：Codex harness
旧版模型引用：codex/gpt-*、openai-codex/gpt-*
插件边界：openai/* 会加载 OpenAI 插件；是否选择原生 Codex app-server 插件，则由显式运行时策略或提供商所属的有效路由决定。
CLI：openclaw onboard --auth-choice openai 或 openclaw models auth login --provider openai
OpenClaw 内置的 ChatGPT Responses 传输方式默认为 auto（优先使用 WebSocket，失败后回退到 SSE）。
agents.defaults.models["openai/<model>"].params.transport 和 params.serviceTier 是由内置提供商编写的请求设置。它们会将隐式运行时选择保留在 OpenClaw 中；原生 Codex 负责其 app-server 的传输方式和服务层级。
有效的模型级 params.fastMode / params.fast_mode 值以及有效的截断键，是可移植的、类型化的代理运行时控制项。它们不计入由用户编写的提供商请求参数，也不会选择运行时。当配方依赖某个运行时时，请固定 agentRuntime.id: "openclaw" 或 agentRuntime.id: "codex"。
隐藏的 OpenClaw 归因请求头（originator、version、User-Agent）仅会附加到发往 chatgpt.com/backend-api 的原生 Codex 流量上，不会附加到通用的 OpenAI 兼容代理请求上。
共享的 /fast 开关、配置的默认值以及有效的模型级 Fast 参数，都会通过统一的运行时控制策略进行解析。优先级请参阅思考级别。
OpenAI API Fast 模式按高级价格计费，并且因模型而异。GPT-5.6 Sol 目前按标准令牌价格的 2 倍计费，长上下文倍率还会叠加。ChatGPT/Codex 积分的 Fast 模式是独立的：GPT-5.6 和 GPT-5.5 目前消耗标准积分的 2.5 倍，而使用 API 密钥运行 Codex 则按 API 令牌价格计费。请参阅 Fast 模式、API 定价和 Codex 速度。
原生 Codex 目录可根据账户访问权限公开精确的 openai/gpt-5.6-sol、openai/gpt-5.6-terra 和 openai/gpt-5.6-luna 引用。它不会在客户端应用直接 API 的裸 gpt-5.6 别名。
openai/gpt-5.5 使用 Codex 目录中的原生 contextWindow = 400000，以及默认运行时 contextTokens = 272000；可通过 models.providers.openai.models[].contextTokens 覆盖运行时上限。
使用 openai 认证登录，并使用 openai/gpt-5.6-sol 设置全新的订阅支持配置。如果该 Codex 工作区未提供 GPT-5.6，请显式选择 openai/gpt-5.5。
使用提供商/模型的 agentRuntime.id: "openclaw"，可将其他方面符合条件的路由保留在内置运行时中。当运行时未设置或为 auto 时，只有在没有编写提供商请求覆盖项的情况下，精确的官方 HTTPS Responses/ChatGPT 兼容路由才可能隐式选择 Codex。
旧版 Codex GPT 引用属于旧状态，而不是正在使用的提供商路由。新代理配置请使用规范的 openai/* 引用，并运行 openclaw doctor --fix 迁移 codex/* 和 openai-codex/* 引用，同时通过模型级 agentRuntime.id: "codex" 保留其原生 Codex 语义。现有的显式规范 openai/gpt-5.5 选择不会被升级。

{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-sol" },
    },
  },
}

{
  models: {
    providers: {
      openai: {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}

其他订阅式托管选项

MiniMax

MiniMax 编程计划 OAuth 或 API 密钥访问。

Qwen Cloud

Qwen Cloud 提供商界面，以及阿里巴巴 DashScope 和编程计划端点映射。

Z.AI（GLM）

Z.AI 编程计划或通用 API 端点。

OpenCode

认证：OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）
Zen 运行时提供商：opencode
Go 运行时提供商：opencode-go
示例模型：opencode/claude-opus-4-6、opencode-go/kimi-k2.6
CLI：openclaw onboard --auth-choice opencode-zen 或 openclaw onboard --auth-choice opencode-go

{
  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
}

Google Gemini（API 密钥）

提供方：google
认证：GEMINI_API_KEY
可选轮换：GEMINI_API_KEYS、GEMINI_API_KEY_1、GEMINI_API_KEY_2、GOOGLE_API_KEY 回退，以及 OPENCLAW_LIVE_GEMINI_KEY（单一覆盖）
示例模型：google/gemini-3.1-pro-preview、google/gemini-3.5-flash
兼容性：使用 google/gemini-3.1-flash-preview 的旧版 OpenClaw 配置会被规范化为 google/gemini-3-flash-preview
别名：google/gemini-3.1-pro 可被接受，并规范化为 Google 的实时 Gemini API ID：google/gemini-3.1-pro-preview
CLI：openclaw onboard --auth-choice gemini-api-key
思考：/think adaptive 使用 Google 动态思考。Gemini 3/3.1 不使用固定的 thinkingLevel；Gemini 2.5 会发送 thinkingBudget: -1
直接运行 Gemini 还支持 agents.defaults.models["google/<model>"].params.cachedContent（或旧版 cached_content），以传递提供方原生的 cachedContents/... 句柄；Gemini 的缓存命中会作为 OpenClaw 的 cacheRead 显示

Google Vertex 和 Gemini CLI 运行时

google-vertex：通过 gcloud 应用程序默认凭据管理 Google Cloud 访问。
google-gemini-cli：用于显式配置的规范 google/* 模型的可选本地运行时。

OpenClaw 不会创建 Gemini CLI OAuth 或 Antigravity OAuth 配置文件。通过 AI Studio API 密钥或 Vertex AI 连接 Google。如果你明确选择 Gemini CLI 运行时，它可以使用选定的 Google API 密钥配置。现有的有效 Gemini CLI OAuth 配置文件仍与该运行时兼容，但它们不是设置或恢复路径。 Gemini CLI 默认使用 stream-json。OpenClaw 会读取 assistant 流消息，并将 stats.cached 规范化为 cacheRead；旧的 --output-format json 覆盖仍会从 response 读取回复文本。

Z.AI（GLM）

提供商：zai
认证：ZAI_API_KEY
示例模型：zai/glm-5.2
CLI：openclaw onboard --auth-choice zai-api-key
- 模型引用使用规范的 zai/* 提供商 ID。
- zai-api-key 会自动检测匹配的 Z.AI 端点；zai-coding-global、zai-coding-cn、zai-global 和 zai-cn 会强制使用特定表面。

Vercel AI 网关

提供商：vercel-ai-gateway
认证：AI_GATEWAY_API_KEY
示例模型：vercel-ai-gateway/anthropic/claude-opus-4.6、vercel-ai-gateway/moonshotai/kimi-k2.6
CLI：openclaw onboard --auth-choice ai-gateway-api-key

其他捆绑提供商插件

提供商	Id	认证环境变量	示例模型
Arcee	`arcee`	`ARCEEAI_API_KEY` 或 `OPENROUTER_API_KEY`	`arcee/trinity-large-thinking`
BytePlus	`byteplus` / `byteplus-plan`	`BYTEPLUS_API_KEY`	`byteplus-plan/ark-code-latest`
Cerebras	`cerebras`	`CEREBRAS_API_KEY`	`cerebras/zai-glm-4.7`
Chutes	`chutes`	`CHUTES_API_KEY` 或 `CHUTES_OAUTH_TOKEN`	`chutes/zai-org/GLM-5-TEE`
ClawRouter	`clawrouter`	`CLAWROUTER_API_KEY`	`clawrouter/anthropic/claude-sonnet-4-6`
Cohere	`cohere`	`COHERE_API_KEY`	`cohere/command-a-plus-05-2026`
DeepInfra	`deepinfra`	`DEEPINFRA_API_KEY`	`deepinfra/deepseek-ai/DeepSeek-V4-Flash`
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY`	`deepseek/deepseek-v4-flash`
Featherless AI	`featherless`	`FEATHERLESS_API_KEY`	`featherless/Qwen/Qwen3-32B`
GitHub Copilot	`github-copilot`	`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`	-
GMI Cloud	`gmi`	`GMI_API_KEY`	`gmi/google/gemini-3.1-flash-lite`
Groq	`groq`	`GROQ_API_KEY`	`groq/llama-3.3-70b-versatile`
Hugging Face Inference	`huggingface`	`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`	`huggingface/deepseek-ai/DeepSeek-R1`
MiniMax	`minimax` / `minimax-portal`	`MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN`	`minimax/MiniMax-M3`
Mistral	`mistral`	`MISTRAL_API_KEY`	`mistral/mistral-large-latest`
Moonshot	`moonshot`	`MOONSHOT_API_KEY`	`moonshot/kimi-k2.6`
NVIDIA	`nvidia`	`NVIDIA_API_KEY`	`nvidia/nvidia/nemotron-3-ultra-550b-a55b`
NovitaAI	`novita`	`NOVITA_API_KEY`	`novita/deepseek/deepseek-v3-0324`
Ollama Cloud	`ollama-cloud`	`OLLAMA_API_KEY`	`ollama-cloud/kimi-k2.6`
OpenRouter	`openrouter`	OpenRouter OAuth 或 `OPENROUTER_API_KEY`	`openrouter/auto`
Qianfan	`qianfan`	`QIANFAN_API_KEY`	`qianfan/deepseek-v3.2`
Tencent TokenHub	`tencent-tokenhub`	`TOKENHUB_API_KEY`	`tencent-tokenhub/hy3-preview`
Together	`together`	`TOGETHER_API_KEY`	`together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
Venice	`venice`	`VENICE_API_KEY`	-
Vercel AI Gateway	`vercel-ai-gateway`	`AI_GATEWAY_API_KEY`	`vercel-ai-gateway/anthropic/claude-opus-4.6`
Volcano Engine (Doubao)	`volcengine` / `volcengine-plan`	`VOLCANO_ENGINE_API_KEY`	`volcengine-plan/ark-code-latest`
xAI	`xai`	SuperGrok/X Premium OAuth 或 `XAI_API_KEY`	OAuth：`xai/auto`；API 密钥：`xai/grok-4.3`
Xiaomi	`xiaomi` / `xiaomi-token-plan`	`XIAOMI_API_KEY` / `XIAOMI_TOKEN_PLAN_API_KEY`	`xiaomi/mimo-v2.5` / `xiaomi-token-plan/mimo-v2.5-pro`

值得注意的特殊行为

OpenRouter

仅在经过验证的 openrouter.ai 路由上应用其应用归因请求头和 Anthropic cache_control 标记。DeepSeek、Moonshot 和 ZAI 引用可用于 OpenRouter 托管的提示缓存 TTL，但不会接收 Anthropic 缓存标记。作为类代理的 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的形状处理（serviceTier、Responses store、提示缓存提示、OpenAI reasoning-compat）。基于 Gemini 的引用只保留代理-Gemini 思维签名清理。

Kilo Gateway

基于 Gemini 的引用遵循相同的代理-Gemini 清理路径；kilocode/kilo-auto/balanced 和其他不支持代理推理的引用会跳过代理推理注入。

MiniMax

API 密钥入门会写入明确的 M3 和 M2.7 聊天模型定义；图像理解仍保留在插件拥有的 MiniMax-VL-01 媒体提供商上。

NVIDIA

模型 id 使用 nvidia/<vendor>/<model> 命名空间（例如 nvidia/nvidia/nemotron-...）；选择器保留字面上的 <provider>/<model-id> 组合，而发送到 API 的规范键保持单前缀。

xAI

使用 xAI Responses 路径。推荐路径是 SuperGrok/X Premium OAuth；全新设置会选择 xai/auto，该模型会遵循 xAI 的经认证默认模型，无需更新 OpenClaw。现有的具体模型 id 会保持固定。API 密钥仍可通过 XAI_API_KEY 或插件配置使用，并将 grok-4.3 作为区域安全的设置默认值。Grok web_search 会在回退到 API 密钥之前重用相同的认证配置文件。较旧的 /fast 和 params.fastMode: true 配置仍会通过 xAI 的 Grok 4.3 兼容性重定向进行解析，但新配置应直接选择当前模型。tool_stream 默认启用；可通过 agents.defaults.models["xai/<model>"].params.tool_stream=false 禁用。

通过 `models.providers` 提供（自定义/基础 URL）

使用 models.providers（或 models.json）来添加自定义提供商或 OpenAI/Anthropic 兼容代理。下面许多内置的提供商插件已经发布了默认目录。只有在你想覆盖默认基础 URL、请求头或模型列表时，才使用显式的 models.providers.<id> 条目。捆绑和目录中已知的路由会从其所属的提供商插件获取其 compat 能力。配置中的 compat 块适用于自定义提供商/模型，或你已验证其端点契约的不同 api/baseUrl 路由；请参见自定义提供商能力指南。Doctor 会移除那些仅仅重复目录内容的旧值，并保留有差异的值以供操作员审查。 Gateway 的模型能力检查也会读取显式的 models.providers.<id>.models[] 元数据。如果自定义或代理模型接受图像，请在该模型上设置 input: ["text", "image"]，这样 WebChat 和 node-origin 附件路径就会将图像作为原生模型输入传递，而不是仅文本的媒体引用。 agents.defaults.models["provider/model"] 用于控制 agents 的别名和每个模型的元数据。它既不会限制覆盖，也不会单独注册新的运行时模型。对于自定义提供商模型，还要添加 models.providers.<provider>.models[]，并至少包含匹配的 id；当你想要覆盖限制时，请另外使用 agents.defaults.modelPolicy.allow。

Moonshot AI（Kimi）

在引导流程之前安装 @openclaw/moonshot-provider。只有在你需要覆盖基础 URL 或模型元数据时，才添加显式的 models.providers.moonshot 条目：

提供方：moonshot
认证：MOONSHOT_API_KEY
示例模型：moonshot/kimi-k3
CLI：openclaw onboard --auth-choice moonshot-api-key 或 openclaw onboard --auth-choice moonshot-api-key-cn

Kimi 模型 ID：

moonshot/kimi-k2.6
moonshot/kimi-k3
moonshot/kimi-k2.7-code
moonshot/kimi-k2.7-code-highspeed
moonshot/kimi-k2.5

{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.6" } },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.6", name: "Kimi K2.6" }],
      },
    },
  },
}

参见 Moonshot AI（Kimi + Kimi Coding）获取完整设置指南。

Kimi 编程

Kimi 编程使用 Moonshot AI 的 Anthropic 兼容端点：

提供商：kimi
认证：KIMI_API_KEY
Kimi K3：kimi/k3（最高 1M，按层级开放）或 kimi/k3-256k（256K，较低配额使用）
Kimi Code：kimi/kimi-for-coding
Kimi Code HighSpeed：kimi/kimi-for-coding-highspeed

{
  env: { vars: { KIMI_API_KEY: "sk-..." } },
  agents: {
    defaults: { model: { primary: "kimi/kimi-for-coding" } },
  },
}

Kimi K3 使用自适应思考。--thinking minimal|low 选择低强度， --thinking medium|high|adaptive 选择高强度，而 --thinking xhigh|max 选择最高强度。目录定价为输入

3/MTok、输出

15/MTok，以及缓存读取 $0.30/MTok。旧版 kimi/kimi-code 和 kimi/k2p5 仍然被接受为兼容模型 id，并会规范化为 Kimi 稳定 API 的模型 id；此前发布的 kimi/k3[1m] 引用会规范化为 kimi/k3，以兼容现有配置。

火山引擎（豆包）

火山引擎提供对中国境内的豆包及其他模型的访问。

提供商：volcengine（编码：volcengine-plan）
认证：VOLCANO_ENGINE_API_KEY
示例模型：volcengine-plan/ark-code-latest
命令行界面：openclaw onboard --auth-choice volcengine-api-key

{
  agents: {
    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },
  },
}

注册时默认使用编码界面，但通用的 volcengine/* 目录会同时注册。在引导配置模型选择器中，火山引擎认证选项会优先显示 volcengine/* 和 volcengine-plan/* 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商分组选择器。

标准模型
编程模型（volcengine-plan）

volcengine/doubao-seed-1-8-251228（豆包 Seed 1.8）
volcengine/doubao-seed-code-preview-251028
volcengine/kimi-k2-5-260127（Kimi K2.5）
volcengine/glm-4-7-251222（GLM 4.7）
volcengine/deepseek-v3-2-251201（DeepSeek V3.2）

volcengine-plan/ark-code-latest
volcengine-plan/doubao-seed-code

BytePlus（国际版）

BytePlus ARK 为国际用户提供与火山引擎相同的模型访问能力。

插件：@openclaw/byteplus-provider
提供商：byteplus（编程：byteplus-plan）
认证：BYTEPLUS_API_KEY
示例模型：byteplus-plan/ark-code-latest
命令行：openclaw onboard --auth-choice byteplus-api-key

安装官方插件并重启网关：

openclaw plugins install @openclaw/byteplus-provider
openclaw gateway restart

{
  agents: {
    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },
  },
}

注册时默认使用编程界面，但通用的 byteplus/* 目录会同时注册。在引导配置模型选择器中，BytePlus 认证选项会优先显示 byteplus/* 和 byteplus-plan/* 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商分组选择器。

标准模型
编程模型（byteplus-plan）

byteplus/seed-1-8-251228（Seed 1.8）
byteplus/kimi-k2-5-260127（Kimi K2.5）
byteplus/glm-4-7-251222（GLM 4.7）

byteplus-plan/ark-code-latest
byteplus-plan/kimi-k2.5
byteplus-plan/glm-4.7

Synthetic

Synthetic 通过 synthetic 提供 Anthropic 兼容模型：

提供商：synthetic
认证：SYNTHETIC_API_KEY
示例模型：synthetic/hf:MiniMaxAI/MiniMax-M3
CLI：openclaw onboard --auth-choice synthetic-api-key

{
  agents: {
    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M3" } },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [{ id: "hf:MiniMaxAI/MiniMax-M3", name: "MiniMax M3" }],
      },
    },
  },
}

MiniMax

MiniMax 通过 models.providers 配置，因为它使用自定义端点：

MiniMax OAuth（全球）：--auth-choice minimax-global-oauth
MiniMax OAuth（中国）：--auth-choice minimax-cn-oauth
MiniMax API 密钥（全球）：--auth-choice minimax-global-api
MiniMax API 密钥（中国）：--auth-choice minimax-cn-api
认证：minimax 使用 MINIMAX_API_KEY；minimax-portal 使用 MINIMAX_OAUTH_TOKEN 或 MINIMAX_API_KEY

请参见 /providers/minimax 获取设置详情、模型选项和配置片段。

在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认会为 M2.x 系列关闭思考，除非你显式设置；MiniMax-M3（以及 M3.x）默认保持提供商省略／自适应思考路径。/fast on 会将 MiniMax-M2.7 重写为 MiniMax-M2.7-highspeed。

插件拥有的能力划分：

文本／聊天默认使用 minimax/MiniMax-M3
图像生成使用 minimax/image-01 或 minimax-portal/image-01
图像理解在两种 MiniMax 认证路径上都由插件拥有的 MiniMax-VL-01 提供
网页搜索保持在提供商 ID minimax

LM Studio

LM Studio 作为一个内置提供商插件发布，使用原生 API：

提供商：lmstudio
认证：LM_API_TOKEN
默认推理基础 URL：http://localhost:1234/v1

然后设置一个模型（替换为 http://localhost:1234/api/v1/models 返回的某个 ID）：

{
  agents: {
    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },
  },
}

OpenClaw 使用 LM Studio 的原生 /api/v1/models 和 /api/v1/models/load 进行发现 + 自动加载，并默认使用 /v1/chat/completions 进行推理。如果你希望由 LM Studio 自己管理模型生命周期（JIT 加载、TTL 和自动逐出），请将 models.providers.lmstudio.params.preload: false。有关设置和故障排除，请参见 /providers/lmstudio。

Ollama

Ollama 作为一个内置提供商插件发布，并使用 Ollama 的原生 API：

提供商：ollama
认证：不需要（本地服务器）
示例模型：ollama/llama3.3
安装：https://ollama.com/download

# 安装 Ollama，然后拉取一个模型：
ollama pull llama3.3

{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}

当你通过 OLLAMA_API_KEY 选择启用时，Ollama 会在本地 http://127.0.0.1:11434 被检测到，内置提供商插件会将 Ollama 直接加入 openclaw onboard 和模型选择器。请参见 /providers/ollama 获取 onboarding、云端／本地模式和自定义配置说明。

vLLM

vLLM 作为一个内置提供商插件发布，用于本地／自托管的 OpenAI 兼容服务器：

提供商：vllm
认证：可选（取决于你的服务器）
默认基础 URL：http://127.0.0.1:8000/v1

要在本地启用自动发现（如果你的服务器不强制认证，任何值都可以）：

export VLLM_API_KEY="vllm-local"

然后设置一个模型（替换为 /v1/models 返回的某个 ID）：

{
  agents: {
    defaults: { model: { primary: "vllm/your-model-id" } },
  },
}

详情请参见 /providers/vllm。

SGLang

SGLang 作为一个内置提供商插件发布，用于快速的自托管 OpenAI 兼容服务器：

提供商：sglang
认证：可选（取决于你的服务器）
默认基础 URL：http://127.0.0.1:30000/v1

要在本地启用自动发现（如果你的服务器不强制认证，任何值都可以）：

export SGLANG_API_KEY="sglang-local"

然后设置一个模型（替换为 /v1/models 返回的某个 ID）：

{
  agents: {
    defaults: { model: { primary: "sglang/your-model-id" } },
  },
}

详情请参见 /providers/sglang。

本地代理（LM Studio、vLLM、LiteLLM 等）

示例（OpenAI 兼容）：

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: { "lmstudio/my-local-model": { alias: "本地" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "${LM_API_TOKEN}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "本地模型",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

默认可选字段

对于自定义提供商，reasoning、input、cost、contextWindow 和 maxTokens 都是可选的。未指定时，OpenClaw 默认：

reasoning: false
input: ["text"]
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
contextWindow: 200000
maxTokens: 8192

建议：设置与你的代理/模型限制相匹配的显式值。

代理路由整形规则

对于非原生端点上的 api: "openai-completions"（任何主机不是 api.openai.com 的非空 baseUrl），OpenClaw 会强制 compat.supportsDeveloperRole: false，以避免提供商因不支持的 developer 角色而返回 400 错误。
代理风格的 OpenAI 兼容路由也会跳过原生 OpenAI 专用的请求整形：不发送 service_tier、不发送 Responses 的 store、不发送 Completions 的 store、不发送 prompt-cache 提示、不进行 OpenAI reasoning 兼容载荷整形，并且不会添加隐藏的 OpenClaw 归因请求头。
对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 agents.defaults.models["provider/model"].params.extra_body（或 extraBody），将额外的 JSON 合并到出站请求体中。
对于 vLLM 的 chat-template 控制，请设置 agents.defaults.models["provider/model"].params.chat_template_kwargs。当会话的 thinking 级别关闭时，随附的 vLLM 插件会自动为 vllm/nemotron-3-* 发送 enable_thinking: false 和 force_nonempty_content: true。
对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 models.providers.<id>.timeoutSeconds。这会延长提供商模型的 HTTP 请求处理时间，包括连接、请求头、流式请求体以及总的受保护 fetch 中止时间，但不会增加整个 agent 运行时的超时时间。如果 agents.defaults.timeoutSeconds 或某次运行的特定超时更低，也需要同时提高那个上限；提供商超时不能延长整个运行时长。
模型提供商的 HTTP 调用仅允许 Surge、Clash 和 sing-box 的 fake-IP DNS 应答（198.18.0.0/15 和 fc00::/7）用于已配置的提供商 baseUrl 主机名。自定义/本地提供商端点也会对该精确配置的 scheme://host:port 来源信任受保护的模型请求，包括回环、局域网和 tailnet 主机。这不是一个新的配置选项；你配置的 baseUrl 只会将请求策略扩展到该来源。fake-IP 主机名允许与精确来源信任是相互独立的机制。其他私有地址、回环、链路本地、元数据目标以及不同端口仍然需要显式启用 models.providers.<id>.request.allowPrivateNetwork: true。设置 models.providers.<id>.request.allowPrivateNetwork: false 可退出精确来源信任。
如果 baseUrl 为空/未指定，OpenClaw 会保持默认的 OpenAI 行为（即解析到 api.openai.com）。
出于安全考虑，即使显式设置了 compat.supportsDeveloperRole: true，在非原生 openai-completions 端点上也仍会被覆盖。
对于非直连端点上的 api: "anthropic-messages"（任何非标准的 anthropic 提供商，或者主机不是公开 api.anthropic.com 端点的自定义 models.providers.anthropic.baseUrl），OpenClaw 会抑制隐式的 Anthropic beta 请求头，例如 claude-code-20250219、interleaved-thinking-2025-05-14 和 OAuth 标记，从而避免自定义的 Anthropic 兼容代理拒绝不受支持的 beta 标志。如果你的代理需要特定的 beta 功能，请显式设置 models.providers.<id>.headers["anthropic-beta"]。

CLI 示例

openclaw onboard --auth-choice opencode-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list

另请参阅：配置以查看完整的配置示例。

概览

概念与配置

提供商

快速规则

在 Control UI 中配置提供方

提供商专属行为

API 密钥轮换

官方提供商插件

OpenAI

Anthropic

OpenAI ChatGPT/Codex OAuth

其他订阅式托管选项

MiniMax

Qwen Cloud

Z.AI（GLM）

OpenCode

Google Gemini（API 密钥）

Google Vertex 和 Gemini CLI 运行时

Z.AI（GLM）

Vercel AI 网关

其他捆绑提供商插件

值得注意的特殊行为

通过 `models.providers` 提供（自定义/基础 URL）

Moonshot AI（Kimi）

Kimi 编程

火山引擎（豆包）

BytePlus（国际版）

Synthetic

MiniMax

LM Studio

Ollama

vLLM

SGLang

本地代理（LM Studio、vLLM、LiteLLM 等）

CLI 示例

相关内容

​快速规则

​在 Control UI 中配置提供方

​提供商专属行为

​API 密钥轮换

​官方提供商插件

​OpenAI

​Anthropic

​OpenAI ChatGPT/Codex OAuth

​其他订阅式托管选项

MiniMax

Qwen Cloud

Z.AI（GLM）

​OpenCode

​Google Gemini（API 密钥）

​Google Vertex 和 Gemini CLI 运行时

​Z.AI（GLM）

​Vercel AI 网关

​其他捆绑提供商插件

​值得注意的特殊行为

​通过 models.providers 提供（自定义/基础 URL）

​Moonshot AI（Kimi）

​Kimi 编程

​火山引擎（豆包）

​BytePlus（国际版）

​Synthetic

​MiniMax

​LM Studio

​Ollama

​vLLM

​SGLang

​本地代理（LM Studio、vLLM、LiteLLM 等）

​CLI 示例

​相关内容

快速规则

在 Control UI 中配置提供方

提供商专属行为

API 密钥轮换

官方提供商插件

OpenAI

Anthropic

OpenAI ChatGPT/Codex OAuth

其他订阅式托管选项

OpenCode

Google Gemini（API 密钥）

Google Vertex 和 Gemini CLI 运行时

Z.AI（GLM）

Vercel AI 网关

其他捆绑提供商插件

值得注意的特殊行为

通过 `models.providers` 提供（自定义/基础 URL）

Moonshot AI（Kimi）

Kimi 编程

火山引擎（豆包）

BytePlus（国际版）

Synthetic

MiniMax

LM Studio

Ollama

vLLM

SGLang

本地代理（LM Studio、vLLM、LiteLLM 等）

CLI 示例

相关内容