What Are OpenClaw Commands? (And Why the Docs Are Never Enough)
The official OpenClaw documentation is thorough. It's also structured for completeness, not for the moment when your agent is down at 11pm and you need the exact flag syntax in 10 seconds.
OpenClaw commands are the CLI interface to the OpenClaw agent runtime — a platform for deploying AI agents that automate workflows across messaging channels, browsers, files, and external APIs. The CLI covers everything from initial setup to production monitoring.
This guide does what the official docs don't: organizes commands by job-to-be-done, explains output formats for scripting, and shows how commands chain together in real automation pipelines.
OpenClaw CLI Architecture in 60 Seconds
The OpenClaw CLI follows a standard three-level hierarchy:
openclaw <command> <subcommand> [flags]
- Entry point:
openclaw - Commands: noun groups (
gateway,agent,channel,skill,model,browser,file) - Flags: modify behavior, can be global or command-specific
Config File Precedence (highest to lowest)
- CLI flags passed directly
- Environment variables (
OPENCLAW_*) - Local config file (
.openclaw/config.json) - Global config (
~/.openclaw/config.json)
You can always inspect the resolved config at runtime using openclaw config show.
Global Flags Reference
| Flag | Type | Default | Description |
|---|---|---|---|
| --config | string | ~/.openclaw/config.json | Path to config file |
| --profile | string | default | Named config profile to use |
| --output | string | plain | Output format: plain, json, table |
| --log-level | string | info | Log verbosity: debug, info, warn, error |
| --no-color | bool | false | Disable ANSI color output |
| --quiet | bool | false | Suppress non-essential output |
| --timeout | int | 30 | Command timeout in seconds |
| --workspace | string | ./workspace | Override workspace directory path |
| --dry-run | bool | false | Preview actions without executing |
| --yes | bool | false | Skip confirmation prompts |
Core Command Reference (Grouped by Job-to-Be-Done)
Install, Init & Configuration Commands
# Install OpenClaw CLI (npm) npm install -g openclaw # Initialize a new project with guided setup openclaw init # Initialize non-interactively with defaults openclaw init --yes --profile production # Show current resolved configuration openclaw config show # Set a config value openclaw config set gateway.port 8080 # Get a specific config value openclaw config get gateway.port # Generate a blank config file template openclaw config init --output .openclaw/config.json # Validate current config file openclaw config validate # List all environment variable overrides in effect openclaw config env
Environment variable pattern: Prefix any config key with OPENCLAW_ and use underscores for nesting. Example: OPENCLAW_GATEWAY_PORT=8080.
Gateway & Agent Management Commands
The gateway is the HTTP/WebSocket host process. Agents are the task-executing workers it manages.
# Start the gateway (foreground) openclaw gateway start # Start gateway as background daemon openclaw gateway start --daemon # Stop the gateway openclaw gateway stop # Restart the gateway (applies config changes) openclaw gateway restart # Check gateway status openclaw gateway status # Stream gateway logs openclaw gateway logs --follow # Tail last N lines openclaw gateway logs --tail 100 # List all registered agents openclaw agent list # Start a specific agent openclaw agent start my-agent # Stop an agent gracefully openclaw agent stop my-agent # Force-kill an unresponsive agent openclaw agent stop my-agent --force # View agent runtime status and uptime openclaw agent status my-agent # Stream logs for a specific agent openclaw agent logs my-agent --follow # Reload agent config without full restart openclaw agent reload my-agent
Channel Setup Commands (Telegram, WhatsApp, Discord, Google Chat, Synology)
Updated for v2026.4.21 syntax — note the --provider flag replaces the legacy --type flag from earlier 2026 builds.
# List all configured channels openclaw channel list # Add a Telegram channel openclaw channel add --provider telegram --token YOUR_BOT_TOKEN --name my-telegram # Add a WhatsApp channel (via WhatsApp Cloud API) openclaw channel add --provider whatsapp --token YOUR_TOKEN --phone-id YOUR_PHONE_ID --name my-whatsapp # Add a Discord channel openclaw channel add --provider discord --token YOUR_BOT_TOKEN --guild-id YOUR_GUILD_ID --name my-discord # Add Google Chat channel openclaw channel add --provider google-chat --credentials ./service-account.json --space-id YOUR_SPACE --name my-gchat # Add Synology Chat channel openclaw channel add --provider synology --webhook-url YOUR_WEBHOOK_URL --name my-synology # Test a channel connection openclaw channel test my-telegram # Remove a channel openclaw channel remove my-telegram # Update channel config (e.g., rotate token) openclaw channel update my-telegram --token NEW_TOKEN # Enable/disable a channel without removing it openclaw channel disable my-telegram openclaw channel enable my-telegram
Skills & Model Management Commands
# List installed skills openclaw skill list # Search the skill registry openclaw skill search "web scrape" # Install a skill openclaw skill install web-scraper # Install a specific version openclaw skill install web-scraper@2.1.0 # Update a skill openclaw skill update web-scraper # Update all skills openclaw skill update --all # Remove a skill openclaw skill remove web-scraper # Show skill details and required config openclaw skill info web-scraper # List available models openclaw model list # Set the default model openclaw model use gpt-4o # Set model for a specific agent openclaw model use claude-3-7-sonnet --agent my-agent # Show current model config openclaw model show
Browser Control & Shell Execution Commands
This is where OpenClaw differentiates itself from simpler agent platforms. Browser and shell commands enable true end-to-end automation without leaving the CLI.
# Launch a managed browser session openclaw browser open --url https://example.com --session my-session # Take a screenshot openclaw browser screenshot --session my-session --output ./screenshot.png # Execute JavaScript in the browser context openclaw browser exec --session my-session --script "document.title" # Click an element by CSS selector openclaw browser click --session my-session --selector "#submit-btn" # Fill a form field openclaw browser fill --session my-session --selector "#email" --value "user@example.com" # Extract page content openclaw browser extract --session my-session --selector "article.main" --format text # Close a browser session openclaw browser close --session my-session # Run a shell command through the OpenClaw runtime openclaw shell exec --cmd "python process.py --input data.json" # Run shell command with timeout openclaw shell exec --cmd "npm run build" --timeout 120 # List active shell processes openclaw shell list
Note: Browser sessions are isolated per --session ID. Reuse the same session ID across commands to maintain state (cookies, auth tokens, page context).
File & Workspace Management Commands
# List workspace files openclaw file list # Read a file from the workspace openclaw file read output/report.md # Write content to a workspace file openclaw file write output/result.txt --content "processed" # Copy a file within the workspace openclaw file copy input/raw.json output/processed.json # Delete a workspace file openclaw file delete output/temp.json # Watch a file for changes (useful in pipelines) openclaw file watch output/result.txt --on-change "openclaw agent trigger my-agent" # Export workspace to a zip archive openclaw workspace export --output ./backup.zip # Import workspace from archive openclaw workspace import --input ./backup.zip
Real-World Workflow Examples (Command Chaining)
Automating a Content Pipeline End-to-End
This pipeline scrapes a URL, processes the content through an LLM, and posts the result to a Telegram channel — all from a single shell script.
#!/bin/bash set -e TARGET_URL="https://example.com/news" CHANNEL="my-telegram" WORKSPACE_OUT="output/summary.md" # Step 1: Scrape the page openclaw browser open --url "$TARGET_URL" --session scrape-session openclaw browser extract --session scrape-session --selector "article" \\ --format text > workspace/input/raw.txt openclaw browser close --session scrape-session # Step 2: Process with LLM via agent openclaw agent trigger content-summarizer \\ --input workspace/input/raw.txt \\ --output "$WORKSPACE_OUT" \\ --wait # Step 3: Post result to Telegram SUMMARY=$(openclaw file read "$WORKSPACE_OUT") openclaw channel send "$CHANNEL" --message "$SUMMARY" echo "Pipeline complete."
Scheduling Tasks with Cron + OpenClaw Commands
Most teams reach for cron far later than they should. Here are copy-paste patterns:
# Run a daily content pipeline at 7am 0 7 * * * /usr/local/bin/openclaw agent trigger daily-report --wait --quiet >> /var/log/openclaw-cron.log 2>&1 # Restart gateway every Sunday at 2am (maintenance window) 0 2 * * 0 /usr/local/bin/openclaw gateway restart --yes >> /var/log/openclaw-restart.log 2>&1 # Health check every 5 minutes, alert if failing */5 * * * * /usr/local/bin/openclaw gateway status --output json | \\ grep -q '"status":"running"' || \\ /usr/local/bin/openclaw channel send ops-alerts --message "Gateway DOWN"
Idempotency tip: Use --dry-run to verify cron command behavior before scheduling. Add --yes to all cron commands to skip interactive prompts. Always redirect stderr alongside stdout (2>&1) to catch flag errors in logs.
Scripting & CI/CD Integration
Output Formats and Exit Codes
Every OpenClaw command supports --output json for machine-readable output:
# Get agent status as JSON
openclaw agent status my-agent --output json
# Example output:
# {"agent":"my-agent","status":"running","uptime":3842,"pid":19204}Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Config or flag validation failure |
| 3 | Agent/gateway not reachable |
| 4 | Timeout exceeded |
| 5 | Permission denied |
Piping into Shell Scripts and GitHub Actions
# Check agent health and branch on status STATUS=$(openclaw agent status my-agent --output json --quiet | jq -r '.status') if [ "$STATUS" != "running" ]; then openclaw agent start my-agent fi
GitHub Actions example:
- name: Trigger OpenClaw content agent
run: |
openclaw agent trigger content-agent \\
--input ./keywords.json \\
--output ./output/article.md \\
--wait \\
--timeout 300 \\
--output-format json
env:
OPENCLAW_API_KEY: \ secrets.OPENCLAW_API_KEY
OPENCLAW_GATEWAY_URL: \ secrets.OPENCLAW_GATEWAY_URLSecurity & Permissions in Production
Running OpenClaw in multi-user or server environments requires deliberate permission scoping — the defaults are optimized for local development.
# Generate a scoped API key (read-only) openclaw auth key create --name ci-readonly --scopes "agent:read,channel:read" # Generate a key with specific agent access only openclaw auth key create --name deploy-bot --scopes "agent:trigger:my-agent" # List active API keys openclaw auth key list # Revoke a compromised key immediately openclaw auth key revoke KEY_ID # Store API key in system keychain (avoid plaintext in config) openclaw config set-secret api_key YOUR_KEY # Restrict workspace file access openclaw config set security.workspace_isolation true # Disable shell execution in production (if not needed) openclaw config set security.allow_shell_exec false # Enable audit logging openclaw config set logging.audit true openclaw config set logging.audit_path /var/log/openclaw/audit.log
Production Checklist
Set security.allow_shell_exec false unless your use case explicitly requires it.
Use --scopes when generating API keys — never use a root key in CI/CD.
Enable logging.audit before your first production deployment.
Rotate keys with openclaw auth key revoke + openclaw auth key create on any suspected exposure.
Troubleshooting: Symptom → Command Fix Decision Tree
Agent Not Responding
openclaw agent status my-agent → status: "stopped" → openclaw agent start my-agent → status: "error" → openclaw agent logs my-agent --tail 50 → status: "running" but unresponsive → openclaw agent stop my-agent --force && openclaw agent start my-agent
Channel Not Receiving Messages
openclaw channel test my-telegram → connection failed → openclaw channel update my-telegram --token NEW_TOKEN → connection ok but no messages → openclaw gateway logs --follow (check routing errors) → 403 error → check token scopes, re-add channel
Skill Not Loading
openclaw skill info my-skill → not installed → openclaw skill install my-skill → version conflict → openclaw skill update my-skill → config missing → openclaw skill info my-skill (check required fields), then openclaw config set
Gateway Won't Start
openclaw config validate → invalid config → fix reported field, retry → port conflict → openclaw config set gateway.port 8081 → permission error → check OPENCLAW_ env vars, run openclaw config env
What Changed in v2026.4.21 — Command Diff from Earlier 2026 Builds
If you're working from a cheatsheet dated January or February 2026, these changes will break your scripts:
| Area | Old syntax (pre-April 2026) | New syntax (v2026.4.21) |
|---|---|---|
| Channel add | --type telegram | --provider telegram |
| Model switch | openclaw agent model use | openclaw model use --agent |
| Shell execute | openclaw exec shell | openclaw shell exec |
| Key creation | openclaw auth create-key | openclaw auth key create |
| Output flag | --format json | --output json |
| Config secrets | openclaw config set-key | openclaw config set-secret |
New in v2026.4.21
openclaw file watchcommand (file change triggers)--dry-runglobal flag added to all mutating commandssecurity.workspace_isolationconfig key- Audit logging via
logging.audit openclaw channel disable/openclaw channel enable(previously required full remove + re-add)
Deprecated (removed in v2026.4.21)
openclaw agent reload --hard— useopenclaw agent stop --force && openclaw agent startopenclaw config get-all— replaced byopenclaw config show
Final Reference: Printable OpenClaw Commands Cheatsheet
| Command | Syntax | Key Flags | Example |
|---|---|---|---|
| Init project | openclaw init | --yes, --profile | openclaw init --yes |
| Show config | openclaw config show | --output json | openclaw config show |
| Start gateway | openclaw gateway start | --daemon | openclaw gateway start --daemon |
| Agent status | openclaw agent status | --output json | openclaw agent status my-agent --output json |
| Agent logs | openclaw agent logs | --follow, --tail | openclaw agent logs my-agent --tail 50 |
| Add channel | openclaw channel add | --provider, --token | openclaw channel add --provider telegram --token XXX |
| Test channel | openclaw channel test | — | openclaw channel test my-telegram |
| Send message | openclaw channel send | --message | openclaw channel send my-telegram --message "done" |
| Install skill | openclaw skill install | @version | openclaw skill install web-scraper@2.1.0 |
| Set model | openclaw model use | --agent | openclaw model use gpt-4o --agent my-agent |
| Browser open | openclaw browser open | --url, --session | openclaw browser open --url https://example.com --session s1 |
| Extract content | openclaw browser extract | --selector, --format | openclaw browser extract --session s1 --selector "article" |
| Run shell cmd | openclaw shell exec | --cmd, --timeout | openclaw shell exec --cmd "python run.py" |
| Read file | openclaw file read | — | openclaw file read output/result.md |
| Trigger agent | openclaw agent trigger | --input, --output, --wait | openclaw agent trigger pipeline --wait |
| Create API key | openclaw auth key create | --name, --scopes | openclaw auth key create --name ci --scopes "agent:read" |
| Validate config | openclaw config validate | — | openclaw config validate |
Why EasyClaw Is the Smarter Way to Run Agent Workflows
OpenClaw gives you powerful CLI primitives. EasyClaw gives you a desktop-native AI agent layer that runs those pipelines — browser automation, LLM processing, channel delivery — without stitching bash scripts together at midnight.
- Visual pipeline builder on top of OpenClaw primitives
- Runs locally — no cloud vendor lock-in, no per-seat pricing
- Built-in skill marketplace: install, configure, run in seconds
- Native scheduling, retry logic, and audit logging out of the box
- Works with any model: GPT-4o, Claude, Gemini, or your own self-hosted LLM
Frequently Asked Questions
Q: What is the difference between openclaw gateway start and openclaw agent start?
A: The gateway is the host process that manages the HTTP/WebSocket runtime. You start it once. Agents are individual task workers registered to that gateway — you start, stop, and monitor them independently. Think of the gateway as the server and agents as the application processes running on it.
Q: My scripts broke after upgrading to v2026.4.21. What changed?
A: Several command signatures changed in v2026.4.21. The most common breaking changes are: --type → --provider for channel add, --format json → --output json globally, and openclaw exec shell → openclaw shell exec. See the full diff table in the changelog section above.
Q: How do I run OpenClaw commands non-interactively in CI/CD pipelines?
A: Add the --yes flag to skip confirmation prompts, use --output json for machine-parseable output, and pass credentials via OPENCLAW_API_KEY and OPENCLAW_GATEWAY_URL environment variables. Never store raw keys in config files committed to version control.
Q: Can I use OpenClaw browser commands with an existing authenticated session?
A: Yes. Browser sessions are isolated by --session ID. As long as you reuse the same session ID across commands, cookies, auth tokens, and page state are preserved. Sessions persist until you explicitly call openclaw browser close --session SESSION_ID or the gateway restarts.
Q: What's the safest way to handle API key rotation in production?
A: Create the new key first with openclaw auth key create --name new-key --scopes "...", update your secrets store, verify the new key works, then revoke the old key with openclaw auth key revoke OLD_KEY_ID. Never revoke the old key before confirming the new one is functional.
Q: How do I debug a pipeline that fails silently in cron?
A: Always redirect both stdout and stderr in your cron entries (>> /var/log/openclaw-cron.log 2>&1). Run the exact cron command manually first with --log-level debug to surface hidden errors. Use openclaw config env to verify environment variables are resolving correctly in the cron execution context.
Q: Is it possible to restrict which agents a CI/CD key can trigger?
A: Yes. Use granular scopes when creating keys: openclaw auth key create --name deploy-bot --scopes "agent:trigger:my-specific-agent". This prevents a compromised CI key from triggering unrelated agents or accessing channel configurations.
Final Thoughts
The OpenClaw CLI is a complete runtime control surface — from first-time setup to production security hardening. The challenge has never been capability; it's always been knowing which command to reach for when something breaks at an inconvenient hour.
Bookmark this page. Use the cheatsheet table as your quick-reference. When a pipeline fails, start with the troubleshooting decision trees — they'll get you to the right command in under a minute.
And if you find yourself spending more time maintaining pipeline scripts than building actual workflows, that's the signal to try EasyClaw — it handles the orchestration layer so you can focus on what your agents actually do.
Quick Recap: Key Commands to Bookmark
openclaw config validate— always run this before restarting the gatewayopenclaw agent logs my-agent --tail 50— first stop when an agent misbehavesopenclaw channel test my-channel— faster than reading logs to confirm channel issuesopenclaw config show --output json— verify resolved config in any environmentopenclaw auth key revoke KEY_ID— immediate response to any suspected key exposure