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.14. 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.
Quality-focused release with GPT-5 family improvements and broad provider/channel reliability fixes: forward-compat for `gpt-5.4-pro`, Telegram forum topic names persisted into context/metadata, Codex catalog `apiKey` visibility fix, media tool model normalization for image/PDF, stricter Slack interaction allowlist checks, gateway-tool guardrails blocking newly-enabled dangerous config flags, improved Ollama usage accounting and timeout wiring, browser/CDP SSRF policy fixes, and many memory/dreaming, queueing, keepalive, and channel stability repairs.
| Feature | Details |
|---|---|
| GPT-5.4-pro compatibility | Adds forward-compat support for gpt-5.4-pro in provider routing plus Codex pricing/limits and model visibility while upstream catalogs catch up. |
| Telegram forum topic names | Learns human-readable topic names from Telegram forum service messages and surfaces them in agent context, prompt metadata, plugin hooks, and persisted sidecar state across restarts. |
| Gateway-tool dangerous patch guardrails | Model-facing gateway tool now rejects config.patch and config.apply when a patch would newly enable any openclaw security audit danger flag, while preserving direct authenticated operator RPC behavior. |
| Slack interaction allowlist hardening | Applies global allowFrom owner allowlists to block-action and modal events, requires sender cross-verification, and rejects ambiguous channel types to prevent allowlist bypasses. |
| Ollama timeout & usage accuracy | Forwards embedded-run timeout into stream timeout tuning for slow local models and sends stream_options.include_usage for OpenAI-compatible Ollama streaming to avoid bogus token accounting. |
| Browser SSRF/CDP reliability fixes | Restores hostname navigation under default browser SSRF policy, preserves strict mode for legacy strict configs, and keeps local loopback CDP readiness requests reachable. |
| Memory/Dreaming reliability pass | Fixes managed heartbeat dedupe, promotion confidence/staging, dreaming self-ingestion loops, transient narrative cleanup, and active-memory recall channel resolution. |
| Feature | Details |
|---|---|
| Plugin loading boundaries | CLI, provider, and channel activation now follows manifest-declared needs so startup and runtime avoid loading unrelated plugin runtime, preserving explicit scope/trust boundaries. |
| Bundled LM Studio provider | Adds LM Studio as a bundled provider with onboarding, runtime model discovery, stream preload support, and OpenAI-compatible memory-search embedding routing for local/self-hosted models. |
| Active Memory plugin | Optional memory sub-agent before the main reply with configurable context modes, /verbose inspection, and transcript persistence options for deeper tuning and debugging. |
| Gateway startup and command UX | Defers scheduled services until sidecars finish, gates history/model listing during startup resume, and loads live slash-command catalog into chat composer and command palette. |
| Dreaming reliability pass | Fixes managed-heartbeat dedupe, promotion thresholds, timezone clarity in diary entries, transient narrative cleanup, and self-ingestion loops in dreaming pipelines. |
| Keepalive and queueing stability | Stops droppable keepalive tick disconnects under backpressure and preserves orphaned active-turn user text so follow-up messages are not silently lost. |
| Channel delivery fixes | Includes WhatsApp media/reaction routing fixes, Telegram approval-lane deadlock prevention, Matrix mention compatibility, and Discord heartbeat reconnect stability. |
v2026.4.11 — Dreaming and memory-wiki: ChatGPT import ingestion with Imported Insights and Memory Palace diary subtabs; C… v2026.4.10 — Bundled Codex provider with plugin-owned app-server harness for `codex/gpt-*` models; optional Active Memory… v2026.4.9 — Dreaming: grounded REM backfill with `rem-harness --path`, diary timeline, and promotion integration; Contro…
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.