本页是 OpenClaw 模型 provider 的完整参考：内置 pi-ai 目录（OpenAI、Anthropic、Gemini、Codex、OpenCode 等）和自定义 provider（Moonshot/Kimi、火山引擎、BytePlus、Ollama、vLLM、SGLang、LM Studio 等）的配置示例。涵盖模型 ID 格式、API Key 环境变量、key 轮换规则、CLI 命令（openclaw onboard、openclaw models set、openclaw models list）和代理路由注意事项。按 provider 分类给出 JSON5 配置片段，方便直接复用。

OpenClaw 模型 Provider 配置完整指南

本页覆盖 LLM/模型 provider（不包括 WhatsApp、Telegram 等聊天渠道）。模型选择规则参考模型概念页。

快速规则

模型引用格式和 CLI 辅助命令

- 模型引用格式：`provider/model`（例如 `opencode/claude-opus-4-6`）
- 设置 `agents.defaults.models` 后，它成为 allowlist
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置 provider 级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 可单独覆盖每个模型
- 故障转移运行时规则、冷却探测和 session override 持久化详见[模型故障转移](/ai/ai-tools/openclaw/concepts/model-failover)

添加 provider 认证不会自动更改主模型

当你使用 `openclaw configure` 添加或重新认证一个 provider 时，OpenClaw 会保留已有的 `agents.defaults.model.primary`。`openclaw models auth login` 行为相同，除非你传入了 `--set-default` 参数。Provider 插件可能在认证配置补丁中返回一个推荐的默认模型，但如果已经有了主模型，OpenClaw 只把它视为"让这个模型可用"，不会替换当前的主模型。要主动切换默认模型，使用 `openclaw models set <provider/model>` 或 `openclaw models auth login --provider &lt;id&gt; --set-default`。

OpenAI provider/运行时分离

OpenAI 系列路由按前缀区分：
- `openai/&lt;model&gt;` 默认使用原生 Codex 应用服务 harness 处理智能体轮次。这是常见的 ChatGPT/Codex 订阅设置。
- `openai-codex/&lt;model&gt;` 是遗留配置，doctor 会将其重写为 `openai/&lt;model&gt;`。
- `openai/&lt;model&gt;` 加上 provider/model 的 `agentRuntime.id: "pi"` 使用 PI 作为显式 API Key 或兼容性路由。

更多信息见 [OpenAI](/ai/ai-tools/openclaw/providers/openai) 和 [Codex harness](/ai/ai-tools/openclaw/plugins/codex-harness)。如果 provider/运行时分离概念不清晰，先阅读[智能体运行时](/ai/ai-tools/openclaw/concepts/agent-runtimes)。

插件自动启用遵循相同边界：`openai/*` 智能体引用为默认路由启用 Codex 插件；显式 provider/model 的 `agentRuntime.id: "codex"` 或遗留的 `codex/&lt;model&gt;` 引用也需要它。

GPT-5.5 默认通过原生 Codex 应用服务 harness 在 `openai/gpt-5.5` 上可用，只有当 provider/model 运行时策略显式选择 `pi` 时才通过 PI。

CLI 运行时

CLI 运行时使用相同的分离方式：选择规范模型引用，如 `anthropic/claude-*` 或 `google/gemini-*`，然后当你想使用本地 CLI 后端时，将 provider/model 运行时策略设置为 `claude-cli` 或 `google-gemini-cli`。

遗留的 `claude-cli/*` 和 `google-gemini-cli/*` 引用会迁移回规范 provider 引用，运行时单独记录。遗留的 `codex-cli/*` 引用迁移到 `openai/*` 并使用 Codex 应用服务路由；OpenClaw 不再打包 Codex CLI 后端。

Plugin 拥有的 provider 行为

大部分 provider 特定逻辑位于 provider 插件（registerProvider(...)）中，OpenClaw 维护通用的推理循环。插件负责 onboarding、模型目录、认证环境变量映射、传输/配置标准化、工具模式清理、故障转移分类、OAuth 刷新、用量报告、思考/推理 profile 等。

完整的 provider-SDK 钩子和捆绑插件示例列表见 Provider 插件。需要完全自定义请求执行器的 provider 属于更深层的扩展面。

INFO

由 provider 拥有的运行器行为位于显式 provider 钩子上，如重放策略、工具模式清理、流包装和传输/请求辅助函数。遗留的 ProviderPlugin.capabilities 静态包仅供兼容性使用，共享运行器逻辑不再读取它。

API Key 轮换

Key 来源和优先级

通过以下方式配置多个 key：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单 key 实时覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号分隔列表）
- `<PROVIDER>_API_KEY`（主 key）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）

对于 Google 系列 provider，`GOOGLE_API_KEY` 也作为回退。Key 的选择顺序保留优先级并去重。

何时触发 key 轮换

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

内置 Provider（pi-ai 目录）

OpenClaw 随 pi-ai 目录一起发布。这些 provider 不需要配置 models.providers，只需设置认证并选择模型。

OpenAI

Provider ID：openai
认证：OPENAI_API_KEY
可选轮换：OPENAI_API_KEYS、OPENAI_API_KEY_1、OPENAI_API_KEY_2，以及 OPENCLAW_LIVE_OPENAI_KEY（单 key 覆盖）
示例模型：openai/gpt-5.5、openai/gpt-5.4-mini
验证账户/模型可用性：如果某个安装或 API Key 行为异常，使用 openclaw models list --provider openai
CLI：openclaw onboard --auth-choice openai-api-key
默认传输为 auto；OpenClaw 将传输选择传递给 pi-ai
每个模型可通过 agents.defaults.models["openai/<model>"].params.transport 覆盖（"sse"、"websocket" 或 "auto"）
OpenAI 优先处理可通过 agents.defaults.models["openai/<model>"].params.serviceTier 启用
/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、prompt-cache 提示和 OpenAI 推理兼容负载塑造；代理路由不保留
openai/gpt-5.3-codex-spark 在 OpenClaw 中故意被抑制，因为实时 OpenAI API 请求拒绝它，且当前 Codex 目录未暴露它

json5

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

Anthropic

Provider ID：anthropic
认证：ANTHROPIC_API_KEY
可选轮换：ANTHROPIC_API_KEYS、ANTHROPIC_API_KEY_1、ANTHROPIC_API_KEY_2，以及 OPENCLAW_LIVE_ANTHROPIC_KEY（单 key 覆盖）
示例模型：anthropic/claude-opus-4-6
CLI：openclaw onboard --auth-choice apiKey
直接公共 Anthropic 请求支持共享的 /fast 切换和 params.fastMode，包括发送到 api.anthropic.com 的 API Key 和 OAuth 认证流量；OpenClaw 将其映射到 Anthropic 的 service_tier（auto 与 standard_only）
首选 Claude CLI 配置保持模型引用规范，并单独选择 CLI 后端：anthropic/claude-opus-4-7 配合模型作用域的 agentRuntime.id: "claude-cli"。遗留的 claude-cli/claude-opus-4-7 引用仍可兼容。

INFO

Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用已获允许，因此除非 Anthropic 发布新政策，OpenClaw 视 Claude CLI 复用和 claude -p 使用为受支持的集成。Anthropic setup-token 仍可作为受支持的 OpenClaw token 路径使用，但 OpenClaw 现在在可用时优先使用 Claude CLI 复用和 claude -p。

json5

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

OpenAI Codex OAuth

Provider ID：openai-codex
认证：OAuth（ChatGPT）
遗留 PI 模型引用：openai-codex/gpt-5.5
原生 Codex 应用服务 harness 引用：openai/gpt-5.5
原生 Codex 应用服务 harness 文档：Codex harness
遗留模型引用：codex/gpt-*
插件边界：openai-codex/* 加载 OpenAI 插件；原生 Codex 应用服务插件仅由 Codex harness 运行时或遗留 codex/* 引用选择
CLI：openclaw onboard --auth-choice openai-codex 或 openclaw models auth login --provider openai-codex
默认传输为 auto（WebSocket 优先，SSE 回退）
每个 PI 模型可通过 agents.defaults.models["openai-codex/<model>"].params.transport 覆盖（"sse"、"websocket" 或 "auto"）
params.serviceTier 也会转发到原生 Codex Responses 请求（chatgpt.com/backend-api）
隐藏的 OpenClaw 归属标头（originator、version、User-Agent）仅附加到发往 chatgpt.com/backend-api 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
与直接 openai/* 共享相同的 /fast 切换和 params.fastMode 配置；OpenClaw 将其映射到 service_tier=priority
openai-codex/gpt-5.5 使用 Codex 目录原生 contextWindow = 400000 和默认运行时 contextTokens = 272000；通过 models.providers.openai-codex.models[].contextTokens 覆盖运行时上限
政策说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具/工作流
对于常见的订阅加原生 Codex 运行时路由，使用 openai-codex 认证登录但配置 openai/gpt-5.5；OpenAI 智能体轮次默认选择 Codex
仅当你想通过 PI 使用兼容性路由时，才使用 provider/model 的 agentRuntime.id: "pi"；否则在新智能体配置中保持 openai/gpt-5.5 使用默认 Codex harness
openai-codex/gpt-* 引用仍然是遗留 PI 路由。对于新智能体配置，优先使用 openai/gpt-5.5 配合原生 Codex 运行时。当你想要迁移旧的 openai-codex/* 引用到规范 openai/* 引用时，运行 openclaw doctor --fix

json5

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

json5

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

其他订阅式托管选项

GLM 模型

Z.AI Coding Plan 或通用 API 端点。

MiniMax

MiniMax Coding Plan OAuth 或 API Key 访问。

Qwen Cloud

Qwen Cloud provider 表面加上阿里 DashScope 和 Coding Plan 端点映射。

OpenCode

认证：OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）
Zen 运行时 provider：opencode
Go 运行时 provider：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 Key）

Provider ID：google
认证：GEMINI_API_KEY
可选轮换：GEMINI_API_KEYS、GEMINI_API_KEY_1、GEMINI_API_KEY_2、GOOGLE_API_KEY 回退，以及 OPENCLAW_LIVE_GEMINI_KEY（单 key 覆盖）
示例模型：google/gemini-3.1-pro-preview、google/gemini-3-flash-preview
兼容性：使用 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）以转发 provider 原生的 cachedContents/... 句柄；Gemini 缓存命中显示为 OpenClaw cacheRead

Google Vertex 和 Gemini CLI

Provider：google-vertex、google-gemini-cli
认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程

WARNING

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`。你**不需要**在 `openclaw.json` 中粘贴客户端 ID 或密钥。CLI 登录流程将 token 存储在网关主机上的认证 profile 中。

设置项目（如果需要）

如果登录后请求失败，在网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。

Gemini CLI JSON 回复从 response 解析；用量回退到 stats，stats.cached 归一化为 OpenClaw cacheRead。

Z.AI（GLM）

Provider ID：zai
认证：ZAI_API_KEY
示例模型：zai/glm-5.1
CLI：openclaw onboard --auth-choice zai-api-key
- 别名：z.ai/* 和 z-ai/* 归一化为 zai/*
- zai-api-key 自动检测匹配的 Z.AI 端点；zai-coding-global、zai-coding-cn、zai-global 和 zai-cn 强制指定特定表面

Vercel AI Gateway

Provider ID：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

Kilo Gateway

Provider ID：kilocode
认证：KILOCODE_API_KEY
示例模型：kilocode/kilo/auto
CLI：openclaw onboard --auth-choice kilocode-api-key
Base URL：https://api.kilo.ai/api/gateway/
静态回退目录包含 kilocode/kilo/auto；实时 https://api.kilo.ai/api/gateway/models 发现可以进一步扩展运行时目录。
kilocode/kilo/auto 背后的精确上游路由由 Kilo Gateway 拥有，不在 OpenClaw 中硬编码。

详见 /providers/kilocode。

其他捆绑的 Provider 插件

Provider	ID	认证环境变量	示例模型
BytePlus	`byteplus` / `byteplus-plan`	`BYTEPLUS_API_KEY`	`byteplus-plan/ark-code-latest`
Cerebras	`cerebras`	`CEREBRAS_API_KEY`	`cerebras/zai-glm-4.7`
Cloudflare AI Gateway	`cloudflare-ai-gateway`	`CLOUDFLARE_AI_GATEWAY_API_KEY`	-
DeepInfra	`deepinfra`	`DEEPINFRA_API_KEY`	`deepinfra/deepseek-ai/DeepSeek-V3.2`
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY`	`deepseek/deepseek-v4-flash`
GitHub Copilot	`github-copilot`	`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`	-
Groq	`groq`	`GROQ_API_KEY`	-
Hugging Face Inference	`huggingface`	`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`	`huggingface/deepseek-ai/DeepSeek-R1`
Kilo Gateway	`kilocode`	`KILOCODE_API_KEY`	`kilocode/kilo/auto`
Kimi Coding	`kimi`	`KIMI_API_KEY` 或 `KIMICODE_API_KEY`	`kimi/kimi-for-coding`
MiniMax	`minimax` / `minimax-portal`	`MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN`	`minimax/MiniMax-M2.7`
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-super-120b-a12b`
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`	`openrouter/auto`
Qianfan	`qianfan`	`QIANFAN_API_KEY`	`qianfan/deepseek-v3.2`
Qwen Cloud	`qwen`	`QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY`	`qwen/qwen3.5-plus`
StepFun	`stepfun` / `stepfun-plan`	`STEPFUN_API_KEY`	`stepfun/step-3.5-flash`
Together	`together`	`TOGETHER_API_KEY`	`together/moonshotai/Kimi-K2.5`
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（豆包）	`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_API_KEY`	`xiaomi/mimo-v2-flash`

值得注意的特性

OpenRouter

仅在经验证的 `openrouter.ai` 路由上应用其应用归属标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用有资格由 OpenRouter 管理的 prompt 缓存获得 cache-TTL，但不接收 Anthropic 缓存标记。作为代理风格的 OpenAI 兼容路径，它跳过原生 OpenAI 专属的塑造（`serviceTier`、Responses `store`、prompt-cache 提示、OpenAI 推理兼容）。Gemini 驱动的引用仅保留代理 Gemini 思考签名清理。

Kilo Gateway

Gemini 驱动的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用跳过代理推理注入。

MiniMax

API Key onboarding 写入显式的纯文本 M2.7 聊天模型定义；图像理解保留在插件拥有的 `MiniMax-VL-01` 媒体 provider 上。

NVIDIA

模型 ID 使用 `nvidia/&lt;vendor&gt;/&lt;model&gt;` 命名空间（例如 `nvidia/nvidia/nemotron-...` 以及 `nvidia/moonshotai/kimi-k2.5`）；选择器保留字面 `&lt;provider&gt;/&lt;model-id&gt;` 组合，而发送到 API 的规范 key 保持单前缀。

xAI

使用 xAI Responses 路径。推荐路径是 SuperGrok/X Premium OAuth；API Key 仍可通过 `XAI_API_KEY` 或插件配置工作，Grok `web_search` 在 API Key 回退之前复用相同的认证 profile。`grok-4.3` 是捆绑的默认聊天模型，`grok-build-0.1` 可选择用于构建/编码相关工作。`/fast` 或 `params.fastMode: true` 将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为它们的 `*-fast` 变体。`tool_stream` 默认启用；通过 `agents.defaults.models["xai/&lt;model&gt;"].params.tool_stream=false` 禁用它。

Cerebras

作为捆绑的 `cerebras` provider 插件发布。GLM 使用 `zai-glm-4.7`；OpenAI 兼容 base URL 是 `https://api.cerebras.ai/v1`。

通过 models.providers 配置的自定义 Provider（Base URL）

使用 models.providers（或 models.json）添加自定义 provider 或 OpenAI/Anthropic 兼容代理。

下面列出的许多捆绑 provider 插件已经发布了默认目录。仅在你想覆盖默认 base URL、标头或模型列表时使用显式 models.providers.<id> 条目。

网关模型能力检查也会读取显式 models.providers.<id>.models[] 元数据。如果自定义或代理模型接受图像，在该模型上设置 input: ["text", "image"]，以便 WebChat 和节点来源附件路径将图像作为原生模型输入传递，而不是纯文本媒体引用。

agents.defaults.models["provider/model"] 仅控制模型可见性、别名和智能体的每个模型元数据。它本身不会注册新的运行时模型。对于自定义 provider 模型，还需要添加 models.providers.<provider>.models[]，至少包含匹配的 id。

Moonshot AI（Kimi）

Moonshot 作为捆绑 provider 插件发布。默认使用内置 provider，仅在需要覆盖 base URL 或模型元数据时添加显式的 models.providers.moonshot 条目：

Provider ID：moonshot
认证：MOONSHOT_API_KEY
示例模型：moonshot/kimi-k2.6
CLI：openclaw onboard --auth-choice moonshot-api-key 或 openclaw onboard --auth-choice moonshot-api-key-cn

Kimi K2 模型 ID：

moonshot/kimi-k2.6
moonshot/kimi-k2.5
moonshot/kimi-k2-thinking
moonshot/kimi-k2-thinking-turbo
moonshot/kimi-k2-turbo

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" }],
      },
    },
  },
}

Kimi coding

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

Provider ID：kimi
认证：KIMI_API_KEY
示例模型：kimi/kimi-for-coding

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（豆包）

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

Provider ID：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" } },
  },
}

Onboarding 默认使用编程表面，但同时注册 volcengine/* 目录。

在 onboarding/configure 模型选择器中，Volcengine 认证选项优先显示 volcengine/* 和 volcengine-plan/* 行。如果这些模型尚未加载，OpenClaw 回退到未过滤的目录，而不是显示空的 provider 作用域选择器。

标准模型

- `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 128K）

编程模型（volcengine-plan）

- `volcengine-plan/ark-code-latest`
- `volcengine-plan/doubao-seed-code`
- `volcengine-plan/kimi-k2.5`
- `volcengine-plan/kimi-k2-thinking`
- `volcengine-plan/glm-4.7`

BytePlus（国际版）

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

Provider ID：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" } },
  },
}

Onboarding 默认使用编程表面，但同时注册 byteplus/* 目录。

在 onboarding/configure 模型选择器中，BytePlus 认证选项优先显示 byteplus/* 和 byteplus-plan/* 行。如果这些模型尚未加载，OpenClaw 回退到未过滤的目录，而不是显示空的 provider 作用域选择器。

标准模型

- `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/doubao-seed-code`
- `byteplus-plan/kimi-k2.5`
- `byteplus-plan/kimi-k2-thinking`
- `byteplus-plan/glm-4.7`

Synthetic

Synthetic 在 synthetic provider 背后提供 Anthropic 兼容模型：

Provider ID：synthetic
认证：SYNTHETIC_API_KEY
示例模型：synthetic/hf:MiniMaxAI/MiniMax-M2.5
CLI：openclaw onboard --auth-choice synthetic-api-key

json5

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

MiniMax

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

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

详见 /providers/minimax 了解设置详情、模型选项和配置片段。

INFO

在 MiniMax 的 Anthropic 兼容流式路径上，除非你显式设置，否则 OpenClaw 默认禁用思考。/fast on 将 MiniMax-M2.7 重写为 MiniMax-M2.7-highspeed。

插件拥有的能力拆分：

文本/聊天默认保留在 minimax/MiniMax-M2.7 上
图像生成是 minimax/image-01 或 minimax-portal/image-01
图像理解是插件拥有的 MiniMax-VL-01，在两种 MiniMax 认证路径上都可用
网络搜索保留在 provider ID minimax 上

LM Studio

LM Studio 作为捆绑 provider 插件发布，使用原生 API：

Provider ID：lmstudio
认证：LM_API_TOKEN
默认推理 base 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。

Ollama

Ollama 作为捆绑 provider 插件发布，使用 Ollama 的原生 API：

Provider ID：ollama
认证：无需（本地服务器）
示例模型：ollama/llama3.3
安装：https://ollama.com/download

bash

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

json5

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

当你在 openclaw.json 中设置 OLLAMA_API_KEY 时，Ollama 在本地 http://127.0.0.1:11434 被检测到，并且捆绑的 provider 插件将 Ollama 直接添加到 openclaw onboard 和模型选择器。详见 /providers/ollama。

vLLM

vLLM 作为捆绑 provider 插件发布，用于本地/自托管的 OpenAI 兼容服务器：

Provider ID：vllm
认证：可选（取决于你的服务器）
默认 base 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。

SGLang

SGLang 作为捆绑 provider 插件发布，用于快速的本地/自托管 OpenAI 兼容服务器：

Provider ID：sglang
认证：可选（取决于你的服务器）
默认 base 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。

本地代理（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,
          },
        ],
      },
    },
  },
}

默认可选字段

对于自定义 provider，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。省略时，OpenClaw 默认使用：
- `reasoning: false`
- `input: ["text"]`
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`

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

代理路由塑造规则

- 对于非原生端点上（任何非空 `baseUrl` 且主机不是 `api.openai.com`）的 `api: "openai-completions"`，OpenClaw 强制 `compat.supportsDeveloperRole: false` 以避免 provider 对不支持的 `developer` 角色返回 400 错误。
- 代理风格的 OpenAI 兼容路由还跳过原生 OpenAI 专属的请求塑造：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有 prompt-cache 提示，没有 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 插件在 session 思考级别关闭时，自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
- 对于慢速本地模型或远程 LAN/tailnet 主机，设置 `models.providers.&lt;id&gt;.timeoutSeconds`。这会延长 provider 模型 HTTP 请求处理，包括连接、标头、主体流和受保护的 fetch 中止，但不增加整个智能体运行时超时。如果 `agents.defaults.timeoutSeconds` 或运行特定的超时更低，也需要提高那个上限；provider 超时不能延长整个运行时间。
- 模型 provider HTTP 调用仅在配置的 provider `baseUrl` 主机名上允许 Surge、Clash 和 sing-box 假 IP DNS 响应在 `198.18.0.0/15` 和 `fc00::/7` 中。自定义/本地 provider 端点也信任该精确配置的 `scheme://host:port` 来源用于受保护的模型请求，包括 loopback、LAN 和 tailnet 主机。这不是新的配置选项；你配置的 `baseUrl` 仅针对该来源扩展请求策略。假 IP 主机名允许和精确来源信任是独立的机制。其他私有、loopback、link-local、元数据目的地和不同端口仍然需要显式的 `models.providers.&lt;id&gt;.request.allowPrivateNetwork: true` 选择加入。设置 `models.providers.&lt;id&gt;.request.allowPrivateNetwork: false` 以选择退出精确来源信任。
- 如果 `baseUrl` 为空/省略，OpenClaw 保留默认的 OpenAI 行为（解析为 `api.openai.com`）。
- 出于安全考虑，在非原生 `openai-completions` 端点上，仍然会覆盖显式的 `compat.supportsDeveloperRole: true`。
- 对于非直接端点上（任何不是规范 `anthropic` 的 provider，或自定义 `models.providers.anthropic.baseUrl` 且主机不是公共 `api.anthropic.com` 端点）的 `api: "anthropic-messages"`，OpenClaw 禁止隐式 Anthropic beta 标头，如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，这样自定义 Anthropic 兼容代理不会拒绝不支持的 beta 标记。如果你的代理需要特定的 beta 特性，请显式设置 `models.providers.&lt;id&gt;.headers["anthropic-beta"]`。

CLI 示例

bash

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

完整配置示例见配置参考。

常见问题

国内用户推荐使用哪个 provider？

对网络限制较多的场景，推荐使用火山引擎（volcengine-plan）和 Qwen Cloud（qwen），它们都提供国内直接访问端点。Kimi Coding（kimi）和 MiniMax 也是不错的选择。具体接入步骤参考对应 provider 文档。

怎么同时配置多个 provider 作为 fallback？

在 agents.defaults.model.fallbacks 中配置 fallback 链，OpenClaw 会按顺序尝试备用 provider。详细配置见模型故障转移。

自定义 proxy 的 baseUrl 配置有哪些注意事项？

如果使用 api: "openai-completions" 且 baseUrl 不是 api.openai.com，OpenClaw 会自动关闭 supportsDeveloperRole 并跳过原生 OpenAI 特有的请求体字段（如 service_tier、store、prompt-cache 提示）。对于慢速本地模型，记得同时设置 models.providers.<id>.timeoutSeconds 和 agents.defaults.timeoutSeconds，否则 provider 超时无法延长整个运行时间。

OpenClaw 模型 Provider 配置完整指南 ​

快速规则 ​

Plugin 拥有的 provider 行为 ​

API Key 轮换 ​

内置 Provider（pi-ai 目录） ​

OpenAI ​

Anthropic ​

OpenAI Codex OAuth ​

其他订阅式托管选项 ​

OpenCode ​

Google Gemini（API Key） ​

Google Vertex 和 Gemini CLI ​

Z.AI（GLM） ​

Vercel AI Gateway ​

Kilo Gateway ​

其他捆绑的 Provider 插件 ​

值得注意的特性 ​

通过 models.providers 配置的自定义 Provider（Base URL） ​

Moonshot AI（Kimi） ​

Kimi coding ​

Volcano Engine（豆包） ​

BytePlus（国际版） ​

Synthetic ​

MiniMax ​

LM Studio ​

Ollama ​

vLLM ​

SGLang ​

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

CLI 示例 ​

常见问题 ​

国内用户推荐使用哪个 provider？ ​

怎么同时配置多个 provider 作为 fallback？ ​

自定义 proxy 的 baseUrl 配置有哪些注意事项？ ​

相关 ​

OpenClaw 模型 Provider 配置完整指南

快速规则

Plugin 拥有的 provider 行为

API Key 轮换

内置 Provider（pi-ai 目录）

OpenAI

Anthropic

OpenAI Codex OAuth

其他订阅式托管选项

OpenCode

Google Gemini（API Key）

Google Vertex 和 Gemini CLI

Z.AI（GLM）

Vercel AI Gateway

Kilo Gateway

其他捆绑的 Provider 插件

值得注意的特性

通过 models.providers 配置的自定义 Provider（Base URL）

Moonshot AI（Kimi）

Kimi coding

Volcano Engine（豆包）

BytePlus（国际版）

Synthetic

MiniMax

LM Studio

Ollama

vLLM

SGLang

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

CLI 示例

常见问题

国内用户推荐使用哪个 provider？

怎么同时配置多个 provider 作为 fallback？

自定义 proxy 的 baseUrl 配置有哪些注意事项？

相关