认证

OpenClaw 支持模型提供商的 OAuth �?API 密钥认证。对�?Anthropic 账户，我们推荐使�?API 密钥。对�?Claude 订阅访问�? 请使用由 claude setup-token 创建的长期令牌�?

完整�?OAuth 流程和存储布局请参�?/concepts/oauth�? 关于基于 SecretRef 的认证（env/file/exec 提供商），请参阅密钥管理�?

推荐�?Anthropic 配置（API 密钥�?

如果您直接使�?Anthropic，请使用 API 密钥�?

  1. �?Anthropic 控制台创�?API 密钥�?
  2. 将其放在 Gateway 主机上（运行 openclaw gateway 的机器）�?
export ANTHROPIC_API_KEY="..."
openclaw models status
  1. 如果 Gateway �?systemd/launchd 下运行，建议将密钥放�? ~/.openclaw/.env 中，以便守护进程可以读取它：
cat >> ~/.openclaw/.env <<'EOF'
ANTHROPIC_API_KEY=...
EOF

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

openclaw models status
openclaw doctor

如果您不想自己管理环境变量，入驻向导可以为守护进程存�? API 密钥：openclaw onboard�?

有关环境继承的详细信息（env.shellEnv�? ~/.openclaw/.env、systemd/launchd），请参阅帮助�?

Anthropic：setup-token（订阅认证）

对于 Anthropic，推荐的方式�?API 密钥。如果您使用的是 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

静态凭据也支持认证配置文件引用�?

  • api_key 凭据可以使用 key, provider, idRef: { source }
  • 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）�?
  • 非速率限制错误不会使用备用密钥重试�?
  • 如果所有密钥都失败，将返回最后一次尝试的错误�?

控制使用哪个凭据

按会话（聊天命令�?

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

使用 /model（或 /model list）进行紧凑选择器；使用 /model status 查看完整视图（候选项 + 下一个认证配置文件，以及配置时的提供商端点详情）�?

按代理（CLI 覆盖�?

为代理设置显式认证配置文件顺序覆盖（存储在该代理�?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 令牌配置文件，请�?**Gateway 主机**上运�?`claude setup-token`，然后重新检查：

```bash
openclaw models status

令牌即将过期/已过�?

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

要求

  • Claude Max �?Pro 订阅（用�?claude setup-token�?
  • 已安�?Claude Code CLI（claude 命令可用�?