从零实现 OpenClaw (01)：架构总览与具身智能时代的路径选择

​

引言：当 AI 从“聊天框”走向“操作系统”

都说2024年是 Llama、Claude 与 GPT 大模型爆发的元年，而 2025-2026 年则是 Agent（智能体）工程化的质变期。站在 2026 年的时间节点回望，AI 的发展史在 2024 年发生了一个隐秘的分叉：一支走向了参数规模的极致（Scale-up） ，追求更强的逻辑推理；另一支则走向了工程落地的极致（Action-oriented） ，追求如何让模型控制现实。

OpenClaw 属于后者。

在过去的两年里，开发者们经历了从 LangChain 的“抽象疲劳”到 AutoGPT 的“死循环焦虑”。我们发现，制约智能体进化的往往不是 LLM 读不懂指令，而是系统的架构无法承载物理世界的复杂性、延迟与不确定性。

我们不再满足于在 Web 界面输入 Prompt 并获得一段文字回复。开发者们正在追求一种更高级的形态：它能感知环境（Vision/Sensor）、能自主决策（Planning）、能操作工具（Tool Use），并且拥有跨越 Session 的长期记忆。这就是 OpenClaw 项目的初衷——构建一个如同“利爪”般精准、敏捷且能够抓取物理与数字世界的通用 Agent 框架。

本系列博客将不仅是一份代码教程，更是一场关于“如何从底层构建复杂 AI 系统”的工程实践。

一、 OpenClaw 的核心设计哲学

在动笔写第一行代码之前，我们需要回答一个核心问题：为什么在 LangChain、AutoGPT 漫天飞舞的今天，我们还要从零实现 OpenClaw？

绝大多数现有的框架要么过于“沉重”（抽象过度导致调试极其困难），要么过于“玩具”（仅能跑通 Demo，无法处理生产环境的并发与韧性），总结起来核心痛点：

1. 过度封装的“黑盒”困境

许多框架为了追求“一行代码启动”，封装了极为复杂的类层级。当 Agent 运行出错时，开发者往往需要跳转十层代码才能找到是哪个 Prompt 注入失败了。 

2. “同步思维”处理“异步世界”

传统的 Agent 框架大多基于 HTTP 轮询。但在操作机械臂或进行实时情感陪伴时，几百毫秒的延迟就会导致物理碰撞或情感断裂。 

3. 记忆的“碎片化”与“遗忘症”

简单的 RAG（检索增强生成）并不能称为记忆。它只是在翻阅一张巨大的报纸。真正的记忆需要有权重的演减和情感的锚点。 

OpenClaw 遵循以下三个核心原则：

1. 最小抽象（Minimal Abstraction）： 拒绝套娃式的类继承。我们优先使用 Python 的 Type Hints 和原生异步协程，确保每一行代码的可观测性。
2. 消息驱动（Message-Centric）： 借鉴操作系统的微内核设计，所有的组件（LLM、记忆、硬件接口）通过 Gateway 消息总线进行通信，天然支持分布式部署。全链路异步（Asyncio）+ 双工通信（WebSocket）。将系统视为一个实时事件流，而非单纯的请求-响应。
3. 具身潜质（Embodied-Ready）： 从设计之初就考虑硬件接入（如机械臂、传感器），将物理世界的反馈视为与文本同等地位的一等公民。引入“分层存储”模型，将瞬时感性、短期逻辑与长期事实彻底分离。

二、 系统架构全景图

OpenClaw 采用 C/S（Client/Server）解耦架构，将复杂的逻辑推理与多样的接入端分离。

1. 核心层：Agent Loop（大脑）

这是系统的“心脏”，基于 ReAct（Reason + Act） 范式。它负责将模糊的用户意图分解为可执行的任务序列。

• 感知（Observe）： 接收来自 Gateway 的多模态数据。
• 思考（Thought）： 利用 LLM 生成内部单步推理。
• 行动（Action）： 调用注册好的 Skills（工具）。

2. 通信层：Gateway（神经系统）

