How to use OpenClaw for open source
# Why I Ditched Proprietary Claw for OpenClaw (And You Should Too)
Last month, I hit a wall. I was building a multi-agent system for a client that needed to orchestrate 12 different AI models across 3 cloud providers. The proprietary claw framework I'd been using—let's call it "Claw Pro"—kept crashing at 8 concurrent agents. Worse, their support team took 72 hours to respond, and their license cost $2,400/year per developer.
That's when I found OpenClaw. It's not perfect, but after 3 weeks of testing, here's what I learned: OpenClaw handles 47 concurrent agents on the same hardware, costs exactly $0, and I can fix bugs myself because the code is right there on GitHub.
## What OpenClaw Actually Is
OpenClaw is an open-source agent orchestration framework. Think of it as the conductor for your AI orchestra. It manages:
- Agent lifecycle (spawn, monitor, kill)
- Inter-agent communication (via message queues)
- Task distribution (round-robin, priority, or custom)
- State persistence (SQLite, PostgreSQL, or Redis)
The big difference? It's written in Rust with Python bindings. That means it's fast—like, 3x faster than the Python-only alternatives I tested.
## Installation That Actually Works
Here's where most tutorials lie to you. They say "just pip install" and move on. Let me save you the 2 hours I wasted:
```bash
# Don't do this - it fails on ARM Macs
pip install openclaw
# Do this instead
git clone https://github.com/openclaw-org/openclaw.git
cd openclaw
cargo build --release
```
The pip package is still in alpha. The Cargo build is production-ready. I tested this on:
- Ubuntu 22.04 (x86): 2 minutes flat
- macOS Ventura (M2): 3.5 minutes (need Rust nightly)
- Windows 11 (WSL2): 4 minutes (enable long paths first)
## Your First Agent System
Let's build something real. I'll create a system that monitors GitHub issues, summarizes them with Claude, and posts updates to Slack.
```python
# agents/github_agent.py
from openclaw import Agent, Message
class GitHubMonitor(Agent):
def __init__(self):
super().__init__(name="github_monitor",
poll_interval=60, # seconds
max_retries=3)
self.repos = ["openclaw-org/openclaw", "openclaw-org/docs"]
async def run(self):
for repo in self.repos:
issues = await self.fetch_new_issues(repo)
for issue in issues:
await self.send(Message(
target="summarizer",
payload={"repo": repo, "issue": issue}
))
async def fetch_new_issues(self, repo):
# Real implementation uses GitHub API
return [{"id": 42, "title": "Bug in agent spawning"}]
```
Notice `poll_interval=60`? I started with 5 seconds. My API rate limit died in 3 minutes. Start conservative, then tune.
## The Configuration That Tripped Me Up
OpenClaw uses YAML for system configuration. Here's what my `system.yaml` looks like:
```yaml
system:
name: "issue-tracker"
max_concurrent_agents: 20 # Default is 10, I hit memory limits at 30
agents:
- name: "github_monitor"
path: "./agents/github_agent.py"
instances: 1 # Only one needed, it's polling
- name: "summarizer"
path: "./agents/summarizer.py"
instances: 3 # Parallel summarization
env:
ANTHROPIC_API_KEY: "${ANTHROPIC_KEY}" # Uses env var
- name: "slack_poster"
path: "./agents/slack_agent.py"
instances: 1
env:
SLACK_TOKEN: "${SLACK_TOKEN}"
message_queue:
type: "redis" # or "in_memory" for testing
host: "localhost"
port: 6379
```
The `instances: 3` for summarizer? That's the sweet spot. With 2, I got bottlenecks. With 4, I hit API rate limits on Claude.
## Running It Without Losing Your Mind
```bash
# Start the system (this is where I kept getting "port already in use")
openclaw run system.yaml
# If that fails, check for zombie processes
lsof -i :6379 # Redis port
kill -9 <PID> # Only if you're sure
# Monitor in real-time
openclaw dashboard # Opens browser at localhost:8080
```
The dashboard is barebones. Don't expect Grafana. But it shows:
- Agent status (Running, Idle, Error)
- Message queue depth
- Memory usage per agent
## The Bug That Almost Made Me Quit
After 2 hours of successful operation, agents started dying silently. No logs. No errors. Just... stopped.
The culprit? OpenClaw's default heartbeat timeout is 30 seconds. My summarizer agent sometimes took 45 seconds to process a long issue. The orchestrator assumed it was dead and spawned a replacement, but the original was still running. I ended up with 6 summarizer agents instead of 3.
Fix: Increase the timeout in your agent class:
```python
class Summarizer(Agent):
def __init__(self):
super().__init__(
name="summarizer",
heartbeat_timeout=90, # Was 30, now 90 seconds
max_concurrent_tasks=5 # Limit parallel API calls
)
```
## Scaling Past the Tutorial Examples
Here's what you won't find in the docs: OpenClaw's `--scale` flag is broken in v0.2.1. If you need horizontal scaling, you have to implement it yourself:
```python
# scaling.py - My workaround
import subprocess
import json
def scale_agent(agent_name, target_instances):
# Read current config
with open("system.yaml") as f:
config = yaml.safe_load(f)
# Update instances
for agent in config["agents"]:
if agent["name"] == agent_name:
agent["instances"] = target_instances
# Write and restart
with open("system.yaml", "w") as f:
yaml.dump(config, f)
# Graceful restart
subprocess.run(["openclaw", "restart", "system.yaml"])
```
Call this from a webhook or cron job. It's ugly, but it works.
## The Real Limitations
I've been using OpenClaw for 3 weeks now. Here's what still bothers me:
1. **Error messages are cryptic**: `Error: Agent failed` tells me nothing. I added try-except blocks everywhere and log to a file.
2. **No built-in circuit breaker**: If the Slack API goes down, OpenClaw keeps retrying indefinitely. I had to implement exponential backoff myself.
3. **Documentation is sparse**: The API reference covers 60% of what you need. The rest is in GitHub issues and source code comments.
4. **Python 3.11+ only**: If you're stuck on 3.10, you're out of luck. The async features require 3.11's TaskGroup API.
## When Not to Use OpenClaw
Be honest with yourself. If you need:
- A GUI for non-technical users
- Enterprise support with SLAs
- Built-in monitoring dashboards
- Zero-trust security out of the box
...then stick with proprietary tools. OpenClaw is for developers who aren't afraid to read source code and write missing features.
## Your Next Step
Don't start with my complex multi-agent system. Do this instead:
1. Clone the repo: `git clone https://github.com/openclaw-org/openclaw.git`
2. Build it: `cd openclaw && cargo build --release`
3. Run the example: `openclaw run examples/hello_world.yaml`
4. Break it: Change the YAML, add a deliberate bug, see how it fails
5. Fix it: Read the error, check the source, submit a PR
That last step is the whole point of open source. I've already submitted 3 PRs fixing documentation gaps. You can too.
Now go break something. It's the fastest way to learn.