身份验证
Note
本页介绍模型提供商身份验证(API 密钥、OAuth、Claude CLI 复用、Anthropic setup-token)。有关网关连接身份验证(令牌、密码、trusted-proxy),请参阅 配置 和 受信任的代理身份验证。
OpenClaw 支持面向模型提供商的 OAuth 和 API 密钥。对于常驻运行的网关主机,API 密钥是最可预测的选择;订阅/OAuth 流程在你的提供商账户模式匹配时也同样适用。
- 完整的 OAuth 流程和存储布局:/concepts/oauth
- 基于 SecretRef 的身份验证(
env/file/exec/store提供商):机密管理 models status --probe使用的凭据资格/原因代码:身份验证凭据语义
推荐设置:API 密钥(任何提供商)¶
- 在你的提供商控制台中创建 API 密钥。
- 将其放到网关主机(运行
openclaw gateway的机器)上:
- 如果网关在 systemd/launchd 下运行,请将密钥放入
~/.openclaw/.env,以便守护进程可以读取它:
- 重启网关进程(或守护进程),然后重新检查:
如果你不想自己管理环境变量,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- 开头、长期有效的令牌。在网关主机上使用以下命令存储该令牌:
该命令需要交互式 TTY。之后管理所存储令牌的身份验证配置文件命令请参阅 openclaw models,提供商侧的详细信息请参阅 Anthropic。
手动输入令牌¶
适用于任何提供商;会写入每个 agent 的 SQLite 身份验证存储并更新配置:
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会被拒绝。
检查模型身份验证状态¶
适合自动化的检查:过期/缺失时退出 1,即将过期时退出 2:
实时身份验证检查(要缩小范围,可添加 --probe-provider、--probe-profile、--probe-timeout、--probe-concurrency 或 --probe-max-tokens):
说明:
- 检查行可以来自身份验证配置文件、环境变量凭据或
models.json。 - 如果
auth.order.<provider>省略了某个已存储的配置文件,检查会针对该配置报告excluded_by_auth_order,而不是尝试使用它。 - 如果存在身份验证,但 OpenClaw 无法为该提供商解析出可测试的模型,检查会报告
status: no_model。 - 限流冷却可以是模型级别的:某个配置文件因一个模型而处于冷却时,仍可为同一提供商上的同族模型提供服务。
可选的运维脚本(systemd/Termux):身份验证监控脚本。
API 密钥轮换(网关)¶
当调用触发提供商限流时,一些提供商会使用配置的备用密钥重试请求。
每个提供商的密钥优先级顺序:
OPENCLAW_LIVE_<PROVIDER>_KEY(单个覆盖,固定使用一个密钥)<PROVIDER>_API_KEYS(逗号/空格/分号分隔的列表)<PROVIDER>_API_KEY<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 配置文件。运行:
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 会删除所选代理目录中该提供商的已保存认证配置文件,然后重新运行相同的认证流程。当已保存的配置文件卡住、过期或绑定到错误账户时使用它。它不会在提供商侧撤销凭据。
按会话(聊天命令)¶
/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 查看哪个配置文件即将过期。如果 Anthropic 令牌配置文件缺失或已过期,请通过 setup-token 刷新它,或迁移到 Anthropic API 密钥。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw