CLI Commands Reference | OpenClaw AI Documentation

Command Overview

Command	Description
`openclaw run`	Execute an AI agent task
`openclaw config`	Manage configuration settings
`openclaw agent`	Manage saved agents
`openclaw status`	Check system status
`openclaw logs`	View execution logs
`openclaw serve`	Start REST API server
`openclaw ping`	Test LLM provider connection
`openclaw doctor`	Run system diagnostics
`openclaw version`	Print version information

openclaw run

The primary command for executing AI agent tasks. Accepts a natural language task description.

openclaw run [OPTIONS] "TASK"

Run an autonomous AI agent to complete the given task. The agent will plan, execute tools, and report results.

Options

Flag	Default	Description
`--provider, -p`	config	Override LLM provider for this run
`--model, -m`	config	Override model (e.g. gpt-4o-mini)
`--profile`	default	Use a named config profile
`--max-steps`	25	Maximum agent steps before stopping
`--dry-run`	false	Plan but don't execute any actions
`--verbose, -v`	false	Show each thought, action, observation
`--output, -o`	stdout	Save result to a file
`--format`	text	Output format: text \| json \| markdown
`--tools`	all	Comma-separated list of allowed tools
`--timeout`	180	Max seconds for task execution

Examples

# Simple task
openclaw run "What Python version is installed on this system?"

# File operations
openclaw run "Find all .log files in /var/log larger than 100MB and list them"

# Code generation
openclaw run "Write a Python script that reads a CSV and outputs a JSON summary"

# With specific model
openclaw run "Review my code for security issues" -m gpt-4o --verbose

# Dry run (show plan without executing)
openclaw run "Delete all .tmp files in the current directory" --dry-run

# Save output to file
openclaw run "Generate a project README" -o README.md --format markdown

# Using only specific tools
openclaw run "Search for OpenAI latest news" --tools web_search,web_scrape

$ openclaw run "List all Python files in the current directory, show line counts" --verbose

🤖 OpenClaw Agent v1.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Task: List all Python files in the current directory, show line counts
🔧 Provider: openai (gpt-4o)
🛠  Tools: shell_exec, file_read

💭 Step 1 — Thought: I need to find all .py files and count their lines.
⚡ Action: shell_exec
   → Command: find . -name "*.py" -exec wc -l {} +
📊 Observation: (13 files found)

💭 Step 2 — Thought: I have the list. I'll format it into a clean table.
⚡ Action: (final answer)

✅ Completed in 2 steps (3.4s)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Results:
  120  ./main.py
   87  ./config.py
   54  ./utils.py
  [10 more files...]
  Total: 892 lines

openclaw config

Manage your OpenClaw configuration settings.

# Show all current settings (API keys masked)
openclaw config show

# Set a value
openclaw config set provider openai
openclaw config set api_key sk-...
openclaw config set model gpt-4o
openclaw config set agent.max_steps 30

# Get a specific value
openclaw config get provider

# Reset to defaults
openclaw config reset

# Initialize fresh config
openclaw config init

# Edit config in your default editor
openclaw config edit

# Profile management
openclaw config profile create staging --provider anthropic
openclaw config profile list
openclaw config profile use staging
openclaw config profile delete staging

openclaw agent

Save, load, and manage reusable named agents with predefined configurations and system prompts.

# Create a new named agent
openclaw agent create code-reviewer \
  --model gpt-4o \
  --system "You are an expert Python security auditor. Be thorough and precise."

# List saved agents
openclaw agent list

# Run a task using a named agent
openclaw agent run code-reviewer "Review the security of ./app.py"

# Show agent configuration
openclaw agent show code-reviewer

# Update an existing agent
openclaw agent update code-reviewer --model claude-3-5-sonnet-20241022

# Delete an agent
openclaw agent delete code-reviewer

# Export/import agents
openclaw agent export code-reviewer > agent.yaml
openclaw agent import agent.yaml

openclaw serve

Start the OpenClaw REST API server for programmatic access or web integrations.

# Start server on default port 8080
openclaw serve

# Custom host and port
openclaw serve --host 0.0.0.0 --port 3000

# With authentication
openclaw serve --auth-token mySecretToken123

# Limit concurrent tasks
openclaw serve --max-concurrent 5

The server exposes:

Endpoint	Method	Description
`/v1/run`	POST	Execute a task (async)
`/v1/status/:id`	GET	Check task status
`/v1/result/:id`	GET	Get task result
`/v1/health`	GET	Server health check

openclaw logs

# Show last 50 log entries
openclaw logs

# Follow logs in real-time
openclaw logs --follow

# Show only errors
openclaw logs --level error

# Show logs for a specific run
openclaw logs --run-id abc123

# Clear all logs
openclaw logs --clear

openclaw status & doctor

# Quick status check
openclaw status
# Shows: Python version, config path, provider, model, memory usage

# Full diagnostic check
openclaw doctor
# Checks: Python version, dependencies, config, provider connectivity,
#          tools availability, disk space, optional components

Global Flags

These flags work with all commands:

Flag	Description
`--config PATH`	Use a custom config file path
`--no-color`	Disable colored output
`--json`	Output in JSON format
`--quiet, -q`	Suppress all output except errors
`--version`	Print version and exit
`--help, -h`	Show help for any command

🔗

See Also

Use Cases — See these commands in real-world automation workflows.

Automation Examples — Ready-to-run scripts using OpenClaw CLI.

Troubleshooting — Fix common command errors and unexpected output.

← Previous

Configuration

Use Cases