# 模型提供商 > 模型提供商概览，包含配置示例和 CLI 流程 - 网址：https://funcoding.ai/agents/openclaw/concepts/model-providers/ - 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11 - 官方原文：https://docs.openclaw.ai/zh-CN/concepts/model-providers --- LLM/模型提供商参考（不是 WhatsApp/Telegram 等聊天渠道）。有关模型选择规则，请参阅[模型](https://funcoding.ai/agents/openclaw/concepts/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 `。 - `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 按模型覆盖这些默认值。 - 回退规则、冷却探测和会话覆盖持久化：[模型故障转移](https://funcoding.ai/agents/openclaw/concepts/model-failover/)。
添加提供商身份验证不会更改主模型 添加提供商或对其重新进行身份验证时，`openclaw configure` 会保留现有的 `agents.defaults.model.primary`。除非传递 `--set-default`，否则 `openclaw models auth login` 也会如此处理。提供商插件仍可在其身份验证配置补丁中返回推荐的默认模型，但如果主模型已存在，OpenClaw 会将其视为“使此模型可用”，而不是“替换当前主模型”。 若要有意切换默认模型，请使用 `openclaw models set ` 或 `openclaw models auth login --provider --set-default`。
OpenAI 提供商/运行时拆分 OpenAI 模型引用和智能体运行时彼此独立： - `openai/` 选择规范的 OpenAI 提供商和模型。仅有此前缀绝不会选择 Codex。 - 当未设置提供商/模型运行时策略或将其设为 `auto` 时，只有对于未编写请求覆盖的精确官方 HTTPS Platform Responses 或 ChatGPT Responses 路由，OpenAI 才可能隐式选择 Codex。 - 自行编写的 Completions 适配器、自定义端点以及具有自行编写请求行为的路由仍使用 OpenClaw。官方明文 HTTP 端点会被拒绝。 - 旧版 Codex 模型引用属于旧版配置，Doctor 会将其重写为 `openai/`。 - 提供商/模型 `agentRuntime.id: "openclaw"` 会明确使原本符合条件的路由继续使用 OpenClaw。`agentRuntime.id: "codex"` 要求使用 Codex，并会在有效路由与 Codex 不兼容时以关闭方式失败。 请参阅 [OpenAI 隐式智能体运行时](https://funcoding.ai/agents/openclaw/providers/openai/#implicit-agent-runtime)和 [Codex harness](https://funcoding.ai/agents/openclaw/plugins/codex-harness/)。如果提供商/运行时拆分令人困惑，请先阅读 [Agent Runtimes](https://funcoding.ai/agents/openclaw/concepts/agent-runtimes/)。 插件自动启用遵循相同边界：隐式兼容 Codex 的有效路由可以启用 Codex 插件，而显式的提供商/模型 `agentRuntime.id: "codex"` 或旧版 `codex/` 引用则要求启用该插件。仅有 `openai/*` 前缀并不会如此。 全新的 OpenAI 设置使用特定于路由的 GPT-5.6 引用：API 密钥设置会选择 `openai/gpt-5.6`（在直接 API 上，不带限定词的直接 API ID 会解析为 Sol），而 ChatGPT/Codex OAuth 会为原生 Codex 目录选择精确的 `openai/gpt-5.6-sol`。添加或刷新 OpenAI 身份验证时，会保留现有的显式主模型，包括 `openai/gpt-5.5`。对于无法使用 GPT-5.6 的账户，GPT-5.5 仍可通过任一运行时作为显式恢复选项使用。
CLI 运行时 CLI 运行时使用相同的拆分方式：选择规范模型引用，例如 `anthropic/claude-*` 或 `google/gemini-*`，然后在需要本地 CLI 后端时，将提供商/模型运行时策略设置为 `claude-cli` 或 `google-gemini-cli`。 旧版 `claude-cli/*` 和 `google-gemini-cli/*` 引用会迁移回规范提供商引用，并单独记录运行时。旧版 `codex-cli/*` 引用会迁移到 `openai/*` 并使用 Codex 应用服务器路由；OpenClaw 不再保留内置 Codex CLI 后端。
## 在 Control UI 中配置提供商 在 Control UI 中打开 **Settings → Model Providers**，以添加、替换或移除存储在 `models.providers..apiKey` 中的提供商 API 密钥。该页面会标识每个 API 密钥来自 OpenClaw 配置还是环境变量，而不会显示凭据。由环境提供的密钥仍由 Gateway 网关进程环境管理。 使用 **Test connection** 运行实时提供商探测，并查看延迟或分类后的身份验证、速率限制、计费、超时或响应错误。探测会发出真实的提供商请求，并可能消耗少量 token。也可以从提供商卡片中注销 OAuth 和 token 配置文件。 **Default models** 卡片用于管理已配置模型目录中的主模型、顺序回退模型和实用模型。选择模型，然后将它们一起保存到现有的 `agents.defaults.model` 和 `agents.defaults.utilityModel` 设置中。对于实用模型，**Automatic** 会保持该设置未设置，而 **Disabled** 会存储空字符串以关闭实用模型路由。 ## 插件所有的提供商行为 大多数提供商专属逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、身份验证环境变量映射、传输/配置规范化、工具架构清理、故障转移分类、OAuth 刷新、用量报告、思考/推理配置文件等。 提供商 SDK 钩子和内置插件示例的完整列表，请参阅[提供商插件](https://funcoding.ai/agents/openclaw/plugins/sdk-provider-plugins/)。需要完全自定义请求执行器的提供商属于独立且更深层的扩展接口。
提供商所有的运行器行为位于显式提供商钩子上，例如重放策略、工具架构规范化、流包装以及传输/请求辅助函数。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容，共享运行器逻辑已不再读取它。
## API 密钥轮换
密钥来源和优先级 通过以下方式配置多个密钥： - `OPENCLAW_LIVE__KEY`（单个实时覆盖，优先级最高） - `_API_KEYS`（以逗号或分号分隔的列表） - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_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`；在直接 API 上，不带限定词的 ID 会解析为 Sol。 - 模型示例：`openai/gpt-5.6`、`openai/gpt-5.6-terra`、`openai/gpt-5.6-luna`、`openai/gpt-5.5` - 如果特定安装或 API 密钥表现不同，请使用 `openclaw models list --provider openai` 验证账户/模型可用性。 - CLI：`openclaw onboard --auth-choice openai-api-key` - 默认传输方式为 `auto`；OpenClaw 会将传输方式选择传递给共享模型运行时。 - 通过 `agents.defaults.models["openai/"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） - 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先处理 - `/fast` 和 `params.fastMode` 会将对 `openai/*` 的直接 Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority` - 如果需要显式层级而不是共享的 `/fast` 开关，请使用 `params.serviceTier` - 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理 - 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI 推理兼容负载整形；代理路由不会 - `openai/gpt-5.3-codex-spark` 仅可通过 ChatGPT/Codex OAuth 使用；OpenAI 直接 API 密钥和 Azure API 密钥路由会拒绝它 ```json5 { agents: { defaults: { model: { primary: "openai/gpt-5.6" } } }, } ``` 如果 API 组织未开放 GPT-5.6，请显式设置 `openai/gpt-5.5`。常规新手引导和重新进行身份验证会保留 现有的显式主模型；`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 设置 token 身份验证仍受支持，但在可用时，OpenClaw 更推荐复用 Claude CLI。
```json5 { agents: { defaults: { model: { primary: "anthropic/claude-opus-5" } } }, } ``` ### OpenAI ChatGPT/Codex OAuth - 提供商：`openai` - 身份验证：OAuth（ChatGPT） - 全新 Native Codex app-server harness 引用：`openai/gpt-5.6-sol` - Native Codex app-server harness 文档：[Codex harness](https://funcoding.ai/agents/openclaw/plugins/codex-harness/) - 旧版模型引用：`codex/gpt-*`、`openai-codex/gpt-*` - 插件边界：`openai/*` 加载 OpenAI 插件；由显式运行时策略或提供商拥有的有效路由决定是否选择 Native 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/"].params.transport`、`params.serviceTier` 和 `params.fastMode` 是编写的内嵌请求设置。它们使隐式运行时选择仍由 OpenClaw 负责；Native Codex 负责其 app-server 传输方式和服务层级。 - 隐藏的 OpenClaw 归属标头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的 Native Codex 流量，而不会附加到通用 OpenAI 兼容代理 - 共享的 `/fast` 开关仍可用作运行时控制；它与编写的模型参数不同。 - Native 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"` 保留其 Native Codex 语义。现有显式选择的规范 `openai/gpt-5.5` 不会升级。 ```json5 { plugins: { entries: { codex: { enabled: true } } }, agents: { defaults: { model: { primary: "openai/gpt-5.6-sol" }, }, }, } ``` ```json5 { models: { providers: { openai: { models: [{ id: "gpt-5.5", contextTokens: 160000 }], }, }, }, } ``` ### 其他订阅式托管选项 - [MiniMax](https://funcoding.ai/agents/openclaw/providers/minimax/)：MiniMax Coding Plan OAuth 或 API 密钥访问。 - [Qwen Cloud](https://funcoding.ai/agents/openclaw/providers/qwen/)：Qwen Cloud 提供商界面，以及 Alibaba DashScope 和 Coding Plan 端点映射。 - [Z.AI (GLM)](https://funcoding.ai/agents/openclaw/providers/zai/)：Z.AI Coding Plan 或通用 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` ```json5 { 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/"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` ### Google Vertex 和 Gemini CLI - 提供商：`google-vertex`、`google-gemini-cli` - 身份验证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，使用第三方客户端后其 Google 账户受到限制。如果你选择继续，请查阅 Google 条款并使用非关键账户。
Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 **安装 Gemini CLI** **brew** ```bash brew install gemini-cli ``` **npm** ```bash npm install -g @google/gemini-cli ``` **启用插件** ```bash openclaw plugins enable google ``` **登录** ```bash openclaw models auth login --provider google-gemini-cli --set-default ``` 默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不需要**将客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的身份验证配置文件中。 **设置项目（如有需要）** 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。 Gemini CLI 默认使用 `stream-json`。OpenClaw 读取助手流式 消息，并将 `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 Gateway 网关 - 提供商：`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](https://funcoding.ai/agents/openclaw/providers/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` | `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 推理兼容处理）。由 Gemini 支持的引用仅保留代理 Gemini 的思维签名清理。
Kilo Gateway 由 Gemini 支持的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo-auto/balanced` 和其他不支持代理推理的引用会跳过代理推理注入。
MiniMax API 密钥新手引导会写入明确的 M3 和 M2.7 聊天模型定义；图像理解仍使用由插件拥有的 `MiniMax-VL-01` 媒体提供商。
NVIDIA 模型 ID 使用 `nvidia//` 命名空间（例如 `nvidia/nvidia/nemotron-...`）；选择器会保留字面量 `/` 组合，而发送到 API 的规范键仍仅带一个前缀。
xAI 使用 xAI Responses 路径。推荐路径为 SuperGrok/X Premium OAuth；API 密钥仍可通过 `XAI_API_KEY` 或插件配置使用，并且 Grok `web_search` 会在回退到 API 密钥之前复用同一身份验证配置文件。在可用的情况下，可选择 Grok 4.5 用于聊天、编码和智能体任务；`grok-4.3` 仍是区域安全的内置默认值。较旧的 `/fast` 和 `params.fastMode: true` 配置仍可通过 xAI 的 Grok 4.3 兼容性重定向解析，但新配置应直接选择当前模型。`tool_stream` 默认启用；可通过 `agents.defaults.models["xai/"].params.tool_stream=false` 禁用。
## 通过 `models.providers` 使用提供商（自定义/基础 URL） 使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。 以下许多内置提供商插件已发布默认目录。仅当需要覆盖默认基础 URL、标头或模型列表时，才使用显式的 `models.providers.` 条目。 内置路由和目录中已知的路由从其所属提供商插件获取 `compat` 能力。配置中的 `compat` 块用于自定义提供商/模型，或用于已验证端点契约的其他 `api`/`baseUrl` 路由；请参阅[自定义提供商能力指南](https://funcoding.ai/agents/openclaw/gateway/config-tools/#custom-provider-capability-declarations)。Doctor 会移除仅重复目录内容的旧值，并保留不同的值，以供操作员审核。 Gateway 网关模型能力检查还会读取显式的 `models.providers..models[]` 元数据。如果自定义或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，以便 WebChat 和源自节点的附件路径将图像作为原生模型输入传递，而不是仅传递文本形式的媒体引用。 `agents.defaults.models["provider/model"]` 控制智能体的别名和每模型元数据。它既不限制覆盖，也不会自行注册新的运行时模型。对于自定义提供商模型，还需添加 `models.providers..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-model-refs:start" - `moonshot/kimi-k2.6` - `moonshot/kimi-k3` - `moonshot/kimi-k2.7-code` - `moonshot/kimi-k2.7-code-highspeed` - `moonshot/kimi-k2.5` [//]: # "moonshot-kimi-k2-model-refs:end" ```json5 { 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）](https://funcoding.ai/agents/openclaw/providers/moonshot/)。 ### Kimi Coding Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： - 提供商：`kimi` - 身份验证：`KIMI_API_KEY` - Kimi K3：`kimi/k3`（256K）或 `kimi/k3[1m]`（1M 方案） - Kimi Code：`kimi/kimi-for-coding` - Kimi Code HighSpeed：`kimi/kimi-for-coding-highspeed` ```json5 { env: { KIMI_API_KEY: "sk-..." }, agents: { defaults: { model: { primary: "kimi/kimi-for-coding" } }, }, } ``` 旧版 `kimi/kimi-code` 和 `kimi/k2p5` 仍作为兼容模型 ID 被接受，并会规范化为 Kimi 的稳定 API 模型 ID。 ### Volcano Engine（Doubao） Volcano Engine（火山引擎）提供对中国境内 Doubao 及其他模型的访问。 - 提供商：`volcengine`（编码：`volcengine-plan`） - 身份验证：`VOLCANO_ENGINE_API_KEY` - 示例模型：`volcengine-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice volcengine-api-key` ```json5 { agents: { defaults: { model: { primary: "volcengine-plan/ark-code-latest" } }, }, } ``` 新手引导默认使用编码界面，但同时也会注册通用 `volcengine/*` 目录。 在新手引导/配置模型选择器中，Volcengine 身份验证选项会优先使用 `volcengine/*` 和 `volcengine-plan/*` 两行。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示空的提供商范围选择器。 **标准模型** - `volcengine/doubao-seed-1-8-251228`（Doubao 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)** - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` ### BytePlus（国际版） BytePlus ARK 为国际用户提供与火山引擎相同的模型。 - 提供商：`byteplus`（编码：`byteplus-plan`） - 身份验证：`BYTEPLUS_API_KEY` - 示例模型：`byteplus-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice byteplus-api-key` ```json5 { agents: { defaults: { model: { primary: "byteplus-plan/ark-code-latest" } }, }, } ``` 新手引导默认使用编码接口，但同时也会注册通用的 `byteplus/*` 目录。 在新手引导/配置的模型选择器中，BytePlus 身份验证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两行。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示空的提供商范围选择器。 **标准模型** - `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)** - `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` ```json5 { 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](https://funcoding.ai/agents/openclaw/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` 提供 - Web 搜索仍使用提供商 ID `minimax` ### LM Studio LM Studio 作为内置提供商插件发布，使用原生 API： - 提供商：`lmstudio` - 身份验证：`LM_API_TOKEN` - 默认推理基础 URL：`http://localhost:1234/v1` 然后设置模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）： ```json5 { 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](https://funcoding.ai/agents/openclaw/providers/lmstudio/)。 ### Ollama Ollama 作为内置提供商插件发布，并使用 Ollama 的原生 API： - 提供商：`ollama` - 身份验证：无需（本地服务器） - 示例模型：`ollama/llama3.3` - 安装：[https://ollama.com/download](https://ollama.com/download) ```bash # 安装 Ollama，然后拉取模型： ollama pull llama3.3 ``` ```json5 { agents: { defaults: { model: { primary: "ollama/llama3.3" } }, }, } ``` 当你通过 `OLLAMA_API_KEY` 选择启用时，会在本地的 `http://127.0.0.1:11434` 检测 Ollama，内置提供商插件还会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式和自定义配置，请参阅 [/providers/ollama](https://funcoding.ai/agents/openclaw/providers/ollama/)。 ### vLLM vLLM 作为内置提供商插件发布，适用于本地/自行托管的 OpenAI 兼容服务器： - 提供商：`vllm` - 身份验证：可选（取决于你的服务器） - 默认基础 URL：`http://127.0.0.1:8000/v1` 要选择启用本地自动发现（如果服务器不强制身份验证，任何值均可）： ```bash export VLLM_API_KEY="vllm-local" ``` 然后设置模型（替换为 `/v1/models` 返回的某个 ID）： ```json5 { agents: { defaults: { model: { primary: "vllm/your-model-id" } }, }, } ``` 有关详情，请参阅 [/providers/vllm](https://funcoding.ai/agents/openclaw/providers/vllm/)。 ### SGLang SGLang 作为内置提供商插件发布，适用于快速、自行托管的 OpenAI 兼容服务器： - 提供商：`sglang` - 身份验证：可选（取决于你的服务器） - 默认基础 URL：`http://127.0.0.1:30000/v1` 要选择启用本地自动发现（如果服务器不强制身份验证，任何值均可）： ```bash export SGLANG_API_KEY="sglang-local" ``` 然后设置模型（替换为 `/v1/models` 返回的某个 ID）： ```json5 { agents: { defaults: { model: { primary: "sglang/your-model-id" } }, }, } ``` 有关详情，请参阅 [/providers/sglang](https://funcoding.ai/agents/openclaw/providers/sglang/)。 ### 本地代理（LM Studio、vLLM、LiteLLM 等） 示例（兼容 OpenAI）： ```json5 { agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, models: { "lmstudio/my-local-model": { alias: "Local" } }, }, }, models: { providers: { lmstudio: { baseUrl: "http://localhost:1234/v1", apiKey: "${LM_API_TOKEN}", api: "openai-completions", timeoutSeconds: 300, models: [ { id: "my-local-model", name: "Local Model", 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`、不包含提示缓存提示、不进行 OpenAI 推理兼容负载调整，也不包含隐藏的 OpenClaw 归属标头。 - 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），将额外 JSON 合并到出站请求正文中。 - 对于 vLLM 聊天模板控件，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话思考级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。 - 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers..timeoutSeconds`。这会延长提供商模型 HTTP 请求的处理时间，包括连接、标头、正文流式传输和受保护提取的总中止时间，但不会增加整个智能体运行时超时。如果 `agents.defaults.timeoutSeconds` 或特定运行的超时更短，也需要提高该上限；提供商超时无法延长整个运行。 - 模型提供商 HTTP 调用仅针对所配置提供商的 `baseUrl` 主机名，允许 `198.18.0.0/15` 和 `fc00::/7` 中由 Surge、Clash 和 sing-box 返回的 fake-IP DNS 答案。自定义/本地提供商端点还会信任所配置的确切 `scheme://host:port` 来源，以执行受保护的模型请求，包括 local loopback、LAN 和 tailnet 主机。这不是新的配置选项；你配置的 `baseUrl` 仅为该来源扩展请求策略。fake-IP 主机名许可和确切来源信任是相互独立的机制。其他私有、local loopback、链路本地、元数据目标以及不同端口仍需明确选择启用 `models.providers..request.allowPrivateNetwork: true`。设置 `models.providers..request.allowPrivateNetwork: false` 可选择退出确切来源信任。 - 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（解析为 `api.openai.com`）。 - 为确保安全，在非原生 `openai-completions` 端点上，明确设置的 `compat.supportsDeveloperRole: true` 仍会被覆盖。 - 对于非直连端点上的 `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..headers["anthropic-beta"]`。
## CLI 示例 ```bash openclaw onboard --auth-choice opencode-zen openclaw models set opencode/claude-opus-4-6 openclaw models list ``` 另请参阅：[配置](https://funcoding.ai/agents/openclaw/gateway/configuration/)，了解完整的配置示例。 ## 相关内容 - [配置参考](https://funcoding.ai/agents/openclaw/gateway/config-agents/#agent-defaults) - 模型配置键 - [模型故障转移](https://funcoding.ai/agents/openclaw/concepts/model-failover/) - 回退链和重试行为 - [Models](https://funcoding.ai/agents/openclaw/concepts/models/) - 模型配置和别名 - [提供商](https://funcoding.ai/agents/openclaw/providers/) - 各提供商的设置指南