AI Agent 第一课:build-your-own-openclaw 聊天循环 Chat Loop 从 0 到 1 完整实现
AI Agent 第一课:build-your-own-openclaw 聊天循环 Chat Loop 从 0 到 1 完整实现
AI Agent 的第一课,往往不是写复杂的代码,而是搭好一个最朴素的 Chat Loop(聊天循环)。开源教程 build-your-own-openclaw 用 18 个循序渐进的步骤,手把手教你从零构建一个生产级 AI 智能体——而起点,正是这个不到 20 行的聊天循环。本文将带你完整拆解它的设计思路、核心代码与运行机制,5 分钟就能跑通属于自己的第一个 AI Agent 🚀
为什么所有 AI Agent 都从聊天循环开始
很多人以为 AI Agent 很复杂,其实它的内核就是一个死循环:
接收用户输入 → 发送给大模型 → 拿到回复 → 展示给用户 → 接收下一轮输入……
这就是 Chat Loop,也是 AI Agent 的"心跳"。
它和"一问一答"的聊天机器人有本质区别:
| 能力 | 普通聊天机器人 | AI Agent(智能体) |
|---|---|---|
| 对话记忆 | 常丢失上下文 | 记住完整会话历史 |
| 个性化人设 | 固定模板 | 由系统提示词塑造"灵魂" |
| 扩展空间 | 单一问答 | 可逐步加工具、技能、记忆 |
build-your-own-openclaw 的思路就是:先让它会说话,再让它会做事。本文聚焦第一步——聊天循环。
聊天循环的本质:一个 while 循环
剥掉所有工程细节,Chat Loop 的核心逻辑惊人地简单:
while True:
user_input = 获取用户输入()
if user_input in ("quit", "exit", "q"):
break
response = await session.chat(user_input) # 问大模型
展示回复(response)
整个循环封装在 src/mybot/cli/chat.py 的 ChatLoop 类中,它做了三件"小事",却体现了工程化思维:
- 🧵 非阻塞输入:用
asyncio.to_thread读取用户输入,等待回复时不会卡死事件循环 - 🛡️ 容错处理:大模型调用出错时打印错误信息,而不是让整个会话崩溃
- 🚪 优雅退出:输入
quit/exit/q或按 Ctrl+C 即可结束会话
# 00-chat-loop/src/mybot/cli/chat.py 核心片段
response = await self.session.chat(user_input)
self.display_agent_response(response)
会话状态:让大模型"记得一切"
为什么 AI 能连续对话?因为它每次都看到完整的历史。这一层由两个类协作完成:
- SessionState(src/mybot/core/session_state.py):纯粹的消息容器,负责存储消息列表
- AgentSession(src/mybot/core/agent.py):会话编排器,串联"存消息 → 构建请求 → 调用大模型 → 存回复"
其中 build_messages() 是关键:它把系统提示词 + 全部历史消息拼成一次请求,保证大模型拥有完整上下文:
# 00-chat-loop/src/mybot/core/session_state.py
def build_messages(self) -> list[Message]:
system_prompt = self.agent.agent_def.agent_md
messages: list[Message] = [{"role": "system", "content": system_prompt}]
messages.extend(self.messages)
return messages
💡 系统提示词(system prompt)就是智能体的"灵魂",它决定了 AI 是谁、怎么说、什么性格。
系统提示词与 Agent 定义:给智能体注入"灵魂"
build-your-own-openclaw 把每个 Agent 定义为一份 Markdown 文件,结构优雅:
- YAML frontmatter:声明名称、默认 LLM 参数等元信息
- Markdown 正文:就是系统提示词本身,塑造智能体的人设
默认内置的"猫助手 Pickle"定义在 AGENT.md:
---
name: Pickle
description: A friendly cat assistant talk to user directly, managing daily tasks.
llm:
temperature: 0.7
max_tokens: 4096
---
You are Pickle, a friendly cat assistant. You help with daily tasks, coding,
questions, and creative work.
加载逻辑在 src/mybot/core/agent_loader.py 中:它解析 frontmatter,并把 Agent 级别的 LLM 配置与全局配置智能合并——这样每个智能体都能拥有独立的"性格参数"。
LLM 调用:一个接口打通多家大模型
真正与大模型打交道的是 src/mybot/provider/llm/base.py 中的 LLMProvider。它基于 litellm 做统一封装:
request_kwargs: dict[str, Any] = {
"model": self.model,
"messages": messages,
"api_key": self.api_key,
"temperature": self.temperature,
"max_tokens": self.max_tokens,
}
response = await acompletion(**request_kwargs)
这意味着你可以只改配置,不改代码,在 OpenAI、Anthropic 等任意提供商之间切换。配置写在 config.user.yaml 里(示例见 config.example.yaml):
llm:
provider: openai # 大模型提供商
model: gpt-4 # 使用的模型
api_key: sk-your-key # 你的 API 密钥
temperature: 0.7
max_tokens: 2048
default_agent: pickle
快速上手:3 步跑通你的第一个 AI Agent
📦 第一步:准备环境
确保已安装 uv(或 Python 3.11+)并克隆本仓库。
🔑 第二步:配置 API 密钥
cp default_workspace/config.example.yaml default_workspace/config.user.yaml
# 编辑 config.user.yaml,填入你的真实 API 密钥
💬 第三步:启动聊天
cd 00-chat-loop
uv run my-bot chat
启动后你会看到欢迎面板,输入任意消息即可和"猫助手 Pickle"对话:
You: Hello, who is this?
pickle: Meow! Hello there! I'm Pickle, your friendly cat assistant. 🐾
输入 quit 或 exit 即可结束会话。🎉
00-chat-loop 项目结构速览
整个聊天循环的代码量非常克制,每个模块职责单一:
| 模块路径 | 职责 |
|---|---|
| src/mybot/cli/chat.py | ChatLoop:交互式聊天循环与输入输出 |
| src/mybot/core/agent.py | Agent / AgentSession:会话编排 |
| src/mybot/core/session_state.py | SessionState:消息历史与请求构建 |
| src/mybot/core/agent_loader.py | 解析 AGENT.md,合并 LLM 配置 |
| src/mybot/provider/llm/base.py | LLMProvider:litellm 统一大模型调用 |
| src/mybot/utils/config.py | Config / LLMConfig:配置加载与校验 |
核心洞察:会话状态、智能体定义、大模型调用三者的职责清晰分离,这正是后续 17 个步骤能够层层叠加的根基。
下一步:从"会说话"到"会做事"
聊天循环只是起点。build-your-own-openclaw 用后续步骤,让智能体逐步获得真正的"行动力":
| 步骤 | 能力升级 |
|---|---|
| 01-tools | 🔧 给智能体加工具,真正执行动作 |
| 02-skills | 🧠 用 SKILL.md 按需扩展能力 |
| 03-persistence | 💾 持久化对话,刷新不丢失 |
| 04-slash-commands | ⚡ 斜杠命令直接操控会话 |
| 05-compaction | 📦 压缩超长历史,节省上下文 |
| 06-web-tools | 🌐 联网搜索与网页阅读 |
每个步骤都构建在前一步之上,循序渐进,非常适合新手完整跟练。
常见问题
Q:必须用 OpenAI 吗?
不必。LLMProvider 通过 litellm 适配多家提供商,修改 config.example.yaml 中的 provider 与 model 即可切换,业务代码零改动。
Q:为什么要把系统提示词放进 Markdown 文件? 把"人设"与"逻辑"分离,改一个文本文件就能换一只新智能体,无需碰代码——这正是该项目"声明式"设计的精髓。
Q:这个聊天循环能直接用于生产吗? 它是理解 AI Agent 的最佳起点。生产环境还需叠加持久化、并发控制、长期记忆等能力,项目后续步骤(16 并发控制、17 记忆)正是为此设计。
总结
AI Agent 的第一课其实很朴素:一个 while 循环 + 一份会话历史 + 一个系统提示词,就构成了智能体的雏形。build-your-own-openclaw 的 00-chat-loop 用最少的代码,把"会话状态、智能体定义、大模型调用"三层职责清晰地分离开来,为后续 17 个能力升级步骤打下了坚实的地基。
跑通它,你就真正理解了:所谓智能体,就是"会记住、有性格、能行动"的聊天循环。现在,去创建属于你的第一只"猫助手"吧 🐱
📖 完整教程目录与所有步骤说明见项目根目录 README.zh.md
