模型提供商

LLM/模型提供商参考（不是 WhatsApp/Telegram 等聊天渠道）。有关模型选择规则，请参阅 Models。

快速规则

插件拥有的提供商行为

大多数提供商特定逻辑位于提供商插件（registerProvider(...)）中，而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、凭证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、思考/推理配置等能力。

提供商 SDK 钩子和内置插件示例的完整列表位于 Provider Plugins。需要完全自定义请求执行器的提供商属于一个独立且更深的扩展面。

API key 轮换

内置提供商（pi-ai 目录）

OpenClaw 随附 pi-ai 目录。这些提供商不需要任何 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.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、提示缓存提示和 OpenAI 推理兼容载荷整形；代理路由不会
• openai/gpt-5.3-codex-spark 在 OpenClaw 中被有意隐藏，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未暴露它

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

Anthropic

• 提供商：anthropic
• 凭证：ANTHROPIC_API_KEY
• 可选轮换：ANTHROPIC_API_KEYS、ANTHROPIC_API_KEY_1、ANTHROPIC_API_KEY_2，以及 OPENCLAW_LIVE_ANTHROPIC_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 引用仍可用于兼容。

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

OpenAI Codex OAuth

• 提供商：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 回退）
• 通过 agents.defaults.models["openai-codex/<model>"].params.transport 按 PI 模型覆盖（"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 Agent 轮次默认选择 Codex。
• 仅当你需要通过 PI 走兼容性路由时，才使用提供商/模型 agentRuntime.id: "pi"；否则让 openai/gpt-5.5 保持在默认 Codex harness 上。
• 较旧的 openai-codex/gpt-5.1*、openai-codex/gpt-5.2* 和 openai-codex/gpt-5.3* 引用被隐藏，因为 ChatGPT/Codex OAuth 账户会拒绝它们；请改用 openai-codex/gpt-5.5 或原生 Codex 运行时路由。

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

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

其他订阅式托管选项

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 key）

• 提供商：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-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），以转发提供商原生的 cachedContents/... 句柄；Gemini 缓存命中会显示为 OpenClaw cacheRead

Google Vertex 和 Gemini CLI

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

Gemini CLI OAuth 作为内置 google 插件的一部分发布。

brew install gemini-cli

npm install -g @google/gemini-cli

openclaw plugins enable google

openclaw models auth login --provider google-gemini-cli --set-default

Gemini CLI JSON 回复会从 response 解析；用量会回退到 stats，其中 stats.cached 会被规范化为 OpenClaw cacheRead。

Z.AI (GLM)

• 提供商：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

• 提供商：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

• 提供商：kilocode
• 认证：KILOCODE_API_KEY
• 示例模型：kilocode/kilo/auto
• CLI：openclaw onboard --auth-choice kilocode-api-key
• 基础 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。

其他内置提供商插件

值得了解的注意事项

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

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

下面许多内置提供商插件已经发布默认目录。仅当你想覆盖默认基础 URL、标头或模型列表时，才使用显式的 models.providers.<id> 条目。

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

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

Moonshot AI（Kimi）

Moonshot 作为内置提供商插件发布。默认使用内置提供商；只有在需要覆盖基础 URL 或模型元数据时，才添加显式的 models.providers.moonshot 条目：

• 提供商：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

{  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 兼容端点：

• 提供商：kimi
• 凭证：KIMI_API_KEY
• 示例模型：kimi/kimi-for-coding

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

旧版 kimi/kimi-code 和 kimi/k2p5 仍作为兼容模型 ID 被接受，并会规范化为 Kimi 的稳定 API 模型 ID。

Volcano Engine（豆包）

Volcano Engine（火山引擎）为中国用户提供对 Doubao 和其他模型的访问。

• 提供商：volcengine（编码：volcengine-plan）
• 凭证：VOLCANO_ENGINE_API_KEY
• 示例模型：volcengine-plan/ark-code-latest
• CLI：openclaw onboard --auth-choice volcengine-api-key

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

新手引导默认使用编码端面，但通用 volcengine/* 目录会同时注册。

在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 volcengine/* 和 volcengine-plan/* 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个按提供商范围过滤后的空选择器。

BytePlus（国际版）

BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。

• 提供商：byteplus（编码：byteplus-plan）
• 凭证：BYTEPLUS_API_KEY
• 示例模型：byteplus-plan/ark-code-latest
• CLI：openclaw onboard --auth-choice byteplus-api-key

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

新手引导默认使用编码端面，但通用 byteplus/* 目录会同时注册。

在新手引导/配置模型选择器中，BytePlus 凭证选项会优先显示 byteplus/* 和 byteplus-plan/* 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个按提供商范围过滤后的空选择器。

Synthetic

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

• 提供商：synthetic
• 凭证：SYNTHETIC_API_KEY
• 示例模型：synthetic/hf:MiniMaxAI/MiniMax-M2.5
• CLI：openclaw onboard --auth-choice synthetic-api-key

{  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 使用 MINIMAX_API_KEY；minimax-portal 使用 MINIMAX_OAUTH_TOKEN 或 MINIMAX_API_KEY

有关设置详情、模型选项和配置片段，请参阅 /providers/minimax。

插件拥有的能力拆分：

• 文本/聊天默认保持在 minimax/MiniMax-M2.7
• 图像生成是 minimax/image-01 或 minimax-portal/image-01
• 图像理解是插件拥有的 MiniMax-VL-01，适用于两个 MiniMax 凭证路径
• Web 搜索保持在提供商 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

# Install Ollama, then pull a model: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。

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

CLI 示例

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

另请参阅：配置，获取完整配置示例。

相关内容

• 配置参考 - 模型配置键
• 模型故障转移 - 回退链和重试行为
• Models - 模型配置和别名
• 提供商 - 各提供商设置指南