openclaw

Comprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.

# OpenClaw Maintenance Skill

OpenClaw is a self-hosted, open-source (MIT) gateway that routes AI agents across WhatsApp, Telegram, Discord, Slack, iMessage, Signal, and 15+ other channels simultaneously. It runs on macOS, Linux, or Windows.

## Reference Files

| Reference | Coverage |
|---|---|
| [channels.md](references/channels.md) | Per-channel setup (WhatsApp, Telegram, Discord, etc.) |
| [channel_troubleshooting.md](references/channel_troubleshooting.md) | Per-channel failure signatures and walkthroughs |
| [tools.md](references/tools.md) | Tools inventory (profiles, groups, all built-in tools) |
| [exec.md](references/exec.md) | Exec tool: parameters, config, PATH, security, process tool |
| [exec_approvals.md](references/exec_approvals.md) | Exec approvals: allowlists, safe bins, approval flow |
| [browser.md](references/browser.md) | Browser tool: profiles, CDP, relay, SSRF, Control API |
| [web_tools.md](references/web_tools.md) | Web tools: Brave, Perplexity, Gemini search providers |
| [pdf_tool.md](references/pdf_tool.md) | PDF tool: native/fallback modes, config, page filtering |
| [elevated.md](references/elevated.md) | Elevated mode: /elevated directives, sandbox breakout |
| [lobster.md](references/lobster.md) | Lobster: typed workflow runtime with approvals |
| [llm_task.md](references/llm_task.md) | LLM Task: JSON-only LLM step for structured output |
| [openprose.md](references/openprose.md) | OpenProse: multi-agent program runtime |
| [plugins.md](references/plugins.md) | Plugins: official list, config, manifest, CLI, authoring |
| [skills.md](references/skills.md) | Skills: locations, config, ClawHub, watcher, token impact |
| [providers.md](references/providers.md) | Model provider setup |
| [multi_agent.md](references/multi_agent.md) | Multi-agent routing |
| [nodes.md](references/nodes.md) | Nodes (iOS/Android/macOS/headless) |
| [security.md](references/security.md) | Security hardening |
| [secrets.md](references/secrets.md) | Secrets management (SecretRef, vault) |
| [sandboxing.md](references/sandboxing.md) | Sandboxing (Docker isolation) |
| [config_reference.md](references/config_reference.md) | Full config field reference |
| [gateway_ops.md](references/gateway_ops.md) | Gateway operations |
| [remote_access.md](references/remote_access.md) | Remote access, SSH, Tailscale, web dashboard |
| [sessions.md](references/sessions.md) | Session management, DM isolation, lifecycle, compaction |
| [hooks.md](references/hooks.md) | Hooks: internal event hooks, HTTP webhooks, authoring, CLI |
| [automation.md](references/automation.md) | Cron jobs, webhooks, Gmail Pub/Sub |
| [acp_agents.md](references/acp_agents.md) | ACP agents: spawn external AI runtimes (Codex, Claude, etc.) |
| [install.md](references/install.md) | Installation, updating, rollback, migration, uninstall |
| [web_ui.md](references/web_ui.md) | Web surfaces: Dashboard, Control UI, WebChat |
| [slash_commands.md](references/slash_commands.md) | Chat slash commands (/new, /model, /acp, etc.) |
| [platforms.md](references/platforms.md) | Platform-specific guides (macOS, iOS, Android, Linux, Windows) |
| [diffs_firecrawl.md](references/diffs_firecrawl.md) | Diffs plugin + Firecrawl anti-bot fallback |
| [subagents.md](references/subagents.md) | Sub-agents: nested spawning, thread binding, announce, tool policy |
| [memory.md](references/memory.md) | Memory system, vector search, hybrid BM25, compaction, QMD backend |
| [architecture.md](references/architecture.md) | Gateway architecture, wire protocol, pairing, invariants |
| [agent_runtime.md](references/agent_runtime.md) | Agent runtime, bootstrap files, agent loop, hooks, timeouts |
| [streaming.md](references/streaming.md) | Streaming + chunking: block streaming, coalescing, preview modes |
| [queue.md](references/queue.md) | Command queue: modes (steer/followup/collect), concurrency, per-session |
| [model_failover.md](references/model_failover.md) | Model failover, OAuth, auth profiles, cooldowns, billing disables |
| [clawhub.md](references/clawhub.md) | ClawHub: public skill registry, CLI commands, publish/install |
| [thinking.md](references/thinking.md) | Thinking levels, verbose directives, reasoning visibility |
| [polls.md](references/polls.md) | Polls: Telegram, WhatsApp, Discord, MS Teams |
| [voice.md](references/voice.md) | Talk Mode (voice interaction) + Voice Wake (wake words) |
| [presence_discovery.md](references/presence_discovery.md) | Presence system, discovery (Bonjour/Tailscale), transports |
| [gateway_internals.md](references/gateway_internals.md) | Network model, gateway lock, health checks, doctor, logging, background exec |
| [heartbeat.md](references/heartbeat.md) | Heartbeat: config, delivery, visibility, HEARTBEAT.md, per-agent |
| [bonjour.md](references/bonjour.md) | Bonjour/mDNS: TXT keys, wide-area DNS-SD, debugging, failure modes |
| [pairing.md](references/pairing.md) | Gateway pairing: node approval, CLI, API, auto-approval, storage |
| [tui.md](references/tui.md) | TUI: keyboard shortcuts, slash commands, pickers, local shell, delivery |
| [media.md](references/media.md) | Media: camera capture, images, audio/voice notes, transcription |
| [channel_routing.md](references/channel_routing.md) | Channel routing, session keys, agent selection, Mattermost, BlueBubbles |



