Running OpenClaw

1. What is OpenClaw #

OpenClaw is a multi-agent orchestration framework. You define agents as a set of plain Markdown files that describe personality, rules, and behavior. A gateway process routes messages between agents, LLM providers, and channels like Telegram or a local control UI. Every agent is a set of files on disk — not a hosted service, not a SaaS lock-in.

It's a sharp tool. You get real control and low overhead, but you also get a single openclaw.json config that can break the whole system if mishandled. This guide exists because most of the friction is in knowing which file to edit, when to restart, and why a 404 just showed up.

2. Prerequisites #

• OS: macOS or Linux. Windows via WSL2 works but is untested for the launchd proxy integration.
• Node.js: 20 LTS or newer.
• At least one LLM provider:
  • Anthropic — using a standard API key.
  • Ollama Cloud — cloud-tagged models (e.g. glm-5.1:cloud).
  • Ollama local — self-hosted models on your own GPU.
  • Any OpenAI-compatible endpoint — via the openai-completions api format.
• Optional: a Telegram bot token per agent you want to reach from a phone. A vault or filesystem the agents can write to.

3. Install #

# install OpenClaw globally
npm install -g openclaw

# initialize a default config in ~/.openclaw/
openclaw init

# start the gateway
openclaw gateway

On first start, OpenClaw writes ~/.openclaw/openclaw.json and scaffolds empty directories for agents, sessions, and extensions. The gateway binds to a local port (default 18789) and is ready to accept channel and UI connections.

4. Config anatomy #

Everything the gateway needs is in a single JSON file. Here's the map:

Safe edit workflow

# unlock
chflags nouchg ~/.openclaw/openclaw.json

# edit — jq, a text editor, or scripted edits
vim ~/.openclaw/openclaw.json

# re-lock
chflags uchg ~/.openclaw/openclaw.json

# restart gateway to apply config changes
openclaw gateway stop && openclaw gateway

5. Agent file architecture #

Every agent has files in two locations with very different purposes. Confusing them is the #1 reason new users can't figure out why a persona change doesn't stick.

Workspace root — the agent's identity and rules

These files are injected into LLM context on every turn. They are plain Markdown. Edit them with any text editor — no restart needed; changes take effect on the next turn.

Agent dir — runtime config (not injected)

Located at ~/.openclaw/agents/<agent-id>/agent/. Managed by the gateway; rarely edited by hand.

Change propagation

6. Your first agent #

The shortest path from nothing to a working agent.

Step 1 — create a workspace directory

mkdir -p ~/clawd-example
cd ~/clawd-example

Step 2 — write the persona

Create SOUL.md:

# You are Example

You are a focused, direct assistant. You prefer terse,
concrete answers over long explanations. You flag uncertainty
instead of guessing. You have a mild aversion to emojis.

## Values
- Clarity over politeness
- Short answers unless depth is requested
- Never fabricate file paths, commands, or API shapes

Step 3 — write operating rules

Create AGENTS.md. This is where you tell the agent where to get context — without these rules, it will hallucinate file paths or write notes nobody can find.

# Operating Rules

## Context & Vault Access

Before answering or acting, search the vault for relevant context.
Tools (provided by the vault-obsidian plugin):

- `vault_context` — quick-reference files from `10-AI-Context/`.
  **Check this first** for any lookup — it's fact-dense and cheap.
- `vault_search "keyword"` — keyword search across all notes.
- `vault_read "path/to/note.md"` — read a specific note.
- `vault_list "folder"` — browse a folder by recency.
- `vault_structure` — show the vault folder layout.

Rules:
- Search before reading — don't dump whole folders.
- Max 3-5 notes per turn unless the user says otherwise.
- Never fabricate paths. If `vault_read` fails, the file doesn't exist.
- If information isn't in the vault, say so explicitly.

## Writing to the Vault

Use `vault_write` for any knowledge the user should find later:
decisions, research notes, meeting minutes, project updates.

- Never write knowledge docs to the agent workspace
  (`~/clawd-example/`) — the user will never find them there.
- Follow the vault's note conventions (frontmatter, headings, tags).
- Always include backlinks to related notes.

## Tool Usage

- If a tool fails twice, stop and report — don't retry blindly.
- If a tool is missing, say so; don't simulate its output.

