认证（Authentication）

OpenClaw 支持 OAuth 和 API Key 两种方式为模型提供商认证。对于常驻运行的 Gateway 主机，API Key 通常是最稳定可预测的选择。订阅/OAuth 流程在与你的提供商账户匹配时也被支持。

完整的 OAuth 流程和存储布局见 /openclaw/concepts/oauth。 基于 SecretRef 的认证（env/file/exec 提供商），见 Secrets Management。 models status --probe 使用的凭证资格/原因码规则，见 Auth Credential Semantics。

推荐配置（API Key，适用于任意提供商）

如果你要运行一个长期存活的 Gateway，建议从所选提供商的 API Key 开始。 对于 Anthropic，API Key 认证是最安全的路径，推荐优先于订阅 setup-token 认证。

1. 在你的提供商控制台创建 API Key。
2. 将 Key 配置在 Gateway 主机（运行 openclaw gateway 的机器）上：

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

3. 如果 Gateway 运行在 systemd/launchd 下，建议将 Key 写入 ~/.openclaw/.env，让守护进程可以读取：

cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF

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

openclaw models status
openclaw doctor

如果不想自己管理环境变量，也可以通过 onboarding 为守护进程存储 API Key：openclaw onboard。

关于环境变量继承（env.shellEnv、~/.openclaw/.env、systemd/launchd）的详细说明见 Help。

Anthropic：setup-token（订阅认证）

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

claude setup-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 Key。

警告：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

静态凭证也支持认证 profile 引用：

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

自动化检查（expired/missing 时退出码 1，即将过期时退出码 2）：

openclaw models status --check

可选的运维脚本（systemd/Termux）文档见 /openclaw/automation/auth-monitoring。

claude setup-token 需要交互式 TTY。

Anthropic：迁移到 Claude CLI

如果 Gateway 主机上已安装并登录了 Claude CLI，可以直接切换到 CLI backend，无需粘贴 setup-token：

openclaw models auth login --provider anthropic --method cli --set-default

这会保留现有的 Anthropic auth profiles 供回滚，同时将默认模型选择改为 claude-cli/...，并在 agents.defaults.models 下添加对应的 Claude CLI allowlist 条目。

快捷方式：

openclaw onboard --auth-choice anthropic-cli

检查模型认证状态

openclaw models status
openclaw doctor

API Key 轮换行为（Gateway）

部分提供商支持在 API 调用触发速率限制时，用备用 Key 重试请求。

• 优先级顺序：
  • OPENCLAW_LIVE_<PROVIDER>_KEY（单一覆盖）
  • <PROVIDER>_API_KEYS
  • <PROVIDER>_API_KEY
  • <PROVIDER>_API_KEY_*
• Google 提供商还包含 GOOGLE_API_KEY 作为额外的后备。
• 同一 Key 列表使用前会去重。
• OpenClaw 仅在速率限制错误（如 429、rate_limit、quota、resource exhausted）时用下一个 Key 重试。
• 非速率限制错误不会用备用 Key 重试。
• 如果所有 Key 都失败，返回最后一次尝试的错误。

控制使用哪个凭证

会话级别（chat 命令）

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

使用 /model（或 /model list）打开紧凑选择器；使用 /model status 查看完整视图（候选者 + 下一个认证 profile，以及配置时的提供商 endpoint 详情）。

Agent 级别（CLI 覆盖）

为 agent 设置显式的 auth profile 顺序覆盖（存储在该 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 profile 丢失，在 Gateway 主机上运行 claude setup-token，然后再次检查：

openclaw models status

Token 即将过期/已过期

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

前置条件

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