OpenClaw Gateway 认证模型 Provider 时，推荐长期部署用 API Key，配置在网关主机环境变量或 ~/.openclaw/.env。Anthropic 现在支持复用本地 Claude CLI 登录作为首选路径，API Key 仍最可预测。使用 openclaw models status --probe 实时探测每个凭据可用性；--check 可自动化检查（过期退出码 1，即将过期 2）。多 Key 轮换只针对速率限制错误重试，非速率错误不切换。

OpenClaw 模型认证配置：API Key、OAuth 与 Token 用法及排查

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

OpenClaw 支持 OAuth 和 API Key 两种模型 Provider 认证方式。对于常驻 Gateway 主机，API Key 通常是确定性最高的选择。订阅/OAuth 流程也适用于对应账号模型的场景。

完整 OAuth 流程及存储布局见 OAuth 概念。

基于 SecretRef 的认证（env/file/exec provider）见 Secrets 管理。

models status --probe 使用的凭据资格/原因码规则见 Auth Credential Semantics。

推荐配置：API Key（任意 Provider）

长期运行的 Gateway，从创建所选 Provider 的 API Key 开始。

1. 在 Provider 控制台创建 API Key。
2. 将 Key 放到 Gateway 主机（运行 openclaw gateway 的机器）。

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

3. 如果 Gateway 运行在 systemd/launchd 下，建议放入 ~/.openclaw/.env 以供守护进程读取：

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

重启守护进程（或重启 Gateway 进程）后重新检查：

openclaw models status
openclaw doctor

如果不想手动管理环境变量，openclaw onboard 可以存储 API Key 供守护进程使用。

环境变量继承细节（env.shellEnv、~/.openclaw/.env、systemd/launchd）见 帮助。

Anthropic：Claude CLI 复用与 Token 兼容性

Anthropic setup-token 认证在 OpenClaw 中仍作为受支持的 Token 路径可用。Anthropic 官方已告知 OpenClaw 的 Claude CLI 使用再次允许，因此 OpenClaw 将 Claude CLI 复用和 claude -p 使用视为本集成下已批准的行为，除非 Anthropic 发布新政策。当主机上可用 Claude CLI 复用时，此路径现在是首选。

对于长期 Gateway 主机，Anthropic API Key 仍然是最确定的配置。如果想复用同一主机上已有的 Claude 登录，请在引导/配置中使用 Anthropic Claude CLI 路径。

Claude CLI 复用的推荐主机配置

# 在网关主机上执行
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

这是两步设置：

1. 在网关主机上先将 Claude Code 自身登录到 Anthropic。
2. 告诉 OpenClaw 将 Anthropic 模型选择切换到本地 claude-cli 后端，并存储匹配的 OpenClaw 认证 Profile。

如果 claude 不在 PATH 中，请先安装 Claude Code，或设置 agents.defaults.cliBackends.claude-cli.command 为实际二进制路径。

手动输入 Token（任意 Provider）

写入 auth-profiles.json 并更新配置：

openclaw models auth paste-token --provider openrouter

auth-profiles.json 仅存储凭据。标准结构为：

{
  "version": 1,
  "profiles": {
    "openrouter:default": {
      "type": "api_key",
      "provider": "openrouter",
      "key": "OPENROUTER_API_KEY"
    }
  }
}

OpenClaw 运行时期望 version + profiles 的标准结构。如果旧安装仍存在扁平文件如 { "openrouter": { "apiKey": "..." } }，运行 openclaw doctor --fix 将其重写为 openrouter:default 的 API-key profile；doctor 会在原文件旁保留 .legacy-flat.*.bak 副本。端点详情（如 baseUrl、api、模型 ID、headers、timeouts）属于 openclaw.json 或 models.json 的 models.providers.<id> 下，不应写在 auth-profiles.json 中。

外部认证路由（如 Bedrock auth: "aws-sdk"）也不是凭据。如需命名 Bedrock 路由，将 auth.profiles.<id>.mode: "aws-sdk" 写入 openclaw.json；不要在 auth-profiles.json 写入 type: "aws-sdk"。openclaw doctor --fix 会将旧版 AWS SDK 标记从凭据存储移动到配置元数据中。

Auth Profile Ref 也支持静态凭据：

