小学子讲技术 - OpenClaw 认证与模型解析机制深度解析

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 会按照以下顺序选择：

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

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

冷却时间（Cooldowns）

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

{
"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 按照以下优先级选择模型：

图像模型路由

如果主模型不支持图像，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

可以通过 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 的两大核心机制：

这两个机制相互配合，确保了 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