OpenClaw cheat sheet
The stuff you actually need. Updated 2026-03-23.
🚀 Get productive in 30 seconds
- 1. Install OpenClaw, then run: openclaw onboard --install-daemon
- 2. Check the gateway is alive: openclaw gateway status
- 3. Open the fastest first chat surface: openclaw dashboard
- 4. If you want chat apps next, add Telegram or Discord first (fastest bot-token flows), then pair your own DM
- 5. Run openclaw doctor after setup or upgrades to catch config drift, bad auth, and stale service state
// daily_workflows
The things you'll actually do every day.
Fastest first chat without any messaging app
setupdashboardsanity-checkSkip channel setup entirely. Use the local Control UI in your browser to confirm the gateway, model auth, and workspace all work before touching Telegram/Discord/Signal.
openclaw dashboard Set up a new agent
setupagentsisolationCreate an isolated brain with its own workspace, sessions, persona files, and auth profiles. Best pattern when you want separate assistants for coding, ops, research, or family use.
openclaw agents add <name> Check whether everything is healthy
opsdebugginghealthUse this before debugging. It catches broken services, invalid config, risky DM policies, orphan session files, cron schema drift, and missing memory-search prerequisites.
openclaw doctor See live runtime and channel health
opsstatuschannelsShows whether the gateway is reachable, whether channels are connected, and recent session/link health. Add --deep when you suspect a channel auth or connectivity issue.
openclaw status --deep Add Telegram fast
telegramchannelssetupTelegram is usually the easiest real chat channel: create a bot in BotFather, add the token, start the gateway, then approve your first DM pairing code.
openclaw channels add --channel telegram --token $TELEGRAM_BOT_TOKEN Add Discord for workspace-style use
discordchannelsworkspaceBest when you want multiple persistent topic channels. Create a bot, enable Message Content Intent, add it to your server, then allowlist the guild/channels you want.
openclaw channels add --channel discord --token $DISCORD_BOT_TOKEN Connect Signal privately
signalchannelsprivacyUse a separate Signal number or linked Signal device via signal-cli. Signal is great for private DM access but has more setup friction than Telegram/Discord.
openclaw pairing approve signal <CODE> Inspect which skills are actually ready
skillsdebuggingreadinessDon't guess. This shows which skills are available and which are blocked by missing binaries, env vars, or dependencies.
openclaw skills check Search long-term memory
memorysearchrecallUseful when the assistant has accumulated notes over time. Memory lives in Markdown files in the workspace, not hidden magic.
openclaw memory search "<query>" Schedule a real recurring job
automationcronreportsUse cron for exact-time reminders, reports, and isolated background jobs. Prefer isolated cron for noisy or model-specific tasks.
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "Summarize overnight updates" --announce ⚡ power_moves
Stuff most people don't know about.
Agent army by channel/account binding
Run multiple isolated agents behind one gateway, then route inbound messages by channel, account, guild, group, topic, or even specific sender. This is the core pattern for a personal fleet: one coding agent, one alerts agent, one family agent, one social agent.
openclaw agents add coding && openclaw agents add alerts && openclaw agents list --bindings You get separate workspaces, memory, auth, and sessions without running multiple gateways. It scales cleanly and prevents context bleed.
Use dashboard first, channels second
Bring the gateway up and confirm the local browser UI works before spending time on bot tokens, QR pairing, or Signal setup. If the dashboard works, your core install is fine.
openclaw gateway status && openclaw dashboard This removes 80% of setup ambiguity. You separate gateway/model problems from channel problems immediately.
Secure multi-user inboxes with per-sender DM isolation
Set session.dmScope to per-channel-peer (or per-account-channel-peer in multi-account setups) so different people don't silently share the same DM session history.
openclaw config set session.dmScope "per-channel-peer" This is one of the highest-value safety settings. Shared main-session DMs are convenient for one owner, but risky for shared inboxes.
Heartbeat for awareness, cron for precision
Put recurring awareness checks into heartbeat, and exact-time tasks into cron. Example: inbox/calendar monitoring in heartbeat; daily 7am briefing and one-shot reminders in cron.
openclaw cron add --name "Reminder" --at "20m" --session main --system-event "Reminder text" --wake now This keeps token use low while still giving you reliable scheduled actions. Heartbeat batches; cron pinpoints.
Thread-bind subagents in Discord/Telegram
Use /focus, /agents, /subagents, and ACP thread binding so a discussion thread becomes a dedicated workstream tied to one subagent or harness session.
/focus <target> This turns chat threads into durable task lanes instead of one noisy shared conversation.
Direct config surgery instead of manual JSON editing
Use config get/set/unset/validate for repeatable, scriptable changes. It's much safer than hand-editing a big JSON5 file, especially remotely.
openclaw config validate && openclaw config set channels.telegram.linkPreview false You get validation, automation, and less typo-driven downtime.
Treat doctor as the safe update command
After updates or weird behavior, run doctor before chasing ghosts. It repairs service/config mismatches and warns about insecure or outdated patterns.
openclaw update && openclaw doctor Most production pain is boring drift: env overrides, stale services, missing deps, migrated config keys. Doctor is designed for exactly that.
Install and manage ClawHub skills from CLI
OpenClaw now has native ClawHub integration: search, install, and update skills directly without going to the website.
openclaw skills search <query> && openclaw skills install <name> && openclaw skills list Replaces manual download + copy. Tracked installs means 'openclaw skills update' keeps everything current.
Attach browser tools to your real signed-in browser
Set userDataDir to point at your actual Chrome/Brave/Edge profile. Lets browser tools act in your real logged-in sessions instead of a fresh sandbox.
openclaw config set browser.profiles.user.userDataDir "~/Library/Application Support/Google/Chrome" Game-changer for automating web apps that require real auth. No more re-logging in a sandboxed session.
Use /btw for quick side questions without polluting session context
Ask a meta question about the session, cron schedule, skill behavior, or anything else without that Q&A becoming part of future conversation context.
/btw how is my heartbeat.md being used right now? Keeps your session context tight. Side Q&A shouldn't inflate the prompt on every future message.
Security audit your config before going live
Run the security audit with --fix to tighten defaults automatically before opening a new channel to users.
openclaw security audit --deep --fix Catches DM policy misconfigs, open allowlists, insecure tool profiles, and state permission issues before users hit them.
🔥 common_gotchas
Save yourself 30 minutes of debugging.
You set up a channel but messages still do nothing.
Check openclaw gateway status, then openclaw channels status --probe, then openclaw logs --follow. Most failures are gateway not running, missing token, or policy blocking the sender.
Different DM senders are sharing the same conversation context.
Set session.dmScope to per-channel-peer (or per-account-channel-peer). Local onboarding now prefers this, but older installs may still be on shared main-session DM scope.
Telegram bot works in DM but seems blind in groups.
Disable Telegram privacy mode or make the bot a group admin, then re-add it to the group. Also verify channels.telegram.groups and requireMention/groupPolicy settings.
Discord bot is online but never sees guild messages.
Enable Message Content Intent, invite the bot with the right scopes, allowlist the guild/channel, and confirm requireMention/groupPolicy are what you expect.
Signal setup is much harder than Telegram/Discord.
That's normal. Signal depends on signal-cli and a linked or registered account. Use a separate bot number if you want a clean bot identity and to avoid loop protection issues.
Cron jobs never fire.
Cron runs inside the gateway, so the gateway must stay running. Check cron.enabled, verify the schedule timezone, and inspect openclaw cron list / openclaw cron runs --id <jobId>.
Memory search is empty or weak even though notes exist.
Remember memory is workspace Markdown plus an index. Run openclaw memory status, reindex with openclaw memory index, and ensure an embeddings provider is configured for memory search.
A skill shows up in list but doesn't actually work.
Run openclaw skills check or openclaw skills info <name>. A skill can exist but be ineligible because required binaries, env vars, or platform deps are missing.
Changing config file manually caused strange runtime/auth mismatches.
Use openclaw config validate and openclaw doctor. Also check for env overrides like OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, or macOS launchctl OPENCLAW_GATEWAY_TOKEN/PASSWORD values shadowing your file.
You expected one workspace but actually launched a different profile/state dir.
Be explicit with --profile and know that OPENCLAW_STATE_DIR / OPENCLAW_CONFIG_PATH fully change where state lives. Mixed profiles are a common source of 'missing sessions' and 'wrong token' confusion.
Plugins install from npm when you wanted ClawHub (or vice versa).
As of latest: bare 'openclaw plugins install <pkg>' prefers ClawHub first, falls back to npm. Use 'openclaw plugins install clawhub:<pkg>' to be explicit. Use 'openclaw plugins marketplace list clawhub' to browse first.
Browser automation can't attach to your real logged-in Chrome/Brave session.
Set browser.profiles.<name>.userDataDir to the browser's actual user data directory. OpenClaw now supports Chrome DevTools attach mode so it can use your existing profile instead of starting a fresh one.
Directives like /think or /fast do nothing for some users in a group.
Directives only work for authorized senders. Set commands.allowFrom or ensure the sender is in the channel allowlist. Unauthorized senders see directives as plain text silently — this is intentional.
Inline command shortcuts (/status, /whoami) are not working mid-message.
Inline shortcuts only work for allowlisted/authorized senders. They strip the command and continue processing the rest of the message. Unauthorized users get them treated as plain text.
📋 cli_flags
----install-daemon Install and start the managed gateway service during onboarding.
Best default for an always-on assistant.
openclaw onboard --install-daemon
----flow Choose onboarding depth: quickstart for sensible defaults, advanced/manual for full control.
Get productive fast or force the wizard to expose every option.
openclaw onboard --flow quickstart
----mode Select local or remote onboarding mode.
Attach a laptop/client to a gateway that already runs elsewhere.
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
----non-interactive Run setup commands without prompts. Useful for scripts, CI, or reproducible bootstrap flows.
Automated installs and infrastructure provisioning.
openclaw onboard --non-interactive --auth-choice openai-api-key --install-daemon
----channel Target a specific chat channel in channel-management commands.
Add or manage Telegram, Discord, Signal, Slack, etc.
openclaw channels add --channel telegram --token $TELEGRAM_BOT_TOKEN
----account Name a specific account instance for a channel that supports multiple accounts.
Run multiple bots/numbers/accounts behind one gateway.
openclaw channels add --channel discord --account work --token $DISCORD_BOT_TOKEN
----bind Bind a new agent to a channel or account during agent creation.
Create an agent and route traffic to it in one step.
openclaw agents add coding --workspace ~/.openclaw/workspace-coding --bind discord:coding --non-interactive
----deep Do extra health/probe work instead of a lightweight status check.
Troubleshoot channels, services, and runtime state more aggressively.
openclaw status --deep
----json Emit machine-readable output instead of terminal formatting.
Scripts, dashboards, and external automation.
openclaw channels list --json
----profile Use an isolated OpenClaw profile with its own state directory.
Separate personal/work/test environments without collisions.
openclaw --profile work gateway status
----dev Use dev-isolated state and shifted default ports.
Safely test config and channels without touching your real setup.
openclaw --dev gateway run
----at Create a one-shot cron job at a specific timestamp or relative time.
Precise reminders.
openclaw cron add --name "Reminder" --at "20m" --session main --system-event "Check in" --wake now
----cron Create a recurring cron schedule using cron expression syntax.
Daily/weekly automation and reporting.
openclaw cron add --name "Daily brief" --cron "0 7 * * *" --session isolated --message "Morning briefing" --announce
----session Choose whether a cron job runs in the main session or an isolated cron session.
Control whether scheduled work shares context or runs clean-room.
openclaw cron add --name "Review" --cron "0 9 * * 1" --session isolated --message "Weekly review"
----announce Have an isolated cron run deliver its result to a chat target instead of staying internal.
Push scheduled reports directly to yourself.
openclaw cron add --name "Status" --cron "0 7 * * *" --session isolated --message "Summarize today" --announce --channel telegram --to 123456789
----tag main Install from the main git branch instead of latest npm release.
Get unreleased features or bug fixes before they hit npm.
openclaw update --tag main
----allow-exec Permit exec-based secret providers during secrets audit/configure/apply flows.
Required when your secrets are backed by exec providers (e.g., 1Password CLI, custom scripts).
openclaw secrets audit --allow-exec
----dry-run Preview what secrets apply would do without writing anything.
Safe way to verify a secrets migration plan before committing it.
openclaw secrets apply --from plan.json --dry-run
----fix Automatically apply safe security fixes: tighten defaults, fix state/config permissions.
Use after setup or before adding users to a new channel.
openclaw security audit --fix / commands
/status The everyday health check from chat. Fast way to see whether the agent is reachable and what state it's in.
/model Inspect or switch the active model. Discord also gives you an interactive model picker.
/subagents spawn Kick off a subagent task from chat and keep the main session clean.
/acp spawn Start an ACP-backed coding/tool harness session from chat, optionally thread-bound.
/focus <target> Bind a Discord thread to a specific session/subagent target.
/agents Show active thread/session bindings and related agent context.
/config set ... Write persistent config from chat if commands.config is enabled and channel configWrites permits it.
/debug set ... Apply runtime-only config overrides that do not touch disk.
/approve <id> allow-once|allow-always|deny Resolve exec approval prompts from chat.
/btw <question> Ask an ephemeral side question about the current session without changing future session context. Gets a quick inline answer then the session continues as normal.
/think <level> Set extended thinking depth: off, minimal, low, medium, high, xhigh. Aliases: /thinking, /t. Persists for the session unless sent inline with a message (then one-shot).
/fast on|off|status Toggle fast mode (routes to faster/cheaper model variant). Persists for the session. Omit arg to see current state.
/reasoning on|off|stream Toggle visible reasoning traces. 'stream' shows live Telegram draft reasoning. Avoid in group chats - it may expose internal reasoning to everyone.
/context detail Show per-file + per-tool + per-skill + system prompt size breakdown of what's using tokens in this session.
/usage cost Print a local cost summary from OpenClaw session logs. '/usage tokens|full' adds per-response token footers.
/exec host=sandbox|gateway|node security=deny|allowlist|full ask=off|on-miss|always Set exec tool permissions for the session. Send '/exec' with no args to see current settings.
/skill <name> [input] Run any installed skill by name directly from chat.
/compact [instructions] Compact the current session context (text-only). Optionally pass custom compaction instructions.
/queue <mode> Control message queuing with options like debounce:2s cap:25 drop:summarize. Send '/queue' to see current state.
/kill <id|#|all> Immediately abort one or all running sub-agents. No confirmation prompt.
/steer <id|#> <message> Steer a running sub-agent: injects message mid-run if possible, otherwise aborts and restarts. Alias: /tell.
/reset or /new [model] Start a fresh session branch. Optionally pass a model name/alias to switch on start.
💡 pro_tips
- › Use the dashboard first. It proves gateway + auth + model + workspace before you waste time debugging Telegram/Discord/Signal setup.
- › Telegram is usually the fastest real chat channel to get working; Signal is the slowest. Use that ordering unless privacy is your top constraint.
- › Create one agent per durable role, not per mood: coding, alerts, family, research. Routing becomes much easier to reason about.
- › Use openclaw agents list --bindings whenever routing feels mysterious. Most 'wrong agent replied' bugs are just binding precedence misunderstandings.
- › Memory is just Markdown plus an index. If you want the assistant to truly remember something, have it write it to MEMORY.md or memory/YYYY-MM-DD.md.
- › Prefer heartbeat for batch awareness checks and cron for exact-time tasks. If you schedule everything as cron, you'll waste tokens and clutter sessions.
- › For multi-user or public-ish contexts, keep mention gating on and tool policy tight. OpenClaw is powerful enough that sloppy defaults become security problems fast.
- › Use openclaw config validate before restarting after config changes. It's faster than discovering a typo via downtime.
- › If status looks wrong after an edit, suspect profile/state/env mismatch before suspecting the model. OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH can make you debug the wrong installation.
- › After upgrades, run openclaw doctor. It is intentionally the boring fix-everything command.
- › Directives (/think, /fast, /model, /exec) work silently for authorized senders and do nothing for unauthorized ones. If a directive feels ignored, check your allowlist — no error is shown.
- › Use /btw for meta questions about the session: what's in context, how cron is configured, etc. It doesn't pollute future session history.
- › openclaw plugins install now prefers ClawHub before npm for known package names. Use 'clawhub:<pkg>' prefix to be explicit.
- › Browser tools can now attach to your real Chrome/Brave/Edge profile via userDataDir config. No more sandboxed re-auth for browser automations.
- › Run 'openclaw security audit --deep --fix' before opening any agent to new users. Catches open DM policies, insecure allowlists, and permission issues automatically.
⚙️ configuration
session.dmScope How DM sessions are isolated. main shares one DM thread; per-channel-peer isolates by sender per channel; per-account-channel-peer adds account separation too.
default: Historically often main; new local onboarding prefers per-channel-peer when unset
recommended: per-channel-peer for almost everyone; per-account-channel-peer if you run multiple channel accounts
tools.profile Base tool policy profile for the assistant.
default: New local onboarding defaults to coding
recommended: coding for serious personal-agent use; tighten further for untrusted/group-facing agents
agents.defaults.workspace Default workspace root where AGENTS.md, SOUL.md, USER.md, MEMORY.md, and memory/ live.
default: ~/.openclaw/workspace
recommended: Keep it stable and backed up; treat it as the assistant's home directory
channels.telegram.dmPolicy Controls who can DM your Telegram bot: pairing, allowlist, open, or disabled.
default: pairing in general docs; quickstart local onboarding may guide you toward allowlist
recommended: allowlist for single-owner bots, pairing if you want explicit first-contact approvals
channels.telegram.groups.*.requireMention Whether the Telegram bot should only respond when mentioned in groups/topics.
default: true in most safe examples
recommended: true for shared groups, false only in trusted/private groups
channels.discord.groupPolicy Controls guild/channel access behavior for Discord.
default: allowlist as the secure baseline when Discord is configured
recommended: allowlist, then explicitly permit only your own guild/channels
channels.discord.guilds.<guildId>.requireMention Whether Discord guild channels require @mention before the agent responds.
default: true in safe setups
recommended: false only in private personal servers where every message should be routed to the bot
commands.native Whether native slash/menu commands are registered on supported channels.
default: auto
recommended: Leave on auto for Discord/Telegram unless native command clutter is a problem
commands.config Enables persistent /config writes from chat.
default: false
recommended: Enable only if you trust the channel and want remote admin from chat
commands.debug Enables runtime-only /debug overrides from chat.
default: false
recommended: Enable for power use; safer than /config because it does not persist
agents.defaults.heartbeat.every How often the main heartbeat runs for periodic awareness tasks.
default: 30m in docs/examples
recommended: 15m-30m for a personal assistant; keep HEARTBEAT.md small
cron.enabled Master switch for gateway scheduler jobs.
default: true
recommended: true if you rely on reminders or scheduled reports
agents.defaults.memorySearch Controls semantic memory indexing/search over MEMORY.md and memory/*.md.
default: enabled when a usable embeddings provider is available
recommended: Enable with a real embeddings provider and periodically check memory status/index health
OPENCLAW_STATE_DIR Environment override for the entire mutable state directory: config, auth, sessions, cron, credentials, logs, and more.
default: ~/.openclaw
recommended: Leave unset unless you deliberately want isolation or are migrating infrastructure
OPENCLAW_CONFIG_PATH Environment override for the active config file path.
default: $OPENCLAW_STATE_DIR/openclaw.json
recommended: Use only intentionally; accidental overrides are a classic source of confusion
browser.profiles.<name>.userDataDir Point browser tools at a real Chrome/Brave/Edge user data directory to attach to your existing logged-in browser session instead of a fresh sandbox.
default: Not set (uses OpenClaw-managed sandbox)
recommended: Set to your real Chrome profile path for browser automations that need real auth. E.g. ~/Library/Application Support/Google/Chrome
commands.bash Enables ! <cmd> and /bash <cmd> to run host shell commands from chat. Requires tools.elevated allowlists to be configured.
default: false
recommended: Enable only for owner-only channels; combine with commands.allowFrom to restrict who can run shell commands
commands.mcp Enables /mcp command for managing OpenClaw MCP server config from chat.
default: false
recommended: Enable for power users who manage MCP servers remotely