认证

OpenClaw 支持模型提供商的 OAuth 和 API 密钥。对于常驻 Gateway 主机，API 密钥通常是最可预测的选项。当订阅/OAuth 流程与您的提供商账户模型匹配时，也支持这些流程。

See /concepts/oauth for the full OAuth flow and storage layout. For SecretRef-based auth (env/file/exec providers), see Secrets Management. For credential eligibility/reason-code rules used by models status --probe, see Auth Credential Semantics.

Anthropic：Claude CLI 和 token 兼容性

Anthropic setup-token 认证在 OpenClaw 中仍然可用，作为一种受支持的 token 路径。Anthropic 工作人员随后告诉我们，OpenClaw 风格的 Claude CLI 使用再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 将 Claude CLI 复用和 AnthropicOpenClawAnthropicOpenClawCLIOpenClawCLIclaude -pAnthropicCLI 使用视为该集成受认可的方式。当主机上可用 Claude CLI 复用时，该路径现为首选。

对于长期运行的网关主机，Anthropic API 密钥仍然是最可预测的设置。如果要在同一主机上复用现有的 Claude 登录，请在新手引导/configure 中使用 Anthropic Claude CLI 路径。

建议的 Claude CLI 复用主机设置：

# Run on the gateway host
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

这是一个两步设置：

在网关主机上将 Claude Code 本身登录到 Anthropic。
告诉 OpenClaw 将 Anthropic 模型选择切换到本地 OpenClawAnthropicclaude-cliOpenClaw 后端并存储匹配的 OpenClaw 认证配置文件。

如果 claude 不在 PATH 上，请先安装 Claude Code或将 agents.defaults.cliBackends.claude-cli.command 设置为真实的二进制文件路径。

手动输入 token（任何提供商；写入 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 在运行时期望规范的 OpenClawversion + profiles 格式。如果旧版安装仍有诸如 { "openrouter": { "apiKey": "..." } } 之类的扁平文件，请运行 openclaw doctor --fix 将其重写为 openrouter:defaultAPI API 密钥配置文件；doctor 会在原始文件旁保留 .legacy-flat.*.bak 副本。端点详情（如 baseUrl、api、模型 ID、标头和超时）应属于 openclaw.json 或 models.json 中的 models.providers.<id>，而非 auth-profiles.json。

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

静态凭据也支持身份验证配置文件引用：

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

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

openclaw models status --check

实时身份验证探测：

openclaw models status --probe

注意事项：

探测行可以来自身份验证配置文件、环境凭据或 models.json。
如果显式的 auth.order.<provider> 省略了存储的配置文件，探测报告将为该配置文件报告 excluded_by_auth_order，而不是尝试它。
如果身份验证存在，但 OpenClaw 无法为该提供商解析可探测的模型候选项，探测将报告 OpenClawstatus: no_model。
速率限制冷却可以是模型范围的。在一个模型上冷却的配置文件对于同一提供商上的同级模型仍然可用。

Optional ops scripts (systemd/Termux) are documented here: Auth monitoring scripts

Anthropic 说明

Anthropic Anthropicclaude-cli 后端再次受到支持。

Anthropic 工作人员告诉我们，这个 OpenClaw 集成路径再次被允许。
因此，除非 Anthropic 发布新政策，OpenClaw 将 Claude CLI 重用和 OpenClawCLIclaude -pAnthropicAnthropic 使用视为对 Anthropic 支持的运行是认可的。
对于长期运行的网关主机和显式的服务器端计费控制，Anthropic API 密钥仍然是最可预测的选择。

检查模型认证状态

openclaw models status
openclaw doctor

API 密钥轮换行为（网关）

当 API 调用达到提供商速率限制时，某些提供商支持使用备用密钥重试请求。

优先级顺序：
- OPENCLAW_LIVE_<PROVIDER>_KEY（单个覆盖）
- <PROVIDER>_API_KEYS
- <PROVIDER>_API_KEY
- <PROVIDER>_API_KEY_*
Google 提供商还包括 GOOGLE_API_KEY 作为额外的后备选项。
相同的密钥列表在使用前会去重。
OpenClaw 仅针对速率限制错误使用下一个密钥进行重试（例如 OpenClaw429、rate_limit、quota、resource exhausted、Too many concurrent requests, ThrottlingException, concurrency limit reached 或 workers_ai ... quota limit exceeded）。
非速率限制错误不会使用备用密钥重试。
如果所有密钥都失败，则返回最后一次尝试的最终错误。

Removing 提供商 auth while the gateway is running

When 提供商 auth is removed through the Gateway(网关) control plane, OpenClaw deletes the saved auth profiles for that 提供商 and aborts active chat or agent runs whose selected 模型提供商 matches the removed 提供商. The aborted runs emit the normal chat cancellation and lifecycle events with stopReason: "auth-revoked", so connected clients can show that the run was stopped because credentials were removed.

Removing saved auth does not revoke keys at the 提供商. Rotate or revoke the key in the 提供商 dashboard when you need 提供商-side invalidation.

Controlling which credential is used

Per-会话 (chat command)

Use /model <alias-or-id>@<profileId> to pin a specific 提供商 credential for the current 会话 (example profile ids: anthropic:default, anthropic:work).

使用 /model （或 /model list ）获取紧凑选择器；使用 /model status 获取完整视图（候选项 + 下一个身份验证配置文件，以及在配置时包含提供商端点详情）。

每个代理（CLI 覆盖）

为代理设置显式的身份验证配置文件顺序覆盖（存储在该代理的 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> 来定位特定的代理；省略它以使用配置的默认代理。当您调试顺序问题时，openclaw models status --probe 会将省略的存储配置文件显示为 excluded_by_auth_order，而不是静默跳过它们。当您调试冷却问题时，请记住速率限制冷却可以绑定到一个模型 ID，而不是整个提供商配置文件。

故障排除

”未找到凭据”

如果 Anthropic 配置文件丢失，请在 网关主机 上配置 Anthropic API 密钥或设置 Anthropic 安装令牌路径，然后重新检查：

openclaw models status

令牌正在过期/已过期

运行 openclaw models status 以确认哪个配置文件正在过期。如果 Anthropic 令牌配置文件丢失或已过期，请通过安装令牌刷新该设置或迁移到 Anthropic API 密钥。

认证

推荐的设置方式（API 密钥，任意提供商）