## Quick Reference

### Key Paths

| Path | Purpose |
|---|---|
| `~/.openclaw/openclaw.json` | Main config (JSON5) |
| `~/.openclaw/.env` | Global env fallback |
| `~/.openclaw/workspace` | Default agent workspace |
| `~/.openclaw/agents/<id>/` | Per-agent state + sessions |
| `~/.openclaw/skills/` | Managed/local skills |
| `~/.openclaw/agents/<id>/qmd/` | QMD memory backend state |
| `~/.openclaw/agents/<id>/agent/auth-profiles.json` | Auth profiles + OAuth tokens |
| `OPENCLAW_CONFIG_PATH` | Override config location |
| `OPENCLAW_STATE_DIR` | Override state directory |
| `OPENCLAW_HOME` | Override home directory |

### Essential Commands

```
openclaw status                    # Overall status
openclaw gateway status            # Gateway daemon status
openclaw gateway status --deep     # Deep scan including system services
openclaw doctor                    # Diagnose config/service issues
openclaw doctor --fix              # Auto-fix safe issues
openclaw logs --follow             # Tail gateway logs
openclaw channels status --probe   # Channel health check
openclaw security audit            # Security posture check
openclaw security audit --fix      # Auto-fix security issues
openclaw update                    # Self-update
openclaw dashboard                 # Open Control UI in browser
openclaw tui                       # Terminal UI (interactive REPL)
openclaw agent                     # Direct agent interaction via CLI
openclaw health                    # Health check
openclaw usage                     # Usage tracking
openclaw config validate           # Validate config file
openclaw config file               # Print active config path
openclaw sessions cleanup          # Session disk cleanup
openclaw agents bindings           # Agent-channel bindings
openclaw agents bind               # Bind agent to account
openclaw agents unbind             # Unbind agent
openclaw update --dry-run          # Preview update
openclaw system presence           # View connected clients/nodes
openclaw system heartbeat last     # Last heartbeat info
openclaw system heartbeat now      # Trigger heartbeat immediately
openclaw memory search <query>     # CLI memory search
openclaw docs <query>              # Search OpenClaw docs
openclaw nodes pending             # List pending pairing requests
openclaw nodes approve <id>        # Approve node pairing
openclaw nodes status              # Show all paired nodes
openclaw health --json             # Full health snapshot (JSON)
openclaw message send --media <p>  # Send media message
```

### Default Gateway

- Bind: `127.0.0.1:18789` (loopback)
- Dashboard: `http://127.0.0.1: