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-5

• moonshot/kimi-k2.5

• minimax/MiniMax-M2.5

• zai/glm-5

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 体系进行管理与依赖性审计。

{
  models: {
    providers: {
      openai: {
        apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" }
      },
    },
  },
}

[!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 是否写在正确位置）。