1. 问题背景与核心症结定位1.1 这个报错到底在说什么invalid handshake配合鉴权失败是 OpenClaw Browser Relay Extension 在建立浏览器扩展与本地服务端连接时最常撞上的一堵墙。先把话说白Browser Relay Extension 的本质是一个跑在浏览器里的“中转站”它负责把网页里的操作指令、页面状态、DOM 事件打包通过 WebSocket 或类似的握手协议转发给本地运行的 OpenClaw 核心服务。握手handshake就是双方建立连接前的“对暗号”环节——扩展说“我是合法的扩展”服务端说“我认识你进来吧”。一旦暗号对不上服务端直接甩出invalid handshake连接当场断开。鉴权失败则是握手失败的常见诱因之一。很多人第一次看到这个报错第一反应是“是不是网络问题”然后开始重启、重装、换端口折腾半天发现没用。实际上这个问题的根子往往不在网络层而在身份凭证的匹配逻辑和握手协议的版本一致性上。我见过太多人在这上面耗掉一整个下午所以这篇内容就是要把这个坑彻底填平。1.2 谁最容易踩到这个坑根据我自己的部署经验和社区里反馈的情况以下几类场景出现invalid handshake的概率最高首次部署 OpenClaw 后直接装扩展服务端还没生成或还没加载鉴权 token扩展就急着连必然握手失败。升级 OpenClaw 核心版本后没同步更新扩展服务端握手协议升级了扩展还是老版本双方“语言不通”。在 WSL2 环境下部署WSL2 的网络栈和 Windows 宿主之间存在端口映射和地址转换扩展拿到的服务端地址可能是错的。在 Termux 原生环境部署Android 的权限模型和文件系统布局跟标准 Linux 有差异token 文件路径容易对不上。多实例并存本地跑了两个 OpenClaw 服务扩展连到了错误的那个实例上token 自然不匹配。注意如果你是在 WSL2 里部署的 OpenClaw而浏览器扩展装在 Windows 侧的 Chrome 上那么扩展配置里的服务端地址绝对不能写localhost或127.0.0.1因为这两个地址在 Windows 侧指向的是 Windows 本机而不是 WSL2 虚拟机。这是 WSL2 环境下最高频的踩坑点。1.3 解决思路的总纲解决这个问题的核心逻辑就三条线凭证对齐、协议对齐、网络可达。凭证对齐是指扩展持有的 token 和服务端期望的 token 必须完全一致协议对齐是指双方的握手版本号、消息格式必须兼容网络可达是指扩展能真正把请求送到服务端监听的端口上。三条线任何一条断了都会表现为invalid handshake或鉴权失败。下面我会逐条拆开讲把每个环节的操作步骤和排查方法都摊开。2. 鉴权机制深度拆解与凭证对齐实操2.1 OpenClaw 的鉴权 token 是怎么生成和分发的OpenClaw 在首次启动时会在其数据目录下生成一个鉴权 token。这个 token 通常是一个随机字符串存放在配置文件或独立的 token 文件里。服务端启动时会读取这个 token并在握手阶段要求扩展提供相同的 token。扩展这边token 是在你安装扩展后手动填入配置页面的或者通过某种配对机制自动写入。问题就出在这个“手动填入”或“自动写入”的环节。我实测下来最常见的失败原因是服务端重新生成了 token比如你删了数据目录重新初始化但扩展里还留着旧 token。扩展配置页面里填 token 时多了空格或换行符肉眼看不出来但字符串比对直接失败。在 Termux 环境下token 文件路径跟标准 Linux 不同服务端读到的 token 和你以为的不是同一个。2.2 找到正确的 token 并验证一致性第一步先确认服务端当前使用的 token 到底是什么。不同部署方式下token 文件的位置不一样我整理了一个对照表部署方式典型 token 路径备注标准 Linux 本地部署~/.openclaw/config/token或~/.config/openclaw/auth.token具体以启动日志输出为准macOS 本地部署~/Library/Application Support/OpenClaw/token注意路径中有空格WSL2 部署WSL2 文件系统内的~/.openclaw/下从 Windows 侧访问需用\\wsl$\路径Termux 原生部署/data/data/com.termux/files/home/.openclaw/Termux 的 HOME 跟标准 Linux 不同Docker 容器部署容器内/root/.openclaw/或挂载卷内需进入容器或查看挂载目录找到 token 文件后用cat命令读出来注意看有没有多余的空白字符。你可以用下面这个命令来检查cat ~/.openclaw/config/token | xxd | tail -5xxd会以十六进制形式展示文件内容如果末尾有多余的0a换行或20空格你一眼就能看出来。正常情况下token 文件应该只包含 token 字符串本身末尾可以有一个换行符但有些版本的 OpenClaw 对末尾换行敏感所以最稳妥的做法是让 token 文件末尾不带换行。2.3 把 token 正确填入扩展配置打开浏览器的扩展管理页面找到 OpenClaw Browser Relay Extension 的配置界面。通常会有以下几个字段需要填写Server URL服务端地址格式一般是ws://地址:端口或http://地址:端口。Auth Token鉴权 token粘贴刚才读到的值。Relay Name中继名称如果服务端配置了多个中继需要对应填写。粘贴 token 时我建议先用一个纯文本编辑器比如记事本或 VS Code中转一下确认没有多余空格和换行再粘贴到扩展配置里。直接复制终端输出有时候会带上不可见字符这是很多人忽略的细节。填完之后点击扩展的“连接”或“测试连接”按钮。如果还是报invalid handshake先别急着改其他配置打开浏览器的开发者工具切到 Network 面板看 WebSocket 连接的具体请求和响应。响应里通常会带有更详细的错误信息比如token mismatch或unsupported protocol version这能帮你快速定位是凭证问题还是协议问题。2.4 实操心得token 轮换后的同步策略如果你经常需要重新初始化 OpenClaw比如测试不同配置每次都会生成新 token手动同步到扩展里很烦。我的做法是写一个简单的脚本在 OpenClaw 启动后自动把 token 推送到扩展的配置存储里。不过这个方案需要扩展支持外部写入配置不是所有版本都行。更通用的做法是把 token 文件软链接到一个固定路径扩展配置里始终填那个固定路径对应的 token 值这样即使重新初始化只要 token 不变就不用改扩展。提示有些版本的 OpenClaw 支持在配置文件里手动指定 token而不是每次随机生成。如果你在测试阶段可以固定一个 token省去反复同步的麻烦。具体是否支持查看你所用版本的配置文件模板即可。3. 握手协议版本匹配与扩展兼容性处理3.1 握手协议版本不一致的典型表现invalid handshake这个报错本身比较笼统它既可能是 token 不对也可能是协议版本不匹配。区分方法很简单如果你确认 token 完全一致但依然握手失败那基本就是协议版本问题了。协议版本不匹配的典型表现是扩展发起连接后服务端在响应里返回一个类似protocol version mismatch或unsupported handshake version的字段然后断开连接。OpenClaw 的握手协议在版本迭代中改过几次。早期版本可能只校验 token后来加入了版本号协商、消息格式校验、甚至加密签名。如果你的 OpenClaw 核心是比较新的版本而扩展还是几个月前装的那大概率会撞上这个问题。3.2 如何确认双方版本并做匹配先确认 OpenClaw 核心的版本。在终端里运行openclaw --version或者查看启动日志日志开头通常会打印版本号和握手协议版本。然后打开浏览器扩展的管理页面查看扩展的版本号。两个版本号不需要完全相同但握手协议版本必须兼容。通常 OpenClaw 的发布说明里会写明“本版本扩展要求核心版本不低于 X.Y.Z”你对照一下就知道该升级哪一边。升级扩展的方法如果是从浏览器商店安装的直接在扩展管理页面点击“更新”即可。如果是手动加载的开发者版本需要下载新版扩展包在扩展管理页面重新加载。升级核心的方法取决于你的部署方式标准部署用包管理器升级Docker 部署拉新镜像Termux 部署重新跑安装脚本。3.3 手动加载扩展时的版本坑手动加载扩展开发者模式有一个很容易被忽略的坑浏览器会缓存旧版本的扩展代码。你明明替换了扩展目录里的文件但浏览器加载的还是旧版本。解决办法是在扩展管理页面先移除旧扩展再重新加载新目录。或者使用浏览器的“重新加载”按钮但有时候这个按钮不够彻底移除再加载是最稳妥的。另外手动加载扩展时扩展的 manifest 文件里会声明它支持的握手协议版本范围。如果你拿到的扩展包和核心版本差距太大即使代码是新的manifest 里的版本声明也可能不匹配。这种情况下要么找对应版本的扩展包要么升级核心到与扩展匹配的版本。3.4 实操心得版本锁定与升级节奏我自己的习惯是在 OpenClaw 核心和扩展都稳定运行后把两者的版本号记录下来非必要不升级。如果确实需要升级先升级核心确认核心正常运行后再升级扩展最后重启浏览器。这个顺序能最大程度避免版本错配。反过来如果先升级扩展再升级核心中间那段时间扩展连不上核心虽然不影响使用但排查起来容易混淆。注意有些 OpenClaw 版本在升级后会重置 token 或更改握手协议升级前最好备份配置目录。备份命令很简单cp -r ~/.openclaw ~/.openclaw.bak出问题了直接回滚。4. 网络可达性排查与特殊环境适配4.1 WSL2 环境下的地址映射问题WSL2 的网络架构跟传统虚拟机不一样它有一个虚拟网卡Windows 宿主和 WSL2 之间通过这个网卡通信。默认情况下WSL2 里的服务监听在0.0.0.0或127.0.0.1但 Windows 侧的浏览器扩展不能直接用localhost访问 WSL2 里的服务因为 Windows 的localhost指向 Windows 本机。解决办法有两个一是让 WSL2 里的服务监听0.0.0.0然后扩展配置里填 WSL2 虚拟网卡的 IP 地址。获取 WSL2 IP 的命令是ip addr show eth0 | grep inet输出里inet后面的地址就是 WSL2 的 IP通常是172.x.x.x网段。把这个地址填到扩展的 Server URL 里端口保持跟服务端一致。第二个办法是在 Windows 侧做端口转发把 Windows 本机的某个端口转发到 WSL2 的对应端口。用 PowerShell管理员权限执行netsh interface portproxy add v4tov4 listenport服务端口 listenaddress0.0.0.0 connectport服务端口 connectaddressWSL2的IP这样扩展配置里填localhost:服务端口就能连上了。不过 WSL2 的 IP 在每次重启后可能会变所以端口转发规则需要定期更新或者写个脚本在 WSL2 启动时自动更新转发规则。4.2 Termux 原生部署的权限与路径适配在 Android 的 Termux 里原生部署 OpenClaw最大的坑是文件系统路径和权限。Termux 的 HOME 目录是/data/data/com.termux/files/home/而不是标准的/home/用户名/。OpenClaw 如果硬编码了标准路径就会找不到 token 文件或配置文件。解决办法是在 Termux 里设置环境变量把 OpenClaw 的数据目录指向 Termux 可访问的路径。具体做法是在~/.bashrc或~/.zshrc里加上export OPENCLAW_HOME/data/data/com.termux/files/home/.openclaw然后重新加载 shell 配置。这样 OpenClaw 就会在 Termux 的 HOME 下读写数据权限问题也一并解决了。另外Termux 里运行的服务默认只能被 Termux 内部访问如果浏览器扩展装在同一个 Android 设备的另一个浏览器里需要确认 Termux 的服务监听地址和端口是否对外暴露。Termux 本身没有网络隔离只要服务监听0.0.0.0同一设备上的浏览器就能访问127.0.0.1:端口。4.3 端口占用与防火墙拦截排查有时候invalid handshake的根因既不是 token 也不是协议而是连接根本没到达服务端。可能是端口被其他程序占用了或者防火墙拦截了连接。排查步骤确认 OpenClaw 服务正在监听你期望的端口netstat -tlnp | grep 端口号或ss -tlnp | grep 端口号。确认没有其他程序占用同一端口。如果端口被占OpenClaw 可能启动失败但你没注意到或者启动在了另一个端口上。检查系统防火墙规则。Linux 上用iptables -L或ufw statusWindows 上检查 Windows Defender 防火墙的入站规则。从浏览器所在机器上用curl或telnet测试端口连通性telnet 服务端地址 端口号如果连不上说明网络层就不通。提示如果你在 Docker 里跑 OpenClaw记得把端口映射出来-p 宿主端口:容器端口否则容器外部无法访问。这个看似基础但我在社区里见过不少人忘了映射端口然后对着invalid handshake百思不得其解。4.4 实操心得用最小化配置快速定位网络问题当你怀疑是网络问题时不要一上来就改 OpenClaw 的复杂配置。先做一个最小化测试在服务端用nc -l 端口号起一个简单的监听然后从浏览器所在机器上用telnet或nc连过去看能不能通。如果这个都通不了那问题百分百在网络层跟 OpenClaw 的鉴权和握手无关。这个测试能帮你省下大量瞎折腾的时间。5. 常见问题速查与避坑经验汇总5.1 高频问题速查表现象最可能原因快速验证方法解决动作扩展报invalid handshake服务端日志显示 token mismatchtoken 不一致对比服务端 token 文件和扩展配置重新同步 token扩展报invalid handshake服务端日志显示协议版本不支持扩展与核心版本不匹配查看双方版本号和握手协议版本升级扩展或核心扩展连不上浏览器控制台显示连接超时网络不可达用 telnet 测试端口检查监听地址、端口映射、防火墙WSL2 环境下扩展连不上地址填了 localhost确认 WSL2 IP 和端口转发改用 WSL2 IP 或配置端口转发Termux 环境下 token 读取失败路径不对检查 OPENCLAW_HOME 环境变量设置正确的数据目录路径升级核心后扩展失效token 重置或协议变更查看升级日志和发布说明重新同步 token 并升级扩展多实例环境下连错服务端口或地址指向了另一个实例确认目标实例的端口和 token修正扩展配置指向正确实例5.2 那些文档里不会写的坑第一个坑token 文件末尾的换行符。有些版本的 OpenClaw 在读取 token 时会把末尾换行也当作 token 的一部分而扩展在比对时可能做了 trim 处理导致两边不一致。解决办法是确保 token 文件末尾没有换行或者确保扩展和服务端使用相同的 trim 逻辑。我实测下来最稳妥的做法是用printf而不是echo来写入 token 文件因为printf默认不加换行。第二个坑浏览器扩展的缓存。Chrome 和 Edge 对扩展的配置有时候会缓存你改了配置但扩展实际用的还是旧值。解决办法是在扩展管理页面找到 OpenClaw 扩展点击“清除数据”或“重置”然后重新填写配置。或者干脆移除扩展再重新安装。第三个坑WSL2 的 IP 漂移。WSL2 每次重启后虚拟网卡 IP 可能变化如果你在扩展里硬编码了 WSL2 IP重启后就连不上了。解决办法是写一个启动脚本在 WSL2 启动时自动获取新 IP 并更新 Windows 侧的端口转发规则或者更新扩展配置。更省事的办法是用 Windows 侧的localhost转发这样扩展配置不用改。第四个坑Termux 的后台限制。Android 系统会限制后台应用的网络活动和 CPU 使用Termux 里跑的 OpenClaw 服务可能在息屏后被挂起导致扩展连接断开。解决办法是在 Android 设置里给 Termux 开启“无限制”后台权限并关闭电池优化。不同厂商的 Android 系统设置路径不同需要自行查找。5.3 排查流程的标准化建议我把自己常用的排查流程整理成了一个固定顺序每次遇到invalid handshake就按这个顺序走一遍基本能在十分钟内定位问题看服务端日志OpenClaw 启动日志和运行日志里通常有握手失败的详细原因这是最快的信息来源。确认 token 一致性读服务端 token 文件对比扩展配置排除凭证问题。确认版本兼容性对比核心和扩展的版本号及握手协议版本。测试网络连通性用 telnet 或 nc 测试端口是否可达。检查特殊环境配置WSL2 看地址映射Termux 看路径和权限Docker 看端口映射。清除扩展缓存重试排除浏览器侧的缓存干扰。这个顺序的核心逻辑是“从服务端到客户端从软件到网络”因为服务端日志信息量最大先看日志能少走很多弯路。5.4 一个容易被忽略的细节时间同步握手协议里有时候会包含时间戳校验如果服务端和客户端的时间差距太大比如超过几分钟握手也会失败。这种情况在 WSL2 里偶尔出现因为 WSL2 的时钟可能跟 Windows 宿主不同步。解决办法是在 WSL2 里运行sudo hwclock -s同步硬件时钟或者安装并启用时间同步服务。Termux 里同样需要确认系统时间准确Android 通常会自动同步时间但如果你手动改过时区或时间需要改回来。6. 部署方式差异化的解决方案6.1 macOS 本地部署的注意事项macOS 上部署 OpenClawtoken 文件路径通常在~/Library/Application Support/OpenClaw/下。这个路径里有空格在终端里操作时需要加引号或用反斜杠转义。扩展配置里填 token 时不受路径影响但如果你用脚本自动读取 token注意处理路径中的空格。macOS 的另一个坑是 Gatekeeper 和隐私权限。OpenClaw 如果需要监听网络端口macOS 可能会弹出防火墙提示你需要允许它接受传入连接。如果误点了“拒绝”后续扩展就连不上而且不会有明显提示。解决办法是去“系统设置 - 网络 - 防火墙 - 选项”里检查 OpenClaw 是否被阻止。6.2 Docker 部署的端口与卷映射Docker 部署 OpenClaw 时两个关键配置端口映射和卷映射。端口映射确保扩展能访问到容器内的服务卷映射确保 token 和配置文件持久化。如果没做卷映射容器重启后 token 会重新生成扩展里的旧 token 就失效了。一个典型的 Docker 启动命令docker run -d \ --name openclaw \ -p 8080:8080 \ -v /宿主机路径/openclaw-data:/root/.openclaw \ openclaw/openclaw:latest这样 token 文件会持久化在宿主机的/宿主机路径/openclaw-data/下容器重启也不会丢。扩展配置里的 Server URL 填ws://宿主机IP:8080即可。6.3 多实例并存时的隔离策略如果你在同一台机器上跑了多个 OpenClaw 实例比如一个用于测试一个用于日常使用每个实例必须使用不同的端口和不同的数据目录。否则两个实例会争抢同一端口或者共用同一个 token 文件导致混乱。启动第二个实例时通过命令行参数或环境变量指定不同的端口和数据目录OPENCLAW_HOME~/.openclaw-test openclaw --port 8081扩展配置里对应填ws://localhost:8081和测试实例的 token。这样两个实例互不干扰。注意多实例场景下最容易犯的错误是扩展连到了错误的实例上。排查时先确认扩展配置里的端口和 token 对应的是哪个实例再看那个实例的日志。6.4 实操心得用日志级别调优加速排查OpenClaw 通常支持调整日志级别。在排查invalid handshake时把日志级别调到debug或trace能看到握手过程的详细步骤包括双方交换的版本号、token 比对结果、失败的具体环节。排查完成后记得调回正常级别否则日志量太大会影响性能。调整方法一般在配置文件里改log_level字段或者启动时加--log-level debug参数。7. 预防性配置与长期稳定运行建议7.1 固定 token 避免反复同步如果你厌倦了每次重新初始化都要同步 token可以在 OpenClaw 配置文件里手动指定一个固定 token。具体字段名因版本而异常见的是auth_token或relay_token。在配置文件里写入一个你自定义的字符串保存后重启服务服务端就会使用这个固定 token。然后扩展配置里填同一个字符串以后无论怎么重启只要配置文件不变token 就不变。这个做法的安全性取决于你的使用场景。如果是本地开发测试固定 token 完全没问题。如果服务暴露在公网固定 token 的风险较高建议还是用随机生成的 token 并定期轮换。7.2 自动化健康检查脚本为了尽早发现握手问题可以写一个简单的健康检查脚本定期测试扩展与服务端的连接。脚本逻辑很简单用curl或websocat模拟一次握手请求检查响应状态。如果握手失败脚本可以发通知提醒你。这个脚本可以放在 cron 里定时执行或者做成 systemd 服务。一个简单的检查命令示例websocat -n1 ws://localhost:8080/relay --header Authorization: Bearer $(cat ~/.openclaw/config/token) 21 | grep -q handshake ok echo OK || echo FAILED具体命令需要根据你的 OpenClaw 版本的握手协议调整这里只是示意。7.3 版本升级前的检查清单每次升级 OpenClaw 核心或扩展之前按这个清单走一遍能避免大部分升级导致的握手问题备份当前配置目录和 token 文件。记录当前核心和扩展的版本号。查看新版本的发布说明确认是否有握手协议变更或 token 重置。升级核心后先不升级扩展测试连接是否正常。如果核心升级后扩展连不上再升级扩展到匹配版本。升级完成后清除浏览器扩展缓存重新加载扩展。7.4 长期运行的环境维护OpenClaw 长期运行后可能会因为日志文件过大、临时文件堆积、内存泄漏等问题导致服务异常进而表现为握手失败。建议定期做以下维护清理日志文件或配置日志轮转。检查服务进程的内存占用如果持续增长考虑重启服务。确认 token 文件权限正确避免被其他程序读取或修改。如果使用 WSL2定期检查端口转发规则是否仍然有效。我在实际使用中的体会是invalid handshake这个问题看起来吓人但只要你把 token、协议版本、网络可达这三条线理清楚排查起来并不复杂。最怕的是一上来就瞎改配置把原本正常的部分也改乱了。按顺序排查先看日志再对 token再查版本最后测网络基本都能解决。 OpenClaw Browser Relay Extension 握手失败与鉴权错误排查指南
1. 问题背景与核心症结定位1.1 这个报错到底在说什么invalid handshake配合鉴权失败是 OpenClaw Browser Relay Extension 在建立浏览器扩展与本地服务端连接时最常撞上的一堵墙。先把话说白Browser Relay Extension 的本质是一个跑在浏览器里的“中转站”它负责把网页里的操作指令、页面状态、DOM 事件打包通过 WebSocket 或类似的握手协议转发给本地运行的 OpenClaw 核心服务。握手handshake就是双方建立连接前的“对暗号”环节——扩展说“我是合法的扩展”服务端说“我认识你进来吧”。一旦暗号对不上服务端直接甩出invalid handshake连接当场断开。鉴权失败则是握手失败的常见诱因之一。很多人第一次看到这个报错第一反应是“是不是网络问题”然后开始重启、重装、换端口折腾半天发现没用。实际上这个问题的根子往往不在网络层而在身份凭证的匹配逻辑和握手协议的版本一致性上。我见过太多人在这上面耗掉一整个下午所以这篇内容就是要把这个坑彻底填平。1.2 谁最容易踩到这个坑根据我自己的部署经验和社区里反馈的情况以下几类场景出现invalid handshake的概率最高首次部署 OpenClaw 后直接装扩展服务端还没生成或还没加载鉴权 token扩展就急着连必然握手失败。升级 OpenClaw 核心版本后没同步更新扩展服务端握手协议升级了扩展还是老版本双方“语言不通”。在 WSL2 环境下部署WSL2 的网络栈和 Windows 宿主之间存在端口映射和地址转换扩展拿到的服务端地址可能是错的。在 Termux 原生环境部署Android 的权限模型和文件系统布局跟标准 Linux 有差异token 文件路径容易对不上。多实例并存本地跑了两个 OpenClaw 服务扩展连到了错误的那个实例上token 自然不匹配。注意如果你是在 WSL2 里部署的 OpenClaw而浏览器扩展装在 Windows 侧的 Chrome 上那么扩展配置里的服务端地址绝对不能写localhost或127.0.0.1因为这两个地址在 Windows 侧指向的是 Windows 本机而不是 WSL2 虚拟机。这是 WSL2 环境下最高频的踩坑点。1.3 解决思路的总纲解决这个问题的核心逻辑就三条线凭证对齐、协议对齐、网络可达。凭证对齐是指扩展持有的 token 和服务端期望的 token 必须完全一致协议对齐是指双方的握手版本号、消息格式必须兼容网络可达是指扩展能真正把请求送到服务端监听的端口上。三条线任何一条断了都会表现为invalid handshake或鉴权失败。下面我会逐条拆开讲把每个环节的操作步骤和排查方法都摊开。2. 鉴权机制深度拆解与凭证对齐实操2.1 OpenClaw 的鉴权 token 是怎么生成和分发的OpenClaw 在首次启动时会在其数据目录下生成一个鉴权 token。这个 token 通常是一个随机字符串存放在配置文件或独立的 token 文件里。服务端启动时会读取这个 token并在握手阶段要求扩展提供相同的 token。扩展这边token 是在你安装扩展后手动填入配置页面的或者通过某种配对机制自动写入。问题就出在这个“手动填入”或“自动写入”的环节。我实测下来最常见的失败原因是服务端重新生成了 token比如你删了数据目录重新初始化但扩展里还留着旧 token。扩展配置页面里填 token 时多了空格或换行符肉眼看不出来但字符串比对直接失败。在 Termux 环境下token 文件路径跟标准 Linux 不同服务端读到的 token 和你以为的不是同一个。2.2 找到正确的 token 并验证一致性第一步先确认服务端当前使用的 token 到底是什么。不同部署方式下token 文件的位置不一样我整理了一个对照表部署方式典型 token 路径备注标准 Linux 本地部署~/.openclaw/config/token或~/.config/openclaw/auth.token具体以启动日志输出为准macOS 本地部署~/Library/Application Support/OpenClaw/token注意路径中有空格WSL2 部署WSL2 文件系统内的~/.openclaw/下从 Windows 侧访问需用\\wsl$\路径Termux 原生部署/data/data/com.termux/files/home/.openclaw/Termux 的 HOME 跟标准 Linux 不同Docker 容器部署容器内/root/.openclaw/或挂载卷内需进入容器或查看挂载目录找到 token 文件后用cat命令读出来注意看有没有多余的空白字符。你可以用下面这个命令来检查cat ~/.openclaw/config/token | xxd | tail -5xxd会以十六进制形式展示文件内容如果末尾有多余的0a换行或20空格你一眼就能看出来。正常情况下token 文件应该只包含 token 字符串本身末尾可以有一个换行符但有些版本的 OpenClaw 对末尾换行敏感所以最稳妥的做法是让 token 文件末尾不带换行。2.3 把 token 正确填入扩展配置打开浏览器的扩展管理页面找到 OpenClaw Browser Relay Extension 的配置界面。通常会有以下几个字段需要填写Server URL服务端地址格式一般是ws://地址:端口或http://地址:端口。Auth Token鉴权 token粘贴刚才读到的值。Relay Name中继名称如果服务端配置了多个中继需要对应填写。粘贴 token 时我建议先用一个纯文本编辑器比如记事本或 VS Code中转一下确认没有多余空格和换行再粘贴到扩展配置里。直接复制终端输出有时候会带上不可见字符这是很多人忽略的细节。填完之后点击扩展的“连接”或“测试连接”按钮。如果还是报invalid handshake先别急着改其他配置打开浏览器的开发者工具切到 Network 面板看 WebSocket 连接的具体请求和响应。响应里通常会带有更详细的错误信息比如token mismatch或unsupported protocol version这能帮你快速定位是凭证问题还是协议问题。2.4 实操心得token 轮换后的同步策略如果你经常需要重新初始化 OpenClaw比如测试不同配置每次都会生成新 token手动同步到扩展里很烦。我的做法是写一个简单的脚本在 OpenClaw 启动后自动把 token 推送到扩展的配置存储里。不过这个方案需要扩展支持外部写入配置不是所有版本都行。更通用的做法是把 token 文件软链接到一个固定路径扩展配置里始终填那个固定路径对应的 token 值这样即使重新初始化只要 token 不变就不用改扩展。提示有些版本的 OpenClaw 支持在配置文件里手动指定 token而不是每次随机生成。如果你在测试阶段可以固定一个 token省去反复同步的麻烦。具体是否支持查看你所用版本的配置文件模板即可。3. 握手协议版本匹配与扩展兼容性处理3.1 握手协议版本不一致的典型表现invalid handshake这个报错本身比较笼统它既可能是 token 不对也可能是协议版本不匹配。区分方法很简单如果你确认 token 完全一致但依然握手失败那基本就是协议版本问题了。协议版本不匹配的典型表现是扩展发起连接后服务端在响应里返回一个类似protocol version mismatch或unsupported handshake version的字段然后断开连接。OpenClaw 的握手协议在版本迭代中改过几次。早期版本可能只校验 token后来加入了版本号协商、消息格式校验、甚至加密签名。如果你的 OpenClaw 核心是比较新的版本而扩展还是几个月前装的那大概率会撞上这个问题。3.2 如何确认双方版本并做匹配先确认 OpenClaw 核心的版本。在终端里运行openclaw --version或者查看启动日志日志开头通常会打印版本号和握手协议版本。然后打开浏览器扩展的管理页面查看扩展的版本号。两个版本号不需要完全相同但握手协议版本必须兼容。通常 OpenClaw 的发布说明里会写明“本版本扩展要求核心版本不低于 X.Y.Z”你对照一下就知道该升级哪一边。升级扩展的方法如果是从浏览器商店安装的直接在扩展管理页面点击“更新”即可。如果是手动加载的开发者版本需要下载新版扩展包在扩展管理页面重新加载。升级核心的方法取决于你的部署方式标准部署用包管理器升级Docker 部署拉新镜像Termux 部署重新跑安装脚本。3.3 手动加载扩展时的版本坑手动加载扩展开发者模式有一个很容易被忽略的坑浏览器会缓存旧版本的扩展代码。你明明替换了扩展目录里的文件但浏览器加载的还是旧版本。解决办法是在扩展管理页面先移除旧扩展再重新加载新目录。或者使用浏览器的“重新加载”按钮但有时候这个按钮不够彻底移除再加载是最稳妥的。另外手动加载扩展时扩展的 manifest 文件里会声明它支持的握手协议版本范围。如果你拿到的扩展包和核心版本差距太大即使代码是新的manifest 里的版本声明也可能不匹配。这种情况下要么找对应版本的扩展包要么升级核心到与扩展匹配的版本。3.4 实操心得版本锁定与升级节奏我自己的习惯是在 OpenClaw 核心和扩展都稳定运行后把两者的版本号记录下来非必要不升级。如果确实需要升级先升级核心确认核心正常运行后再升级扩展最后重启浏览器。这个顺序能最大程度避免版本错配。反过来如果先升级扩展再升级核心中间那段时间扩展连不上核心虽然不影响使用但排查起来容易混淆。注意有些 OpenClaw 版本在升级后会重置 token 或更改握手协议升级前最好备份配置目录。备份命令很简单cp -r ~/.openclaw ~/.openclaw.bak出问题了直接回滚。4. 网络可达性排查与特殊环境适配4.1 WSL2 环境下的地址映射问题WSL2 的网络架构跟传统虚拟机不一样它有一个虚拟网卡Windows 宿主和 WSL2 之间通过这个网卡通信。默认情况下WSL2 里的服务监听在0.0.0.0或127.0.0.1但 Windows 侧的浏览器扩展不能直接用localhost访问 WSL2 里的服务因为 Windows 的localhost指向 Windows 本机。解决办法有两个一是让 WSL2 里的服务监听0.0.0.0然后扩展配置里填 WSL2 虚拟网卡的 IP 地址。获取 WSL2 IP 的命令是ip addr show eth0 | grep inet输出里inet后面的地址就是 WSL2 的 IP通常是172.x.x.x网段。把这个地址填到扩展的 Server URL 里端口保持跟服务端一致。第二个办法是在 Windows 侧做端口转发把 Windows 本机的某个端口转发到 WSL2 的对应端口。用 PowerShell管理员权限执行netsh interface portproxy add v4tov4 listenport服务端口 listenaddress0.0.0.0 connectport服务端口 connectaddressWSL2的IP这样扩展配置里填localhost:服务端口就能连上了。不过 WSL2 的 IP 在每次重启后可能会变所以端口转发规则需要定期更新或者写个脚本在 WSL2 启动时自动更新转发规则。4.2 Termux 原生部署的权限与路径适配在 Android 的 Termux 里原生部署 OpenClaw最大的坑是文件系统路径和权限。Termux 的 HOME 目录是/data/data/com.termux/files/home/而不是标准的/home/用户名/。OpenClaw 如果硬编码了标准路径就会找不到 token 文件或配置文件。解决办法是在 Termux 里设置环境变量把 OpenClaw 的数据目录指向 Termux 可访问的路径。具体做法是在~/.bashrc或~/.zshrc里加上export OPENCLAW_HOME/data/data/com.termux/files/home/.openclaw然后重新加载 shell 配置。这样 OpenClaw 就会在 Termux 的 HOME 下读写数据权限问题也一并解决了。另外Termux 里运行的服务默认只能被 Termux 内部访问如果浏览器扩展装在同一个 Android 设备的另一个浏览器里需要确认 Termux 的服务监听地址和端口是否对外暴露。Termux 本身没有网络隔离只要服务监听0.0.0.0同一设备上的浏览器就能访问127.0.0.1:端口。4.3 端口占用与防火墙拦截排查有时候invalid handshake的根因既不是 token 也不是协议而是连接根本没到达服务端。可能是端口被其他程序占用了或者防火墙拦截了连接。排查步骤确认 OpenClaw 服务正在监听你期望的端口netstat -tlnp | grep 端口号或ss -tlnp | grep 端口号。确认没有其他程序占用同一端口。如果端口被占OpenClaw 可能启动失败但你没注意到或者启动在了另一个端口上。检查系统防火墙规则。Linux 上用iptables -L或ufw statusWindows 上检查 Windows Defender 防火墙的入站规则。从浏览器所在机器上用curl或telnet测试端口连通性telnet 服务端地址 端口号如果连不上说明网络层就不通。提示如果你在 Docker 里跑 OpenClaw记得把端口映射出来-p 宿主端口:容器端口否则容器外部无法访问。这个看似基础但我在社区里见过不少人忘了映射端口然后对着invalid handshake百思不得其解。4.4 实操心得用最小化配置快速定位网络问题当你怀疑是网络问题时不要一上来就改 OpenClaw 的复杂配置。先做一个最小化测试在服务端用nc -l 端口号起一个简单的监听然后从浏览器所在机器上用telnet或nc连过去看能不能通。如果这个都通不了那问题百分百在网络层跟 OpenClaw 的鉴权和握手无关。这个测试能帮你省下大量瞎折腾的时间。5. 常见问题速查与避坑经验汇总5.1 高频问题速查表现象最可能原因快速验证方法解决动作扩展报invalid handshake服务端日志显示 token mismatchtoken 不一致对比服务端 token 文件和扩展配置重新同步 token扩展报invalid handshake服务端日志显示协议版本不支持扩展与核心版本不匹配查看双方版本号和握手协议版本升级扩展或核心扩展连不上浏览器控制台显示连接超时网络不可达用 telnet 测试端口检查监听地址、端口映射、防火墙WSL2 环境下扩展连不上地址填了 localhost确认 WSL2 IP 和端口转发改用 WSL2 IP 或配置端口转发Termux 环境下 token 读取失败路径不对检查 OPENCLAW_HOME 环境变量设置正确的数据目录路径升级核心后扩展失效token 重置或协议变更查看升级日志和发布说明重新同步 token 并升级扩展多实例环境下连错服务端口或地址指向了另一个实例确认目标实例的端口和 token修正扩展配置指向正确实例5.2 那些文档里不会写的坑第一个坑token 文件末尾的换行符。有些版本的 OpenClaw 在读取 token 时会把末尾换行也当作 token 的一部分而扩展在比对时可能做了 trim 处理导致两边不一致。解决办法是确保 token 文件末尾没有换行或者确保扩展和服务端使用相同的 trim 逻辑。我实测下来最稳妥的做法是用printf而不是echo来写入 token 文件因为printf默认不加换行。第二个坑浏览器扩展的缓存。Chrome 和 Edge 对扩展的配置有时候会缓存你改了配置但扩展实际用的还是旧值。解决办法是在扩展管理页面找到 OpenClaw 扩展点击“清除数据”或“重置”然后重新填写配置。或者干脆移除扩展再重新安装。第三个坑WSL2 的 IP 漂移。WSL2 每次重启后虚拟网卡 IP 可能变化如果你在扩展里硬编码了 WSL2 IP重启后就连不上了。解决办法是写一个启动脚本在 WSL2 启动时自动获取新 IP 并更新 Windows 侧的端口转发规则或者更新扩展配置。更省事的办法是用 Windows 侧的localhost转发这样扩展配置不用改。第四个坑Termux 的后台限制。Android 系统会限制后台应用的网络活动和 CPU 使用Termux 里跑的 OpenClaw 服务可能在息屏后被挂起导致扩展连接断开。解决办法是在 Android 设置里给 Termux 开启“无限制”后台权限并关闭电池优化。不同厂商的 Android 系统设置路径不同需要自行查找。5.3 排查流程的标准化建议我把自己常用的排查流程整理成了一个固定顺序每次遇到invalid handshake就按这个顺序走一遍基本能在十分钟内定位问题看服务端日志OpenClaw 启动日志和运行日志里通常有握手失败的详细原因这是最快的信息来源。确认 token 一致性读服务端 token 文件对比扩展配置排除凭证问题。确认版本兼容性对比核心和扩展的版本号及握手协议版本。测试网络连通性用 telnet 或 nc 测试端口是否可达。检查特殊环境配置WSL2 看地址映射Termux 看路径和权限Docker 看端口映射。清除扩展缓存重试排除浏览器侧的缓存干扰。这个顺序的核心逻辑是“从服务端到客户端从软件到网络”因为服务端日志信息量最大先看日志能少走很多弯路。5.4 一个容易被忽略的细节时间同步握手协议里有时候会包含时间戳校验如果服务端和客户端的时间差距太大比如超过几分钟握手也会失败。这种情况在 WSL2 里偶尔出现因为 WSL2 的时钟可能跟 Windows 宿主不同步。解决办法是在 WSL2 里运行sudo hwclock -s同步硬件时钟或者安装并启用时间同步服务。Termux 里同样需要确认系统时间准确Android 通常会自动同步时间但如果你手动改过时区或时间需要改回来。6. 部署方式差异化的解决方案6.1 macOS 本地部署的注意事项macOS 上部署 OpenClawtoken 文件路径通常在~/Library/Application Support/OpenClaw/下。这个路径里有空格在终端里操作时需要加引号或用反斜杠转义。扩展配置里填 token 时不受路径影响但如果你用脚本自动读取 token注意处理路径中的空格。macOS 的另一个坑是 Gatekeeper 和隐私权限。OpenClaw 如果需要监听网络端口macOS 可能会弹出防火墙提示你需要允许它接受传入连接。如果误点了“拒绝”后续扩展就连不上而且不会有明显提示。解决办法是去“系统设置 - 网络 - 防火墙 - 选项”里检查 OpenClaw 是否被阻止。6.2 Docker 部署的端口与卷映射Docker 部署 OpenClaw 时两个关键配置端口映射和卷映射。端口映射确保扩展能访问到容器内的服务卷映射确保 token 和配置文件持久化。如果没做卷映射容器重启后 token 会重新生成扩展里的旧 token 就失效了。一个典型的 Docker 启动命令docker run -d \ --name openclaw \ -p 8080:8080 \ -v /宿主机路径/openclaw-data:/root/.openclaw \ openclaw/openclaw:latest这样 token 文件会持久化在宿主机的/宿主机路径/openclaw-data/下容器重启也不会丢。扩展配置里的 Server URL 填ws://宿主机IP:8080即可。6.3 多实例并存时的隔离策略如果你在同一台机器上跑了多个 OpenClaw 实例比如一个用于测试一个用于日常使用每个实例必须使用不同的端口和不同的数据目录。否则两个实例会争抢同一端口或者共用同一个 token 文件导致混乱。启动第二个实例时通过命令行参数或环境变量指定不同的端口和数据目录OPENCLAW_HOME~/.openclaw-test openclaw --port 8081扩展配置里对应填ws://localhost:8081和测试实例的 token。这样两个实例互不干扰。注意多实例场景下最容易犯的错误是扩展连到了错误的实例上。排查时先确认扩展配置里的端口和 token 对应的是哪个实例再看那个实例的日志。6.4 实操心得用日志级别调优加速排查OpenClaw 通常支持调整日志级别。在排查invalid handshake时把日志级别调到debug或trace能看到握手过程的详细步骤包括双方交换的版本号、token 比对结果、失败的具体环节。排查完成后记得调回正常级别否则日志量太大会影响性能。调整方法一般在配置文件里改log_level字段或者启动时加--log-level debug参数。7. 预防性配置与长期稳定运行建议7.1 固定 token 避免反复同步如果你厌倦了每次重新初始化都要同步 token可以在 OpenClaw 配置文件里手动指定一个固定 token。具体字段名因版本而异常见的是auth_token或relay_token。在配置文件里写入一个你自定义的字符串保存后重启服务服务端就会使用这个固定 token。然后扩展配置里填同一个字符串以后无论怎么重启只要配置文件不变token 就不变。这个做法的安全性取决于你的使用场景。如果是本地开发测试固定 token 完全没问题。如果服务暴露在公网固定 token 的风险较高建议还是用随机生成的 token 并定期轮换。7.2 自动化健康检查脚本为了尽早发现握手问题可以写一个简单的健康检查脚本定期测试扩展与服务端的连接。脚本逻辑很简单用curl或websocat模拟一次握手请求检查响应状态。如果握手失败脚本可以发通知提醒你。这个脚本可以放在 cron 里定时执行或者做成 systemd 服务。一个简单的检查命令示例websocat -n1 ws://localhost:8080/relay --header Authorization: Bearer $(cat ~/.openclaw/config/token) 21 | grep -q handshake ok echo OK || echo FAILED具体命令需要根据你的 OpenClaw 版本的握手协议调整这里只是示意。7.3 版本升级前的检查清单每次升级 OpenClaw 核心或扩展之前按这个清单走一遍能避免大部分升级导致的握手问题备份当前配置目录和 token 文件。记录当前核心和扩展的版本号。查看新版本的发布说明确认是否有握手协议变更或 token 重置。升级核心后先不升级扩展测试连接是否正常。如果核心升级后扩展连不上再升级扩展到匹配版本。升级完成后清除浏览器扩展缓存重新加载扩展。7.4 长期运行的环境维护OpenClaw 长期运行后可能会因为日志文件过大、临时文件堆积、内存泄漏等问题导致服务异常进而表现为握手失败。建议定期做以下维护清理日志文件或配置日志轮转。检查服务进程的内存占用如果持续增长考虑重启服务。确认 token 文件权限正确避免被其他程序读取或修改。如果使用 WSL2定期检查端口转发规则是否仍然有效。我在实际使用中的体会是invalid handshake这个问题看起来吓人但只要你把 token、协议版本、网络可达这三条线理清楚排查起来并不复杂。最怕的是一上来就瞎改配置把原本正常的部分也改乱了。按顺序排查先看日志再对 token再查版本最后测网络基本都能解决。