> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/04_config_models/4.2_provider_access.md).

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

在[第二章](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/02_setup/2.3_onboarding.md)中，`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` 中指定模型标识即可：

```javascript
{
  // 内置供应商已通过 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`：

```javascript
{
  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 官方目录为准，不建议在文档里长期写死具体快照名。

```javascript
{
  // 认证走 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 地址。

```javascript
{
  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` 输出为准。

环境变量设置：

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

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

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

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

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

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

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

```bash
# 方式 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"`：执行命令并取其标准输出

```javascript
{
  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 中）：

```javascript
{
  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 做可观测验证

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

```bash
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` 这类本地主动限流字段。模型侧限流治理应分成三层处理：

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

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

**多供应商 Fallback 规避单点限流**

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

```javascript
{
  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 体系。