学了个寂寞

Appearance

模型提供商 ​

本页介绍 LLM / 模型 provider（不含 WhatsApp/Telegram 等 chat 渠道）。 模型选择规则参见 /openclaw/concepts/models。

快速规则 ​

  • Model ref 格式为 provider/model（例如 opencode/claude-opus-4-6）。
  • 若设置了 agents.defaults.models，它将成为允许列表（allowlist）。
  • CLI 辅助命令：openclaw onboard、openclaw models list、openclaw models set <provider/model>。
  • Provider 插件可通过 registerProvider({ catalog }) 注入模型目录，OpenClaw 会在写入 models.json 前将其合并到 models.providers。
  • Provider 清单可声明 providerAuthEnvVars，使通用环境变量认证探测无需加载插件运行时。
  • Provider 插件还可通过 resolveDynamicModel、prepareDynamicModel、normalizeResolvedModel、capabilities、prepareExtraParams、wrapStreamFn、formatApiKey、refreshOAuth、buildAuthDoctorHint、isCacheTtlEligible、buildMissingAuthMessage、suppressBuiltInModel、augmentModelCatalog、isBinaryThinking、supportsXHighThinking、resolveDefaultThinkingLevel、isModernModelRef、prepareRuntimeAuth、resolveUsageAuth、fetchUsageSnapshot 等接口控制 provider 运行时行为。
  • 注意：provider 运行时 capabilities 是共享的 runner 元数据（provider 家族、对话/工具特性、传输/缓存提示），与公开 capability 模型（描述插件注册的能力：文本推理、语音等）不同。

插件拥有的 Provider 行为 ​

Provider 插件现在可以拥有大部分 provider 特定逻辑，而 OpenClaw 保持通用推理循环。

典型分工：

  • auth[].run / auth[].runNonInteractive：provider 拥有 openclaw onboard、openclaw models auth 和无头配置的上线/登录流程
  • wizard.setup / wizard.modelPicker：provider 拥有认证选项标签、遗留别名、上线允许列表提示以及上线/模型选择器中的配置入口
  • catalog：provider 出现在 models.providers
  • resolveDynamicModel：provider 接受本地静态目录中尚不存在的 model id
  • prepareDynamicModel：provider 在重试动态解析前需要刷新元数据
  • normalizeResolvedModel：provider 需要改写传输方式或 base URL
  • capabilities：provider 发布对话/工具/provider 家族特性
  • prepareExtraParams：provider 默认或规范化每个模型的请求参数
  • wrapStreamFn：provider 应用请求 headers/body/model 兼容包装
  • formatApiKey：provider 将存储的 auth profile 格式化为传输层期望的运行时 apiKey 字符串
  • refreshOAuth：当共享 pi-ai 刷新器不够用时，provider 自行处理 OAuth 刷新
  • buildAuthDoctorHint：OAuth 刷新失败时，provider 追加修复指引
  • isCacheTtlEligible：provider 决定哪些上游 model id 支持 prompt-cache TTL
  • buildMissingAuthMessage：provider 用特定恢复提示替换通用认证错误
  • suppressBuiltInModel：provider 隐藏过期的上游行，并可为直接解析失败返回厂商自有错误
  • augmentModelCatalog：provider 在发现和配置合并后追加合成/最终目录行
  • isBinaryThinking：provider 拥有 thinking 开/关的二进制 UX
  • supportsXHighThinking：provider 为选定模型启用 xhigh
  • resolveDefaultThinkingLevel：provider 拥有某模型家族的默认 /think 策略
  • isModernModelRef：provider 拥有 live/smoke 首选模型匹配
  • prepareRuntimeAuth：provider 将已配置的凭据转为短期运行时令牌
  • resolveUsageAuth：provider 解析 /usage 等状态/报告界面的用量/配额凭据
  • fetchUsageSnapshot：provider 拥有用量端点的抓取/解析，核心拥有摘要外壳和格式化

