OpenClaw 模型认证完全指南：API Key、OAuth、Claude CLI 复用与密钥轮换

OpenClaw 模型认证完全指南API Key、OAuth、Claude CLI 复用与密钥轮换【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 为模型提供方model provider提供了 API Key、OAuth、Claude CLI 复用与 Anthropic setup-token 四类认证路径并将凭证统一收口到 SQLite 认证库中管理。本文围绕docs/gateway/authentication.md的完整脉络逐一讲解在网关gateway主机上配置、检查、轮换与移除模型认证的实操命令并结合仓库源码说明其底层存储与解析机制帮助你为常驻网关选型最可预测的认证方式并掌握openclaw models系列认证命令的完整用法。说明本文只讨论模型提供方的认证API Key、OAuth、Claude CLI 复用、setup-token。网关连接本身的认证token、password、trusted-proxy不在本文范围参见 Configuration 与 Trusted Proxy Auth。认证方式总览与选型OpenClaw 对模型提供方同时支持 OAuth 与 API Key 两类凭证形态。对于需要 7×24 常驻的网关主机API Key 是最可预测的选择它不依赖浏览器回跳、不依赖订阅账户的刷新令牌生命周期计费与限流都能在服务端显式控制订阅类 / OAuth 流程在与你所用提供方的账户模式匹配时同样可用例如 OpenAI Codex 的 ChatGPT OAuth、Anthropic 的 Claude CLI 订阅复用。三条相关的深层文档是完整的 OAuth 流程与存储布局OAuth 概念基于 SecretRefenv/file/exec/store四种来源的认证Secrets 管理openclaw models status --probe使用的凭证资格判定与原因码语义Auth Credential Semantics推荐配置API Key适用于任意提供方这是最通用、最稳的一条路径步骤只有四步在提供方控制台创建 API Key把 Key 放到网关主机运行openclaw gateway的那台机器上export PROVIDER_API_KEY... openclaw models status如果网关由 systemd/launchd 托管把 Key 写入~/.openclaw/.env让守护进程能读到cat ~/.openclaw/.env EOF PROVIDER_API_KEY... EOF重启网关进程或守护进程然后复查openclaw models status openclaw doctor如果你不想手工管理环境变量openclaw onboard交互向导也可以直接把 API Key 存给守护进程使用。环境变量加载优先级关于.env究竟从哪里读取见 Environment variables。其优先级从高到低为进程环境网关进程从父 shell/守护进程继承的变量当前工作目录下的.envdotenv 默认不覆盖已有值且忽略其中的提供方凭证与受保护运行时控制项全局.env即~/.openclaw/.env等价于$OPENCLAW_STATE_DIR/.env官方推荐在此存放提供方 API Key配置env块~/.openclaw/openclaw.json中的env.vars仅在该变量缺失时生效可选的登录 shell 导入env.shellEnv.enabled或OPENCLAW_LOAD_SHELL_ENV1只导入缺失的预期键。核心规则是永不覆盖已有值。OpenClaw 会从工作区.env屏蔽一整批提供方凭证键如GEMINI_API_KEY、GOOGLE_API_KEY、XAI_API_KEY、MISTRAL_API_KEY等以及任何以_API_HOST、_BASE_URL、_ENDPOINT结尾的键和整个OPENCLAW_*、ANTHROPIC_API_KEY_*、OPENAI_API_KEY_*命名空间——所以不要把提供方 Key 只放在工作区.env里要用上面列出的受信任来源。AnthropicClaude CLI 复用本地/桌面首选Anthropic 提供两条认证路线API Key直接计费、可预测与Claude CLI 复用复用宿主机上已有的 Claude Code 登录。setup-token 认证仍然是受支持的路径Claude CLI 复用claude -p风格在本集成中也被认可当主机上已有 Claude CLI 登录时本地/桌面场景优先走 Claude CLI 复用。但对于长期运行的网关主机Anthropic API Key 依然是最可预测的选择因为它具备显式的服务端计费控制。主机侧配置# 在网关主机上执行 claude auth login claude auth status --text openclaw models auth login --provider anthropic --method cli --set-default这是两步操作第一步让 Claude Code 在主机上登录 Anthropic第二步告诉 OpenClaw 把 Anthropic 模型路由到本地的claude-cli后端。--set-default会应用提供方推荐的默认模型。令牌边界OpenClaw 永不触碰原生登录令牌一个重要的安全设计是OpenClaw 从不读取、存储、刷新或转发 Claude CLI 的原生登录令牌。登录生命周期完全由本机安装的claude进程自己负责——它自己读取并刷新自己的登录态。若在网关进程上设置了CLAUDE_CONFIG_DIR则可以借此选择一套独立的 Claude 登录。OpenClaw 托管的 setup token 与 API Key 是与之隔离的独立凭证。此外网关服务必须在PATH中解析到claude。如果部署需要非标准可执行路径需要通过 CLI 后端插件注册一个 wrapper关于 CLI 后端的运行细节可参考 CLI Backends。Anthropic setup-token在任意装有 Claude Code 的机器上运行claude setup-token它会打印一个长寿命令牌前缀为sk-ant-oat01-。然后在网关主机上存储它openclaw models auth login --provider anthropic --method setup-token注意该命令需要交互式 TTY。令牌存好之后后续的管理命令见openclaw models的 auth-profile 命令组提供方侧细节见 Anthropic。手动令牌输入paste-tokenpaste-token适用于任意提供方它会写入对应 agent 的 SQLite 认证库并更新配置openclaw models auth login paste-token --provider openrouter实际命令形态是openclaw models auth paste-token --provider openrouter凭证存储位置OpenClaw 从每个 agent 的openclaw-agent.sqlite读取认证档案auth profiles。数据库布局见 OAuth 概念共享凭证~/.openclaw/state/openclaw.sqliteagent 本地凭证与认证路由状态~/.openclaw/agents/agentId/agent/openclaw-agent.sqliteagent 凭证行auth_profile_store表agent 的 order、last-good、cooldown、usage 行auth_profile_state表端点细节baseUrl、api、模型 id、headers、超时属于openclaw.json或models.json中的models.providers.id配置不属于认证档案。也就是说认证档案只管用什么凭证端点配置只管打到哪个地址二者分离。旧版 JSON 认证文件的迁移如果旧安装仍残留auth-profiles.json、auth-state.json或{ openrouter: { apiKey: ... } }这样的扁平结构运行一次openclaw doctor --fix即可将其导入 SQLite。doctor 会在原 JSON 文件旁边保留带时间戳的备份。从源码结构看运行时只从 SQLite 读取凭证迁移完成前若 SQLite 为空会按AUTH_PROFILE_MIGRATION_REQUIRED机制只封锁受影响提供方详见 Auth Credential Semantics 的Legacy-Compatible Messaging一节。Bedrock 的aws-sdk路由不是凭证外部认证路由如 Bedrock 的auth: aws-sdk不是凭证。对命名 Bedrock 路由应在openclaw.json中设置auth.profiles.id.mode: aws-sdk绝不要把type: aws-sdk写进认证档案存储——存储中的凭证类型只有api_key、token、oauth三种。openclaw doctor --fix会把遗留的 AWS SDK 标记从凭证存储迁移进配置元数据。这类配置型档案即使没有对应的存储凭证行也可以合法出现在auth.order与会话覆盖中。SecretRef 支持的凭证静态凭证可以直接用 SecretRef 引用外部来源避免在配置中明文存放api_key凭证可用keyRef: { source, provider, id }token凭证可用tokenRef: { source, provider, id }OAuth 模式的档案拒绝 SecretRef如果auth.profiles.id.mode是oauth那么该档案的 SecretRef 型keyRef/tokenRef会被直接拒绝。原因是 OAuth 凭证在运行期是可变的刷新流程会持久化轮换后的令牌若用 SecretRef 会把可变状态拆到两个存储中去这一策略在 Auth Credential Semantics 的 OAuth SecretRef Policy Guard 一节中被定义为硬失败错误。SecretRef 的四种来源env/file/exec/store详见 Secrets 管理。检查模型认证状态最常用的两个命令openclaw models status openclaw doctor自动化友好--check--check适用于脚本退出码语义明确openclaw models status --check退出码0未发现配置路由的认证/运行时问题也没有选中的凭证即将过期注意这并不保证一次模型请求必然成功退出码1某路由认证缺失或已过期、路由不兼容、运行时不可用或就绪状态不确定indeterminate退出码2选中的凭证即将过期且不存在需要返回1的条件。实时探测--probe--probe会发起真实模型调用可能消耗令牌并触发限流务必只在需要时使用openclaw models status --probe可用参数收敛探测范围参数作用--probe-provider name只探测指定提供方--probe-profile id只探测指定认证档案 id可重复或逗号分隔--probe-timeout ms单次探测超时默认8000--probe-concurrency n并发探测数默认2--probe-max-tokens n探测最大 tokens尽力而为默认8探测行的来源可以是认证档案、环境凭证或models.json。--json时认证/提供方/启动诊断走 stderrstdout 保持可被jq管道消费。探测结果解读要点如果auth.order.provider省略了某个已存储档案探测会报告该档案为excluded_by_auth_order而不是去尝试它如果存在认证但 OpenClaw 无法为该提供方解析出可探测模型报告status: no_model限流冷却cooldown可以是模型级的一个档案在某个模型上冷却同一提供方的兄弟模型仍可被服务。models status --probe还会在选中 agent 的规范数据库中创建临时内部会话因此要求对配置的状态目录拥有独占所有权——先openclaw gateway stop再探测。原因码的完整语义表missing_credential、expired、invalid_expires、unresolved_ref、ineligible_profile、no_model、excluded_by_auth_order见 Auth Credential Semantics 的 Stable probe reason codes 一节。可选运维脚本仓库还提供了可选的认证监控脚本体系systemd/Termux用于在远程/无头主机上监控Claude Code CLI 订阅令牌并支持从手机重新认证详见 Scriptsscripts/setup-auth-system.sh — 一次性初始化生成长期claude setup-token并打印 systemd/Termux 安装步骤scripts/claude-auth-status.sh — 检查 Claude Code 与 OpenClaw 的认证状态full|json|simplescripts/auth-monitor.sh — 轮询状态令牌临近过期时通过 OpenClaw send 和/或 ntfy.sh 推送通知可通过WARN_HOURS默认2、NOTIFY_PHONE、NOTIFY_NTFY环境变量配置配套scripts/systemd/openclaw-auth-monitor.{service,timer}每 30 分钟运行一次scripts/mobile-reauth.sh — 重跑claude setup-token并打印可在手机上打开的 URL。API Key 轮换网关某些提供方在调用命中提供方限流时会用配置中的备用 Key重试同一请求。Key 优先级每提供方OPENCLAW_LIVE_PROVIDER_KEY单值覆盖钉住一个 KeyPROVIDER_API_KEYS逗号/空格/分号分隔的列表PROVIDER_API_KEYPROVIDER_API_KEY_*以此前缀命名的任意环境变量Google 系提供方google、google-vertex额外回退到GOOGLE_API_KEY。组合后的列表在使用前会去重。轮换触发条件OpenClaw 只在下述错误信息匹配时轮换到下一个 Keyrate_limit、rate limit、429、quota exceeded/quota_exceeded、resource exhausted/resource_exhausted、too many requests。其他错误不会用备用 Key 重试。如果所有 Key 都失败返回最后一次尝试的最终错误。注意区分两个机制提供方特定短语如ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded驱动的是故障转移/重试分类反复失败时切换模型或提供方与上面的 API Key 轮换是两套独立机制模型级故障转移规则见 Model failover。撤销语义移除已保存的认证不会在提供方侧撤销 Key——需要提供方侧失效时请到提供方控制台自行轮换或撤销。同时注意--force重登与logout也都不会在提供方侧撤销凭证。网关运行中移除提供方认证当你通过网关控制面移除提供方认证时OpenClaw 会删除该提供方的已保存认证档案中止所有选中模型提供方与该被移除提供方匹配的进行中 chat/agent 运行。被中止的运行会照常发出取消/生命周期事件并带有stopReason: auth-revoked因此已连接的客户端可以明确感知运行是因为凭证被移除而停止的。相关实现位于 src/commands/models/auth-logout.ts 及其测试 src/commands/models/auth-logout.test.ts。控制使用哪一份凭证OpenAI 与遗留的openai-codexidOpenAI 的 API Key 档案与 ChatGPT/Codex OAuth 档案共用规范提供方 idopenai。新配置请使用openai:*档案 id 和auth.order.openai。如果旧配置里出现openai-codex、openai-codex:*档案 id 或auth.order.openai-codex请把它当作遗留迁移输入——不要新建openai-codex档案然后执行openclaw doctor --fix openclaw models auth list --provider openaidoctor 会把遗留的openai-codex:*档案 id 与auth.order.openai-codex条目重写为规范的openai路由迁移为无冲突的新档案 id修复后再复制档案 id 到auth.order或/model ...profileId使用。OpenAI 特定的模型/运行时路由细节见 OpenAI。登录时CLI同一 agent 内为同一提供方保存多份 OAuth 登录用--profile-id区分openclaw models auth login --provider openai --profile-id openai:ritsuko openclaw models auth login --provider openai --profile-id openai:lain--force会先删除所选 agent 目录中该提供方的已保存认证档案然后重新执行同一认证流程——适用于已保存档案卡住、过期或绑错账户的场景。它不会在提供方侧撤销凭证openclaw models auth login --provider anthropic --force会话级chat 命令/model alias-or-idprofileId -s为当前会话钉住一份具体提供方凭证示例档案 idanthropic:default、anthropic:work/model或/model list显示紧凑选择器/model status显示完整视图候选 下一个认证档案配置了端点时还含提供方端点细节。auth.order的变更会影响自动档案选择。/new与/reset会清除自动选择的回退/轮换状态但保留有效的显式用户模型/档案钉选想替换用户级档案钉选时请另外选择一份显式profile。代理级CLI 覆盖认证顺序覆盖存储在该 agent 的 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指定目标 agent省略则使用配置的默认 agent存储的 order 覆盖优先于配置中的auth.order.provideropenclaw models status --probe会把被省略的已存档案显示为excluded_by_auth_order而不是静默跳过——这对排查为什么某档案没被尝试非常有用。底层实现可参见 src/commands/models/auth-order.ts 与其测试 src/commands/models/auth-order.test.ts。其余 auth 子命令add、list、login、activate、logout、paste-api-key、setup-token、paste-token、order get/set/clear的完整参数说明见 CLI: models。故障排查No credentials found在网关主机上配置 Anthropic API Key或走 setup-token 路径然后复查openclaw models status补充排查agent 在运行时是读穿共享认证库的agent 本地档案优先于同 id 的共享档案详见 Auth Credential Semantics 的 Agent copy portability。因此新 agent 在存在可用共享 Anthropic 档案时不需要单独的 API Key用openclaw models status --agent agentId检查受影响 agent。Token 即将过期 / 已过期运行openclaw models status查看哪个档案即将过期。如果 Anthropic token 档案缺失或过期通过 setup-token 刷新它或迁移到 Anthropic API Key。补充openclaw models auth list --provider id可列出已保存档案不打印任何令牌/Key/OAuth 秘密材料活跃冷却与禁用条目会附带原因和恢复动作。相关文档Secrets 管理 — SecretRef 契约与共享密钥存储远程访问 — 网关远程连接认证认证存储与 OAuth — PKCE 令牌交换、存储布局、多账户路由Auth Credential Semantics — 档案排序与运行期凭证解析的规范规则Environment variables — 环境变量加载优先级与提供方凭证变量清单【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考