搭建属于你的 OpenClaw

这是一份循序渐进的教程，教你从一个简单的聊天循环开始，逐步构建出轻量级版的 OpenClaw AI 代理。

概述

18 个递进步骤，将手把手教你如何搭建一个极简版的 OpenClaw。每个步骤都包含：

• 一份 README.md，详细讲解关键组件与设计决策。
• 一个可运行的代码库。

示例项目： pickle-bot — 我们的参考实现。

教程结构

第一阶段：功能完备的单体代理（步骤 1–7）

构建一个功能齐全的代理，能够进行对话、使用工具、学习技能、记忆对话内容，并访问互联网。

• 00-chat-loop - 仅一个聊天循环
• 01-tools - 为你的代理添加工具
• 02-skills - 通过 SKILL.md 扩展代理能力
• 03-persistence - 保存对话记录
• 04-slash-commands - 用户直接控制会话
• 05-compaction - 压缩历史记录并继续
• 06-web-tools - 让你的代理探索更广阔的世界

第二阶段：事件驱动架构（步骤 8–11）

重构为事件驱动架构，以提升可扩展性和多平台支持。

• 07-event-driven - 将你的代理暴露到 CLI 之外
• 08-config-hot-reload - 无需重启即可编辑配置
• 09-channels - 用手机与你的代理交流
• 10-websocket - 想以编程方式与你的代理交互吗？

第三阶段：自主与多代理系统（步骤 12–16）

添加定时任务、代理协作和智能路由功能。

• 11-multi-agent-routing - 将合适的工作分配给合适的代理
• 12-cron-heartbeat - 让代理在你睡觉时工作
• 13-multi-layer-prompts - 更多上下文，更多上下文，更多上下文
• 14-post-message-back - 让你的代理也能“对你说”话
• 15-agent-dispatch - 让你的代理有伙伴一起工作！

第四阶段：生产与规模化（步骤 17–18）

引入可靠性与长期记忆相关的特性。

• 16-concurrency-control - 同时运行的 Pickle 太多了吗？
• 17-memory - 记住我吧！

如何使用本教程

配置 API 密钥

在运行任何步骤之前，你需要先配置好 API 密钥：

1. 复制示例配置文件：

   cp default_workspace/config.example.yaml default_workspace/config.user.yaml
   

2. 编辑 config.user.yaml，填入你的 API 密钥：

   • 参考 LiteLLM 提供者列表，了解所有支持的提供商。
   • 查看 提供者示例，获取一些配置示例。

3. 按照每个步骤的指引，阅读并动手实践即可。

贡献说明

每个步骤都独立成一个模块。欢迎提出改进建议！

Build Your Own OpenClaw 快速上手指南

本指南将带你通过 18 个渐进式步骤，从零开始构建一个属于自己的 AI Agent（智能体），最终实现类似 OpenClaw 的轻量级版本。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)
• Python 版本：Python 3.9 或更高版本
• 依赖管理：pip 或 poetry
• API Key：你需要一个大模型服务商的 API Key（支持 LiteLLM 接入的所有提供商，如 OpenAI, Anthropic, 国内大模型等）

安装步骤

1. 克隆项目

首先，将教程代码库克隆到本地：

git clone https://github.com/openclaw/build-your-own-openclaw.git
cd build-your-own-openclaw

2. 配置 API 密钥

在运行任何步骤前，必须配置你的模型 API 密钥。

复制配置文件：

cp default_workspace/config.example.yaml default_workspace/config.user.yaml

编辑配置： 使用你喜欢的编辑器打开 default_workspace/config.user.yaml，填入你的 API Key 和选择的模型提供商。

• 支持的提供商列表参考：LiteLLM Providers
• 配置示例参考项目中的 PROVIDER_EXAMPLES.md

提示：如果你使用的是国内大模型（如通义千问、智谱 AI 等），请确保在配置文件中正确设置 base_url 和 model 名称。

3. 安装依赖

进入你想要开始的步骤目录（例如从第一步开始），安装所需依赖：

cd 00-chat-loop
pip install -r requirements.txt

(注：每个步骤目录下通常包含独立的 requirements.txt，请根据当前步骤所在目录执行安装)

基本使用

本教程采用“阅读文档 + 运行代码”的学习方式。每个步骤都是一个可运行的独立项目。

运行第一个示例：聊天循环 (Step 00)

这是最基础的起点，构建一个简单的对话循环。

1. 进入目录：

   cd 00-chat-loop
   

2. 阅读设计文档： 先阅读该目录下的 README.md，了解核心组件和设计决策。

3. 运行代码： 执行主程序启动 Agent：

   python main.py
   

4. 交互体验： 终端启动后，你可以直接输入消息与 Agent 对话。

进阶学习路径

完成基础步骤后，你可以按照以下四个阶段逐步深入：

• 阶段 1：全能单智能体 (Steps 1-7) 学习如何让 Agent 使用工具、掌握技能 (SKILL.md)、持久化记忆、处理斜杠命令以及访问互联网。

  • 示例：cd 01-tools -> 运行并测试工具调用功能。

• 阶段 2：事件驱动架构 (Steps 8-11) 重构为事件驱动模式，支持多平台接入（手机、WebSocket）、配置热重载。

  • 示例：cd 09-channels -> 尝试通过不同渠道与 Agent 通信。

• 阶段 3：自主与多智能体 (Steps 12-16) 添加定时任务 (Cron)、多层提示词上下文、多智能体路由与协作。

  • 示例：cd 15-agent-dispatch -> 观察多个 Agent 如何协同工作。

• 阶段 4：生产与扩展 (Steps 17-18) 实现并发控制和长期记忆机制，为生产环境做准备。

参考实现

如果你在某个步骤遇到困难，可以参考完整的实现示例：

• Pickle-bot: https://github.com/czl9707/pickle-bot

现在，请从 00-chat-loop 开始你的构建之旅吧！