Every command, config, file, and trick — on one page. Bookmark this.
Want to support this page and keep it free with the latest tips & tricks?
☕ Buy me a coffee · other ways to support
OpenClaw in 60 seconds
Run these once after upgrading to quickly align config and verify the biggest changes from v2026.4.5 and v2026.4.2.
openclaw doctor --fix # Migrate legacy aliases + x_search/Firecrawl path moves openclaw config validate # Confirm canonical config is valid openclaw plugins install --force <plugin-or-hook> # v2026.4.5 safe replace flow openclaw flows list # v2026.4.2 Task Flow substrate sanity check openclaw memory rem-harness # Optional: verify dreaming/REM pipeline (experimental)
Monitor your OpenClaw gateway in real time: channel health, memory index, skills, model costs, system resources. Connect to your live gateway or try Demo Mode — no setup required. Bookmark it.
📡 Open Status DashboardLooking for specific setup help? Start with these focused pages:
curl -fsSL https://openclaw.ai/install.sh | bashopenclaw onboard --install-daemonopenclaw dashboard → browser → talk to your lobsterHighlights from the latest OpenClaw releases on GitHub — media tools, task flows, config migrations, and platform changes. Follow the links for curated feature pages and full notes.
| Feature | Details |
|---|---|
| Breaking: config aliases | Legacy keys removed — openclaw doctor --fix migrates; cliBackends dropped. |
video_generate / music_generate | Built-in media tools; xAI, Runway, Wan, Lyria, MiniMax, Comfy-backed workflows. |
| Comfy plugin | Local / Comfy Cloud workflows for image, video, and music generation. |
| Providers & Mantle | Qwen, Fireworks, StepFun bundles; Bedrock Mantle + inference profiles + IAM bearer. |
| Control UI | 12+ locales; ClawHub search/install in Skills panel; plugins install --force. |
/dreaming | Experimental memory promotion, Dreams UI, dreams.md, REM tooling. |
| Claude CLI MCP | OpenClaw tools via loopback MCP; stream-json partial streaming; env hardening. |
| Feature | Details |
|---|---|
| Breaking: xAI / Firecrawl | x_search & Firecrawl web_fetch move under plugins.entries.* — doctor --fix. |
| Task Flow substrate | Durable state, managed children, api.runtime.taskFlow, openclaw flows recovery. |
| Android Assistant | App Actions — launch OpenClaw from Google Assistant into the composer. |
before_agent_reply | Plugin hook to short-circuit with a synthetic reply before the model. |
| Feishu comments | Drive comment events, thread context, in-thread replies. |
| Compaction | Consistent agents.defaults.compaction.model; optional notifyUser. |
Matrix m.mentions | Reliable @mentions in Element-class clients. |
v2026.4.1 — /tasks, SearXNG, Bedrock Guardrails, cron --tools, agents.defaults.params. v2026.3.31 — flows, unified ledger, QQ Bot, Matrix/MCP. v2026.3.28 — config schema, Qwen migration, plugin approvals.
openclaw doctor --fixagents.defaults.cliBackends removedx_search → plugins.entries.xai.config.xSearch.*; Firecrawl → plugins.entries.firecrawl.config.webFetch.* — detailsnodes.run removed — use exec host=node; install fail-closed; trusted-proxy / node-command rulesopenclaw doctor --fixsudo npm i -g openclaw@latest openclaw update status openclaw update --dry-run # Preview first openclaw update wizard openclaw gateway restart
If you are searching for how to install OpenClaw quickly, this is the fastest path from zero to a working personal AI assistant. The commands below cover both one-line install and source install, then move you directly to onboarding, health checks, and first-run verification.
# macOS / Linux curl -fsSL https://openclaw.ai/install.sh | bash # Windows (PowerShell) iwr -useb https://openclaw.ai/install.ps1 | iex # npm global npm i -g openclaw # Onboard wizard openclaw onboard --install-daemon
git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install && pnpm ui:build && pnpm build pnpm openclaw onboard --install-daemon # Dev loop (auto-reload) pnpm gateway:watch
node --version)export NODE_OPTIONS="--max-old-space-size=4096"Step-by-step walkthrough for macOS — Homebrew, Node.js, install, wizard, daemon, troubleshooting. Apple Silicon & Intel.
📖 Open Mac Guideopenclaw --version # Version (includes git hash) openclaw doctor # Health check openclaw doctor --deep --yes # Deep + auto-fix openclaw test model # Test AI openclaw dashboard # Web UI openclaw message send --target +1555... --message "Hi" # Test channel
OpenClaw behavior is mostly defined by workspace files, not by hidden prompts. Getting SOUL.md, AGENTS.md, USER.md, and TOOLS.md right gives you better results than model switching alone. Use this as your practical reference for what each file does and when it is loaded.
All in ~/.openclaw/workspace/ — agent reads at session start.
| File | Purpose | Loaded |
|---|---|---|
| AGENTS.md | Operating instructions, priorities, workflow rules | Every session |
| SOUL.md | Personality, tone, values, behavioral constraints | Every session |
| USER.md | About you — name, preferences, style | Every session |
| IDENTITY.md | Agent name, role, goals, voice | Every session |
| TOOLS.md | Local tool notes, calendar IDs, conventions | Every session |
| HEARTBEAT.md | Checklist for periodic heartbeat runs | Heartbeat only |
| BOOT.md | Startup ritual on gateway restart | Boot hook |
| BOOTSTRAP.md | First-run interview — auto-deleted after | First run |
| MEMORY.md | Long-term curated memory (optional) | Main DM only |
| dreams.md | Dreaming trail / diary when experimental dreaming is on (v2026.4.5+) | Optional; inspectable |
| memory/YYYY-MM-DD.md | Daily logs — today + yesterday loaded | Session start |
Don't know what to write? The Workspace Wizard asks 8 questions and generates all your workspace files — SOUL.md, AGENTS.md, USER.md, IDENTITY.md, TOOLS.md, HEARTBEAT.md — ready to download.
✨ Open Workspace WizardJust installed? This hour-by-hour guide walks you through SOUL.md, USER.md, first channel, cron jobs, heartbeat, security & model failover.
⏰ Open First 24h GuideComplete workflows you can copy-paste: Developer Workflow (PR reviews, CI monitoring, dependency audits) and Personal Assistant (morning briefings, email triage, meal planning). Full configs, cron jobs & SOUL.md included.
📋 Browse Playbookscd ~/.openclaw/workspace git init && git add AGENTS.md SOUL.md TOOLS.md \ IDENTITY.md USER.md HEARTBEAT.md memory/ git commit -m "Add workspace"
Never commit: API keys, OAuth tokens, config.
Most setup issues come from configuration mismatches: model choice, channel auth, heartbeat behavior, and security defaults. This section gives you copy-paste-safe openclaw.json patterns for stable day-one setup, plus fallback and reliability settings for long-running assistants.
// ~/.openclaw/openclaw.json — JSON5 { identity: { name: "Clawd", emoji: "🦞", theme: "helpful lobster" }, agent: { workspace: "~/.openclaw/workspace", model: { primary: "anthropic/claude-sonnet-4-6" }, heartbeat: { every: "30m", target: "last" }, }, channels: { telegram: { enabled: true, botToken: "123456:ABC..." } } }
openclaw config file # Print active config path openclaw config get <key> # Values redacted in output openclaw config set <key> <val> openclaw config unset <key> openclaw config validate # Check JSON/schema before restart openclaw config schema # Print generated schema (v2026.3.28+) openclaw gateway restart # Required after changes
agent: { model: { primary: "anthropic/claude-sonnet-4-6", fallbacks: ["anthropic/claude-opus-4-6", "mistral/mistral-large"], params: { context1m: true } // 1M context beta }}
Auto-rotates auth on rate limits. Per-agent params overrides supported.
When both gateway.auth.token and gateway.auth.password are set (including SecretRefs), you must set gateway.auth.mode to token or password. Required before upgrade.
gateway: { auth: { mode: "token", // or "password" token: "..." } }
Don't want to edit JSON manually? The Config Builder lets you pick models, channels, heartbeat, security — and generates a valid openclaw.json with live preview.
The OpenClaw CLI is your primary interface for managing the gateway, channels, agents, and plugins. Every command below works in both interactive and scripted contexts, so you can use them in cron jobs, shell aliases, or CI pipelines. Memorize doctor, logs --follow, and gateway restart — they solve most day-to-day issues.
openclaw gateway status|start|stop|restart openclaw dashboard # Web UI openclaw tui # Terminal UI
openclaw channels list openclaw channels status --probe openclaw channels login # WhatsApp QR openclaw channels add --channel telegram --token $TOK openclaw channels logs --channel telegram openclaw channels remove --channel discord --delete
openclaw agents list --bindings openclaw agents add|delete <name> openclaw agents bindings|bind|unbind openclaw agents set-identity --from-identity
openclaw logs --follow openclaw logs --json --limit 200 openclaw status --all --deep # Full diagnosis openclaw status --usage # Provider usage/quota openclaw doctor --deep --yes openclaw health --json --verbose
openclaw plugins list|info|enable|disable|install|doctor openclaw plugins install --force … # v2026.4.5+: replace existing without dangerous override openclaw plugins install clawhub:<pkg> # ClawHub-first installs openclaw skills list|info|check # v2026.3.22+: search|install|update clawhub install|uninstall <slug> clawhub update --all
openclaw sessions cleanup # Disk budget cleanup openclaw memory search --query "text" openclaw memory rem-harness # v2026.4.5: REM preview (experimental dreaming) openclaw memory promote-explain # v2026.4.5: explain promotion openclaw cron list|add|edit|rm|enable|disable|run # v2026.4.1: --tools on add|edit openclaw flows list|show|cancel # Task flows (substrate v2026.4.2+) openclaw config schema # JSON Schema dump (v2026.3.28+) openclaw --container my-openclaw status --all --deep # CLI in container (v2026.3.24) openclaw update --dry-run # Preview update openclaw update --channel stable|beta|dev openclaw update --tag main # From GitHub main (v2026.3.22+)
openclaw backup create # Local state archive openclaw backup create --only-config # Config only openclaw backup create --no-include-workspace openclaw backup verify <path> # Validate manifest
Slash commands are processed by the gateway before the AI sees them, making them instant and deterministic. Use them to reset sessions, control thinking levels, check token usage, or abort a runaway action. They work identically across Telegram, WhatsApp, Discord, and webchat.
Processed by Gateway — never reaches the AI.
| Command | What it does |
|---|---|
| /status | Model, context, queue, runtime; adds provider usage when available |
| /tasks | Session background task board (v2026.4.1) |
| /dreaming | Memory dreaming status/help — experimental (v2026.4.5); see changelog |
| /help, /commands | Common commands grouped |
| /new [model] | Fresh session (alias: /reset) |
| /compact [instr] | Summarize context, free tokens |
| /stop | Abort run + clear queue |
| /think [level] | off, minimal, low, medium, high, xhigh, adaptive |
| /model [id] | Switch model; /model list, /model status |
| /usage off|tokens|full|cost | Per-response footer; cost = local summary |
| /fast | Toggle fast mode (Anthropic/OpenAI) — v2026.3.12 |
| /tts on|off|always|inbound | Toggle text-to-speech |
| /send on|off|inherit | Override delivery (owner-only) |
| /reasoning on|off|stream | Separate reasoning message |
| /elevated on|off|ask|full | Exec approval level |
| /whoami | Sender identity (alias: /id) |
| /context [list|detail|json] | Token usage per-file |
| /subagents spawn|list|kill|steer | Spawn or control sub-agents |
| /export-session [path] | Export session to HTML with full prompt |
| /approve allow-once|deny | Resolve exec approval prompts |
| /check-updates | Quick update summary |
:think high # Thinking level :model opus # Model override :fast # Fast mode (Anthropic/OpenAI) v2026.3.12 :send off # Suppress delivery :verbose # Verbose mode :reasoning on # Separate reasoning :elevated ask # Exec approval
Natural language abort: “stop openclaw”, “stop action”, “please stop”, “STOP!”, “do not do that”. Works in ES/FR/ZH/HI/AR/JP/DE/PT/RU too.
Channel setup is where most users decide whether OpenClaw feels magical or frustrating. Telegram is the easiest stable path, while WhatsApp and Discord offer different tradeoffs around reliability, voice, and group workflows. Use the config blocks below as baseline templates before customizing policy and routing.
{ channels: { telegram: {
enabled: true,
botToken: "123456:ABC-DEF..."
}}}Most stable — survives reboots. DM voice transcription supported.
{ channels: { whatsapp: {
enabled: true,
allowFrom: ["+1555..."],
groupPolicy: "allowlist"
}}}QR scan needed. Breaks on reboot.
{ channels: { discord: {
enabled: true,
token: "BOT_TOKEN",
allowFrom: ["USER_ID"],
autoArchiveDuration: 4320 // 1h=60, 1d=1440, 3d=4320, 1w=10080
}}}Voice joins recover from DAVE failures. autoArchiveDuration for thread archiving (v2026.3.11).
| Channel | Notes |
|---|---|
| Telegram | Most stable. Bot API. DM voice. |
| QR scan. Breaks on reboot. | |
| Discord | Voice + text. DAVE recovery. |
| Google Chat | Native support. |
| Slack | Bot + App Token + Signing Secret. |
| iMessage | macOS only, Shortcuts bridge. |
| Signal | Requires signal-cli. |
| MS Teams | Extension channel. |
| Synology Chat | Native plugin. Webhook ingress. NEW |
| WebChat | Built-in at localhost:18789 |
| Matrix | Extension. BlueBubbles, Zalo also. |
Side-by-side comparison of every channel, setup configs for Telegram, WhatsApp, Discord, iMessage, Slack & Signal, plus multi-channel and troubleshooting tips.
📱 Open Channels GuideOpenClaw remembers what matters through a layered memory system: daily logs capture conversation history, MEMORY.md holds curated long-term facts, and vector search lets the agent recall context from weeks ago. Optional dreaming (v2026.4.5+) can promote short-term notes into durable recall in the background; when enabled, a top-level dreams.md holds the operator-visible trail while /dreaming and the Dreams UI surface status. Understanding flush, compaction, and indexing helps you stay sharp without bloating token usage.
memory/YYYY-MM-DD.md — today + yesterdayMEMORY.md — curated, DM onlyopenclaw memory index --all openclaw memory search --query "text" openclaw memory rem-harness # REM preview (experimental dreaming, v2026.4.5+) openclaw memory promote-explain # Explain promotion decisions openclaw sessions cleanup # Disk budget
Dreaming runs weighted promotion from recent daily notes into longer-lived memory (light / deep / REM-style phases). Promotion trace and diary-style output are written to dreams.md at the workspace root so you can inspect what ran without pulling that file into default recall unless you ask.
/dreaming — status and help for the featurerecencyHalfLifeDays / maxAgeDays where supportedSkills extend what your assistant can do — from web searches and calendar integration to custom automation scripts. Bundled skills ship with OpenClaw and require zero setup, while community skills on ClawHub let you install with one command. You can also build your own SKILL.md files for private tools and workflows.
--- name: my-skill description: "What it does" metadata: { "openclaw": { "requires": { "bins": ["uv"], "env": ["API_KEY"] }}} ---
| Key | Default | Effect |
|---|---|---|
| user-invocable | true | /slash command |
| disable-model-invocation | false | Exclude from prompt |
| command-dispatch | — | “tool” = bypass model |
| os | all | darwin, linux, win32 |
workspace/skills/~/.openclaw/skills/Explore 40+ curated skills by category, copy install commands, and generate custom SKILL.md files with the interactive builder.
🧩 Open Skill ExplorerThe heartbeat is your assistant's proactive loop — it runs on a schedule, reads HEARTBEAT.md, and only notifies you when something needs attention. Use it for server health checks, inbox monitoring, weather alerts, or any recurring task that should run silently until it matters.
every: "0m" → disabledheartbeat: { every: "30m", target: "last", model: "cheap-model", activeHours: { start: "08:00", end: "22:00", timezone: "Europe/Bucharest" } }
Cron jobs let your assistant run scheduled tasks independently — morning briefings, weekly reports, CI checks, or data scraping. Jobs are defined in cron/jobs.json with standard cron expressions and can target isolated sessions so they never interfere with your active conversations.
{ "name": "Morning Brief",
"schedule": { "kind": "cron", "expr": "0 8 * * *" },
"sessionTarget": "isolated",
"payload": { "kind": "agentTurn",
"message": "Deliver my briefing." }
}0 7 * * * — Morning briefing0 18 * * 1-5 — Weekday recap0 10 * * 1 — Weekly intel0 8 1 * * — Monthly reminderCron persists delivered state for failure visibility. v2026.3.11: Isolated cron jobs no longer notify via ad hoc agent sends — run openclaw doctor --fix to migrate legacy config.
Model selection drives quality, speed, and cost. Use a high-quality model for deep reasoning and a cheaper model for heartbeat or routine automation. The matrix below is designed to help you pick provider formats, auth patterns, and fallback strategy without burning budget.
| Provider | Format | Auth |
|---|---|---|
| Anthropic | anthropic/claude-* | API / OAuth |
| OpenAI | openai/gpt-* | API / OAuth |
| Mistral NEW | mistral/* | API key |
| google/gemini-*, gemini-3.1-flash-lite | API key | |
| OpenRouter | openrouter/* | Single key |
| Kilo Gateway NEW | kilocode/* | Auth + onboarding |
| Vercel AI GW | vercel-ai-gateway/* | Normalized refs |
| Amazon Bedrock | amazon-bedrock/* | AWS SDK |
| Ollama | ollama/* | Local |
| LM Studio | Custom baseUrl | Local |
| Moonshot NEW | kimi provider | API key |
| Doubao/BytePlus NEW | volcengine provider | volcengine-api-key |
models: { providers: { "ollama": { baseUrl: "http://127.0.0.1:11434/v1", apiKey: "ollama", api: "openai-responses" }}}
cacheRetention per-agent for prompt cachingadaptive; other reasoning models default to lowInteractive calculator with all providers, heartbeat costs, optimizations, and savings tips. Know exactly what you'll spend.
💰 Open Cost CalculatorOpenClaw can read files, run commands, and connect to external services, so security defaults matter from day one. Start with DM pairing, allowlists, and sandboxing, then add skill vetting and regular audits. Treat every inbound message and community skill as untrusted input until proven safe.
openclaw doctor --fix openclaw security audit --deep chmod 700 ~/.openclaw chmod 600 ~/.openclaw/openclaw.json chmod 700 ~/.openclaw/credentials
security: { dmPolicy: "pairing", groupPolicy: "allowlist", sandboxEnabled: true, trust_model: { multi_user_heuristic: true // NEW } }
trusted-network by defaultcurl|bash, base64, Gatekeeper bypasspip install cisco-ai-skill-scanner/config and /debug now require sender ownership. Authorized non-owner senders can no longer reach these surfaces.
Deep dive: DM policies, pairing flow, sandboxing, exec controls, credential hygiene, network hardening, skill vetting, incident response & a 20-point checklist.
🔐 Open Security GuideMost OpenClaw issues fall into a few categories: port conflicts, stale sessions, channel disconnects, or configuration mismatches. The openclaw doctor --deep --yes command resolves the majority automatically. This section covers the rest — common problems, their fixes, and the update commands to keep your installation current.
Looking for a specific error? → Browse all 20 error fixes
openclaw doctor --deep --yes
Solves 80% of issues. Now checks memory embedding readiness too.
| Problem | Fix |
|---|---|
| Port conflict | lsof -i :18789 |
| Context full | /compact or /new |
| Channel down | openclaw channels status --probe |
| No response | openclaw logs --follow |
| WhatsApp drops | Re-scan QR. Use Telegram. |
| Stale lock | Auto-detected via port reachability now |
| Config invalid / startup fails | openclaw config validate for JSON/schema errors |
| Auth/pairing fails after upgrade | Set gateway.auth.mode to token or password (v2026.3.7+). Cron notify broken? Run openclaw doctor --fix (v2026.3.11). Workspace plugins not loading? v2026.3.12 disabled auto-load — explicit trust required. |
| Restart loop | Fixed in v2026.2.22+. Update. |
| Disk full sessions | openclaw sessions cleanup |
sudo npm i -g openclaw@latest openclaw update --dry-run openclaw update wizard openclaw update --channel beta
OpenClaw uses specific terminology throughout its docs and config. If a term in another section is unclear, check here first. These definitions are kept short and practical — they map directly to concepts you will encounter during setup and daily use.
Knowing where OpenClaw stores its files is essential for backups, debugging, and manual edits. The workspace lives in ~/.openclaw/workspace/, config in ~/.openclaw/openclaw.json, and credentials in a permissions-locked directory. Gateway logs rotate daily under /tmp/openclaw/.
~/.openclaw/ ├── openclaw.json ← Main config (JSON5) ├── credentials/ ← OAuth/API keys (chmod 600) ├── workspace/ ← Agent's home │ ├── AGENTS.md SOUL.md USER.md IDENTITY.md │ ├── TOOLS.md HEARTBEAT.md MEMORY.md dreams.md │ ├── memory/ ← Daily logs │ └── skills/ ← Workspace skills ├── agents/<id>/sessions/ ← Chat history ├── skills/ ← Managed skills ├── memory/<id>.sqlite ← Vector index ├── cron/jobs.json ← Scheduled tasks └── sandboxes/ ← Sandbox workspaces /tmp/openclaw/openclaw-YYYY-MM-DD.log ← Gateway log
Voice and text-to-speech turn OpenClaw into a hands-free assistant. Choose from premium providers like ElevenLabs, fast options like OpenAI TTS, or free alternatives like Edge TTS. Voice input works natively in Telegram and Discord, and the browser canvas supports real-time interaction with snapshot and action controls.
| Provider | Quality | Cost |
|---|---|---|
| ElevenLabs | Ultra-realistic | Premium |
| OpenAI TTS | Fast, high-quality | Standard |
| Edge TTS | Multi-language | Free |
| Mistral Voice | New provider NEW | Standard |
Talk config is now provider-agnostic. iOS TTS prefetches segments for smooth playback. macOS voice wake defaults to webchat channel.
openclaw browser fill --fields '[...]' openclaw sandbox list|recreate
Canvas: A2UI push/reset/eval/snapshot. Browser: dedicated Chrome profiles, snapshots, actions, uploads.