OpenClaw 401 认证失败：修复 invalid bearer token 与 missing authentication header
遇到 OpenClaw 401，先看是谁拒绝认证：invalid bearer token 要检查实际使用的令牌，missing authentication header 要检查凭证读取与请求配置，Gateway 认证码则要修客户端令牌或设备授权。修复后在原来的 agent 和会话中验证。
文章目录
OpenClaw 报 401 时，先看失败发生在哪里。调用模型时出现 invalid bearer token，要检查模型服务商实际收到的令牌；出现 missing authentication header，要检查请求是否带上认证；Control UI 连接时出现 AUTH_TOKEN_MISMATCH 等代码，则要修 Gateway 客户端认证。 模型 API key、Gateway 共享令牌和聊天渠道令牌分别用于不同连接，不能互相替换。
先保存精确报错、服务商、模型、失败的 agent 和 OpenClaw 版本，再只处理对应分支。以下操作依据截至 2026 年 10 月 4 日的官方文档与有版本限定的公开故障报告；本文没有执行账户登录或真实模型调用。
先按精确报错找到第一步
这张旧图用于识别模型认证分支，实际操作使用下表和后文的当前命令。
| 你看到的报错或现象 | 先检查什么 | 下一步 |
|---|---|---|
HTTP 401 authentication_error: Invalid bearer token | 所选模型走 API、OpenClaw 管理的 token，还是原生 Claude CLI | 按实际认证方式检查账号和重新认证，不把三者当成同一个登录 |
HTTP 401: missing authentication header / 401 Missing Authentication header | 失败的 provider 是否找到可用凭证，请求是否发到正确地址 | 查服务进程环境、agent 覆盖、provider 配置；都正确仍失败时查版本和中间代理 |
No API key found for provider / No credentials found | 失败 agent 的共享认证和本地覆盖 | 对该 agent 查状态，缺少可用认证才补；不要先复制其他 agent 的令牌 |
AUTH_TOKEN_MISSING / AUTH_TOKEN_MISMATCH | 客户端与 Gateway 的连接认证 | 设置正确的 Gateway 令牌，按连接详情处理设备令牌 |
AUTH_SCOPE_MISMATCH / PAIRING_REQUIRED | 设备获批的权限或待批准连接 | 检查权限请求并重新配对、批准，而不是轮换模型 API key |
上游 HTTP 报错与 Gateway connect 详细代码来自不同位置。若错误出现在 WhatsApp、Telegram 等渠道的连接阶段，先确认它是否来自渠道自身；不要凭一个 401 就推断 Anthropic 或 OpenRouter 的 key 失效。官方 Gateway 排障说明列出了连接认证码的具体含义。
在实际运行 Gateway 的主机上检查
在 Gateway 所在主机、运行服务的用户下执行检查。笔记本终端能读到的环境变量，不一定出现在远端服务器、容器或 systemd/launchd 服务中。根据官方认证说明，常驻服务需要能在自己的启动环境中读取 provider key；仅在另一个 shell 里 export 不足以证明服务已加载。
先运行这些诊断命令，不加入会发起模型请求的 --probe：
openclaw --version
openclaw gateway status
openclaw doctor
openclaw models status --agent YOUR_AGENT_ID
openclaw logs --follow把 YOUR_AGENT_ID 换成发生错误的 agent ID。记录该 agent 的默认模型、回退模型、provider、凭证来源、不可用 profile 与运行时诊断；日志中找到第一次失败的原文，而不只看最后的 all in cooldown。
然后在原来报错的聊天会话中输入：
/model status这一步不能省略。模型 CLI 文档明确说明，models status --agent 查看配置中的 agent，不检查聊天会话临时指定的模型。会话可能固定了另一个模型、运行时或 @profile，因此“默认模型正常”与“这次会话能用”是两件事。
invalid bearer token：按实际认证方式恢复
这一报错表示接收方不接受所收到的 bearer token，但错误文本本身不能确定是过期、撤销、账号选错还是其他原因。先确认 /model status 中的模型和运行时，再选择下列操作。
直接使用 API key
到对应服务商控制台确认所用 key 是否仍有效、属于预期账号，以及实际请求地址是否属于该服务商。如果 key 已撤销，重新生成并通过当前 provider 的认证入口保存；如果服务进程读取了另一份旧 key，修正那个来源。不要仅凭 key 前缀或“已保存”判断有效。
Anthropic 新接入可以运行 openclaw onboard 并选择 Anthropic API key。当前 Anthropic provider 文档在 token 突然失效的分支中建议新配置使用 API key；它按 API 用量计费，不意味着 Claude 月费覆盖这部分调用。
若通过环境变量配置，检查 Gateway 实际加载的 .env、服务环境或容器配置。官方说明提供 ~/.openclaw/.env 供常驻服务读取；修改正确的来源后重启 Gateway，再查看失败 agent 的模型状态。不要把完整 key 打进共享日志。
使用原生 Claude CLI 登录
如果所选运行时是 Claude CLI，在 Gateway 同一主机、同一服务用户下检查并重新登录：
claude auth status --text
claude auth login
openclaw gateway restart这是官方 Anthropic 排障步骤。原生 Claude 登录由 Claude Code 自己保存和刷新，OpenClaw 不读取、保存或刷新这些原生登录令牌。不要从 Claude 的登录文件复制 OAuth token 到 OpenClaw 数据库。
还要确认 Gateway 服务能在 PATH 中找到 claude；配置了 CLAUDE_CONFIG_DIR 时，服务可能选中了另一份 Claude 登录。个人终端已登录不能证明服务用户已登录。
使用 OpenClaw 管理的 setup-token 或 OAuth profile
先在 models status 中确认失效的 profile 和 provider，再使用该 provider 当前支持的登录方法重新认证。对于既有 Anthropic setup-token 配置，广义认证文档仍提供交互式入口：
openclaw models auth login --provider anthropic --method setup-token --agent YOUR_AGENT_ID这会改变指定 agent 的认证状态，需要在交互式终端中操作。setup-token 支持仍存在，不能据此说所有 token 登录已取消；也不能把它与原生 Claude CLI 登录混为一谈。新建的常驻 Gateway 按当前 provider 建议优先考虑 API key，已有 token 则按自己的账号、认证方法和失效原因处理。
missing authentication header：先查凭证如何进入请求
missing authentication header 表示接收方没有找到所需认证头。它与“收到令牌但拒绝令牌”不同，也不能单凭这一句证明 OpenClaw 存在程序缺陷。
按下面顺序缩小范围：
- 确认请求目标。 对照
/model status、agent 状态和失败日志，确定 provider、模型与实际baseUrl。OpenRouter、自定义兼容代理与直接服务商可能使用不同地址和认证方式。 - 确认服务进程找到可用凭证。 如果状态显示缺少认证，先修 Gateway 用户的环境或 auth profile。若状态显示存在凭证，继续检查该 agent 是否选中了另一份本地覆盖。
- 核对 provider 配置。 官方认证文档把
baseUrl、api、模型 ID 和 headers 等端点设置放在models.providers.<id>，而不是认证 profile。凭证与请求设置错配时，重新保存同一 key 不会自动修正端点。 - 检查中间代理与版本。 如果凭证来源和请求配置都符合预期，但接收方仍报缺少认证头，核查反向代理是否保留所需请求头，以及升级前后是否改变了行为。日志若隐藏认证值，不能把“看不到 header”当成“没有 header”的证明。
公开报告说明这一分支值得检查版本：issue #51056的报告者在 Linux、OpenClaw 2026.3.13 上描述了 OpenRouter 识别 key 但仍返回缺少认证头；issue #97934的报告者在 macOS、2026.6.10 上描述相似现象，并报告回退到 2026.6.1 后恢复。这些是特定环境的历史报告，两个 issue 均已关闭，不能证明你当前版本存在同一问题，也不构成今天直接安装旧版本的建议。
如果问题只在升级后出现，转到下文检查认证迁移与版本一致性；不要持续轮换已在同一路径下验证过的 key。
一个 agent 正常，另一个没凭证：检查共享认证与本地覆盖
当前 OpenClaw 不要求每个 agent 都另存一把 API key。 agent 没有本地 auth profile 时，会在运行时读取共享认证；相同 profile ID 的本地记录会覆盖共享记录。官方认证存储说明与Anthropic 排障说明明确了这种关系。
默认状态目录下，当前存储位置是：
| 位置 | 用途 |
|---|---|
~/.openclaw/state/openclaw.sqlite | 共享认证的基础存储 |
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite | agent 本地凭证覆盖，以及选择顺序、冷却等状态 |
设置了 OPENCLAW_STATE_DIR 时，根目录会随之改变。个人账号记录与普通共享认证也有各自的读取范围，不能假设所有登录都能被 agent 按普通共享 profile 读取。
对失败 agent 与正常 agent 分别查看 models status --agent，比较它们所选 provider/profile、认证来源和不可用原因。共享记录健康而某个 agent 失败时，重点检查该 agent 是否存在同 ID 的旧本地记录、不同认证选择顺序或会话固定的 profile。共享读取不会自动克隆凭证，尤其不要手动复制 OAuth refresh token；确实需要独立账号时，应给那个 agent 单独登录。
旧 JSON 文件现在怎么处理？
旧教程中的 auth-profiles.json、auth-state.json 或 agent auth.json 是迁移输入，不再是当前运行时的凭证来源。看到 AUTH_PROFILE_MIGRATION_REQUIRED 时，按官方迁移说明处理：
- 先确认版本和
openclaw doctor的诊断，保留现有配置、状态和迁移源的可恢复备份。 - 对受支持的旧文件运行
openclaw doctor --fix。这是修复操作，会导入核验过的值并把原文件改名归档。 - 重新查看失败 agent 的状态，再进行下文的短验证。
不要手工修改 SQLite 凭证表，也不要删除旧文件来跳过迁移。如果具体残留文件是 credentials/oauth.json，当前导入器已退役，官方要求先经过 2026.9.5 的中间升级导入，再安装最新版本；这条特殊路径不能与普通 JSON 迁移混用。
Control UI 认证失败：修 Gateway 令牌或设备权限
如果仪表板无法连接、失败的 connect 响应包含认证详细代码，按当前官方代码速查表操作：
| 详细代码 | 正确动作 |
|---|---|
AUTH_TOKEN_MISSING | 在 Gateway 主机的交互式终端运行 openclaw gateway auth-token --show，把令牌设置到客户端后重连 |
AUTH_TOKEN_MISMATCH | 核对客户端与 Gateway 的共享令牌；若 canRetryWithDeviceToken=true，允许一次可信设备令牌重试，仍失败则按官方令牌偏移恢复流程处理 |
AUTH_DEVICE_TOKEN_MISMATCH | 缓存设备令牌过时或已撤销，按设备管理流程重新批准或轮换该设备令牌 |
AUTH_SCOPE_MISMATCH | 设备令牌已识别，但获批角色或权限不够；审查请求后重新配对或批准所需权限 |
PAIRING_REQUIRED | 查看待批准请求，核对设备与请求的权限，再批准相应 requestId |
查看并批准待配对设备的当前命令是：
openclaw devices list
openclaw devices approve YOUR_REQUEST_ID用列表中核对过的请求 ID 替换 YOUR_REQUEST_ID。共享令牌输出应留在本地，不要粘贴到 issue、截图或聊天记录。权限不足需要批准正确权限，轮换共享令牌不能补足权限；也不要通过关闭 Gateway 认证来消除错误。
升级后才出现 401：检查迁移与版本一致性
官方更新排障特别提到，重新认证后仍有 provider 401 时，旧的 agent 本地 OAuth 副本可能遮住当前共享 profile，doctor --fix 会检查并清理这类旧副本。
先核对版本、更新状态和服务实际使用的安装：
openclaw --version
openclaw update status --json
openclaw gateway status --deep诊断指向升级修复或旧认证覆盖时，保留备份后运行 openclaw doctor --fix，再运行 openclaw gateway restart 并检查失败 agent。不要对所有 401 无条件先执行修复。
如果命令行与服务使用了不同 OpenClaw 安装，按官方说明修正 PATH 和服务安装。需要主动降级时，使用兼容检查或经过确认的升级前备份及其配套版本，不删除 meta.lastTouchedVersion 来绕过较新配置保护。
修完后，在原来的 agent 和会话中短验证
先确认失败 agent 的认证诊断已恢复，再回到原会话确认模型、运行时与 profile。openclaw models status --agent YOUR_AGENT_ID --check 返回 0，只表示没有发现配置认证或运行时问题、所选凭证未临近过期，不证明实际模型请求已成功。官方模型命令说明对此有明确区分。
要确认真实请求，优先在原来的会话发一条短消息。这会使用该会话实际选定的模型和账号，也可能消耗额度或产生费用。
如果需要单独定位某个 provider/profile，可以使用限定范围的探测。当前 CLI 文档要求直接 models status --probe 独占配置的状态目录，因为它会在 agent 数据库中创建临时内部会话。先停止运行中的 Gateway；探测和清理全部结束后才恢复 Gateway。 下面是诊断 OpenRouter 的示例，执行前替换 agent 与 profile ID，并安排这段服务暂停时间：
openclaw gateway stop
openclaw models status --agent YOUR_AGENT_ID --probe \
--probe-provider openrouter \
--probe-profile YOUR_OPENROUTER_PROFILE_ID \
--probe-concurrency 1 \
--probe-max-tokens 16--probe 会发起真实模型请求，可能消耗额度、产生费用或触发限流；--probe-max-tokens 是尽力限制，不是零费用保证。结果可能早于清理结束显示，中断或超时也不证明状态锁、临时会话已释放。等待命令完成及清理结束，若报告清理失败则先处理该问题，再用 openclaw gateway start 恢复服务。
探测证明的是指定 agent/provider/profile 的结果，原会话如果固定了别的模型或运行时，仍需在那个会话验证。
成功判断应对应原来的故障：客户端能连接只证明 Gateway 连接恢复；模型短请求完成且未再出现原来的 401，才证明该次模型认证恢复。若原始错误已变为 429、retry-after 或配额耗尽，转到 OpenClaw 429 限流排查。如果出现 all in cooldown，先找它之前的第一条错误；当前 Anthropic 文档还指出冷却可以按模型生效，并不等于所有认证都无效。
常见问题
401 就说明 API key 错了吗？
不一定。模型服务商可能拒绝令牌，也可能没有收到认证头；Gateway 客户端则有自己的共享令牌、设备令牌和权限检查。先看失败发生在模型调用还是 Gateway 连接，再处理对应凭证。其他错误类型可继续查看 OpenClaw API Key 与网关错误排查。
setup-token 还支持吗？要全部改成 API key 吗？
广义认证文档仍支持 Anthropic setup-token；当前 provider 文档建议 token 失效后的新配置使用 API key。已有配置要按实际认证方式处理，不需要因支持路径并存就全部重建。
主 agent 正常，新 agent 为什么仍然失败？
先查本地同 ID profile 覆盖、认证选择顺序、会话指定的 profile，以及服务用户的环境。当前共享读取规则允许没有本地 profile 的 agent 使用共享认证，因此“新 agent 必须复制主 agent 的 key”已经不是正确的通用建议。
选择 Claude CLI，就一定使用 Claude 月费吗？
不能这样判断。Anthropic provider 文档要求同时检查运行时与所选账号：原生 Claude CLI 登录和 API key 是不同认证，Claude CLI 明确选中了 API key 账号时仍走 API 计费。仅看 anthropic/* 模型名也无法确定账单方式。
长期在线的 Gateway 应该选什么认证？
官方认证指导把 API key 作为常驻 Gateway 更可预测的选择；个人本机已有 Claude 登录时，可以使用受支持的 Claude CLI。选择前确认费用由哪个账号承担、服务用户能否读取认证，以及重新启动后是否仍能使用。不存在只换一种认证就保证不再出现 401 的通用修复。
