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#

ReferenceCoveragechannels.mdPer-channel setup (WhatsApp, Telegram, Discord, etc.)channel_troubleshooting.mdPer-channel failure signatures and walkthroughstools.mdTools inventory (profiles, groups, all built-in tools)exec.mdExec tool: parameters, config, PATH, security, process toolexec_approvals.mdExec approvals: allowlists, safe bins, approval flowbrowser.mdBrowser tool: profiles, CDP, relay, SSRF, Control APIweb_tools.mdWeb tools: Brave, Perplexity, Gemini search providerspdf_tool.mdPDF tool: native/fallback modes, config, page filteringelevated.mdElevated mode: /elevated directives, sandbox breakoutlobster.mdLobster: typed workflow runtime with approvalsllm_task.mdLLM Task: JSON-only LLM step for structured outputopenprose.mdOpenProse: multi-agent program runtimeplugins.mdPlugins: official list, config, manifest, CLI, authoringskills.mdSkills: locations, config, ClawHub, watcher, token impactproviders.mdModel provider setupmulti_agent.mdMulti-agent routingnodes.mdNodes (iOS/Android/macOS/headless)security.mdSecurity hardeningsecrets.mdSecrets management (SecretRef, vault)sandboxing.mdSandboxing (Docker isolation)config_reference.mdFull config field referencegateway_ops.mdGateway operationsremote_access.mdRemote access, SSH, Tailscale, web dashboardsessions.mdSession management, DM isolation, lifecycle, compactionhooks.mdHooks: internal event hooks, HTTP webhooks, authoring, CLIautomation.mdCron jobs, webhooks, Gmail Pub/Subacp_agents.mdACP agents: spawn external AI runtimes (Codex, Claude, etc.)install.mdInstallation, updating, rollback, migration, uninstallweb_ui.mdWeb surfaces: Dashboard, Control UI, WebChatslash_commands.mdChat slash commands (/new, /model, /acp, etc.)platforms.mdPlatform-specific guides (macOS, iOS, Android, Linux, Windows)diffs_firecrawl.mdDiffs plugin + Firecrawl anti-bot fallbacksubagents.mdSub-agents: nested spawning, thread binding, announce, tool policymemory.mdMemory system, vector search, hybrid BM25, compaction, QMD backendarchitecture.mdGateway architecture, wire protocol, pairing, invariantsagent_runtime.mdAgent runtime, bootstrap files, agent loop, hooks, timeoutsstreaming.mdStreaming + chunking: block streaming, coalescing, preview modesqueue.mdCommand queue: modes (steer/followup/collect), concurrency, per-sessionmodel_failover.mdModel failover, OAuth, auth profiles, cooldowns, billing disablesclawhub.mdClawHub: public skill registry, CLI commands, publish/installthinking.mdThinking levels, verbose directives, reasoning visibilitypolls.mdPolls: Telegram, WhatsApp, Discord, MS Teamsvoice.mdTalk Mode (voice interaction) + Voice Wake (wake words)presence_discovery.mdPresence system, discovery (Bonjour/Tailscale), transportsgateway_internals.mdNetwork model, gateway lock, health checks, doctor, logging, background execheartbeat.mdHeartbeat: config, delivery, visibility, HEARTBEAT.md, per-agentbonjour.mdBonjour/mDNS: TXT keys, wide-area DNS-SD, debugging, failure modespairing.mdGateway pairing: node approval, CLI, API, auto-approval, storagetui.mdTUI: keyboard shortcuts, slash commands, pickers, local shell, deliverymedia.mdMedia: camera capture, images, audio/voice notes, transcriptionchannel_routing.mdChannel routing, session keys, agent selection, Mattermost, BlueBubbles

Quick Reference#

Key Paths#

PathPurpose~/.openclaw/openclaw.jsonMain config (JSON5)~/.openclaw/.envGlobal env fallback~/.openclaw/workspaceDefault 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.jsonAuth profiles + OAuth tokensOPENCLAW_CONFIG_PATHOverride config locationOPENCLAW_STATE_DIROverride state directoryOPENCLAW_HOMEOverride 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: ["+15555550123"] } },
}

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#

ErrorCauseFixrefusing to bind gateway ... without authNon-loopback bind without tokenSet gateway.auth.token or gateway.auth.password``another gateway instance is already listening / EADDRINUSEPort conflictopenclaw gateway --force or change portGateway start blocked: set gateway.mode=localLocal mode not enabledSet gateway.mode="local"``unauthorized / reconnect loopToken/password mismatchCheck OPENCLAW_GATEWAY_TOKEN or config authdevice identity requiredMissing device authEnsure client completes connect.challenge flowNo replies from botPairing/allowlist/mention gatingCheck openclaw pairing list, DM policy, mention patternsEmbedding 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 Gatewayconfig change requires gateway restart (plugins.*)Plugin config changes can't hot-reloadFull openclaw gateway restart or launchctl kickstart -k``Bootstrap failed: 5: Input/output errorLaunchAgent plist in stale/stuck stateopenclaw 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 definedAdd variable to ~/.openclaw/.env and restart Gateway

Environment Variables#

VariablePurposeOPENCLAW_GATEWAY_TOKENGateway auth tokenOPENCLAW_GATEWAY_PASSWORDGateway auth passwordOPENCLAW_GATEWAY_PORTOverride gateway portOPENCLAW_CONFIG_PATHOverride config file pathOPENCLAW_STATE_DIROverride state directoryOPENCLAW_HOMEOverride home directoryOPENCLAW_LOAD_SHELL_ENVImport shell env (set to 1)OPENCLAW_VERBOSEVerbose loggingOPENCLAW_LOG_FILEFile logging pathOPENCLAW_LOG_LEVELLog level controlOPENCLAW_SHELLSet by OpenClaw in exec/acp/tui runtimesBRAVE_API_KEYFor web_search toolFIRECRAWL_API_KEYFor Firecrawl anti-bot fallbackELEVENLABS_API_KEYFor Talk Mode TTSELEVENLABS_VOICE_IDDefault voice for Talk ModeCLAWHUB_TOKENClawHub API token for CI/automationCLAWHUB_WORKDIRClawHub working directory overrideOLLAMA_API_KEYFor Ollama embeddings provider