# OpenClaw 401 认证失败：修复 invalid bearer token 与 missing authentication header

> 遇到 OpenClaw 401，先看是谁拒绝认证：invalid bearer token 要检查实际使用的令牌，missing authentication header 要检查凭证读取与请求配置，Gateway 认证码则要修客户端令牌或设备授权。修复后在原来的 agent 和会话中验证。

- URL: https://blog.laozhang.ai/zh/posts/openclaw-401-authentication-error
- Published: 2026-04-07
- Updated: 2026-10-04
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Category: AI 故障排除
- Tags: OpenClaw, 401 错误, 认证错误, Anthropic, AI 故障排除

---
OpenClaw 报 401 时，先看失败发生在哪里。**调用模型时出现 `invalid bearer token`，要检查模型服务商实际收到的令牌；出现 `missing authentication header`，要检查请求是否带上认证；Control UI 连接时出现 `AUTH_TOKEN_MISMATCH` 等代码，则要修 Gateway 客户端认证。** 模型 API key、Gateway 共享令牌和聊天渠道令牌分别用于不同连接，不能互相替换。

先保存精确报错、服务商、模型、失败的 agent 和 OpenClaw 版本，再只处理对应分支。以下操作依据截至 2026 年 10 月 4 日的官方文档与有版本限定的公开故障报告；本文没有执行账户登录或真实模型调用。

## 先按精确报错找到第一步

