4.2 模型供应商接入与认证方式

在第二章中，openclaw onboard 向导已经帮你完成了内置供应商的密钥绑定，模型已经可以调用。本节的目标不是重复“接入”，而是讲清楚三件事：什么时候需要显式写 models.providers、什么时候不需要；密钥如何安全注入与轮换；以及如何用标准化命令验收接入状态。

4.2.1 三条路径：你真的需要 models.providers 吗？

OpenClaw 的内置供应商（OpenAI、Anthropic、Moonshot 等）已经发布了默认的模型目录（default catalog）。多数内置 provider 在通过 openclaw onboard 完成认证后，密钥会写入 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json，通常无需手动编写 models.providers；但也要注意，部分 provider / onboarding 流程仍可能把 provider 配置同步写入 openclaw.json。

更准确地说，只有在以下情况下你通常需要显式写 models.providers：

覆盖内置供应商的默认行为：需要自定义 baseURL、请求头或模型列表时。
接入自定义/自托管供应商：如自建代理或自托管端点；OpenRouter、Ollama 已有 provider 文档/插件路径，通常只有在定制端点或模型目录时才需要手写 models.providers。

一个常见误区是把多凭据轮换写进 models.providers。灰度发布、profile 顺序或多 key 候选应走 auth profiles 与 auth.order；只有 provider 明确支持的静态凭据环境变量才适合直接依赖环境注入（详见 4.2.5）。

换句话说，对大多数用户而言，onboard 完成后只需要在 agents.defaults.model 中指定模型标识即可：

{
  // 内置供应商已通过 onboard 认证，无需 models.providers
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-5.5",
      },
    },
  },
}