• api_key 凭据可使用 keyRef: { source, provider, id }
• token 凭据可使用 tokenRef: { source, provider, id }
• OAuth 模式的 Profile 不支持 SecretRef 凭据；如果设置 auth.profiles.<id>.mode 为 "oauth"，对该 Profile 使用 SecretRef 的 keyRef/tokenRef 输入将被拒绝。

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

openclaw models status --check

实时认证探测：

openclaw models status --probe

注意：

• 探测行可以来自 Auth Profile、环境变量凭据或 models.json。
• 如果显式的 auth.order.<provider> 省略了某个存储的 Profile，探测会报告 excluded_by_auth_order 而不是尝试它。
• 如果存在认证但 OpenClaw 无法解析该 Provider 的可探测模型候选，探测报告 status: no_model。
• 速率限制冷却可以针对特定模型。一个 Profile 因一个模型冷却中，仍可用于同一 Provider 的其他模型。

可选的运维脚本（systemd/Termux）见 Auth monitoring scripts。

检查模型认证状态

openclaw models status
openclaw doctor

API Key 轮换行为（Gateway）

某些 Provider 支持在 API 调用触发 Provider 速率限制时自动使用备用 Key 重试请求。

优先级顺序：

• OPENCLAW_LIVE_<PROVIDER>_KEY（单一覆盖）

• <PROVIDER>_API_KEYS

• <PROVIDER>_API_KEY

• <PROVIDER>_API_KEY_*

• Google Provider 还包含 GOOGLE_API_KEY 作为额外后备。

• 相同 Key 列表在去重后使用。

• OpenClaw 仅对速率限制错误重试（例如 429、rate_limit、quota、resource exhausted、Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded）。

• 非速率限制错误不会切换备用 Key。

• 如果所有 Key 都失败，返回最后一次尝试的最终错误。

Gateway 运行时移除 Provider 认证

通过 Gateway 控制平面移除 Provider 认证时，OpenClaw 会删除该 Provider 保存的 Auth Profile，并中止其选定模型 Provider 与已移除 Provider 匹配的活动聊天或智能体运行。中止的运行会正常发出聊天取消和生命周期事件，stopReason: "auth-revoked"，以便连接的客户端显示运行因凭据被移除而停止。

删除保存的认证不会在 Provider 端撤销 Key。如需在 Provider 端失效，请到 Provider 控制台轮换或撤销 Key。

控制使用哪个凭据

每会话（聊天命令）

使用 /model &lt;alias-or-id&gt;@<profileId> 将当前会话固定到某个具体的 Provider 凭据（例如 profile Id: anthropic:default、anthropic:work）。

使用 /model（或 /model list）查看紧凑选择器；使用 /model status 查看完整视图（候选 + 下一个 Auth Profile，配置时的 Provider 端点详情）。

每 Agent（CLI 覆盖）

为某个 Agent 设置显式的 Auth Profile 顺序覆盖（存储在该 Agent 的 auth-state.json 中）：

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。 排查顺序问题时，openclaw models status --probe 会将已省略的存储 Profile 显示为 excluded_by_auth_order 而不是静默跳过。 排查冷却问题时，注意速率限制冷却可能绑定到某个模型 ID 而不是整个 Provider Profile。

排查常见问题

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

如果 Anthropic Profile 缺失，在 Gateway 主机上配置 Anthropic API Key 或设置 Anthropic setup-token 路径，然后重新检查：

openclaw models status

Token 即将过期/已过期

运行 openclaw models status 确认哪个 Profile 即将过期。如果 Anthropic Token Profile 缺失或过期，通过 setup-token 刷新配置，或迁移到 Anthropic API Key。

常见问题

如何切换当前会话使用的认证凭据？

在聊天窗口输入 /model <模型别名>@<profileId>，例如 /model claude-3-5-sonnet@anthropic:work。可用 /model 查看所有可选项目。

如何自动化检查认证是否有效？

使用 openclaw models status --check，凭据缺失或过期时退出码为 1，即将过期时为 2。可集成到监控脚本。

Anthropic setup-token 和 API Key 哪个更好？

API Key 更确定，适合长期 Gateway 主机。Anthropic 现在也允许复用本地 Claude CLI 登录（推荐路径），但需要主机上安装 Claude Code 并登录。setup-token 仍然可用但为 legacy 方式。

延伸阅读

• OAuth 配置
• Secrets 管理
• Gateway 配置
• Trusted Proxy Auth
• Auth Credential Semantics
• 帮助