身份验证

OpenClaw 支持模型提供商的 OAuth 和 API 密钥。对于始终在线的网关主机，API 密钥是最可预测的选项；当订阅/OAuth 流程与你的提供商账户模型匹配时，它们也可以工作。

• 完整 OAuth 流程和存储布局：/concepts/oauth
• 基于 SecretRef 的身份验证（env/file/exec/store 提供商）：密钥管理
• models status --probe 使用的凭据资格/原因代码：身份验证凭据语义

推荐设置：API 密钥（任意提供商）¶

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

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

1. 如果网关在 systemd/launchd 下运行，请将密钥放入 ~/.openclaw/.env，以便守护进程可以读取：

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

1. 重启网关进程（或守护进程），然后重新检查：

openclaw models status
openclaw doctor

openclaw onboard 也可以为守护进程存储 API 密钥，如果你不想自己管理环境变量。有关完整的环境变量加载优先级（env.shellEnv、~/.openclaw/.env、systemd/launchd），请参阅环境变量。

Anthropic：Claude CLI 复用¶

Anthropic setup-token 身份验证仍然是受支持的路径。Claude CLI 复用（claude -p 风格的使用）也为此集成所认可；当主机上存在 Claude CLI 登录时，这是本地/桌面使用的首选路径。对于长期运行的网关主机，Anthropic API 密钥仍然是最可预测的选择，具有明确的服务器端计费控制。

Claude CLI 复用的主机设置：

# Run on the gateway host
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

这是两步：在主机上将 Claude Code 登录到 Anthropic，然后告诉 OpenClaw 通过本地 claude-cli 后端路由 Anthropic 模型。

OpenClaw 从不读取、存储、刷新或转发原生登录 token。已安装的 claude 进程读取并刷新其自身的登录。当在网关进程上设置 CLAUDE_CONFIG_DIR 时，它会选择一个单独的 Claude 登录。由 OpenClaw 管理的 setup token 和 API 密钥仍然是独立的凭据。

网关服务必须在 PATH 上解析 claude。如果部署需要 非标准可执行文件路径，请通过 CLI 后端插件注册一个包装器。

Anthropic setup-token¶

在任何安装了 Claude Code 的机器上运行 claude setup-token。它会打印一个以 sk-ant-oat01- 开头的长期有效 token。使用以下命令将其存储在网关主机上：

openclaw models auth login --provider anthropic --method setup-token

该命令需要交互式 TTY。有关之后管理已存储 token 的身份验证配置文件命令，请参阅openclaw models；有关提供商端详细信息，请参阅Anthropic。

手动 token 输入¶

适用于任意提供商；写入每个 agent 的 SQLite 身份验证存储并更新配置：

openclaw models auth paste-token --provider openrouter

OpenClaw 从每个 agent 的 openclaw-agent.sqlite 读取身份验证配置文件。端点详细信息（baseUrl、api、模型 ID、请求头、超时）应位于 openclaw.json 或 models.json 中的 models.providers.<id> 下，而不是身份验证配置文件中。

如果旧安装仍有 auth-profiles.json、auth-state.json，或类似 { "openrouter": { "apiKey": "..." } } 的扁平结构，请运行 openclaw doctor --fix 将其导入 SQLite；doctor 会在原始 JSON 文件旁边保留带时间戳的备份。

诸如 Bedrock auth: "aws-sdk" 之类的外部身份验证路由不是凭据。对于命名的 Bedrock 路由，请在 openclaw.json 中设置 auth.profiles.<id>.mode: "aws-sdk" — 不要将 type: "aws-sdk" 写入身份验证配置文件存储。openclaw doctor --fix 会将旧版 AWS SDK 标记从凭据存储迁移到配置元数据。

基于 SecretRef 的凭据¶

• api_key 凭据可以使用 keyRef: { source, provider, id }
• token 凭据可以使用 tokenRef: { source, provider, id }
• OAuth 模式配置文件拒绝 SecretRef 凭据：如果 auth.profiles.<id>.mode 为 "oauth"，则该配置文件基于 SecretRef 的 keyRef/tokenRef 会被拒绝。

检查模型身份验证状态¶

openclaw models status
openclaw doctor

适合自动化的检查，过期/缺失时退出 1，即将过期时退出 2：

openclaw models status --check

实时身份验证探测（添加 --probe-provider、--probe-profile、--probe-timeout、--probe-concurrency 或 --probe-max-tokens 以缩小范围）：

openclaw models status --probe

说明：

