DEV Community

mibii
mibii

Posted on

OpenClaw Cheatsheet: The Autonomous AI Agent That Runs on Your Machine

#ai #opensource #automation #agents

TL;DR — OpenClaw is an open-source autonomous AI agent runtime. It connects an LLM of your choice to your machine, your files, and your messaging apps. It has 247k+ GitHub stars. It is powerful and genuinely dangerous if misconfigured. This article is your map.

🧠 The Mental Model 

You (Telegram / iMessage / Discord)
        ↓
   Gateway — always-on router, never reasons
        ↓
  Agent Runtime — calls LLM, executes tools, loops
        ↓
   LLM (Claude / GPT / Ollama / DeepSeek — your choice)
        ↓
 Files · Browser · Email · Shell · APIs
Enter fullscreen mode Exit fullscreen mode

LLM = the brain. OpenClaw = the hands, legs, and dispatcher.

It is not a chatbot. It takes actions, not just generates text. It can read your email while you sleep, process files on a schedule, and reply to your Telegram messages on your behalf — adaptively, not from a rigid script.

📁 Workspace File Structure 

~/.openclaw/
├── openclaw.json          ← main config (models, channels, agents)
└── workspace/
    ├── SOUL.md            ← agent's personality and boundaries
    ├── AGENTS.md          ← operating instructions
    ├── MEMORY.md          ← what the agent remembers (auto-updated)
    ├── USER.md            ← your profile (name, timezone, accounts)
    ├── TOOLS.md           ← tool notes and conventions
    ├── BOOTSTRAP.md       ← first-run setup ritual (deleted after)
    ├── HEARTBEAT.md       ← background check-in schedule
    ├── IDENTITY.md        ← agent name, avatar, emoji
    └── skills/
        └── my-skill/
            ├── SKILL.md   ← instructions + YAML frontmatter
            └── scripts/   ← executable automation
Enter fullscreen mode Exit fullscreen mode

Pro tip: Think of SOUL.md as your CLAUDE.md — but for your always-on agent. Start here before anything else.

⚙️ Installation 

# macOS
brew install openclaw

# Windows
winget install OpenClaw.OpenClaw

# Linux
curl -fsSL https://openclaw.ai/install.sh | sh

# Verify
openclaw --version
openclaw doctor   # checks your environment
Enter fullscreen mode Exit fullscreen mode

Requirements: Node 22+, one messaging app connected, an LLM API key (or local Ollama)

🚀 First Run 

openclaw start              # starts the Gateway daemon
openclaw channels list      # see available channels
openclaw channels add telegram
openclaw agents add main --model anthropic:claude-opus-4-6
openclaw agents set-identity --from-identity
Enter fullscreen mode Exit fullscreen mode

Then message your bot: Hey, let's get you set up. Read BOOTSTRAP.md and walk me through it.

⚠️ If your first message is a real question, BOOTSTRAP never runs. Send the setup message first.

🔧 Core CLI Commands

Command What it does
openclaw start Start the Gateway daemon
openclaw stop Stop the Gateway
openclaw status Health check
openclaw doctor Full environment diagnostics
openclaw agents list List configured agents
openclaw agents add <name> Create a new agent
openclaw channels list Show connected channels
openclaw channels status --probe Test channel connectivity
openclaw skills list List installed skills
openclaw skills add <skill> Install from ClawHub
openclaw memory search <query> Semantic search your memory
openclaw logs --tail 50 Stream recent logs

📝 Workspace Files — What Goes Where

SOUL.md — Agent Constitution

Persona, tone, hard limits. Injected every session.

# Identity
You are Alex, a personal assistant who is direct and never verbose.

# Hard limits
- Never send emails without explicit confirmation
- Never delete files without showing what will be deleted first
- Always ask before executing shell commands in production directories
Enter fullscreen mode Exit fullscreen mode

USER.md — Your Profile 

# User Profile
- Name: Your Name
- Timezone: Europe/London
- Key accounts: electricity (British Gas), broadband (BT)
- Morning briefing: 8:00 AM
- Preferred reminder: evening before deadline
Enter fullscreen mode Exit fullscreen mode

AGENTS.md — Operating Instructions

Build commands, code conventions, what NOT to do. Same concept as CLAUDE.md in Claude Code.

MEMORY.md — Persistent Memory

Auto-updated by the agent. Uses vector + BM25 search. Lives in SQLite. Do not edit manually.

🧩 Skills — Modular Capabilities

Skills are Markdown files that tell the agent how to handle a domain. The agent reads them on demand — not injected into every prompt.

---
name: github-pr-reviewer
description: Review GitHub pull requests and post structured feedback
---

# GitHub PR Reviewer

When asked to review a pull request:
1. Use web_fetch to retrieve the PR diff
2. Analyze for correctness, security issues, code style
3. Structure as: Summary → Issues → Suggestions
4. Post via GitHub API only if explicitly asked
Enter fullscreen mode Exit fullscreen mode

Install from ClawHub:

