> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every openclaw CLI command, subcommand, key flags, and environment variables.

# CLI reference

The `openclaw` CLI is the primary interface for managing the gateway, channels, agents, models, and configuration. Install it globally via npm or pnpm - see [Getting started](/admin/getting-started).

The canonical binary is `wednesdayai`; `openclaw` remains supported as a legacy alias.

```bash theme={"dark"}
openclaw --version            # show installed version (-V also works)
openclaw --help               # list all top-level commands
openclaw <command> --help     # help for a specific command
```

<Note>
  This page summarises the command surface. Flags evolve between releases - when a flag is not listed here, run `openclaw <command> --help` for the authoritative set on your install.
</Note>

## Global flags

These apply to every command. Per-command flags such as `--json`, `--verbose`, and `--log-level` are documented under each command, not here.

| Flag                    | Effect                                                                          |
| ----------------------- | ------------------------------------------------------------------------------- |
| `--dev`                 | Isolate state under `~/.openclaw-dev` and shift default ports (gateway `19001`) |
| `--profile <name>`      | Isolate state under `~/.openclaw-<name>` for a named instance                   |
| `--no-color`            | Disable ANSI colours (`NO_COLOR=1` is also respected)                           |
| `--update`              | Shorthand for `openclaw update` (source installs only)                          |
| `-V`, `--version`, `-v` | Print the version and exit                                                      |

## Output styling

* ANSI colours and progress indicators only render in TTY sessions.
* OSC-8 hyperlinks render as clickable links in supported terminals; otherwise we fall back to plain URLs.
* `--json` (and `--plain` where supported) disables styling for clean machine output.
* Long-running commands show an OSC 9;4 progress indicator where supported.

***

## Setup and onboarding

### `openclaw setup`

Initialise config and workspace. Auto-runs the onboarding wizard when any wizard flag is present.

```bash theme={"dark"}
openclaw setup --workspace ~/.openclaw/workspace
```

Key flags: `--workspace <dir>`, `--wizard`, `--non-interactive`, `--mode <local\|remote>`, `--remote-url <url>`, `--remote-token <token>`.

### `openclaw onboard`

Interactive wizard to set up gateway, workspace, model auth, channels, and skills.

```bash theme={"dark"}
openclaw onboard                         # full onboarding wizard
openclaw onboard --install-daemon        # also install the gateway service
openclaw onboard --flow quickstart       # quickstart | advanced | manual
```

Key flags: `--workspace <dir>`, `--reset`, `--reset-scope <config\|config+creds+sessions\|full>`, `--non-interactive`, `--mode <local\|remote>`, `--flow <quickstart\|advanced\|manual>`, `--auth-choice <id>`, `--gateway-port <port>`, `--gateway-bind <loopback\|lan\|tailnet\|auto\|custom>`, `--gateway-auth <token\|password>`, `--tailscale <off\|serve\|funnel>`, `--install-daemon` / `--no-install-daemon`, `--node-manager <npm\|pnpm\|bun>`, `--json`. Many provider-specific key flags exist (for example `--anthropic-api-key`, `--openai-api-key`) - see `openclaw onboard --help`.

### `openclaw configure`

Interactive configuration wizard (models, channels, skills, gateway). Re-runs onboarding-style prompts against an existing config.

Key flags: `--section <section>` — run only the specified wizard section(s) — can be passed multiple times to run several sections in sequence. Valid values: `workspace | model | web | gateway | daemon | channels | skills | health`.

### `openclaw completion`

Print a shell completion script for your shell.

```bash theme={"dark"}
openclaw completion
```

### `openclaw reset`

Reset local config/state while keeping the CLI installed.

```bash theme={"dark"}
openclaw reset --scope config+creds+sessions --yes
```

Key flags: `--scope <config\|config+creds+sessions\|full>`, `--yes`, `--non-interactive`, `--dry-run`. Non-interactive use requires both `--scope` and `--yes`.

### `openclaw uninstall`

Remove the gateway service and local data (the CLI itself remains).

```bash theme={"dark"}
openclaw uninstall --all --yes
```

