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)
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:
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 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 |
1---2name: openclaw3description: 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.4metadata:5 source: https://skillmd.com/skills/leoyeai-openclaw-master-skills/openclaw6---78# OpenClaw Maintenance Skill910OpenClaw 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.1112## Reference Files1314| Reference | Coverage |15|---|---|16| [channels.md](references/channels.md) | Per-channel setup (WhatsApp, Telegram, Discord, etc.) |17| [channel_troubleshooting.md](references/channel_troubleshooting.md) | Per-channel failure signatures and walkthroughs |18| [tools.md](references/tools.md) | Tools inventory (profiles, groups, all built-in tools) |19| [exec.md](references/exec.md) | Exec tool: parameters, config, PATH, security, process tool |20| [exec_approvals.md](references/exec_approvals.md) | Exec approvals: allowlists, safe bins, approval flow |21| [browser.md](references/browser.md) | Browser tool: profiles, CDP, relay, SSRF, Control API |22| [web_tools.md](references/web_tools.md) | Web tools: Brave, Perplexity, Gemini search providers |23| [pdf_tool.md](references/pdf_tool.md) | PDF tool: native/fallback modes, config, page filtering |24| [elevated.md](references/elevated.md) | Elevated mode: /elevated directives, sandbox breakout |25| [lobster.md](references/lobster.md) | Lobster: typed workflow runtime with approvals |26| [llm_task.md](references/llm_task.md) | LLM Task: JSON-only LLM step for structured output |27| [openprose.md](references/openprose.md) | OpenProse: multi-agent program runtime |28| [plugins.md](references/plugins.md) | Plugins: official list, config, manifest, CLI, authoring |29| [skills.md](references/skills.md) | Skills: locations, config, ClawHub, watcher, token impact |30| [providers.md](references/providers.md) | Model provider setup |31| [multi_agent.md](references/multi_agent.md) | Multi-agent routing |32| [nodes.md](references/nodes.md) | Nodes (iOS/Android/macOS/headless) |33| [security.md](references/security.md) | Security hardening |34| [secrets.md](references/secrets.md) | Secrets management (SecretRef, vault) |35| [sandboxing.md](references/sandboxing.md) | Sandboxing (Docker isolation) |36| [config_reference.md](references/config_reference.md) | Full config field reference |37| [gateway_ops.md](references/gateway_ops.md) | Gateway operations |38| [remote_access.md](references/remote_access.md) | Remote access, SSH, Tailscale, web dashboard |39| [sessions.md](references/sessions.md) | Session management, DM isolation, lifecycle, compaction |40| [hooks.md](references/hooks.md) | Hooks: internal event hooks, HTTP webhooks, authoring, CLI |41| [automation.md](references/automation.md) | Cron jobs, webhooks, Gmail Pub/Sub |42| [acp_agents.md](references/acp_agents.md) | ACP agents: spawn external AI runtimes (Codex, Claude, etc.) |43| [install.md](references/install.md) | Installation, updating, rollback, migration, uninstall |44| [web_ui.md](references/web_ui.md) | Web surfaces: Dashboard, Control UI, WebChat |45| [slash_commands.md](references/slash_commands.md) | Chat slash commands (/new, /model, /acp, etc.) |46| [platforms.md](references/platforms.md) | Platform-specific guides (macOS, iOS, Android, Linux, Windows) |47| [diffs_firecrawl.md](references/diffs_firecrawl.md) | Diffs plugin + Firecrawl anti-bot fallback |48| [subagents.md](references/subagents.md) | Sub-agents: nested spawning, thread binding, announce, tool policy |49| [memory.md](references/memory.md) | Memory system, vector search, hybrid BM25, compaction, QMD backend |50| [architecture.md](references/architecture.md) | Gateway architecture, wire protocol, pairing, invariants |51| [agent_runtime.md](references/agent_runtime.md) | Agent runtime, bootstrap files, agent loop, hooks, timeouts |52| [streaming.md](references/streaming.md) | Streaming + chunking: block streaming, coalescing, preview modes |53| [queue.md](references/queue.md) | Command queue: modes (steer/followup/collect), concurrency, per-session |54| [model_failover.md](references/model_failover.md) | Model failover, OAuth, auth profiles, cooldowns, billing disables |55| [clawhub.md](references/clawhub.md) | ClawHub: public skill registry, CLI commands, publish/install |56| [thinking.md](references/thinking.md) | Thinking levels, verbose directives, reasoning visibility |57| [polls.md](references/polls.md) | Polls: Telegram, WhatsApp, Discord, MS Teams |58| [voice.md](references/voice.md) | Talk Mode (voice interaction) + Voice Wake (wake words) |59| [presence_discovery.md](references/presence_discovery.md) | Presence system, discovery (Bonjour/Tailscale), transports |60| [gateway_internals.md](references/gateway_internals.md) | Network model, gateway lock, health checks, doctor, logging, background exec |61| [heartbeat.md](references/heartbeat.md) | Heartbeat: config, delivery, visibility, HEARTBEAT.md, per-agent |62| [bonjour.md](references/bonjour.md) | Bonjour/mDNS: TXT keys, wide-area DNS-SD, debugging, failure modes |63| [pairing.md](references/pairing.md) | Gateway pairing: node approval, CLI, API, auto-approval, storage |64| [tui.md](references/tui.md) | TUI: keyboard shortcuts, slash commands, pickers, local shell, delivery |65| [media.md](references/media.md) | Media: camera capture, images, audio/voice notes, transcription |66| [channel_routing.md](references/channel_routing.md) | Channel routing, session keys, agent selection, Mattermost, BlueBubbles |67686970## Quick Reference7172### Key Paths7374| Path | Purpose |75|---|---|76| `~/.openclaw/openclaw.json` | Main config (JSON5) |77| `~/.openclaw/.env` | Global env fallback |78| `~/.openclaw/workspace` | Default agent workspace |79| `~/.openclaw/agents/<id>/` | Per-agent state + sessions |80| `~/.openclaw/skills/` | Managed/local skills |81| `~/.openclaw/agents/<id>/qmd/` | QMD memory backend state |82| `~/.openclaw/agents/<id>/agent/auth-profiles.json` | Auth profiles + OAuth tokens |83| `OPENCLAW_CONFIG_PATH` | Override config location |84| `OPENCLAW_STATE_DIR` | Override state directory |85| `OPENCLAW_HOME` | Override home directory |8687### Essential Commands8889```90openclaw status # Overall status91openclaw gateway status # Gateway daemon status92openclaw gateway status --deep # Deep scan including system services93openclaw doctor # Diagnose config/service issues94openclaw doctor --fix # Auto-fix safe issues95openclaw logs --follow # Tail gateway logs96openclaw channels status --probe # Channel health check97openclaw security audit # Security posture check98openclaw security audit --fix # Auto-fix security issues99openclaw update # Self-update100openclaw dashboard # Open Control UI in browser101openclaw tui # Terminal UI (interactive REPL)102openclaw agent # Direct agent interaction via CLI103openclaw health # Health check104openclaw usage # Usage tracking105openclaw config validate # Validate config file106openclaw config file # Print active config path107openclaw sessions cleanup # Session disk cleanup108openclaw agents bindings # Agent-channel bindings109openclaw agents bind # Bind agent to account110openclaw agents unbind # Unbind agent111openclaw update --dry-run # Preview update112openclaw system presence # View connected clients/nodes113openclaw system heartbeat last # Last heartbeat info114openclaw system heartbeat now # Trigger heartbeat immediately115openclaw memory search <query> # CLI memory search116openclaw docs <query> # Search OpenClaw docs117openclaw nodes pending # List pending pairing requests118openclaw nodes approve <id> # Approve node pairing119openclaw nodes status # Show all paired nodes120openclaw health --json # Full health snapshot (JSON)121openclaw message send --media <p> # Send media message122```123124### Default Gateway125126- Bind: `127.0.0.1:18789` (loopback)127- Dashboard: `http://127.0.0.1:18789/`128- Protocol: WebSocket (JSON text frames)129130## Core Workflow131132### Diagnosing Issues133134Always follow this command ladder:1351361. `openclaw status` — quick overview1372. `openclaw gateway status` — daemon running? RPC probe ok?1383. `openclaw logs --follow` — watch for errors1394. `openclaw doctor` — config/service diagnostics1405. `openclaw channels status --probe` — per-channel health141142### Starting / Restarting Gateway143144```bash145# Foreground with verbose logging146openclaw gateway --port 18789 --verbose147148# Force-kill existing listener then start149openclaw gateway --force150151# Service management (launchd on macOS, systemd on Linux)152openclaw gateway install153openclaw gateway start154openclaw gateway stop155openclaw gateway restart156```157158### Configuration159160Edit config via any method:161162```bash163# Interactive wizard164openclaw onboard # Full setup165openclaw configure # Config wizard166167# CLI one-liners168openclaw config get <path> # Read value169openclaw config set <path> <value> # Set value (JSON5 or raw string)170openclaw config unset <path> # Remove value171172# Direct edit173# Edit ~/.openclaw/openclaw.json (JSON5 format)174# Gateway hot-reloads on save (if gateway.reload.mode != "off")175```176177Minimal config example:178179```json5180{181 agents: { defaults: { workspace: "~/.openclaw/workspace" } },182 channels: { whatsapp: { allowFrom: ["+15555550123"] } },183}184```185186### Channel Setup187188For detailed per-channel setup, see [references/channels.md](references/channels.md).189For per-channel troubleshooting (failure signatures, setup walkthroughs), see [references/channel_troubleshooting.md](references/channel_troubleshooting.md).190For plugins adding new channels (Matrix, Nostr, MS Teams, etc.), see [references/plugins.md](references/plugins.md).191192Quick channel add:193194```bash195# Interactive wizard196openclaw channels add197198# Non-interactive199openclaw channels add --channel telegram --account default --name "My Bot" --token $BOT_TOKEN200openclaw channels login --channel whatsapp # QR pairing for WhatsApp201openclaw channels status --probe # Verify202```203204### Model Provider Setup205206For detailed provider setup, see [references/providers.md](references/providers.md).207208```bash209# Set default model210openclaw models set anthropic/claude-sonnet-4-5211212# List available models213openclaw models list --all214215# Check auth/token status216openclaw models status --probe217218# Add auth interactively219openclaw models auth add220```221222Config example:223224```json5225{226 agents: {227 defaults: {228 model: {229 primary: "anthropic/claude-sonnet-4-5",230 fallbacks: ["openai/gpt-5.2"],231 },232 },233 },234}235```236237### Multi-Agent Routing238239For detailed multi-agent config, see [references/multi_agent.md](references/multi_agent.md).240241```bash242openclaw agents add <id> # Create agent243openclaw agents list --bindings # Show agent-channel bindings244openclaw agents delete <id> # Remove agent245```246247### Nodes (iOS / Android / macOS / Headless)248249For detailed node setup, see [references/nodes.md](references/nodes.md).250251```bash252openclaw nodes status # List connected nodes253openclaw nodes describe --node <id> # Node capabilities254openclaw devices list # Pending device approvals255openclaw devices approve <requestId> # Approve a device256openclaw node run --host <host> --port 18789 # Start headless node host257```258259### Security260261For detailed security hardening, see [references/security.md](references/security.md).262For secrets management (SecretRef, vault integration), see [references/secrets.md](references/secrets.md).263For sandboxing (Docker isolation for tools), see [references/sandboxing.md](references/sandboxing.md).264For full config field reference, see [references/config_reference.md](references/config_reference.md).265For remote access (SSH, Tailscale, VPN), see [references/remote_access.md](references/remote_access.md).266267```bash268openclaw security audit # Check posture269openclaw security audit --deep # Live gateway probe270openclaw security audit --fix # Auto-fix safe issues271openclaw secrets reload # Re-resolve secret refs272openclaw secrets audit # Scan for plaintext leaks273```274275### Update / Uninstall276277For detailed installation, updating, rollback, and migration guide, see [references/install.md](references/install.md).278279```bash280# Install (recommended)281curl -fsSL https://openclaw.ai/install.sh | bash282283# Update284openclaw update # Self-update command285# Or: npm install -g openclaw@latest286openclaw doctor # Run after update to apply migrations287288# Uninstall289openclaw uninstall290```291292## Tools Reference293294For detailed per-tool documentation, see [references/tools.md](references/tools.md).295296For specific tools, see:297- [references/exec.md](references/exec.md) — Exec tool deep-dive298- [references/exec_approvals.md](references/exec_approvals.md) — Exec approvals and allowlists299- [references/browser.md](references/browser.md) — Browser automation deep-dive300- [references/web_tools.md](references/web_tools.md) — Web search/fetch with multiple providers301- [references/lobster.md](references/lobster.md) — Lobster workflow runtime302- [references/llm_task.md](references/llm_task.md) — LLM Task for structured JSON output303- [references/openprose.md](references/openprose.md) — OpenProse multi-agent programs304- [references/plugins.md](references/plugins.md) — Plugin system (install, author, distribute)305- [references/skills.md](references/skills.md) — Skills system (load, config, ClawHub)306307For ACP agents (Codex, Claude Code, Gemini CLI, etc.), see [references/acp_agents.md](references/acp_agents.md).308For Diffs plugin and Firecrawl anti-bot fallback, see [references/diffs_firecrawl.md](references/diffs_firecrawl.md).309For chat slash commands (/new, /model, /acp, etc.), see [references/slash_commands.md](references/slash_commands.md).310For thinking levels (/think, /verbose, /reasoning), see [references/thinking.md](references/thinking.md).311For polls (Telegram, WhatsApp, Discord, MS Teams), see [references/polls.md](references/polls.md).312For Talk Mode and Voice Wake, see [references/voice.md](references/voice.md).313For Gateway architecture and wire protocol, see [references/architecture.md](references/architecture.md).314For agent runtime and loop details, see [references/agent_runtime.md](references/agent_runtime.md).315For command queue system, see [references/queue.md](references/queue.md).316For model failover and OAuth, see [references/model_failover.md](references/model_failover.md).317For ClawHub skill registry, see [references/clawhub.md](references/clawhub.md).318For presence and discovery, see [references/presence_discovery.md](references/presence_discovery.md).319For streaming and chunking, see [references/streaming.md](references/streaming.md).320For Gateway internals (network model, lock, health, doctor, logging), see [references/gateway_internals.md](references/gateway_internals.md).321For heartbeat system, see [references/heartbeat.md](references/heartbeat.md).322For Bonjour/mDNS discovery details, see [references/bonjour.md](references/bonjour.md).323For Gateway node pairing, see [references/pairing.md](references/pairing.md).324For Terminal UI (TUI), see [references/tui.md](references/tui.md).325For media (camera, images, audio), see [references/media.md](references/media.md).326For channel routing and session keys, see [references/channel_routing.md](references/channel_routing.md).327328**Tool profiles**: `minimal`, `coding`, `messaging`, `full` (default).329330**Tool groups** (for allow/deny):331- `group:runtime` — exec, bash, process332- `group:fs` — read, write, edit, apply_patch333- `group:sessions` — sessions_list/history/send/spawn, session_status334- `group:memory` — memory_search, memory_get335- `group:web` — web_search, web_fetch336- `group:ui` — browser, canvas337- `group:automation` — cron, gateway338- `group:messaging` — message339- `group:nodes` — nodes340- `group:openclaw` — all built-in OpenClaw tools (excludes provider plugins)341342## Common Failure Signatures343344| Error | Cause | Fix |345|---|---|---|346| `refusing to bind gateway ... without auth` | Non-loopback bind without token | Set `gateway.auth.token` or `gateway.auth.password` |347| `another gateway instance is already listening` / `EADDRINUSE` | Port conflict | `openclaw gateway --force` or change port |348| `Gateway start blocked: set gateway.mode=local` | Local mode not enabled | Set `gateway.mode="local"` |349| `unauthorized` / reconnect loop | Token/password mismatch | Check `OPENCLAW_GATEWAY_TOKEN` or config auth |350| `device identity required` | Missing device auth | Ensure client completes connect.challenge flow |351| No replies from bot | Pairing/allowlist/mention gating | Check `openclaw pairing list`, DM policy, mention patterns |352| `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 |353| `config change requires gateway restart (plugins.*)` | Plugin config changes can't hot-reload | Full `openclaw gateway restart` or `launchctl kickstart -k` |354| `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` |355| `Missing env var "X" referenced at config path: ...` | `.env` missing or variable not defined | Add variable to `~/.openclaw/.env` and restart Gateway |356357## Environment Variables358359| Variable | Purpose |360|---|---|361| `OPENCLAW_GATEWAY_TOKEN` | Gateway auth token |362| `OPENCLAW_GATEWAY_PASSWORD` | Gateway auth password |363| `OPENCLAW_GATEWAY_PORT` | Override gateway port |364| `OPENCLAW_CONFIG_PATH` | Override config file path |365| `OPENCLAW_STATE_DIR` | Override state directory |366| `OPENCLAW_HOME` | Override home directory |367| `OPENCLAW_LOAD_SHELL_ENV` | Import shell env (set to `1`) |368| `OPENCLAW_VERBOSE` | Verbose logging |369| `OPENCLAW_LOG_FILE` | File logging path |370| `OPENCLAW_LOG_LEVEL` | Log level control |371| `OPENCLAW_SHELL` | Set by OpenClaw in exec/acp/tui runtimes |372| `BRAVE_API_KEY` | For web_search tool |373| `FIRECRAWL_API_KEY` | For Firecrawl anti-bot fallback |374| `ELEVENLABS_API_KEY` | For Talk Mode TTS |375| `ELEVENLABS_VOICE_ID` | Default voice for Talk Mode |376| `CLAWHUB_TOKEN` | ClawHub API token for CI/automation |377| `CLAWHUB_WORKDIR` | ClawHub working directory override |378| `OLLAMA_API_KEY` | For Ollama embeddings provider |379