OpenClaw 系统伴侣

严格说来这像是一篇技术笔记。

OpenClaw WSL2 + Windows Companion 故障总结与稳定配置指南

基于本聊天中围绕 Windows 11 + WSL2 Ubuntu 24.04 + OpenClaw Gateway + Windows Companion / Windows Node 的全部排查、反复试错、修正结论与最终稳定链路整理。生成时间：2026-06-07 10:49。

核心结论：本次问题不是单一故障，而是 Gateway 主控源、认证凭据、Operator / Node 身份、Windows Companion 本机能力注册、安全执行边界五个层级叠加造成的状态混乱。最终正确方向是：保留 WSL2 Gateway 作为唯一主 Gateway，Windows Companion 只作为 Operator + Windows Node 客户端连接它。

大纲

0. 总裁判结论

1. 正常运行基线

2. 总体结构图

3. 问题分类与正确方案

4. 反复出现的问题

5. 网络 / VPN / WSL mirrored

6. 认证、token、setup code

7. pairing / approve / requestId

8. Node capabilities 与命令暴露

9. screen.snapshot 与 allowlist

10. 安全边界与 System tools

11. 稳定操作流程

12. 最小命令清单

13. 术语概念汇总

14. 常见错误与禁止动作

15. 最终核验表

0. 总裁判结论

这轮排查的真实主线不是“OpenClaw 连不上”，而是：系统里同时存在 Windows 原生 Gateway、WSL2 Gateway、Windows Companion、Windows Node、旧 device token、bootstrap token、shared token、operator token、node token 等多个对象，用户不断按不同入口连接，导致表象不断变化。

最终确认项	状态	含义
WSL2 Gateway	运行正常	应作为唯一主 Gateway，监听 18789，由 WSL2 Ubuntu 中的 systemd user service 托管。
Windows Companion	已连通	Connection 页面出现 Connected，Operator 绿色。
Windows Node	已配对并 connected	openclaw nodes status 显示 Known:1 / Paired:1 / Connected:1。
Capabilities	UI 与日志有冲突	UI 显示 0 capabilities，但 Tray 日志曾明确注册 9 caps / 29 commands。最终以 nodes describe 和实际调用测试为准。
System tools	需谨慎	日志显示 MXC unavailable，命令可能 uncontained 执行，测试阶段建议关闭或只允许只读命令。

最关键经验：不要在连接失败时立即删除、重配、重启、旋转 token。必须先判断当前属于哪一层：网络层、认证层、身份层、能力层、还是命令安全层。

1. 正常运行的电脑配置与环境基线

层级	建议/已验证配置	注意事项
Windows	Windows 11，已安装 OpenClaw Windows Companion	Windows 原生 OpenClaw Gateway 不作为主 Gateway，避免与 WSL2 Gateway 抢端口和认证源。
WSL	WSL2，Ubuntu-24.04，wsl -l -v 显示 VERSION=2	推荐开启 mirrored networking；改 .wslconfig 后必须 wsl –shutdown。
OpenClaw Gateway	WSL2 内 systemd user service 运行，端口 18789	openclaw gateway status 应显示 Runtime running、Connectivity probe ok。
认证模式	gateway.auth.mode = token，持久化 gateway.auth.token	不要让 Gateway 每次启动临时生成 runtime token。
Companion 连接	Direct + Gateway URL + shared token	不要使用旧的 device token 记录反复 Connect。
Windows Node	由 Companion 的 Node mode 提供	Node 必须被 Gateway 批准；本机能力还要在 Permissions 面板启用。
网络	Windows 能访问 http://127.0.0.1:18789/ 和 WSL IP 的 :18789	VPN 的 4780/4781 主要影响外网下载；本地 Gateway 应绕过代理。

2. 总体结构图：正确结构与错误结构

正确结构：单一 WSL2 Gateway 作为主控制平面

错误结构：双 Gateway / 多 token / 旧身份交叉

3. 用户问题主要分类与正确解决方案