• 探测行可以来自身份验证配置文件、环境变量凭据或 models.json。
• 如果 auth.order.<provider> 省略了已存储的配置文件，探测会报告该配置文件的 excluded_by_auth_order，而不是尝试它。
• 如果身份验证存在，但 OpenClaw 无法为该提供商解析可探测的模型，探测会报告 status: no_model。
• 速率限制冷却可以是模型范围的：一个配置文件针对某个模型冷却时，仍可以为同一提供商上的同级模型提供服务。

可选运维脚本（systemd/Termux）：身份验证监控脚本。

API 密钥轮换（网关）¶

某些提供商在调用遇到提供商速率限制时，会使用另一个已配置的密钥重试请求。

每个提供商的密钥优先级顺序：

1. OPENCLAW_LIVE_<PROVIDER>_KEY（单个覆盖，固定一个密钥）
2. <PROVIDER>_API_KEYS（逗号/空格/分号分隔的列表）
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_*（具有此前缀的任何环境变量）

Google 提供商（google、google-vertex）还会回退到 GOOGLE_API_KEY。合并后的列表在使用前会进行去重。

仅当错误消息匹配以下模式时，OpenClaw 才会轮换到下一个密钥：rate_limit、rate limit、429、quota exceeded/quota_exceeded、resource exhausted/resource_exhausted 或 too many requests。其他错误不会使用备用密钥重试。如果所有密钥都失败，则返回最后一次尝试的最终错误。

删除已保存的认证不会在提供商处吊销密钥——当您需要提供商侧失效时，请在提供商控制台中轮换或吊销该密钥。

在网关运行时移除提供商认证¶

当您通过网关控制平面移除提供商认证时，OpenClaw 会删除该提供商的已保存认证配置文件，并中止所选模型提供商与已移除提供商匹配的活动聊天/代理运行。被中止的运行会发出正常的取消/生命周期事件，并带有 stopReason: "auth-revoked"，以便已连接的客户端可以显示该运行因凭据被移除而停止。

控制使用哪个凭据¶

OpenAI 和旧版 openai-codex id¶

OpenAI API 密钥配置文件和 ChatGPT/Codex OAuth 配置文件都使用规范提供商 ID openai。对于新配置，请使用 openai:* 配置文件 ID 和 auth.order.openai。

如果您在旧配置、认证配置文件 ID 或 auth.order.openai-codex 中看到 openai-codex，请将其视为旧版迁移输入——不要创建新的 openai-codex 配置文件。请运行：

openclaw doctor --fix
openclaw models auth list --provider openai

Doctor 会将旧版 openai-codex:* 配置文件 ID 和 auth.order.openai-codex 条目重写为规范的 openai 路由。有关 OpenAI 特定的模型/运行时路由，请参阅 OpenAI。

登录期间（CLI）¶

openclaw models auth login --provider openai --profile-id openai:ritsuko
openclaw models auth login --provider openai --profile-id openai:lain

--profile-id 可在单个代理内将同一提供商的多个 OAuth 登录保持隔离。

--force 会删除所选代理目录中该提供商的已保存认证配置文件，然后重新运行相同的认证流程。当已保存的配置文件卡住、过期或绑定到错误的账户时，请使用它。它不会在提供商处吊销凭据。

openclaw models auth login --provider anthropic --force

按会话（聊天命令）¶

• /model <alias-or-id>@<profileId> -s 将为当前会话固定特定的提供商凭据（示例配置文件 ID：anthropic:default、anthropic:work）。
• /model（或 /model list）显示紧凑的选择器；/model status 显示完整视图（候选配置 + 下一个认证配置文件，以及已配置时的提供商端点详细信息）。

对 auth.order 的更改会影响自动配置文件选择。/new 和 /reset 会清除自动选择的回退/轮换状态，但会保留有效的显式用户模型/配置文件固定；选择另一个显式的 @profile 选项可替换用户配置文件固定。

按代理（CLI 覆盖）¶

认证顺序覆盖存储在该代理的 SQLite 认证状态中：

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，而不是静默跳过它们。

故障排除¶

“未找到凭据”¶

在网关主机上配置 Anthropic API 密钥，或设置 Anthropic setup-token 路径，然后重新检查：

openclaw models status

令牌即将过期/已过期¶

运行 openclaw models status 查看哪个配置文件即将过期。如果 Anthropic 令牌配置文件缺失或已过期，请通过 setup-token 刷新它，或迁移到 Anthropic API 密钥。

相关¶

• 密钥管理
• 远程访问
• 认证存储