## Response Format

- Default to 3-5 sentences.
- Use bullet lists for anything enumerable.
- Wrap shell commands in fenced code blocks.

Step 4 — register the agent in openclaw.json

Unlock the config and add an entry to agents.list:

{
  "id": "example",
  "workspace": "~/clawd-example",
  "model": {
    "primary": "ollama/glm-5.1:cloud",
    "fallbacks": ["anthropic/claude-sonnet-4-6"]
  },
  "channels": []
}

Re-lock the config and restart the gateway. Send the agent a message via the control UI — or attach a Telegram bot token via channels.telegram and message it from your phone.

7. Model providers #

Providers live in models.providers. The two most common:

Ollama cloud

"ollama": {
  "baseUrl": "https://ollama.com",
  "apiKey": "<your ollama key>",
  "api": "ollama"
}

Cloud-tagged models use the :cloud suffix. Use full tags — for example gemma4:31b-cloud, not gemma4:cloud. Shorthand tags that don't exist will appear to work at startup but fail at first request.

Anthropic

"anthropic": {
  "baseUrl": "https://api.anthropic.com",
  "apiKey": "<your anthropic key>",
  "api": "anthropic-messages"
}

OpenAI-compatible endpoints

Any endpoint that speaks the OpenAI /v1/chat/completions shape can be registered as a provider. Useful for local inference servers (vLLM, LM Studio) or third-party gateways.

"local-llm": {
  "baseUrl": "http://localhost:8000",
  "apiKey": "<key or placeholder>",
  "api": "openai-completions"
}

8. Model tiers #

A workable default: assign different primaries by agent role, with graceful fallback chains.

Pick primaries you can afford to hit thousands of times per day. Reserve Anthropic for the last slot in each chain so you don't burn quota on routine turns.

9. Plugins #

Plugins live in ~/.openclaw/extensions/ and are toggled in plugins.entries. Common ones:

The nine vault-obsidian tools

Agents that write to a knowledge vault all the time end up with three recurring problems: they blow their context window reading whole files when they only need one section, they overwrite notes that had content worth preserving, and they file things in the wrong folder. The plugin's tool set is designed around those three failure modes.

Plugin code changes require a gateway restart. They are not hot-reloaded.

10. Daily workflows #

Check status

pgrep -fl openclaw | grep -v "Chrome\|node"
# expected: openclaw, openclaw-gateway, openclaw-tui

Edit agent instructions

Instructions are plain Markdown in the workspace root. No unlock. No restart. Changes take effect on the agent's next turn.

vim ~/clawd-example/AGENTS.md

Propagate a rule to all agents

When you add a rule that applies to all agents (for example: "always use vault_write for knowledge docs"), add it to the appropriate section of each agent's AGENTS.md. Don't blindly append — each agent's AGENTS.md usually has a tailored structure.

Restart the gateway cleanly

openclaw gateway stop
# give it a beat to release lock files
sleep 2
openclaw gateway

A robust wrapper script — call it openclaw-restart — should:

1. Stop the gateway.
2. Kill any leftover openclaw processes.
3. Delete stale *.jsonl.lock files in session directories.
4. Detect corrupted sessions (consecutive user turns, "stopReason": "error") and archive them.
5. Start the gateway.
6. Verify gateway + proxy + bot connections. Report pass/warn/fail.

Switch a model for a single agent

Use the safe edit workflow. In agents.list, find the agent by id and update model.primary. Use the provider-prefixed form: anthropic/<id> or ollama/<id>.

Open the control UI

openclaw dashboard --no-open   # prints the URL

The URL uses a hash fragment for the token — http://127.0.0.1:18789/#token=<TOKEN>, not a query string. Hash fragments aren't sent to the server, which keeps the token out of access logs.

The controlUi.allowedOrigins list must include every origin you'll connect from — including any Tailscale IPs if you access the UI remotely.

Mobile app pairing

The official mobile app connects via Settings → Manual Host, not QR scan. After the WebSocket is established, the app requests device pairing. Approve it on the host:

openclaw devices list
openclaw devices approve <requestId>

Pending pairing requests expire after 5 minutes. Gateway token + device pairing form a two-layer auth model.

Cron jobs

