OpenClaw: A Practical Guide to Running a Local Autonomous AI Agent 2

I refuse to answer that question on the grounds that I don’t know the answer, Douglas Adams

When I was a boy the Dead Sea was only sick, George Burns

1. The workspace: AGENTS.md, SOUL.md, skills, and memory

All files live in ~/.openclaw/. In Windows: C:\Users\Your_UserName\.openclaw\ or C:\Users\W6-N5\.openclaw\.

• workspace: agent files, memory, tasks
• config.yaml: global configuration

They are injected into the agent’s context on every turn. They are core files that define the agent’s personality, identity, and behavior.

Skills are directories under workspace/skills/skill/SKILL.md, each with YAML frontmatter and instructions. OpenClaw loads skills from three locations, with the workspace taking precedence on name conflicts:

1. Managed/local: ~/.openclaw/skills
2. Workspace: workspace/skills

Skills are supplemental domain guidance; they do not replace or modify AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, or USER.md.

openclaw config set agents.defaults.instructions "You are MyPi. Follow SOUL.md."

# SOUL
You are MyPi, a meticulous, encouraging proofreader and technical editor.

## Tone
Direct, practical, warm but not chatty. Light, occasional humor is fine in
creative work; keep technical reviews focused.

## Style
Clear English. Concise explanations. No unnecessary filler.

## Default behavior
Proofread first, then suggest improvements. Distinguish required fixes
(correctness, clarity, consistency, LaTeX/math, broken logic, accessibility,
Markdown/front-matter issues) from optional style changes. Preserve the
author's voice; improve precision rather than making writing sound corporate.

## Boundaries
Explain important changes briefly. Do not rewrite the author's argument.

2. Web search and fetch

OpenClaw ships with web_search and web_fetch tools. web_fetch works without a key. web_search needs a provider, and the recommended one is Brave Search.

DuckDuckGo is the zero-cost option: no API key, no account. It is also explicitly experimental and unofficial.

# 1. Install the plugin
openclaw plugins install @openclaw/duckduckgo-plugin
# 2. Restart the gateway
openclaw gateway restart
# This order matters. Plugins are loaded when the Gateway starts, 
# so restart **after installing the plugin, before configuring the provider.**

# 3. Select DuckDuckGo explicitly
openclaw configure --section web
# When prompted, choose DuckDuckGo. The provider must be selected explicitly
# This is not optional. Because DuckDuckGo has no credentials, auto-detection will never pick it. 
# You must select it, either through the wizard or directly in config:
{
  tools: {
    web: {
      search: {
        provider: "duckduckgo"
      }
    }
  }
}

# 4. Testing the configuration
# Check what provider is effective and whether it is reachable
# From the CLI
openclaw status --deep
# From the UI: Setting, Search, e.g., 
DuckDuckGo Search (experimental) Provider search
Configure provider... DuckDuckGo Search (experimental)
# From the agent
openclaw agent --agent main --message \
  'Use web_search to find the OpenClaw plugin SDK docs, then web_fetch the top result.'

3. Automation: heartbeat and cron

OpenClaw has two scheduling mechanisms, and the distinction matters.

Before this version, heartbeats were a hidden background mechanism — they ran somewhere inside OpenClaw, but you couldn’t really inspect or manage them through the normal tooling. From v2026.8.1 onward, heartbeats were promoted to first-class citizens of the automation system: they live in the same scheduler that powers your user-defined cron jobs.

So instead of being a black-box background thread, a heartbeat is now just a cron job that OpenClaw happens to own. It uses the same execution engine, the same run history, and the same status reporting.

A heartbeat is a periodic “are you alive?” check that runs against an agent. Think of it as the agent’s pulse:

• The scheduler fires the heartbeat job on a fixed cadence (default: every 60 seconds, configurable per agent).
• The job pings the agent — verifies the process is responsive, the model endpoint is reachable, and any registered tools are still loadable.
• If the ping fails or times out, OpenClaw marks the agent as degraded and can trigger alerts, restarts, or failover depending on your policy.
• If the ping succeeds, the agent’s lastHeartbeatAt timestamp is updated and the next tick is scheduled.

# Heartbeat jobs are hidden from the default cron list output to keep noise down.
# Lists only your user-defined cron jobs. Heartbeat jobs are filtered out here so they don't clutter the view. 
openclaw cron list
# Lists every scheduled job, including system-owned heartbeats. 
# This is the command to reach for when you suspect a heartbeat is misbehaving — it lets you grab the job ID you'll need for the next command.
openclaw cron list --all

# Shows the run history for a specific job — each invocation, when it started, how long it took, whether it succeeded, and any error output.
# This is your primary debugging tool when an agent is reporting as degraded — you can see exactly which heartbeat ticks failed and why.
openclaw cron runs jobId

