模型提供商

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

快速规则

在 Control UI 中配置提供商

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

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

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

插件所有的提供商行为

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

提供商 SDK 钩子和内置插件示例的完整列表，请参阅提供商插件。需要完全自定义请求执行器的提供商属于独立且更深层的扩展接口。

API 密钥轮换

官方提供商插件

官方提供商插件会发布各自的模型目录条目。这些提供商不需要 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/<model>"].params.transport 按模型覆盖（"sse"、"websocket" 或 "auto"）
• 可通过 agents.defaults.models["openai/<model>"].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 密钥路由会拒绝它

{  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 引用仍可用于兼容。

{  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
• 旧版模型引用：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/<model>"].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 不会升级。

{  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 密钥）

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

内置路由和目录中已知的路由从其所属提供商插件获取 compat 能力。配置中的 compat 块用于自定义提供商/模型，或用于已验证端点契约的其他 api/baseUrl 路由；请参阅自定义提供商能力指南。Doctor 会移除仅重复目录内容的旧值，并保留不同的值，以供操作员审核。

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

agents.defaults.models["provider/model"] 控制智能体的别名和每模型元数据。它既不限制覆盖，也不会自行注册新的运行时模型。对于自定义提供商模型，还需添加 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 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

{  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

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

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

在新手引导/配置模型选择器中，Volcengine 身份验证选项会优先使用 volcengine/* 和 volcengine-plan/* 两行。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示空的提供商范围选择器。

BytePlus（国际版）

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

• 提供商：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-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/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 - 模型配置和别名
• 提供商 - 各提供商的设置指南