# OpenClaw Official Documentation — Troubleshooting Reference

Compiled from local docs at `/opt/homebrew/lib/node_modules/openclaw/docs/`
Online mirror: https://docs.openclaw.ai
GitHub source: https://github.com/openclaw/openclaw

---

# SECTION 1: GENERAL TROUBLESHOOTING TRIAGE

Source: `/help/troubleshooting` | https://docs.openclaw.ai/help/troubleshooting

## First 60 seconds — run in this exact order:
```bash
openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow
```

**Healthy signals:**
- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok`
- `openclaw doctor` → no blocking issues
- `openclaw channels status --probe` → `works` or `audit ok` per channel
- `openclaw logs --follow` → steady activity, no repeating fatal errors

## Decision Tree

| Symptom | First Check | Deep Docs |
|---------|-------------|-----------|
| No replies | `openclaw channels status --probe` | /channels/troubleshooting |
| Dashboard won't connect | `openclaw gateway status` | /gateway/troubleshooting#dashboard |
| Gateway won't start | `openclaw gateway status --deep` | /gateway/troubleshooting#gateway-service-not-running |
| Channel connects, messages don't flow | `openclaw pairing list --channel <x>` | /gateway/troubleshooting#channel-connected |
| Cron/heartbeat didn't fire | `openclaw cron status` + `openclaw cron runs --id <id>` | /automation/cron-jobs#troubleshooting |
| Node tool fails | `openclaw nodes describe --node <id>` | /nodes/troubleshooting |
| Browser tool fails | `openclaw browser status` | /gateway/troubleshooting#browser-tool-fails |

---

# SECTION 2: GATEWAY TROUBLESHOOTING DEEP RUNBOOK

Source: `/gateway/troubleshooting` | https://docs.openclaw.ai/gateway/troubleshooting

## Command ladder (always run first):
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```

## After an update
```bash
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart
```
Look for: `plugin load failed: dependency tree corrupted; run openclaw doctor --fix`

## Split brain installs / newer config guard
```bash
which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion
```
Fix: `openclaw gateway install --force && openclaw gateway restart`

## Protocol mismatch after rollback
Look for: `protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>` in gateway logs.
Fix: Stop the stale client process, restart apps/wrappers, recheck `openclaw gateway status --deep`.

## Skill symlink skipped as path escape
Log: `Skipping escaped skill path outside its configured root: ... reason=symlink-escape`
Fix: Add to config:
```json
{ "skills": { "load": { "allowSymlinkTargets": ["~/Projects/manager/skills"] } } }
```

## Anthropic 429 — Extra usage required for long context
```bash
openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models
```
Fix: Use standard context window model, or eligible Anthropic credential.

## Upstream 403 blocked responses
Check for WAF/CDN blocking. Run minimal `curl` probe to verify the block is upstream, not config.

## Local OpenAI-compatible backend passes probes but agent runs fail
Common signatures:
- `model_not_found` with local MLX/vLLM → verify `baseUrl` includes `/v1`
- `messages[...].content: invalid type: sequence` → set `compat.requiresStringContent: true`
- `incomplete turn detected ... stopReason=stop payloads=0` → backend returned empty content

## No replies
```bash
openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel>
openclaw logs --follow
```
Signatures:
- `drop guild message (mention required` → group mention gating
- `pairing request` → sender needs approval
- `blocked` / `allowlist` → sender/channel filtered

## Dashboard Control UI connectivity
```bash
openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789
```
Auth error codes:
| Code | Meaning | Fix |
|------|---------|-----|
| `AUTH_TOKEN_MISSING` | No shared token sent | Paste token in client |
| `AUTH_TOKEN_MISMATCH` | Wrong token | Token drift recovery checklist |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Stale device token | `openclaw devices list` then re-approve |
| `PAIRING_REQUIRED` | Device needs approval | `openclaw devices approve <requestId>` |

## Gateway service not running
```bash
openclaw gateway status
openclaw gateway status --deep
openclaw doctor
```
Signatures:
- `Gateway start blocked: set gateway.mode=local` → config lost local-mode stamp
- `refusing to bind gateway ... without auth` → non-loopback bind without auth
- `another gateway instance is already listening` / `EADDRINUSE` → port conflict
- `Other gateway-like services detected` → stale/parallel launchd units

## macOS gateway silently stops responding (then comes back when you touch dashboard)
```bash
ls ~/.openclaw/logs/stability/ | tail -5
openclaw gateway stability --bundle latest
pmset -g log | grep -iE "sleep|wake|maintenance" | tail -50
launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"
```
Root cause: Power Nap / Maintenance Sleep briefly puts Wi-Fi into state 0; ENETDOWN errors crash gateway.

