OpenClaw Troubleshooter

Work through the decision tree below in order. Do not skip steps.

STEP 1 — Baseline check

openclaw health 2>&1
launchctl print gui/$UID/ai.openclaw.gateway 2>&1 | grep -E "state|pid|exit"
cat ~/.openclaw/logs/gateway.log | tail -20

Match your symptom:

SECTION A — Device role issue (most common failure)

Root cause: The CLI device is registered as role: node in the gateway. It needs role: operator to function. This is a pairing issue, not a gateway crash. The gateway process itself is usually still running.

A1 — Confirm gateway IS running

launchctl print gui/$UID/ai.openclaw.gateway 2>&1 | grep state
# → "state = running" means gateway is UP, problem is pairing only
# → anything else means gateway process is down (→ A2)

A2 — If gateway is DOWN, restart it

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist 2>&1
sleep 2
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist 2>&1
sleep 5
openclaw health

If plist doesn't exist:

openclaw gateway install
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
sleep 5
openclaw health

A3 — If gateway IS running but CLI role is wrong

⚠️ This requires Raphael to run an interactive command. You cannot fix this autonomously.

Tell Raphael:

"The OpenClaw gateway is running but my device needs operator approval. Please run this in a terminal and follow the prompts:

code

openclaw onboard

The prompts will ask to confirm security, then approve this device as operator."

After he runs it:

openclaw health   # should return OK
openclaw channels status

Why this keeps happening: The gateway's device registry survives restarts but does not auto-approve devices. Each time the gateway's device DB is cleared or replaced, the CLI needs re-pairing. This happens when: gateway reinstalled, plist replaced, or auth token regenerated.

SECTION B — Plugin disabled

openclaw plugins enable telegram
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
sleep 3
openclaw channels status

SECTION C — Channel not configured

openclaw plugins enable telegram
openclaw channels add --channel telegram --token "$TELEGRAM_BOT_TOKEN"
openclaw config set channels.telegram.dmPolicy pairing
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
sleep 3
openclaw channels status

SECTION D — Gateway CPU spike (99%+)

Cause: Almost always Section A — the role: node upgrade loop. The gateway processes hundreds of rejected upgrade requests per second.

# First fix Section A, then:
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
sleep 5
openclaw health

Note: openclaw gateway start --force does NOT exist. Use launchctl.

SECTION E — Unknown channel error

openclaw plugins enable telegram
openclaw channels add --channel telegram --token "..."

New user pairing (Telegram)

User messages bot → receives code like DMMD89RG:

openclaw pairing approve telegram DMMD89RG
openclaw config set channels.telegram.allowFrom '["8519931474"]'
launchctl kickstart -k gui/$UID/ai.openclaw.gateway

KNOWN STATE (2026-02-21)