认证

认证

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

查看 /concepts/oauth 了解完整的 OAuth 流程和存储 布局。 对于基于 SecretRef 的认证（env/file/exec 提供商），查看 Secrets 管理。

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

如果你运行的是长期运行的 gateway，首先为你选择的 提供商创建一个 API 密钥。 特别是对于 Anthropic，API 密钥认证是安全的路径，推荐 使用它而不是订阅 setup-token 认证。

1. 在你的提供商控制台中创建 API 密钥。
2. 将其放在 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

如果你不想自己管理环境变量，onboarding 向导可以存储 API 密钥供守护进程使用：openclaw onboard。

查看 Help 了解环境变量继承的详细信息（env.shellEnv、 ~/.openclaw/.env、systemd/launchd）。

Anthropic：setup-token（订阅认证）

如果你使用 Claude 订阅，支持 setup-token 流程。在 gateway 主机上运行：

claude setup-token

然后将其粘贴到 OpenClaw 中：

openclaw models auth setup-token --provider anthropic

如果令牌是在另一台机器上创建的，手动粘贴它：

openclaw models auth paste-token --provider anthropic

如果你看到类似这样的 Anthropic 错误：

This credential is only authorized for use with Claude Code and cannot be used for other API requests.

…请改用 Anthropic API 密钥。

手动令牌输入（任何提供商；写入 auth-profiles.json + 更新配置）：

openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter

Auth profile 引用也支持静态凭据：

• api_key 凭据可以使用 keyRef: { source, provider, id }
• token 凭据可以使用 tokenRef: { source, provider, id }

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

openclaw models status --check

可选的运维脚本（systemd/Termux）在此处记录： /automation/auth-monitoring

claude setup-token 需要交互式 TTY。

检查模型认证状态

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）时使用下一个密钥重试。
• 非速率限制错误不会使用备用密钥重试。
• 如果所有密钥都失败，则返回最后一次尝试的最终错误。

控制使用哪个凭据

每会话（chat 命令）

使用 /model <alias-or-id>@<profileId> 为当前会话固定特定的提供商凭据（示例 profile id：anthropic:default、anthropic:work）。

使用 /model（或 /model list）获取紧凑的选择器；使用 /model status 获取完整视图（候选项 + 下一个 auth profile，以及配置提供商端点详情时）。

每代理（CLI 覆盖）

为代理设置显式的 auth profile 顺序覆盖（存储在该代理的 auth-profiles.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> 定位特定代理；省略它以使用配置的默认代理。

故障排除

"未找到凭据"

如果 Anthropic 令牌 profile 缺失，在 gateway 主机上运行 claude setup-token，然后重新检查：

openclaw models status

令牌即将过期/已过期

运行 openclaw models status 确认哪个 profile 即将过期。如果 profile 缺失，重新运行 claude setup-token 并再次粘贴令牌。

要求

• Anthropic 订阅账户（用于 claude setup-token）
• Claude Code CLI 已安装（claude 命令可用）