Fix:
1. Upgrade past 2026.5.26 (ENETDOWN now logged as warning, not crash)
2. `sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0`
3. Add liveness watchdog:
```bash
state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')
if [ "$state" != "running" ]; then
  launchctl kickstart -k gui/$UID/ai.openclaw.gateway
fi
```

## Gateway exits during high memory use
```bash
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export
```
Look for: `Reason: diagnostic.memory.pressure.critical`, large session files in `Largest session files:`

## Gateway rejected invalid config
```bash
openclaw logs --follow
openclaw config validate
openclaw doctor
```
Files to check: `openclaw.json.rejected.*` and `openclaw.json.clobbered.*` next to active config.
Fix: `openclaw doctor --fix`

## Cron and heartbeat delivery
```bash
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
```
Signatures:
- `cron: scheduler disabled` → cron is off
- `heartbeat skipped reason=quiet-hours` → outside active hours window
- `heartbeat skipped reason=empty-heartbeat-file` → HEARTBEAT.md has no real content
- `heartbeat: unknown accountId` → bad delivery target

## Browser tool fails
```bash
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw doctor
```
Signatures:
- `unknown command "browser"` → `plugins.allow` excludes browser
- `Failed to start Chrome CDP on port` → browser process failed to launch
- `browser.executablePath not found` → bad executable path
- `No Chrome tabs found for profile="user"` → no open local Chrome tabs
- `Playwright is not available` → gateway build lacks browser runtime dependency

---

# SECTION 3: CHANNEL TROUBLESHOOTING

Source: `/channels/troubleshooting` | https://docs.openclaw.ai/channels/troubleshooting

## Telegram Failure Signatures
| Symptom | Fastest check | Fix |
|---------|--------------|-----|
| `/start` but no reply flow | `openclaw pairing list telegram` | Approve pairing or change DM policy |
| Bot online but group silent | Verify mention requirement + privacy mode | Disable privacy mode or mention bot |
| Send failures with network errors | `openclaw logs --follow` | Fix DNS/IPv6/proxy to `api.telegram.org` |
| Startup reports `getMe returned 401` | Check token source | Re-copy/regenerate BotFather token |
| Polling stalls | `openclaw logs --follow` for polling diagnostics | Upgrade; tune `pollingStallThresholdMs` |
| Allowlist blocks you after upgrade | `openclaw security audit` | `openclaw doctor --fix` or replace @username with numeric IDs |

Full docs: https://docs.openclaw.ai/channels/telegram#troubleshooting

## WhatsApp Failure Signatures
| Symptom | Fastest check | Fix |
|---------|--------------|-----|
| Connected but no DM replies | `openclaw pairing list whatsapp` | Approve sender |
| Group messages ignored | Check `requireMention` | Mention bot or relax policy |
| QR login times out 408 | Check gateway proxy env | Set `HTTPS_PROXY` |
| Random disconnect/relogin loops | `openclaw channels status --probe` + logs | Watch logs, restart gateway, relink if flapping |

## Discord Failure Signatures
| Symptom | Fastest check | Fix |
|---------|--------------|-----|
| Bot online but no guild replies | `openclaw channels status --probe` | Allow guild/channel + verify message content intent |
| Group messages ignored | Check logs for mention gating drops | Mention bot or set `requireMention: false` |
| DM replies missing | `openclaw pairing list discord` | Approve DM pairing |

---

# SECTION 4: AUTOMATION / CRON TROUBLESHOOTING

Source: `/automation/cron-jobs` | https://docs.openclaw.ai/automation/cron-jobs

## Cron Scheduler Checks
```bash
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow
```

## Common Cron Failure Signatures
- `cron: scheduler disabled; jobs will not run automatically` → enable cron
- `cron: timer tick failed` → check file/log/runtime errors
- `job interrupted by gateway restart` at same timestamp on 3+ jobs = single restart event, not individual failures
- `dispatch stall: isolated agent run stalled before execution start (last phase: attempt-dispatch)` → does NOT self-recover, fix the job

## Cron Job Schema
```json
{
  "name": "JOB-NAME",
  "schedule": { "kind": "cron", "expr": "0 2 * * *", "tz": "America/Los_Angeles" },
  "payload": { "kind": "agentTurn", "message": "...", "model": "openrouter/openai/gpt-5.5" },
  "sessionTarget": "isolated",
  "delivery": { "mode": "none" },
  "enabled": true
}
```

