The OpenClaw cheatsheet. Every command, one page.

Install (macOS / Linux)

curl -fsSL https://openclaw.ai/install.sh | bash

Or try it without installing

npx openclaw@latest

First run

1. 1

   Guided setup

   openclaw onboard
2. 2

   Run the Gateway as a service

   openclaw gateway install
3. 3

   Check it listens on 18789

   openclaw gateway status
4. 4

   Open the Control UI

   openclaw dashboard

Onboard flags

--classic

Full step-by-step wizard

--flow quickstart

Classic wizard with minimal prompts

--flow manual

Full prompts for port, bind and secret storage

--flow import

Migrate from another assistant (e.g. --import-from hermes)

--mode remote --remote-url <wss://…>

Connect to a remote Gateway

--non-interactive --accept-risk

Scripted setup

--install-daemon

Install the Gateway service during setup

--skip-channels

Skip channel setup

• openclaw gateway --port --bind --token

  Run the Gateway in the foreground

• openclaw gateway install --force

  Install the service (launchd, systemd, Scheduled Task)

• openclaw gateway start|stop|restart

  Control the installed service

• openclaw gateway status --require-rpc

  Runtime, connectivity and capability

• openclaw gateway probe

  Is the Gateway reachable, and with what scope?

• openclaw setup --baseline

  Repair or redo setup without the wizard

• openclaw configure

  Change model auth, gateway, channels, plugins or skills

• openclaw doctor --fix --deep --lint

  Health checks, migrations and quick fixes

• openclaw triage

  Sanitized, agent-ready diagnosis and support archive

• openclaw status --all --deep --usage

  Full, shareable report

• openclaw config get|set|unset|patch --dry-run

  Read or write openclaw.json

• openclaw config validate

  Check the config against the schema

• openclaw channels add

  Add a channel account (guided without flags)

• openclaw channels status --probe

  Live per-account channel health

• openclaw models status --probe

  Resolved default, fallbacks and auth

• openclaw agents list --bindings

  Agents and the traffic they own

• openclaw sessions --all-agents --json

  Stored sessions across agents

• openclaw logs --follow

  Tail Gateway logs

• openclaw security audit --deep --fix

  Audit config for foot-guns

• openclaw backup create --dry-run

  Back up config, state and workspace

• openclaw update --channel beta --dry-run

  Update OpenClaw

• openclaw reset --scope config|config+creds+sessions|full

  Reset part or all of the install

Global flags

--dev

Isolate state under ~/.openclaw-dev, Gateway on port 19001

--profile <name>

Isolate state under ~/.openclaw-<name>

--container <name>

Run the CLI inside a Podman or Docker container

--log-level <level>

Override the log level for this run

--no-color

Disable ANSI colors (NO_COLOR=1 also works)

--update

Shorthand for openclaw update

-V, --version, -v

Print the version and exit

• openclaw plugins list|install|enable|disable

  Manage plugins

• openclaw plugins doctor

  Diagnose plugin load failures

• openclaw approvals get|set

  Exec approval policy

• openclaw approvals allowlist add|remove

  Exec allowlist entries

• openclaw sandbox list|recreate|explain

  Inspect or rebuild sandboxes

• openclaw system event --text "X" --mode now

  Queue a system event for the agent

• openclaw system heartbeat last|enable|disable

  Control heartbeat runs

• openclaw update status|wizard|repair

  Update channel, history and recovery

• openclaw nodes list|pending|approve

  Approve and manage remote nodes

• openclaw devices list|approve|rotate|revoke

  Device token lifecycle

• openclaw directory peers list

  Resolve peer IDs before sending

• openclaw secrets audit|reload

  Check and reload SecretRefs

• openclaw gateway usage-cost --days 7 --agent

  Token spend by day

• openclaw health --json --verbose

  Direct Gateway health check

• openclaw tui --url --token

  Terminal UI; chat is tui --local

• openclaw dashboard

  Open the Control UI with the current token

Gotchas

models status --probe

Real requests: spends tokens, can hit rate limits

channels status --deep

Not supported; use --probe, or openclaw status --deep

security audit --fix

Writes changes to your config and permissions

doctor --fix --force

Applies aggressive config and state repairs too

TelegramBot token

channels add --channel telegram --token <bot-token>

WhatsAppQR pairing

channels login --channel whatsapp

DiscordBot token

channels add --channel discord

SlackSocket Mode

