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
Current stable: v2026.4.21. Run these after upgrading — especially if you still need v2026.4.5 (legacy config aliases) or v2026.4.2 (x_search / Firecrawl paths) migrations.
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> # Safe plugin replace (since v2026.4.5) openclaw flows list # Task Flow sanity check (v2026.4.2+) openclaw exec-policy show # Exec policy vs approvals (v2026.4.10+)
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 recent OpenClaw releases on GitHub — media tools, task flows, config migrations, and platform changes. Follow the links for curated feature pages and full notes.
Latest stable quality pass: OpenAI image generation defaults move to `gpt-image-2`, doctor can now repair missing bundled plugin runtime dependencies in packaged installs, image provider/model fallback failures are logged clearly, owner-enforced command checks are tightened, Slack runtime sends preserve `threadTs` aliases, browser invalid accessibility refs fail fast, and npm install noise is reduced via `node-domexception` override mirroring.
| Feature | Details |
|---|---|
| OpenAI images default to gpt-image-2 | Bundled image generation defaults and live media smoke tests now target gpt-image-2, with tool/docs metadata advertising newer 2K/4K OpenAI size hints. |
| Doctor plugin runtime dependency repair | Doctor can repair missing bundled plugin runtime dependencies from packaged installs without forcing broad core dependency reinstalls. |
| Image fallback warning visibility | Failed provider/model candidates are now logged at warn level before automatic fallback, so hidden image-generation failures are visible in gateway logs. |
| Owner-command enforcement hardening | Owner-enforced commands now require owner-candidate identity match or internal operator.admin; permissive channel allowFrom fallback no longer bypasses owner-only command gates. |
| Slack threadTs alias preservation | Runtime outbound sends now preserve thread aliases so generic sends stay in the intended Slack thread when callers provide threadTs. |
| Browser accessibility ref fast-fail | Invalid ax<N> accessibility refs are rejected immediately in browser action paths instead of failing only after timeout. |
| npm node-domexception override mirror | Root package.json mirrors the node-domexception alias in overrides, reducing deprecated transitive dependency-chain warnings during npm installs. |
| Feature | Details |
|---|---|
| Onboarding security UX refresh | Setup wizard now uses a clearer warning-banner layout, better scanning structure, and loading feedback during initial model catalog resolution. |
| Tiered model pricing + Kimi defaults | Token-cost reporting now supports tiered pricing; bundled Moonshot setup and media/web-search defaults move to kimi-k2.6 with kimi-k2.5 compatibility. |
| Session maintenance guardrails | Built-in session entry caps and age pruning are enforced by default, including load-time pruning for oversized stores to reduce startup OOM risk. |
Cron state split (jobs-state.json) | Execution/runtime state is separated from job definitions so jobs.json remains clean for review and source control. |
| Owner-command and gateway guardrails | Owner-enforced commands require true owner identity, and model-facing gateway config mutation paths are further restricted for trusted settings. |
| Plugin runtime dependency repair | Bundled plugin runtime deps are repaired per-plugin runtime directory with quieter repeated startups and safer package-manager handling. |
| Channel delivery reliability pass | Fixes include Slack thread alias handling, Telegram polling/reaction tuning, Matrix allowlist reloads, BlueBubbles send/replay stability, and cron announce delivery correctness. |
v2026.4.15 — Broad platform and packaging release: Anthropic defaults move to Claude Opus 4.7, Gemini TTS is added, Model… v2026.4.14 — Quality-focused release with GPT-5 family improvements and broad provider/channel reliability fixes: forward… v2026.4.12 — Broad quality release centered on plugin loading boundaries, memory/dreaming reliability, and local-model er…
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.