docs(openclaw): add detailed architecture and health monitoring guide

2026-03-19 15:36:12 +01:00
parent 3bfe632055
commit 2a7ed4ea40
3 changed files with 148 additions and 0 deletions
@@ -0,0 +1,96 @@
+# OpenClaw Health Monitoring: MacBook Pro Node
+
+## 1. Quick Service Status (Launchd)
+
+Check if the node and tunnel services are reported as running by macOS:
+
+```bash
+launchctl list | grep ai.openclaw
+```
+*   `ai.openclaw.node`: The node runner.
+*   `ai.openclaw.ssh-tunnel`: The SSH entry tunnel.
+
+A status of `0` in the middle column usually indicates success. A positive number is the PID.
+
+## 2. Testing Connectivity (The "Curl" Test)
+
+Since the tunnel maps the gateway to your local loopback, you can probe the gateway's health endpoint directly from the MacBook terminal:
+
+```bash
+curl -i http://127.0.0.1:18789/health
+```
+*   **Success**: Returns `HTTP/1.1 200 OK` with a JSON body `{"ok":true,...}`.
+*   **Failure (Tunnel Down)**: `curl: (7) Failed to connect to 127.0.0.1 port 18789: Connection refused`.
+*   **Failure (Gateway Down)**: `curl: (52) Empty reply from server` or timeout (if SSH connected but gateway is dead).
+
+## 3. Log Inspection
+
+The LaunchAgents are configured to log to `~/.openclaw/logs/`.
+
+*   **Node Logs**: `tail -f ~/.openclaw/logs/node.err.log`
+    *   Look for: `[node] connected to gateway`, `[node] authenticated`.
+    *   Errors like `Device identity required` indicate a pairing/token issue.
+*   **Tunnel Logs**: `tail -f ~/.openclaw/logs/ssh-tunnel.err.log`
+    *   Look for: `Permission denied`, `Connection refused`, or `channel 0: open failed: connect failed`.
+    *   `Forwarding port 18789 to 172.18.0.2:18789` should be present.
+
+## 4. Using the Local CLI
+
+You can use the `openclaw` CLI directly on the MacBook to interact with the gateway through the tunnel.
+
+### Check Node Status
+```bash
+openclaw node status
+```
+
+### Manual Node Run (Foreground)
+If the background service is acting up, stop it and run in the foreground to see real-time output:
+```bash
+launchctl unload ~/Library/LaunchAgents/ai.openclaw.node.plist
+openclaw node run --host 127.0.0.1 --port 18789 --display-name "Debug Node"
+```
+
+## 5. Advanced RPC Diagnostics
+
+If you need to verify specific gateway states (e.g., if the node is actually visible in the `node.list`), you can use the RPC protocol. Since the `openclaw` CLI sometimes has scope issues, you can use a simple Node.js script (similar to the one on Luca) to send signed requests.
+
+**Example: Check Gateway Health via RPC**
+```bash
+OPENCLAW_WS_URL=ws://127.0.0.1:18789 \
+OPENCLAW_TOKEN=$(grep OPENCLAW_GATEWAY_TOKEN ~/Library/LaunchAgents/ai.openclaw.node.plist | sed -E 's/.*<string>(.*)<\/string>.*/\1/') \
+node -e "
+const WebSocket = require('ws');
+const ws = new WebSocket(process.env.OPENCLAW_WS_URL);
+ws.on('open', () => {
+  ws.send(JSON.stringify({
+    type: 'req', id: '1', method: 'connect',
+    params: { auth: { token: process.env.OPENCLAW_TOKEN }, role: 'operator', scopes: ['operator.read'] }
+  }));
+});
+ws.on('message', (data) => {
+  const msg = JSON.parse(data);
+  if (msg.method === 'connect') {
+     ws.send(JSON.stringify({ type: 'req', id: '2', method: 'health' }));
+  } else if (msg.id === '2') {
+     console.log(JSON.stringify(msg.payload, null, 2));
+     process.exit(0);
+  }
+});
+"
+```
+
+## 6. Restarting Services
+
+If things get stuck, the "Standard Restart" is:
+
+```bash
+# 1. Restart Tunnel
+launchctl unload ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist
+launchctl load ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist
+
+# 2. Restart Node
+launchctl unload ~/Library/LaunchAgents/ai.openclaw.node.plist
+launchctl load ~/Library/LaunchAgents/ai.openclaw.node.plist
+```
+
+Wait ~5 seconds between steps for the port to bind.