name: openclaw-guide-maintenance description: 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. version: 2026.3.9 tags: openclaw, gateway, devops, self-hosted, multi-channel, ai-agent license: MIT

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

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, auto-infers agent from cwd)
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 backup create             # Create local state archive
openclaw backup verify             # Verify backup integrity
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 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:

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

Starting / Restarting Gateway

# 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:

# 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:

{
  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:

# 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.

# 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:

{
  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.

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.

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.

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.

# 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 advanced internals and features, see:

references/thinking.md — Thinking levels (/think, /verbose, /reasoning)
references/polls.md — Polls (Telegram, WhatsApp, Discord, MS Teams)
references/voice.md — Talk Mode and Voice Wake
references/architecture.md — Gateway architecture and wire protocol
references/agent_runtime.md — Agent runtime and loop details
references/queue.md — Command queue system
references/model_failover.md — Model failover and OAuth
references/clawhub.md — ClawHub skill registry
references/presence_discovery.md — Presence and discovery
references/streaming.md — Streaming and chunking
references/gateway_internals.md — Gateway internals
references/heartbeat.md — Heartbeat system
references/bonjour.md — Bonjour/mDNS discovery details
references/pairing.md — Gateway node pairing
references/tui.md — Terminal UI (TUI)
references/media.md — Media (camera, images, audio)
references/channel_routing.md — Channel routing and session keys

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
`OPENCLAW_THEME`	Terminal theme override (`light` or `dark`)
`OPENCLAW_BIND_MOUNT_OPTIONS`	Override bind mount suffix for Podman SELinux (e.g., `:z`)
`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
`CLAWHUB_REGISTRY`	ClawHub registry API URL override
`OLLAMA_API_KEY`	For Ollama embeddings provider

OpenClaw Guide & Maintenance

Description

OpenClaw Maintenance Skill

Reference Files

Quick Reference

Key Paths

Essential Commands

Default Gateway

Core Workflow

Diagnosing Issues

Starting / Restarting Gateway

Configuration

Channel Setup

Model Provider Setup

Multi-Agent Routing

Nodes (iOS / Android / macOS / Headless)

Security

Update / Uninstall

Tools Reference

Common Failure Signatures

Environment Variables

Reviews (0)

Comments (0)

Compatible Platforms

Links

Pricing

Related Configs

self-improving-agent

Self Improving Agent

Find Skills

Summarize