# This command directly answers the most common question: "When was the last successful heartbeat for each of my agents?"
# Use this as your at-a-glance health dashboard 
openclaw system heartbeat last
Agent                Last heartbeat           Status    Latency
──────────────────── ──────────────────────── ────────── ────────
agent-prod-7f3a      2026-10-22 14:31:02 UTC  healthy    142ms
agent-staging-c2     2026-10-22 14:30:58 UTC  healthy    89ms
agent-edge-9912      2026-10-22 14:29:11 UTC  degraded   timeout

# Reports on the scheduler itself — is the cron engine running, how many jobs are queued, are there any stuck executions, 
# what's the average tick latency. This is a system-level diagnostic, not an agent-level one.
openclaw cron status

4. Diagnostics: the first 60 seconds, maybe more :)

When something breaks — the agent stops responding, a channel goes silent, a cron run fails — resist the urge to start digging through log files. Instead, run the five commands below in order. This ladder is engineered to take you from “it’s broken” to “here’s the specific cause” in under a minute, with each step narrowing the search space.

# 1. Quick local summary. Verifies the CLI can reach its local state, the config file parses, 
# and basic environment info is correct. 
# If this fails, your problem is at the install or config level — no point going deeper until it's green.
openclaw status               
# 2. Runs every available diagnostic and emits a single redacted report. 
# This is the command to share when asking for help.
openclaw status --all           
# 3. Extends the report with live network probes: it pings the model provider endpoints, 
# checks gateway connectivity, validates webhook URLs, and confirms scheduled jobs are actually firing. 
openclaw status --deep 
# 4. Zooms in on the gateway supervisor specifically: PID, uptime, memory footprint, last restart reason, last error message. 
# The gateway is the long-running process that brokers messages between channels and agents — if it has crashed or wedged,
# every channel will appear dead even though the agent itself is healthy.          
openclaw gateway status          
# 5. Tail the live log stream. By the time you reach this step, 
# the previous commands have told you where to look; the logs tell you why. 
openclaw logs --follow           

4.1 Log and config locations

OpenClaw scatters its artifacts across a few well-defined locations. Knowing where each lives turns “I need to check the logs” into a one-line command instead of a hunt.

4.2 openclaw doctor

While openclaw status is a read-only diagnostic, openclaw doctor is the repair and migration tool. It detects stale config from older versions, fixes corrupted state rows, validates auth token shape, checks sandbox integrity, and — critically — tells you exactly what it can and cannot fix automatically.

Run it after every upgrade, after a crash, or whenever openclaw status reports something it can’t explain.

# Walks every subsystem, prints a categorized report (OK, WARN, FAIL) with a one-line explanation per finding. 
# No files are touched. Start here when you're unsure what's wrong.
openclaw doctor                             

# Applies every repair that's safe to auto-apply: migrating deprecated config keys, 
# pruning stale heartbeat records, rebuilding missing state indexes, refreshing expired tokens stored locally
openclaw doctor --fix                        

openclaw doctor --lint                       # read-only, structured JSON output for CI
openclaw doctor --deep                       # deeper checks: sandbox exec, provider auth round-trips

# Nuclear option for gateway auth issues. 
# If the supervisor token has been corrupted, revoked, or never created, this forces a fresh one and rewrites the config entry
openclaw doctor --generate-gateway-token     

5. Backup, secrets, and updates

5.1 Backup is a second secret store

A full OpenClaw backup is not just configuration. It is a complete snapshot of everything that makes your agent your agent:

• Authentication profiles and provider credentials
• Channel credentials (WhatsApp sessions, Telegram bot tokens, Discord tokens)
• Session history and transcripts
• Agent workspaces, including AGENTS.md, SOUL.md, skills, and memory
• Plugin state
• A credentials directory outside the state directory, when one exists

Treat the archive like a password file. Store it encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure.

# Stop the Gateway first: a live SQLite database can be captured mid-write
openclaw gateway stop

# The current recommended backup command uses backup create, not bare backup, and supports --verify.
# --verify is optional, but recommended: it checks the archive after creation so you can catch a bad backup right away. 
# Backup — saves config, workspace, and state, so you can restore it in a new machine or after system failure
# "$env:USERPROFILE\Backups\openclaw" expands to something like C:\Users\YourName\Backups\openclaw.
openclaw backup create --output "$env:USERPROFILE\Backups\openclaw" --verify

# Restore to a staging directory
openclaw backup restore .\openclaw-backup.tar.gz --target "$env:USERPROFILE\openclaw-restored"

# Review manifest.json, then activate
# Option A: move assets to their recorded destinations
# Option B: point the Gateway at the restored state
$env:OPENCLAW_STATE_DIR = "$env:USERPROFILE\openclaw-restored\state"
# After restoring, run openclaw doctor to apply config migrations and repair services.