Key flags: `--service`, `--state`, `--workspace`, `--app`, `--all`, `--yes`, `--non-interactive`, `--dry-run`.

### `openclaw update`

Update WednesdayAI to a newer version (source/npm installs).

```bash theme={"dark"}
openclaw update                  # update to latest on the current channel
openclaw update --dry-run        # preview without applying
openclaw update --channel beta   # stable | beta | dev
openclaw update --tag <version>  # install a specific version
openclaw update --no-restart     # skip gateway service restart after successful update (useful for automation)
openclaw update --yes            # non-interactive mode, accepts downgrade prompts
openclaw update --json           # output machine-readable UpdateRunResult JSON
openclaw update --timeout 600    # per-step timeout in seconds (default: 1200)
openclaw update status           # show current version, update channel, and whether an update is available
openclaw update wizard           # step-by-step wizard to configure update settings (channel, schedule, notifications)
```

***

## Gateway

### `openclaw gateway`

Run the WebSocket gateway in the foreground, or manage it as a system service. Subcommands cover the service lifecycle and RPC helpers.

```bash theme={"dark"}
openclaw gateway run                # run in foreground (Ctrl-C to stop)
openclaw gateway start              # start the installed service
openclaw gateway stop
openclaw gateway restart
openclaw gateway install            # install as systemd/launchd/schtasks service
openclaw gateway uninstall
openclaw gateway status             # probe the gateway RPC (default)
openclaw gateway status --deep --json
openclaw gateway usage-cost         # rolling usage/cost summary from session logs
openclaw gateway health             # health snapshot via RPC
openclaw gateway probe              # connectivity probe
openclaw gateway discover           # discover gateways on the network
openclaw gateway call <method> --params '<json>'   # invoke any RPC method
```

Foreground run flags: `--port <port>`, `--bind <loopback\|tailnet\|lan\|auto\|custom>`, `--token <token>`, `--auth <none\|token\|password\|trusted-proxy>`, `--password <password>`, `--tailscale <off\|serve\|funnel>`, `--tailscale-reset-on-exit` (reset Tailscale serve/funnel configuration on shutdown), `--allow-unconfigured`, `--force`, `--verbose`, `--ws-log <auto\|full\|compact>`, `--claude-cli-logs` (enable Claude CLI log output), `--raw-stream` (write raw stream to stdout), `--raw-stream-path <path>` (write raw stream to the specified file path).

RPC subcommands (`call`, `health`, `status`, `probe`, `discover`) accept `--url`, `--token`, `--password`, `--timeout`. `call`, `health`, and `usage-cost` also accept `--expect-final`.

`gateway status` additional flags: `--no-probe` (skip RPC probe, show service status only).

`gateway probe` additional flags: `--ssh <user@host[:port]>` (route probe through SSH tunnel), `--ssh-identity <path>` (SSH identity file path), `--ssh-auto` (auto-derive SSH target via Bonjour discovery).

`gateway usage-cost` — Fetch rolling usage/cost summary from session logs. Flags: `--days <days>` (number of days to include), `--url <url>`, `--token <token>`, `--json`, `--expect-final` (wait for a final response before returning).

<Warning>
  When you pass `--url`, the CLI does **not** auto-apply config or environment credentials. Include `--token` or `--password` explicitly; missing credentials is an error.
</Warning>

The gateway runs on port `18789` by default. Common RPC methods for `gateway call`: `config.apply`, `config.patch`, `update.run`. See the [API reference](/reference/api) for the full method surface.

**Systemd (Linux):**

```bash theme={"dark"}
systemctl --user start|stop|restart|status openclaw-gateway
journalctl --user -u openclaw-gateway -f
```

### `openclaw daemon`

Legacy alias namespace for the gateway service commands (`status`, `install`, `uninstall`, `start`, `stop`, `restart`). Prefer `openclaw gateway <subcommand>`.

### `openclaw status`

Local and channel diagnostics summary.

```bash theme={"dark"}
openclaw status              # compact: gateway, channels, sessions
openclaw status --all        # full local diagnosis (safe to paste)
openclaw status --deep       # also probe the running gateway per-channel
openclaw status --usage      # include provider usage/quota
```

