认证（模型 Provider）

注意：本页面涵盖模型 Provider 认证（API Key、OAuth 和 legacy Anthropic setup-token）。关于 Gateway 连接认证（Token、密码、Trusted Proxy），见 配置 和 Trusted Proxy Auth。

OpenClaw 支持 OAuth 和 API Key 两种模型 Provider 认证方式。对于常驻 Gateway 主机，API Key 通常是最可预测的选择。

推荐配置（API Key，适用任意 Provider）

长期运行的 Gateway，从为你选择的 Provider 配置 API Key 开始：

1. 在 Provider 控制台创建 API Key。

2. 在 Gateway 主机上设置：

export <PROVIDER>_API_KEY="..."
openclaw models status

3. 如果 Gateway 运行在 systemd/launchd 下，建议放入 ~/.openclaw/.env：

cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF

重启 daemon，再验证：

openclaw models status
openclaw doctor

不想手动管理环境变量，用 openclaw onboard 引导配置。

Anthropic：Legacy Token 兼容性

Anthropic setup-token 认证在 OpenClaw 中仍作为 legacy/手动路径可用。Anthropic 已明确告知 OpenClaw 用户，OpenClaw 的 Claude-login 路径属于第三方 harness 使用，需要单独计费的 Extra Usage，不属于订阅计划限额。

最清晰的配置路径：使用 Anthropic API Key。如果必须保留订阅式 Anthropic 路径，预期 Anthropic 将其视为 Extra Usage 计费。

手动输入 Token（任意 Provider，写入 auth-profiles.json 并更新配置）：

openclaw models auth paste-token --provider openrouter

认证 Profile Ref 也支持静态凭据：

• api_key 凭据可使用 keyRef: { source, provider, id }
• token 凭据可使用 tokenRef: { source, provider, id }
• OAuth 模式的 Profile 不支持 SecretRef 凭据

自动化友好检查（过期/缺失时退出码 1，即将过期时 2）：

openclaw models status --check

实时认证探测：

openclaw models status --probe

多 Key 轮换（速率限制时自动切换）

部分 Provider 支持在 API 调用触发速率限制时自动切换备用 Key：

优先级顺序：

1. OPENCLAW_LIVE_<PROVIDER>_KEY（单一覆盖）
2. <PROVIDER>_API_KEYS
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_*

• Google Provider 额外支持 GOOGLE_API_KEY 作后备
• 相同 Key 去重
• 仅对速率限制错误重试（429、rate_limit、quota、resource exhausted 等）
• 非速率限制错误不会切换备用 Key
• 所有 Key 都失败时，返回最后一次失败的错误

控制使用哪个凭据

每会话（聊天命令）

/model <alias-or-id>@<profileId>

例如 anthropic:default、anthropic:work。

用 /model（或 /model list）查看简洁选择器，/model status 查看完整视图（候选 + 下一个 auth profile + Provider 端点详情）。

每 Agent（CLI override）

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

使用 --agent <id> 指定特定 agent，省略则使用默认 agent。

排查常见问题

"No credentials found"（未找到凭据）

在 Gateway 主机上配置 Anthropic API Key 或 legacy setup-token，然后重新检查：

openclaw models status

Token 即将/已经过期

运行 openclaw models status 确认哪个 Profile 正在过期。如果旧版 Claude CLI 状态残留，运行：

openclaw doctor --yes

Doctor 会将 anthropic:claude-cli 转换回 Anthropic token/OAuth Profile（如果凭据字节仍然存在），否则删除过期 Claude CLI 配置并给出下一步指引。

FAQ

Q：API Key 和 OAuth Token 有什么区别？ API Key 长期有效，适合服务端常驻 Gateway；OAuth Token 有过期时间，适合个人用户交互式使用。对于生产部署推荐 API Key。

Q：如何确认我的认证配置是否正确？ 运行 openclaw models status（概览）或 openclaw models status --probe（实时探测每个 Profile 的可用性）。

延伸阅读

• OAuth 配置
• Secrets 管理
• Gateway 配置
• Trusted Proxy Auth