从零构建 AI Agent 网关的渐进式教学指南，涵盖 Tool Use、WebSocket 网关、路由调度及可靠投递等核心模块。
claw0 是由 shareAI-lab（新加坡开源 AI 实验室）维护的 Python 教学项目，采用 MIT 许可证开源。项目将复杂的 AI Agent 网关系统拆解为 10 个渐进式章节（s01-s10），帮助开发者从零理解 Agent 架构的核心概念。
项目定位#
- 解决问题：降低构建生产级 AI Agent 网关的学习门槛，填补简单 Demo 与复杂生产系统之间的认知鸿沟
- 适用场景：AI 工程师学习 Agent 架构、构建私有 Agent 原型、理解 Tool Use 与 Session 管理的最佳实践
- 能力边界：定位为教学与原型验证工具，生产环境需参考关联项目 OpenClaw
核心模块#
| 章节 | 名称 | 核心机制 |
|---|---|---|
| s01 | Agent Loop | while + stop_reason（基础循环） |
| s02 | Tool Use | TOOL_HANDLERS dispatch（工具调度） |
| s03 | Sessions | SessionStore + JSONL（持久化会话） |
| s04 | Multi-Channel | Channel 插件接口（多渠道抽象） |
| s05 | Gateway Server | WebSocket + JSON-RPC（服务端） |
| s06 | Routing | Binding resolution（多 Agent 路由） |
| s07 | Soul & Memory | SOUL.md + MemoryStore（人格+记忆） |
| s08 | Heartbeat | HeartbeatRunner（主动行为） |
| s09 | Cron Scheduler | CronService（定时任务） |
| s10 | Delivery Queue | DeliveryQueue + backoff（可靠投递） |
架构设计#
分层架构：
- 基础层 (s01-s03)：构建单次会话的 Agent 闭环，Messages 列表维护上下文，TOOL_HANDLERS 实现工具调度
- 服务层 (s04-s06)：将单机 Agent 封装为网络服务，WebSocket 双向通信，JSON-RPC 协议规范
- 智能层 (s07-s08)：赋予 Agent 人格与主动性，Markdown 文件定义人格，独立线程处理心跳
- 运维层 (s09-s10)：保障系统长期运行，Cron 定时触发，Delivery Queue 确保消息不丢失
环境配置#
平台要求：Python 3.11+
依赖项：anthropic>=0.39.0, python-dotenv>=1.0.0, websockets>=12.0, croniter>=2.0.0
配置项：
ANTHROPIC_API_KEY：Anthropic API 密钥（必需）MODEL_ID：模型 ID，默认 claude-sonnet-4-20250514ANTHROPIC_BASE_URL：可选，支持 OpenRouter 等兼容服务
安全机制#
safe_path()：防止路径穿越攻击- 危险命令黑名单：rm -rf /, mkfs, dd if= 等
- 命令超时控制：默认 30 秒
快速开始#
git clone https://github.com/shareAI-lab/claw0.git && cd claw0
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env 设置 ANTHROPIC_API_KEY
python agents/s01_agent_loop.py
项目包含中英日三语文档，适合不同语言背景的学习者。