1. OpenClaw 启动报 unauthorizedgateway password missing 到底卡在哪你敲下openclaw gateway终端里日志一行行刷过去最后停在Gateway listening on 127.0.0.1:18789看起来一切正常。接着你打开浏览器访问http://127.0.0.1:18789/Control UI 界面是出来了但顶部或对话区飘着一行红色报错unauthorized: gateway password missing (enter the password in Control UI settings)。终端没报错、进程没退出、端口也在监听可你就是连不上、发不出消息——这是 OpenClaw 新手最容易被绊住的一类假成功。这个报错的本质不是服务没起来而是认证层没对齐。OpenClaw 的 gateway 在启用密码认证后会要求每一个接入方包括它自带的 Control UI都出示同一个密码。终端启动时你通过命令行参数或配置文件给了 gateway 一个密码但 Control UI 是独立的前端页面它并不知道这个密码需要你在界面里手动填一次。两边对不上gateway 就回一个unauthorized前端把它渲染成红色提示。这篇面向的就是 Control UI 用户你已经能启动 gateway但卡在 UI 登录这一步。我会把openclaw.json里gateway.auth.password的配置骨架完整给出来再带你走一遍复制密码 → UI 粘贴 → 连接 → 刷新 → 验证对话的闭环最后把几个高频坑一次性排掉。全程本地操作不需要任何额外网络工具照着做就能恢复服务。适合谁看刚装完 OpenClaw、第一次跑 gateway 的人改了openclaw.json后 UI 突然连不上的人以及把 OpenClaw 当本地 Agent 跑、需要 Control UI 做对话调试的人。如果你连 gateway 都还没启动成功那属于另一个问题本文假设终端已经能正常监听端口。2. 前置TaoToken 与 OpenClaw 的模型接入准备OpenClaw 本身是网关和 Control UI 的壳真正干活的是背后接的大模型。很多人卡在unauthorized之后紧接着就会遇到连上了但模型调不通所以这里先把模型侧的 Key 准备好避免来回折腾。我用的方式是走 TaoToken 的兼容接口。它的 API 地址是https://taotoken.net/api兼容主流大模型的调用格式OpenClaw 这类工具只要填 base URL 和 Key 就能接。你需要先去控制台拿一个 API Key再决定用哪个模型。拿 Key 的入口在控制台的 API Keys 页面登录后新建一个即可。如果你还没账号从官网进https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册和拿 Key 的过程不复杂这里不展开重点放在配置上。拿到 Key 之后OpenClaw 侧一般有两种接法一种是在openclaw.json的模型配置段里写baseUrl和apiKey另一种是在 Control UI 的设置里填。两种都行但建议统一写在配置文件里方便版本管理和迁移。下面给一个模型段的骨架字段名以你实际版本为准核心是baseUrl指向https://taotoken.net/apiapiKey填你刚拿到的值。{ models: { default: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, model: claude-sonnet-4-5 } } }这里要提醒一句baseUrl只写到/api不要自己拼/v1/chat/completions之类的路径OpenClaw 和兼容层会自己补。模型名按你实际想用的填不同模型在 Control UI 里的表现差异主要看上下文长度和工具调用能力。如果你打算长期跑编码类 Agent 任务可以关注 Coding Plan 的额度方案入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 只是临时验证模型通不通用模型对话页更快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。模型侧准备好回到 gateway 认证这条主线。记住一个原则gateway 密码和模型 API Key 是两码事。前者管的是谁能连上这个本地网关后者管的是网关拿什么去调模型。unauthorized: gateway password missing说的是前者别把 TaoToken 的 Key 填到 gateway 密码框里那只会让你更困惑。3. 可复制配置openclaw.json 的 gateway 密码字段骨架现在进入正题。先找到你的openclaw.json。默认位置通常在用户目录下的.openclaw/openclaw.json也可能是项目根目录取决于你启动时的工作目录。用编辑器打开定位到gateway这一段。一个能触发unauthorized: gateway password missing的典型配置长这样gateway里开了认证但密码字段缺失或为空。修复的核心就是补上auth.password。下面给一份完整的可复制骨架你按自己的端口和密码替换即可。{ gateway: { host: 127.0.0.1, port: 18789, auth: { mode: password, password: my-local-gateway-pass-2024 } } }几个字段逐个说清楚host建议保持127.0.0.1只监听本机避免把网关暴露到局域网。port默认18789如果你改过UI 地址也要跟着改。auth.mode设为password表示启用密码认证如果你设成none理论上不会报这个错但也不安全不推荐。auth.password就是关键它必须是一个非空字符串且要和你在 Control UI 里填的完全一致。密码怎么设别用123456这种也别用带特殊符号导致 JSON 转义出错的字符。建议用字母加数字的组合长度 16 位以上。上面示例里的my-local-gateway-pass-2024只是占位你换成自己的。注意 JSON 里字符串要用双引号密码里如果含或\需要转义省事的做法是避开这两个字符。如果你之前是用命令行参数启动的比如openclaw gateway --auth password那密码可能是启动时随机生成或从环境变量读的。这种情况下配置文件里可能没有明文密码你需要确认密码来源。最稳妥的做法是统一在openclaw.json里写死密码启动命令不再带--auth相关参数避免两处配置打架。改完配置后先别急着启动用编辑器自带的 JSON 校验或python -m json.tool openclaw.json检查一下语法一个多余的逗号就能让 gateway 读不到密码。python -m json.tool openclaw.json这条命令能正常输出格式化后的 JSON说明语法没问题如果报Expecting property name之类就是括号或逗号错了先修好再往下走。4. 重启验证与 Control UI 登录确认配置改完接下来是重启和验证。顺序很重要先停掉旧进程再启动新的最后去 UI 填密码。第一步停掉正在跑的 gateway。如果你是在前台终端跑的直接CtrlC。如果是后台或用了进程管理找到进程杀掉ps aux | grep openclaw kill PID确认端口释放可以顺手查一下lsof -i :18789没有输出说明端口空了。第二步重新启动openclaw gateway观察终端日志应该能看到 gateway 正常监听且不再有认证相关的警告。如果日志里出现auth mode: password之类的字样说明配置被读到了。第三步打开 Control UIhttp://127.0.0.1:18789/。这时候红色报错可能还在别慌因为 UI 还没拿到密码。找到设置里的【密码(不存储)】输入框——不同版本位置略有差异一般在设置面板或连接配置区。把openclaw.json里auth.password的值原样复制过去注意不要多复制空格或换行。粘贴后点击【连接】再点【刷新】。如果一切正常红色报错会消失界面进入可用状态。这时候发一条测试消息比如你好做个自我介绍看是否有正常回复。有回复说明 gateway 认证和模型调用两条链路都通了。如果报错消失但消息发不出去那问题就转移到模型配置上回到第 2 节检查baseUrl和apiKey。这里有个细节Control UI 的密码框标注不存储意味着刷新页面或重开浏览器后可能需要重新填。这是设计如此不是 bug。如果你嫌麻烦可以在浏览器里保存该站点的密码或者确认你的 OpenClaw 版本是否支持会话保持。但无论如何配置文件里的密码才是源头UI 里填的只是本次会话的凭证。验证成功的标志很明确红色unauthorized消失 能正常对话。两个都满足这条报错就算彻底解决了。5. 本篇常见错排查密码对了还是 unauthorized 怎么办即使按上面做了还是有人会卡住。下面这几个是我见过最高频的坑逐个排。坑一配置文件改了但没重启。OpenClaw 的 gateway 一般在启动时读取openclaw.json运行中改文件不会热加载。你改完密码必须重启进程否则读的还是旧配置。判断方法重启后看日志里有没有打印当前 auth 模式。坑二命令行参数覆盖了配置文件。如果你启动时带了--auth password或类似参数它可能优先于配置文件导致你改openclaw.json不生效。解决办法是启动命令保持干净只写openclaw gateway所有认证配置都放文件里。坑三密码里有隐藏字符。从配置文件复制时容易带上行尾空格或不可见字符。UI 里粘贴后gateway 比对失败依旧unauthorized。建议手动重新输入一遍或者复制后用编辑器查看是否有异常空白。坑四UI 地址或端口不对。如果你改过gateway.port但浏览器还开着旧的18789那连的是另一个进程或根本连不上。确认 UI 地址和配置文件里的port一致。坑五把模型 Key 填进了 gateway 密码框。前面强调过这两个不是一回事。gateway 密码是你自己在openclaw.json里设的TaoToken 的 Key 是给模型用的。填错了自然过不了认证。坑六JSON 语法错误导致整段配置被忽略。一个多余的逗号会让解析失败gateway 可能回退到默认无密码模式或直接报别的错。用第 3 节的json.tool先校验。如果以上都排除了还是不行可以打开浏览器开发者工具看 Network 面板找到返回401的那个请求看响应体里的具体错误信息。unauthorized: gateway password missing和unauthorized: invalid password是两种不同情况前者是没提供后者是提供了但不匹配。对症下药前者检查 UI 有没有填后者检查两边值是否完全一致。6. 接入与排障的后续入口走到这里unauthorized: gateway password missing应该已经解决了。如果你在配置模型或调 API 时遇到问题比如 Key 无效、模型名不对、请求超时可以直接去 API Keys 页面核对密钥状态或者翻接入文档确认参数格式。这两个入口分别是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 和 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你只是想快速验证某个模型能不能用、回复质量如何不必折腾 OpenClaw直接在模型对话页试更省事https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。而如果你打算把 OpenClaw 长期当编码 Agent 用频繁跑任务那 Coding Plan 的额度方案会比按量更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个我自己的习惯每次改完openclaw.json先跑python -m json.tool校验再重启再去 UI 填密码三步固定下来基本不会再被unauthorized绊住。密码统一放配置文件、启动命令保持干净这两条守住后面换模型、加 Agent 都省心。