AI Agent 第一课:build-your-own-openclaw 聊天循环 Chat Loop 从 0 到 1 完整实现

原创2026-10-09 19:50:111,732 阅读
文章标签:示例工程教程人工智能AI AgentAI 应用Agent 工作流提示工程LLM 网关

AI Agent 第一课:build-your-own-openclaw 聊天循环 Chat Loop 从 0 到 1 完整实现

AI Agent 的第一课,往往不是写复杂的代码,而是搭好一个最朴素的 Chat Loop(聊天循环)。开源教程 build-your-own-openclaw 用 18 个循序渐进的步骤,手把手教你从零构建一个生产级 AI 智能体——而起点,正是这个不到 20 行的聊天循环。本文将带你完整拆解它的设计思路、核心代码与运行机制,5 分钟就能跑通属于自己的第一个 AI Agent 🚀

build-your-own-openclaw 项目封面:一个圆点一步步进化成橙色小机器人,展示 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 能连续对话?因为它每次都看到完整的历史。这一层由两个类协作完成:

其中 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

登录后查看全文
build-your-own-openclaw