问题类别	典型症状	正确方案	错误做法
Gateway 连接失败	Can’t reach gateway、No credential available	先确认 WSL2 Gateway 是否监听；再用 Direct + shared token 建立 Operator 凭据。	反复点旧 Saved gateway 的 Connect。
token mismatch	gateway token mismatch、device token mismatch	确认唯一主 Gateway；持久化 gateway.auth.token；清理错误旧记录后重新 Direct。	在 Windows 原生 Gateway 和 WSL2 Gateway 之间来回切。
requestId unknown	Could not start the CLI、unknown requestId	用 openclaw devices list 取当前 Pending 里的最新 Request ID，再批准。	批准截图里的旧 requestId 或已被替换的 requestId。
scope / role upgrade	scope upgrade pending approval、role upgrade, repair	用 operator.admin 权限批准 Companion 请求，使其从 node 变成 operator 或 node+operator。	误用 nodes approve 批准 device request。
Node 连接但无能力	Node active · 0 capabilities、Commands none reported	查 Permissions 面板、Tray 日志、nodes describe。必要时只重启 Node mode，不重配 Gateway。	重新生成 setup code、重置 Gateway。
screen.snapshot not allowed	node command not allowed	检查两层：Node 是否上报 screen commands；Gateway allowlist 是否包含 screen.snapshot。	只改 allowlist，却不查 Node 是否上报命令。
VPN/代理影响	GitHub/npm/curl 超时，或 WSL 代理警告	mirrored networking + autoProxy；必要时配置 4780/4781；本地 18789 放入 no_proxy。	把本地 Gateway 流量也走代理。

4. 反复出现的问题：为什么会反复、不同选项导致什么结果

4.1 “No credential available” 反复出现

这个问题多次出现，原因不是网络不可达，而是 Companion 当前保存的身份凭据不足或错位。

连接方式	会发生什么	适用性
旧 Saved Gateway + device token	只能代表已配对设备身份，不能保证 Companion 拥有 operator 凭据。	不适合作为修复入口
Setup code	包含 bootstrap token，适合新配对，但可能过期、一次性，且后续仍可能需要 role upgrade。	适合初次配对或临时修复
Direct + shared token	使用持久 gateway.auth.token，更适合稳定连接 WSL2 Gateway。	推荐稳定方案

4.2 requestId 一直 unknown

原因：requestId 是 Gateway 当前 pending request 的一次性编号。只要 Companion 重新 Connect、断开重连、换了身份、或 Gateway 生成了新 repair request，旧 requestId 就可能失效。

requestId 变化链条

4.3 多窗口是否导致问题

单纯多个 Bash / PowerShell 窗口本身不是根因。真正的问题是：多个窗口里执行了改变状态的命令，例如重启 Gateway、重新生成 setup code、删除设备、旋转 token、重复 Connect。多个窗口会扩大状态不同步风险。

5. 网络、VPN、WSL mirrored 与防火墙

电脑同时运行 VPN，HTTP(S) 端口 4780、SOCKS 端口 4781，对本次问题的影响应分层看。

流量类型	是否受 VPN 影响	正确处理
本地 Gateway：127.0.0.1:18789	理论上不应走 VPN	配置 NO_PROXY=127.0.0.1,localhost,192.168.100.195，避免本地流量被代理。
WSL 下载 GitHub/npm	可能受影响	mirrored networking + autoProxy，或手动设置 http_proxy=http://WINHOST:4780。
Windows 访问 WSL IP:18789	主要受 WSL mirrored / Hyper-V Firewall 影响	用 curl 和 Test-NetConnection 验证，必要时添加窄范围防火墙规则。

网络路径判断

# Windows PowerShell：验证 Windows 能访问 Gatewaycurl.exe -I http://127.0.0.1:18789/$wslIp = (wsl -d Ubuntu-24.04 hostname -I).Trim().Split(" ")[0]curl.exe -I "http://$wslIp`:18789/"Test-NetConnection 127.0.0.1 -Port 18789Test-NetConnection $wslIp -Port 18789

6. 认证、token、setup code 的关系

四种凭据的区别

概念	解决什么问题	常见误区
gateway.auth.token	Gateway 的持久共享认证密钥。	不要让 Gateway 启动时临时生成 runtime token；重启会变化。
setup code	用于快速添加 Gateway，一般包含 URL 与 bootstrap token。	不是长期稳定凭据；可能过期或只适合初始配对。
device token	设备配对后用于证明设备身份。	不能等同于 operator 权限；只用 device token 可能出现 No credential available。
operator token	让 Companion 有查看 sessions、管理 Gateway、批准请求等权限。	缺 operator 权限时，界面可连但功能不足。
node token	让 Windows Node 接入并提供能力。	Node online 不代表 capabilities 已注册。

7. pairing、approve、role upgrade、scope upgrade

本次最容易进入死循环的地方，是把 devices approve、nodes approve、UI 里的 Approve、以及不同 requestId 混为一谈。

