OpenClaw Guide Maintenance

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	Per-channel setup (WhatsApp, Telegram, Discord, etc.)
channel_troubleshooting.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
~/.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

text

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:18789/
• Protocol: WebSocket (JSON text frames)

Core Workflow

Diagnosing Issues

Always follow this command ladder:

1. openclaw status — quick overview
2. openclaw gateway status — daemon running? RPC probe ok?
3. openclaw logs --follow — watch for errors
4. openclaw doctor — config/service diagnostics
5. openclaw channels status --probe — per-channel health

Starting / Restarting Gateway

bash

# Foreground with verbose logging
openclaw gateway --port 18789 --verbose

# Force-kill existing listener then start
openclaw gateway --force

# Service management (launchd on macOS, systemd on Linux)
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

Configuration

Edit config via any method:

bash

# Interactive wizard
openclaw onboard                    # Full setup
openclaw configure                  # Config wizard

# CLI one-liners
openclaw config get <path>          # Read value
openclaw config set <path> <value>  # Set value (JSON5 or raw string)
openclaw config unset <path>        # Remove value

# Direct edit
# Edit ~/.openclaw/openclaw.json (JSON5 format)
# Gateway hot-reloads on save (if gateway.reload.mode != "off")

Minimal config example:

json5

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["[phone]"] } },
}

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:

bash

# Interactive wizard
openclaw channels add

# Non-interactive
openclaw channels add --channel telegram --account default --name "My Bot" --token $BOT_TOKEN
openclaw channels login --channel whatsapp     # QR pairing for WhatsApp
openclaw channels status --probe               # Verify

Model Provider Setup

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

bash

# Set default model
openclaw models set anthropic/claude-sonnet-4-5

# List available models
openclaw models list --all

# Check auth/token status
openclaw models status --probe

# Add auth interactively
openclaw models auth add

Config example:

json5

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
    },
  },
}

Multi-Agent Routing

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

bash

openclaw agents add <id>                # Create agent
openclaw agents list --bindings         # Show agent-channel bindings
openclaw agents delete <id>             # Remove agent

Nodes (iOS / Android / macOS / Headless)

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

bash

openclaw nodes status                   # List connected nodes
openclaw nodes describe --node <id>     # Node capabilities
openclaw devices list                   # Pending device approvals
openclaw devices approve <requestId>    # Approve a device
openclaw node run --host <host> --port 18789  # Start headless node host

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.

bash

openclaw security audit                 # Check posture
openclaw security audit --deep          # Live gateway probe
openclaw security audit --fix           # Auto-fix safe issues
openclaw secrets reload                 # Re-resolve secret refs
openclaw secrets audit                  # Scan for plaintext leaks

Update / Uninstall

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

bash

# Install (recommended)
curl -fsSL https://openclaw.ai/install.sh | bash

# Update
openclaw update                    # Self-update command
# Or: npm install -g openclaw@latest
openclaw doctor                    # Run after update to apply migrations

# Uninstall
openclaw uninstall

Tools Reference

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

For specific tools, see:

• references/exec.md — Exec tool deep-dive
• references/exec_approvals.md — Exec approvals and allowlists
• references/browser.md — Browser automation deep-dive
• references/web_tools.md — Web search/fetch with multiple providers
• references/lobster.md — Lobster workflow runtime
• references/llm_task.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
• group:fs — read, write, edit, apply_patch
• group:sessions — sessions_list/history/send/spawn, session_status
• group:memory — memory_search, memory_get
• group:web — web_search, web_fetch
• group:ui — browser, canvas
• group:automation — cron, gateway
• group:messaging — message
• group:nodes — nodes
• group:openclaw — all built-in OpenClaw tools (excludes provider plugins)

Common Failure Signatures

Error	Cause	Fix
refusing to bind gateway ... without auth	Non-loopback bind without token	Set gateway.auth.token or gateway.auth.password
another gateway instance is already listening / EADDRINUSE	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
OPENCLAW_GATEWAY_TOKEN	Gateway auth token
OPENCLAW_GATEWAY_PASSWORD	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