CLI Reference

This page describes current CLI behavior. If commands change, please update this documentation.

- setup

- onboard

- configure

- config

- doctor

- dashboard

- reset

- uninstall

- update

- message

- agent

- agents

- acp

- status

- health

- sessions

- gateway

- logs

- system

- models

- memory

- nodes

- devices

- node

- approvals

- sandbox

- tui

- browser

- cron

- dns

- docs

- hooks

- webhooks

- pairing

- plugins(plugin commands)

- channels

- security

- skills

- voicecall(plugin; if installed)

- --dev：Isolate state under ~/.openclaw-dev and switch default ports.

- --profile <name>：Isolate state under ~/.openclaw-'<name>'.

- --no-color：Disable ANSI colors.

- --update：Shorthand for openclaw update (source installs only).

- -V、--version、-v：Print version and exit.

ANSI colors and progress indicators are only rendered in TTY sessions.

OSC-8 hyperlinks render as clickable links in supported terminals; otherwise we fall back to plain URLs.

(and --plain when supported) disable styling for clean output.

Disables ANSI styling; NO_COLOR=1 is also respected.

Long-running commands display progress indicators (OSC 9;4 when supported).

OpenClaw uses the Lobster palette for CLI output.

- accent (#FF5A2D)：Headings, labels, primary highlights.

- accentBright (#FF7A3D)：Command names, emphasis.

- accentDim (#D14A22)：Secondary highlight text.

- info (#FF8A5B)：Informational values.

- success (#2FBF71)：Success states.

- warn (#FFB020)：Warnings, fallbacks, notes.

- error (#E23D2D)：Errors, failures.

- muted (#8B7F77)：De-emphasis, metadata.

Palette source of truth: src/terminal/palette.ts (aka "Lobster Seam").

openclaw [--dev] [--profile <name>] <command>
  setup
  onboard
  configure
  config
    get
    set
    unset
  doctor
  security
    audit
  reset
  uninstall
  update
  channels
    list
    status
    logs
    add
    remove
    login
    logout
  skills
    list
    info
    check
  plugins
    list
    info
    install
    enable
    disable
    doctor
  memory
    status
    index
    search
  message
  agent
  agents
    list
    add
    delete
  acp
  status
  health
  sessions
  gateway
    call
    health
    status
    probe
    discover
    install
    uninstall
    start
    stop
    restart
    run
  logs
  system
    event
    heartbeat last|enable|disable
    presence
  models
    list
    status
    set
    set-image
    aliases list|add|remove
    fallbacks list|add|remove|clear
    image-fallbacks list|add|remove|clear
    scan
    auth add|setup-token|paste-token
    auth order get|set|clear
  sandbox
    list
    recreate
    explain
  cron
    status
    list
    add
    edit
    rm
    enable
    disable
    runs
    run
  nodes
  devices
  node
    run
    status
    install
    uninstall
    start
    stop
    restart
  approvals
    get
    set
    allowlist add|remove
  browser
    status
    start
    stop
    reset-profile
    tabs
    open
    focus
    close
    profiles
    create-profile
    delete-profile
    screenshot
    snapshot
    navigate
    resize
    click
    type
    press
    hover
    drag
    select
    upload
    fill
    dialog
    wait
    evaluate
    console
    pdf
  hooks
    list
    info
    check
    enable
    disable
    install
    update
  webhooks
    gmail setup|run
  pairing
    list
    approve
  docs
  dns
    setup
  tui

Note: Plugins can add additional top-level commands (e.g., openclaw voicecall).

- openclaw security audit — Audit configuration+local state for common security gotchas.

- openclaw security audit --deep — Best-effort live gateway probing.

- openclaw security audit --fix — Tighten security defaults and chmod state/config.

Manage extensions and their configuration:

- openclaw plugins list — Discover plugins (use --json for machine output).

- openclaw plugins info <id> — Show detailed information about a plugin.

- openclaw plugins install <path|.tgz|npm-spec> — Install a plugin (or add plugin path to plugins.load.paths).

- openclaw plugins enable <id> / disable <id> — Toggle plugins.entries.'<id>'.enabled.

- openclaw plugins doctor — Report plugin loading errors.

Most plugin changes require a gateway restart. See /plugins.

Vector search over MEMORY.md + memory/*.md:

- openclaw memory status — Show index statistics.

- openclaw memory index — Re-index memory files.

- openclaw memory search "<query>" — Semantic search over memory.

Chat messages support /... commands (text and native). See /tools/slash-commands.

Highlights:

- /status For quick diagnostics.

- /config For persistent configuration changes.

- /debug For runtime-only configuration overrides (in-memory, not disk; requires commands.debug: true).

#

Initialize configuration+workspace.

Options:

- --workspace <dir>：Agent workspace path (default ~/.openclaw/workspace).

- --wizard：Run onboarding wizard.

- --non-interactive：Run wizard without prompting.

- --mode <local|remote>：Wizard mode.

- --remote-url <url>：Remote gateway URL.

- --remote-token <token>：Remote gateway token.

ReferenceCliPage step 11: Wizard auto run

#

Interactive wizard for setting up gateway, workspace, and skills.

Options:

- --workspace <dir>

- --reset（ReferenceCliPage step 12: Reset）

- --non-interactive

- --mode <local|remote>

- --flow <quickstart|advanced|manual> （ReferenceCliPage step 12: Flow）

- --auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|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>

- --token-provider <id>（ReferenceCliPage step 12: Token provider）

- --token <token>（ReferenceCliPage step 12: Token）

- --token-profile-id <id>（ReferenceCliPage step 12: Token profile id）

- --token-expires-in <duration>（ReferenceCliPage step 12: Token expires in）

- --anthropic-api-key <key>

- --openai-api-key <key>

- --openrouter-api-key <key>

- --ai-gateway-api-key <key>

- --moonshot-api-key <key>

- --kimi-code-api-key <key>

- --gemini-api-key <key>

- --zai-api-key <key>

- --minimax-api-key <key>

- --opencode-zen-api-key <key>

- --gateway-port <port>

- --gateway-bind <loopback|lan|tailnet|auto|custom>

- --gateway-auth <token|password>

- --gateway-token <token>

- --gateway-password <password>

- --remote-url <url>

- --remote-token <token>

- --tailscale <off|serve|funnel>

- --tailscale-reset-on-exit

- --install-daemon

- --no-install-daemon（ReferenceCliPage step 12: No install daemon）

- --daemon-runtime <node|bun>

- --skip-channels

- --skip-skills

- --skip-health

- --skip-ui

- --node-manager <npm|pnpm|bun> （ReferenceCliPage step 12: Node manager）

- --json

#

Interactive configuration wizard (models, channels, skills, gateway).

#

Non-interactive configuration helper (get/set/unset). Running openclaw config without

subcommand launches wizard.

Subcommands:

- config get <path>：Print a configuration value (dot/bracket path).

- config set <path> <value>：Set a value (JSON5 or raw string).

- config unset <path>：Delete a value.

#

Health check+quick fixes (configuration+gateway+legacy services).

Options:

- --no-workspace-suggestions：Disable workspace memory hints.

- --yes：Accept defaults without prompting (headless).

- --non-interactive：Skip prompts; only apply safe migrations.

- --deep：Scan system services for additional gateway installations.

#

Manage chat channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams).

Subcommands:

- channels list：Show configured channels and authentication profiles.

- channels status：Check gateway reachability and channel health (--probe runs additional checks; use openclaw health or openclaw status --deep for gateway health probing).

- Tip: When channels status can detect common misconfigurations, it prints warnings along with suggested fixes (then points you to openclaw doctor).

- channels logs：Show recent channel logs from gateway log files.

- channels add：Wizarded setup when no flags passed; flags switch to non-interactive mode.

- channels remove：Disabled by default; pass --delete to remove config entry without prompting.

- channels login：Login to a channel (e.g., WhatsApp).

- channels logout：Logout from a channel.

Common options:

- --channel <name>：Channel name.

- --account <id>：Account ID (if required).

- --name <label>：Display name.

Logs options:

Login options:

- --channel <channel>（Channel name.）

- --account <id>

- --verbose

channels logout Logout options:

- --channel <channel>（Channel name.）

- --account <id>

Logout options:

- --no-usageHide usage statistics.

- --jsonReferenceCliPage step 17: Json

Login options:

- --channel <name|all> （ReferenceCliPage step 17: Default all）

- --lines <n> （(default 200)）

- --json

See /channels for more information.

Examples:

openclaw channels add --channel telegram --account alerts --name "Alerts Bot" --token $TELEGRAM_BOT_TOKEN
openclaw channels add --channel discord --account work --name "Work Bot" --token $DISCORD_BOT_TOKEN
openclaw channels remove --channel discord --account work --delete
openclaw channels status --probe
openclaw status --deep

#

List available skills and check installation status.

Subcommands:

- skills list：List available skills.

- skills info <name>：Show detailed information about a skill.

- skills check：Check skill installation status.

Options:

- --eligible：Only show eligible skills.

- --json：Machine-readable output.

- -v、--verbose：Verbose output.

See /skills for more information.

#

Manage device pairing requests.

Subcommands:

- pairing list <channel> [--json]

- pairing approve <channel> <code> [--notify]

#

Gmail Pub/Sub hook setup + runner. See /automation/gmail-pubsub.

Subcommands:

- webhooks gmail setup（ReferenceCliPage step 20: Setup）

- webhooks gmail run （ReferenceCliPage step 20: Run）

#

Wide-area discovery DNS helper (CoreDNS + Tailscale). See /gateway/discovery.

Options:

- --apply：Install/update CoreDNS configuration (requires sudo; macOS only).

#

Unified outbound messaging+channel operations.

See: /cli/message

Subcommands:

- message send|poll|react|reactions|read|edit|delete|pin|unpin|pins|permissions|search|timeout|kick|ban

- message thread <create|list|reply>

- message emoji <list|upload>

- message sticker <send|upload>

- message role <info|add|remove>

- message channel <info|list>

- message member info

- message voice status

- message event <list|create>

Examples:

- openclaw message send --target +15555550123 --message "Hi"

- openclaw message poll --channel discord --target channel:123 --poll-question "Snack?" --poll-option Pizza --poll-option Sushi

#

Run an agent via gateway (or embedded --local).

Requirements:

- --message <text>

Options:

- --to <dest>（ReferenceCliPage step 24: To）

- --session-id <id>

- --thinking <off|minimal|low|medium|high|xhigh>ReferenceCliPage step 24: Thinking

- --verbose <on|full|off>

- --channel <whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams>

- --local

- --deliver

- --json

- --timeout <seconds>

#

Manage isolated agents (workspace+auth+routing).

##

List configured agents.

Options:

- --json

- --bindings

##

Add a new isolated agent. Runs onboarding wizard unless flags passed (or --non-interactive); --workspace required in non-interactive mode.

Options:

- --workspace <dir>

- --model <id>

- --agent-dir <dir>

- --bind <channel[:accountId]> （(repeatable)）

- --non-interactive

- --json

Binding spec uses channel[:accountId]. When accountId is omitted for WhatsApp, the default account ID will be used.

##

Delete an agent and prune its workspace+state.

Options:

- --force

- --json

#

Run ACP bridge that connects IDE to gateway.

See acp for full options and examples.

#

Show linked session health and recent recipients.

Options:

- --json

- --all(full diagnostics; read-only, pasteable)

- --deep(probe channels)

- --usage(show model provider usage/quota)

- --timeout <ms>

- --verbose

- --debug(alias for --verbose)

ReferenceCliPage step 39: Notes

- Overview includes gateway + node host service status (if available).

- ReferenceCliPage step 30: Hide usage

- ReferenceCliPage step 30: Usage tracking

#

ReferenceCliPage step 31: Oauth intro

ReferenceCliPage step 31: Surface

- /status（ReferenceCliPage step 31: Status）

- openclaw status --usage（ReferenceCliPage step 31: Usage）

- macOS menu bar (usage section in context)

ReferenceCliPage step 31: Notes

- ReferenceCliPage step 31: Data

- Providers: Anthropic, GitHub Copilot, OpenAI Codex OAuth, and Gemini CLI/Antigravity when those provider plugins are enabled.

- Usage is hidden if no matching credentials exist.

- ReferenceCliPage step 31: Usage tracking

#

ReferenceCliPage step 32: Get health

Options:

- --json

- --timeout <ms>

- --verbose

#

ReferenceCliPage step 33: List sessions

Options:

- --json

- --verbose

- --store <path>

- --active <minutes>

#

ReferenceCliPage step 35: Reset local

Options:

- --scope <config|config+creds+sessions|full>

- --yes

- --non-interactive

- --dry-run

ReferenceCliPage step 35: Notes

- ReferenceCliPage step 35: Non interactive req

#

ReferenceCliPage step 36: Uninstall gateway

Options:

- --service

- --state

- --workspace

- --app

- --all

- --yes

- --non-interactive

- --dry-run

ReferenceCliPage step 39: Notes

- ReferenceCliPage step 36: Non interactive req

#

ReferenceCliPage step 38: Run gateway

Options:

- --port <port>

- --bind <loopback|tailnet|lan|auto|custom>

- --token <token>

- --auth <token|password>

- --password <password>

- --tailscale <off|serve|funnel>

- --tailscale-reset-on-exit

- --allow-unconfigured

- --dev

- --reset（Reset dev config+credentials+sessions+workspace.）

- --force（Kill existing listener on port.）

- --verbose

- --claude-cli-logs

- --ws-log <auto|full|compact>

- --compact（ReferenceCliPage step 38: Compact alias）

- --raw-stream

- --raw-stream-path <path>

#

ReferenceCliPage step 39: Manage service

Subcommands:

- gateway status （ReferenceCliPage step 39: Status）

- gateway install（ReferenceCliPage step 39: Install）

- gateway uninstall

- gateway start

- gateway stop

- gateway restart

ReferenceCliPage step 39: Notes

- ReferenceCliPage step 39: Gateway status default

- ReferenceCliPage step 39: Gateway status support

- ReferenceCliPage step 39: Gateway status extra

- ReferenceCliPage step 39: Gateway status print

- ReferenceCliPage step 39: Gateway commands json

- ReferenceCliPage step 39: Gateway install default

- ReferenceCliPage step 39: Gateway install options

#

ReferenceCliPage step 40: Tail logs

ReferenceCliPage step 40: Notes

- ReferenceCliPage step 40: Tty

- JSON output.

ReferenceCliPage step 40: Example

openclaw logs --follow
openclaw logs --limit 200
openclaw logs --plain
openclaw logs --json
openclaw logs --no-color

#

ReferenceCliPage step 41: Cli helper

Subcommands:

- gateway call <method> [--params <json>]

- gateway health

- gateway status

- gateway probe

- gateway discover

- gateway install|uninstall|start|stop|restart

- gateway run

ReferenceCliPage step 41: Common rpc

- config.apply（ReferenceCliPage step 41: Config apply）

- config.patch（ReferenceCliPage step 41: Config patch）

- update.run（ReferenceCliPage step 41: Update run）

ReferenceCliPage step 41: Tip

ReferenceCliPage step 42: See

ReferenceCliPage step 42: Preferred auth

claude setup-token
openclaw models auth setup-token --provider anthropic
openclaw models status

#

ReferenceCliPage step 43: Alias

ReferenceCliPage step 43: Root options

- --status-json（ReferenceCliPage step 43: Status json）

- --status-plain（ReferenceCliPage step 43: Status plain）

#

ReferenceCliPage step 44: Intro

ReferenceCliPage step 44: Options

- --all

- --local

- --provider <name>

- --json

- --plain

#

System commands (gateway RPC).

ReferenceCliPage step 45: Options

- --json

- --plain

- --check（ReferenceCliPage step 45: Check）

- --probe（ReferenceCliPage step 45: Live probe）

- --probe-profile <id> （ReferenceCliPage step 45: Repeat）

- --probe-timeout <ms>

- --probe-concurrency <n>

- --probe-max-tokens <n>

ReferenceCliPage step 45: Auth overview

ReferenceCliPage step 45: Probe

#

ReferenceCliPage step 46: Set primary

#

ReferenceCliPage step 47: Set image model

#

List system presence entries (gateway RPC).

Options:

- list：ReferenceCliPage step 48: List

- ReferenceCliPage step 48: Add

- ReferenceCliPage step 48: Remove

#

Manage scheduled jobs (gateway RPC). See /automation/cron-jobs.

ReferenceCliPage step 49: Options

- list：ReferenceCliPage step 49: List

- ReferenceCliPage step 49: Add

- ReferenceCliPage step 49: Remove

- ReferenceCliPage step 49: Clear

#

node runs headless node host or manages it as a background service. See

ReferenceCliPage step 50: Options

- list: ReferenceCliPage step 50: List

- ReferenceCliPage step 50: Add

- ReferenceCliPage step 50: Remove

- ReferenceCliPage step 50: Clear

#

nodes communicates with gateway and targets paired nodes. See /nodes.

ReferenceCliPage step 51: Options

- --min-params <b>（ReferenceCliPage step 51: Min params）

- --max-age-days <days>

- --provider <name>

- --max-candidates <n>

- --timeout <ms>

- --concurrency <n>

- --no-probe

- --yes

- --no-input

- --set-default

- --set-image

- --json

#

Browser control CLI (dedicated Chrome/Brave/Edge/Chromium). See openclaw browser and browser tools.

ReferenceCliPage step 52: Options

- add：ReferenceCliPage step 52: Add

- setup-token：ReferenceCliPage step 52: Setup token

- paste-token：ReferenceCliPage step 52: Paste token

#

ReferenceCliPage step 53: Intro

ReferenceCliPage step 53: Options

- get：ReferenceCliPage step 53: Get

- set：ReferenceCliPage step 53: Set

- clear: ReferenceCliPage step 53: Clear

#

ReferenceCliPage step 55: Queue event

ReferenceCliPage step 55: Requirements

- ReferenceCliPage step 55: Text

ReferenceCliPage step 55: Options

- --mode <now|next-heartbeat>

- --json

- --url、--token、--timeout、--expect-final

#

Open terminal UI connected to gateway.

Options:

- --json

- --url、--token、--timeout、--expect-final

#

List system presence entries (gateway RPC).

Options:

- --json

- --url、--token、--timeout、--expect-final

Manage scheduled jobs (gateway RPC). See /automation/cron-jobs.

Subcommands:

- cron status [--json]

- ''cron list [--all] [--json]''（Default table output；For raw data ''--json'' touse）

- ''cron add'' (alias: ''create''; requires ''--name'' and one of ''--at'' | ''--every'' | ''--cron'', and payload from ''--system-event'' | ''--message'')

- ''cron edit <id>''（Patch fields）

- ''cron rm <id>''（alias：''remove''、''delete''）

- cron enable <id>

- cron disable <id>

- cron runs --id <id> [--limit <n>]

- cron run <id> [--force]

All cron commands accept --url, --token, --timeout, --expect-final.

node runs headless node host or manages it as a background service. See

openclaw node。。

Subcommands:

- node run --host <gateway-host> --port 18789

- node status

- node install [--host <gateway-host>] [--port <port>] [--tls] [--tls-fingerprint <sha256>] [--node-id <id>] [--display-name <name>] [--runtime <node|bun>] [--force]

- node uninstall

- node stop

- node restart

nodes communicates with gateway and targets paired nodes. See /nodes.

Common options:

- --url、--token、--timeout、--json

Subcommands:

- nodes status [--connected] [--last-connected <duration>]

- nodes describe --node <id|name|ip>

- nodes list [--connected] [--last-connected <duration>]

- nodes pending

- nodes approve <requestId>

- nodes reject <requestId>

- nodes rename --node <id|name|ip> --name <displayName>

- nodes invoke --node <id|name|ip> --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]

- nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>ReferenceCliPage step 60: Mac node

- nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]ReferenceCliPage step 60: Mac only

Camera:

- nodes camera list --node <id|name|ip>

- 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>]

- nodes camera clip --node <id|name|ip> [--facing front|back] [--device-id <id>] [--duration <ms|10s|1m>] [--no-audio] [--invoke-timeout <ms>]

Canvas+Screen:

- nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]

- nodes canvas present --node <id|name|ip> [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>] [--invoke-timeout <ms>]

- nodes canvas hide --node <id|name|ip> [--invoke-timeout <ms>]

- nodes canvas navigate <url> --node <id|name|ip> [--invoke-timeout <ms>]

- nodes canvas eval [<js>] --node <id|name|ip> [--js <code>] [--invoke-timeout <ms>]

- nodes canvas a2ui push --node <id|name|ip> (--jsonl <path> | --text <text>) [--invoke-timeout <ms>]

- nodes canvas a2ui reset --node <id|name|ip> [--invoke-timeout <ms>]

- nodes screen record --node <id|name|ip> [--screen <index>] [--duration <ms|10s>] [--fps <n>] [--no-audio] [--out <path>] [--invoke-timeout <ms>]

Location:

- nodes location get --node <id|name|ip> [--max-age <ms>] [--accuracy <coarse|balanced|precise>] [--location-timeout <ms>] [--invoke-timeout <ms>]

Browser control CLI (dedicated Chrome/Brave/Edge/Chromium). See openclaw browser and browser tools.

Common options:

- --url、--token、--timeout、--json

- --browser-profile <name>

Manage:

- browser status

- browser start

- browser stop

- browser reset-profile

- browser tabs

- browser open <url>

- browser focus <targetId>

- browser close [targetId]

- browser profiles

- browser create-profile --name <name> [--color <hex>] [--cdp-url <url>]

- browser delete-profile --name <name>

Inspect:

- browser screenshot [targetId] [--full-page] [--ref <ref>] [--element <selector>] [--type png|jpeg]

- browser snapshot [--format aria|ai] [--target-id <id>] [--limit <n>] [--interactive] [--compact] [--depth <n>] [--selector <sel>] [--out <path>]

Actions:

- browser navigate <url> [--target-id <id>]

- browser resize <width> <height> [--target-id <id>]

- browser click <ref> [--double] [--button <left|right|middle>] [--modifiers <csv>] [--target-id <id>]

- browser type <ref> <text> [--submit] [--slowly] [--target-id <id>]

- browser press <key> [--target-id <id>]

- browser hover <ref> [--target-id <id>]

- browser drag <startRef> <endRef> [--target-id <id>]

- browser select <ref> <values...> [--target-id <id>]

- browser upload <paths...> [--ref <ref>] [--input-ref <ref>] [--element <selector>] [--target-id <id>] [--timeout-ms <ms>]

- browser fill [--fields <json>] [--fields-file <path>] [--target-id <id>]

- browser dialog --accept|--dismiss [--prompt <text>] [--target-id <id>] [--timeout-ms <ms>]

- browser wait [--time <ms>] [--text <value>] [--text-gone <value>] [--target-id <id>]

- browser evaluate --fn <code> [--ref <ref>] [--target-id <id>]

- browser console [--level <error|warn|info>] [--target-id <id>]

- browser pdf [--target-id <id>]

#

Search live documentation index.

#

Open terminal UI connected to gateway.

Options:

- --url <url>

- --token <token>

- --password <password>

- --session <key>

- --deliver

- --thinking <level>

- --message <text>

- ''--timeout-ms <ms>''（Default is ''agents.defaults.timeoutSeconds''）

- --history-limit <n>