对象	使用命令/入口	对应问题
Companion / Tray 作为设备申请	openclaw devices approve	new pairing、role upgrade、scope upgrade、repair
Windows Node 能力授权	Companion 黄色提示条中的 Approve	本机是否允许作为 node 提供能力
节点状态查看	openclaw nodes status / nodes describe	是否 connected、是否有 caps/commands
设备状态查看	openclaw devices list	是否有 pending、paired、roles、scopes、tokens

判断规则：批准前永远先执行 openclaw devices list，只批准 Pending 表格中当前存在的 Request ID。不要批准截图里的旧 ID。

8. Node capabilities 与命令暴露

这里至少有三层，不可混淆：

层级	负责什么	异常表现
Companion Permissions	本机能力开关：System tools、Browser、Screen、Camera 等	开关关闭时，Node 不应上报相应能力。
Node runtime registration	Windows Node 向 Gateway 上报 caps 与 commands	Commands none reported 或 Caps 空。
Gateway command policy	平台命令 allowlist / deny policy	node command not allowed。

能力可用的三重门

现阶段判断：日志中出现过 caps=9、commands=29，说明 Windows Tray 端能力注册逻辑本身能工作。若 UI 仍显示 0 capabilities，优先查状态刷新、Node mode 重启、nodes describe，而不是重置 Gateway。

9. screen.snapshot 与 allowlist

最初调用 screen.snapshot 失败，提示：

node command not allowed: "screen.snapshot" is not in the allowlist for platform "windows"

这类错误说明 Gateway 命令策略没有放行该命令。后来设置：

openclaw config set gateway.nodes.allowCommands '["screen.snapshot","screen.record"]' --strict-jsonopenclaw gateway restart --safe

后续又扩展为：

["screen.snapshot","screen.record","system.run","system.run.prepare"]

但必须注意：allowlist 只是放行层，不等于 Node 已经提供命令。只有当 openclaw nodes describe –node … 中同时出现相关 Commands，调用才可能成功。

10. 安全边界与 System tools

本聊天中已确认一条高风险信息：Windows Node 的 System tools 可能 uncontained 执行。原因是当前 Windows build 26200 不满足 MXC supported build 26300 的条件。

能力	建议状态	理由
System tools	默认关闭，按需开启	可执行 shell/PowerShell 命令，风险最高。
Screen capture	测试阶段可开启	用于验证桌面观察能力。
Browser control	可开启	用于受控浏览器操作。
Camera / Location	按需开启	涉及隐私；非必要不启用。
TTS / STT	按需开启	语音测试需要时再开。

安全原则：读多写少、先查状态、再计划、再执行；涉及删除、安装、清理、修改系统设置的命令必须人工确认。不要把 system.run 当成无风险能力。

11. 稳定操作流程：以后必须按阶段推进

1.先查 Windows 侧：Companion 截图、OpenClaw 进程、Windows 是否能 curl Gateway。

2.再查 WSL2 侧：openclaw gateway status、devices list、nodes status。

3.判断属于哪一层：网络、认证、身份、能力、命令策略、安全。

4.只改当前层：不要同时改 token、删除设备、重启 Gateway、切换 setup code。

5.每一步只执行一个操作：操作完成后贴日志，再判断下一步。

6.稳定后沉淀：保留最小命令清单、确认正确 Gateway、关闭高风险能力。

排查运动阶段

12. 最小命令清单

12.1 WSL2 / Bash：状态查询echo "===== gateway status ====="openclaw gateway statusecho "===== devices list ====="openclaw devices listecho "===== nodes status ====="openclaw nodes statusecho "===== command policy ====="openclaw config get gateway.nodes.allowCommands

12.2 WSL2 / Bash：网络自测

hostname -Iss -lntp | grep 18789 || truecurl -I http://127.0.0.1:18789/ || truecurl -I http://$(hostname -I | awk '{print $1}'):18789/ || true

12.3 Windows PowerShell：Gateway 可达性

curl.exe -I http://127.0.0.1:18789/$wslIp = (wsl -d Ubuntu-24.04 hostname -I).Trim().Split(" ")[0]Write-Host "WSL IPv4 = $wslIp"curl.exe -I "http://$wslIp`:18789/"Test-NetConnection 127.0.0.1 -Port 18789Test-NetConnection $wslIp -Port 18789

12.4 Windows PowerShell：查 OpenClaw 进程