openclaw skills add github-pr-reviewer
openclaw skills add email-triage
openclaw skills add daily-briefing
Enter fullscreen mode Exit fullscreen mode

⚠️ ClawHub has 5,700+ skills. Cisco researchers found silent data exfiltration in a community skill. Treat every SKILL.md like an npm package from an unknown author — read the code first.

🪝 Hooks — Event-Driven Automation

Hooks are TypeScript handlers that fire on lifecycle events. Deterministic logic that runs before/after the LLM.

Event When it fires
command:new New session starts
agent:bootstrap Before system prompt is finalized
before_tool_call Before any tool executes
after_tool_call After tool completes
before_compaction Before context is compressed
session_start / session_end Session lifecycle
gateway_start / gateway_stop Daemon lifecycle
PreCommit Before git commit (secret detection)

Example use cases: auto-format on file write, block dangerous shell commands, log all tool calls, inject environment context at session start.

🤖 Multi-Agent Setup 

openclaw agents add main --model anthropic:claude-opus-4-6
openclaw agents add code-reviewer --model anthropic:claude-opus-4-6 \
  --workspace ./src --tools file,shell,git
openclaw agents add researcher --model openai:gpt-4.1 \
  --tools web_fetch,file
Enter fullscreen mode Exit fullscreen mode

Agent team patterns:

Pattern When to use
Orchestrator Central task dispatcher routes to specialists
Pipeline Sequential handoff (research → draft → review)
Map-Reduce Parallel then merge (multiple files at once)
Supervisor Monitor and retry failed tasks
Swarm Dynamic peer delegation

📊 Context Management

Usage Action
0–50% Work freely
50–70% Monitor token usage
70–90% Run /compact
90%+ /clear — mandatory

Memory compaction: older turns are summarized, not dropped. Semantic content preserved.

🔐 Security — Read This Before You Start

CVE-2026-25253 (CVSS 8.8): Patched RCE — a malicious web page could leak the Gateway auth token and execute arbitrary commands. Update immediately.

Prompt injection is real. If your agent reads emails or web pages, malicious instructions in that content can hijack it. A researcher demonstrated an agent leaking its full config (including API keys) via a spoofed email.

Minimum security checklist:

# Run before connecting to any external network
openclaw audit

# Never hardcode keys — use env vars
export ANTHROPIC_API_KEY=sk-...
export OPENCLAW_GATEWAY_TOKEN=...

# Add to .gitignore
echo "openclaw.local.json" >> .gitignore
echo ".env" >> .gitignore

# Enable DM pairing (default — don't disable)
# Only approve known users via pairing codes
Enter fullscreen mode Exit fullscreen mode

Before installing any skill:

  • Who made it? Check GitHub stars, last commit, issues
  • What permissions does it request?
  • Does it make outbound network calls?
  • Read every line of SKILL.md

🧭 Who Is This For — Honestly

✅ Use OpenClaw if:

  • You're comfortable in a terminal and understand environment variables
  • You need adaptive automation where logic can't be reduced to if-else
  • You want a personal agent on your own infrastructure, data stays local
  • You're a developer who wants to study how production AI agents actually work

❌ Skip OpenClaw if:

  • You don't know how to read a command-line error
  • You need compliance, audit trails, or enterprise governance
  • Your task has deterministic logic — a scheduler will be safer and cheaper
  • You want a quick setup with no maintenance overhead

⚡ OpenClaw vs Other Tools

Tool Best for
OpenClaw Adaptive personal agent, agentic workflows, LLM-driven decisions
Jenkins / GitHub Actions CI/CD, reproducible pipelines, audit logs — no LLM needed
xStarter / Task Scheduler Simple scheduled scripts, deterministic triggers
n8n / Make / Zapier Visual workflow builder, SaaS integrations, no-code
LangChain / custom code Full architectural control, enterprise integrations
Claude chat One-off tasks where you want to stay in the loop

The right tool is not the smartest one. It's the one that solves your problem with the least risk.

💡 Pro Tips

  • Start minimal. Add SOUL.md + USER.md first. Add skills only when you feel the need.
  • Keep AGENTS.md under 500 lines. Longer = context bloat = ignored rules.
  • Use --dev flag to isolate state while experimenting: openclaw --dev start
  • Back up your workspace directory. It's plain Markdown — git-track it.
  • Test skills in isolation before connecting them to live channels.
  • Run openclaw audit regularly, especially after adding new skills.
  • MEMORY.md is auto-updated — the agent writes what it learns. Review it occasionally.
  • openclaw doctor is your first stop for any issue.

📚 Key Resources

Resource Link
Official docs docs.openclaw.ai
GitHub github.com/openclaw/openclaw
ClawHub (skills) clawhub.ai
Security audit tool openclaw audit
Community Discord via official docs

Based on OpenClaw documentation, freecodecamp.org, bibek-poudel.medium.com, arxiv.org (ClawSafety), digitalocean.com, and vallettasoftware.com. April 2026.

Top comments (0)