openclaw run — Execute AI Tasks

The primary command for running AI agent tasks from the command line. Accepts any natural language description and executes it autonomously.

Reference7 min read

Synopsis

openclaw run [OPTIONS] "<task description>"

The run command is the most frequently used command in the OpenClaw CLI. It accepts a natural language task description, sets up an autonomous agent, and executes the task step by step. The agent can read and write files, run shell commands, call APIs, and interact with your system within configurable boundaries.

Description

When you invoke openclaw run, the following happens internally:

  1. The task description is parsed and sent to the configured LLM provider.
  2. The agent creates an execution plan broken into discrete steps.
  3. Each step is executed using the available tools (filesystem, shell, web, etc.).
  4. Results are evaluated and the plan is adjusted as needed.
  5. Final output is returned to stdout or written to the specified file.
📝
Task scope

By default, OpenClaw has access to the current working directory. Use --context to specify a different path or limit the scope to a specific file or folder.

Options & Flags

FlagTypeDefaultDescription
--providerstringopenaiLLM provider: openai, claude, ollama, gemini
--modelstringgpt-4oModel name to use for this task
--max-stepsint20Maximum number of agent execution steps
--timeoutint300Timeout in seconds before aborting
--dry-runflagfalsePreview planned actions without executing them
--verboseflagfalseShow detailed step-by-step execution logs
--quietflagfalseSuppress all output except the final result
--outputstringstdoutWrite result to this file path
--formatstringtextOutput format: text, json, markdown
--contextpathnoneFile or directory to provide as agent context
--profilestringdefaultConfiguration profile name to use
--no-confirmflagfalseSkip all confirmation prompts automatically

Usage Examples

1. Basic File Summarization

Summarize all text files in a directory:

openclaw run "Summarize all .txt files in ~/docs"

Expected output:

Found 12 .txt files in ~/docs.

report.txt (2.3 KB): Monthly sales report covering Q4 2025...
notes.txt (1.1 KB): Meeting notes from Dec 15 standup...
[...]

Summary complete. 12 files processed.

2. Contextual Code Review

Review source code for security issues and output a markdown report:

openclaw run --context ./src "Review this code for security issues" --format markdown --output security-report.md

3. Dry Run Preview

Preview what actions would be taken without actually executing them:

openclaw run --dry-run "Delete all .tmp files older than 30 days in /tmp"
[DRY RUN] Planned actions:
  1. Scan /tmp for .tmp files
  2. Filter files older than 30 days
  3. [WOULD DELETE] /tmp/cache_a1b2.tmp (45 days old, 2.1 MB)
  4. [WOULD DELETE] /tmp/session_xy99.tmp (32 days old, 0.3 MB)

No changes made. Re-run without --dry-run to execute.

4. Custom Provider & Model

Use Claude Sonnet instead of the default OpenAI provider:

openclaw run --provider claude --model claude-3-5-sonnet "Explain this codebase architecture" --context .

5. JSON Output for Scripting

Output structured JSON for use in automation pipelines:

openclaw run "List all Python functions in project" --format json --output functions.json --context ./src
{
  "task": "List all Python functions in project",
  "status": "completed",
  "steps_used": 8,
  "result": {
    "functions": [
      {"name": "parse_config", "file": "config.py", "line": 12},
      {"name": "run_agent", "file": "agent.py", "line": 47}
    ],
    "total": 2
  }
}

Exit Codes

CodeMeaning
0Task completed successfully
1Error — task failed due to agent or tool error
2Timeout — task exceeded the configured timeout
3Aborted — user cancelled with Ctrl+C or confirmation rejected
💡
Scripting tip

Check exit codes in shell scripts with $? (bash) or $LASTEXITCODE (PowerShell) to detect failures and implement error handling in automated pipelines.

💡
See Also
← CLI Commands openclaw start →