channels add --channel slack

Signalsignal-cli

channels add --channel signal

iMessageimsg plugin

plugins install @openclaw/imessage

Google ChatPlugin

channels add --channel googlechat

Matrix, Teams, Feishu, LINE…Plugins

channels add, then pick from the list

Diagnostics

• openclaw channels list --all

  Configured and available channels

• openclaw channels status --probe

  Live connection state per account

• openclaw channels logs --channel all --lines 200

  Channel logs

• openclaw pairing list telegram

  Pending DM pairing requests

• openclaw pairing approve telegram <code>

  Let a sender talk to the agent

Start with Telegram: it needs only a bot token and no plugin install.

AGENTS.md

Operating instructions; its ## Tools section holds local tool notes

SOUL.md

Persona, tone and boundaries

USER.md

Preferences as dated directives (4,000-char budget)

IDENTITY.md

Agent name, vibe and emoji

MEMORY.md

Curated long-term memory (main private session only)

memory/YYYY-MM-DD.md

Daily notes, searched on demand

DREAMS.md

Dream Diary from memory consolidation

BOOT.md

Startup checklist (needs the boot-md hook)

BOOTSTRAP.md

First-run ritual; delete when done

skills/

Workspace skills; highest precedence

Default root: ~/.openclaw/workspace. HEARTBEAT.md is no longer read: doctor --fix moves it into the heartbeat monitor's scratch.

MEMORY.mdbootstrap

Durable facts and decisions, loaded at session start