Key flags: `--json`, `--all`, `--deep`, `--usage`, `--timeout <ms>`, `--verbose`.

### `openclaw health`

Fetch a health snapshot from the running gateway via RPC. Exits non-zero if unreachable or any probe fails.

```bash theme={"dark"}
openclaw health --json --timeout 5000
```

Key flags: `--json`, `--timeout <ms>`, `--verbose`.

### `openclaw doctor`

Health checks and guided repairs (config, model auth, channel connectivity, service health, port collisions, permissions, legacy migrations).

```bash theme={"dark"}
openclaw doctor              # interactive: prompts before applying fixes
openclaw doctor --yes        # accept defaults without prompting
openclaw doctor --deep       # scan for extra/stale gateway installs
```

Key flags: `--yes`, `--non-interactive` (safe migrations only), `--deep`, `--no-workspace-suggestions`, `--fix` (auto-remediate detected issues where safe to do so), `--json` (output findings as JSON for scripting), `--check <name>` (run only the named check, e.g. `--check ollama`, `--check disk`).

### `openclaw logs`

Tail the gateway log file via RPC.

```bash theme={"dark"}
openclaw logs --follow       # live tail (pretty in a TTY)
openclaw logs --limit 200
openclaw logs --json         # line-delimited JSON
openclaw logs --plain
openclaw logs --no-color
openclaw logs --local-time   # display timestamps in local timezone (default: UTC)
```

### `openclaw dashboard`

Open the control panel in your browser (default `http://localhost:18789/`).

```bash theme={"dark"}
openclaw dashboard
```

### `openclaw tui`

Open the terminal UI connected to the gateway.

```bash theme={"dark"}
openclaw tui --session main --message "status?"
```

Key flags: `--url <url>`, `--token <token>`, `--password <password>`, `--session <key>`, `--deliver`, `--thinking <level>`, `--message <text>`, `--timeout-ms <ms>`, `--history-limit <n>`.

### `openclaw qr`

Display a QR code for mobile pairing.

```bash theme={"dark"}
openclaw qr
openclaw qr --channel whatsapp
```

***

## Authentication, models, and providers

### `openclaw models`

Manage AI model credentials and selection. `openclaw models` with no subcommand is an alias for `models status`.

```bash theme={"dark"}
openclaw models status                   # auth overview + OAuth expiry
openclaw models status --check           # exit 1=expired/missing, 2=expiring
openclaw models status --probe           # probe configured provider auth (validates credentials live — does not send a completion)
openclaw models status --probe --probe-timeout 15000   # timeout for probe request (default: 10000 ms)
openclaw models list --all
openclaw models set anthropic/claude-sonnet-4-5
openclaw models set-image openai/gpt-image-1
openclaw models auth setup-token --provider anthropic
openclaw models auth paste-token --provider anthropic
openclaw models auth order set --provider anthropic anthropic:work
```

Subcommands: `list`, `status`, `set <model>`, `set-image <model>`, `aliases list\|add\|rm`, `fallbacks list\|add\|rm\|clear`, `image-fallbacks list\|add\|rm\|clear`, `scan`, `auth add\|setup-token\|paste-token`, `auth order get\|set\|clear`.