5.2 Secrets

OpenClaw’s secrets system is built around SecretRefs: references to secrets stored outside the main config, so openclaw.json never contains plaintext credentials.

# 1. Audit for plaintext and unresolved refs
openclaw secrets audit --check
# Exit code 1 on findings, 2 on unresolved refs — useful in CI

# 2. Build a plan interactively
openclaw secrets configure --plan-out "$env:TEMP\openclaw-secrets-plan.json"

# 3. Validate the plan without writing
openclaw secrets apply --from "$env:TEMP\openclaw-secrets-plan.json" --dry-run

# 4. Apply it
openclaw secrets apply --from "$env:TEMP\openclaw-secrets-plan.json"

# 5. Confirm the runtime picked it up
openclaw secrets reload

This reduces the blast radius of a config leak and keeps openclaw.json shareable for debugging (with OPENCLAW_SHOW_SECRETS=0 set before pasting openclaw status output).

5.3 Update

# Update to latest version — run it regularly for bug fixes
# Besides, the project moves quickly, and Node compatibility changes between releases
openclaw update

5.4 Uninstall

openclaw gateway stop
openclaw uninstall
# For automation or a fully non-interactive removal:
openclaw uninstall --all --yes --non-interactive

# The CLI binary is kept unless you remove the global npm package:
npm uninstall -g openclaw

# For a **complete** removal, also delete the state directory:
Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"
# Add rm -rf ~/.openclaw for complete removal (macOS)

6. OpenRouter Free Models in OpenClaw

Use OpenRouter’s free‑model router (openrouter/openrouter/free) from within OpenClaw so that the system automatically picks an available free model that supports your request. This eliminates the need to hard‑code a specific model name and lets you take advantage of OpenRouter’s free‑tier selection.

1. Prerequisites: OpenRouter account, API key with free‑model access. Sign up at OpenRouter, then create an API key in the dashboard.

2. Authenticate OpenClaw to OpenRouter. This stores your API key securely in OpenClaw’s credential manager — the key itself is never written to chat or logs.

   openclaw models auth login --provider openrouter --method api-key
   # You’ll be prompted to paste your OpenRouter API key.
   # The key is stored in OpenClaw’s credential store, not written to chat or logs.
   
   # Set the free router as your default model
   # `openrouter` = the provider name configured in step 2.1.
   # `openrouter/free` = OpenRouter's special router that dynamically selects an available free model.
   openclaw models set openrouter/openrouter/free
   
   # You still need an OpenRouter API key for actual inference: 
   echo $OPENROUTER_API_KEY
   # If it is empty, set it (or store it in OpenClaw’s config):
   export OPENROUTER_API_KEY="sk-or-v1-..."
   openclaw config set env.OPENROUTER_API_KEY "$OPENROUTER_API_KEY"
   # Restart the gateway so the running OpenClaw process picks up the new default:
   openclaw gateway restart
   

3. Verify the configuration.

   openclaw models status
   # Expected output ( abbreviated ):
   Provider: openrouter
   Model: openrouter/openrouter/free
   Key: ✅ configured
   Status: ready
   # In your chat, check:
   /model status
   /model openrouter/free
   

4. Using the Free Router in Practice.

   # Direct CLI completion (curl example from the prompt)
   # Set `OPENROUTER_KEY` in your environment or replace `$env:OPENROUTER_KEY` with your literal key.
   # The `openrouter/free` router will return a response from whichever free model currently fits the request.
   curl https://openrouter.ai/api/v1/chat/completions `
     -H "Authorization: Bearer $env:OPENROUTER_API_KEY" `
     -H "Content-Type: application/json" `
     -d '{
       "model": "openrouter/free",
       "messages": [
         {"role": "user", "content": "Explain photosynthesis in one paragraph."}
       ]
     }'
   

5. From within OpenClaw chat / sessions. After setting the default model, you can simply ask for completions and OpenClaw will route through the free router automatically.

6. If you want deterministic behavior (e.g., always use the same free model), you can scan the current catalog and lock to a particular model:

   openclaw models scan --no-probe
   # The output lists models currently marked as free and compatible, e.g.:
   openrouter/mistralai/mistral-7b-instruct:free
   openrouter/google/gemini-1.5-flash:free
   openrouter/anthropic/claude-3-haiku:free
   # Then set your chosen model explicitly:
   openclaw models set openrouter/deepseek/deepseek-v4.1-flash
   openclaw models set openrouter/openrouter/mistralai/mistral-7b-instruct
   

Caveat: Explicitly set models bypass the router's automatic selection. If that model becomes unavailable or hits its free‑tier limit, requests will fail until you switch back or let the router pick again.