当前内置示例：

  • anthropic：Claude 4.6 前向兼容回退、认证修复提示、用量端点抓取、cache-TTL/provider 家族元数据
  • openrouter：透传 model id、请求包装、provider capability 提示、cache-TTL 策略
  • github-copilot：上线/设备登录、前向兼容模型回退、Claude thinking 对话提示、运行时令牌交换、用量端点抓取
  • openai：GPT-5.4 前向兼容回退、直连 OpenAI 传输规范化、Codex 感知缺失认证提示、Spark 抑制、合成 OpenAI/Codex 目录行、thinking/live-model 策略、provider 家族元数据
  • google 和 google-gemini-cli：Gemini 3.1 前向兼容回退和现代模型匹配；Gemini CLI OAuth 还拥有 auth-profile token 格式化、用量令牌解析以及用量界面的配额端点抓取
  • moonshot：共享传输、插件拥有 thinking payload 规范化
  • kilocode：共享传输、插件拥有请求 headers、推理 payload 规范化、Gemini 对话提示、cache-TTL 策略
  • zai：GLM-5 前向兼容回退、tool_stream 默认值、cache-TTL 策略、二进制 thinking/live-model 策略、用量认证+配额抓取
  • mistral、opencode、opencode-go：插件拥有 capability 元数据
  • byteplus、cloudflare-ai-gateway、huggingface、kimi-coding、modelstudio、nvidia、qianfan、synthetic、together、venice、vercel-ai-gateway、volcengine：仅插件拥有目录
  • minimax 和 xiaomi：插件拥有目录加上用量认证/快照逻辑

内置 openai 插件现在同时拥有 openai 和 openai-codex 两个 provider id。

以上涵盖了适合 OpenClaw 标准传输的 provider。需要完全自定义请求执行器的 provider 属于独立的更深层扩展面。

API Key 轮换 ​

  • 支持对选定 provider 做通用 provider 轮换。
  • 通过以下方式配置多个 key：
    • OPENCLAW_LIVE_<PROVIDER>_KEY（单个实时覆盖，最高优先级）
    • <PROVIDER>_API_KEYS（逗号或分号分隔的列表）
    • <PROVIDER>_API_KEY（主要 key）
    • <PROVIDER>_API_KEY_*（编号列表，如 <PROVIDER>_API_KEY_1）
  • 对于 Google provider，还会将 GOOGLE_API_KEY 作为 fallback。
  • Key 选择顺序保持优先级并去重。
  • 仅在限流响应（例如 429、rate_limit、quota、resource exhausted）时才用下一个 key 重试。
  • 非限流失败立即失败，不尝试 key 轮换。
  • 所有候选 key 均失败时，返回最后一次尝试的错误。

内置 Provider（pi-ai 目录） ​

OpenClaw 内置 pi-ai 目录。这些 provider 无需 models.providers 配置，只需设置认证并选择模型即可。

OpenAI ​

  • Provider：openai
  • 认证：OPENAI_API_KEY
  • 可选轮换：OPENAI_API_KEYS、OPENAI_API_KEY_1、OPENAI_API_KEY_2，以及 OPENCLAW_LIVE_OPENAI_KEY（单个覆盖）
  • 示例模型：openai/gpt-5.4、openai/gpt-5.4-pro
  • 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 优先处理
  • 可通过 agents.defaults.models["<provider>/<model>"].params.fastMode 按模型启用 OpenAI 快速模式
  • openai/gpt-5.3-codex-spark 在 OpenClaw 中被有意抑制，因为 OpenAI 直连 API 会拒绝它；Spark 被视为仅 Codex 可用
json5
{
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}

Anthropic ​

  • Provider：anthropic
  • 认证：ANTHROPIC_API_KEY 或 claude setup-token
  • 可选轮换：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 token（粘贴 setup-token）或 openclaw models auth paste-token --provider anthropic
  • 直连 API key 模型支持共享 /fast 切换和 params.fastMode；OpenClaw 会将其映射到 Anthropic service_tier（auto 或 standard_only）
  • 策略说明：setup-token 支持是技术兼容性，Anthropic 过去曾限制 Claude Code 以外的订阅使用。请自行确认当前 Anthropic 条款并根据风险承受度决定。
  • 建议：Anthropic API key 认证是比订阅 setup-token 更安全的推荐路径。