Daily notesmemory/*.md

Detailed context, indexed for search, not injected

Toolsmemory_search · memory_get

Semantic recall and exact file reads

Embeddingsmemory.search.provider

OpenAI by default; gemini, voyage, ollama, local…

Hybrid searchvectors + BM25

Ranked by relevance, recency and importance

Enginesbuiltin · Honcho

SQLite builtin by default; Honcho via plugin

Dreaming/dreaming

Background sweep that distils daily notes into MEMORY.md

Memory flushcompaction.memoryFlush

Saves context before compaction; on by default

• openclaw memory status --deep --agent

  Index and provider health

• openclaw memory index --force --agent

  Rebuild the index

• openclaw memory search "query"

  Search from the CLI

• openclaw models list --all --refresh

  Every available model

• openclaw models set <model-or-alias>

  Set the default model

• openclaw models set-image <model-or-alias>

  Set the default image model

• openclaw models fallbacks add <model-or-alias>

  Append to the fallback chain

• openclaw models fallbacks list

  Show the fallback chain

• openclaw models auth login --provider <id>

  Sign in to a provider

• openclaw models auth paste-api-key --provider <id>

  Store an API key

• openclaw models auth order set --provider <id> <profiles…>

  Profile rotation order

• openclaw models aliases add <alias> <model>

  Create a model alias

• openclaw models status --probe

  Live-test configured auth profiles

Failover: a rate-limited or failing auth profile goes into cooldown and the next profile, then the next fallback model, takes over for that turn only.

session.dmScope

main (default) | per-peer | per-channel-peer | per-account-channel-peer

session.reset.mode

none (default) | daily | idle

session.reset.atHour

Hour for daily resets (default 4, Gateway local time)

session.reset.idleMinutes

Idle window; with daily, whichever expires first wins

session.resetByType

Overrides for direct, group and thread sessions

session.resetByChannel

Per-channel override

session.identityLinks

Link one person's identities across channels

• openclaw sessions tail --follow

  Stream session activity

• openclaw sessions compact "agent:main:main"

  Compact one session

• openclaw sessions cleanup --dry-run --enforce

  Preview stale-session cleanup

Use per-channel-peer for multi-user inboxes, or one person's DMs leak into another's context.

• /status

  Runtime status, plugin health, provider usage

• /context list

  What fills the context window

• /context detail

  System prompt and injected files

• /model <model> -s

  Switch model for this session (-a agent, -g global)

• /models

  List available providers and models

• /compact [instructions]

  Summarize older context

• /new [model]

  Archive this session and start fresh

• /reset [soft]

  Reset in place; soft keeps the transcript

• /stop

  Abort the current run

• /steer <message>

  Inject guidance into the active run

• /btw <question>

  Side question without touching context

• /think <level>

  Set the thinking level

• /verbose on|off

  Verbose output; keep off in groups

• /tools

  What the agent can use right now

• /usage tokens|full|cost

  Per-reply usage footer

• /goal start|status|complete

  Durable session goal

• /loop [interval] <prompt>

  Repeat a prompt in this chat

• /approve <id> <decision>

  Resolve an approval prompt

• /send on|off|inherit

  Set send policy (owner)

• /config show|set

  Edit openclaw.json (commands.config: true)

• /debug show|set

  Runtime-only overrides (commands.debug: true)

• /restart

  Restart OpenClaw

OpenAIOPENAI_API_KEY

Reliable; also writes auto-summaries

ElevenLabsELEVENLABS_API_KEY

Voice cloning, multilingual

MicrosoftNo key

Edge neural TTS; best-effort, no SLA (was edge)

Local CLINo key

Runs a configured local TTS command

Speak every reply (off by default)

tts: { auto: "always", provider: "elevenlabs" }

/tts status shows the current state; /tts audio <text> sends a one-off voice reply.

• openclaw logs --follow --local-time

  Tail Gateway logs

• openclaw logs --json

  One JSON event per line

• openclaw logs --limit 500

  Cap the number of lines

• openclaw channels logs --channel whatsapp

  Logs for one channel

• openclaw gateway stability

  Recent stability events

• openclaw gateway diagnostics export

  Zip diagnostics for a bug report

OpenTelemetry export

openclaw plugins install clawhub:@openclaw/diagnostics-otel
# then in openclaw.json
diagnostics: { enabled: true, otel: { enabled: true, endpoint: "http://otel-collector:4318" } }

• openclaw browser start --headless

  Start the managed browser

• openclaw browser status

  Is it running, and which profile?

• openclaw browser tabs

  List open tabs

• openclaw browser open <url>

  Open a URL in a new tab

• openclaw browser navigate <url>

  Navigate the current tab

• openclaw browser snapshot

  Accessibility snapshot with element refs

• openclaw browser screenshot --full-page

  Capture the page

• openclaw browser click|type|hover <ref>

  Act on a snapshot ref

• openclaw browser evaluate --fn '<js>'

  Run JavaScript in the page

• openclaw browser pdf

  Export the page as PDF

• openclaw browser profiles

  Managed and existing-session profiles

• openclaw browser doctor --deep

  Diagnose browser setup

• openclaw automations list --all

  Jobs, including heartbeat monitors

• openclaw automations create "0 7 * * *" "<prompt>" --name <name> --agent

  Schedule an agent turn

• openclaw automations show <job-id>

  Job details

• openclaw automations edit <job-id>

  Change schedule, agent or delivery

• openclaw automations enable|disable <job-id>

  Toggle a job

• openclaw automations run <job-id> --wait

  Run a job now

• openclaw automations runs <job-id> --status error

  Run history

• openclaw automations rm <job-id>

  Delete a job

openclaw cron is the same command. Automations need a running Gateway.

Bundled hooks

session-memorycommand:new, command:reset

Save recent conversation to workspace memory

boot-mdgateway:startup

Run BOOT.md when the Gateway starts

bootstrap-extra-filesagent:bootstrap

Add matching files to the bootstrap context

command-loggercommand

Append command events to a JSONL log

compaction-notifiersession:compact:*

Post compaction status notices

• openclaw hooks list --eligible

  Discovered hooks that can run

• openclaw hooks enable <name>

  Enable a hook

• openclaw hooks disable <name>

  Disable a hook

• openclaw hooks info <name>

  Hook details

• openclaw hooks check

  Check eligibility

• openclaw hooks install <path-or-spec>

  Install a hook pack

Events

command:new | reset | stop

The matching slash command runs

session:compact:before | after

Around compaction

agent:bootstrap

Before workspace files are injected

gateway:startup | shutdown

Gateway lifecycle

message:received | sent

Inbound and outbound messages

Precedence

1

<workspace>/skills/

Workspace skills

2

<workspace>/.agents/skills/

Project agent skills

3

~/.agents/skills/

Personal agent skills

4

~/.openclaw/skills/

Managed skills, shared across agents

5

Workshop skills

Drafted with /learn

6

Bundled skills

Shipped with OpenClaw

7

skills.load.extraDirs

Extra directories and plugin skills

Install and manage

• openclaw skills search "calendar"

  Search ClawHub

• openclaw skills install @owner/<slug> --global

  Install into the workspace

• openclaw skills update --all

  Update ClawHub installs

• openclaw skills list --eligible

  Skills the agent can use

• openclaw skills check

  Missing requirements

• clawhub uninstall @owner/<slug>

  Remove a ClawHub skill (npm i -g clawhub)

SKILL.md frontmatter

---
name: my-skill
description: "What this skill does"
metadata: { "openclaw": { "requires": { ... } } }
---

agents.entries.<id>

Per-agent workspace, model, tools and sandbox

Isolated state

Each agent has its own sessions and auth profiles

bindings

Route traffic by channel, account, peer, guild or team

groupChat.mentionPatterns

Names that wake an agent in groups

Routing precedence

1

peer

Exact DM, group or channel id

2

parent peer

Thread inherits its parent

3

peer.id: "*"

Peer wildcard

4

guildId + roles

Discord guild and roles

5

guildId

Discord guild

6

teamId

Slack team

7

accountId

One channel account

8

accountId: "*"

Any account on the channel

9

fallback owner

The sole agent; several agents need a binding

• openclaw agents add work --workspace ~/.openclaw/workspace-work

  Add an agent

• openclaw agents bind --agent work --bind telegram:ops

  Route an account to it

• openclaw agents bindings

  Current routing

• openclaw agents delete <id>

  Remove an agent

heartbeat.every

30m by default, 1h with Anthropic OAuth; 0m disables

heartbeat.target

owner (default DM) | last | none | <channel id>

heartbeat.to

Explicit recipient, with target set to a channel

heartbeat.model

Cheaper model for heartbeat runs

heartbeat.lightContext

Skip workspace bootstrap files

heartbeat.isolatedSession

Fresh session per run, no history

heartbeat.activeHours

Only run inside a time window

Contract: reply NO_REPLY when nothing needs attention. Legacy HEARTBEAT_OK replies are still dropped.

Monitor checklist (replaces HEARTBEAT.md)

openclaw automations scratch <job-id> --set "Check inbox for urgent mail"

sandbox.mode

"off"

No sandbox (default)

"non-main"

Sandbox every session except the main one

"all"

Every session runs sandboxed

sandbox.scope

"agent"

One container per agent (default)

"session"

One container per session

"shared"

One container for all sandboxed sessions

sandbox.workspaceAccess

"none"

Isolated sandbox workspace only (default)

"ro"

Agent workspace read-only at /agent

"rw"

Agent workspace read-write at /workspace

Backends: docker (default), podman, ssh, openshell, crabbox. Default image: openclaw-sandbox:bookworm-slim.

Parallel work

Research and slow tools without blocking the main run

Isolation

Own session; no session or message tools by default

Announce

Results post back to the requester

Auto-archive

After subagents.archiveAfterMinutes (default 60)

subagents.model

Run children on a cheaper model

• /subagents list

  Sub-agent runs in this session

• /subagents log <id|#>

  Recent turns of a run

• /subagents info <id|#>

  Run metadata

• /agents

  Thread-bound agents for this session

sessions_spawn tool

sessions_spawn({ task, label?, agentId?, model?, thinking?,
  runTimeoutSeconds?, mode?: "run" | "session",
  context?: "isolated" | "fork", cleanup?: "delete" | "keep" })

First 60 seconds

openclaw triage
openclaw status --all
openclaw gateway probe
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

No DM reply

openclaw pairing list <channel>, then approve

Silent in a group

Mention gating: check requireMention and mentionPatterns

Auth failing

openclaw models status, then models auth login --provider <id>

Gateway down

openclaw gateway status; doctor --deep finds stray installs

Missing tools

Check tools.profile: minimal, messaging, coding or full

Memory not found

openclaw memory status --deep, then memory index --force

Context full

/compact, or /new for a fresh session

Broke after update

openclaw update status, then update repair

Universal fix

openclaw doctor --fix

~/.openclaw/openclaw.json

Main configuration (JSON5)

~/.openclaw/workspace/

Default agent workspace

~/.openclaw/agents/<id>/agent/openclaw-agent.sqlite

Sessions, transcripts, local auth

~/.openclaw/state/openclaw.sqlite

Shared state and auth profiles

~/.openclaw/credentials/

Channel state, e.g. WhatsApp creds

~/.openclaw/skills/

Managed skills

~/.openclaw/sandboxes/

Sandbox workspaces

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Gateway log (logging.file)

Never commit ~/.openclaw: it holds credentials, sessions and tokens.