OpenClaw 不直接绑定任何平台。通过 WebSocket/FastAPI 路由，我们可以同时接入 T@elegrimm、微信、网页端，甚至是一台基于 ROS2 的机械臂。Gateway 负责消息的标准化映射，确保核心层只处理 OpenClawMessage 协议。

3. 持久化层：Persistence（海马体）

不同于简单的数据库，OpenClaw 的持久化分为三层：

• Short-term (Buffer)： 当前对话的上下文，存储在 Redis 或内存中。
• Long-term (Archive)： 基于 SQLite 的结构化历史记录。
• Semantic (Vector)： 基于向量数据库（如 Chroma/Qdrant）的知识检索。

4. 技能层：Skill System（双手）

Skill 是 OpenClaw 操作世界的接口，每一个 Skill 都是一个独立的函数封装，通过 Python 装饰器自动生成 JSON Schema，实现与 LLM 的“零成本”对接。

定义了一套 SKILL.md 规范，任何 Python 函数只要符合规范，都可以被自动加载为 Agent 的一项技能。

• 安全性： Skill 运行在独立的沙箱环境中，防止 Agent 生成的恶意代码污染宿主机。

三、 路径选择：为什么选择这套技术栈？

在工程实现上，我们拒绝盲目追新，而是选择了在生产环境中被验证过的组合：

1. 语言：Python 3.10+

虽然 Rust 在性能上更有优势，但 Python 在 AI 生态位上的统治力不可动摇。利用 asyncio，我们可以轻松处理 Agent 在调用 LLM 时的 I/O 等待。

2. 核心引擎：LiteLLM

为了避免绑定在 OpenAI 这一棵树上，我们使用 LiteLLM 作为中间层。它允许 OpenClaw 在不改动核心代码的情况下，一键切换 DeepSeek、Claude 3.5 或本地部署的 Llama 3。

3. 通信协议：JSON-RPC over WebSocket

对于情感陪伴或硬件控制场景，低延迟是关键。WebSocket 允许服务器主动推送消息（如 Agent 主动关怀），这是传统 REST API 难以实现的。

4. 数据安全：Docker Sandbox

在后续章节中，我们将引入 Docker 代码解释器。当 Agent 决定写一段 Python 代码来分析你的 Excel 时，这段代码将在隔离的沙箱中运行，确保你的宿主机安全。

四、 核心数据模型定义

代码是最好的说明书。在 OpenClaw 中，一切皆消息。以下是我们定义的通用协议雏形：

from pydantic import BaseModel, Field
from typing import List, Optional, Any
from datetime import datetime

class Message(BaseModel):
    role: str  # system, user, assistant, tool
    content: str
    sender_id: str
    timestamp: datetime = Field(default_factory=datetime.now)
    attachments: Optional[List[str]] = None  # 图像、文件或传感器数据 URL

class AgentState(BaseModel):
    session_id: str
    memory_context: List[Message]
    current_plan: List[str]
    mood_score: float = 1.0  # 针对情感陪伴场景的扩展

五、 结语

架构图画得再漂亮，也抵不过第一行运行成功的 print("Hello, OpenClaw")。

OpenClaw 是一场关于“构建自主性”的实验。我们不希望创造一个只会复读的程序，我们要创造一个能感知寒暑、能记住承诺、能挥动机械臂改变物理世界的伙伴。

这篇博文不仅仅是教你写代码。通过参与 OpenClaw 的从零实现，你将在 2026 年的技术浪潮中建立以下壁垒：

1. 工程化 Agent 的深度理解： 了解如何处理大模型的非确定性输出，如何设计具备韧性（Resilience）的复杂系统。
2. 具身智能的先发优势： 当别人还在写网页翻译插件时，你已经掌握了如何用大脑模型驱动硬件。
3. 社区规范的制定者： 通过贡献 SOUL.md 或 SKILL.md，你参与定义的协议可能成为未来 Agent 协作的标准。

下一篇预告： 我们将进入代码实操阶段。不再是简单的 client.ch@t.completions，我们将手写一个能够自我修正、具备多步思考能力的 最小 Agent Loop。

​本系列文章原创首发于 CSDN，原文链接：blog.csdn.net/wyj333333/a… 作者：Wu_Dylan，转载请注明出处