Get-CimInstance Win32_Process |Where-Object { $_.CommandLine -match "openclaw|OpenClaw|node-host|node" } |Select-Object ProcessId,Name,CommandLine |Format-List

12.5 WSL2 / Bash：批准当前 pending request

# 先查当前 Pending，不要用旧截图 IDopenclaw devices list# 只批准当前表格中存在的 Request IDopenclaw devices approve <当前PendingRequestId>

12.6 WSL2 / Bash：查看 Node 命令

openclaw nodes describe --node <当前WindowsNodeId>

13. 重要概念、术语单独汇总

术语	本次语境中的含义	不要误解为	用户操作
Gateway	OpenClaw 的主控制平面，管理状态、设备、节点、会话、插件、工具。	不是 Windows Companion；不是 Node。	openclaw gateway status
Windows Companion	Windows 图形客户端，可作为 Operator，也可开启 Node mode 提供本机能力。	不是 Gateway 本体。	Connection / Permissions 页面操作。
Operator	可以管理 Gateway、查看 sessions、批准设备请求的身份。	不是提供桌面能力的 Node。	需要 operator.admin / read / write 等 scopes。
Node	向 Gateway 提供本机能力的设备角色，如截图、浏览器、系统命令。	不是聊天 Agent。	开启 Node mode 并批准配对。
Capabilities	Node 能力类别，如 system、screen、browser、camera。	不等同于具体命令。	Companion Permissions 开关。
Commands	具体可调用命令，如 screen.snapshot、system.run。	不是 UI 开关；必须由 Node 上报。	nodes describe 查看。
Allowlist	Gateway 允许 Windows Node 执行的命令清单。	不代表 Node 一定提供该命令。	config get/set gateway.nodes.allowCommands
Setup code	快速添加 Gateway 的一次性/临时配对信息。	不是长期稳定 token。	Companion 的 Setup code 页面粘贴。
Shared token	持久 Gateway 共享认证 token。	不是 device token。	Direct 页面填写 Shared token。
Device token	设备已配对后的身份凭据。	不必然包含 operator 权限。	一般不手动填，自动保存。
requestId	一次 pending request 的临时编号。	不是设备 ID，不永久有效。	从 devices list 当前 Pending 读取。
systemd user service	WSL2 中托管 Gateway 后台服务的 Linux 用户级服务。	不是 Windows 任务计划。	systemctl –user / gateway status
MXC	Windows 命令执行隔离相关能力。	不是普通权限开关。	不可用时 System tools 风险升高。

14. 常见错误与禁止动作

禁止动作 1：连接失败就删除所有设备、旋转 token、重新 setup code、重启 Gateway 一起做。这样会制造更多未知状态。

禁止动作 2：将 Windows 原生 Gateway 与 WSL2 Gateway 同时作为主 Gateway 使用。必须选一个，本次稳定方案是 WSL2 Gateway。

禁止动作 3：看到 requestId 就立即批准。必须先查 openclaw devices list，确认该 request 仍存在。

禁止动作 4：把 Companion UI 的 0 capabilities 当作唯一真相。必须结合 Tray 日志、nodes describe、实际调用测试。

禁止动作 5：在 System tools 开启且 uncontained 的情况下执行删除、清理、安装、修改系统设置等高风险命令。

15. 最终核验表

核验项	合格输出	不合格时下一步
Windows curl Gateway	HTTP/1.1 200 OK	查 WSL Gateway 是否 listening；查防火墙/WSL mirrored。
Gateway status	Runtime running；Connectivity probe ok；Listening *:18789	查 systemd 日志：journalctl –user -u openclaw-gateway.service
devices list	无 Pending；有 operator 与 Windows Node	批准当前 pending request；不要用旧 requestId。
nodes status	Known:1 / Paired:1 / Connected:1	重启 Companion Node mode；必要时重新批准 Node。
nodes describe	显示 Commands	查 Permissions、Tray 日志、Node runtime。
screen.snapshot 测试	成功返回截图结果	查 Node commands 与 Gateway allowlist。
System tools	只在需要时开启	默认关闭；只读测试后再放开。

最终稳定形态：WSL2 Gateway 长期运行；Windows Companion 通过 Direct + shared token 连接；Operator 与 Node 身份均正确；Windows Node capabilities 已注册；高风险 System tools 按需开启；所有修改前先查状态。

本文为本次对话的归并型技术说明指南。为安全起见，所有 token、device token、bootstrap token、private key 均未记录明文。