模型标识统一使用 provider/model 格式，斜杠前的 provider 来自内置/插件模型目录或显式 models.providers 自定义 provider；auth profiles 与环境变量只提供认证材料，不注册 provider。需要特别注意的是：provider path 与运行时不是同一层概念。OpenAI agent 模型统一使用 openai/* 模型引用；ChatGPT/Codex 订阅 OAuth 通过 Codex/OpenAI auth profile 与运行时表达，旧配置中的 openai-codex/* 模型引用应使用 openclaw doctor --fix 迁移到 openai/*。常见的命名形态（以下名称仅为格式示例，实际可用模型以 openclaw models list、openclaw models status --probe 和各供应商官方目录为准）：

openai/gpt-5.4、openai/gpt-5.4-pro
openai/gpt-5.5（可配合 Codex 订阅 OAuth 或 OpenAI API Key）
anthropic/claude-sonnet-4-6、anthropic/claude-opus-4-6
anthropic-vertex/claude-sonnet-4-6（通过 Google Vertex AI 调用 Claude）
moonshot/kimi-k2.6（moonshotai 是历史/兼容别名）
zai/glm-5
chutes/<模型名>（Chutes 平台，支持 OAuth 和 API Key 两种认证）
xai/grok-4.3；若使用 Grok 4.20 beta，应写完整 beta 模型 ID，例如 xai/grok-4.20-beta-latest-reasoning

4.2.2 需要显式配置的场景与示例

以下示例面向确实需要 models.providers 的场景：自定义 provider、代理后的 OpenAI-compatible 端点、或需要显式维护模型目录的部署。如果你使用的是内置供应商且 onboard 已完成认证，可直接跳到 4.2.4 了解密钥注入的高阶形式。

1. 自定义代理 provider

当需要将模型请求走自建代理或 OpenAI-compatible 端点时，models.providers.<id> 至少要提供 baseUrl 和 models，并按实际后端选择 api：

{
  models: {
    providers: {
      "custom-proxy": {
        baseUrl: "https://my-proxy.internal/v1",
        apiKey: "${CUSTOM_PROXY_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "team-fast",
            name: "Team Fast Model",
            input: ["text"],
            contextWindow: 128000,
            contextTokens: 96000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },

  agents: {
    defaults: {
      model: {
        primary: "custom-proxy/team-fast",
      },
    },
  },
}

[!NOTE] 如果只是想更换内置供应商的密钥，不要用只有 apiKey 的 models.providers 覆盖。优先使用 onboarding / models auth 写入 auth profiles，或使用当前 provider 支持的环境变量。

2. Anthropic Vertex（通过 Google Cloud Vertex AI 调用 Claude）

认证方式：GCP 服务账号或 Application Default Credentials 常用模型标识应以你当前版本的 openclaw models list、openclaw models status --probe 输出和 Anthropic / Vertex 官方目录为准，不建议在文档里长期写死具体快照名。

{
  // 认证走 GCP Application Default Credentials、服务账号或 onboarding 生成的认证档案；
  // 不要把 region/projectId 当作仅含元数据的 models.providers 覆盖来写。
  agents: {
    defaults: {
      model: {
        primary: "anthropic-vertex/<当前可用的 Claude 模型标识>",
      },
    },
  },
}

[!TIP] Anthropic Vertex 适用于已有 GCP 基础设施的团队：流量走 Google 内网，可利用 GCP 的 IAM 权限体系和 VPC 网络策略，且计费合并到 GCP 账单中。

3. 自托管 Ollama

baseUrl：http://localhost:11434 常用模型标识：ollama/llama2、ollama/mistral 等（取决于本地部署）

[!WARNING] 不要使用 http://localhost:11434/v1 这样的 OpenAI-compatible 路径——官方明确指出这会破坏工具调用，让模型把工具 JSON 当普通文本输出。应直接使用 Ollama 原生 API 地址。

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://localhost:11434",
        apiKey: "ollama-local",
        api: "ollama",
        models: [
          {
            id: "mistral",
            name: "Mistral",
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 8192,
            maxTokens: 8192,
          },
        ],
      },
    },
  },

  agents: {
    defaults: {
      model: {
        primary: "ollama/mistral",
      },
    },
  },
}

4.2.3 OpenRouter

baseUrl：https://openrouter.ai/api/v1 API 适配器：openai-completions 环境变量：OPENROUTER_API_KEY 常用模型标识示例：openrouter/<provider>/<model>。具体模型名应以 OpenRouter 当前目录与本地 models list / models status --probe 输出为准。

环境变量设置：

export OPENROUTER_API_KEY="sk-or-xxx..."

配置示例（OpenRouter 已有 provider 插件和 onboarding 入口，通常只需要认证与模型选择；不要写只有 apiKey/baseUrl、没有 models 的 models.providers.openrouter 覆盖）：

{
  agents: {
    defaults: {
      model: {
        primary: "openrouter/<provider>/<model>",
      },
    },
  },
}

4.2.4 密钥注入：${} 插值与 SecretRef 凭据管线

配置支持在字符串字段里写 ${VAR_NAME}，或是使用 SecretRef 对象。推荐把密钥放进环境变量或密钥系统，在配置里不写任何明文：这样配置文件可入库、可审计、可复现，且避免了密钥意外落盘。

1. 基本形式：${} 环境变量插值

内置供应商优先通过环境变量、onboarding 或 models auth 进入 auth profiles；这里展示最常见的环境变量形式：

# 方式 A：直接 export
export OPENAI_API_KEY="..."

# 方式 B：写入 ~/.openclaw/.env 或项目目录下的 .env
OPENAI_API_KEY="..."

[!NOTE] OpenClaw 在启动时会遵循优先级读取环境变量，规则为：进程真实环境变量 > 当前目录 .env > ~/.openclaw/.env。注意：.env 文件中的定义不会覆盖已经存在于进程中的同名环境变量。

2. 高阶形式：使用 SecretRef 对接统一凭据管线

针对生产级部署，OpenClaw 提供了统一的 Secrets 管线。你不仅限于使用环境变量，而是可以使用 SecretRef 形式安全加载，这使你可以对接各类 secrets provider，并结合 openclaw secrets 体系进行管理与依赖性审计。

SecretRef 只适用于当前 schema 明确支持的静态凭据字段；OAuth profile material 等运行期认证材料不接受 SecretRef。写入前建议用 openclaw config set --dry-run 或 openclaw security audit 验证。SecretRef 支持三种 source 类型：

"env"：从环境变量读取（最常用）
"file"：从文件路径读取内容
"exec"：执行命令并取其标准输出

{
  secrets: {
    providers: {
      default: { source: "env" },
    },
  },
  models: {
    providers: {
      "custom-proxy": {
        baseUrl: "https://my-proxy.internal/v1",
        api: "openai-completions",
        // 方式 1：从环境变量读取
        apiKey: { source: "env", provider: "default", id: "CUSTOM_PROXY_API_KEY" },
        models: [
          {
            id: "team-fast",
            name: "Team Fast Model",
            input: ["text"],
            contextWindow: 128000,
            contextTokens: 96000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

[!WARNING] 配置自写的落盘风险：如果系统允许外部（如 AI）修改配置文件或执行了不当的同步行为，普通的内联 ${VAR_NAME} 配置有极低概率在重写时被错误解引用而变成明文写回磁盘。而使用 SecretRef 对象语义则能严格隔离数据链路，有效避免误操作。

注意：

结构化日志与诊断输出不打印明文密钥。
验证时请使用 openclaw security audit、models status 和必要时的 models status --probe。

4.2.5 多密钥与认证档案：为轮换与灰度预留结构

当前 OpenClaw 不使用 models.providers.*.keys / keyId 作为运行时多密钥接口。同一 provider 的多凭据应通过 auth profiles、auth.order、或 provider 支持的环境变量 key 列表表达。建议把“新增凭据”与“切换默认顺序”拆成两个动作：先新增并小流量验证，再调整 auth.order 或环境变量顺序，最后吊销旧密钥。

配置示例（认证档案顺序，只保存路由元数据，密钥仍在 auth-profiles.json 或 SecretRef 中）：

{
  auth: {
    profiles: {
      "openai:primary": {
        provider: "openai",
        mode: "api_key",
      },
      "openai:secondary": {
        provider: "openai",
        mode: "api_key",
      },
    },
    order: {
      openai: ["openai:primary", "openai:secondary"],
    },
  },
}

不要把 <PROVIDER>_API_KEYS、<PROVIDER>_API_KEY_1 或 OPENCLAW_LIVE_<PROVIDER>_KEY 这类名字当作所有 provider 都支持的通用候选池接口。生产轮换更稳的路径是新增 auth profile、调整 auth.order，并用 provider 文档明确支持的环境变量或 SecretRef 注入静态凭据。轮换建议：不要在故障窗口直接“替换同一个环境变量的值”，那会让排障证据变得不可追溯；更稳的是新增一把凭据、调整 profile 顺序、保留旧凭据一段观测窗口后再回收。

4.2.6 接入验收：用 models status 做可观测验证

配置完成后用一组最小命令做验收（只看结果，不靠感觉）：

openclaw doctor
openclaw models status
openclaw models status --probe
openclaw status --deep

doctor 失败：先修复“配置可读”与“运行依赖”，不要先调提示词或工作流。
models status 显示异常：优先检查认证档案是否缺失、OAuth 是否过期、环境变量是否存在、${} 占位符的变量名是否拼对。
models status --probe 失败：再检查 provider live auth、上游连通性、模型名是否仍可用。
status --deep 中看不到预期的 provider/model：优先回看层级（models.providers 与 agents.defaults.model 是否写在正确位置）。

4.2.7 速率限制与配额管理

上游模型供应商通常对 API 调用实施速率限制（rate limit），OpenClaw 需要妥善处理这些限制，避免请求失败或服务中断。

上游 429 响应处理

当 OpenClaw 收到上游供应商返回的 HTTP 429（Too Many Requests）时，当前主路径不是在同一个 key 上按 1s/2s/4s 长时间阻塞等待，而是把对应 auth profile 标记为冷却，再按预算尝试同 provider 的下一个 profile；预算耗尽或错误类型适合切换时，进入模型 fallback 链路（见 4.4）。

默认冷却梯度通常是 30 秒、60 秒，之后最高到 5 分钟；具体窗口由 auth.cooldowns.*、错误分类和 profile 状态共同决定。结构化日志会记录冷却、profile rotation 与 fallback 决策，便于事后分析与告警配置。

配置速率限制策略

当前公开配置面不提供 models.providers.*.rateLimit 这类本地主动限流字段。模型侧限流治理应分成三层处理：

OpenClaw 内部：依赖 auth-profile 冷却、同 provider profile rotation、auth.cooldowns.rateLimitedProfileRotations 与模型 fallback。
供应商侧：设置供应商账单限额、项目配额、组织级 rate limit 或 key 级权限。
入口侧：在反向代理、队列、插件或业务网关中做请求整形、排队与熔断。

具体冷却与轮换由 auth.cooldowns.* 配置和错误类型决定；默认 overloaded / rate-limit 路径只做有限次数的同 provider profile rotation，预算耗尽后可进入模型 fallback 链路。

多供应商 Fallback 规避单点限流

最稳健的做法是为关键服务配置多个供应商，在单一供应商频繁限流时自动切换到次要供应商。见 4.4 关于 fallback 链路的详细说明。

{
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-5.5",
        fallbacks: [
          "anthropic/claude-sonnet-4-6",
        ],
      },
    },
  },
}

如果你走的是 ChatGPT/Codex 订阅 OAuth，当前配置仍应使用 openai/* 模型引用，由 Codex/OpenAI auth profile 与运行时表达订阅认证；历史配置中的 openai-codex/* 模型引用属于兼容路径，应通过 openclaw doctor --fix 迁移。关键不是复用某段历史配置，而是要和当前模型目录、auth profile 与运行时选择保持一致。这样即便主链路因限流而暂时不可用，请求也能自动降级到次级模型或备用供应商，保证服务连续性。

踩坑实录：环境变量“明明设了却读不到”
一个常见的部署陷阱：在 .bashrc 中 export 了 ANTHROPIC_API_KEY，但 OpenClaw 以 systemd 服务启动时读不到。原因是 systemd 不会加载用户 shell profile。解决方案：在 systemd unit 文件中用 EnvironmentFile=/etc/openclaw/env 显式指定，或使用 openclaw secrets configure 把密钥写入 SecretRef 体系。

上一页4.1 openclaw.json 结构与配置优先级下一页4.3 模型选择与默认策略

最后更新于 1个月前