身份验证

OpenClaw 支持通过 OAuth 和 API 密钥对模型提供商进行身份验证。对于常驻运行的 Gateway 主机，API 密钥通常是最稳妥的选择。如果你的提供商账户走的是订阅/OAuth 模式，也可以用相应的认证流程。

完整 OAuth 流程和存储结构详见 /concepts/oauth。 基于 SecretRef 的认证（env/file/exec 提供者）参考 密钥管理。 models status --probe 用到的凭证资格/原因码规则，见 Auth Credential Semantics。

推荐方式（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

不想自己管环境变量的话，引导向导可以帮你存好 API 密钥供守护进程使用：openclaw onboard。

环境变量继承机制（env.shellEnv、~/.openclaw/.env、systemd/launchd）详见 Help。

Anthropic：setup-token（订阅认证）

如果你用的是 Claude 订阅，可以走 setup-token 流程。在 Gateway 主机上执行：

claude setup-token

然后把 token 粘贴到 OpenClaw：

openclaw models auth setup-token --provider anthropic

如果 token 是在另一台机器上创建的，手动粘贴即可：

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 密钥。

注意： Anthropic setup-token 的支持仅限技术兼容层面。Anthropic 过去曾限制过订阅凭证在 Claude Code 以外的使用。如果你能接受政策风险，可以用它，但请自行确认 Anthropic 的当前条款。

手动输入 token（适用任何提供商，会写入 auth-profiles.json 并更新配置）：

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

认证配置也支持静态凭证引用：

• 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 需要交互式终端。

检查模型认证状态

openclaw models status
openclaw doctor

API 密钥轮换行为（Gateway）

部分提供商支持在遇到速率限制时，用备用密钥重试请求。

• 优先级顺序：
  • 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 查看完整视图（候选凭证 + 下一个认证配置，以及已配置的提供商端点信息）。

Agent 级别（CLI 覆盖）

为某个 Agent 设置显式的认证配置优先级（存储在该 Agent 的 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> 指定目标 Agent；省略则使用默认 Agent。

故障排除

”No credentials found”

如果 Anthropic 的 token 配置缺失，在 Gateway 主机上运行 claude setup-token，然后再检查：

openclaw models status

Token 即将过期/已过期

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

前提条件

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