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	Per-channel setup (WhatsApp, Telegram, Discord, etc.)
channeltroubleshooting.md

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

Quick Reference

Key Paths

Path	Purpose
INLINECODE0	Main config (JSON5)
INLINECODE1

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

CODEBLOCK0

Default Gateway

• - Bind: 127.0.0.1:18789 (loopback)
• Dashboard: INLINECODE11
• Protocol: WebSocket (JSON text frames)

Core Workflow

Diagnosing Issues

Always follow this command ladder:

1. 1. openclaw status — quick overview
2. INLINECODE13 — daemon running? RPC probe ok?
3. INLINECODE14 — watch for errors
4. INLINECODE15 — config/service diagnostics
5. INLINECODE16 — per-channel health

Starting / Restarting Gateway

CODEBLOCK1

Configuration

Edit config via any method:

CODEBLOCK2

Minimal config example:

CODEBLOCK3

Channel Setup

For detailed per-channel setup, see references/channels.md.
For per-channel troubleshooting (failure signatures, setup walkthroughs), see references/channel_troubleshooting.md.
For plugins adding new channels (Matrix, Nostr, MS Teams, etc.), see references/plugins.md.

Quick channel add:

CODEBLOCK4

Model Provider Setup

For detailed provider setup, see references/providers.md.

CODEBLOCK5

Config example:

CODEBLOCK6

Multi-Agent Routing

For detailed multi-agent config, see references/multi_agent.md.

CODEBLOCK7

Nodes (iOS / Android / macOS / Headless)

For detailed node setup, see references/nodes.md.

CODEBLOCK8

Security

For detailed security hardening, see references/security.md.
For secrets management (SecretRef, vault integration), see references/secrets.md.
For sandboxing (Docker isolation for tools), see references/sandboxing.md.
For full config field reference, see references/config_reference.md.
For remote access (SSH, Tailscale, VPN), see references/remote_access.md.

CODEBLOCK9

Update / Uninstall

For detailed installation, updating, rollback, and migration guide, see references/install.md.

CODEBLOCK10

Tools Reference

For detailed per-tool documentation, see references/tools.md.

For specific tools, see:

• - references/exec.md — Exec tool deep-dive
• references/execapprovals.md — Exec approvals and allowlists
• references/browser.md — Browser automation deep-dive
• references/webtools.md — Web search/fetch with multiple providers
• references/lobster.md — Lobster workflow runtime
• references/llmtask.md — LLM Task for structured JSON output
• references/openprose.md — OpenProse multi-agent programs
• references/plugins.md — Plugin system (install, author, distribute)
• references/skills.md — Skills system (load, config, ClawHub)

For ACP agents (Codex, Claude Code, Gemini CLI, etc.), see references/acp_agents.md.
For Diffs plugin and Firecrawl anti-bot fallback, see references/diffs_firecrawl.md.
For chat slash commands (/new, /model, /acp, etc.), see references/slash_commands.md.
For thinking levels (/think, /verbose, /reasoning), see references/thinking.md.
For polls (Telegram, WhatsApp, Discord, MS Teams), see references/polls.md.
For Talk Mode and Voice Wake, see references/voice.md.
For Gateway architecture and wire protocol, see references/architecture.md.
For agent runtime and loop details, see references/agent_runtime.md.
For command queue system, see references/queue.md.
For model failover and OAuth, see references/model_failover.md.
For ClawHub skill registry, see references/clawhub.md.
For presence and discovery, see references/presence_discovery.md.
For streaming and chunking, see references/streaming.md.
For Gateway internals (network model, lock, health, doctor, logging), see references/gateway_internals.md.
For heartbeat system, see references/heartbeat.md.
For Bonjour/mDNS discovery details, see references/bonjour.md.
For Gateway node pairing, see references/pairing.md.
For Terminal UI (TUI), see references/tui.md.
For media (camera, images, audio), see references/media.md.
For channel routing and session keys, see references/channel_routing.md.

Tool profiles: minimal, coding, messaging, full (default).

Tool groups (for allow/deny):

• - group:runtime — exec, bash, process
• INLINECODE22 — read, write, edit, applypatch
• INLINECODE23 — sessionslist/history/send/spawn, sessionstatus
• INLINECODE24 — memorysearch, memoryget
• INLINECODE25 — websearch, web_fetch
• INLINECODE26 — browser, canvas
• INLINECODE27 — cron, gateway
• INLINECODE28 — message
• INLINECODE29 — nodes
• INLINECODE30 — all built-in OpenClaw tools (excludes provider plugins)

Common Failure Signatures

Error	Cause	Fix
INLINECODE31	Non-loopback bind without token	Set gateway.auth.token or INLINECODE33
INLINECODE34 / INLINECODE35

Port conflict | openclaw gateway --force or change port | | Gateway start blocked: set gateway.mode=local | Local mode not enabled | Set gateway.mode="local" | | unauthorized / reconnect loop | Token/password mismatch | Check OPENCLAW_GATEWAY_TOKEN or config auth | | device identity required | Missing device auth | Ensure client completes connect.challenge flow | | No replies from bot | Pairing/allowlist/mention gating | Check openclaw pairing list, DM policy, mention patterns | | Embedding provider authentication failed (401) | .env has placeholder API key (e.g. your-jina-api-key-here) | Replace with real API key in ~/.openclaw/.env, restart Gateway | | config change requires gateway restart (plugins.*) | Plugin config changes can't hot-reload | Full openclaw gateway restart or launchctl kickstart -k | | Bootstrap failed: 5: Input/output error | LaunchAgent plist in stale/stuck state | openclaw gateway install then launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway | | Missing env var "X" referenced at config path: ... | .env missing or variable not defined | Add variable to ~/.openclaw/.env and restart Gateway |

Environment Variables

Variable	Purpose
INLINECODE56	Gateway auth token
INLINECODE57

Gateway auth password | | OPENCLAW_GATEWAY_PORT | Override gateway port | | OPENCLAW_CONFIG_PATH | Override config file path | | OPENCLAW_STATE_DIR | Override state directory | | OPENCLAW_HOME | Override home directory | | OPENCLAW_LOAD_SHELL_ENV | Import shell env (set to 1) | | OPENCLAW_VERBOSE | Verbose logging | | OPENCLAW_LOG_FILE | File logging path | | OPENCLAW_LOG_LEVEL | Log level control | | OPENCLAW_SHELL | Set by OpenClaw in exec/acp/tui runtimes | | BRAVE_API_KEY | For web_search tool | | FIRECRAWL_API_KEY | For Firecrawl anti-bot fallback | | ELEVENLABS_API_KEY | For Talk Mode TTS | | ELEVENLABS_VOICE_ID | Default voice for Talk Mode | | CLAWHUB_TOKEN | ClawHub API token for CI/automation | | CLAWHUB_WORKDIR | ClawHub working directory override | | OLLAMA_API_KEY | For Ollama embeddings provider |