模型提供商

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

快速规则

在 Control UI 中配置提供商

在 Control UI 中打开 Settings → Model Providers，以添加、替换或移除存储在 models.providers.<id>.apiKey 中的提供商 API key。该页面会标明每个 API key 来自 OpenClaw 配置还是环境变量，但不会显示凭据。由环境提供的密钥仍由 Gateway 网关进程环境管理。

使用 Test connection 运行实时提供商探测，并查看延迟，或经过分类的身份验证、速率限制、计费、超时或响应错误。探测会发出真实的提供商请求，并可能消耗少量 token。也可以从提供商卡片中注销 OAuth 和 token 配置文件。

Default models 卡片用于管理主模型、有序回退模型以及配置模型目录中的实用模型。选择模型，然后将它们一起保存到现有的 agents.defaults.model 和 agents.defaults.utilityModel 设置中。对于实用模型，Automatic 会让该设置保持未设置状态，而 Disabled 会存储空字符串以关闭实用模型路由。

插件所有的提供商行为

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

提供商 SDK 钩子的完整列表以及内置插件示例位于提供商插件中。需要完全自定义请求执行器的提供商属于另一个更深层的扩展接口。

API key 轮换

官方提供商插件

官方提供商插件会发布自己的模型目录行。这些提供商不需要 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 key 的行为不同，请使用 openclaw models list --provider openai 验证账户/模型可用性。
• CLI：openclaw onboard --auth-choice openai-api-key
• 默认传输方式为 auto；OpenClaw 会将传输方式选择传递给共享模型运行时。
• 通过 agents.defaults.models["openai/<model>"].params.transport 按模型覆盖（"sse"、"websocket" 或 "auto"）
• 可以通过 agents.defaults.models["openai/<model>"].params.serviceTier 启用 OpenAI 优先处理
• /fast 和 params.fastMode 会将发送到 api.openai.com 的直接 openai/* Responses 请求映射到 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 key 和 Azure API key 路由会拒绝它

{  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-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-8，并使用模型范围的 agentRuntime.id: "claude-cli"。为兼容起见，旧版 claude-cli/claude-opus-4-7 引用仍然有效。

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

OpenAI ChatGPT/Codex OAuth

• 提供商：openai
• 身份验证：OAuth（ChatGPT）
• 全新的原生 Codex app-server harness 引用：openai/gpt-5.6-sol
• 原生 Codex app-server harness 文档：Codex harness
• 旧版模型引用：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 和 params.fastMode 是编写到请求中的内嵌请求设置。它们让隐式运行时选择继续由 OpenClaw 负责；原生 Codex 负责其 app-server 传输和服务层级。
• 隐藏的 OpenClaw 归因标头（originator、version、User-Agent）仅附加到发往 chatgpt.com/backend-api 的原生 Codex 流量，不会附加到通用的 OpenAI 兼容代理
• 共享的 /fast 开关仍可用作运行时控制；它不同于编写到请求中的模型参数。
• 原生 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/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 }],      },    },  },}

其他订阅式托管选项

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.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、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 默认使用 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

其他内置提供商插件

值得了解的特殊行为

通过 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）

请在新手引导前安装 @openclaw/moonshot-provider。仅当需要覆盖基础 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.7-code
• 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" }],      },    },  },}

完整设置指南请参阅 Moonshot AI（Kimi + Kimi Coding）。

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（火山引擎）在中国提供对豆包及其他模型的访问。

• 提供商：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 密钥（全球）：--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/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 之一）：

{  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 选择启用后，会在本地的 http://127.0.0.1:11434 检测 Ollama，内置提供商插件也会将 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 - 模型配置和别名
• 提供商 - 各提供商的设置指南