How do I start the OpenClaw gateway?

Run `openclaw gateway` to start in the foreground, or `openclaw gateway install` to set it up as a system daemon that auto-starts on boot.

How do I check which channels are connected?

Run `openclaw gateway status` — it shows all channels and their current connection status in one view.

How do I add a new user to my OpenClaw agent?

Run `openclaw channels pair` to review and approve pending pairing requests from new contacts.

How do I view OpenClaw logs?

Run `openclaw logs` for all logs, `openclaw logs --tail 50` for the last 50 lines, or `openclaw logs --filter error` to see only errors.

How do I test an automation without waiting for the scheduled time?

Run `openclaw cron run [id]` — this triggers the job immediately and sends the result to your configured channel.

OpenClaw CLI: tools list, cron, logs, gateway commands

Most-used commands

These cover 90% of day-to-day OpenClaw use:

openclaw gateway status          # Is everything running?
openclaw logs --tail 50          # What just happened?
openclaw config edit             # Open config in your editor
openclaw channels pair           # Approve a new user
openclaw cron list               # See all scheduled automations

Bookmark this page. The full reference is below.

Copy-paste reference. For full options, run openclaw [command] --help.

Gateway

Use these when starting, stopping, or diagnosing the Gateway. gateway status is the first thing to run when something feels off.

openclaw gateway               # Start the Gateway (foreground)
openclaw gateway status        # Check if running + channel status
openclaw gateway restart       # Reload config without full stop
openclaw gateway stop          # Stop the Gateway
openclaw gateway install       # Install Gateway as a system daemon (auto-starts on boot)
openclaw logs                  # View logs
openclaw logs --tail 50        # Last 50 lines
openclaw logs --filter error   # Only error lines
openclaw logs --filter [text]  # Filter by any keyword (e.g. --filter telegram)

Example output for openclaw gateway status:

Gateway: running (pid 12847, uptime 3d 14h)
Channels:
  ✓ telegram     connected
  ✓ webchat      ready
  ✗ slack        disconnected (token expired)
Automations: 3 active, next run in 6h 22m

Example output for openclaw logs --tail 20:

[2025-03-12 07:00:01] [cron] Running automation: morning-briefing
[2025-03-12 07:00:02] [agent] Fetching weather for San Francisco
[2025-03-12 07:00:04] [skill] gmail: reading last 5 emails
[2025-03-12 07:00:07] [agent] Sending summary to telegram
[2025-03-12 07:00:07] [channel] telegram: message sent

openclaw update now checks the target release's Node.js engine requirements before installing. If your Node runtime is too old for the target version, the update fails with a clear upgrade message instead of installing an unsupported release.

Channels

Use when adding a new messaging platform or approving a new user. channels pair is how you let someone new message your agent.

openclaw channels list                        # List configured channels
openclaw channels list --all                  # Also list bundled + catalog channels (v2026.5.7+)
openclaw channels pair                        # Approve pending pairing requests
openclaw channels login --channel whatsapp    # WhatsApp QR code pairing
openclaw channels setup imessage              # iMessage permission setup
openclaw gateway status                       # Shows channel connection status

As of v2026.5.7, openclaw channels list shows only channel state (installed / configured / enabled). Model auth and usage details moved to openclaw models auth list and openclaw status.

Automations (Cron)

Use when building or managing scheduled tasks. cron status shows you what's running and when the next trigger fires.

openclaw cron list                     # List all cron automations
openclaw cron status                   # Status and next run times
openclaw cron run [id]                 # Run an automation immediately (for testing)
openclaw cron add                      # Add a new cron automation
openclaw cron edit [id]                # Edit an existing automation
openclaw cron delete [id]              # Remove an automation
openclaw cron logs [id]                # View recent runs for one job

What `openclaw cron list` shows

cron list prints every scheduled job the gateway knows about — its ID, cron expression, next fire time in your configured timezone, whether it's enabled, and the action it calls. This is the fastest way to answer "why didn't my morning briefing fire?"

Expect a row per job with these fields:

ID — the job identifier you pass to cron run, cron edit, cron delete, cron logs
Schedule — the cron expression (e.g. 0 7 * * * for every day at 07:00)
Next run — the next scheduled fire time, resolved in your configured timezone
Status — enabled or disabled
Agent — which agent receives the invocation
Action — the command or slash action that runs when the job fires

If no jobs exist, the output is empty. Use openclaw cron add to create your first one.

Checking whether a job actually ran

Use openclaw cron status to see run history alongside the schedule — each job's last run timestamp, whether it succeeded or failed, and duration. If the last run failed, the error message appears inline so you don't need to dig through openclaw logs.

For per-job history:

openclaw cron logs morning-brief       # Recent runs of a single job

If a job is enabled but never firing, common causes:

