node-connect

核心功能

Node Connect 是一款针对 OpenClaw 生态系统的专业网络诊断工具，专注于解决节点与网关之间的连接和配对失败问题。它支持 Android、iOS 和 macOS 三大平台的配套应用，能够系统性处理从本地开发环境到生产部署的各种连接场景。

显著优点

拓扑感知的诊断逻辑：工具内置四种路由场景的明确区分（同机/模拟器/USB 隧道、局域网 Wi-Fi、Tailscale 虚拟网络、公网 URL/反向代理），避免常见的"混合调试"错误。当用户报告连接失败时，它会优先确认实际意图的网络路径，而非盲目尝试多种方案。

标准化检查流程：提供 openclaw qr --json 为核心的一整套验证命令，确保诊断结果与 Android 应用实际扫描的二维码载荷完全一致。通过解析 gatewayUrl 和 urlSource 字段，可以精确定位配置生效路径，杜绝"我以为配置的是公网地址但实际还是 localhost"这类隐蔽问题。

精确的错误映射：将应用端的模糊报错（如"pairing required"、"unauthorized"、"bootstrap token invalid"）与后端状态精确关联，区分网络层可达性问题与授权层配置问题，大幅降低修复方向的误判率。

潜在局限

前置知识门槛：有效使用该技能需要理解 OpenClaw 的配置体系（gateway.bind、gateway.tailscale.mode、gateway.remote.url 等）以及 Tailscale 网络的基础概念，对纯终端用户不够友好。

依赖外部工具链：诊断流程需要同时操作 openclaw CLI 和 tailscale CLI，在受限环境或容器化部署中可能无法完整执行。

无自动修复能力：工具定位为诊断指引，所有修复步骤仍需人工执行配置变更和重启操作，不提供一键修复功能。

适用人群

• 部署和维护 OpenClaw 网关的系统管理员
• 开发 OpenClaw 配套应用的工程师
• 需要远程访问本地服务的进阶用户（已配置或计划配置 Tailscale）

常规风险

配置变更可能影响正在运行的服务可用性，特别是修改 gateway.bind 或启用 gateway.tailscale.mode 后需要重启网关进程。建议在低峰期执行网络层配置的变更，并在变更前备份当前配置。

核心用法

node-connect 是一款纯文档型故障诊断 Skill，专注于解决 OpenClaw 网关与 Android/iOS/macOS 伴侣应用之间的连接和配对失败问题。它不提供可执行代码，而是通过系统化的诊断流程帮助用户定位问题根因。

诊断流程框架：
1. 拓扑确认：首先明确网络场景（同机/模拟器、局域网 Wi-Fi、Tailscale 虚拟网络、公网 URL），禁止混合诊断
2. 信息收集：要求用户提供确切错误文本、连接方式（QR/手动）、以及 openclaw devices list 输出
3. 配置验证：通过标准命令集检查网关绑定模式、认证配置、Tailscale 状态及设备配对队列
4. 根因映射：将症状映射到具体问题（如仅绑定回环地址、Tailscale IP 未获取、配对待审批、令牌过期等）

显著优点

• 结构化诊断：强制要求先确认网络拓扑再动手，避免常见"乱枪打鸟"式排查
• 命令标准化：提供完整的配置查询命令集，确保诊断结果可复现
• 场景覆盖全面：从本地开发到远程 VPS、从 Tailscale 到公网反向代理，覆盖四大典型部署模式
• 零代码风险：纯 Markdown 文档，无脚本执行、无外部依赖、无权限操作

潜在局限

• 需用户手动执行命令并反馈输出，无法自动化检测
• 对 Tailscale 网络问题仅能给出配置建议，无法直接修复 Tailscale 本身故障
• 依赖用户对 OpenClaw CLI 的基础熟悉度
• 未涵盖防火墙、路由器端口转发等底层网络基础设施问题

适合人群

• 部署 OpenClaw 网关并遇到伴侣应用连接问题的用户
• 需要区分"网络不通"和"认证失败"两种失败模式的开发者
• 使用 Tailscale 进行异地组网但配置不熟悉的自托管用户

常规风险

• 诊断过程中可能暴露网关配置信息，建议在安全环境分享输出
• 误操作 openclaw devices approve 可能授权非预期设备，需确认 pending 设备来源
• 生成新 setup code 会使旧代码失效，需确保伴侣应用及时重新扫描