1. OpenClaw 启动正常却一直 401 Unauthorized 的现场还原OpenClaw 这个网关工具简单说就是把你本地或服务器上的模型能力、工具链统一暴露成一个 HTTP 接口层让 Claude Code、Cline、Codex 这类客户端通过一个入口去调用。它适合谁适合手里同时跑好几个 AI 编码客户端、又不想每个客户端都单独配一遍 Key 和地址的人。而gateway.auth.mode就是它认证体系里的总开关——这个字段没配网关就不知道该怎么校验请求于是所有调用一律被挡在门外。我遇到的现象很典型openclaw gateway status显示进程 running端口也监听着日志里没有任何崩溃堆栈看起来一切正常。但只要一发请求立刻回来HTTP 401 Unauthorized {error: Missing or invalid authentication token}第一反应是 Token 写错了于是反复核对客户端里的 Key换了一遍又一遍还是 401。后来把配置文件整个翻出来看才发现问题根本不在客户端——服务端的gateway.auth.mode压根没写。官方文档里给的示例配置为了简洁经常把认证段省略掉直接复制过来就会踩这个坑。这个报错的本质是网关的认证机制需要「模式声明」和「令牌值」两样东西同时到位。gateway.auth.mode告诉网关用哪种方式校验比如 token 模式gateway.auth.token或环境变量OPENCLAW_GATEWAY_TOKEN提供具体的凭据。缺了模式网关无法进入校验流程只能一律拒绝缺了令牌模式配了也校验不过。两者缺一不可而报错信息只笼统地说 Unauthorized不会告诉你到底缺哪个所以排查时容易在客户端那边绕圈子。下面这张流程图是我当时理出来的判断路径你可以对照自己的情况走一遍Gateway 启动加载配置 ↓ 读取 gateway.auth.mode ↓ mode 是否已明确配置 ├─ 是 → 按该模式校验请求头里的凭据 │ ├─ 凭据有效 → 放行 │ └─ 凭据无效 → 401 └─ 否 → 无法进入校验流程 → 全部 401搞清楚这一点之后解决方向就明确了不是去客户端反复改 Key而是回到服务端把认证模式补上并且把认证入口统一指向一个稳定的 Key/API 通道。我这边最终是把认证配置接到了 TaoToken 的统一通道上这样多个客户端共用一套 Key不用每个都单独维护。接下来先讲前置准备再给可复制的配置。2. 把认证入口接到 TaoToken 统一通道的前置准备在动auth.json之前得先把「认证入口指向哪里」这件事定下来。OpenClaw 的网关认证本质上是在校验「调用方是不是被授权的」而调用方最终要访问的模型服务需要一个稳定的 Base URL 和 Key。如果每个客户端各自配一套Key 散落各处一旦要轮换就得挨个改很容易漏。所以我选择把认证和调用都收敛到 TaoToken 这一层。TaoToken 在这里扮演的角色是统一的 Key/API 通道你拿到一个 Key配一个 Base URL所有支持自定义端点的客户端都能接进来。对 OpenClaw 来说网关的认证 Token 用于保护网关本身而网关背后真正调模型时用的凭据走 TaoToken 的通道。这样职责是分开的——gateway.auth.mode管「谁能调我的网关」TaoToken 的 Key 管「网关能调哪些模型」。前置准备分三步。第一步拿到 TaoToken 的 API Key。访问 API Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite登录后在控制台里创建一个新 Key复制出来先存到安全的地方。这个 Key 就是后面配置里要填的凭据值。第二步确认 Base URL。TaoToken 的 API 入口是https://taotoken.net/api注意这个地址不带任何查询参数配置时原样填入即可。很多客户端要求 Base URL 以/v1结尾或者不带/v1具体看客户端要求OpenClaw 这边按它文档里对 OpenAI 兼容端点的要求填。第三步确认你要用的 Model ID。不同客户端对模型名的写法要求不一样有的要claude-sonnet-4-5这种有的要带前缀。建议先在模型对话页确认一下当前可用的模型标识https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite在对话页里选一个模型发一条消息确认通道是通的同时记下这个模型的准确 ID。这一步别跳过后面配置里 Model ID 写错报错会变成另一种反而更难查。如果你打算长期用 OpenClaw 跑编码类任务或者 Agent 流程可以考虑 Coding Plan它更适合高频调用场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite前置准备做完你手里应该有三样东西一个 TaoToken Key、Base URLhttps://taotoken.net/api、一个确认可用的 Model ID。这三样就是后面配置的核心素材。顺便提一句如果你用的是 Claude Code 这类工具它的接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有针对不同客户端的配置示例可以对照着看。3. 可复制的 auth.json 与 gateway.auth.mode 配置片段这一节是重点直接给能复制粘贴的配置。OpenClaw 的配置文件通常叫auth.json也可能在~/.openclaw/目录下具体路径以你安装时的文档为准。我这边是放在~/.openclaw/auth.json。先看修复gateway.auth.mode缺失的核心片段。这个配置解决的是「网关不知道用什么模式校验」的问题{ gateway: { auth: { mode: token, token: 在这里填入你的网关认证令牌 } } }mode填token表示用令牌模式校验token是网关自己的认证令牌用于保护网关接口。这个令牌和 TaoToken 的 Key 是两回事别混用。网关令牌建议用随机值生成openssl rand -hex 32生成出来的一长串十六进制就是网关令牌填到上面token字段里。客户端调用网关时请求头要带上这个令牌。接下来是把认证入口指向 TaoToken 通道的部分。OpenClaw 背后调模型时需要知道往哪发、用什么 Key、用哪个模型。这部分配置通常和网关认证放在同一个文件里或者单独一个 provider 配置段{ gateway: { auth: { mode: token, token: 你的网关认证令牌 } }, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: 你的TaoToken Key, model: 你的Model ID } } }这里三件套齐了Base URL 是https://taotoken.net/apiapiKey 是你在 API Keys 页创建的那个model 是你在对话页确认过的 Model ID。这三个字段缺一个调用就会失败而且报错各不相同——缺 Base URL 通常是连接错误缺 Key 是 401缺 Model 是模型不存在之类的错误。如果你更习惯用环境变量而不是写死在文件里可以这样导出export OPENCLAW_GATEWAY_TOKEN你的网关认证令牌 export TAOTOKEN_API_KEY你的TaoToken Key然后在配置里用占位符引用环境变量。这种方式的好处是配置文件可以进版本库而不用担心泄露 Key。不过要注意环境变量方式需要确保启动网关的进程能读到这些变量如果你用 systemd 或者容器启动得在对应的 service 文件或 compose 文件里声明。配置改完重启网关让配置生效openclaw gateway restart重启后先别急着测跑一下诊断命令看看配置完整性openclaw doctor这个命令会检查常见配置项包括认证配置是否完整。如果它提示认证相关字段缺失就回到上面核对。诊断通过后再进入下一步验证。有一点要提醒gateway.auth.mode这个字段的值不是随便填的具体支持哪些模式以你当前版本的官方文档为准。我这边用的是token模式如果你看到文档里还有别的模式按文档填。填错模式值可能导致网关启动失败或者行为异常所以改完一定要看启动日志。4. 用 curl 验证 Unauthorized 是否消失、鉴权是否通过配置改完、网关重启、doctor 通过之后就到了最关键的一步实际发一个请求确认 401 真的消失了。这一步不能省因为配置文件的语法正确不代表运行时行为正确只有真实请求才能证明鉴权链路通了。先确认网关在监听。假设你的网关监听在本地 8080 端口具体端口看你的配置先看进程状态openclaw gateway status输出里应该能看到 running 和监听的地址端口。然后发一个带认证头的请求curl -i -X POST http://127.0.0.1:8080/v1/chat/completions \ -H Authorization: Bearer 你的网关认证令牌 \ -H Content-Type: application/json \ -d { model: 你的Model ID, messages: [ {role: user, content: ping} ] }这里有几个点要盯住。第一Authorization头里的令牌是网关认证令牌不是 TaoToken 的 Key这两个别搞混。第二model字段填的是你在 TaoToken 通道确认过的 Model ID。第三URL 路径/v1/chat/completions是 OpenAI 兼容格式如果你的 OpenClaw 版本用的是别的路径按文档改。如果一切正常你会看到类似这样的响应{ id: chatcmpl-xxxx, object: chat.completion, choices: [ { index: 0, message: { role: assistant, content: pong }, finish_reason: stop } ] }HTTP 状态码应该是 200不再是 401。看到choices数组里有内容返回说明整条链路通了网关认证通过 → 转发到 TaoToken 通道 → 模型返回结果 → 网关回传。如果还是 401先别改客户端回到服务端检查。用-i参数看完整响应头确认返回的确实是 401 而不是别的。如果返回的是 403那可能是权限问题而不是认证问题方向不同。如果返回 200 但choices是空的或者报模型错误那说明网关认证过了但 TaoToken 通道那边有问题检查 Base URL、Key、Model ID 三件套。再给一个不带认证头的对照请求确认网关确实在保护接口curl -i -X POST http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model: 你的Model ID, messages: [{role: user, content: ping}]}这个请求应该返回 401因为没带认证头。如果它返回 200说明你的网关认证没生效gateway.auth.mode可能没被正确加载回去检查配置文件的路径和格式。两个请求一对比就能确认认证机制在正常工作带令牌的通过不带令牌的被拒。这就是我们要的结果。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth配置过程中踩的坑不止一个这里把几个高频报错和对应排查方法列出来方便你对照。401 Unauthorized 反复出现。最常见的原因是gateway.auth.mode没配或者配错其次是客户端请求头里的令牌和服务端配置的不一致。排查顺序先确认配置文件里gateway.auth.mode存在且值正确再确认gateway.auth.token或环境变量OPENCLAW_GATEWAY_TOKEN已设置最后确认客户端请求头Authorization: Bearer xxx里的 xxx 和服务端一致。三处都对还 401跑openclaw doctor看有没有别的提示。local proxy failed。这个报错通常出现在网关尝试转发请求到上游时。如果你把认证入口指向了 TaoToken 通道但 Base URL 写错或者网络不通就会看到这个。检查baseUrl是不是https://taotoken.net/api注意不要多加斜杠或者路径。另外确认网关所在机器能正常访问外网如果是容器环境检查容器的网络配置。reading choices 相关报错。这个一般是在解析上游返回时出的问题常见原因是 Model ID 写错导致上游返回的不是标准的 chat completion 格式网关解析choices字段时失败。回到模型对话页确认 Model ID 的准确写法注意大小写和连字符。另外确认 Base URL 指向的是 OpenAI 兼容端点如果指向了别的格式的端点返回结构对不上也会报这个。OAuth 相关报错。如果你在配置里看到 OAuth 字样说明当前认证模式可能被设成了 OAuth 而不是 token。检查gateway.auth.mode的值如果你只是想用简单的令牌认证确保它填的是token。如果你确实需要 OAuth那配置会更复杂需要额外的 client id、secret 等字段按官方文档补齐。混用模式是常见错误——mode 填了 token 但配置里残留 OAuth 字段或者反过来。配置改了但没生效。OpenClaw 的配置加载时机很关键改完auth.json必须重启网关。如果你只 reload 没 restart可能旧配置还在内存里。用openclaw gateway restart确保完全重启。另外确认你改的配置文件路径和网关实际加载的路径一致有些安装方式会有多个配置位置改错了地方自然不生效。CC Switch / Cline MCP / Codex auth.json 场景。如果你是通过这些工具间接调用 OpenClaw配置要写全三件套Base URL、Key、Model ID。以 Codex 的auth.json为例它需要知道往哪个端点发请求、用什么 Key、用哪个模型。这三个字段任何一个缺失或写错都会导致调用失败。CC Switch 和 Cline MCP 同理它们的配置文件里都要把这三样填完整。特别注意 Base URL 的写法有的工具要求带/v1有的不要求按各工具文档来。排查的时候有个通用思路先确认服务端配置完整mode token再确认客户端凭据正确请求头里的令牌最后确认上游通道通Base URL Key Model。这三层任何一层出问题都会表现为调用失败但报错信息往往只指向最后一层所以要从里往外查。6. 把认证配置固化成部署检查清单解决完这次 401 之后我把认证配置相关的检查项固化成了一个清单每次部署 OpenClaw 网关前过一遍避免再踩同样的坑。清单第一项确认gateway.auth.mode已在配置文件中明确设置。这一项是根本缺了它后面全白搭。第二项确认对应的认证令牌已正确配置或通过环境变量导出。第三项确认调用方请求中正确携带了认证凭据服务端和客户端要匹配。第四项网关令牌用随机值生成别用简单默认值。第五项跑openclaw doctor检查配置完整性。第六项生产环境必须配置严格认证不能图方便简化。关于认证入口指向 TaoToken 通道这件事我的经验是把它当成「上游凭据」和「网关凭据」两层来管理。网关凭据保护你的网关接口上游凭据让网关能调模型。两层分开的好处是轮换其中一层不影响另一层。比如网关令牌泄露了换一个网关令牌、更新客户端即可TaoToken 的 Key 不用动反过来 TaoToken Key 要轮换也只改上游配置客户端无感。如果你有多个客户端都要接这个网关统一走 TaoToken 通道的优势会更明显。所有客户端只需要知道网关地址和网关令牌背后的模型通道由网关统一管理。新增一个客户端时不用再单独申请 Key、配 Base URL只要它能连上网关、带上正确的网关令牌就行。这样 Key 的轮换、模型的切换都集中在网关这一层维护成本低很多。最后留一个实用技巧把验证请求写成一个脚本每次改完配置跑一遍。脚本里包含一个带令牌的请求期望 200和一个不带令牌的请求期望 401两个结果都对才说明认证配置正确。这样比手动敲 curl 可靠也不容易漏掉对照测试。脚本可以长这样#!/bin/bash GATEWAYhttp://127.0.0.1:8080/v1/chat/completions TOKEN你的网关认证令牌 MODEL你的Model ID echo 带令牌请求期望 200: curl -s -o /dev/null -w %{http_code}\n -X POST $GATEWAY \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {\model\: \$MODEL\, \messages\: [{\role\: \user\, \content\: \ping\}]} echo 不带令牌请求期望 401: curl -s -o /dev/null -w %{http_code}\n -X POST $GATEWAY \ -H Content-Type: application/json \ -d {\model\: \$MODEL\, \messages\: [{\role\: \user\, \content\: \ping\}]}跑出来两个数字第一个是 200、第二个是 401就说明认证链路完全正常。这个脚本我放在部署目录里每次改配置都跑一次几秒钟的事比事后排查省心得多。