`models status` key flags: `--check`, `--probe` (validates credentials live — does not send a completion), `--probe-timeout <ms>` (probe timeout, default `10000`), `--probe-provider <name>` (probe only the named provider), `--probe-profile <id>` (filter to specific profile(s); repeatable or comma-separated), `--probe-concurrency <n>` (number of concurrent probe requests), `--probe-max-tokens <n>` (max tokens for probe completion request), `--plain` (plain line output, no table formatting), `--agent <id>` (inspect a specific configured agent's model and auth state).

`models set` writes `agents.defaults.model.primary`; `models set-image` writes `agents.defaults.imageModel.primary`.

### `openclaw models auth`

Authenticate with model providers interactively.

```bash theme={"dark"}
openclaw models auth login --provider anthropic        # interactive OAuth flow for the named provider
openclaw models auth login-github-copilot              # GitHub Copilot device-flow OAuth; sets providers.copilot.token
```

`auth login` flags: `--provider <name>` (required — specifies the provider to authenticate with).

***

## Channels and pairing

### `openclaw channels`

Manage chat channel accounts.

```bash theme={"dark"}
openclaw channels list                   # configured channels and auth profiles
openclaw channels list --no-usage        # skip model provider usage/quota snapshots
openclaw channels status --probe         # connectivity + live probe
openclaw channels add --channel telegram --account alerts --name "Alerts Bot" --token $TELEGRAM_BOT_TOKEN
openclaw channels remove --channel discord --account work --delete
openclaw channels login --channel whatsapp --account work    # WhatsApp Web only
openclaw channels logout --channel whatsapp
openclaw channels logs --channel telegram --lines 200
openclaw channels capabilities --channel whatsapp             # list capabilities: reactions, threads, voice, files
openclaw channels resolve alice bob --channel telegram [--kind auto]   # resolve names/IDs to OpenClaw user records
```

Subcommands: `list`, `status`, `logs`, `add`, `remove`, `login`, `logout`, `capabilities --channel <name>`, `resolve <entries...> --channel <name> [--kind <auto|user|group>]`. Common flags: `--channel <name>`, `--account <id>`, `--name <label>`, `--json`. `--channel` accepts `whatsapp\|telegram\|discord\|googlechat\|slack\|mattermost\|signal\|imessage\|msteams\|irc` (plus installed channel extensions). `channels add` runs a wizard when no flags are passed; flags switch to non-interactive mode.

### `openclaw pairing`

Approve DM pairing requests across channels.

```bash theme={"dark"}
openclaw pairing list                            # all pending requests
openclaw pairing list whatsapp --json
openclaw pairing approve whatsapp <CODE> --notify
```

Subcommands: `list [channel]`, `approve <channel> <code>`. Flags: `--channel <channel>`, `--account <id>`, `--json`, `--notify` (on `approve`).

<Warning>
  There is no `pairing deny` and no `pairing list --all`. To refuse a sender, leave the request unapproved or tighten `channels.<channel>.dmPolicy`/`allowFrom`.
</Warning>

### `openclaw devices`

Manage gateway device-pairing entries and per-role device tokens.

```bash theme={"dark"}
openclaw devices list --json
openclaw devices approve --latest
openclaw devices reject <requestId>
openclaw devices remove <deviceId>
openclaw devices clear --yes
openclaw devices rotate --device <id> --role <role>
openclaw devices revoke --device <id> --role <role>
```

Subcommands: `list`, `approve [requestId] [--latest]`, `reject <requestId>`, `remove <deviceId>`, `clear --yes [--pending]`, `rotate --device <id> --role <role> [--scope <scope...>]`, `revoke --device <id> --role <role>`.

***

## Configuration

### `openclaw config`

Read and write gateway configuration. Running `openclaw config` with no subcommand launches the wizard.

```bash theme={"dark"}
openclaw config get                                   # print full config
openclaw config get agents.defaults.model.primary
openclaw config set agents.defaults.model.primary '"anthropic/claude-sonnet-4-5"'
openclaw config unset channels.telegram.dmPolicy
openclaw config file                                  # print active config path
openclaw config validate --json                       # validate against schema
```

Subcommands: `get <path>`, `set <path> <value>` (value is JSON5 or a raw string), `unset <path>`, `file`, `validate`.

### `openclaw secrets`

Manage SecretRef resolution and provider mappings.

```bash theme={"dark"}
openclaw secrets reload                 # re-resolve refs, atomically swap runtime snapshot
openclaw secrets audit                  # scan for plaintext residues / unresolved refs
openclaw secrets configure              # interactive provider + SecretRef setup
openclaw secrets apply --from plan.json --dry-run
```

Subcommands: `reload`, `audit`, `configure`, `apply --from <plan.json>` (`migrate` also exists as an alias surface).

### `openclaw directory`

Look up contact and group IDs for supported chat channels.

```bash theme={"dark"}
openclaw directory self                          # show your own user ID across connected channels
openclaw directory peers list                    # list all known contacts
openclaw directory groups list                   # list all known groups
openclaw directory groups members <group-id>     # list members of a group
```

### `openclaw dns`

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

```bash theme={"dark"}
openclaw dns setup --apply        # install/update CoreDNS config (sudo; macOS only)
```

See [/gateway/discovery](/gateway/discovery).

***

## Agents, sessions, and ACP

### `openclaw agent`

Run one agent turn via the gateway (or `--local` embedded).

```bash theme={"dark"}
openclaw agent --message "Summarise today" --to whatsapp:+15555550123 --deliver
```

Required: `--message <text>`. Key flags: `--to <dest>`, `--session-id <id>`, `--thinking <off\|minimal\|low\|medium\|high>`, `--verbose <on\|off>`, `--channel <name>`, `--local`, `--deliver`, `--json`, `--timeout <seconds>`.

#### `openclaw agent nudge`

Interrupt an active agent session mid-turn with a nudge message.

```bash theme={"dark"}
openclaw agent nudge "stop and summarise what you have so far"
openclaw agent nudge "abort" --agent work
openclaw agent nudge "checkpoint" --all
```

Flags: `--agent <id>` (target a specific agent by id; defaults to the current active agent), `--all` (broadcast the nudge to all active agents).

### `openclaw agents`

Manage isolated agents (workspaces + auth + routing). There is no `agents status`.

```bash theme={"dark"}
openclaw agents list --bindings
openclaw agents add work --workspace ~/.openclaw/workspace-work --bind whatsapp:biz
openclaw agents bindings --agent work
openclaw agents bind --agent work --bind discord:guild
openclaw agents unbind --agent work --bind discord:guild
openclaw agents delete work --force
openclaw agents set-identity work "Wednesday"   # set display name/persona; persists in the agent's config file
```

Subcommands: `list`, `add [name]`, `bindings`, `bind`, `unbind`, `delete <id>`, `set-identity <agent-id> <name>`. Binding specs use `channel[:accountId]`. `--workspace` is required for non-interactive `add`.

### `openclaw sessions`

List stored conversation sessions.

```bash theme={"dark"}
openclaw sessions --active 60 --json
openclaw sessions cleanup --dry-run                   # preview what would be cleaned up without making changes
openclaw sessions cleanup --enforce                   # enforce storage caps and prune over-budget sessions
openclaw sessions backfill-user-ids                   # one-time migration: back-fill userId in legacy records
```

Key flags: `--json`, `--verbose`, `--store <path>`, `--active <minutes>`, `--agent <id>` (inspect a specific agent's store), `--all-agents` (aggregate across all agents).

`sessions cleanup` — Enforce session-store storage budgets and caps. Prunes sessions exceeding configured limits.

| Flag                 | Description                                                                            |
| -------------------- | -------------------------------------------------------------------------------------- |
| `--dry-run`          | Preview what would be cleaned up without making changes                                |
| `--enforce`          | Enforce storage caps and prune over-budget sessions                                    |
| `--all-agents`       | Run cleanup across all agents (not just current)                                       |
| `--agent <id>`       | Target a specific agent                                                                |
| `--fix-missing`      | Remove store entries whose transcript files are missing (bypasses age/count retention) |
| `--active-key <key>` | Treat sessions with this key as active (skip pruning)                                  |

`sessions backfill-user-ids` is safe on live data and idempotent — re-running it is a no-op for records already migrated. Flags: `--batch-size <n>` (rows per batch, default `500`), `--dry-run` (preview without writing).

### `openclaw session-storage`

Manage the session backing store.

```bash theme={"dark"}
openclaw session-storage init                  # initialize the session storage schema
openclaw session-storage validate              # validate schema integrity
openclaw session-storage cutover               # cut over to new storage schema
openclaw session-storage drop-legacy-archive   # remove legacy archive after successful cutover
```

Subcommands: `init`, `validate`, `cutover`, `drop-legacy-archive`. Common flags: `--json`.

### `openclaw acp`

Run the ACP bridge that connects IDEs (Agent Client Protocol) to the gateway. See [`acp`](/cli/acp) for options.

***

## Messaging

### `openclaw message`

Unified outbound messaging and channel actions.

```bash theme={"dark"}
openclaw message send --target +15555550123 --message "Hello"
openclaw message send --channel discord --target channel:123 --message "Test"
openclaw message poll --channel discord --target channel:123 \
  --poll-question "Snack?" --poll-option Pizza --poll-option Sushi
```

```bash theme={"dark"}
openclaw message broadcast "Gateway maintenance at 22:00 UTC"
openclaw message broadcast "Scheduled downtime" --channel telegram
openclaw message broadcast "Test run" --dry-run
```

Subcommands: `send`, `poll`, `react`, `reactions`, `read`, `edit`, `delete`, `pin`, `unpin`, `pins`, `permissions`, `search`, `timeout`, `kick`, `ban`, `thread <create\|list\|reply>`, `emoji <list\|upload>`, `sticker <send\|upload>`, `role <info\|add\|rm>`, `channel <info\|list>`, `member info`, `voice status`, `event <list\|create>`, `broadcast <message>`. See [/cli/message](/cli/message) for per-subcommand flags.

`message broadcast` flags: `--channel <name>` (restrict broadcast to one channel; omit to send across all active channels), `--dry-run` (print targets without sending).

***

## Skills and hooks

### `openclaw skills`

List and inspect available skills plus readiness info. Skills are **read-only** from the CLI.

```bash theme={"dark"}
openclaw skills list --eligible
openclaw skills info <name>
openclaw skills check
```

Subcommands: `list`, `info <name>`, `check`. Flags: `--eligible`, `--json`, `--verbose`.

<Note>
  There is no `skills enable`, `skills disable`, or `skills install`. Use `npx clawhub` to search, install, and sync skills; control which bundled skills load via `skills.allowBundled` and `skills.load.extraDirs` in config.
</Note>

### `openclaw hooks`

Manage gateway hooks.

```bash theme={"dark"}
openclaw hooks list                      # all hooks with enabled/disabled status
openclaw hooks info <name>
openclaw hooks check                     # verify enabled hooks can load
openclaw hooks enable <name>
openclaw hooks disable <name>
openclaw hooks install ./path/to/hook
openclaw hooks update [id]               # update an installed hook
```

Subcommands: `list`, `info`, `check`, `enable`, `disable`, `install`, `update [id]`. `update` flags: `--all` (update all tracked hooks), `--dry-run`. See the [Hooks catalogue](/reference/hooks-catalogue).

***

## Plugins

### `openclaw plugins`

Manage extensions and their config. Most plugin changes require a gateway restart.

```bash theme={"dark"}
openclaw plugins list --json
openclaw plugins list --verbose          # show detailed entries including config and state
openclaw plugins info <id>
openclaw plugins install <path|.tgz|npm-spec>
openclaw plugins install <path> --link   # link local path instead of copying
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins status                  # show plugin status (enabled/disabled/error) for all installed plugins
openclaw plugins uninstall <id>          # remove an installed plugin
openclaw plugins update [id]             # update a plugin (or all plugins if no id given)
openclaw plugins doctor                  # report plugin load errors
```

Subcommands: `list`, `info <id>`, `install`, `enable <id>`, `disable <id>`, `doctor`, `status`, `uninstall <id>`, `update [id]`.

`plugins install` flags: `-l, --link` (link local path instead of copying), `--pin` (pin to exact version), `--force` (overwrite existing install).

`plugins list` flags: `--json`, `--verbose` (show detailed entries including config and state).

`plugins uninstall` flags: `--keep-files` (preserve plugin files), `--force` (skip confirmation), `--dry-run` (preview without removing).

***

## Memory

### `openclaw memory`

Vector search over `MEMORY.md` and `memory/*.md`.

```bash theme={"dark"}
openclaw memory status                   # index stats
openclaw memory index                    # reindex memory files
openclaw memory search "deployment notes"
```

Subcommands: `status`, `index`, `search "<query>"` (`--query` also accepted).

***

## Nodes and node host

### `openclaw nodes`

Target paired nodes (mobile/desktop) via the gateway.

```bash theme={"dark"}
openclaw nodes list --connected
openclaw nodes status
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes describe --node <id|name|ip>
openclaw nodes rename --node <id> --name "Studio Mac"
openclaw nodes run --node <id> -- ls -la
openclaw nodes camera snap --node <id> --facing front
openclaw nodes screen record --node <id> --duration 10s
openclaw nodes notify --node <id> --title "Hi" --body "Ping"   # mac only
```

Subcommands include: `status`, `list`, `pending`, `approve`, `reject`, `describe`, `rename`, `invoke`, `run`, `notify`, `camera <list\|snap\|clip>`, `canvas <snapshot\|present\|hide\|navigate\|eval\|a2ui>`, `screen record`, `location get`. Common flags: `--url`, `--token`, `--timeout`, `--json`. See [/nodes](/nodes).

### `openclaw node`

Run a headless node host, or manage it as a background service.

```bash theme={"dark"}
openclaw node run --host gateway-host --port 18789
openclaw node install --host gateway-host --tls --runtime node
openclaw node status
openclaw node start|stop|restart|uninstall
```

Subcommands: `run`, `status`, `install`, `uninstall`, `start`, `stop`, `restart`. See [`openclaw node`](/cli/node).

***

## Approvals and sandbox

### `openclaw approvals`

Manage exec-approval policy and allowlists.

```bash theme={"dark"}
openclaw approvals get
openclaw approvals set <policy>
openclaw approvals allowlist add <pattern>
openclaw approvals allowlist remove <pattern>
```

Subcommands: `get`, `set`, `allowlist add\|remove`.

### `openclaw sandbox`

Inspect and manage agent sandboxes.

```bash theme={"dark"}
openclaw sandbox list
openclaw sandbox explain               # explain effective sandbox policy
openclaw sandbox recreate
```

Subcommands: `list`, `recreate`, `explain`.

***

## Browser

### `openclaw browser`

Control a dedicated Chrome/Brave/Edge/Chromium instance. Common flags: `--url`, `--token`, `--timeout`, `--json`, `--browser-profile <name>`.

```bash theme={"dark"}
openclaw browser status
openclaw browser start
openclaw browser open https://example.com
openclaw browser navigate https://example.com --target-id <id>
openclaw browser screenshot --full-page
openclaw browser snapshot --format ai
openclaw browser click <ref>
openclaw browser type <ref> "hello" --submit
openclaw browser pdf
```

Manage: `status`, `start`, `stop`, `reset-profile`, `tabs`, `open <url>`, `focus <targetId>`, `close [targetId]`, `profiles`, `create-profile`, `delete-profile`.
Inspect: `screenshot`, `snapshot`.
Actions: `navigate`, `resize`, `click`, `type`, `press`, `hover`, `drag`, `select`, `upload`, `fill`, `dialog`, `wait`, `evaluate`, `console`, `pdf`. See [`openclaw browser`](/cli/browser) and the [Browser tool](/tools/browser).

***

## System

### `openclaw system`

Enqueue system events and manage heartbeat/presence (gateway RPC).

```bash theme={"dark"}
openclaw system event --text "Deploy finished" --mode next-heartbeat
openclaw system heartbeat last
openclaw system heartbeat enable
openclaw system presence
```

Subcommands: `event` (`--text` required; `--mode <now\|next-heartbeat>`), `heartbeat last\|enable\|disable`, `presence`. All accept `--json`, `--url`, `--token`, `--timeout`, `--expect-final`.

***

## Cron

### `openclaw cron`

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

```bash theme={"dark"}
openclaw cron list --all
openclaw cron status
openclaw cron add --name "Morning briefing" --cron "0 9 * * *" --message "Daily summary"
openclaw cron edit <id>
openclaw cron rm <id>
openclaw cron enable <id>
openclaw cron disable <id>
openclaw cron run <id> --due
openclaw cron runs --id <id> --limit 20
```

Subcommands: `status`, `list`, `add` (alias `create`), `edit <id>`, `rm <id>` (aliases `remove`, `delete`), `enable <id>`, `disable <id>`, `runs --id <id>`, `run <id>`.

`cron add` delivery and lifecycle flags:

| Flag               | Description                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| `--announce`       | Deliver cron output to chat (default for isolated jobs)                  |
| `--no-deliver`     | Keep output internal, do not deliver to chat                             |
| `--deliver`        | Deprecated alias for `--announce`                                        |
| `--keep-after-run` | Keep one-shot job after it runs successfully (default: delete after run) |

<Warning>
  Use `--cron` for cron expressions (not `--schedule`). `cron add` requires `--name` and exactly one schedule of `--at` / `--every` / `--cron`, plus exactly one payload of `--message` / `--system-event`. Use `cron rm` (canonical) for deletion and `cron runs --id <id>` (not `logs`) for run history.
</Warning>

***

## Security

### `openclaw security`

Audit config and local state for common security foot-guns.

```bash theme={"dark"}
openclaw security audit                  # flag misconfigurations
openclaw security audit --deep           # best-effort live gateway probe
openclaw security audit --fix            # tighten safe defaults and chmod state
```

Subcommand: `audit`. Flags: `--deep`, `--fix`, `--json`.

***

## Webhooks and docs

### `openclaw webhooks`

Inbound webhook helpers.

```bash theme={"dark"}
openclaw webhooks gmail setup --account you@example.com
openclaw webhooks gmail run
```

Subcommands: `gmail setup`, `gmail run`. See [/automation/gmail-pubsub](/automation/gmail-pubsub).

### `openclaw docs`

Search the live docs index.

```bash theme={"dark"}
openclaw docs "remote access"
```

***

## Legacy and plugin commands

### `openclaw clawbot`

Legacy alias namespace (for example `openclaw clawbot qr`). Prefer the modern equivalents.

### `openclaw voicecall`

Provided by the voice-call plugin when installed. Plugins can register additional top-level commands.

***

## Environment variables

| Variable                        | Effect                                                                                   |
| ------------------------------- | ---------------------------------------------------------------------------------------- |
| `OPENCLAW_GATEWAY_TOKEN`        | Gateway auth token                                                                       |
| `OPENCLAW_GATEWAY_PASSWORD`     | Gateway auth password                                                                    |
| `OPENCLAW_GATEWAY_PORT`         | Override gateway port                                                                    |
| `OPENCLAW_CONFIG_PATH`          | Absolute path to config file                                                             |
| `OPENCLAW_HOME`                 | Override home directory for internal paths                                               |
| `OPENCLAW_STATE_DIR`            | Override state directory                                                                 |
| `OPENCLAW_LOG_LEVEL`            | Log level override (`error`, `warn`, `info`, `debug`, `trace`)                           |
| `OPENCLAW_LOAD_SHELL_ENV=1`     | Import missing vars from login shell                                                     |
| `NO_COLOR=1`                    | Disable ANSI colours                                                                     |
| `ANTHROPIC_API_KEY`             | Anthropic API key                                                                        |
| `OPENAI_API_KEY`                | OpenAI API key                                                                           |
| `GOOGLE_API_KEY`                | Google AI API key                                                                        |
| `GEMINI_API_KEY`                | Google Gemini API key (first-class provider key, not just an alias for `GOOGLE_API_KEY`) |
| `OPENCLAW_SHELL_ENV_TIMEOUT_MS` | Timeout in ms for shell environment import (default: `15000`)                            |
| `TELEGRAM_BOT_TOKEN`            | Telegram bot token (default account)                                                     |
| `DISCORD_BOT_TOKEN`             | Discord bot token (default account)                                                      |
| `SLACK_BOT_TOKEN`               | Slack bot token (default account)                                                        |
| `SLACK_APP_TOKEN`               | Slack app token for Socket Mode (default account)                                        |

## Related

* [Gateway configuration reference](/reference/config)
* [Gateway API reference](/reference/api)
* [Hooks catalogue](/reference/hooks-catalogue)
* [Health checks](/admin/gateway/health-checks)
* [Troubleshooting](/admin/troubleshooting)