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

本节围绕 models.providers 配置展开，重点探讨供应商（provider）与模型（model）的命名规范及关联机制；通过 ${VAR_NAME} 占位符安全注入 API 密钥以避免明文落盘的最佳实践；以及利用多密钥与 keyId 实现平滑轮换与灰度发布的支持机制。最后，提供一套标准化的验收命令，确保接入的模型不仅高可用且可灵活替换。

4.2.1 概念拆分：provider 与 model 的层级

在 OpenClaw 里，供应商配置集中在 models.providers：它解决”怎么连、用什么凭据连”。注意：

内置供应商（OpenAI、Anthropic、Moonshot 等）的密钥通常由 openclaw onboard 向导写入 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json，无需在 openclaw.json 中手动配置。
自定义/自托管供应商（如 OpenRouter 或自建代理）才需要在 models.providers 里声明连接信息与 baseURL。

真正的调用目标由 provider/model 形式的模型标识决定，例如：openai/gpt-5.2、anthropic/claude-sonnet-4-6。

两者的关联只有一条规则：模型标识里斜杠前的 provider，必须能在 models.providers 里找到同名的 provider 配置（自定义 provider）或已存入认证档案（内置 provider）。

一个最小示例（把”接入”与”选用”放在同一张图里）：

{
  models: {
    providers: {
      openai: { apiKey: “${OPENAI_API_KEY}” },
      anthropic: { apiKey: “${ANTHROPIC_API_KEY}” },
    },
  },

  agents: {
    defaults: {
      model: {
        primary: “openai/gpt-5.2”,
      },
    },
  },
}

常见的命名形态（用于帮助你理解层级，不要求你一次记住所有模型名；以下名称仅为格式示例，实际可用模型以各供应商官方发布为准）：

openai/gpt-5.2、openai/gpt-5-mini
anthropic/claude-sonnet-4-6
moonshot/kimi-k2.5
minimax/MiniMax-M2.5
zai/glm-5

4.2.1a 主流供应商快速接入参考

下列供应商是最常见的选择，每个都提供完整的接入配置示例与环境变量设置方法。选择与你的业务契合的供应商，按对应步骤配置即可。

1. Anthropic（Claude）

环境变量：ANTHROPIC_API_KEY 常用模型标识：anthropic/claude-sonnet-4-6、anthropic/claude-opus-4-6、anthropic/claude-haiku-4-5

环境变量设置：

export ANTHROPIC_API_KEY=”sk-ant-xxx...”

配置示例：

{
  models: {
    providers: {
      anthropic: {
        apiKey: “${ANTHROPIC_API_KEY}”,
      },
    },
  },

  agents: {
    defaults: {
      model: {
        primary: “anthropic/claude-sonnet-4-6”,
      },
    },
  },
}

2. OpenAI

环境变量：OPENAI_API_KEY 常用模型标识：openai/gpt-5.2、openai/gpt-5-mini

环境变量设置：

export OPENAI_API_KEY=”sk-proj-xxx...”

配置示例：

{
  models: {
    providers: {
      openai: {
        apiKey: “${OPENAI_API_KEY}”,
      },
    },
  },

  agents: {
    defaults: {
      model: {
        primary: “openai/gpt-5.2”,
      },
    },
  },
}

3. 自托管 Ollama

baseUrl：http://localhost:11434/v1 API 适配器：openai-completions 常用模型标识：ollama/llama2、ollama/mistral 等（取决于本地部署）

配置示例：

{
  models: {
    providers: {
      ollama: {
        baseUrl: “http://localhost:11434/v1”,
        apiAdapter: “openai-completions”,
      },
    },
  },

  agents: {
    defaults: {
      model: {
        primary: “ollama/mistral”,
      },
    },
  },
}

4. OpenRouter

baseUrl：https://openrouter.ai/api/v1 API 适配器：openai-completions 环境变量：OPENROUTER_API_KEY 常用模型标识：openrouter/anthropic/claude-sonnet-4-6、openrouter/openai/gpt-5.2 等

环境变量设置：

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

配置示例：

{
  models: {
    providers: {
      openrouter: {
        baseUrl: “https://openrouter.ai/api/v1”,
        apiAdapter: “openai-completions”,
        apiKey: “${OPENROUTER_API_KEY}”,
      },
    },
  },

  agents: {
    defaults: {
      model: {
        primary: “openrouter/anthropic/claude-sonnet-4-6”,
      },
    },
  },
}

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

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

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

配置示例：

{
  models: {
    providers: {
      openai: {
        apiKey: "${OPENAI_API_KEY}",
      }
    },
  },
}

本地设置环境变量或写入 .env 文件：


# 方式 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 支持三种 source 类型：

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

{
  models: {
    providers: {
      openai: {
        // 方式 1：从环境变量读取
        apiKey: { source: "env", id: "OPENAI_API_KEY" },
      },
      anthropic: {
        // 方式 2：从文件读取
        apiKey: { source: "file", id: "/run/secrets/anthropic_key" },
      },
      custom: {
        // 方式 3：从命令执行结果读取
        apiKey: { source: "exec", id: "vault kv get -field=key secret/custom" },
      },
    },
  },
}

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

注意：

结构化日志与诊断输出不打印明文密钥。
验证时请使用 openclaw security audit 或 models status --check。

4.2.3 多密钥与 keyId：为轮换与灰度预留结构

同一 provider 可以配置多把密钥，用 keyId 选择默认密钥。建议把“新增密钥”与“切换默认”拆成两个动作：先新增并小流量验证，再切换 keyId，最后吊销旧密钥。

配置示例（多密钥）：

{
  models: {
    providers: {
      openai: {
        keys: {
          primary: {
            apiKey: "${OPENAI_API_KEY_PRIMARY}",
          },
          secondary: {
            apiKey: "${OPENAI_API_KEY_SECONDARY}",
          },
        },
        keyId: "primary",
      },
    },
  },
}

轮换建议：不要在故障窗口直接“替换同一个环境变量的值”，那会让排障证据变得不可追溯；更稳的是新增一把钥匙、切换 keyId、保留旧钥匙一段观测窗口后再回收。

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

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

openclaw doctor
openclaw models status --check
openclaw status --deep

doctor 失败：先修复”配置可读”与”运行依赖”，不要先调提示词或工作流。
models status --check 失败：优先检查环境变量是否存在、${} 占位符的变量名是否拼对、provider 配置是否写在 models.providers 下。
status --deep 中看不到预期的 provider/model：优先回看层级（models.providers 与 agents.defaults.model 是否写在正确位置）。

4.2.5 速率限制与配额管理

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

上游 429 响应处理

当 OpenClaw 收到上游供应商返回的 HTTP 429（Too Many Requests）时，采用指数退避（exponential backoff）与冷却窗口（cooldown window）机制：

首次 429 响应：立即进入冷却期，第一次重试等待 1 秒。
重试失败再收 429：等待时间翻倍（1s → 2s → 4s → 8s）。
达到最大重试次数或冷却时间上限（通常为 60 秒）后，将请求标记为失败并触发 fallback 链路（见 4.4）。

结构化日志会记录每次 429 及重试动作，便于事后分析与告警配置。

配置速率限制策略

某些供应商与自托管方案支持在 models.providers 中配置速率限制参数。配置示例：

{
  models: {
    providers: {
      openai: {
        apiKey: “${OPENAI_API_KEY}”,
        rateLimit: {
          requestsPerMinute: 60,
          tokensPerMinute: 100000,
        },
      },
      ollama: {
        baseUrl: “http://localhost:11434/v1”,
        apiAdapter: “openai-completions”,
        rateLimit: {
          requestsPerSecond: 10,
        },
      },
    },
  },
}

这些限制告诉 OpenClaw 在本地主动控制请求频率，防止触发上游 429 前就自我限流。

多供应商 Fallback 规避单点限流

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

{
  agents: {
    defaults: {
      model: {
        primary: “openai/gpt-5.2”,
        fallbacks: [
          “anthropic/claude-sonnet-4-6”,
          “openrouter/openai/gpt-5.2”,
        ],
      },
    },
  },
}

这样即便 OpenAI 因限流而暂时不可用，请求也能自动降级到 Anthropic 或 OpenRouter，保证服务连续性。

💡 踩坑实录：环境变量 “明明设了却读不到”
一个常见的部署陷阱：在 .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小时前

hashtag4.2.1 概念拆分：provider 与 model 的层级

hashtag4.2.1a 主流供应商快速接入参考

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

hashtag4.2.3 多密钥与 keyId：为轮换与灰度预留结构

hashtag4.2.4 接入验收：用 models status 做可观测验证

hashtag4.2.5 速率限制与配额管理

4.2.1 概念拆分：provider 与 model 的层级

4.2.1a 主流供应商快速接入参考

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

4.2.3 多密钥与 keyId：为轮换与灰度预留结构

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

4.2.5 速率限制与配额管理