OpenClaw CLI Commands Every New User Should Know

Most people bounce off AI agent frameworks within the first 48 hours. Not because the technology is bad, but because the CLI experience is genuinely terrible. You install the thing, stare at a blinking cursor, type some command you found in documentation that's already outdated, and get back an error message that might as well say "good luck, buddy."

I've been there. Multiple times, across multiple frameworks. And every time, the pain points are the same: you can't see what your agent is doing, you can't control how much it's spending, you can't debug when it breaks, and you can't share what you've built with anyone else without a 45-minute walkthrough over Zoom.

OpenClaw fixes most of this. Not all of it — no tool is perfect — but the CLI was clearly designed by people who've actually tried to use AI agents in production and got frustrated by the same stuff we all get frustrated by.

Here are the commands you actually need to know, organized by the problems they solve.

---

Getting Started Without the Configuration Circus

The single biggest barrier to entry with most agent frameworks is the setup ritual. You need a virtual environment, a dozen config files scattered across directories, Python boilerplate, and some kind of arcane initialization sequence. By the time you've written your first agent, you've already forgotten why you started.

OpenClaw gives you two paths. The fast path:

openclaw quick "Search for AI news and summarize the top 5 articles" \
  --tools web_search,web_scrape \
  --model gpt-4

That's it. No config files. No Python. No YAML. You type a command, specify what tools the agent can use, pick your model, and it runs. If you're just trying to see whether OpenClaw can solve your problem, this is where you start.

The structured path is for when you know you're going to run this agent more than once:

openclaw init my-research-agent

This creates a single YAML file — not five, not twelve, one — that contains everything your agent needs:

name: research_agent
model: gpt-4-turbo
tools:
  - web_search
  - web_scrape
  - markdown_writer

task: "Research {topic} and create a summary report"

limits:
  max_cost: 5.00
  timeout: 300

Then you run it:

openclaw run my-research-agent.yaml --vars topic="quantum computing"

The --vars flag is one of those small things that makes a huge difference. Instead of hardcoding inputs, you parameterize your agent config once and swap variables at runtime. This means one agent definition can serve dozens of use cases.

---

Seeing What Your Agent Is Actually Doing

Here's a scenario that happens constantly: you kick off an agent run, and it just... sits there. The cursor blinks. Nothing happens for 30 seconds. Then 60. Is it working? Is it stuck? Did it crash silently? You have literally no way to know.

This is the number one complaint I see across every AI agent community, and OpenClaw's answer is straightforward:

openclaw run --verbose agent.yaml

The --verbose flag gives you real-time output that actually tells you what's happening:

[12:34:01] 🔍 Analyzing task: "Find competitor pricing"
[12:34:02] 🧠 Planning: 3 steps identified
[12:34:03] 🔧 Calling tool: web_search(query="competitor X pricing 2026")
[12:34:05] 📊 Processing 12 search results
[12:34:06] 🔧 Calling tool: extract_price(url="https://competitor.com/pricing")
[12:34:08] ✅ Step 1/3 complete

Every tool call, every decision point, every intermediate result — visible in real time. You can actually watch your agent think.

For deeper debugging, there's --trace:

openclaw run --trace --output trace.json agent.yaml

This generates a full decision tree: every LLM call with the exact prompt and response, every tool invocation with parameters and return values, every branching point where the agent chose one path over another. When something goes wrong — and it will — this is how you figure out why.

---

Stopping Your Agent From Draining Your Bank Account

I once read a Hacker News thread where someone's agent racked up $200 in API calls overnight because it got stuck in a loop. Two hundred dollars. For an experiment. That's not a typo and it's not an exaggeration — it happens more than you'd think.

OpenClaw builds cost controls directly into the CLI:

openclaw run agent.yaml \
  --max-cost 5.00 \
  --max-iterations 20 \
  --timeout 300

Three flags. Hard ceiling on spending. Hard ceiling on iterations. Hard ceiling on time. The agent stops the moment it hits any of these limits, no exceptions.

