跳转至

身份验证

Note

本页介绍模型提供商身份验证(API 密钥、OAuth、Claude CLI 复用、Anthropic setup-token)。有关网关连接身份验证(令牌、密码、trusted-proxy),请参阅 配置 和 受信任的代理身份验证。

OpenClaw 支持面向模型提供商的 OAuth 和 API 密钥。对于常驻运行的网关主机,API 密钥是最可预测的选择;订阅/OAuth 流程在你的提供商账户模式匹配时也同样适用。

  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 从不读取、存储、刷新或转发原生登录令牌。已安装的 claude 进程会自行读取并刷新其登录状态。在网关进程上设置 CLAUDE_CONFIG_DIR 可选择另一个 Claude 登录。OpenClaw 管理的 setup token 和 API 密钥仍然是相互独立的凭据。

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

Anthropic setup-token

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

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

该命令需要交互式 TTY。之后管理所存储令牌的身份验证配置文件命令请参阅 openclaw models,提供商侧的详细信息请参阅 Anthropic。

手动输入令牌

适用于任何提供商;会写入每个 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。其他错误不会使用备用密钥重试。如果所有密钥均失败,则返回最后一次尝试的最终错误。

Note

提供商特定的短语,如 ThrottlingException、concurrency limit reached 或 workers_ai ... quota limit exceeded,会驱动故障转移/重试分类(在重复失败时切换模型或提供商),这是与上述 API 密钥轮换不同的独立机制。

删除已保存的认证信息不会在提供商侧撤销密钥——当需要在提供商侧使密钥失效时,请在提供商控制台中轮换或撤销它。

在网关运行期间移除提供商认证

当你通过网关控制平面移除提供商认证时,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 密钥。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw