A progressive tutorial for building an AI Agent Gateway from scratch, covering core modules like Tool Use, WebSocket Gateway, Routing, and Reliable Delivery.
claw0 is a Python tutorial project maintained by shareAI-lab (Singapore-based open-source AI lab), released under MIT license. The project deconstructs complex AI Agent gateway systems into 10 progressive chapters (s01-s10), helping developers understand core Agent architecture concepts from scratch.
Project Positioning#
- Problem Solved: Lowering the learning barrier for building production-grade AI Agent gateways, bridging the cognitive gap between simple demos and complex production systems
- Use Cases: AI engineers learning Agent architecture, building private Agent prototypes, understanding best practices for Tool Use and Session management
- Capability Boundary: Positioned as a teaching and prototyping tool; production environments should refer to the related OpenClaw project
Core Modules#
| Chapter | Name | Core Mechanism |
|---|---|---|
| s01 | Agent Loop | while + stop_reason (basic loop) |
| s02 | Tool Use | TOOL_HANDLERS dispatch (tool routing) |
| s03 | Sessions | SessionStore + JSONL (persistent sessions) |
| s04 | Multi-Channel | Channel plugin interface (multi-channel abstraction) |
| s05 | Gateway Server | WebSocket + JSON-RPC (server) |
| s06 | Routing | Binding resolution (multi-Agent routing) |
| s07 | Soul & Memory | SOUL.md + MemoryStore (personality + memory) |
| s08 | Heartbeat | HeartbeatRunner (proactive behavior) |
| s09 | Cron Scheduler | CronService (scheduled tasks) |
| s10 | Delivery Queue | DeliveryQueue + backoff (reliable delivery) |
Architecture Design#
Layered Architecture:
- Foundation Layer (s01-s03): Build single-session Agent loop, Messages list maintains context, TOOL_HANDLERS implements tool dispatch
- Service Layer (s04-s06): Encapsulate standalone Agent as network service, WebSocket bidirectional communication, JSON-RPC protocol
- Intelligence Layer (s07-s08): Grant Agent personality and proactivity, Markdown files define personality, dedicated thread handles heartbeat
- Operations Layer (s09-s10): Ensure long-term system operation, Cron scheduled triggers, Delivery Queue ensures no message loss
Environment Setup#
Platform Requirements: Python 3.11+
Dependencies: anthropic>=0.39.0, python-dotenv>=1.0.0, websockets>=12.0, croniter>=2.0.0
Configuration:
ANTHROPIC_API_KEY: Anthropic API key (required)MODEL_ID: Model ID, default claude-sonnet-4-20250514ANTHROPIC_BASE_URL: Optional, supports OpenRouter and compatible services
Security Mechanisms#
safe_path(): Prevents path traversal attacks- Dangerous command blacklist: rm -rf /, mkfs, dd if=, etc.
- Command timeout control: default 30 seconds
Quick Start#
git clone https://github.com/shareAI-lab/claw0.git && cd claw0
pip install -r requirements.txt
cp .env.example .env
# Edit .env to set ANTHROPIC_API_KEY
python agents/s01_agent_loop.py
The project includes documentation in Chinese, English, and Japanese, suitable for learners from different language backgrounds.