![OpenClaw 模型认证错误分支示意，区分无效令牌、缺少认证头与没有可用凭证](https://blog.laozhang.ai/posts/zh/openclaw-401-authentication-error/img/triage-map.webp)

这张旧图用于识别模型认证分支，实际操作使用下表和后文的当前命令。

| 你看到的报错或现象 | 先检查什么 | 下一步 |
|---|---|---|
| `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 排障说明](https://docs.openclaw.ai/gateway/troubleshooting/agent-replies-and-control-ui#auth-detail-codes-quick-map)列出了连接认证码的具体含义。

## 在实际运行 Gateway 的主机上检查

在 Gateway 所在主机、运行服务的用户下执行检查。笔记本终端能读到的环境变量，不一定出现在远端服务器、容器或 systemd/launchd 服务中。根据[官方认证说明](https://docs.openclaw.ai/gateway/authentication)，常驻服务需要能在自己的启动环境中读取 provider key；仅在另一个 shell 里 `export` 不足以证明服务已加载。

先运行这些诊断命令，不加入会发起模型请求的 `--probe`：

```bash
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`。

然后在**原来报错的聊天会话中**输入：

```text
/model status
```

这一步不能省略。[模型 CLI 文档](https://docs.openclaw.ai/cli/models#status)明确说明，`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 文档](https://docs.openclaw.ai/providers/anthropic#troubleshooting)在 token 突然失效的分支中建议新配置使用 API key；它按 API 用量计费，不意味着 Claude 月费覆盖这部分调用。

若通过环境变量配置，检查 Gateway 实际加载的 `.env`、服务环境或容器配置。官方说明提供 `~/.openclaw/.env` 供常驻服务读取；修改正确的来源后重启 Gateway，再查看失败 agent 的模型状态。不要把完整 key 打进共享日志。

### 使用原生 Claude CLI 登录

如果所选运行时是 Claude CLI，在 **Gateway 同一主机、同一服务用户**下检查并重新登录：

```bash
claude auth status --text
claude auth login
openclaw gateway restart
```

这是[官方 Anthropic 排障步骤](https://docs.openclaw.ai/providers/anthropic#troubleshooting)。原生 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 配置，广义[认证文档](https://docs.openclaw.ai/gateway/authentication#anthropic-setup-token)仍提供交互式入口：

```bash
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 存在程序缺陷。

按下面顺序缩小范围：

1. **确认请求目标。** 对照 `/model status`、agent 状态和失败日志，确定 provider、模型与实际 `baseUrl`。OpenRouter、自定义兼容代理与直接服务商可能使用不同地址和认证方式。
2. **确认服务进程找到可用凭证。** 如果状态显示缺少认证，先修 Gateway 用户的环境或 auth profile。若状态显示存在凭证，继续检查该 agent 是否选中了另一份本地覆盖。
3. **核对 provider 配置。** [官方认证文档](https://docs.openclaw.ai/gateway/authentication)把 `baseUrl`、`api`、模型 ID 和 headers 等端点设置放在 `models.providers.<id>`，而不是认证 profile。凭证与请求设置错配时，重新保存同一 key 不会自动修正端点。
4. **检查中间代理与版本。** 如果凭证来源和请求配置都符合预期，但接收方仍报缺少认证头，核查反向代理是否保留所需请求头，以及升级前后是否改变了行为。日志若隐藏认证值，不能把“看不到 header”当成“没有 header”的证明。

公开报告说明这一分支值得检查版本：[issue #51056](https://github.com/openclaw/openclaw/issues/51056)的报告者在 Linux、OpenClaw `2026.3.13` 上描述了 OpenRouter 识别 key 但仍返回缺少认证头；[issue #97934](https://github.com/openclaw/openclaw/issues/97934)的报告者在 macOS、`2026.6.10` 上描述相似现象，并报告回退到 `2026.6.1` 后恢复。这些是特定环境的历史报告，两个 issue 均已关闭，不能证明你当前版本存在同一问题，也不构成今天直接安装旧版本的建议。

如果问题只在升级后出现，转到下文检查认证迁移与版本一致性；不要持续轮换已在同一路径下验证过的 key。

## 一个 agent 正常，另一个没凭证：检查共享认证与本地覆盖

**当前 OpenClaw 不要求每个 agent 都另存一把 API key。** agent 没有本地 auth profile 时，会在运行时读取共享认证；相同 profile ID 的本地记录会覆盖共享记录。[官方认证存储说明](https://docs.openclaw.ai/concepts/oauth#storage-where-tokens-live)与[Anthropic 排障说明](https://docs.openclaw.ai/providers/anthropic#troubleshooting)明确了这种关系。

默认状态目录下，当前存储位置是：

| 位置 | 用途 |
|---|---|
| `~/.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` 时，按[官方迁移说明](https://docs.openclaw.ai/concepts/oauth#storage-where-tokens-live)处理：

1. 先确认版本和 `openclaw doctor` 的诊断，保留现有配置、状态和迁移源的可恢复备份。
2. 对受支持的旧文件运行 `openclaw doctor --fix`。这是修复操作，会导入核验过的值并把原文件改名归档。
3. 重新查看失败 agent 的状态，再进行下文的短验证。

不要手工修改 SQLite 凭证表，也不要删除旧文件来跳过迁移。如果具体残留文件是 `credentials/oauth.json`，当前导入器已退役，官方要求先经过 `2026.9.5` 的中间升级导入，再安装最新版本；这条特殊路径不能与普通 JSON 迁移混用。

## Control UI 认证失败：修 Gateway 令牌或设备权限

如果仪表板无法连接、失败的 `connect` 响应包含认证详细代码，按[当前官方代码速查表](https://docs.openclaw.ai/gateway/troubleshooting/agent-replies-and-control-ui#auth-detail-codes-quick-map)操作：

| 详细代码 | 正确动作 |
|---|---|
| `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` |

查看并批准待配对设备的当前命令是：

```bash
openclaw devices list
openclaw devices approve YOUR_REQUEST_ID
```

用列表中核对过的请求 ID 替换 `YOUR_REQUEST_ID`。共享令牌输出应留在本地，不要粘贴到 issue、截图或聊天记录。权限不足需要批准正确权限，轮换共享令牌不能补足权限；也不要通过关闭 Gateway 认证来消除错误。

## 升级后才出现 401：检查迁移与版本一致性

[官方更新排障](https://docs.openclaw.ai/gateway/troubleshooting/updates-and-rollbacks#after-an-update)特别提到，重新认证后仍有 provider 401 时，旧的 agent 本地 OAuth 副本可能遮住当前共享 profile，`doctor --fix` 会检查并清理这类旧副本。

先核对版本、更新状态和服务实际使用的安装：

```bash
openclaw --version
openclaw update status --json
openclaw gateway status --deep
```

诊断指向升级修复或旧认证覆盖时，保留备份后运行 `openclaw doctor --fix`，再运行 `openclaw gateway restart` 并检查失败 agent。不要对所有 401 无条件先执行修复。

如果命令行与服务使用了不同 OpenClaw 安装，按官方说明修正 `PATH` 和服务安装。需要主动降级时，使用兼容检查或经过确认的升级前备份及其配套版本，不删除 `meta.lastTouchedVersion` 来绕过较新配置保护。

## 修完后，在原来的 agent 和会话中短验证

![OpenClaw 修复后核对清单，提醒回测同一 agent、确认生效认证并检查冷却状态](https://blog.laozhang.ai/posts/zh/openclaw-401-authentication-error/img/post-fix-checklist.webp)

先确认失败 agent 的认证诊断已恢复，再回到原会话确认模型、运行时与 profile。`openclaw models status --agent YOUR_AGENT_ID --check` 返回 0，只表示没有发现配置认证或运行时问题、所选凭证未临近过期，**不证明实际模型请求已成功**。[官方模型命令说明](https://docs.openclaw.ai/cli/models#read-status-correctly)对此有明确区分。

要确认真实请求，优先在原来的会话发一条短消息。这会使用该会话实际选定的模型和账号，也可能消耗额度或产生费用。

如果需要单独定位某个 provider/profile，可以使用限定范围的探测。[当前 CLI 文档](https://docs.openclaw.ai/cli/models)要求直接 `models status --probe` 独占配置的状态目录，因为它会在 agent 数据库中创建临时内部会话。**先停止运行中的 Gateway；探测和清理全部结束后才恢复 Gateway。** 下面是诊断 OpenRouter 的示例，执行前替换 agent 与 profile ID，并安排这段服务暂停时间：

```bash
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 限流排查](https://blog.laozhang.ai/zh/posts/openclaw-rate-limit-exceeded-429)。如果出现 `all in cooldown`，先找它之前的第一条错误；当前 Anthropic 文档还指出冷却可以按模型生效，并不等于所有认证都无效。

## 常见问题

### 401 就说明 API key 错了吗？

不一定。模型服务商可能拒绝令牌，也可能没有收到认证头；Gateway 客户端则有自己的共享令牌、设备令牌和权限检查。先看失败发生在模型调用还是 Gateway 连接，再处理对应凭证。其他错误类型可继续查看 [OpenClaw API Key 与网关错误排查](https://blog.laozhang.ai/zh/posts/openclaw-api-key-error)。

### setup-token 还支持吗？要全部改成 API key 吗？

[广义认证文档](https://docs.openclaw.ai/gateway/authentication#anthropic-setup-token)仍支持 Anthropic setup-token；[当前 provider 文档](https://docs.openclaw.ai/providers/anthropic#troubleshooting)建议 token 失效后的新配置使用 API key。已有配置要按实际认证方式处理，不需要因支持路径并存就全部重建。

### 主 agent 正常，新 agent 为什么仍然失败？

先查本地同 ID profile 覆盖、认证选择顺序、会话指定的 profile，以及服务用户的环境。[当前共享读取规则](https://docs.openclaw.ai/concepts/oauth#storage-where-tokens-live)允许没有本地 profile 的 agent 使用共享认证，因此“新 agent 必须复制主 agent 的 key”已经不是正确的通用建议。

### 选择 Claude CLI，就一定使用 Claude 月费吗？

不能这样判断。[Anthropic provider 文档](https://docs.openclaw.ai/providers/anthropic#choose-a-model-route)要求同时检查运行时与所选账号：原生 Claude CLI 登录和 API key 是不同认证，Claude CLI 明确选中了 API key 账号时仍走 API 计费。仅看 `anthropic/*` 模型名也无法确定账单方式。

### 长期在线的 Gateway 应该选什么认证？

[官方认证指导](https://docs.openclaw.ai/gateway/authentication)把 API key 作为常驻 Gateway 更可预测的选择；个人本机已有 Claude 登录时，可以使用受支持的 Claude CLI。选择前确认费用由哪个账号承担、服务用户能否读取认证，以及重新启动后是否仍能使用。不存在只换一种认证就保证不再出现 401 的通用修复。