OpenClaw 认证与模型解析机制深度解析

各位小伙伴们，大家好！我是小学子 👨‍🏫 今天要带大家深入了解 OpenClaw 的两大核心机制——认证系统和模型解析。这两个机制就像 OpenClaw 的大脑和心脏，保证了整个系统能够安全、稳定地运行。准备好了吗？让我们开始吧！

---

🔐 第一部分：认证系统——谁可以使用 OpenClaw？

什么是 Auth Profile？

在 OpenClaw 中，Auth Profile（认证配置文件） 是管理所有认证凭证的核心机制。它支持两种凭证类型：

• API Key 认证：最简单的方式，直接使用 API 密钥访问模型服务
• OAuth 认证：支持多账户登录，适合团队协作场景

凭证存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 文件中。注意啦，配置中的 auth.profiles 和 auth.order 只是元数据和路由信息，真正的密钥不会保存在这里。

认证配置文件示例

{
  // 模型选择
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
    },
  },
  
  // 认证配置
  auth: {
    profiles: [
      { provider: "anthropic", id: "default" },
      { provider: "openai", id: "default" },
    ],
    order: {
      anthropic: ["anthropic:default"],
      openai: ["openai:default"],
    },
  },
}

Profile ID 的那些事儿

OAuth 登录会创建独立的 Profile，方便多账户共存：

• 默认格式：provider:default（没有邮箱时使用）
• 带邮箱格式：provider:user@example.com（例如 google-antigravity:user@gmail.com）

认证轮换机制

当一个 Provider 有多个认证配置时，OpenClaw 会按照以下顺序选择：

1. 显式配置：优先使用 auth.order[provider] 中指定的顺序
2. 配置好的 profiles：从 auth.profiles 中筛选
3. 存储的 profiles：从 auth-profiles.json 中读取

如果没有任何配置，OpenClaw 会采用轮询策略：

• 优先级：OAuth 凭证优先于 API Key
• 次要标准：按最后使用时间排序（最早使用的优先）

冷却时间（Cooldowns）

当认证失败或遇到速率限制时，OpenClaw 会将 Profile 标记为冷却状态，并使用指数退避策略：

失败次数	冷却时间
第1次	1 分钟
第2次	5 分钟
第3次	25 分钟
第4次+	1 小时（上限）

{
  "usageStats": {
    "anthropic:default": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

计费失败处理

如果遇到"余额不足"等计费错误，OpenClaw 会将 Profile 标记为禁用状态，冷却时间更长：

• 初始冷却：5 小时
• 每次失败：翻倍
• 上限：24 小时
• 重置条件：连续 24 小时无失败

---

🤖 第二部分：模型解析机制——OpenClaw 如何选择模型？

模型引用格式

OpenClaw 使用统一的模型引用格式：provider/model

例如：

• anthropic/claude-opus-4-6
• openai/gpt-5.1-codex
• google/gemini-3-pro-preview

Model Registry（模型注册表）

通过配置 agents.defaults.models，可以定义模型目录和别名：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

⚠️ 重要提示：如果设置了 agents.defaults.models，它就变成了允许列表。用户只能从这个列表中选择模型，否则会收到 “Model is not allowed” 的错误提示。

模型选择流程

OpenClaw 按照以下优先级选择模型：

1. 主模型：agents.defaults.model.primary
2. 备用模型：按 agents.defaults.model.fallbacks 顺序依次尝试
3. Provider 认证轮换：在同一个 Provider 内轮换不同的认证凭证

图像模型路由

如果主模型不支持图像，OpenClaw 会自动切换到 agents.defaults.imageModel：

{
  agents: {
    defaults: {
      imageModel: {
        primary: "openai/gpt-5.2",
        fallbacks: ["anthropic/claude-sonnet-4-5"],
      },
    },
  },
}

在对话中切换模型

用户可以通过 /model 命令实时切换模型：

/model              # 查看当前模型
/model list         # 列出可用模型
/model 3            # 选择第3个模型
/model openai/gpt-5.2  # 直接指定模型
/model status       # 查看详细状态

---

🔧 第三部分：Provider 参数配置

内置 Provider

OpenClaw 内置了众多模型 Provider，无需额外配置即可使用：

Provider	认证方式	示例模型
openai	OPENAI_API_KEY	openai/gpt-5.1-codex
anthropic	ANTHROPIC_API_KEY	anthropic/claude-opus-4-6
opencode	OPENCODE_API_KEY	opencode/claude-opus-4-6
google	GEMINI_API_KEY	google/gemini-3-pro-preview
zai	ZAI_API_KEY	zai/glm-5
openrouter	OPENROUTER_API_KEY	openrouter/anthropic/claude-sonnet-4-5

自定义 Provider

可以通过 models.providers 添加自定义 Provider：

{
  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" }
        ],
      },
    },
  },
}

API Key 轮换

对于支持多个 API Key 的 Provider，OpenClaw 提供自动轮换功能：

# 方式1：环境变量列表
export OPENAI_API_KEYS="key1,key2,key3"

# 方式2：编号变量
export OPENAI_API_KEY_1="key1"
export OPENAI_API_KEY_2="key2"

# 方式3：实时覆盖
export OPENCLAW_LIVE_OPENAI_KEY="override-key"

OpenClaw 会按照优先级选择 Key，只在遇到速率限制（429 错误）时才会轮换到下一个 Key。

---

📝 总结

今天我们学习了 OpenClaw 的两大核心机制：

1. 认证系统：通过 Auth Profile 管理 API Key 和 OAuth 凭证，支持多账户、轮换策略、冷却机制
2. 模型解析：统一的 provider/model 格式，灵活的 Model Registry，允许列表控制，自动故障转移

这两个机制相互配合，确保了 OpenClaw 能够：

• ✅ 安全地访问各种模型服务
• ✅ 在认证失败时自动恢复
• ✅ 灵活地在多个模型之间切换
• ✅ 支持复杂的生产环境需求

好啦，今天的课程就到这里！如果你有任何问题，欢迎随时问我哦～

---

参考来源：

• OpenClaw 官方文档：https://docs.openclaw.ai/
• Configuration 文档：https://docs.openclaw.ai/gateway/configuration
• Models CLI 文档：https://docs.openclaw.ai/concepts/models
• Model Failover 文档：https://docs.openclaw.ai/concepts/model-failover
• Model Providers 文档：https://docs.openclaw.ai/concepts/model-providers