部署OpenClaw的时候最闹心的不是功能不会用而是服务跑着跑着突然给你来一句disconnected (1008): unauthorized: gateway token。我第一次遇到这个报错的时候把网络排查了个遍以为是代理、是防火墙折腾半天才发现问题出在网关令牌上。这篇文章就把这个报错从原理到解法完整梳理一遍顺便把OpenClaw部署中常见的401、stream disconnected、session file locked这些同族病一起讲清楚如果你正在折腾OpenClaw建议先收藏再慢慢看。1. 先把问题定性1008不是网络断了是门禁卡被拒1.1 WebSocket 1008状态码到底在说什么WebSocket协议里关闭连接时会带一个状态码。1008这个码的意思是Policy Violation也就是服务端在握手或通信过程中发现客户端违反了策略主动把连接掐断。这个策略可能是消息格式不对、权限不足、认证失败等等。而在OpenClaw的场景里出现1008并且错误文本带unauthorized基本就能锁定是认证环节出了问题而不是网络不稳定。很多朋友一看到disconnected就以为是网断了去查防火墙结果方向完全错了。这里要解释一下WebSocket连接建立后如果服务端在认证检查中发现token无效最好的处理方式就是直接关闭连接并返回1008。客户端看到的报错就是disconnected (1008): unauthorized后面的gateway token字样是OpenClaw自己在错误信息里补充的告诉你具体是哪个环节认证失败。整个过程其实不是在通信中被踢掉而是在握手时就没被放进来这是理解这个报错最关键的一点。1.2 gateway token就是OpenClaw的门禁卡OpenClaw的架构里通常会有一个gateway网关服务负责把各类客户端连到核心代理。无论是命令行工具、Web界面还是第三方平台比如Teams、Obsidian插件本质上都要通过这个gateway跟OpenClaw核心通信。gateway token就是这个通信的凭证你可以把它想成小区门禁卡卡对了大门随便进卡错了、卡过期了门禁系统直接把你拦在外面并且明确告诉你unauthorized。token失效的核心原因通常是这么几类第一配置里根本没设置token服务端用的空值客户端却带了token或者反过来第二服务端和客户端配置的token不一致最常见的是改了一遍配置忘了同步第三环境变量覆盖了配置文件里的旧值导致实际生效的token和预期不一致第四部署重启后token被重新生成但客户端还在用旧的。还有一种比较隐蔽的情况是安装脚本或者一键部署工具在初始化时自动生成了一个随机token输出到终端日志里但你当时没注意到。后面你自己去改配置文件以为token是空的需要填一个结果写进去的跟服务端真实生效的完全不是同一个自然怎么连都连不上。1.3 常见的1008 unauthorized触发场景我见过的1008报错十有八九发生在下面几个阶段刚部署完OpenClaw客户端第一次连gateway发现连不上一看日志是token不对。修改了config文件里的token重启服务后客户端没跟着改旧连接还在用旧token。用环境变量设置了OPENCLAW_GATEWAY_TOKEN但环境变量的作用域或优先级搞错了。多实例部署时A实例生成的token拿到B实例去用自然认证失败。这里想强调一个容易被忽略的点很多人都是在改动之后才遇到这个报错。如果你什么都没改之前也连得好好的突然出现1008那优先怀疑是不是服务端token被轮换了或者有定时任务/脚本重置了配置。这类莫名其妙的1008往往比第一次部署时的1008更难排查因为你没动过配置直觉上就会排除token问题。2. 排查步骤五分钟定位token问题2.1 第一步确认服务端配置的token先别急着改配置第一步是确认服务端当前实际生效的token是什么。OpenClaw的配置通常会放在~/.openclaw/config.yaml或者config.json取决于版本和安装方式里面会有类似gateway.token这样的字段。同时还要检查环境变量大多数版本里OPENCLAW_GATEWAY_TOKEN会覆盖配置文件里的token。可以执行一下env | grep OPENCLAW看看当前环境里有没有这个变量。这里强调一点配置文件里的值不一定等于实际生效的值。如果配置文件和环境变量都设置了token很多实现里环境变量优先级更高。所以排查时一定要把配置里的token和环境变量里的token都查一遍确认最终生效的是哪一个。我遇到过的情况是配置文件里是新token环境变量里残留着旧token服务启动时用的是环境变量里的旧值客户端用新token去连直接1008。另一个检查技巧是看服务进程的启动参数或systemd unit文件里的EnvironmentFile指向。如果环境变量是通过EnvironmentFile加载的那改环境变量不是export一下就行得改那个文件再重启服务。很多人在这上面栽过跟头以为export了就生效了实际上服务根本没继承你shell里的环境变量。2.2 第二步确认客户端使用的token服务端查完了接着看客户端。如果用的是OpenClaw自带的命令行客户端token一般通过配置文件或环境变量传入如果是Web界面token可能是在登录时填写的如果是第三方集成比如Teams机器人token可能在集成配置文件或回调地址里。把客户端设置的token和服务端实际生效的token对齐这一步通常能解决80%的问题。实际操作的时候我喜欢把两个token分别存成变量再对比避免肉眼比对时看漏字符。比如echo 服务端token: $SERVER_TOKEN echo 客户端token: $CLIENT_TOKENtoken通常很长复制粘贴的时候容易出现前缀或者末尾少了几个字符。如果你是在终端里手动复制的token建议复制完回头检查一下首尾完整性。我曾经因为复制的时候少了一个末尾字符排查了整整一晚上最后把两个token并列打印出来一对比才发现问题。2.3 第三步看日志确认错误链路如果两边token看起来都对那就需要看日志了。systemd服务的话用journalctl -u openclaw-gateway -f直接跑进程的话在启动终端里就能看到输出。日志里通常会记录类似gateway: authentication failed或token mismatch这样的信息能帮你确认认证失败的详细原因。不看日志直接盲改配置是最容易走弯路的我第一次排查时就是没看日志反复改了好几轮才发现是环境变量在作怪。日志还有一个作用确认服务是否真的重启成功了。有时候你改了配置、重启了服务但旧进程根本没被杀掉端口还是被旧进程占着新配置压根没生效。journalctl里能看到启动时间和进程ID如果时间对不上说明你的重启操作可能没成功。这种情况下1008报错会一直存在但根因根本不是token而是你的新配置没有加载。2.4 需要区分的相近错误401 vs 1008排查的时候经常会把401和1008搞混这里特意说明一下401 Unauthorized通常是HTTP层面的错误出现在调用REST API时比如OpenClaw调用模型服务商的接口返回401 incorrect api key provided。这表示API key不对不是gateway token的问题。1008 unauthorized是WebSocket层面的关闭码出现在客户端连gateway时表示gateway认证失败。两者的处理方向完全不同。热词里那一大串unexpected status 401 unauthorized: incorrect api key provided是模型API的key问题而标题里这个disconnected (1008)是OpenClaw网关的token问题。先分清楚你遇到的到底是哪一个再动手。判断方法也很简单看报错发生的阶段。如果是连接gateway时立刻断开报disconnected那是WebSocket认证问题如果是客户端已经连上、开始发消息时返回401那是模型API调用问题。一个是大门不让进一个是进了门发现房间打不开。3. 完整处理方法从生成token到验证连接3.1 重新生成gateway token如果确认当前token已经不可用比如丢失了、被改了、或者一开始就没配对最干净的办法是重新生成一个token。OpenClaw的CLI通常会提供类似openclaw gateway token create或openclaw gateway token rotate的命令不同版本命令名可能不一样执行openclaw gateway --help就能看到。如果你用的是旧版本也可以直接在配置文件里手动写一串足够随机的字符串比如用openssl rand -hex 32生成。这里要补充一个判断依据token生成后服务端通常会把它持久化到配置里而不是每次启动都重新生成。如果每次重启服务token都变就会导致客户端连接极不稳定这种情况一般是因为配置写入权限有问题比如服务以不同用户运行写不到配置文件导致token无法持久化。我有一个习惯新token生成后第一时间把输出保存到本地的密码管理器里同时把时间戳记下来。这样以后排查的时候能知道这个token是哪一轮换的心里有底。如果你用的是团队共用的服务器最好让运维在配置管理平台里统一记录token的生成历史和有效期避免某个人自己改了token其他同事全被踢下线。3.2 修改配置文件并重启服务拿到新token后把它同步到两个地方一是服务端的配置或环境变量二是客户端的连接配置。修改完后按正确的顺序重启服务先重启gateway服务再重启客户端。注意如果服务是通过systemd管理的改完环境变量或配置文件后建议执行systemctl daemon-reload再restart否则新的环境变量可能不会加载进去。这一步是systemd部署最常见的坑。很多人在这一步犯了顺序错误先重启了客户端再重启服务端结果客户端启动时连的还是旧服务报错信息看起来像是新token也不对。其实换token的正确姿势是服务端先行客户端跟进中间会有一个短暂的服务不可用窗口期这是正常现象。如果你在正式环境里操作可以先在低峰期轮换或者干脆直接让服务端和客户端配置同步更新后同时重启。3.3 用wscat等工具验证网关连通性配置都改完之后别急着启动完整客户端先用WebSocket测试工具验证一下网关是否真的能握手成功。比如用wscat这样的小工具手动连一下wscat -c ws://127.0.0.1:8787/gateway -H Authorization: Bearer 你的token如果握手成功能看到连接建立说明token认证已经通过了问题基本解决。如果返回1008说明token还是不匹配需要回到前面两步重新检查。用这种方式做最小化验证能帮你把OpenClaw业务问题和网络认证问题彻底隔离排查效率会高很多。实际使用wscat的时候有些版本的gateway要求token放在URL参数里而不是Header里格式类似ws://127.0.0.1:8787/gateway?tokenxxx。如果使用Header认证返回1008可以试试URL传参或者反过来。这是不同版本OpenClaw实现差异的问题不要死磕某一种格式多试一次就能确认。3.4 OpenClaw部署中的实践示例systemd env关于openclaw部署我常用的是systemd加环境文件的方式。在/etc/openclaw/env或/etc/default/openclaw里面写好环境变量然后systemd服务引用这个文件。这样配置集中、重启可以持久化、权限也好控制。简单示例如下# /etc/openclaw/env OPENCLAW_GATEWAY_TOKENxxx OPENCLAW_MODEL_API_KEYxxx OPENCLAW_WS_PORT8787systemd单元文件里加上EnvironmentFile-/etc/openclaw/env然后systemctl daemon-reload systemctl restart openclaw-gateway。这个方案处理gateway token这类问题非常直观token变了改一个文件、重启一次服务、客户端同步一次就完事。还要注意文件权限/etc/openclaw/env这个文件建议chmod 600因为里面包含的是敏感凭证。如果你用的是一键安装脚本生成的配置建议安装完手动检查一下配置文件权限很多安装脚本默认权限是644等于把token明文暴露给了服务器上所有能读文件的用户。这个细节在单机个人部署时问题不大但团队共用服务器上就是安全隐患了。4. 同族错误速查专治OpenClaw连不上4.1 unexpected status 401 unauthorized: incorrect api key provided这个报错在热词里出现频率极高它其实和gateway token没有直接关系是OpenClaw在调用模型服务商的API时返回的HTTP 401。常见原因有三种一是API key本身填错了二是key填对了但余额不足或权限被限制三是环境变量里有多个API key生效的并不是你以为的那个。我遇到过一个经典场景在配置文件里填了新key但services下的环境变量还是旧的服务重启后实际加载的是环境变量里的旧key于是接口一直401。排查第一件事永远是确认到底哪个配置文件被加载了。可以加上--print或调试模式看启动时的环境快照或者直接运行env | grep API_KEY看看当前shell继承的环境变量。另外错误信息里如果出现的key像是sk-svcac****这种打码形式说明OpenClaw已经读取到了这个key并且试图使用它只是服务商不给过。这时候要看key本身是不是被truncated了有时候配置里填的key末尾被编辑器自动截断或者换行符混进去都会导致401。建议用cat -A检查一下配置文件里key那一行的结尾有没有隐藏字符。4.2 stream disconnected before completion: transport error流式响应走到一半断了错误是transport error这是典型的网络链路问题而不是认证问题。OpenClaw通过SSE或WebSocket和模型服务通信如果网络不稳定、代理干扰、或者服务端超时就会出现这个错误。处理思路依次是检查网络稳定性ping一下API域名看延迟和丢包关掉本地代理或走直连测试如果是自建服务或者远程模型API检查超时时间和重试机制是否配置合理。有个容易被忽视的点某些检测或安全软件会拦截长连接导致SSE流式响应被掐断。遇到stream disconnected且带transport error时可以试试临时关闭拦截测试一次。另外错误信息里如果出现target computer actively refused或者由于目标计算机积极拒绝,无法连接那是连接被拒往往是端口根本没开或防火墙挡住了处理思路完全不同。4.3 session file locked (timeout 60000ms)这个报错是OpenClaw的会话文件锁超时通常发生在两个进程同时操作同一个会话文件或者上一次运行时异常退出导致锁没有释放。解决的思路很简单找到会话目录一般叫sessions或conversations删掉残留的锁文件或者干脆备份后删掉对应会话文件重建。但要注意如果会话目录是NFS或共享存储锁问题会更频繁这时候需要检查文件系统是否支持可靠的锁机制。这个报错看起来跟token一点关系都没有但它通常在客户端连接成功后才会出现属于连接都通了但会话打不开的情况。处理时不要跟1008混在一起。如果日志里同时出现1008和session file locked建议先解决token认证问题因为连接都进不去的话会话锁报错很可能只是个伴随现象。4.4 错误速查表我把OpenClaw部署运维中最常见的几个错误整理成一张表方便对照排查报错关键字出错环节核心原因处理方向disconnected (1008): unauthorized: gateway token网关WebSocket握手gateway token错误或未配置重新生成并同步token401: incorrect api key provided模型API调用API key错误或未生效检查模型服务商API keystream disconnected: transport error流式响应传输网络不稳或代理干扰检查网络、关闭拦截stream disconnected: idle timeout流式响应传输长时间无数据导致超时调大空闲超时或启用心跳session file locked会话管理锁文件残留或并发冲突清理锁文件或会话目录unexpected status 401: missing bearerHTTP API调用请求头缺少认证信息检查请求头的Authorization字段这张表算是我这几个月折腾OpenClaw下来浓缩的排查路线图每次遇到连接问题都会先拿来对一遍基本能覆盖掉九成以上的报错场景。5. 部署层面的几点建议5.1 token安全与轮换策略gateway token属于敏感凭证一定要管好。首先不要把token硬编码在会提交到Git仓库的文件里用环境文件或密钥管理工具来处理其次建议定期轮换token比如每个月换一次轮换时严格按照服务端先换、客户端跟换的顺序避免窗口期内大量连接报错最后如果已经把token发到过聊天记录或者截图里第一时间轮换不要有侥幸心理。另外如果你用的是Docker部署要注意容器环境变量是可以通过docker inspect看到的别把token放在compose文件里还随手传到公司内网仓库。正确做法是通过Docker secret或者挂载一个600权限的环境文件进去。个人部署可能觉得无所谓但哪怕是自己用也建议把token当作密码一样对待因为一旦泄露别人可以控制你的OpenClaw执行操作相当于拿到了你AI工作流的操作权限。5.2 部署时的常见坑本地访问与外部接入本地部署时gateway默认监听127.0.0.1这样最安全。但如果要接入外部平台比如Teams、Obsidian就需要让gateway监听0.0.0.0或者在前面加一层反向代理。这里要特别提醒一个坑把监听地址改成0.0.0.0却不设置强token认证等于把门禁拆了任何人都能连你的网关。热词里提到openclaw接入Microsoft Teams这类场景下token的安全性尤其重要因为外部平台会主动连你的网关暴露面比本地大得多。如果必须监听公网强烈建议前面加一层反向代理比如Nginx或Caddy启用TLS。网关本身的WebSocket流量在里面走明文没关系但公网链路上必须加密。配置好反向代理之后连接地址从ws://变成wss://这也是一个排查点很多人在接入外部平台时地址写成了ws://但反向代理那边只允许wss结果握手一直失败。5.3 关于接入Microsoft Teams的补充如果是为了OpenClaw接入Teams除了token配置还需要注意回调URL的配置、平台侧的应用权限、消息订阅方式以及Teams自身的超时限制。接入过程中如果出现连不上先确认Teams平台的出站连接能到你的gateway端口再确认token一致。用wscat验证网关连通性这个步骤在接入Teams之前一定要做不然你根本分不清是Teams配置问题还是OpenClaw网关问题。接入Teams还有一个常见问题Teams应用的后台配置里要求填写消息端点URL这个URL必须是公网可访问的不能填127.0.0.1。很多第一次接入的人会在这里卡住以为OpenClaw服务是通的就行结果Teams那边回调过来全部超时。如果借不到公网IP可以考虑用内网穿透或者和云服务器打通但这些方案会引入额外的网络链路排查时要额外多看一眼链路状态。这个错误我现在看到基本能一眼定位但第一次真的绕了不少弯路先排查网络、再怀疑端口、最后才想到token。OpenClaw这类AI助手项目的部署其实并不复杂难点反而在这些看似不起眼的认证细节上。token这类问题有个共性报错信息其实已经告诉你是unauthorized了只是我们容易被前面那串英文唬住。下次再遇到先确认服务端和客户端的token是否一致再验证网络和API key大概率五分钟内解决。如果你在OpenClaw部署时也遇到过这个报错或者有其他奇怪的连接问题欢迎在评论区分享你的排查过程我看了之后会结合经验补充进后续的文章里。
