Getting Started with the OpenClaw CLI

Command pages

You can find the specific details for every command in these dedicated pages. It’s the best way to see what each tool does:

• setup
• onboard
• configure
• config
• completion
• doctor
• dashboard
• backup
• reset
• uninstall
• update
• message
• agent
• agents
• acp
• mcp
• status
• health
• sessions
• gateway
• logs
• system
• models
• infer
• memory
• wiki
• directory
• nodes
• devices
• node
• approvals
• sandbox
• tui
• browser
• cron
• tasks
• flows
• dns
• docs
• hooks
• webhooks
• pairing
• qr
• plugins (plugin commands)
• channels
• security
• secrets
• skills
• daemon (legacy alias for gateway service commands)
• clawbot (legacy alias namespace)
• voicecall (plugin; if installed)

Global flags

These flags work across the board. You can use them to change how the CLI behaves globally:

• --dev: isolate state under ~/.openclaw-dev and shift default ports.
• --profile <name>: isolate state under ~/.openclaw-<name>.
• --container <name>: target

Command tree

You’ll find that OpenClaw has a deep command structure designed to handle everything from basic setup to complex node and browser automation. Here is the full map of the commands you can use:

openclaw [--dev] [--profile <name>] <command>
  setup
  onboard
  configure
  config
    get
    set
    unset
    file
    schema
    validate
  completion
  doctor
  dashboard
  backup
    create
    verify
  security
    audit
  secrets
    reload
    audit
    configure
    apply
  reset
  uninstall
  update
    wizard
    status
  channels
    list
    status
    capabilities
    resolve
    logs
    add
    remove
    login
    logout
  directory
    self
    peers list
    groups list|members
  skills
    search
    install
    update
    list
    info
    check
  plugins
    list
    inspect
    install
    uninstall
    update
    enable
    disable
    doctor
    marketplace list
  memory
    status
    index
    search
  wiki
    status
    doctor
    init
    ingest
    compile
    lint
    search
    get
    apply
    bridge import
    unsafe-local import
    obsidian status|search|open|command|daily
  message
    send
    broadcast
    poll
    react
    reactions
    read
    edit
    delete
    pin
    unpin
    pins
    permissions
    search
    thread create|list|reply
    emoji list|upload
    sticker send|upload
    role info|add|remove
    channel info|list
    member info
    voice status
    event list|create
    timeout
    kick
    ban
  agent
  agents
    list
    add
    delete
    bindings
    bind
    unbind
    set-identity
  acp
  mcp
    serve
    list
    show
    set
    unset
  status
  health
  sessions
    cleanup
  tasks
    list
    audit
    maintenance
    show
    notify
    cancel
    flow list|show|cancel
  gateway
    call
    usage-cost
    health
    status
    probe
    discover
    install
    uninstall
    start
    stop
    restart
    run
  daemon
    status
    install
    uninstall
    start
    stop
    restart
  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
  infer (alias: capability)
    list
    inspect
    model run|list|inspect|providers|auth login|logout|status
    image generate|edit|describe|describe-many|providers
    audio transcribe|providers
    tts convert|voices|providers|status|enable|disable|set-provider
    video generate|describe|providers
    web search|fetch|providers
    embedding create|providers
    auth add|login|login-github-copilot|setup-token|paste-token
    auth order get|set|clear
  sandbox
    list
    recreate
    explain
  cron
    status
    list
    add
    edit
    rm
    enable
    disable
    runs
    run
  nodes
    status
    describe
    list
    pending
    approve
    reject
    rename
    invoke
    notify
    push
    canvas snapshot|present|hide|navigate|eval
    canvas a2ui push|reset
    camera list|snap|clip
    screen record
    location get
  devices
    list
    remove
    clear
    approve
    reject
    rotate
    revoke
  node
    run
    status
    install
    uninstall
    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
  qr
  clawbot
    qr
  docs
  dns
    setup
  tui

You should note that plugins can add additional top-level commands. For example, you might see openclaw voicecall if you have the right extension installed.

Security

Keeping your environment safe is vital. You can use the security suite to check for common configuration mistakes or “foot-guns.”

• openclaw security audit — This audits your config and local state.
• openclaw security audit --deep — This performs a best-effort live Gateway probe.
• openclaw security audit --fix — This command tightens your safe defaults.
• It also updates your state and config permissions for better protection.

Secrets

Managing your SecretRefs and keeping your runtime hygiene in check is handled through the secrets command.

secrets

You have several subcommands to manage how secrets are handled:

• secrets reload
• secrets audit
• secrets configure
• secrets apply --from <path>

If you are using secrets reload, you can use these options:

• --url, --token, --timeout, --expect-final, --json

For the secrets audit command, these flags are available:

• --check
• --allow-exec
• --json
• These help you identify issues in your secret resolution.

When you run secrets configure, you have access to these options:

• --apply
• --yes
• --providers-only
• --skip-provider-setup
• --agent <id>
• --allow-exec
• --plan-out <path>
• --json

For secrets apply --from <path>, you can use:

• --dry-run
• --allow-exec
• --json
• These allow you to test your changes before they go live.

There are a few technical details you should keep in mind:

• The reload command is a Gateway RPC. It keeps the last-known-good runtime snapshot if resolution fails.
• Using audit --check returns a non-zero exit code on findings. Unresolved references use a higher-priority non-zero exit code.
• Dry-run execution checks are skipped by default.
• You must use --allow-exec to opt in to those checks.

Plugins

You can manage extensions and their configurations to add more power to your setup:

