Openclaw-docs-skill openclaw-docs

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.

install

source · Clone the upstream repo

git clone https://github.com/tbdavid2019/openclaw-docs-skill

Claude Code · Install into ~/.claude/skills/

git clone --depth=1 https://github.com/tbdavid2019/openclaw-docs-skill ~/.claude/skills/tbdavid2019-openclaw-docs-skill-openclaw-docs

OpenClaw · Install into ~/.openclaw/skills/

git clone --depth=1 https://github.com/tbdavid2019/openclaw-docs-skill ~/.openclaw/skills/tbdavid2019-openclaw-docs-skill-openclaw-docs

manifest: SKILL.md

source content

OpenClaw Maintenance Skill

[!CAUTION]

Installed Skill Refresh Boundary

Keep the installed skill as a git checkout if updates are expected to work.

Use this boundary:
If available, run
bash <skill-directory>/scripts/install-skill.sh <skill-directory>
in the final installed directory. If this did not happen, treat the installation as incomplete.
Only auto-update with
git -C <skill-directory> pull origin main --ff-only
when
<skill-directory>/.git
exists.
Do not run repo-maintenance scripts such as
scripts/sync-docs.sh
or
scripts/generate_index.py
during normal skill usage.
If refresh fails, continue with the local files and do not block the user.

OpenClaw is a self-hosted, open-source gateway that routes AI agents across WhatsApp, Telegram, Discord, Slack, iMessage, Signal, and 15+ other channels simultaneously.

Find the local skill directory — it will be somewhere under the agent's skills path (e.g.,
```
~/.gemini/antigravity/skills/openclaw-docs/
```
).

Before using the docs, run the installer script in the final installed directory when available:

bash <skill-directory>/scripts/install-skill.sh <skill-directory>

If the installer script is unavailable, only then fall back to a direct pull when

<skill-directory>/.git

exists:

git -C <skill-directory> pull origin main --ff-only

After pulling, reload any reference files you are about to use.

If refresh fails (no internet, API rate limit, git not available, or non-git install) → silently continue using the local version. Never block the user.
If already up-to-date → proceed normally with no output to the user.

Key principle: Prefer an installed git checkout plus the installer script. If the host platform only copied files, use the local docs without blocking the user.

Use

view_file

grep_search

to read these references as needed.

MANDATORY: Always check references/SKILL_INDEX.md first to locate the exact documentation needed for any OpenClaw task.

Reference	Coverage
SKILL_INDEX.md	Directory of ALL available documentation (Start here)
channels/	Channel setup (WhatsApp, Telegram, Discord, Slack, iMessage, etc.)
providers/	Model provider setup (Anthropic, OpenAI, Google, Ollama, etc.)
tools/	Detailed per-tool documentation (exec, browser, web, etc.)
gateway/	Gateway operations, config, and security
automation/	Cron jobs, webhooks, and background tasks
concepts/	Core concepts: agent loop, memory, queue, sessions
diagnostics/	Troubleshooting guides and failure walkthroughs
cli/	Full CLI command reference
install/	Installation, updating, and migration
platforms/	OS-specific guides (macOS, Linux, Windows, etc.)
web/	Web Surfaces: Dashboard, Control UI, TUI, nodes

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 tasks list                # List background/detached task runs
openclaw tasks show <id>           # Show specific task details
openclaw tasks cancel <id>         # Cancel a running task
openclaw tasks audit               # Identify problematic task runs
openclaw agent --message "..."     # Run single agent turn (scripted/testing)
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 in order — do NOT skip steps:

```
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/. For per-channel troubleshooting (failure signatures, setup walkthroughs), see references/diagnostics/. For plugins adding new channels (Matrix, Nostr, MS Teams, etc.), see references/plugins/.

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

# 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-4o"],
      },
    },
  },
}

Multi-Agent Routing

For detailed multi-agent config, see references/concepts/.

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

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/gateway/security.md and references/security/.

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

# 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

Keeping This Skill Up-to-Date

This skill syncs its

references/

from the official OpenClaw repository. To update:

sh scripts/sync-docs.sh

Or trigger the Auto-Sync workflow on GitHub Actions (runs daily at 04:00 UTC).

Tools Reference

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

For specific tools:

references/tools/exec.md — Exec tool deep-dive
references/tools/exec-approvals.md — Exec approvals and allowlists
references/tools/browser.md — Browser automation deep-dive
references/tools/web.md — Web search/fetch with multiple providers
references/tools/plugin.md — Plugin system (install, author, distribute)
references/tools/skills.md — Skills system (load, config, ClawHub)
references/tools/acp-agents.md — ACP agents (Codex, Claude Code, Gemini CLI)
references/tools/firecrawl.md — Firecrawl anti-bot fallback
references/tools/slash-commands.md — Chat slash commands
references/tools/thinking.md — Thinking levels (/think, /verbose)
references/tools/clawhub.md — ClawHub skill registry
references/web/tui.md — Terminal UI (TUI)
references/tools/tts.md — Talk Mode and Voice Wake

Tool profiles:

minimal

coding

messaging

full

(default).

Tool groups (for allow/deny):

Group	Tools Included
`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)`	Placeholder API key in `.env`	Replace with real API key in `~/.openclaw/.env` , restart Gateway
`openclaw flows list` / `ClawFlow` references	ClawFlow is deprecated	Use `openclaw tasks list/show/cancel/audit` instead
`config change requires gateway restart (plugins.*)`	Plugin config can't hot-reload	Full `openclaw gateway restart` or `launchctl kickstart -k`
`Bootstrap failed: 5: Input/output error`	LaunchAgent plist stuck/stale	`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
`OPENCLAW_SKIP_CRON`	Disable cron scheduler (set to `1` )
`OPENCLAW_HIDE_BANNER`	Suppress banner output
`OPENCLAW_SUPPRESS_NOTES`	Suppress informational notes