## sessionTarget Rules (CRITICAL)
- `sessionTarget: "main"` → REQUIRES `payload.kind: "systemEvent"`. agentTurn + main silently skips.
- `sessionTarget: "isolated"` → REQUIRES `payload.kind: "agentTurn"`
- Never use `message` tool inside isolated crons — no Telegram bot token in isolated sessions
- For isolated cron alerts: output text as agent reply OR use `openclaw message send` CLI

## Cron edit CLI flags
```bash
openclaw cron add --session isolated --cron "0 2 * * *" --timeout-seconds 300 --model openrouter/openai/gpt-5.5
openclaw cron edit <id> --channel telegram --announce     # correct delivery flags
# NO --delivery flag exists
# NO --tools-allow flag exists; use --clear-tools to remove allowlist
openclaw cron run <id>
```

## Heartbeat Skip Reasons
- `quiet-hours` → outside configured active window
- `empty-heartbeat-file` → HEARTBEAT.md has only comments/blank/scaffolding
- `no-tasks-due` → task-mode enabled but none due on this tick
- `requests-in-flight` → main lane busy, deferred
- `dm-blocked` → heartbeat target is DM-blocked per policy

---

# SECTION 5: GATEWAY CONFIGURATION REFERENCE

Source: `/gateway/configuration` | https://docs.openclaw.ai/gateway/configuration

## Key config paths
```
gateway.mode                    # "local" or "remote"
gateway.bind                    # loopback (default), lan, tailnet, custom
gateway.auth.mode               # shared-token, password, trusted-proxy
gateway.auth.token              # shared token
agents.defaults.models          # default model config
agents.defaults.heartbeat       # heartbeat config
channels.<id>                   # per-channel config
cron.*                          # cron scheduler config
tools.exec.host                 # auto, gateway, sandbox, node
tools.exec.security             # full, allowlist
tools.exec.ask                  # on, off, on-miss
plugins.allow                   # plugin allowlist
plugins.deny                    # plugin denylist
skills.load.extraDirs           # extra skill directories
models.providers.*              # custom model providers
mcp.servers.*                   # MCP server definitions
session.*                       # session lifecycle config
```

## Config validation
```bash
openclaw config validate
openclaw config file
openclaw config get <path>
openclaw config schema           # full live JSON schema
```

## Hot reload vs restart required
- Most config changes hot-reload automatically
- Plugin changes (`plugins.*`) require gateway restart
- `models.pricing.enabled` requires restart

## Config repair
```bash
openclaw doctor --fix            # repairs corrupted/clobbered config
# Inspect rejected edits:
ls ~/.openclaw/openclaw.json.rejected.*
ls ~/.openclaw/openclaw.json.clobbered.*
```

---

# SECTION 6: DEBUGGING TOOLS

Source: `/help/debugging` | https://docs.openclaw.ai/help/debugging

## Runtime debug overrides (memory only, not disk)
```
/debug show
/debug set messages.responsePrefix="[test]"
/debug unset messages.responsePrefix
/debug reset
```
Enable with `commands.debug: true`

## Session trace
```
/trace
/trace on
/trace off
```
Use for plugin diagnostics.

## Raw stream logging
```bash
OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
```
Captures raw assistant stream before filtering. Contains full prompts + tool output — keep local.

## Diagnostics export
```bash
openclaw gateway diagnostics export
openclaw gateway stability --bundle latest
```

---

# SECTION 7: GATEWAY HEALTH & LOGGING

Source: `/gateway/health` + `/gateway/logging` | https://docs.openclaw.ai/gateway/health

## Health checks
```bash
openclaw gateway status           # basic
openclaw gateway status --deep    # includes system-level service scan
openclaw gateway probe            # connectivity probe
openclaw gateway probe --json     # JSON output with warnings array
openclaw doctor                   # automated health checks
openclaw doctor --fix             # automated repair
```

## Log locations
- Gateway log: `~/Library/Logs/openclaw/gateway.log`
- Stability bundles: `~/.openclaw/logs/stability/`
- Raw stream: `~/.openclaw/logs/raw-stream.jsonl`

```bash
openclaw logs --follow
tail -f ~/Library/Logs/openclaw/gateway.log
```

## Memory pressure
Signs: `Reason: diagnostic.memory.pressure.critical` in stability bundle
```bash
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export
```

---

# SECTION 8: NODE TROUBLESHOOTING

Source: `/nodes/troubleshooting` | https://docs.openclaw.ai/nodes/troubleshooting

```bash
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
```

