模型提供商

LLM/模型提供商的参考（不是 WhatsApp/Telegram 这样的聊天渠道）。模型选择规则见 Models。

# 快速规则

# 插件拥有的提供商行为

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

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

# API 密钥轮换

# 内置提供商（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 密钥表现不同，请用 openclaw models list --provider openai 验证账户/模型可用性。
• CLI：openclaw onboard --auth-choice openai-api-key
• 默认传输为 auto（WebSocket 优先，SSE 回退）
• 通过 agents.defaults.models["openai/<model>"].params.transport 按模型覆盖（"sse"、"websocket" 或 "auto"）
• OpenAI Responses WebSocket 预热默认通过 params.openaiWsWarmup 启用（true/false）
• 可以通过 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 在 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 密钥和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic service_tier（auto 与 standard_only）
• 首选 Claude CLI 配置会保留规范模型引用，并单独选择 CLI 后端：anthropic/claude-opus-4-7 搭配 agents.defaults.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，搭配 agents.defaults.agentRuntime.id: "codex"
• 原生 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 加上 agents.defaults.agentRuntime.id: "codex"。
• 仅当你希望通过 PI 使用 Codex OAuth/订阅路线时，才使用 openai-codex/gpt-5.5；当你的 API 密钥设置和本地目录公开公共 API 路线时，使用不带 Codex 运行时覆盖的 openai/gpt-5.5。
• 较旧的 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" },
      agentRuntime: { id: "codex" },
    },
  },
}

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

• 提供商：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 配置提供商（自定义/base URL）

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

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

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

# Moonshot AI（Kimi）

Moonshot 作为内置提供商插件交付。默认使用内置提供商；仅当你需要覆盖 base 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 编码

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

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

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

旧版 kimi/k2p5 仍作为兼容模型 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 为国际用户提供对与 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_API_KEY 用于 minimax；MINIMAX_OAUTH_TOKEN 或 MINIMAX_API_KEY 用于 minimax-portal

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

插件拥有的能力拆分：

• 文本/聊天默认保留在 minimax/MiniMax-M2.7
• 图像生成是 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

# 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-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list

另请参阅：配置 了解完整配置示例。

# 相关内容

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