But the really useful part is the real-time cost tracking that shows up during execution:

[12:34:15] 💰 Running cost: $0.47 / $5.00 (9.4%)
[12:34:16] 🔧 Tool: web_search (+$0.02)
[12:34:18] 🤖 LLM call: gpt-4 (+$0.15)
[12:35:02] ⛔ STOPPED: Cost limit reached ($5.01)

You can also bake these limits directly into your YAML config so they're always active:

limits:
  max_cost: 10.00
  max_tool_calls: 50
  max_iterations: 30
  timeout_seconds: 600

This is the kind of feature that sounds boring until it saves you real money. Set it once, forget about it, and never wake up to a surprise bill.

---

Adding Tools Without Writing Integration Code

Integrating external tools with most agent frameworks requires writing custom code — sometimes substantial custom code — for every single API, service, or function you want your agent to access. It's tedious, error-prone, and the interfaces are different in every framework.

OpenClaw's tool add command handles the three most common integration patterns:

# From an OpenAPI spec (works with most modern APIs)
openclaw tool add my-api \
  --from openapi https://api.example.com/openapi.json

# From a Python function
openclaw tool add my-tool \
  --from python ./tools/my_tool.py:my_function

# From MCP (Model Context Protocol)
openclaw tool add filesystem \
  --from mcp @modelcontextprotocol/server-filesystem

The MCP integration is particularly nice because it means you instantly get access to a growing ecosystem of pre-built tool servers. Need Slack? Jira? File system access? Database queries?

openclaw tool add slack --from mcp @modelcontextprotocol/server-slack
openclaw tool add jira --from openapi https://my-jira.com/api/openapi.json
openclaw tool add internal --from python ./internal_api.py:make_request

Register once, reference by name in any agent config, done. No wrapper classes, no adapter patterns, no boilerplate.

---

Debugging Without Re-Running Everything

Your agent successfully scraped 20 websites, processed the data from 17 of them, and then crashed on number 18 because of a timeout. In most frameworks, your only option is to start over from scratch. All 20 websites. All that time. All those API calls.

OpenClaw keeps a run log, and the replay and resume commands let you work with it:

# See exactly what happened at step 18
openclaw replay last-run.log --step 18 --verbose

# Fix the issue, then resume from where it broke
openclaw resume last-run.log --from-step 18

The replay command can also step through an entire execution interactively:

openclaw replay last-run.log --debug

This lets you pause at each step, inspect the state, and understand the agent's decision-making. It's the difference between printf debugging and having an actual debugger.

When something fails, the error messages also include actionable suggestions:

[12:40:15] ❌ Tool execution failed: web_scrape
           URL: https://example.com/page
           Error: Timeout after 30s
           Suggestion: Try increasing timeout with --tool-timeout 60
           Debug: openclaw replay --step 15 agent.log

That Suggestion line alone saves more time than you'd think.

---

Testing Without Burning Credits

Every test run costs money. Every iteration costs money. Every "let me just try one thing" costs money. This creates a horrible incentive: you either test thoroughly and spend a fortune, or you skip testing and ship broken agents. Neither option is good.

OpenClaw gives you three ways to test without spending:

Dry run mode shows you what would happen without making any API calls:

openclaw run agent.yaml --dry-run

🔍 DRY RUN - No actual API calls will be made
[Plan] Would call: web_search(query="...")
[Plan] Would call: extract_data(url="...")
[Plan] Would generate: report.md
💰 Estimated cost: $0.45
⏱️  Estimated time: ~30 seconds

Record/replay mode lets you capture one real run and replay it infinitely for free:

# Record real responses once
openclaw run agent.yaml --record responses.json

# Replay as many times as you want — zero API calls
openclaw run agent.yaml --replay responses.json

Deterministic mode ensures identical results across runs, which is essential for regression testing:

openclaw run agent.yaml --seed 42 --temperature 0

