OpenClaw 的 401，通常不是一个“换掉 key 就行”的问题，而是三条不同的认证分支之一：invalid bearer token、missing authentication header，或者某个 agent 根本没有凭证。先把日志里的精确报错分到正确分支，再决定是重认证、查 header 路由，还是只修失败的那个 agent，才不会把原本还能工作的配置一起弄坏。
正确分支之后，真正有价值的判断才会出现。你不仅能更快把这次故障修好，还能顺手判断这台 host 以后该保留哪种认证方式。对长期在线的 gateway host 来说，长期默认值通常应该选最可预测的那条路，而不是最省事的那条。
30 秒分流板
先别改任何凭证，先按报错文本分支：
| 如果日志写的是 | 更可能坏掉的环节 | 最安全的第一步 | 要在同一路径上验证什么 | 什么时候升级排查 |
|---|---|---|---|---|
invalid bearer token | 某条 token 驱动的认证路径已经失效、被覆盖，或在当前构建上不够稳定 | 先把这条认证重新走一遍 | 在同一个 agent、同一台 host 上重试，看这条路径是否恢复 | 干净重认证后，同一分支还是继续报错 |
missing authentication header | 请求路由、provider 配置，或某一层根本没把认证带出去 | 先查是谁在组装出站请求，再决定是否动凭证 | 看重试请求是否真的带上了可用认证 | 已知正常的凭证仍然落到同一条 missing-header 分支 |
| 一个 agent 正常，另一个 agent 报 401 或 “no credentials” | 出错的那个 agent 本身 | 给失败的 agent 补凭证或刷新凭证 | 只重测失败的 agent，不要拿正常 agent 当修复证据 | 失败的 agent 仍然没有可用 profile 或状态仍为空 |
这不是纸上分类。当前 OpenClaw 文档仍然同时记录了多条 Anthropic 认证路径，包括 API key、Claude CLI 复用和 setup-token 复用；当前 Anthropic provider 文档和 CLI 路径也都说明认证状态和 agent 有明确绑定关系。公开运行时证据同样表明 401 会分叉：issue #23538 记录了 OpenClaw 2026.2.21-2 上的 invalid bearer token，issue #34830 记录了另一条 401 missing authentication header 回归。
所以最先该问的不是“我要换哪个 key”，而是“我现在到底在哪条分支”。这一步不做，后面几乎一定会修得过头。
如果报错是 invalid bearer token
这一支通常意味着：请求确实带着某种 token 发出去了，但上游不接受它。结合当前 OpenClaw 对 Anthropic 的公开说明，这种情况更常见于 Claude 登录复用、Claude CLI 复用、setup-token 复用这一类 token 路线，而不是最直接的 Anthropic API key。
因此，第一步应该是重认证，而不是上来就大改配置。当前 OpenClaw Anthropic provider 文档 仍把 401 errors / token suddenly invalid 当成一条独立排障分支来写。Claude 官方帮助文档还补了一个很关键的现实条件：Claude Code 会被 ANTHROPIC_API_KEY 覆盖。也就是说，机器看起来像是“已经登录 Claude”，真正发请求时却可能走了另一条你没意识到的认证路径。
这也是为什么“token 已经保存成功”不等于“运行时认证一定健康”。在 issue #23538 里，setup-token 路线完成了写入，但运行时 Anthropic 请求仍返回 HTTP 401 authentication_error: Invalid bearer token。这并不意味着 setup-token 已经全面不可用，只意味着它不能被表述成“保存成功就等于这条路已经稳定”的路径。
这一支的恢复顺序可以按下面来：
- 按当前文档把预期要用的 token 或 setup-token 流程完整重走一遍。
- 清掉可能还在抢优先级的旧 Claude 会话、旧 token 或已撤销的本地状态。Claude 的会话撤销说明 可以直接用来做这一步。
- 检查 host 上有没有
ANTHROPIC_API_KEY之类的环境变量，把你以为在用的订阅式认证覆盖掉了。 - 回到同一个 agent、同一台 host 上复测，不要拿另一台刚好没问题的机器当成功证据。
如果同一条 token 分支在干净重认证后仍然报错，就不要再把它当成“多试几次”的问题，而要把它升级成“这台 host 该不该继续保留这种认证方式”的问题。对长期在线的 gateway host 来说，更少隐含状态、更少本地会话依赖的认证路径通常更稳。要是你的故障已经明显收敛成 Anthropic token 这一条，可以继续看更窄的 OpenClaw Anthropic API key 错误指南。
如果报错是 missing authentication header
missing authentication header 也是 401，但它和 invalid bearer token 的含义完全不同。前者更像“请求根本没把可用认证送出去”，后者则是“认证送出去了，但对方不接受”。这两种分支混着修，最常见的结果就是你旋转了一堆原本没问题的凭证，却仍然没碰到真正坏掉的那一层。
Issue #34830 的价值就在这里。它把 401 missing authentication header 明确暴露成了另一类回归，而不是“同一个 bad token 故事的另一种表述”。如果日志已经直接写 header 缺失，最先要做的就是定位请求是由哪一层组装出去的，那一层有没有凭证可用，以及配置到底在哪里断掉了。
这条分支不需要很长的恢复动作，关键是顺序不能错：
- 先确认是哪条 provider 路径或哪个 agent 产出了这次失败请求。
- 检查那条路径当前正在读取的 config、环境变量或 profile。
- 用一组已知正常的凭证重试，并确认请求这次是否真的把认证头带出去了。
如果换成已知正常的凭证后，请求仍然落在同一条 missing-header 分支，就别再把它当普通的 credential drift。到这里，问题已经更像 routing、配置接线，或者某个构建版本的行为差异。继续轮换 secrets，基本只会越修越乱。
如果主 agent 正常，但另一个 agent 没凭证
这是第三条独立分支。当前 OpenClaw 文档和 CLI 路径都把认证 profile 放在 agent 级别管理，例如 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 这一类路径。换成操作层面的说法就是：每个 agent 都需要它自己的凭证。主 agent 正常，不代表新建的 agent 自动继承到了相同的认证状态。
所以这条分支的正确修法不是“重跑整个 host 的 onboarding”，而是盯着失败的那个 agent 修。先比对失败 agent 和正常 agent 的 auth state，再给失败 agent 补凭证或刷新凭证，然后只重试这个失败 agent。很多人就是在这里把正常的主配置也一起重做了，最后把原本健康的一条路也搅乱。
当环境里同时混着本地登录复用、per-agent profiles 和 host 级环境变量覆盖时，这条分支会更难看清。它不是不能用，而是调试成本会陡增。如果这台机器是为了长时间在线和稳定服务而存在，认证路径越简单，后面越不容易在这一层反复踩坑。
这台 host 应该留哪种认证方式
把服务拉起来之后，真正要做的决定不是“哪条认证刚才试通了”，而是“哪条认证最不容易在这台 host 上再掉一次”。
当前 OpenClaw 的公开指导在这个问题上其实很直接。Gateway authentication 文档 倾向把 API key 作为长期在线 gateway host 的默认路线。Anthropic provider 文档 仍然保留 Claude CLI 复用和 setup-token 复用，但 OpenClaw FAQ 对环境边界说得更清楚：本地 Claude 登录复用可以支持，但并不建议当成生产默认值。FAQ 还记录了一条 2026 年 4 月 4 日的 Anthropic 通知，说明 OpenClaw 的 Claude 登录路径需要单独的 Extra Usage 计费，而不是直接包含在订阅里。
换成更实用的判断：
| 环境 | 更适合长期保留的默认路线 | 原因 |
|---|---|---|
| 长期在线的 server / shared gateway host | 直接 API key | 状态更少、依赖更少、重启后更容易解释和排查 |
| 你自己控制的个人机器 | Claude CLI 或订阅关联登录也可以接受 | 便利性可能比长期可预测性更重要，而且用户会话就是本地的 |
| setup-token 复用 | 官方仍支持，但要带着版本敏感意识使用 | 文档还支持，但公开 issue 足以说明它不该被包装成所有 host 的默认最优解 |
核心不是永远为某一种认证辩护，而是把认证方式和运行环境配对。对长期开着的 host 来说，“更可预测”几乎总比“更方便”重要；对你自己的本地机器来说，反过来也可能成立。
修完以后，先做一轮短验证
绝大多数重复 401，都不是因为第一次修错了所有事实，而是因为修完以后没有在同一条路径上做验证。把下面这轮短检查做完，能少掉很多二次故障：
- 重新测试同一个失败的 agent。不要看到另一个 profile 正常就宣布结束。
- 确认当前生效的认证方式，真的是你以为已经留下来的那一条。
- 清掉不该再抢优先级的旧 token 路线、旧会话或已撤销状态。
- 如果你换了认证方式，把这台 host 的默认路线记清楚，避免以后旧路径又悄悄回来。
这里还要把 cooldown 和凭证错误分开看。当前 Anthropic provider 文档说，No available auth profile (all in cooldown/unavailable) 这类状态应该配合 openclaw models status --json 看。它不等于 invalid bearer token，也不等于 missing authentication header。如果把这几种状态全部压成“认证坏了”，你就会反复去换凭证，但真正该看的其实是 profile 可用性。
升级排查范围的标准可以很简单：
invalid bearer token被重认证修好以后，单独判断这台 host 是否还值得继续走同一路线。missing authentication header用已知正常凭证重试后仍存在，就继续盯 routing 和版本行为，不要回去循环换 token。- 一个 agent 正常、另一个失败，就优先修失败的那个 agent。
- 如果问题明显超出这篇 401 分流本身，就跳去更广的 OpenClaw 错误排查总指南 或 安装与部署指南。
FAQ
OpenClaw 的 401 都等于 API key 错了吗？
不是。当前公开证据至少能稳定分出三类：invalid bearer token、missing authentication header，以及单个 agent 没有可用凭证。
setup-token 现在还支持吗？
支持。当前 OpenClaw 文档仍把 setup-token 列为 Anthropic 的受支持认证路径之一。但截至 2026 年 4 月 7 日，公开 issue #23538 仍然说明某些版本上存在 invalid bearer token 的运行时回归，所以更准确的说法是“官方支持，但带版本敏感性”。
为什么主 agent 正常，新 agent 却报 401？
因为当前 OpenClaw 文档明确把认证状态绑定到 agent。主 agent 健康，只能证明它自己有凭证，不能证明其他 agent 自动继承到了同一状态。
对长期在线的 server，最稳的认证方式是什么？
当前 OpenClaw 的指导倾向于让 long-lived host 选最可预测的路径。实际操作里，这通常意味着优先直接 API key，而不是长期依赖 token 或会话复用。
工作规则
修 OpenClaw 401 时，先别问“我要换哪个凭证”，先问“哪条分支坏了”。按精确报错把问题放回正确分支，只修那一条，再在同一路径上验证，最后才决定这台 host 该长期保留哪种认证方式。这样才能把一个窄 401 故障控制在最小范围内，而不是把它扩散成更大的认证事故。