Cron jobs live in ~/.openclaw/cron/jobs.json. Reference agents by their id from agents.list, not by Telegram handle. Mixing those up silently breaks the job.

11. Troubleshooting #

Agent receives messages but never replies

Symptom: the typing indicator appears on Telegram but no response arrives. Logs show Removed orphaned user message to prevent consecutive user turns or typing TTL reached.

Cause: the session journal has consecutive user turns — usually from a proxy outage that wrote an empty or error-stop assistant message, corrupting the conversation state.

Fix:

# identify the session
openclaw logs --max-bytes 50000 2>&1 | grep "orphan" | grep -o 'sessionId=[^ ]*'

# delete session + its lock
rm ~/.openclaw/agents/<agent>/sessions/<session-id>.jsonl.lock
rm ~/.openclaw/agents/<agent>/sessions/<session-id>.jsonl

# restart
openclaw gateway stop && openclaw gateway

This clears the conversation history with that channel; a fresh session starts on the next inbound message.

404 not_found_error on every turn

The api field of a provider doesn't match the endpoint shape it's pointing at. Inspect the config:

jq '.models.providers' ~/.openclaw/openclaw.json

Verify each provider's api matches its baseUrl: anthropic-messages for Anthropic, openai-completions for OpenAI-shaped endpoints, ollama for Ollama.

Config won't load after editing

The gateway refuses to start and logs a schema error. Most common offenders:

• Used fallback (singular) instead of fallbacks (plural array).
• Added a key that doesn't exist in your OpenClaw version — openclaw doctor --fix will remove unknown keys; always diff before accepting.
• Invalid model.primary reference — the string must match a concrete provider/model combo.

Known crash: network interface flapping

Symptom: gateway dies with AssertionError: Reached illegal state! IPv4 address changed from undefined to defined.

Cause: a USB ethernet adapter or mobile hotspot briefly loses IPv4; the embedded mDNS library crashes on the undefined→defined transition.

Fix: restart the gateway. A good openclaw-restart wrapper handles this cleanly. If it recurs hourly, pin the adapter (disable USB power management) or switch to Wi-Fi.

12. Using Claude Code as admin #

Claude Code — the CLI — is a good fit for OpenClaw admin because most of the work is file editing, config diffing, and log tailing. A few patterns pay back fast:

Write a skill for OpenClaw operations

Claude Code's skills feature lets you package common OpenClaw tasks into an invokable capability: status checks, config edits with unlock/relock, restart workflows, session cleanup. One skill means every conversation that touches OpenClaw inherits the same safety rails.

A skill file should document:

• Key paths (~/.openclaw/openclaw.json, proxy plist/unit, extensions dir).
• The agent roster — ids, workspace paths, channel bindings.
• Change-propagation rules (what requires a restart vs. next-turn).
• Troubleshooting playbooks (corrupted sessions, 404s, config won't load).
• Hard rules (never kill the proxy manually; always re-lock after editing).

Ask the CLI to do full workflows

Instead of editing files manually, describe the intent: "add a rule to every core agent's AGENTS.md that says to use vault_write for knowledge docs, restart the gateway, and verify the restart succeeded." Claude Code walks the roster, makes the edits, runs the restart script, and reports pass/fail against each step.

Diff before you restart

Before re-locking the config, ask the CLI to show the diff against a known-good backup. A 3-line change in openclaw.json can accidentally delete a whole providers block if jq output is pasted wrong. Diffs surface that before you restart the gateway into a broken state.

13. Rules & pitfalls #

• Always re-lock openclaw.json after every edit. An unlocked config is a doctor run away from silent destruction.
• Never run openclaw doctor with the config unlocked unless you have a recent backup and intend to accept its changes.
• After any config change, update whatever doc you use as the source of truth (e.g. a vault note).
• If an agent stops responding on a channel, check for corrupted sessions before restarting the gateway. A restart alone won't fix a bad journal.
• Provider outages cascade into session corruption — when a model endpoint returns errors mid-turn, the assistant message lands in the journal as an aborted stop. Monitor provider health.
• A CLAUDE.md in an agent runtime dir is not read by OpenClaw. Put context in the workspace root.
• Use fallbacks (plural array), not fallback.
• Ollama cloud tags need the full -cloud suffix (e.g. gemma4:31b-cloud, not gemma4:cloud).