1. 从一次真实的 1008 报错说起如果你正在本地跑 OpenClaw浏览器打开http://localhost:18789却看到控制台刷出disconnected (1008): unauthorized: gateway token mismatch那你来对地方了。这个错误说白了就是一句话你的网关令牌gateway token对不上被拒绝连接了。OpenClaw 的 Web 控制台和本地网关之间走的是 WebSocket Token 校验只要两边持有的 token 不一致握手阶段就会直接返回 1008 关闭码页面表现为空白、转圈或者干脆提示未授权。我先把结论摆出来1008 不是网络问题也不是端口没通而是认证层的问题。很多人第一反应是去查防火墙、换端口、重启电脑方向就错了。真正要盯的是三个地方——网关进程当前持有的 token、浏览器 URL 里携带的 token、以及配置文件里写死的 token这三者只要有一个对不上1008 必然出现。这个错误的高频触发场景其实很集中网关重启后自动生成了新 token但你还在用旧链接或者你手动改过openclaw.json里的auth.token却没同步更新remote.token再或者 Docker 环境里用环境变量覆盖了配置文件两边打架。理解了这个机制排查就有了主线。下面我会从 token 校验原理讲起把触发点一个个拆开然后给你可以直接复制的配置片段和验证命令。整套流程我在本地环境反复跑过从定位到修复基本十分钟内能搞定。适合刚接触 OpenClaw 的新手也适合被这个错误反复折磨的老用户。2. OpenClaw 网关 token 校验机制与前置准备要修 1008先得搞明白 OpenClaw 的认证是怎么设计的。OpenClaw 的 Web Dashboard 和 Gateway 之间不是简单的 HTTP 请求而是建立了一条 WebSocket 长连接。连接建立时客户端浏览器需要携带一个 token网关收到后会和自己配置里的 token 做比对一致才放行不一致就返回 1008 并断开。这里有个关键点容易被忽略token 有两个来源。一个是网关侧存在~/.openclaw/openclaw.json的gateway.auth.token字段里或者由环境变量OPENCLAW_GATEWAY_TOKEN注入另一个是浏览器侧通常通过 URL 参数?tokenxxx传入或者由openclaw dashboard命令自动拼接到链接里。两边必须完全相等包括大小写和连字符。我见过最多的坑就是网关重启后 token 变了但浏览器书签里存的还是老链接。OpenClaw 每次gateway restart都有可能重新生成 token尤其是你执行过doctor --generate-gateway-token之后。所以排查第一步永远是——先确认当前网关到底在用哪个 token。在动手之前你需要准备好这几样东西一个能正常运行的 OpenClaw 环境本地或 Docker 都行、终端访问权限、以及一个现代浏览器。如果你还没装 OpenClaw先去官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 看一下接入说明把基础环境跑起来。另外如果你打算把 OpenClaw 接到大模型上做编码或 Agent 任务建议顺手在 https://taotoken.net/api 申请一个 API Key后面配置模型时会用到省得来回折腾。前置检查清单如下建议逐条过一遍检查项命令预期结果网关是否运行openclaw gateway status显示 running当前 tokenopenclaw gateway token输出一串 UUID配置文件位置ls ~/.openclaw/openclaw.json文件存在端口占用lsof -i :18789只有 openclaw 进程这里要特别提醒一句不要直接去访问http://localhost:18789裸地址。裸地址不带 token网关无法完成校验1008 是必然的。正确姿势是用openclaw dashboard命令它会自动读取当前 token 并生成带参数的完整 URL。很多人第一次踩坑就是因为手动敲了裸地址然后以为服务坏了。理解了这套机制后面的排查就是按图索骥。token 不匹配的触发点虽然多但归类下来无非就是网关侧变了浏览器侧旧了配置打架了这三类。下一节我给出可直接复制的配置片段把这三类问题一次性覆盖。3. 可复制的 gateway 配置片段与修复步骤这一节是全文的核心我按先看配置、再改配置、最后验证的顺序来。所有片段都可以直接复制路径和字段名保持和 OpenClaw 默认一致。先看默认的配置文件结构。打开~/.openclaw/openclaw.json你会看到类似这样的内容{ gateway: { port: 18789, auth: { mode: token, token: 35fxxxd4-xxxx-xxxx-xxxx-xxxxxxxxxxxx } }, remote: { token: 35fxxxd4-xxxx-xxxx-xxxx-xxxxxxxxxxxx } }注意gateway.auth.token和remote.token这两个字段。它们必须一致否则网关内部自己就会打架。我遇到过有人只改了其中一个结果 1008 反复出现查了半天才发现是这里不同步。如果你用的是 Docker配置可能通过环境变量注入这时候要格外小心覆盖问题。下面是一个可用的docker-compose.yml片段version: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw ports: - 18789:18789 volumes: - ./data:/app/data - ./config:/app/config environment: - OPENCLAW_GATEWAY_PORT18789 - OPENCLAW_GATEWAY_TOKEN${GATEWAY_TOKEN} restart: unless-stopped启动前先生成 token 并导出export GATEWAY_TOKEN$(openssl rand -hex 32) docker-compose up -d这样环境变量和容器内配置就统一了不会出现两边 token 不一致的情况。接下来是修复动作。最省事、成功率最高的方法是直接用官方命令重新拉起 Dashboard# 1. 确认网关在跑 openclaw gateway status # 2. 重新生成带最新 token 的链接并打开 openclaw dashboardopenclaw dashboard会自动读取当前网关的 token拼成http://localhost:18789?tokenxxx并在默认浏览器打开。这一步能解决 80% 的 1008因为浏览器拿到的永远是最新 token。如果 dashboard 命令没反应或者你想手动控制那就走手动流程# 获取当前 token openclaw gateway token # 手动拼接 URL把 xxx 换成上面输出的 token # http://localhost:18789?tokenxxx还有一种情况是配置被改乱了这时候用内置诊断工具自动修复openclaw doctor --fix这个命令会检查网关状态、校验 token 配置、修复不匹配项然后重启网关。修完再执行一次openclaw dashboard即可。如果你在本地开发环境实在不想被 token 折腾可以临时关闭校验仅限本地 127.0.0.1生产环境绝对不要这么干{ gateway: { port: 18789, auth: { mode: none } } }改完保存执行openclaw gateway restart然后直接访问http://localhost:18789就能进。但记住这个口子一开任何能访问该端口的程序都能控制你的 OpenClaw风险自负。配置改完后别忘了检查一下模型接入部分。如果你打算用 OpenClaw 做编码或 Agent 任务模型 ID 和 Base URL 也要配对。可以参考 https://taotoken.net/api 的文档把 Base URL 指向https://taotoken.net/apiKey 用你申请的令牌Model ID 按需选择。这三件套Base URL Key Model ID缺一不可配错了虽然不会报 1008但会报别的错排查起来一样头疼。4. 验证请求与成功结果确认配置改完不代表万事大吉必须实际发一次请求验证。这一步很多人跳过结果以为修好了过两天又冒出来。我习惯用命令行 浏览器双重验证确保网关侧和客户端侧都正常。先看命令行验证。OpenClaw 提供了状态查询和日志查看这是最直接的证据# 查看网关状态确认 running openclaw gateway status # 实时看日志观察连接过程 openclaw gateway logs -f正常启动后gateway status应该输出类似Runtime: running RPC probe: success Port: 18789如果显示stopped说明网关根本没起来先解决启动问题再谈 token。然后打开浏览器用openclaw dashboard生成的链接访问。按 F12 打开开发者工具切到 Network 面板筛选 WSWebSocket。你会看到一条到localhost:18789的连接状态应该是101 Switching Protocols这就是握手成功。如果看到1008说明 token 还是不对回到上一节重新核对。再切到 Console 面板正常情况下不应该有红色报错。如果之前有disconnected (1008)修复后刷新页面这条错误应该消失控制台界面正常加载出来。我实测下来最可靠的验证方式是改 token → 重启 → 重新打开 dashboard这个闭环。具体命令序列openclaw gateway restart sleep 5 openclaw gateway token openclaw dashboardrestart后等 5 秒是给网关留出初始化时间太急着打开可能连不上。gateway token确认当前值dashboard用最新值打开。三步走完如果控制台正常显示就说明 1008 彻底解决了。还有一个细节如果你之前用旧链接访问过浏览器可能缓存了旧的 WebSocket 连接或 token。这时候强制刷新CtrlF5或者开无痕窗口再试一次。无痕窗口能排除缓存干扰是排查认证问题的好帮手。验证通过后建议把当前 token 记下来或者写进密码管理器。因为下次网关重启 token 可能又变有记录的话排查会快很多。你也可以写个小脚本每次重启后自动打印新 token 并打开 dashboard这个后面会讲。5. 本篇常见错误排查对照即使按上面的步骤走还是可能遇到各种变体错误。这一节我把高频报错和对应解法列出来方便你对号入座。报错一disconnected (1008): unauthorized: gateway token missing注意这里是missing不是mismatch。意思是请求里压根没带 token。原因通常是你直接访问了http://localhost:18789裸地址没有?tokenxxx参数。解法很简单用openclaw dashboard打开或者手动拼上 token。报错二disconnected (1008): unauthorized: gateway token mismatch这就是本文主角token 带了但对不上。按第 3 节流程先openclaw gateway token看当前值再核对浏览器 URL 里的值不一致就重新生成链接。如果两边看起来一样还是报错检查有没有多余空格或换行复制粘贴时很容易带上。报错三ECONNREFUSED 127.0.0.1:18789这个不是 1008是连接被拒绝说明网关没在监听 18789。先openclaw gateway status确认进程状态没起来就openclaw gateway start。如果启动失败看日志里有没有端口占用lsof -i :18789有别的进程占着就杀掉或者改配置换端口。报错四4008 port already in use端口冲突。解法同上找到占用进程处理掉或者把gateway.port改成别的值比如 18790然后重启。报错五1006 connection closed abnormally这个和 token 无关是连接异常断开。常见于网关进程崩溃、系统休眠后网络中断。重启网关通常能解决。如果频繁出现检查系统资源是否吃紧。报错六Docker 环境下 token 反复不匹配这是环境变量和配置文件打架的典型。检查docker-compose.yml里的OPENCLAW_GATEWAY_TOKEN和挂载的openclaw.json里的 token 是否一致。建议只保留一种来源要么全用环境变量要么全用配置文件别混着来。报错七OAuth相关认证失败如果你在 OpenClaw 里接了需要 OAuth 的模型服务token 过期也会报认证错误但错误码通常不是 1008。这时候去对应服务的控制台重新授权或者换用 API Key 方式接入。用 TaoToken 的话直接在 https://taotoken.net/api-keys 生成 Key配置到 OpenClaw 的模型设置里就行比 OAuth 省心。排查时有个通用技巧先看错误码再看错误信息最后看日志。1008 系列基本都是 token 问题1006 是连接问题ECONNREFUSED 是进程问题。分类清楚了解决就快。6. 稳定复现与长期使用建议修好一次不难难的是让它别再犯。我在本地环境反复折腾后总结了几条实用经验能帮你把 1008 的出现频率降到最低。第一条永远用openclaw dashboard打开控制台别存书签。书签里存的是旧 token网关一重启就失效。养成用命令打开的习惯token 永远是最新的。第二条网关重启后主动刷新。如果你有脚本或定时任务会重启网关重启后记得重新执行openclaw dashboard。可以写个别名简化操作alias oc-restartopenclaw gateway restart sleep 5 openclaw dashboard这样一条命令搞定重启和打开省得手动两步。第三条Docker 环境统一 token 来源。要么全用环境变量要么全用挂载配置文件别两边都写。我推荐环境变量方式因为docker-compose.yml里一眼能看到不容易漏。第四条定期备份配置。~/.openclaw/openclaw.json改乱了很麻烦改之前先复制一份cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak出问题直接还原比重头配快得多。第五条把模型接入和网关认证分开排查。1008 是网关层的问题模型报错是应用层的问题两者不要混在一起查。如果你在 OpenClaw 里配了 TaoToken 的模型Base URL 用https://taotoken.net/apiKey 和 Model ID 按文档填这部分配好后基本不用动。网关 token 则是每次重启都可能变需要动态获取。如果你打算长期用 OpenClaw 跑编码或 Agent 任务建议了解一下 Coding Plan把常用的模型和额度规划好避免临时抓瞎。地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有详细的套餐说明。最后说个我踩过的坑有次我改了openclaw.json里的 token但忘了同步remote.token结果网关自己内部就不一致dashboard 打开也是 1008。后来用openclaw doctor --fix一键修复才发现是这两个字段不同步。所以改配置时两个 token 字段要么一起改要么用工具改别手动只动一个。按这套流程走下来1008 基本不会再成为你的拦路虎。真遇到了回到第 3 节复制命令十分钟内能解决。