You can even build formal test suites:

openclaw test create regression-suite \
  --agent agent.yaml \
  --cases test-cases.json \
  --seed 42

openclaw test run regression-suite
# ✅ 47/50 tests passed
# ❌ 3 regressions detected

For anyone building agents that need to work reliably in production, this workflow is non-negotiable.

---

Sharing Agents With Your Team

"Works on my machine" is already a meme in software development, but it's even worse with AI agents because the config surface area is so large: model settings, tool registrations, prompt templates, environment variables, dependency versions.

OpenClaw's export/import system bundles everything together:

# Package the agent with all dependencies
openclaw export research-agent.yaml \
  --with-tools \
  --with-prompts \
  --output research-agent-v1.tar.gz

# Team member imports and runs immediately
openclaw import research-agent-v1.tar.gz
openclaw run research-agent --vars topic="market analysis"

For broader distribution, there's a publish/install workflow:

openclaw publish agent.yaml --name "research-agent" --version 1.2.0

# Anyone can install and run
openclaw install research-agent@1.2.0
openclaw run research-agent

This transforms agents from fragile scripts that live on one person's laptop into portable, versioned artifacts that a whole team can rely on.

---

The Cheat Sheet

Here's every command mentioned above in one place, organized by workflow:

What You're Doing	Command
Quick one-off task	openclaw quick "task" --tools x,y --model gpt-4
Create agent config	openclaw init my-agent
Run agent	openclaw run agent.yaml --vars key="value"
See what's happening	openclaw run agent.yaml --verbose
Full execution trace	openclaw run agent.yaml --trace --output trace.json
Set cost limit	openclaw run agent.yaml --max-cost 5.00
Set iteration limit	openclaw run agent.yaml --max-iterations 20
Set timeout	openclaw run agent.yaml --timeout 300
Add tool (OpenAPI)	openclaw tool add name --from openapi URL
Add tool (Python)	openclaw tool add name --from python path:function
Add tool (MCP)	openclaw tool add name --from mcp package
Dry run (no cost)	openclaw run agent.yaml --dry-run
Record responses	openclaw run agent.yaml --record file.json
Replay responses	openclaw run agent.yaml --replay file.json
Debug failed step	openclaw replay run.log --step N --verbose
Resume from failure	openclaw resume run.log --from-step N
Deterministic mode	openclaw run agent.yaml --seed 42 --temperature 0
Export agent	openclaw export agent.yaml --output bundle.tar.gz
Import agent	openclaw import bundle.tar.gz
Run test suite	openclaw test run suite-name

---

Skip the Setup Grind

Look, I've walked you through the commands, and honestly, the CLI itself is clean enough that you'll figure most of it out. But there's a difference between knowing the commands and having a well-structured starting point that actually works.

If you don't want to set all this up manually — the YAML configs, the tool registrations, the limit settings, the testing workflows — Felix's OpenClaw Starter Pack on Claw Mart is worth the $29. It includes pre-configured skills and agent templates that cover the most common use cases: research agents, data processing pipelines, content workflows. The configs already have sensible cost limits, tool integrations, and trace settings baked in. You import it, swap in your variables, and you're running.

I spent my first week with OpenClaw building all of this from scratch. It was educational, but it wasn't efficient. If your goal is to get productive fast rather than learn through trial and error, starting from a tested foundation saves real time.

---

What to Do Next

Start with openclaw quick to validate that OpenClaw can handle your use case. Don't over-invest in configuration until you've proven the concept works.

Once it does, move to a YAML config with openclaw init. Add --max-cost and --timeout flags from day one — not after your first surprise bill.

Use --record and --replay religiously during development. The cost savings compound fast, and the ability to iterate on agent logic without burning credits changes how you work.

And when you break something — which you will — openclaw replay --debug is your best friend. Don't guess. Trace.

The CLI is the interface you'll spend 90% of your time in. Learn these commands, and everything else about OpenClaw gets easier.