openclaw — Маршрутизация AI-агентов по мессенджерам

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