json5
{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

OpenAI Code（Codex） ​

  • Provider：openai-codex
  • 认证：OAuth（ChatGPT）
  • 示例模型：openai-codex/gpt-5.4
  • 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 按模型覆盖
  • 与直连 openai/* 共享相同的 /fast 切换和 params.fastMode 配置
  • 当 Codex OAuth 目录暴露时，openai-codex/gpt-5.3-codex-spark 仍可用；取决于账户权限
  • 策略说明：OpenAI Codex OAuth 明确支持在 OpenClaw 等外部工具/工作流中使用。
json5
{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}

OpenCode ​

  • 认证：OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）
  • Zen 运行时 provider：opencode
  • Go 运行时 provider：opencode-go
  • 示例模型：opencode/claude-opus-4-6、opencode-go/kimi-k2.5
  • 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：google
  • 认证：GEMINI_API_KEY
  • 可选轮换：GEMINI_API_KEYS、GEMINI_API_KEY_1、GEMINI_API_KEY_2、GOOGLE_API_KEY（fallback），以及 OPENCLAW_LIVE_GEMINI_KEY（单个覆盖）
  • 示例模型：google/gemini-3.1-pro-preview、google/gemini-3-flash-preview
  • 兼容性：旧版 OpenClaw 配置使用的 google/gemini-3.1-flash-preview 会被规范化为 google/gemini-3-flash-preview
  • CLI：openclaw onboard --auth-choice gemini-api-key

Google Vertex 和 Gemini CLI ​

  • Provider：google-vertex、google-gemini-cli
  • 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
  • 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。部分用户报告使用第三方客户端后 Google 账号受限。请查阅 Google 条款，建议使用非关键账号。
  • Gemini CLI OAuth 作为内置 google 插件的一部分提供：
    • 启用：openclaw plugins enable google
    • 登录：openclaw models auth login --provider google-gemini-cli --set-default
    • 注意：无需将 client id 或 secret 粘贴到 openclaw.json，CLI 登录流程会在 gateway 主机的 auth profile 中存储 token。

Z.AI（GLM） ​

  • Provider：zai
  • 认证：ZAI_API_KEY
  • 示例模型：zai/glm-5
  • CLI：openclaw onboard --auth-choice zai-api-key
    • 别名：z.ai/* 和 z-ai/* 会规范化为 zai/*

Vercel AI Gateway ​

  • Provider：vercel-ai-gateway
  • 认证：AI_GATEWAY_API_KEY
  • 示例模型：vercel-ai-gateway/anthropic/claude-opus-4.6
  • CLI：openclaw onboard --auth-choice ai-gateway-api-key

Kilo Gateway ​

  • Provider：kilocode
  • 认证：KILOCODE_API_KEY
  • 示例模型：kilocode/anthropic/claude-opus-4.6
  • CLI：openclaw onboard --kilocode-api-key <key>
  • Base URL：https://api.kilo.ai/api/gateway/
  • 扩展内置目录包含 GLM-5 Free、MiniMax M2.5 Free、GPT-5.2、Gemini 3 Pro Preview、Gemini 3 Flash Preview、Grok Code Fast 1 和 Kimi K2.5。

设置详情参见 /openclaw/providers/kilocode（如有）。

其他内置 Provider 插件 ​

  • OpenRouter：openrouter（OPENROUTER_API_KEY）
    • 示例模型：openrouter/anthropic/claude-sonnet-4-6
  • Kilo Gateway：kilocode（KILOCODE_API_KEY）
    • 示例模型：kilocode/anthropic/claude-opus-4.6
  • MiniMax：minimax（MINIMAX_API_KEY）
  • Moonshot：moonshot（MOONSHOT_API_KEY）
  • Kimi Coding：kimi-coding（KIMI_API_KEY 或 KIMICODE_API_KEY）
  • Qianfan：qianfan（QIANFAN_API_KEY）
  • Model Studio：modelstudio（MODELSTUDIO_API_KEY）
  • NVIDIA：nvidia（NVIDIA_API_KEY）
  • Together：together（TOGETHER_API_KEY）
  • Venice：venice（VENICE_API_KEY）
  • Xiaomi：xiaomi（XIAOMI_API_KEY）
  • Vercel AI Gateway：vercel-ai-gateway（AI_GATEWAY_API_KEY）
  • Hugging Face Inference：huggingface（HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN）
  • Cloudflare AI Gateway：cloudflare-ai-gateway（CLOUDFLARE_AI_GATEWAY_API_KEY）
  • Volcengine：volcengine（VOLCANO_ENGINE_API_KEY）
  • BytePlus：byteplus（BYTEPLUS_API_KEY）
  • xAI：xai（XAI_API_KEY）
  • Mistral：mistral（MISTRAL_API_KEY）
    • 示例模型：mistral/mistral-large-latest
    • CLI：openclaw onboard --auth-choice mistral-api-key
  • Groq：groq（GROQ_API_KEY）
  • Cerebras：cerebras（CEREBRAS_API_KEY）
    • Cerebras 上的 GLM 模型使用 id zai-glm-4.7 和 zai-glm-4.6
    • OpenAI 兼容 base URL：https://api.cerebras.ai/v1
  • GitHub Copilot：github-copilot（COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN）
  • Hugging Face Inference 示例模型：huggingface/deepseek-ai/DeepSeek-R1；CLI：openclaw onboard --auth-choice huggingface-api-key

通过 models.providers 添加自定义 Provider ​

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

许多内置 provider 插件已发布默认目录。仅当你需要覆盖默认 base URL、headers 或模型列表时，才需要显式配置 models.providers.<id>。

Moonshot AI（Kimi） ​

Moonshot 使用 OpenAI 兼容端点，以自定义 provider 方式配置：

  • Provider：moonshot
  • 认证：MOONSHOT_API_KEY
  • 示例模型：moonshot/kimi-k2.5

Kimi K2 model ID：

  • moonshot/kimi-k2.5
  • moonshot/kimi-k2-0905-preview
  • moonshot/kimi-k2-turbo-preview
  • moonshot/kimi-k2-thinking
  • moonshot/kimi-k2-thinking-turbo
json5
{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.5" } },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.5", name: "Kimi K2.5" }],
      },
    },
  },
}

Kimi Coding ​

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

  • Provider：kimi-coding
  • 认证：KIMI_API_KEY
  • 示例模型：kimi-coding/k2p5
json5
{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: { model: { primary: "kimi-coding/k2p5" } },
  },
}

火山引擎（Doubao） ​

火山引擎提供国内 Doubao 和其他模型的访问。

  • Provider：volcengine（编程：volcengine-plan）
  • 认证：VOLCANO_ENGINE_API_KEY
  • 示例模型：volcengine/doubao-seed-1-8-251228
  • CLI：openclaw onboard --auth-choice volcengine-api-key
json5
{
  agents: {
    defaults: { model: { primary: "volcengine/doubao-seed-1-8-251228" } },
  },
}

可用模型：

  • volcengine/doubao-seed-1-8-251228（Doubao 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：byteplus（编程：byteplus-plan）
  • 认证：BYTEPLUS_API_KEY
  • 示例模型：byteplus/seed-1-8-251228
  • CLI：openclaw onboard --auth-choice byteplus-api-key
json5
{
  agents: {
    defaults: { model: { primary: "byteplus/seed-1-8-251228" } },
  },
}

可用模型：

  • 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：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（Anthropic 兼容）：--auth-choice minimax-api
  • 认证：MINIMAX_API_KEY

Ollama ​

Ollama 作为内置 provider 插件提供，使用 Ollama 原生 API：

bash
# 安装 Ollama，然后拉取模型：
ollama pull llama3.3
json5
{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}

Ollama 在设置 OLLAMA_API_KEY 后自动在 http://127.0.0.1:11434 本地探测，内置 provider 插件会将 Ollama 直接添加到 openclaw onboard 和模型选择器。

vLLM ​

vLLM 作为内置 provider 插件，用于本地/自托管 OpenAI 兼容服务器：

  • Provider：vllm
  • 认证：可选（取决于服务器配置）
  • 默认 base URL：http://127.0.0.1:8000/v1

本地自动发现（任意值均可，若服务器不要求认证）：

bash
export VLLM_API_KEY="vllm-local"

然后设置模型（将以下 ID 替换为 /v1/models 返回的实际 ID）：

json5
{
  agents: {
    defaults: { model: { primary: "vllm/your-model-id" } },
  },
}

SGLang ​

SGLang 作为内置 provider 插件，用于高性能自托管 OpenAI 兼容服务器：

  • Provider：sglang
  • 认证：可选（取决于服务器配置）
  • 默认 base URL：http://127.0.0.1:30000/v1

本地自动发现：

bash
export SGLANG_API_KEY="sglang-local"
json5
{
  agents: {
    defaults: { model: { primary: "sglang/your-model-id" } },
  },
}

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

示例（OpenAI 兼容）：

json5
{
  agents: {
    defaults: {
      model: { primary: "lmstudio/minimax-m2.5-gs32" },
      models: { "lmstudio/minimax-m2.5-gs32": { alias: "Minimax" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "LMSTUDIO_KEY",
        api: "openai-completions",
        models: [
          {
            id: "minimax-m2.5-gs32",
            name: "MiniMax M2.5",
            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
  • 建议：显式设置与代理/模型限制相匹配的值。
  • 对于非原生端点（任何 host 不是 api.openai.com 且 baseUrl 非空）使用 api: "openai-completions" 时，OpenClaw 会强制 compat.supportsDeveloperRole: false 以避免 provider 400 错误。
  • 若 baseUrl 为空/省略，OpenClaw 保持默认 OpenAI 行为（解析到 api.openai.com）。

CLI 示例 ​

养好龙虾第一步：跑 openclaw onboard，按提示选 provider，三分钟搞定。

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

完整配置示例参见 /openclaw/gateway/index。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策