OpenClaw troubleshooting session — 2026-05-08

This is a chronological record of a session where the user (cawl, on macOS) repaired their OpenClaw install after a failed update. Written to give OpenClaw context on what was done to its install.

Initial symptom

After an attempted update, the OpenClaw app on macOS was unresponsive / showed a "gateway connection error." A previous attempt to restart had been resolved manually by the user. On this attempt, the app launched but could not connect to its gateway.

Environment

• Host: Belisariuss-MacBook-Pro (macOS 15+)
• User: cawl
• OpenClaw .app was at /Applications/OpenClaw.app
• OpenClaw data dir: ~/.openclaw/ (rich tree: agents, flows, memory, credentials, plugins, workspace, etc.)
• Auxiliary state: ~/Library/Application Support/OpenClaw/ (bridge.sock, identity/)
• Local services seen running: clawmetry on 127.0.0.1:8900, Ollama on 127.0.0.1:11434
• Gateway expected at ws://127.0.0.1:18789

Diagnostic steps taken

1. Confirmed processes were running:
   • OpenClaw UI (PID 4742) and several openclaw workers (high CPU — stuck in retry loops).
   • clawmetry Python daemon (PID 4737) bound to localhost:8900.
   • No process listening on 127.0.0.1:18789 (the gateway port).
2. Ruled out stale processes: pkill -9 -f -i openclaw && pkill -9 -f clawmetry, then open -a OpenClaw. Workers came back fresh; gateway port still unbound.
3. Tried moving ~/Library/Application Support/OpenClaw/identity/ aside in case the update invalidated identity state. Did not fix it. (A copy/paste duplication of the rollback commands accidentally deleted identity/ entirely; this is harmless — OpenClaw recreates it on next launch and the user just has to re-auth.)
4. Pulled system log: log show --predicate 'process == "OpenClaw" OR process CONTAINS[c] "claw"' --last 15m --info --debug.

Root-cause finding (from the log)

The smoking gun:

[ai.openclaw:gateway.launchd] Gateway daemon command failed (exit 1):
Gateway install blocked: Refusing to install or rewrite the gateway service
because this OpenClaw binary (2026.4.26) is older than the config last
written by OpenClaw 2026.5.6.

The running OpenClaw binary was 2026.4.26, but ~/.openclaw/openclaw.json had last been written by version 2026.5.6. The (older) binary refused to install/rewrite the launchd-managed gateway service over a newer-version config, so the gateway never started, and the UI got "no gateway."

Confirmed the binary version from the bundle on disk:

plutil -p ~/Desktop/OpenClaw.app.old/Contents/Info.plist | grep -i version
  "CFBundleShortVersionString" => "2026.4.26"
  "CFBundleVersion" => "2026042690"

(The bundle had been moved to ~/Desktop/OpenClaw.app.old during cleanup.)

Why the binary stayed old across updates

This was the underlying cause discovered later by openclaw doctor:

Gateway service entrypoint resolves to a source checkout: /Users/cawl/openclaw Gateway service entrypoint does not match the current install: /Users/cawl/openclaw/dist/index.js -> /opt/homebrew/lib/node_modules/openclaw/dist/index.js

The launchd plist for the OpenClaw gateway was hard-wired to launch from a source checkout at /Users/cawl/openclaw/ (probably from an early git clone). Subsequent npm updates were correctly installing into /opt/homebrew/lib/node_modules/openclaw/, but the launchd-managed gateway daemon kept running the stale source-checkout copy. So the npm package version moved forward while the daemon stayed at 2026.4.26. The newer npm version wrote the 2026.5.6 config, the old daemon refused to reconcile, and the gateway was permanently down.

Fix applied

1. Killed all OpenClaw processes:

   pkill -9 -f -i openclaw && pkill -9 -f clawmetry

2. Ran the official installer:

   curl -fsSL https://openclaw.ai/install.sh | bash

   • Installer detected the existing install and upgraded.
   • Installed openclaw v2026.5.7 (commit eeef486) via npm at /opt/homebrew/lib/node_modules/openclaw/.
   • Used Node v25.9.0 / npm 11.12.1 from Homebrew.
3. Installer ran openclaw doctor to migrate settings.
4. Doctor surfaced the gateway-entrypoint mismatch and asked whether to update the gateway service config to the recommended defaults. Answered Yes, which re-pointed the launchd service from /Users/cawl/openclaw/dist/index.js to /opt/homebrew/lib/node_modules/openclaw/dist/index.js.

Verification

After doctor finished, the gateway was finally listening:

$ lsof -iTCP:18789 -P
node    5843 cawl   20u  IPv4   TCP localhost:18789 (LISTEN)
node    5843 cawl   21u  IPv6   TCP localhost:18789 (LISTEN)
node    5843 cawl   34u  IPv4   TCP localhost:18789->localhost:64727 (ESTABLISHED)
Google  48448 cawl   30u  IPv4   TCP localhost:64727->localhost:18789 (ESTABLISHED)

node (PID 5843) is the new gateway daemon listening on 18789, with an ESTABLISHED connection from the OpenClaw UI in Chrome. Gateway connection error cleared.

Outstanding (non-blocking) items doctor reported

1. messages.groupChat.visibleReplies is set to "message_tool", but the message tool is unavailable for agent "main", agent "sonnet-worker", and 5 more. OpenClaw is falling back to automatic visible replies. Either enable the message tool for those agents or set messages.groupChat.visibleReplies to "automatic".
2. No command owner is configured. Doctor's recommended fix:

   openclaw config set commands.ownerAllowFrom '["telegram:<your-id>"]'

   (then restart the gateway).
3. 6 orphan transcript files in ~/.openclaw/agents/main/sessions/. Not yet archived (user answered "No" when prompted). Reversible if archived — doctor only renames them to *.deleted.<timestamp>.
4. The stale source checkout at /Users/cawl/openclaw/ is no longer referenced by launchd, but still exists on disk. Optional: remove or rename to prevent any future tool from accidentally launching from it.

Summary

Root cause: launchd gateway service was launching from /Users/cawl/openclaw/ (a source checkout pinned at 2026.4.26) instead of the npm-installed package, so updates didn't actually update the running daemon. The old daemon then refused to install the gateway service because the on-disk config had been written by a newer version (2026.5.6).

Fix: Reinstalled via curl … install.sh | bash (got 2026.5.7), and let openclaw doctor repoint the gateway service config to the npm install path.

Status: Gateway up, UI connected, app working again.