| Error code | Meaning | Fix |
|-----------|---------|-----|
| `NODE_BACKGROUND_UNAVAILABLE` | App not in foreground | Bring node app to foreground |
| `*_PERMISSION_REQUIRED` | OS permission missing | Grant permission in macOS Settings |
| `SYSTEM_RUN_DENIED: approval required` | Exec approval pending | Approve in OpenClaw |
| `SYSTEM_RUN_DENIED: allowlist miss` | Command not on allowlist | Add to allowlist |

---

# SECTION 9: KEY CLI REFERENCE

Source: `/cli/` | https://docs.openclaw.ai/cli/

## gateway
```bash
openclaw gateway status           # status
openclaw gateway status --deep    # full including system services
openclaw gateway restart          # restart
openclaw gateway start            # start
openclaw gateway stop             # stop
openclaw gateway install --force  # reinstall service
openclaw gateway probe            # connectivity probe
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export
```

## cron
```bash
openclaw cron list
openclaw cron list --json
openclaw cron status
openclaw cron add --session isolated --cron "0 2 * * *"
openclaw cron edit <id> [flags]
openclaw cron run <id>
openclaw cron runs --id <id> --limit 20
openclaw cron enable <id>
openclaw cron disable <id>
openclaw cron delete <id>
```

## doctor
```bash
openclaw doctor                   # run health checks
openclaw doctor --fix             # auto-repair
openclaw doctor --deep            # deep scan including system services
openclaw doctor --non-interactive # CI-safe
```

## config
```bash
openclaw config get <path>
openclaw config set <path> <value>
openclaw config validate
openclaw config file              # show active config path
openclaw config schema            # show live JSON schema
openclaw backup create --verify   # backup before risky changes
```

## sessions
```bash
openclaw sessions                  # list sessions (flags only, no subcommands)
openclaw sessions --active 60      # sessions active in last 60 min
openclaw sessions --json           # JSON output (pipe stderr separately)
```

## logs
```bash
openclaw logs --follow
openclaw logs --level debug
```

## update
```bash
openclaw update                    # NOT from inside gateway process
openclaw --version                 # verify installed version
openclaw update status --json      # check update availability
```

---

# SECTION 10: CONCEPTS — SESSION, COMPACTION, AGENT LOOP

Source: `/concepts/` | https://docs.openclaw.ai/concepts/

## Session lifecycle
- Sessions stored in `~/.openclaw/agents/<agent>/sessions/<sessionId>.jsonl`
- Compaction: long sessions are compressed to save context
- Pruning: old sessions cleaned up per `session.pruning` config
- Session poison pattern: `Invalid signature in thinking block` error = session bricked, start fresh

## Agent loop
- Each message → agent run → tool calls → response
- Heartbeat: periodic background run on `HEARTBEAT.md` schedule
- Isolated subagent: fresh session, no access to parent context unless `context=fork`
- `streamTo: "parent"` only valid with `runtime="acp"` — fails with subagent

## Model failover
- Configure fallback models in `agents.defaults.models.fallbacks`
- 429 rate limits → automatic retry with backoff
- Provider outage → failover to configured fallback

---

# SECTION 11: CONCEPTS — CONTEXT ENGINE & COMPACTION

Source: `/concepts/compaction` | https://docs.openclaw.ai/concepts/compaction

- Compaction triggers when context window approaches limit
- State: current tasks, decisions, memory written to `memory/session-state.md` before compaction
- After compaction: agent re-reads workspace files on next turn
- Context window management: flag at >60% to push work to subagents; write memory at >75%

---

# USEFUL DIAGNOSTIC ONE-LINERS

```bash
# Check all enabled crons and their last status
openclaw cron list --json | python3 -c "
import json, sys
data = json.loads(sys.stdin.read())
jobs = data.get('jobs', data) if isinstance(data, dict) else data
for j in jobs:
    print(f\"{j.get('id','?')[:8]} | {j.get('name','?')[:30]} | {j.get('lastRunStatus','?')} | err={j.get('consecutiveErrors',0)}\")
"

# Check gateway version vs installed
openclaw --version
node -e "const p='/opt/homebrew/lib/node_modules/openclaw/package.json';console.log(require(p).version)"

# Check launchd gateway state
launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

# Tail gateway log for errors
tail -100 ~/Library/Logs/openclaw/gateway.log | grep -i error

# Check macOS power events (sleep/wake causing gateway drops)
pmset -g log | grep -iE "sleep|wake|maintenance" | tail -20

# Verify Telegram bot token is set
python3 -c "
import json
with open('$HOME/.openclaw/clawdbot.json') as f:
    c = json.load(f)
t = c.get('channels',{}).get('telegram',{})
print('botToken set:', bool(t.get('botToken')))
"
```