{
  "title": "CLI reference",
  "content": "This page describes the current CLI behavior. If commands change, update this doc.\n\n* [`setup`](/cli/setup)\n* [`onboard`](/cli/onboard)\n* [`configure`](/cli/configure)\n* [`config`](/cli/config)\n* [`doctor`](/cli/doctor)\n* [`dashboard`](/cli/dashboard)\n* [`reset`](/cli/reset)\n* [`uninstall`](/cli/uninstall)\n* [`update`](/cli/update)\n* [`message`](/cli/message)\n* [`agent`](/cli/agent)\n* [`agents`](/cli/agents)\n* [`acp`](/cli/acp)\n* [`status`](/cli/status)\n* [`health`](/cli/health)\n* [`sessions`](/cli/sessions)\n* [`gateway`](/cli/gateway)\n* [`logs`](/cli/logs)\n* [`system`](/cli/system)\n* [`models`](/cli/models)\n* [`memory`](/cli/memory)\n* [`nodes`](/cli/nodes)\n* [`devices`](/cli/devices)\n* [`node`](/cli/node)\n* [`approvals`](/cli/approvals)\n* [`sandbox`](/cli/sandbox)\n* [`tui`](/cli/tui)\n* [`browser`](/cli/browser)\n* [`cron`](/cli/cron)\n* [`dns`](/cli/dns)\n* [`docs`](/cli/docs)\n* [`hooks`](/cli/hooks)\n* [`webhooks`](/cli/webhooks)\n* [`pairing`](/cli/pairing)\n* [`plugins`](/cli/plugins) (plugin commands)\n* [`channels`](/cli/channels)\n* [`security`](/cli/security)\n* [`skills`](/cli/skills)\n* [`voicecall`](/cli/voicecall) (plugin; if installed)\n\n* `--dev`: isolate state under `~/.openclaw-dev` and shift default ports.\n* `--profile <name>`: isolate state under `~/.openclaw-<name>`.\n* `--no-color`: disable ANSI colors.\n* `--update`: shorthand for `openclaw update` (source installs only).\n* `-V`, `--version`, `-v`: print version and exit.\n\n* ANSI colors and progress indicators only render in TTY sessions.\n* OSC-8 hyperlinks render as clickable links in supported terminals; otherwise we fall back to plain URLs.\n* `--json` (and `--plain` where supported) disables styling for clean output.\n* `--no-color` disables ANSI styling; `NO_COLOR=1` is also respected.\n* Long-running commands show a progress indicator (OSC 9;4 when supported).\n\nOpenClaw uses a lobster palette for CLI output.\n\n* `accent` (#FF5A2D): headings, labels, primary highlights.\n* `accentBright` (#FF7A3D): command names, emphasis.\n* `accentDim` (#D14A22): secondary highlight text.\n* `info` (#FF8A5B): informational values.\n* `success` (#2FBF71): success states.\n* `warn` (#FFB020): warnings, fallbacks, attention.\n* `error` (#E23D2D): errors, failures.\n* `muted` (#8B7F77): de-emphasis, metadata.\n\nPalette source of truth: `src/terminal/palette.ts` (aka “lobster seam”).\n\nNote: plugins can add additional top-level commands (for example `openclaw voicecall`).\n\n* `openclaw security audit` — audit config + local state for common security foot-guns.\n* `openclaw security audit --deep` — best-effort live Gateway probe.\n* `openclaw security audit --fix` — tighten safe defaults and chmod state/config.\n\nManage extensions and their config:\n\n* `openclaw plugins list` — discover plugins (use `--json` for machine output).\n* `openclaw plugins info <id>` — show details for a plugin.\n* `openclaw plugins install <path|.tgz|npm-spec>` — install a plugin (or add a plugin path to `plugins.load.paths`).\n* `openclaw plugins enable <id>` / `disable <id>` — toggle `plugins.entries.<id>.enabled`.\n* `openclaw plugins doctor` — report plugin load errors.\n\nMost plugin changes require a gateway restart. See [/plugin](/plugin).\n\nVector search over `MEMORY.md` + `memory/*.md`:\n\n* `openclaw memory status` — show index stats.\n* `openclaw memory index` — reindex memory files.\n* `openclaw memory search \"<query>\"` — semantic search over memory.\n\n## Chat slash commands\n\nChat messages support `/...` commands (text and native). See [/tools/slash-commands](/tools/slash-commands).\n\n* `/status` for quick diagnostics.\n* `/config` for persisted config changes.\n* `/debug` for runtime-only config overrides (memory, not disk; requires `commands.debug: true`).\n\n## Setup + onboarding\n\nInitialize config + workspace.\n\n* `--workspace <dir>`: agent workspace path (default `~/.openclaw/workspace`).\n* `--wizard`: run the onboarding wizard.\n* `--non-interactive`: run wizard without prompts.\n* `--mode <local|remote>`: wizard mode.\n* `--remote-url <url>`: remote Gateway URL.\n* `--remote-token <token>`: remote Gateway token.\n\nWizard auto-runs when any wizard flags are present (`--non-interactive`, `--mode`, `--remote-url`, `--remote-token`).\n\nInteractive wizard to set up gateway, workspace, and skills.\n\n* `--workspace <dir>`\n* `--reset` (reset config + credentials + sessions + workspace before wizard)\n* `--non-interactive`\n* `--mode <local|remote>`\n* `--flow <quickstart|advanced|manual>` (manual is an alias for advanced)\n* `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|moonshot-api-key-cn|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip>`\n* `--token-provider <id>` (non-interactive; used with `--auth-choice token`)\n* `--token <token>` (non-interactive; used with `--auth-choice token`)\n* `--token-profile-id <id>` (non-interactive; default: `<provider>:manual`)\n* `--token-expires-in <duration>` (non-interactive; e.g. `365d`, `12h`)\n* `--anthropic-api-key <key>`\n* `--openai-api-key <key>`\n* `--openrouter-api-key <key>`\n* `--ai-gateway-api-key <key>`\n* `--moonshot-api-key <key>`\n* `--kimi-code-api-key <key>`\n* `--gemini-api-key <key>`\n* `--zai-api-key <key>`\n* `--minimax-api-key <key>`\n* `--opencode-zen-api-key <key>`\n* `--gateway-port <port>`\n* `--gateway-bind <loopback|lan|tailnet|auto|custom>`\n* `--gateway-auth <token|password>`\n* `--gateway-token <token>`\n* `--gateway-password <password>`\n* `--remote-url <url>`\n* `--remote-token <token>`\n* `--tailscale <off|serve|funnel>`\n* `--tailscale-reset-on-exit`\n* `--install-daemon`\n* `--no-install-daemon` (alias: `--skip-daemon`)\n* `--daemon-runtime <node|bun>`\n* `--skip-channels`\n* `--skip-skills`\n* `--skip-health`\n* `--skip-ui`\n* `--node-manager <npm|pnpm|bun>` (pnpm recommended; bun not recommended for Gateway runtime)\n* `--json`\n\nInteractive configuration wizard (models, channels, skills, gateway).\n\nNon-interactive config helpers (get/set/unset). Running `openclaw config` with no\nsubcommand launches the wizard.\n\n* `config get <path>`: print a config value (dot/bracket path).\n* `config set <path> <value>`: set a value (JSON5 or raw string).\n* `config unset <path>`: remove a value.\n\nHealth checks + quick fixes (config + gateway + legacy services).\n\n* `--no-workspace-suggestions`: disable workspace memory hints.\n* `--yes`: accept defaults without prompting (headless).\n* `--non-interactive`: skip prompts; apply safe migrations only.\n* `--deep`: scan system services for extra gateway installs.\n\nManage chat channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams).\n\n* `channels list`: show configured channels and auth profiles.\n* `channels status`: check gateway reachability and channel health (`--probe` runs extra checks; use `openclaw health` or `openclaw status --deep` for gateway health probes).\n* Tip: `channels status` prints warnings with suggested fixes when it can detect common misconfigurations (then points you to `openclaw doctor`).\n* `channels logs`: show recent channel logs from the gateway log file.\n* `channels add`: wizard-style setup when no flags are passed; flags switch to non-interactive mode.\n* `channels remove`: disable by default; pass `--delete` to remove config entries without prompts.\n* `channels login`: interactive channel login (WhatsApp Web only).\n* `channels logout`: log out of a channel session (if supported).\n\n* `--channel <name>`: `whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams`\n* `--account <id>`: channel account id (default `default`)\n* `--name <label>`: display name for the account\n\n`channels login` options:\n\n* `--channel <channel>` (default `whatsapp`; supports `whatsapp`/`web`)\n* `--account <id>`\n* `--verbose`\n\n`channels logout` options:\n\n* `--channel <channel>` (default `whatsapp`)\n* `--account <id>`\n\n`channels list` options:\n\n* `--no-usage`: skip model provider usage/quota snapshots (OAuth/API-backed only).\n* `--json`: output JSON (includes usage unless `--no-usage` is set).\n\n`channels logs` options:\n\n* `--channel <name|all>` (default `all`)\n* `--lines <n>` (default `200`)\n* `--json`\n\nMore detail: [/concepts/oauth](/concepts/oauth)\n\nList and inspect available skills plus readiness info.\n\n* `skills list`: list skills (default when no subcommand).\n* `skills info <name>`: show details for one skill.\n* `skills check`: summary of ready vs missing requirements.\n\n* `--eligible`: show only ready skills.\n* `--json`: output JSON (no styling).\n* `-v`, `--verbose`: include missing requirements detail.\n\nTip: use `npx clawhub` to search, install, and sync skills.\n\nApprove DM pairing requests across channels.\n\n* `pairing list <channel> [--json]`\n* `pairing approve <channel> <code> [--notify]`\n\nGmail Pub/Sub hook setup + runner. See [/automation/gmail-pubsub](/automation/gmail-pubsub).\n\n* `webhooks gmail setup` (requires `--account <email>`; supports `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--tailscale-target`, `--push-endpoint`, `--json`)\n* `webhooks gmail run` (runtime overrides for the same flags)\n\nWide-area discovery DNS helper (CoreDNS + Tailscale). See [/gateway/discovery](/gateway/discovery).\n\n* `--apply`: install/update CoreDNS config (requires sudo; macOS only).\n\nUnified outbound messaging + channel actions.\n\nSee: [/cli/message](/cli/message)\n\n* `message send|poll|react|reactions|read|edit|delete|pin|unpin|pins|permissions|search|timeout|kick|ban`\n* `message thread <create|list|reply>`\n* `message emoji <list|upload>`\n* `message sticker <send|upload>`\n* `message role <info|add|remove>`\n* `message channel <info|list>`\n* `message member info`\n* `message voice status`\n* `message event <list|create>`\n\n* `openclaw message send --target +15555550123 --message \"Hi\"`\n* `openclaw message poll --channel discord --target channel:123 --poll-question \"Snack?\" --poll-option Pizza --poll-option Sushi`\n\nRun one agent turn via the Gateway (or `--local` embedded).\n\n* `--to <dest>` (for session key and optional delivery)\n* `--session-id <id>`\n* `--thinking <off|minimal|low|medium|high|xhigh>` (GPT-5.2 + Codex models only)\n* `--verbose <on|full|off>`\n* `--channel <whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams>`\n* `--local`\n* `--deliver`\n* `--json`\n* `--timeout <seconds>`\n\nManage isolated agents (workspaces + auth + routing).\n\nList configured agents.\n\n* `--json`\n* `--bindings`\n\n#### `agents add [name]`\n\nAdd a new isolated agent. Runs the guided wizard unless flags (or `--non-interactive`) are passed; `--workspace` is required in non-interactive mode.\n\n* `--workspace <dir>`\n* `--model <id>`\n* `--agent-dir <dir>`\n* `--bind <channel[:accountId]>` (repeatable)\n* `--non-interactive`\n* `--json`\n\nBinding specs use `channel[:accountId]`. When `accountId` is omitted for WhatsApp, the default account id is used.\n\n#### `agents delete <id>`\n\nDelete an agent and prune its workspace + state.\n\n* `--force`\n* `--json`\n\nRun the ACP bridge that connects IDEs to the Gateway.\n\nSee [`acp`](/cli/acp) for full options and examples.\n\nShow linked session health and recent recipients.\n\n* `--json`\n* `--all` (full diagnosis; read-only, pasteable)\n* `--deep` (probe channels)\n* `--usage` (show model provider usage/quota)\n* `--timeout <ms>`\n* `--verbose`\n* `--debug` (alias for `--verbose`)\n\n* Overview includes Gateway + node host service status when available.\n\nOpenClaw can surface provider usage/quota when OAuth/API creds are available.\n\n* `/status` (adds a short provider usage line when available)\n* `openclaw status --usage` (prints full provider breakdown)\n* macOS menu bar (Usage section under Context)\n\n* Data comes directly from provider usage endpoints (no estimates).\n* Providers: Anthropic, GitHub Copilot, OpenAI Codex OAuth, plus Gemini CLI/Antigravity when those provider plugins are enabled.\n* If no matching credentials exist, usage is hidden.\n* Details: see [Usage tracking](/concepts/usage-tracking).\n\nFetch health from the running Gateway.\n\n* `--json`\n* `--timeout <ms>`\n* `--verbose`\n\nList stored conversation sessions.\n\n* `--json`\n* `--verbose`\n* `--store <path>`\n* `--active <minutes>`\n\nReset local config/state (keeps the CLI installed).\n\n* `--scope <config|config+creds+sessions|full>`\n* `--yes`\n* `--non-interactive`\n* `--dry-run`\n\n* `--non-interactive` requires `--scope` and `--yes`.\n\nUninstall the gateway service + local data (CLI remains).\n\n* `--service`\n* `--state`\n* `--workspace`\n* `--app`\n* `--all`\n* `--yes`\n* `--non-interactive`\n* `--dry-run`\n\n* `--non-interactive` requires `--yes` and explicit scopes (or `--all`).\n\nRun the WebSocket Gateway.\n\n* `--port <port>`\n* `--bind <loopback|tailnet|lan|auto|custom>`\n* `--token <token>`\n* `--auth <token|password>`\n* `--password <password>`\n* `--tailscale <off|serve|funnel>`\n* `--tailscale-reset-on-exit`\n* `--allow-unconfigured`\n* `--dev`\n* `--reset` (reset dev config + credentials + sessions + workspace)\n* `--force` (kill existing listener on port)\n* `--verbose`\n* `--claude-cli-logs`\n* `--ws-log <auto|full|compact>`\n* `--compact` (alias for `--ws-log compact`)\n* `--raw-stream`\n* `--raw-stream-path <path>`\n\n### `gateway service`\n\nManage the Gateway service (launchd/systemd/schtasks).\n\n* `gateway status` (probes the Gateway RPC by default)\n* `gateway install` (service install)\n* `gateway uninstall`\n* `gateway start`\n* `gateway stop`\n* `gateway restart`\n\n* `gateway status` probes the Gateway RPC by default using the service’s resolved port/config (override with `--url/--token/--password`).\n* `gateway status` supports `--no-probe`, `--deep`, and `--json` for scripting.\n* `gateway status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans). Profile-named OpenClaw services are treated as first-class and aren't flagged as \"extra\".\n* `gateway status` prints which config path the CLI uses vs which config the service likely uses (service env), plus the resolved probe target URL.\n* `gateway install|uninstall|start|stop|restart` support `--json` for scripting (default output stays human-friendly).\n* `gateway install` defaults to Node runtime; bun is **not recommended** (WhatsApp/Telegram bugs).\n* `gateway install` options: `--port`, `--runtime`, `--token`, `--force`, `--json`.\n\nTail Gateway file logs via RPC.\n\n* TTY sessions render a colorized, structured view; non-TTY falls back to plain text.\n* `--json` emits line-delimited JSON (one log event per line).\n\n### `gateway <subcommand>`\n\nGateway CLI helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for RPC subcommands).\nWhen you pass `--url`, the CLI does not auto-apply config or environment credentials.\nInclude `--token` or `--password` explicitly. Missing explicit credentials is an error.\n\n* `gateway call <method> [--params <json>]`\n* `gateway health`\n* `gateway status`\n* `gateway probe`\n* `gateway discover`\n* `gateway install|uninstall|start|stop|restart`\n* `gateway run`\n\n* `config.apply` (validate + write config + restart + wake)\n* `config.patch` (merge a partial update + restart + wake)\n* `update.run` (run update + restart + wake)\n\nTip: when calling `config.set`/`config.apply`/`config.patch` directly, pass `baseHash` from\n`config.get` if a config already exists.\n\nSee [/concepts/models](/concepts/models) for fallback behavior and scanning strategy.\n\nPreferred Anthropic auth (setup-token):\n\n`openclaw models` is an alias for `models status`.\n\n* `--status-json` (alias for `models status --json`)\n* `--status-plain` (alias for `models status --plain`)\n\n* `--all`\n* `--local`\n* `--provider <name>`\n* `--json`\n* `--plain`\n\n* `--json`\n* `--plain`\n* `--check` (exit 1=expired/missing, 2=expiring)\n* `--probe` (live probe of configured auth profiles)\n* `--probe-provider <name>`\n* `--probe-profile <id>` (repeat or comma-separated)\n* `--probe-timeout <ms>`\n* `--probe-concurrency <n>`\n* `--probe-max-tokens <n>`\n\nAlways includes the auth overview and OAuth expiry status for profiles in the auth store.\n`--probe` runs live requests (may consume tokens and trigger rate limits).\n\n### `models set <model>`\n\nSet `agents.defaults.model.primary`.\n\n### `models set-image <model>`\n\nSet `agents.defaults.imageModel.primary`.\n\n### `models aliases list|add|remove`\n\n* `list`: `--json`, `--plain`\n* `add <alias> <model>`\n* `remove <alias>`\n\n### `models fallbacks list|add|remove|clear`\n\n* `list`: `--json`, `--plain`\n* `add <model>`\n* `remove <model>`\n* `clear`\n\n### `models image-fallbacks list|add|remove|clear`\n\n* `list`: `--json`, `--plain`\n* `add <model>`\n* `remove <model>`\n* `clear`\n\n* `--min-params <b>`\n* `--max-age-days <days>`\n* `--provider <name>`\n* `--max-candidates <n>`\n* `--timeout <ms>`\n* `--concurrency <n>`\n* `--no-probe`\n* `--yes`\n* `--no-input`\n* `--set-default`\n* `--set-image`\n* `--json`\n\n### `models auth add|setup-token|paste-token`\n\n* `add`: interactive auth helper\n* `setup-token`: `--provider <name>` (default `anthropic`), `--yes`\n* `paste-token`: `--provider <name>`, `--profile-id <id>`, `--expires-in <duration>`\n\n### `models auth order get|set|clear`\n\n* `get`: `--provider <name>`, `--agent <id>`, `--json`\n* `set`: `--provider <name>`, `--agent <id>`, `<profileIds...>`\n* `clear`: `--provider <name>`, `--agent <id>`\n\nEnqueue a system event and optionally trigger a heartbeat (Gateway RPC).\n\n* `--mode <now|next-heartbeat>`\n* `--json`\n* `--url`, `--token`, `--timeout`, `--expect-final`\n\n### `system heartbeat last|enable|disable`\n\nHeartbeat controls (Gateway RPC).\n\n* `--json`\n* `--url`, `--token`, `--timeout`, `--expect-final`\n\n### `system presence`\n\nList system presence entries (Gateway RPC).\n\n* `--json`\n* `--url`, `--token`, `--timeout`, `--expect-final`\n\nManage scheduled jobs (Gateway RPC). See [/automation/cron-jobs](/automation/cron-jobs).\n\n* `cron status [--json]`\n* `cron list [--all] [--json]` (table output by default; use `--json` for raw)\n* `cron add` (alias: `create`; requires `--name` and exactly one of `--at` | `--every` | `--cron`, and exactly one payload of `--system-event` | `--message`)\n* `cron edit <id>` (patch fields)\n* `cron rm <id>` (aliases: `remove`, `delete`)\n* `cron enable <id>`\n* `cron disable <id>`\n* `cron runs --id <id> [--limit <n>]`\n* `cron run <id> [--force]`\n\nAll `cron` commands accept `--url`, `--token`, `--timeout`, `--expect-final`.\n\n`node` runs a **headless node host** or manages it as a background service. See\n[`openclaw node`](/cli/node).\n\n* `node run --host <gateway-host> --port 18789`\n* `node status`\n* `node install [--host <gateway-host>] [--port <port>] [--tls] [--tls-fingerprint <sha256>] [--node-id <id>] [--display-name <name>] [--runtime <node|bun>] [--force]`\n* `node uninstall`\n* `node stop`\n* `node restart`\n\n`nodes` talks to the Gateway and targets paired nodes. See [/nodes](/nodes).\n\n* `--url`, `--token`, `--timeout`, `--json`\n\n* `nodes status [--connected] [--last-connected <duration>]`\n* `nodes describe --node <id|name|ip>`\n* `nodes list [--connected] [--last-connected <duration>]`\n* `nodes pending`\n* `nodes approve <requestId>`\n* `nodes reject <requestId>`\n* `nodes rename --node <id|name|ip> --name <displayName>`\n* `nodes invoke --node <id|name|ip> --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]`\n* `nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>` (mac node or headless node host)\n* `nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]` (mac only)\n\n* `nodes camera list --node <id|name|ip>`\n* `nodes camera snap --node <id|name|ip> [--facing front|back|both] [--device-id <id>] [--max-width <px>] [--quality <0-1>] [--delay-ms <ms>] [--invoke-timeout <ms>]`\n* `nodes camera clip --node <id|name|ip> [--facing front|back] [--device-id <id>] [--duration <ms|10s|1m>] [--no-audio] [--invoke-timeout <ms>]`\n\n* `nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]`\n* `nodes canvas present --node <id|name|ip> [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>] [--invoke-timeout <ms>]`\n* `nodes canvas hide --node <id|name|ip> [--invoke-timeout <ms>]`\n* `nodes canvas navigate <url> --node <id|name|ip> [--invoke-timeout <ms>]`\n* `nodes canvas eval [<js>] --node <id|name|ip> [--js <code>] [--invoke-timeout <ms>]`\n* `nodes canvas a2ui push --node <id|name|ip> (--jsonl <path> | --text <text>) [--invoke-timeout <ms>]`\n* `nodes canvas a2ui reset --node <id|name|ip> [--invoke-timeout <ms>]`\n* `nodes screen record --node <id|name|ip> [--screen <index>] [--duration <ms|10s>] [--fps <n>] [--no-audio] [--out <path>] [--invoke-timeout <ms>]`\n\n* `nodes location get --node <id|name|ip> [--max-age <ms>] [--accuracy <coarse|balanced|precise>] [--location-timeout <ms>] [--invoke-timeout <ms>]`\n\nBrowser control CLI (dedicated Chrome/Brave/Edge/Chromium). See [`openclaw browser`](/cli/browser) and the [Browser tool](/tools/browser).\n\n* `--url`, `--token`, `--timeout`, `--json`\n* `--browser-profile <name>`\n\n* `browser status`\n* `browser start`\n* `browser stop`\n* `browser reset-profile`\n* `browser tabs`\n* `browser open <url>`\n* `browser focus <targetId>`\n* `browser close [targetId]`\n* `browser profiles`\n* `browser create-profile --name <name> [--color <hex>] [--cdp-url <url>]`\n* `browser delete-profile --name <name>`\n\n* `browser screenshot [targetId] [--full-page] [--ref <ref>] [--element <selector>] [--type png|jpeg]`\n* `browser snapshot [--format aria|ai] [--target-id <id>] [--limit <n>] [--interactive] [--compact] [--depth <n>] [--selector <sel>] [--out <path>]`\n\n* `browser navigate <url> [--target-id <id>]`\n* `browser resize <width> <height> [--target-id <id>]`\n* `browser click <ref> [--double] [--button <left|right|middle>] [--modifiers <csv>] [--target-id <id>]`\n* `browser type <ref> <text> [--submit] [--slowly] [--target-id <id>]`\n* `browser press <key> [--target-id <id>]`\n* `browser hover <ref> [--target-id <id>]`\n* `browser drag <startRef> <endRef> [--target-id <id>]`\n* `browser select <ref> <values...> [--target-id <id>]`\n* `browser upload <paths...> [--ref <ref>] [--input-ref <ref>] [--element <selector>] [--target-id <id>] [--timeout-ms <ms>]`\n* `browser fill [--fields <json>] [--fields-file <path>] [--target-id <id>]`\n* `browser dialog --accept|--dismiss [--prompt <text>] [--target-id <id>] [--timeout-ms <ms>]`\n* `browser wait [--time <ms>] [--text <value>] [--text-gone <value>] [--target-id <id>]`\n* `browser evaluate --fn <code> [--ref <ref>] [--target-id <id>]`\n* `browser console [--level <error|warn|info>] [--target-id <id>]`\n* `browser pdf [--target-id <id>]`\n\n### `docs [query...]`\n\nSearch the live docs index.\n\nOpen the terminal UI connected to the Gateway.\n\n* `--url <url>`\n* `--token <token>`\n* `--password <password>`\n* `--session <key>`\n* `--deliver`\n* `--thinking <level>`\n* `--message <text>`\n* `--timeout-ms <ms>` (defaults to `agents.defaults.timeoutSeconds`)\n* `--history-limit <n>`",
  "code_samples": [
    {
      "code": "openclaw [--dev] [--profile <name>] <command>\n  setup\n  onboard\n  configure\n  config\n    get\n    set\n    unset\n  doctor\n  security\n    audit\n  reset\n  uninstall\n  update\n  channels\n    list\n    status\n    logs\n    add\n    remove\n    login\n    logout\n  skills\n    list\n    info\n    check\n  plugins\n    list\n    info\n    install\n    enable\n    disable\n    doctor\n  memory\n    status\n    index\n    search\n  message\n  agent\n  agents\n    list\n    add\n    delete\n  acp\n  status\n  health\n  sessions\n  gateway\n    call\n    health\n    status\n    probe\n    discover\n    install\n    uninstall\n    start\n    stop\n    restart\n    run\n  logs\n  system\n    event\n    heartbeat last|enable|disable\n    presence\n  models\n    list\n    status\n    set\n    set-image\n    aliases list|add|remove\n    fallbacks list|add|remove|clear\n    image-fallbacks list|add|remove|clear\n    scan\n    auth add|setup-token|paste-token\n    auth order get|set|clear\n  sandbox\n    list\n    recreate\n    explain\n  cron\n    status\n    list\n    add\n    edit\n    rm\n    enable\n    disable\n    runs\n    run\n  nodes\n  devices\n  node\n    run\n    status\n    install\n    uninstall\n    start\n    stop\n    restart\n  approvals\n    get\n    set\n    allowlist add|remove\n  browser\n    status\n    start\n    stop\n    reset-profile\n    tabs\n    open\n    focus\n    close\n    profiles\n    create-profile\n    delete-profile\n    screenshot\n    snapshot\n    navigate\n    resize\n    click\n    type\n    press\n    hover\n    drag\n    select\n    upload\n    fill\n    dialog\n    wait\n    evaluate\n    console\n    pdf\n  hooks\n    list\n    info\n    check\n    enable\n    disable\n    install\n    update\n  webhooks\n    gmail setup|run\n  pairing\n    list\n    approve\n  docs\n  dns\n    setup\n  tui",
      "language": "unknown"
    },
    {
      "code": "### `skills`\n\nList and inspect available skills plus readiness info.\n\nSubcommands:\n\n* `skills list`: list skills (default when no subcommand).\n* `skills info <name>`: show details for one skill.\n* `skills check`: summary of ready vs missing requirements.\n\nOptions:\n\n* `--eligible`: show only ready skills.\n* `--json`: output JSON (no styling).\n* `-v`, `--verbose`: include missing requirements detail.\n\nTip: use `npx clawhub` to search, install, and sync skills.\n\n### `pairing`\n\nApprove DM pairing requests across channels.\n\nSubcommands:\n\n* `pairing list <channel> [--json]`\n* `pairing approve <channel> <code> [--notify]`\n\n### `webhooks gmail`\n\nGmail Pub/Sub hook setup + runner. See [/automation/gmail-pubsub](/automation/gmail-pubsub).\n\nSubcommands:\n\n* `webhooks gmail setup` (requires `--account <email>`; supports `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--tailscale-target`, `--push-endpoint`, `--json`)\n* `webhooks gmail run` (runtime overrides for the same flags)\n\n### `dns setup`\n\nWide-area discovery DNS helper (CoreDNS + Tailscale). See [/gateway/discovery](/gateway/discovery).\n\nOptions:\n\n* `--apply`: install/update CoreDNS config (requires sudo; macOS only).\n\n## Messaging + agent\n\n### `message`\n\nUnified outbound messaging + channel actions.\n\nSee: [/cli/message](/cli/message)\n\nSubcommands:\n\n* `message send|poll|react|reactions|read|edit|delete|pin|unpin|pins|permissions|search|timeout|kick|ban`\n* `message thread <create|list|reply>`\n* `message emoji <list|upload>`\n* `message sticker <send|upload>`\n* `message role <info|add|remove>`\n* `message channel <info|list>`\n* `message member info`\n* `message voice status`\n* `message event <list|create>`\n\nExamples:\n\n* `openclaw message send --target +15555550123 --message \"Hi\"`\n* `openclaw message poll --channel discord --target channel:123 --poll-question \"Snack?\" --poll-option Pizza --poll-option Sushi`\n\n### `agent`\n\nRun one agent turn via the Gateway (or `--local` embedded).\n\nRequired:\n\n* `--message <text>`\n\nOptions:\n\n* `--to <dest>` (for session key and optional delivery)\n* `--session-id <id>`\n* `--thinking <off|minimal|low|medium|high|xhigh>` (GPT-5.2 + Codex models only)\n* `--verbose <on|full|off>`\n* `--channel <whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams>`\n* `--local`\n* `--deliver`\n* `--json`\n* `--timeout <seconds>`\n\n### `agents`\n\nManage isolated agents (workspaces + auth + routing).\n\n#### `agents list`\n\nList configured agents.\n\nOptions:\n\n* `--json`\n* `--bindings`\n\n#### `agents add [name]`\n\nAdd a new isolated agent. Runs the guided wizard unless flags (or `--non-interactive`) are passed; `--workspace` is required in non-interactive mode.\n\nOptions:\n\n* `--workspace <dir>`\n* `--model <id>`\n* `--agent-dir <dir>`\n* `--bind <channel[:accountId]>` (repeatable)\n* `--non-interactive`\n* `--json`\n\nBinding specs use `channel[:accountId]`. When `accountId` is omitted for WhatsApp, the default account id is used.\n\n#### `agents delete <id>`\n\nDelete an agent and prune its workspace + state.\n\nOptions:\n\n* `--force`\n* `--json`\n\n### `acp`\n\nRun the ACP bridge that connects IDEs to the Gateway.\n\nSee [`acp`](/cli/acp) for full options and examples.\n\n### `status`\n\nShow linked session health and recent recipients.\n\nOptions:\n\n* `--json`\n* `--all` (full diagnosis; read-only, pasteable)\n* `--deep` (probe channels)\n* `--usage` (show model provider usage/quota)\n* `--timeout <ms>`\n* `--verbose`\n* `--debug` (alias for `--verbose`)\n\nNotes:\n\n* Overview includes Gateway + node host service status when available.\n\n### Usage tracking\n\nOpenClaw can surface provider usage/quota when OAuth/API creds are available.\n\nSurfaces:\n\n* `/status` (adds a short provider usage line when available)\n* `openclaw status --usage` (prints full provider breakdown)\n* macOS menu bar (Usage section under Context)\n\nNotes:\n\n* Data comes directly from provider usage endpoints (no estimates).\n* Providers: Anthropic, GitHub Copilot, OpenAI Codex OAuth, plus Gemini CLI/Antigravity when those provider plugins are enabled.\n* If no matching credentials exist, usage is hidden.\n* Details: see [Usage tracking](/concepts/usage-tracking).\n\n### `health`\n\nFetch health from the running Gateway.\n\nOptions:\n\n* `--json`\n* `--timeout <ms>`\n* `--verbose`\n\n### `sessions`\n\nList stored conversation sessions.\n\nOptions:\n\n* `--json`\n* `--verbose`\n* `--store <path>`\n* `--active <minutes>`\n\n## Reset / Uninstall\n\n### `reset`\n\nReset local config/state (keeps the CLI installed).\n\nOptions:\n\n* `--scope <config|config+creds+sessions|full>`\n* `--yes`\n* `--non-interactive`\n* `--dry-run`\n\nNotes:\n\n* `--non-interactive` requires `--scope` and `--yes`.\n\n### `uninstall`\n\nUninstall the gateway service + local data (CLI remains).\n\nOptions:\n\n* `--service`\n* `--state`\n* `--workspace`\n* `--app`\n* `--all`\n* `--yes`\n* `--non-interactive`\n* `--dry-run`\n\nNotes:\n\n* `--non-interactive` requires `--yes` and explicit scopes (or `--all`).\n\n## Gateway\n\n### `gateway`\n\nRun the WebSocket Gateway.\n\nOptions:\n\n* `--port <port>`\n* `--bind <loopback|tailnet|lan|auto|custom>`\n* `--token <token>`\n* `--auth <token|password>`\n* `--password <password>`\n* `--tailscale <off|serve|funnel>`\n* `--tailscale-reset-on-exit`\n* `--allow-unconfigured`\n* `--dev`\n* `--reset` (reset dev config + credentials + sessions + workspace)\n* `--force` (kill existing listener on port)\n* `--verbose`\n* `--claude-cli-logs`\n* `--ws-log <auto|full|compact>`\n* `--compact` (alias for `--ws-log compact`)\n* `--raw-stream`\n* `--raw-stream-path <path>`\n\n### `gateway service`\n\nManage the Gateway service (launchd/systemd/schtasks).\n\nSubcommands:\n\n* `gateway status` (probes the Gateway RPC by default)\n* `gateway install` (service install)\n* `gateway uninstall`\n* `gateway start`\n* `gateway stop`\n* `gateway restart`\n\nNotes:\n\n* `gateway status` probes the Gateway RPC by default using the service’s resolved port/config (override with `--url/--token/--password`).\n* `gateway status` supports `--no-probe`, `--deep`, and `--json` for scripting.\n* `gateway status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans). Profile-named OpenClaw services are treated as first-class and aren't flagged as \"extra\".\n* `gateway status` prints which config path the CLI uses vs which config the service likely uses (service env), plus the resolved probe target URL.\n* `gateway install|uninstall|start|stop|restart` support `--json` for scripting (default output stays human-friendly).\n* `gateway install` defaults to Node runtime; bun is **not recommended** (WhatsApp/Telegram bugs).\n* `gateway install` options: `--port`, `--runtime`, `--token`, `--force`, `--json`.\n\n### `logs`\n\nTail Gateway file logs via RPC.\n\nNotes:\n\n* TTY sessions render a colorized, structured view; non-TTY falls back to plain text.\n* `--json` emits line-delimited JSON (one log event per line).\n\nExamples:",
      "language": "unknown"
    },
    {
      "code": "### `gateway <subcommand>`\n\nGateway CLI helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for RPC subcommands).\nWhen you pass `--url`, the CLI does not auto-apply config or environment credentials.\nInclude `--token` or `--password` explicitly. Missing explicit credentials is an error.\n\nSubcommands:\n\n* `gateway call <method> [--params <json>]`\n* `gateway health`\n* `gateway status`\n* `gateway probe`\n* `gateway discover`\n* `gateway install|uninstall|start|stop|restart`\n* `gateway run`\n\nCommon RPCs:\n\n* `config.apply` (validate + write config + restart + wake)\n* `config.patch` (merge a partial update + restart + wake)\n* `update.run` (run update + restart + wake)\n\nTip: when calling `config.set`/`config.apply`/`config.patch` directly, pass `baseHash` from\n`config.get` if a config already exists.\n\n## Models\n\nSee [/concepts/models](/concepts/models) for fallback behavior and scanning strategy.\n\nPreferred Anthropic auth (setup-token):",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Command pages",
      "id": "command-pages"
    },
    {
      "level": "h2",
      "text": "Global flags",
      "id": "global-flags"
    },
    {
      "level": "h2",
      "text": "Output styling",
      "id": "output-styling"
    },
    {
      "level": "h2",
      "text": "Color palette",
      "id": "color-palette"
    },
    {
      "level": "h2",
      "text": "Command tree",
      "id": "command-tree"
    },
    {
      "level": "h2",
      "text": "Security",
      "id": "security"
    },
    {
      "level": "h2",
      "text": "Plugins",
      "id": "plugins"
    },
    {
      "level": "h2",
      "text": "Memory",
      "id": "memory"
    },
    {
      "level": "h2",
      "text": "Chat slash commands",
      "id": "chat-slash-commands"
    },
    {
      "level": "h2",
      "text": "Setup + onboarding",
      "id": "setup-+-onboarding"
    },
    {
      "level": "h3",
      "text": "`setup`",
      "id": "`setup`"
    },
    {
      "level": "h3",
      "text": "`onboard`",
      "id": "`onboard`"
    },
    {
      "level": "h3",
      "text": "`configure`",
      "id": "`configure`"
    },
    {
      "level": "h3",
      "text": "`config`",
      "id": "`config`"
    },
    {
      "level": "h3",
      "text": "`doctor`",
      "id": "`doctor`"
    },
    {
      "level": "h2",
      "text": "Channel helpers",
      "id": "channel-helpers"
    },
    {
      "level": "h3",
      "text": "`channels`",
      "id": "`channels`"
    },
    {
      "level": "h3",
      "text": "`skills`",
      "id": "`skills`"
    },
    {
      "level": "h3",
      "text": "`pairing`",
      "id": "`pairing`"
    },
    {
      "level": "h3",
      "text": "`webhooks gmail`",
      "id": "`webhooks-gmail`"
    },
    {
      "level": "h3",
      "text": "`dns setup`",
      "id": "`dns-setup`"
    },
    {
      "level": "h2",
      "text": "Messaging + agent",
      "id": "messaging-+-agent"
    },
    {
      "level": "h3",
      "text": "`message`",
      "id": "`message`"
    },
    {
      "level": "h3",
      "text": "`agent`",
      "id": "`agent`"
    },
    {
      "level": "h3",
      "text": "`agents`",
      "id": "`agents`"
    },
    {
      "level": "h3",
      "text": "`acp`",
      "id": "`acp`"
    },
    {
      "level": "h3",
      "text": "`status`",
      "id": "`status`"
    },
    {
      "level": "h3",
      "text": "Usage tracking",
      "id": "usage-tracking"
    },
    {
      "level": "h3",
      "text": "`health`",
      "id": "`health`"
    },
    {
      "level": "h3",
      "text": "`sessions`",
      "id": "`sessions`"
    },
    {
      "level": "h2",
      "text": "Reset / Uninstall",
      "id": "reset-/-uninstall"
    },
    {
      "level": "h3",
      "text": "`reset`",
      "id": "`reset`"
    },
    {
      "level": "h3",
      "text": "`uninstall`",
      "id": "`uninstall`"
    },
    {
      "level": "h2",
      "text": "Gateway",
      "id": "gateway"
    },
    {
      "level": "h3",
      "text": "`gateway`",
      "id": "`gateway`"
    },
    {
      "level": "h3",
      "text": "`gateway service`",
      "id": "`gateway-service`"
    },
    {
      "level": "h3",
      "text": "`logs`",
      "id": "`logs`"
    },
    {
      "level": "h3",
      "text": "`gateway <subcommand>`",
      "id": "`gateway-<subcommand>`"
    },
    {
      "level": "h2",
      "text": "Models",
      "id": "models"
    },
    {
      "level": "h3",
      "text": "`models` (root)",
      "id": "`models`-(root)"
    },
    {
      "level": "h3",
      "text": "`models list`",
      "id": "`models-list`"
    },
    {
      "level": "h3",
      "text": "`models status`",
      "id": "`models-status`"
    },
    {
      "level": "h3",
      "text": "`models set <model>`",
      "id": "`models-set-<model>`"
    },
    {
      "level": "h3",
      "text": "`models set-image <model>`",
      "id": "`models-set-image-<model>`"
    },
    {
      "level": "h3",
      "text": "`models aliases list|add|remove`",
      "id": "`models-aliases-list|add|remove`"
    },
    {
      "level": "h3",
      "text": "`models fallbacks list|add|remove|clear`",
      "id": "`models-fallbacks-list|add|remove|clear`"
    },
    {
      "level": "h3",
      "text": "`models image-fallbacks list|add|remove|clear`",
      "id": "`models-image-fallbacks-list|add|remove|clear`"
    },
    {
      "level": "h3",
      "text": "`models scan`",
      "id": "`models-scan`"
    },
    {
      "level": "h3",
      "text": "`models auth add|setup-token|paste-token`",
      "id": "`models-auth-add|setup-token|paste-token`"
    },
    {
      "level": "h3",
      "text": "`models auth order get|set|clear`",
      "id": "`models-auth-order-get|set|clear`"
    },
    {
      "level": "h2",
      "text": "System",
      "id": "system"
    },
    {
      "level": "h3",
      "text": "`system event`",
      "id": "`system-event`"
    },
    {
      "level": "h3",
      "text": "`system heartbeat last|enable|disable`",
      "id": "`system-heartbeat-last|enable|disable`"
    },
    {
      "level": "h3",
      "text": "`system presence`",
      "id": "`system-presence`"
    },
    {
      "level": "h2",
      "text": "Cron",
      "id": "cron"
    },
    {
      "level": "h2",
      "text": "Node host",
      "id": "node-host"
    },
    {
      "level": "h2",
      "text": "Nodes",
      "id": "nodes"
    },
    {
      "level": "h2",
      "text": "Browser",
      "id": "browser"
    },
    {
      "level": "h2",
      "text": "Docs search",
      "id": "docs-search"
    },
    {
      "level": "h3",
      "text": "`docs [query...]`",
      "id": "`docs-[query...]`"
    },
    {
      "level": "h2",
      "text": "TUI",
      "id": "tui"
    },
    {
      "level": "h3",
      "text": "`tui`",
      "id": "`tui`"
    }
  ],
  "url": "llms-txt#cli-reference",
  "links": []
}