The gateway wasn't running at the scheduled time (sleeping laptop, stopped daemon). Check openclaw gateway status.
The cron expression is invalid — validate at crontab.guru.
Timezone mismatch — cron list shows the resolved timezone in the footer; confirm it matches what you intended.
The action references a channel or agent that no longer exists. cron logs [id] will show the exact error.

Test a job immediately without waiting for the schedule:

openclaw cron run morning-brief        # Fires the job once, now

Execution Policy Management (v2026.4.12)

Use exec-policy to manage tool execution permissions and see what your agent is allowed to do.

openclaw exec-policy show              # Display current exec policy
openclaw exec-policy preset [name]     # Load a preset policy (e.g., "safe", "full")
openclaw exec-policy set [path]        # Set custom policy from a file

The exec policy controls what tools and system commands your agent can execute. show displays your current settings, preset loads a predefined safe or permissive mode, and set lets you customize the policy with your own file.

Skills & Tools

Use when adding new capabilities. Skills connect to external services (Gmail, GitHub); tools are built-in capabilities (web_search, exec).

openclaw skills list                   # List installed skills
openclaw skills info [skill-name]      # Show skill details, requirements, and API key setup guidance
openclaw skills install [package]      # Install a skill from npm
openclaw skills auth [skill-name]      # Authenticate a skill (OAuth)

openclaw skills info shows whether a skill's dependencies are met, where to get required API keys, the CLI command to save them, and the storage path. Skills that are missing requirements are labeled "needs setup" (not "missing").

`openclaw tools list` command

The openclaw tools list command prints every tool the current agent can call right now. This includes three categories:

Built-in tools — compiled into OpenClaw, enabled via config flags (e.g. read, write, exec, web_search)
Skill-provided tools — contributed by installed skills from ClawHub or npm (e.g. gmail.send, calendar.create)
MCP-server tools — surfaced from any Model Context Protocol servers you've connected

Use it to confirm what your agent actually has access to before debugging "why didn't it do X?" problems.

openclaw tools list                    # Compact view — one line per tool
openclaw tools list --detailed         # Full parameter schemas for each tool
openclaw tools list --agent [name]     # Tools available to a specific agent
openclaw tools list --json             # Machine-readable output

What the compact view shows

Each row is a tool name and a one-line description. Tools are grouped by source (built-in, skills, MCP), so you can see at a glance whether a missing capability is a built-in that's disabled or a skill that isn't installed.

What `--detailed` adds

--detailed expands each tool with its parameter schema — name, type, required vs. optional, and description — which is useful when you're writing prompts and need the exact parameter names the agent will call with. This is the same metadata the model sees at tool-call time.

Tool listed but agent won't call it?

If a tool appears in tools list but the agent refuses to invoke it, check your execution policy — openclaw exec-policy show often reveals the tool is gated behind safe or a custom policy. The Execution Policy Management section above covers the commands.

Models & Plugins

openclaw models                        # List available AI models
openclaw models auth list              # List saved per-agent auth profiles (v2026.5.4+)
openclaw plugins                       # List installed plugins

WebChat

openclaw dashboard                    # Open WebChat in browser (http://localhost:18789)

Messaging

Use agent --message to test your agent from the terminal without opening any channel. Useful for quick verification after config changes.

openclaw agent --message "prompt"                    # Chat with the agent directly from CLI
openclaw agent --message "prompt" --thinking high    # Higher-effort reasoning
openclaw message send --to +1234567890 --message "text"  # Send a message to a number (WhatsApp/Signal)
openclaw pairing approve <channel> <code>            # Approve a pairing request by channel + code

Devices & Secrets

openclaw devices                       # Manage device pairing (mobile app, etc.)
openclaw secrets                       # Manage stored credentials and API keys

Running Inside Containers

If OpenClaw is running in a Docker or Podman container, use --container (or set the OPENCLAW_CONTAINER environment variable) to route CLI commands into the running container:

openclaw --container gateway status          # Check gateway status inside the container
openclaw --container logs --tail 50          # View logs from the containerized instance
openclaw --container config validate         # Validate config inside the container

Or set the environment variable so all commands route automatically:

export OPENCLAW_CONTAINER=1
openclaw gateway status                      # Runs inside the container

This works with both Docker and Podman. The CLI detects the running OpenClaw container automatically.

Useful flags

--config [path]    # Use a different config file
--container        # Run command inside a running Docker/Podman container
--verbose          # More detailed output
--json             # Output as JSON (for scripting)
--dev              # Run in development mode
--profile <name>   # Use a named configuration profile
--no-color         # Disable colored output
--update           # Check for updates before running
-V / --version     # Print version
--help             # Show all options for any command

Config file locations

~/.openclaw/openclaw.json    ← Main config
~/.openclaw/SOUL.md          ← Agent personality
~/.openclaw/USER.md          ← User context
~/.openclaw/workspace/       ← Files the agent reads/writes
~/.openclaw/tokens/          ← OAuth tokens (don't edit)
~/.openclaw/sessions/        ← Channel sessions (don't edit)