• openclaw plugins list — Use this to discover plugins. You can use --json for machine-readable output.
• openclaw plugins inspect <id> — This shows details for a specific plugin. You can also use info as an alias.
• openclaw plugins install <path|.tgz|npm-spec|plugin@marketplace> — This installs a plugin or adds a path to plugins.load.paths. Use --force if you need to overwrite an existing install.
• openclaw plugins marketplace list <marketplace> — This lets you see marketplace entries before you install them.
• openclaw plugins enable <id> / disable <id> — These commands toggle the plugins.entries.<id>.enabled setting.
• openclaw plugins doctor — Run this to get a report on any plugin load errors.

Most plugin changes will require you to restart the gateway to take effect. You can find more information at /plugin.

Memory

You can manage your agent’s long-term context using vector search over MEMORY.md and memory/*.md files. Here is how you can handle your memory index:

• openclaw memory status — show index stats; use --deep for vector + embedding readiness checks or --fix to repair stale recall/promotion artifacts.
• openclaw memory index — reindex memory files.
• openclaw memory search "<query>" (or --query "<query>") — semantic search over memory.
• openclaw memory promote — rank short-term recalls and optionally append top entries into MEMORY.md.

Sandbox

If you need to run agent execution in isolation, you can manage sandbox runtimes. You can find more details at /cli/sandbox.

Use these subcommands to control your environment:

• sandbox list [--browser] [--json]
• sandbox recreate [--all] [--session <key>] [--agent <id>] [--browser] [--force]
• sandbox explain [--session <key>] [--agent <id>] [--json]

Keep these notes in mind:

• sandbox recreate removes existing runtimes so the next use seeds them again with current config.
• For ssh and OpenShell remote backends, recreate deletes the canonical remote workspace for the selected scope.

Chat slash commands

Your chat messages support /... commands for both text and native functions. You can check the full list at /tools/slash-commands.

Here are the main highlights:

• /status for quick diagnostics.
• /config for persisted config changes.
• /debug for runtime-only config overrides (this stays in memory and does not touch your disk; it requires commands.debug: true).

Setup + onboarding

Getting your environment ready is straightforward with these setup and onboarding tools.

completion

You can generate shell-completion scripts and install them directly into your shell profile.

Options:

• -s, --shell <zsh|bash|powershell|fish>
• -i, --install
• --write-state
• -y, --yes

If you run this without --install or --write-state, completion simply prints the script to your terminal. Using --install writes an OpenClaw Completion block into your shell profile and points it at the cached script in the OpenClaw state directory.

setup

This command initializes your configuration and workspace.

Options:

• --workspace <dir>: agent workspace path (default ~/.openclaw/workspace).
• --wizard: run onboarding.
• --non-interactive: run onboarding without prompts.
• --mode <local|remote>: onboard mode.
• --remote-url <url>: remote Gateway URL.
• --remote-token <token>: remote Gateway token.

Onboarding will run automatically whenever any onboarding flags are present, such as --non-interactive, --mode, --remote-url, or --remote-token.

onboard

This is the interactive onboarding process for your gateway, workspace, and skills.

Options:

• --workspace <dir>
• --reset (reset config + credentials + sessions before onboarding)
• --reset-scope <config|config+creds+sessions|full> (default config+creds+sessions; use full to also remove workspace)
• --non-interactive
• --mode <local|remote>
• --flow <quickstart|advanced|manual> (manual is an alias for advanced)
• --auth-choice <choice> where <choice> is one of: chutes, deepseek-api-key, openai-codex, openai-api-key, openrouter-api-key, kilocode-api-key, litellm-api-key, ai-gateway-api-key, cloudflare-ai-gateway-api-key, moonshot-api-key, moonshot-api-key-cn, kimi-code-api-key, synthetic-api-key, venice-api-key, together-api-key, huggingface-api-key, apiKey, gemini-api-key, google-gemini-cli, zai-api-key, zai-coding-global, zai-coding-cn, zai-global, zai-cn, xiaomi-api-key, minimax-global-oauth, minimax-global-api, minimax-cn-oauth, minimax-cn-api, opencode-zen, opencode-go, github-copilot, copilot-proxy, xai-api-key, mistral-api-key, volcengine-api-key, byteplus-api-key, qianfan-api-key, qwen-standard-api-key-cn, qwen-standard-api-key, qwen-api-key-cn, qwen-api-key, modelstudio-standard-api-key-cn, modelstudio-standard-api-key, modelstudio-api-key-cn, modelstudio-api-key, custom-api-key, skip
• Qwen note: qwen-* is the canonical auth-choice family. modelstudio-* ids remain accepted as legacy compatibility aliases only.
• --secret-input-mode <plaintext|ref> (default plaintext; use ref to store provider default env refs instead of plaintext keys)
• --anthropic-api-key <key>
• --openai-api-key <key>
• --mistral-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>
• --opencode-go-api-key <key>
• --custom-base-url <url> (non-interactive; used with --auth-choice custom-api-key)
• --custom-model-id <id> (non-interactive; used with --auth-choice custom-api-key)
• --custom-api-key <key> (non-interactive; optional; used with --auth-choice custom-api-key; falls back to CUSTOM_API_KEY when omitted)
• --custom-provider-id <id> (non-interactive; optional custom provider id)
• --custom-compatibility <openai|anthropic> (non-interactive; optional; default openai)
• --gateway-port <port>
• --gateway-bind <loopback|lan|tailnet|auto|custom>
• --gateway-auth <token|password>
• --gateway-token <token>
• --gateway-token-ref-env <name> (non-interactive; store gateway.auth.token as an env SecretRef; requires that env var to be set; cannot be combined with --gateway-token)
• --gateway-password <password>
• --remote-url <url>
• --remote-token <token>
• --tailscale <off|serve|funnel>
• --tailscale-reset-on-exit
• --install-daemon
• --no-install-daemon (alias: --skip-daemon)
• --daemon-runtime <node|bun>
• --skip-channels
• --skip-skills
• --skip-search
• --skip-health
• --skip-ui
• --cloudflare-ai-gateway-account-id <id>
• --cloudflare-ai-gateway-gateway-id <id>
• --node-manager <npm|pnpm|bun> (setup/onboarding node manager for skills; pnpm recommended, bun also supported)
• --json

configure

This is the interactive configuration wizard for your models, channels, skills, and gateway.

Options:

• --section <section> (repeatable; limit the wizard to specific sections)

config

If you prefer non-interactive helpers, you can use the config command. Running openclaw config without a subcommand will launch the wizard.

Subcommands:

• config get <path>: print a config value (dot/bracket path).
• config set: supports four assignment modes:
• value mode: config set <path> <value> (JSON5-or-string parsing)
• SecretRef builder mode: config set <path> --ref-provider <provider> --ref-source <source> --ref-id <id>
• provider builder mode: config set secrets.providers.<alias> --provider-source <env|file|exec> ...
• batch mode: config set --batch-json '<json>' or config set --batch-file <path>
• config set --dry-run: validate assignments without writing openclaw.json (exec SecretRef checks are skipped by default).
• config set --allow-exec --dry-run: opt in to exec SecretRef dry-run checks (may execute provider commands).
• config set --dry-run --json: emit machine-readable dry-run output (checks + completeness signal, operations, refs checked/skipped, errors).
• config set --strict-json: require JSON5 parsing for path/value input. --json remains a legacy alias for strict parsing outside dry-run output mode.
• config unset <path>: remove a value.
• config file: print the active config file path.
• config schema: print the generated JSON schema for openclaw.json, including propagated field title / description docs metadata across nested object, wildcard, array-item, and composition branches, plus best-effort live plugin/channel schema metadata.
• config validate: validate the current config against the schema without starting the gateway.
• config validate --json: emit machine-readable JSON output.

doctor

Use this for health checks and quick fixes for your config, gateway, and legacy services.

Options:

• --no-workspace-suggestions: disable workspace memory hints.
• --yes: accept defaults without prompting (headless).
• --non-interactive: skip prompts; apply safe migrations only.
• --deep: scan system services for extra gateway installs.
• --repair (alias: --fix): attempt automatic repairs for detected issues.
• --force: force repairs even when not strictly needed.
• --generate-gateway-token: generate a new gateway auth token.

dashboard

Open the Control UI with your current token.

Options:

• --no-open: print the URL but do not launch a browser

Notes:

• For SecretRef-managed gateway tokens, dashboard prints or opens a non-tokenized URL instead of exposing the secret in terminal output or browser launch arguments.

update

Use this command to update your installed CLI.

Root options:

• --json
• --no-restart
• --dry-run
• --channel <stable|beta|dev>
• --tag <dist-tag|version|spec>
• --timeout <seconds>
• --yes

Subcommands:

• update status
• update wizard

update status options:

• --json
• --timeout <seconds>

update wizard options:

• --timeout <seconds>

Notes:

• openclaw --update rewrites to openclaw update.

backup

You can create and verify local backup archives for your OpenClaw state.

Subcommands:

• backup create
• backup verify <archive>

backup create options:

• --output <path>
• --json
• --dry-run
• --verify
• --only-config
• --no-include-workspace

backup verify <archive> options:

• --json

Channel helpers

channels

You can use this command to manage your chat channel accounts, including WhatsApp, Telegram, Discord, Google Chat, Slack, Mattermost, Signal, iMessage, and Microsoft Teams.

Subcommands:

• channels list: You can see all your configured channels and auth profiles here.
• channels status: This lets you check if your gateway is reachable and see the health of your channels. If you use --probe, it runs live checks for each account when the gateway is reachable. If not, it just shows you a summary based on your config. For a full check, you might want to use openclaw health or openclaw status --deep.
• Tip: channels status is great because it gives you warnings and suggested fixes for common mistakes, then points you toward openclaw doctor.
• channels logs: Use this to see the most recent channel logs from your gateway.
• channels add: This starts a wizard-style setup if you don’t pass any flags. If you do use flags, it switches to a non-interactive mode.
• If you add a non-default account to a channel that’s still using a single-account setup, OpenClaw moves those values into the channel account map before writing the new one. Most channels use accounts.default, but Matrix can keep an existing matching target instead.
• Keep in mind that non-interactive channels add won’t auto-create or upgrade your bindings; channel-only bindings will still point to the default account.
• channels remove: This is disabled by default to keep you safe. You’ll need to pass --delete to remove config entries without being prompted.
• channels login: This is for interactive channel logins (currently WhatsApp Web only).
• channels logout: Use this to log out of a channel session if the channel supports it.

Common options:

• --channel <name>: Choose from whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams.
• --account <id>: Your channel account id (this defaults to default).
• --name <label>: A display name you want to give the account.

channels login options:

• --channel <channel> (defaults to whatsapp; you can use whatsapp or web).
• --account <id>
• --verbose

channels logout options:

• --channel <channel> (defaults to whatsapp).
• --account <id>

channels list options:

• --no-usage: You can skip the model provider usage and quota snapshots for OAuth or API-backed accounts.
• --json: Get your output in JSON format (this includes usage unless you use --no-usage).

channels status options:

• --probe
• --timeout <ms>
• --json

channels capabilities options:

• --channel <name>
• --account <id> (only works if you also set --channel).
• --target <dest>
• --timeout <ms>
• --json

channels resolve options:

• <entries...>
• --channel <name>
• --account <id>
• --kind <auto|user|group>
• --json

channels logs options:

• --channel <name|all> (defaults to all).
• --lines <n> (defaults to 200).
• --json

Notes:

• You can use --verbose with channels login.
• The --account flag for channels capabilities only works when you’ve set a --channel.
• When you use channels status --probe, you’ll see the transport state and results like works, probe failed, audit ok, or audit failed, depending on what the channel supports.

For more details, check out: /concepts/oauth

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

directory

You can use this to look up IDs for yourself, your peers, or groups on channels that have a directory. Take a look at openclaw directory for more.

Common options:

• --channel <name>
• --account <id>
• --json

Subcommands:

• directory self
• directory peers list [--query <text>] [--limit <n>]
• directory groups list [--query <text>] [--limit <n>]
• directory groups members --group-id <id> [--limit <n>]

skills

This command lets you list and inspect the skills you have available and see if they are ready to use.

Subcommands:

• skills search [query...]: Search for skills on ClawHub.
• skills search --limit <n> --json: Limit your search results or get machine-readable output.
• skills install <slug>: Install a skill from ClawHub into your active workspace.
• skills install <slug> --version <version>: Install a specific version from ClawHub.
• skills install <slug> --force: Use this to overwrite an existing skill folder in your workspace.
• skills update <slug|--all>: Keep your tracked ClawHub skills up to date.
• skills list: Shows your skills (this is the default if you don’t provide a subcommand).
• skills list --json: Outputs your skill inventory as JSON.
• skills list --verbose: This will show you exactly which requirements are missing in the table.
• skills info <name>: Get the details for a specific skill.
• skills info <name> --json: Get those skill details in JSON format.
• skills check: Gives you a summary of which skills are ready and which are missing requirements.
• skills check --json: Outputs that readiness info as JSON.

Options:

• --eligible: Only show the skills that are actually ready to go.
• --json: Output everything in JSON without any styling.
• -v, --verbose: Get more detail on missing requirements.

Tip: Stick to openclaw skills search, openclaw skills install, and openclaw skills update when you’re working with ClawHub-backed skills.

pairing

You can use this to approve DM pairing requests across your channels.

Subcommands:

• pairing list [channel] [--channel <channel>] [--account <id>] [--json]
• pairing approve <channel> <code> [--account <id>] [--notify]
• pairing approve --channel <channel> [--account <id>] <code> [--notify]

Notes:

• If you only have one pairing-capable channel configured, you can just use pairing approve <code>.
• Both list and approve support the --account <id> flag if you’re using multi-account channels.

devices

This helps you manage gateway device pairing entries and tokens for specific roles.

Subcommands:

• devices list [--json]
• devices approve [requestId] [--latest]
• devices reject <requestId>
• devices remove <deviceId>
• devices clear --yes [--pending]
• devices rotate --device <id> --role <role> [--scope <scope...>]
• devices revoke --device <id> --role <role>

Notes:

• devices list and devices approve can use local pairing files on your local loopback if the direct pairing scope isn’t available.
• You need an explicit request ID for devices approve before it can mint tokens. If you leave out the ID or use --latest, it just previews the newest pending request.
• When you reconnect using a stored token, it uses the cached scopes. If you want to update those scopes for future reconnects, use devices rotate --scope ....
• Both devices rotate and devices revoke will give you JSON payloads back.

qr

You can generate a mobile pairing QR and setup code from your current Gateway config. Check out openclaw qr.

Options:

• --remote
• --url <url>
• --public-url <url>
• --token <token>
• --password <password>
• --setup-code-only
• --no-ascii
• --json

Notes:

• You can’t use --token and --password at the same time.
• The setup code uses a short-lived bootstrap token, not your main gateway token or password.
• The built-in bootstrap process keeps the primary node token at scopes: [].
• Any operator bootstrap token you hand off is restricted to operator.approvals, operator.read, operator.talk.secrets, and operator.write.
• These scope checks are role-prefixed. This means an operator allowlist only works for operator requests; other roles still need scopes under their own prefix.
• The --remote flag can use your gateway.remote.url or your active Tailscale Serve/Funnel URL.
• Once you’ve scanned the code, you can approve the request with openclaw devices list or openclaw devices approve <requestId>.

clawbot

This is a legacy alias. Right now, it supports openclaw clawbot qr, which just points to openclaw qr.

hooks

Use this to manage your internal agent hooks.

Subcommands:

• hooks list
• hooks info <name>
• hooks check
• hooks enable <name>
• hooks disable <name>
• hooks install <path-or-spec> (this is a deprecated alias for openclaw plugins install)
• hooks update [id] (this is a deprecated alias for openclaw plugins update)

Common options:

• --json
• --eligible
• -v, --verbose

Notes:

• You can’t enable or disable hooks that are managed by plugins through openclaw hooks. You’ll need to enable or disable the plugin itself instead.
• While hooks install and hooks update still work for compatibility, they’ll show you a warning and forward you to the plugin commands.

webhooks

These are your webhook helpers. Currently, the built-in support is for Gmail Pub/Sub setup and running:

• webhooks gmail setup
• webhooks gmail run

webhooks gmail

This handles your Gmail Pub/Sub hook setup and the runner. See Gmail Pub/Sub.

Subcommands:

• webhooks gmail setup: This requires --account <email>. It supports a lot of flags like --project, --topic, --subscription, --label, --hook-url, and more for detailed configuration.
• webhooks gmail run: Use this to start the runner with optional overrides for the same flags.

Notes:

• setup handles the Gmail watch and the push path for OpenClaw.
• run kicks off the local watcher and renewal loop.

dns

These are helpers for wide-area discovery DNS using CoreDNS and Tailscale.

• dns setup [--domain <domain>] [--apply]

dns setup

This is the specific helper for wide-area discovery DNS. See /gateway/discovery.

Options:

• --domain <domain>
• --apply: This installs or updates your CoreDNS config. You’ll need sudo for this, and it currently only works on macOS.

Notes:

• If you don’t use --apply, it acts as a planner and prints out the recommended DNS config for OpenClaw and Tailscale.
• Currently, --apply only supports macOS using Homebrew CoreDNS.

Messaging + agent

message

This is your unified tool for outbound messaging and channel actions.

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

agent

You can use this to run a single agent turn through the Gateway. You can also use --local to run it embedded.

You need to pass at least one session selector: --to, --session-id, or --agent.

Required:

• -m, --message <text>

Options:

• -t, --to <dest> (used for the session key and delivery)
• --session-id <id>
• --agent <id> (this overrides your routing bindings)
• --thinking <off|minimal|low|medium|high|xhigh> (support depends on your provider)
• --verbose <on|off>
• --channel <channel> (the delivery channel; if you omit this, it uses the main session channel)
• --reply-to <target> (overrides the delivery target)
• --reply-channel <channel> (overrides the delivery channel)
• --reply-account <id> (overrides the delivery account id)
• --local (runs embedded, but preloads the plugin registry first)
• --deliver
• --json
• --timeout <seconds>

Notes:

• If you’re in Gateway mode and the request fails, it falls back to the embedded agent.
• Even with --local, the plugin registry is preloaded so your providers, tools, and channels stay available.
• The --channel, --reply-channel, and --reply-account flags only change how the reply is delivered, not how it’s routed.

agents

Use this to manage isolated agents, including their workspaces, auth, and routing.

If you run openclaw agents without a subcommand, it’s the same as running openclaw agents list.

agents list

Shows you all your configured agents.

Options:

• --json
• --bindings

agents add [name]

Adds a new isolated agent. This runs a guided wizard unless you provide flags or use --non-interactive. If you go the non-interactive route, you must provide --workspace.

Options:

• --workspace <dir>
• --model <id>
• --agent-dir <dir>
• --bind <channel[:accountId]> (you can repeat this)
• --non-interactive
• --json

For bindings, use the format channel[:accountId]. If you leave out the accountId, OpenClaw tries to resolve it via defaults or hooks. Using any flags here will trigger the non-interactive path. Note that main is a reserved ID and can’t be used for new agents.

agents bindings

Lists your routing bindings.

Options:

• --agent <id>
• --json

agents bind

Adds routing bindings to an agent.

Options:

• --agent <id> (defaults to your current default agent)
• --bind <channel[:accountId]> (repeatable)
• --json

agents unbind

Removes routing bindings from an agent.

Options:

• --agent <id> (defaults to your current default agent)
• --bind <channel[:accountId]> (repeatable)
• --all
• --json

You should use either --all or --bind, but not both at once.

agents delete <id>

Deletes an agent and cleans up its workspace and state.

Options:

• --force
• --json

Notes:

• You cannot delete the main agent.
• You’ll need to confirm interactively unless you use --force.

agents set-identity

Updates an agent’s identity, like its name, theme, emoji, or avatar.

Options:

• --agent <id>
• --workspace <dir>
• --identity-file <path>
• --from-identity
• --name <name>
• --theme <theme>
• --emoji <emoji>
• --avatar <value>
• --json

Notes:

• Use --agent or --workspace to pick which agent you’re updating.
• If you don’t provide specific fields, the command will look for an IDENTITY.md file.

acp

This runs the ACP bridge to connect your IDEs to the Gateway.

Root options:

• --url <url>
• --token <token>
• --token-file <path>
• --password <password>
• --password-file <path>
• --session <key>
• --session-label <label>
• --require-existing
• --reset-session
• --no-prefix-cwd
• --provenance <off|meta|meta+receipt>
• --verbose

acp client

An interactive client for debugging your ACP bridge.

Options:

• --cwd <dir>
• --server <command>
• --server-args <args...>
• --server-verbose
• --verbose

Check out acp for more on security and examples.

mcp

Manage your saved MCP server definitions and expose your channels over MCP stdio.

mcp serve

Exposes your routed OpenClaw channel conversations over MCP stdio.

Options:

• --url <url>
• --token <token>
• --token-file <path>
• --password <password>
• --password-file <path>
• --claude-channel-mode <auto|on|off>
• --verbose

mcp list

Shows your saved MCP server definitions.

Options:

• --json

mcp show [name]

Shows a specific saved MCP server definition or the entire object.

Options:

• --json

mcp set <name> <value>

Saves an MCP server definition from a JSON object.

mcp unset <name>

Removes a saved MCP server definition.

approvals

Manage your execution approvals. You can also use the alias exec-approvals.

approvals get

Fetches your current exec approvals snapshot and the effective policy.

Options:

• --node <node>
• --gateway
• --json
• node RPC options from openclaw nodes

approvals set

Replaces your exec approvals using JSON from a file or stdin.

Options:

• --node <node>
• --gateway
• --file <path>
• --stdin
• --json
• node RPC options from openclaw nodes

approvals allowlist add|remove

Edits the execution allowlist for a specific agent.

Options:

• --node <node>
• --gateway
• --agent <id> (defaults to *)
• --json
• node RPC options from openclaw nodes

status

Shows the health of your linked sessions and recent recipients.

Options:

• --json
• --all (gives a full diagnosis that is read-only and easy to paste)
• --deep (asks the gateway for a live health probe, including channels)
• --usage (shows your model provider usage and quotas)
• --timeout <ms>
• --verbose
• --debug (this is an alias for --verbose)

Notes:

• The overview includes the status of the Gateway and node host service when available.
• Using --usage prints out your provider usage as a normalized X% left.

Usage tracking

OpenClaw can show you your provider usage and quota if you have OAuth or API credentials set up.

You can see this in:

• /status (shows a short usage line)
• openclaw status --usage (gives a full breakdown)
• The macOS menu bar (under the Usage section in Context)

Notes:

• This data comes straight from the provider endpoints, so it’s not an estimate.
• Output is normalized to X% left for readability.
• Supported providers include Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi, and z.ai.
• For MiniMax: OpenClaw inverts the usage_percent field because it represents remaining quota. It prefers chat-model entries and derives labels from timestamps.
• Usage auth is pulled from provider-specific hooks or falls back to matching credentials in your profiles, environment, or config. If nothing is found, usage info is hidden.
• For more, see Usage tracking.

health

Fetches the health status from your running Gateway.

Options:

• --json
• --timeout <ms>
• --verbose (forces a live probe and prints connection details)
• --debug (alias for --verbose)

Notes:

• Running health normally might return a cached snapshot.
• Using --verbose forces a live check and gives you more detail across all accounts and agents.

sessions

Lists your stored conversation sessions.

Options:

• --json
• --verbose
• --store <path>
• --active <minutes>
• --agent <id> (filter by agent)
• --all-agents (show sessions for every agent)

Subcommands:

• sessions cleanup: Removes sessions that are expired or orphaned.

Notes:

• You can use --fix-missing with sessions cleanup to remove entries if their transcript files are missing.

Reset / Uninstall

Sometimes you just need to start fresh. If you want to wipe your local configuration or state but keep the CLI tool itself, you can use the reset command.

reset

This command clears out your local config and state without removing the CLI.

Options:

• --scope <config|config+creds+sessions|full>
• --yes
• --non-interactive
• --dry-run

Just a heads-up: if you are running this in a script using --non-interactive, you are required to provide both the --scope and the --yes flag.

uninstall

When you need to remove the gateway service and your local data entirely, use uninstall. Note that the CLI itself will remain on your system.

Options:

• --service
• --state
• --workspace
• --app
• --all
• --yes
• --non-interactive
• --dry-run

If you use --non-interactive, you must include --yes and specify which scopes to remove (or just use --all to wipe the service, state, workspace, and app in one go).

tasks

You can list and manage background task runs across your agents with these commands:

• tasks list — Show active and recent task runs.
• tasks show <id> — Get the details for a specific task run.
• tasks notify <id> — Change the notification policy for a task run.
• tasks cancel <id> — Stop a running task.
• tasks audit — Find operational issues like stale or lost tasks.
• tasks maintenance [--apply] [--json] — Preview or apply cleanup for tasks and TaskFlow (handles things like active cron jobs or live CLI runs).
• tasks flow list — List active and recent Task Flow flows.
• tasks flow show <lookup> — Inspect a flow by its ID or lookup key.
• tasks flow cancel <lookup> — Cancel a running flow and its active tasks.

flows

This is a legacy shortcut. These commands now live under openclaw tasks flow:

• tasks flow list [--json]
• tasks flow show <lookup>
• tasks flow cancel <lookup>

Gateway

The Gateway is what handles the WebSocket connections for your setup.

gateway

Use this command to run the WebSocket Gateway directly.

Options:

• --port <port>
• --bind <loopback|tailnet|lan|auto|custom>
• --token <token>
• --auth <token|password>
• --password <password>
• --password-file <path>
• --tailscale <off|serve|funnel>
• --tailscale-reset-on-exit
• --allow-unconfigured
• --dev
• --reset (resets dev config, credentials, sessions, and workspace)
• --force (kills any existing listener on the specified port)
• --verbose
• --cli-backend-logs
• --ws-log <auto|full|compact>
• --compact (alias for --ws-log compact)
• --raw-stream
• --raw-stream-path <path>

gateway service

This is how you manage the Gateway service lifecycle on your system (launchd, systemd, or schtasks).

Subcommands:

• gateway status (probes the Gateway RPC by default)
• gateway install (installs the service)
• gateway uninstall
• gateway start
• gateway stop
• gateway restart

The gateway status command is quite powerful for diagnostics. It probes the Gateway RPC using the service’s resolved config, but you can override this with --url, --token, or --password. It also supports --no-probe, --deep, and --json for scripting. If you use --deep, it will scan for legacy or extra gateway services on your system.

When you run gateway install, it defaults to the Node runtime. We don’t recommend using bun because of known bugs with WhatsApp and Telegram.

daemon

If you see daemon in older documentation, it is just a legacy alias for the gateway service management commands. You can find more details at /cli/daemon.

logs

You can tail Gateway file logs via RPC using this command.

Options:

• --limit <n>: Maximum number of log lines to return.
• --max-bytes <n>: Maximum bytes to read from the log file.
• --follow: Follow the log file in real-time (like tail -f).
• --interval <ms>: Polling interval when following.
• --local-time: Display timestamps in your local time.
• --json: Output as line-delimited JSON.
• --plain: Disable structured formatting.
• --no-color: Disable ANSI colors.
• --url <url>: Explicit Gateway WebSocket URL.
• --token <token>: Gateway token.
• --timeout <ms>: Gateway RPC timeout.
• --expect-final: Wait for a final response when needed.

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

Keep in mind that if you pass an explicit --url, the CLI won’t auto-apply your local config or environment credentials, so you’ll need to provide the token or password yourself.

gateway <subcommand>

These are Gateway CLI helpers for RPC subcommands. When you use --url, remember to include --token or --password explicitly, as the CLI won’t pull them from your config.

Subcommands:

• gateway call <method> [--params <json>]
• gateway health
• gateway status
• gateway probe
• gateway discover
• gateway install|uninstall|start|stop|restart
• gateway run

Common RPC methods you might use:

• config.schema.lookup: Inspect a specific part of the config schema.
• config.get: Read the current configuration snapshot.
• config.set: Validate and write a full config (use baseHash for safety).
• config.apply: Write config, restart the gateway, and wake it up.
• config.patch: Merge a partial update, restart, and wake.
• update.run: Run an update and restart.

Pro tip: For partial edits, it is usually better to inspect the schema with config.schema.lookup first and then use config.patch. Also, the gateway tool will refuse to rewrite protected paths like tools.exec.ask or tools.exec.security.

Models

You should check out /concepts/models to understand how fallback behavior and scanning strategies work.

Regarding Anthropic: their staff mentioned that using the Claude CLI in an OpenClaw-style way is allowed again. Because of this, OpenClaw treats Claude CLI reuse and claude -p usage as sanctioned for this integration unless Anthropic puts out a new policy. If you are working on a production setup, you should probably use an Anthropic API key or another supported subscription provider like OpenAI Codex, Alibaba Cloud Model Studio Coding Plan, MiniMax Coding Plan, or Z.AI / GLM Coding Plan.

The Anthropic setup-token is still a supported path for token-auth, but OpenClaw now prefers Claude CLI reuse and claude -p when you have them available.

models (root)

openclaw models is an alias for models status.

Root options:

• --status-json (alias for models status --json)
• --status-plain (alias for models status --plain)

models list

Options:

• --all
• --local
• --provider <name>
• --json
• --plain

models status

Options:

• --json
• --plain
• --check (exit 1=expired/missing, 2=expiring)
• --probe (live probe of configured auth profiles)
• --probe-provider <name>
• --probe-profile <id> (repeat or comma-separated)
• --probe-timeout <ms>
• --probe-concurrency <n>
• --probe-max-tokens <n>
• --agent <id>

This command always includes the auth overview and OAuth expiry status for profiles in your auth store. Using --probe runs live requests, which might consume your tokens and trigger rate limits. You can expect probe statuses like ok, auth, rate_limit, billing, timeout, format, unknown, and no_model. When an explicit auth.order.<provider> leaves out a stored profile, the probe will report excluded_by_auth_order instead of trying that profile.

models set <model>

Set agents.defaults.model.primary.

models set-image <model>

Set agents.defaults.imageModel.primary.

models aliases list|add|remove

Options:

• list: --json, --plain
• add <alias> <model>
• remove <alias>

models fallbacks list|add|remove|clear

Options:

• list: --json, --plain
• add <model>
• remove <model>
• clear

models image-fallbacks list|add|remove|clear

Options:

• list: --json, --plain
• add <model>
• remove <model>
• clear

models scan

Options:

• --min-params <b>
• --max-age-days <days>
• --provider <name>
• --max-candidates <n>
• --timeout <ms>
• --concurrency <n>
• --no-probe
• --yes
• --no-input
• --set-default
• --set-image
• --json

models auth add|login|login-github-copilot|setup-token|paste-token

Options:

• add: interactive auth helper (provider auth flow or token paste)
• login: --provider <name>, --method <method>, --set-default
• login-github-copilot: GitHub Copilot OAuth login flow (--yes)
• setup-token: --provider <name>, --yes
• paste-token: --provider <name>, --profile-id <id>, --expires-in <duration>

Notes:

• setup-token and paste-token are generic token commands for providers that expose token auth methods.
• setup-token requires an interactive TTY and runs the provider’s token-auth method.
• paste-token prompts for the token value and defaults to auth profile id <provider>:manual when you omit --profile-id.
• Anthropic setup-token / paste-token remain available as a supported OpenClaw token path, but OpenClaw now prefers Claude CLI reuse and claude -p when available.

models auth order get|set|clear

Options:

• get: --provider <name>, --agent <id>, --json
• set: --provider <name>, --agent <id>, <profileIds...>
• clear: --provider <name>, --agent <id>

System

system event

You can use this to enqueue a system event and optionally trigger a heartbeat (Gateway RPC).

Required:

• --text <text>

Options:

• --mode <now|next-heartbeat>
• --json
• --url, --token, --timeout, --expect-final

system heartbeat last|enable|disable

These are your heartbeat controls (Gateway RPC).

Options:

• --json
• --url, --token, --timeout, --expect-final

system presence

This lists the system presence entries (Gateway RPC).

Options:

• --json
• --url, --token, --timeout, --expect-final

Cron

You can manage your scheduled jobs through the Gateway RPC using the cron command. If you want to see how these work in detail, check out the /automation/cron-jobs documentation.

Here are the subcommands you’ll use:

• cron status [--json]
• cron list [--all] [--json] (this outputs a table by default; use --json for the raw data)
• cron add (alias: create; this requires --name and exactly one of --at | --every | --cron, plus exactly one payload of --system-event | --message)
• cron edit <id> (to patch specific fields)
• cron rm <id> (aliases: remove, delete)
• cron enable <id>
• cron disable <id>
• cron runs --id <id> [--limit <n>]
• cron run <id> [--due]

All cron commands accept these flags: --url, --token, --timeout, and --expect-final.

When you use cron add|edit --model ..., the job uses that specific allowed model. If the model isn’t allowed, the system warns you and falls back to the job’s agent or default model selection instead. Your configured fallback chains still apply. However, a plain model override without an explicit per-job fallback list no longer appends the primary agent as a hidden extra retry target.

Node host

The node command lets you run a headless node host or manage it as a background service. You can find more details at openclaw node.

Use these subcommands to manage your node:

• 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

Regarding authentication, the node command handles things a bit differently. It resolves gateway auth from your environment or config instead of using --token or --password flags. It looks for OPENCLAW_GATEWAY_TOKEN or OPENCLAW_GATEWAY_PASSWORD. It also checks gateway.auth.*.

In local mode, the node host ignores gateway.remote.*. If you are using gateway.mode=remote, then gateway.remote.* participates based on remote precedence rules. Just keep in mind that node-host auth resolution only honors OPENCLAW_GATEWAY_* environment variables.

Nodes

The nodes command is how you talk to the Gateway and interact with your paired devices. You can find more details about how this works at /nodes.

When you are working with nodes, you will typically use these common options:

• --url, --token, --timeout, --json

Here are the subcommands you can use to manage your nodes:

nodes status [--connected] [--last-connected <duration>]
nodes describe --node &lt;id|name|ip&gt;
nodes list [--connected] [--last-connected <duration>]
nodes pending
nodes approve <requestId>
nodes reject <requestId>
nodes rename --node &lt;id|name|ip&gt; --name <displayName>
nodes invoke --node &lt;id|name|ip&gt; --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]
nodes notify --node &lt;id|name|ip&gt; [--title <text>] [--body <text>] [--sound <name>] [--priority &lt;passive|active|timeSensitive&gt;] [--delivery &lt;system|overlay|auto&gt;] [--invoke-timeout <ms>]

(Note: nodes notify is for macOS only).

If you need to use the camera on a node, these commands have you covered:

nodes camera list --node <id|name|ip>
nodes camera snap --node &lt;id|name|ip&gt; [--facing front|back|both] [--device-id <id>] [--max-width <px>] [--quality <0-1>] [--delay-ms <ms>] [--invoke-timeout <ms>]
nodes camera clip --node &lt;id|name|ip&gt; [--facing front|back] [--device-id <id>] [--duration &lt;ms|10s|1m&gt;] [--no-audio] [--invoke-timeout <ms>]

For canvas and screen interactions, use these subcommands:

nodes canvas snapshot --node &lt;id|name|ip&gt; [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]
nodes canvas present --node &lt;id|name|ip&gt; [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>] [--invoke-timeout <ms>]
nodes canvas hide --node &lt;id|name|ip&gt; [--invoke-timeout <ms>]
nodes canvas navigate <url> --node &lt;id|name|ip&gt; [--invoke-timeout <ms>]
nodes canvas eval [<js>] --node &lt;id|name|ip&gt; [--js <code>] [--invoke-timeout <ms>]
nodes canvas a2ui push --node &lt;id|name|ip&gt; (--jsonl <path> | --text <text>) [--invoke-timeout <ms>]
nodes canvas a2ui reset --node &lt;id|name|ip&gt; [--invoke-timeout <ms>]
nodes screen record --node &lt;id|name|ip&gt; [--screen <index>] [--duration &lt;ms|10s&gt;] [--fps <n>] [--no-audio] [--out <path>] [--invoke-timeout <ms>]

You can also grab location data from a node:

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

Browser

The browser command is a dedicated CLI for controlling browsers like Chrome, Brave, Edge, or Chromium. You can find more information at openclaw browser and in the Browser tool documentation.

These common options are available for browser commands:

• --url, --token, --timeout, --expect-final, --json
• --browser-profile <name>

To manage your browser instances and profiles, use these commands:

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>] [--driver existing-session] [--user-data-dir <path>]
browser delete-profile --name <name>

If you need to inspect the page or take screenshots:

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

For interacting with the page, use these action subcommands:

browser navigate <url> [--target-id <id>]
browser resize <width> <height> [--target-id <id>]
browser click <ref> [--double] [--button &lt;left|right|middle&gt;] [--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 &lt;error|warn|info&gt;] [--target-id <id>]
browser pdf [--target-id <id>]

Voice call

voicecall

You can use these plugin-provided voice-call utilities if you have the voice-call plugin installed and enabled. For the full breakdown, check out openclaw voicecall.

Common commands:

• voicecall call --to <phone> --message <text> [--mode notify|conversation]
• voicecall start --to <phone> [--message <text>] [--mode notify|conversation]
• voicecall continue --call-id <id> --message <text>
• voicecall speak --call-id <id> --message <text>
• voicecall end --call-id <id>
• voicecall status --call-id <id>
• voicecall tail [--file <path>] [--since <n>] [--poll <ms>]
• voicecall latency [--file <path>] [--last <n>]
• voicecall expose [--mode off|serve|funnel] [--path <path>] [--port <port>] [--serve-path <path>]

Docs search

docs

This command lets you search the live OpenClaw docs index whenever you need a quick answer.

docs [query...]

You can search the live docs index by adding your query directly to the command.

TUI

tui

Use this to open the terminal UI and connect directly to the Gateway.

Options:

• --url <url>
• --token <token>
• --password <password>
• --session <key>
• --deliver
• --thinking <level>
• --message <text>
• --timeout-ms <ms> (defaults to agents.defaults.timeoutSeconds)
• --history-limit <n>