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 参数?token=xxx传入，或者由openclaw dashboard命令自动拼接到链接里。两边必须完全相等，包括大小写和连字符。

我见过最多的坑就是：网关重启后 token 变了，但浏览器书签里存的还是老链接。OpenClaw 每次gateway restart都有可能重新生成 token，尤其是你执行过doctor --generate-gateway-token之后。所以排查第一步永远是——先确认当前网关到底在用哪个 token。

在动手之前，你需要准备好这几样东西：一个能正常运行的 OpenClaw 环境（本地或 Docker 都行）、终端访问权限、以及一个现代浏览器。如果你还没装 OpenClaw，先去官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 看一下接入说明，把基础环境跑起来。另外，如果你打算把 OpenClaw 接到大模型上做编码或 Agent 任务，建议顺手在 https://taotoken.net/api 申请一个 API Key，后面配置模型时会用到，省得来回折腾。

前置检查清单如下，建议逐条过一遍：

这里要特别提醒一句：不要直接去访问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_PORT=18789 - 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 dashboard

openclaw dashboard会自动读取当前网关的 token，拼成http://localhost:18789?token=xxx并在默认浏览器打开。这一步能解决 80% 的 1008，因为浏览器拿到的永远是最新 token。

如果 dashboard 命令没反应，或者你想手动控制，那就走手动流程：

# 获取当前 token openclaw gateway token # 手动拼接 URL（把 xxx 换成上面输出的 token） # http://localhost:18789?token=xxx

还有一种情况是配置被改乱了，这时候用内置诊断工具自动修复：

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/api，Key 用你申请的令牌，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 面板，筛选 WS（WebSocket）。你会看到一条到localhost:18789的连接，状态应该是101 Switching Protocols，这就是握手成功。如果看到1008，说明 token 还是不对，回到上一节重新核对。

再切到 Console 面板，正常情况下不应该有红色报错。如果之前有disconnected (1008)，修复后刷新页面，这条错误应该消失，控制台界面正常加载出来。

我实测下来，最可靠的验证方式是"改 token → 重启 → 重新打开 dashboard"这个闭环。具体命令序列：

openclaw gateway restart sleep 5 openclaw gateway token openclaw dashboard

restart后等 5 秒是给网关留出初始化时间，太急着打开可能连不上。gateway token确认当前值，dashboard用最新值打开。三步走完，如果控制台正常显示，就说明 1008 彻底解决了。

还有一个细节：如果你之前用旧链接访问过，浏览器可能缓存了旧的 WebSocket 连接或 token。这时候强制刷新（Ctrl+F5）或者开无痕窗口再试一次。无痕窗口能排除缓存干扰，是排查认证问题的好帮手。

验证通过后，建议把当前 token 记下来，或者写进密码管理器。因为下次网关重启 token 可能又变，有记录的话排查会快很多。你也可以写个小脚本，每次重启后自动打印新 token 并打开 dashboard，这个后面会讲。

5. 本篇常见错误排查对照

即使按上面的步骤走，还是可能遇到各种变体错误。这一节我把高频报错和对应解法列出来，方便你对号入座。

报错一：disconnected (1008): unauthorized: gateway token missing

注意这里是missing不是mismatch。意思是请求里压根没带 token。原因通常是你直接访问了http://localhost:18789裸地址，没有?token=xxx参数。解法很简单，用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-restart='openclaw 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/api，Key 和 Model ID 按文档填，这部分配好后基本不用动。网关 token 则是每次重启都可能变，需要动态获取。

如果你打算长期用 OpenClaw 跑编码或 Agent 任务，建议了解一下 Coding Plan，把常用的模型和额度规划好，避免临时抓瞎。地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有详细的套餐说明。

最后说个我踩过的坑：有次我改了openclaw.json里的 token，但忘了同步remote.token，结果网关自己内部就不一致，dashboard 打开也是 1008。后来用openclaw doctor --fix一键修复才发现是这两个字段不同步。所以改配置时，两个 token 字段要么一起改，要么用工具改，别手动只动一个。

按这套流程走下来，1008 基本不会再成为你的拦路虎。真遇到了，回到第 3 节复制命令，十分钟内能解决。