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

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