Back to Details

openclaw-diagnose

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenClaw Diagnose

OpenClaw 诊断

When the user asks you to diagnose or fix OpenClaw gateway/node issues, follow this structured investigation.
当用户要求你诊断或修复OpenClaw网关/节点问题时，请遵循以下结构化排查步骤。

Step 1: Gather status

步骤1：收集状态信息

Run these in parallel:
bash
openclaw gateway status
openclaw node status
openclaw nodes status
openclaw nodes pending
并行运行以下命令：
bash
openclaw gateway status
openclaw node status
openclaw nodes status
openclaw nodes pending

Step 2: Analyze warnings

步骤2：分析警告信息

Look for these common issues:
排查以下常见问题：

Multiple gateway-like services detected

检测到多个类网关服务

  • Check if both 
    ai.openclaw.gateway
    and 
    ai.openclaw.node
    are registered as LaunchAgents
  • Use 
    launchctl print gui/$(id -u)/<label>
    to inspect each service
  • Use 
    lsof -iTCP:<port> -sTCP:LISTEN -P
    to confirm which process owns the port
  • The gateway listens on the port; the node host connects to the gateway on that port — they do NOT conflict
  • 检查
    ai.openclaw.gateway
    和
    ai.openclaw.node
    是否都已注册为LaunchAgents
  • 使用
    launchctl print gui/$(id -u)/<label>
    检查每个服务的状态
  • 使用
    lsof -iTCP:<port> -sTCP:LISTEN -P
    确认哪个进程占用了端口
  • 网关会监听端口；节点主机会连接到网关的该端口——二者不会产生冲突

Pairing required errors

需要配对的错误

  • Check 
    ~/.openclaw/logs/node.err.log
    for 
    pairing required
    or 
    ECONNREFUSED
  • If the node shows "pairing required", run 
    openclaw nodes pending
    to find the pending request
  • Approve with: 
    openclaw nodes approve <requestId>
  • Pairing requests expire quickly — if approval fails with "unknown requestId", restart the node (
    openclaw node restart
    ) and immediately re-check pending + approve
  • 查看
    ~/.openclaw/logs/node.err.log
    中是否有
    pairing required
    或
    ECONNREFUSED
    信息
  • 如果节点显示“需要配对”，运行
    openclaw nodes pending
    查找待处理的配对请求
  • 使用以下命令批准请求：
    openclaw nodes approve <requestId>
  • 配对请求过期很快——如果批准时提示“unknown requestId”，请重启节点（
    openclaw node restart
    ）并立即重新检查待处理请求并批准

ECONNREFUSED errors

ECONNREFUSED错误

  • The gateway may not be running yet when the node starts
  • Check if gateway is listening: 
    lsof -iTCP:<port> -sTCP:LISTEN -P
  • If gateway is down: 
    openclaw gateway restart
  • The node has 
    KeepAlive: true
    so it will automatically reconnect once the gateway is up
  • 节点启动时网关可能尚未运行
  • 检查网关是否在监听：
    lsof -iTCP:<port> -sTCP:LISTEN -P
  • 如果网关未运行：
    openclaw gateway restart
  • 节点配置了
    KeepAlive: true
    ，因此网关启动后会自动重新连接

Step 3: Verify fix

步骤3：验证修复效果

After taking corrective action, confirm health:
bash
openclaw nodes status    # Should show: paired · connected
openclaw nodes pending   # Should show: No pending pairing requests
tail -5 ~/.openclaw/logs/node.err.log  # Check for new errors
采取纠正措施后，确认服务健康状态：
bash
openclaw nodes status    # 应显示：paired · connected
openclaw nodes pending   # 应显示：No pending pairing requests
tail -5 ~/.openclaw/logs/node.err.log  # 检查是否有新错误

Key architecture notes

关键架构说明

  • Gateway (
    ai.openclaw.gateway
    ): WebSocket server that listens on a port (default 18789)
  • Node host (
    ai.openclaw.node
    ): Client that connects to the gateway via WebSocket to register capabilities (browser, system commands)
  • The 
    --host
    and 
    --port
    flags on 
    openclaw node run
    specify the gateway address to connect to, not a port to bind
  • One gateway supports multiple nodes — running both on the same machine is the normal setup
  • Node plist is at 
    ~/Library/LaunchAgents/ai.openclaw.node.plist
  • Gateway plist is at 
    ~/Library/LaunchAgents/ai.openclaw.gateway.plist
  • Node logs: 
    ~/.openclaw/logs/node.log
    and 
    ~/.openclaw/logs/node.err.log
  • 网关（
    ai.openclaw.gateway
    ）：WebSocket服务器，监听指定端口（默认18789）
  • 节点主机（
    ai.openclaw.node
    ）：客户端，通过WebSocket连接到网关以注册功能（浏览器、系统命令）
  • openclaw node run
    命令中的
    --host
    和
    --port
    参数指定的是要连接的网关地址，而非要绑定的端口
  • 一个网关支持多个节点——同一机器上同时运行二者是常规配置
  • 节点的plist文件位于
    ~/Library/LaunchAgents/ai.openclaw.node.plist
  • 网关的plist文件位于
    ~/Library/LaunchAgents/ai.openclaw.gateway.plist
  • 节点日志：
    ~/.openclaw/logs/node.log
    和
    ~/.openclaw/logs/node.err.log