身份验证

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

完整 OAuth 流程和存储布局请参阅 /concepts/oauth。 对于基于 SecretRef 的身份认证（env/file/exec 提供商），请参阅机密信息管理。 对于 models status --probe 使用的凭证可用性/原因代码规则，请参阅身份认证凭证语义。

# 推荐设置（API 密钥，任意提供商）

如果你正在运行长期存在的 Gateway 网关，请从所选提供商的 API 密钥开始。 特别是对于 Anthropic，API 密钥身份认证仍然是最可预测的服务器设置，但 OpenClaw 也支持复用本地 Claude CLI 登录。

1. 在你的提供商控制台中创建 API 密钥。
2. 将它放到 Gateway 网关主机（运行 openclaw gateway 的机器）上。

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

3. 如果 Gateway 网关在 systemd/launchd 下运行，建议将密钥放入 ~/.openclaw/.env，这样守护进程就可以读取它：

cat >> ~/.openclaw/.env <<'EOF'
&lt;PROVIDER&gt;_API_KEY=...
EOF

然后重启守护进程（或重启你的 Gateway 网关进程）并重新检查：

openclaw models status
openclaw doctor

如果你不想自行管理环境变量，新手引导可以为守护进程使用存储 API 密钥：openclaw onboard。

关于环境继承（env.shellEnv、~/.openclaw/.env、systemd/launchd）的详情，请参阅帮助。

# Anthropic：Claude CLI 和 token 兼容性

Anthropic setup-token 身份认证仍作为受支持的 token 路径在 OpenClaw 中可用。Anthropic 工作人员后来告诉我们，OpenClaw 风格的 Claude CLI 使用方式已再次被允许，因此 OpenClaw 将 Claude CLI 复用和 claude -p 用法视为此集成的受认可方式，除非 Anthropic 发布新政策。当主机上可以使用 Claude CLI 复用时，它现在是首选路径。

对于长期存在的 Gateway 网关主机，Anthropic API 密钥仍然是最可预测的设置。如果你想在同一主机上复用现有 Claude 登录，请在新手引导/配置中使用 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

这是一个两步设置：

1. 在 Gateway 网关主机上让 Claude Code 自身登录 Anthropic。
2. 告诉 OpenClaw 将 Anthropic 模型选择切换到本地 claude-cli 后端，并存储匹配的 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 在运行时需要规范的 version + profiles 形状。如果较旧的安装仍有类似 { "openrouter": { "apiKey": "..." } } 的扁平文件，请运行 openclaw doctor --fix，将其重写为 openrouter:default API 密钥配置文件；Doctor 会在原文件旁保留一份 .legacy-flat.*.bak 副本。baseUrl、api、模型 ID、headers 和 timeouts 等端点细节应放在 openclaw.json 或 models.json 中的 models.providers.<id> 下，而不是放在 auth-profiles.json 中。

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

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

• api_key 凭证可以使用 keyRef: { source, provider, id }
• token 凭证可以使用 tokenRef: { source, provider, id }
• OAuth 模式配置文件不支持 SecretRef 凭证；如果 auth.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 无法为该提供商解析可探测的模型候选项，探测会报告 status: no_model。
• 速率限制冷却可以按模型限定。某个配置文件针对一个模型处于冷却状态时，仍可用于同一提供商上的同级模型。

可选运维脚本（systemd/Termux）记录在这里： 身份认证监控脚本

# Anthropic 说明

Anthropic claude-cli 后端已重新受支持。

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

# 检查模型身份认证状态

openclaw models status
openclaw doctor

# API 密钥轮换行为（Gateway 网关）

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

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

# 控制使用哪个凭证

# 按会话（聊天命令）

使用 /model <alias-or-id>@<profileId> 为当前会话固定特定提供商凭证（示例配置文件 ID：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 配置文件，请在 Gateway 网关主机上配置 Anthropic API 密钥，或设置 Anthropic setup-token 路径，然后重新检查：

openclaw models status

# Token 即将过期/已过期

运行 openclaw models status 来确认哪个配置文件即将过期。如果 Anthropic token 配置文件缺失或已过期，请通过 setup-token 刷新该设置，或迁移到 Anthropic API 密钥。

# 相关内容

• 机密信息管理
• 远程访问
• 身份认证存储