OpenClaw 从零开始的架构与原理学习笔记

目标读者： – 想系统理解 AI Agent / AI 助手系统是如何真正“跑起来”的开发者 – 对 AutoGPT / LangChain Agent / Devin / Manus 类系统感兴趣的工程师

本文目标： – 把 OpenClaw 当作一个“可拆解的工程样本” – 不只讲“它是什么”，而是讲： – 为什么要这么设计 – 每一层解决了什么工程问题 – 如果你自己做，会踩哪些坑 – 最终你应该能： – 读懂 OpenClaw 的代码结构 – 自己实现一个 Mini-OpenClaw

为什么 OpenClaw 会火
OpenClaw 在整个 AI Agent 版图中的位置
从“聊天机器人”到“行动代理”的范式转变
OpenClaw 的整体架构总览
Gateway：控制平面与消息中枢
Agent Runtime：思考、规划与决策循环
Tool / Skill 系统：让 AI 真正“能干活”
LLM 在 OpenClaw 中到底负责什么
一次完整任务的端到端执行流程
状态、记忆与长期运行
权限、安全与为什么这东西很危险
和 AutoGPT / LangChain / Manus 的架构对比
如果你要自己实现一个：最小实现清单
常见误区与工程教训

1. 为什么 OpenClaw 会火

OpenClaw 的爆火并不是因为：

– 模型更强

– Prompt 写得更骚

而是因为它击中了一个长期被忽视但极其关键的问题：

如何把 LLM 的“语言智能”，转化为“现实世界中的可执行能力”？

在 OpenClaw 之前，大多数系统是：

用户 → LLM → 文本回复

而 OpenClaw 把结构变成了：

用户 → LLM → 行动计划 → 工具调用 → 真实世界变化

这一步的跨越，本质上不是模型问题，而是：

系统架构问题
执行模型问题
安全边界问题

2. OpenClaw 在 AI Agent 版图中的位置

我们先把几个概念放到同一张图里：

系统	核心定位
ChatGPT	对话系统
LangChain Agent	Agent 抽象库
AutoGPT	单机自动化 Agent
Manus / Devin	商业级通用 Agent
OpenClaw	可落地的 Agent 操作系统

一句话总结 OpenClaw：

它不是一个 Agent，而是“跑 Agent 的基础设施”。

3. 从“聊天机器人”到“行动代理”的范式转变

3.1 聊天机器人范式（旧）

核心循环是：

Input → Prompt → LLM → Output

问题： – LLM 只能“说”，不能“做” – 每一次调用都是无状态的 – 无法长期运行

3.2 行动代理范式（新）

核心循环变成：

感知 → 计划 → 行动 → 反馈 → 再计划

这是一个控制系统（Control Loop），而不是问答系统。

OpenClaw 正是围绕这个 Loop 来设计的。

4. OpenClaw 的整体架构总览

先给出一个高层架构图（逻辑）：

┌──────────┐
│ 用户 │
│(WeChat)│
└────┬─────┘
│
┌────▼─────┐
│ Gateway │ ← 控制平面 / 消息中枢
└────┬─────┘
│ WebSocket
┌────▼────────┐
│ Agent Runtime│ ← 思考与决策
└────┬────────┘
│ Tool Call
┌────▼────────┐
│ Skills/Tools │ ← 真正干活
└─────────────┘

非常关键的一点：

Gateway 和 Agent 是解耦的

这是 OpenClaw 能扩展、能多端、能远程的基础。

5. Gateway：控制平面与消息中枢

5.1 Gateway 解决了什么问题

Gateway 本质上解决 3 件事：

多入口统一
- WeChat/ Telegram / Web UI
长连接与事件分发
权限与设备管理

你可以把 Gateway 理解成：

Agent 世界里的 Kubernetes API Server

它不负责“聪明”，只负责“秩序”。

5.2 为什么一定要有 Gateway

很多初学者会问： > 不能 Agent 直接连 WhatsApp 吗？

技术上可以，工程上是灾难。

Gateway 带来的价值： – 解耦通信协议 – 隔离安全边界 – 支持多 Agent / 多客户端

6. Agent Runtime：思考、规划与决策循环

这是整个系统中最容易被误解的部分。

6.1 Agent 不是一个 while(true)

错误理解：

while(true):
调用 LLM

正确理解：

Agent 是一个事件驱动的状态机。

6.2 核心内部结构

典型包含：

Context（上下文）
Memory（记忆）
Planner（计划器）
Executor（执行器）

6.3 Planner 到底在干嘛

Planner 的输出不是自然语言，而是：

Action Plan = [
{ tool: “read_file”, args: {…} },
{ tool: “run_shell”, args: {…} }
]

LLM 在 OpenClaw 中的角色是：

“根据当前状态，选择下一步行动”

而不是直接生成结果。

7. Tool / Skill 系统：让 AI 真正“能干活”

7.1 Skill 是什么

Skill = 带权限的函数

它通常： – 有 JSON Schema 描述 – 有明确输入输出 – 有安全边界

7.2 为什么 Skill 是系统核心

因为：

没有 Tool，Agent 永远只能“想”

OpenClaw 把 Tool 提升为一等公民。

7.3 Tool 的典型分类

文件系统
Shell / 命令执行
浏览器自动化
网络请求
定时任务

8. LLM 在 OpenClaw 中到底负责什么

一个非常重要的澄清：

LLM ≠ Agent

在 OpenClaw 中：

LLM 的职责只有三件： 1. 理解输入 2. 生成计划 3. 评估结果

所有“执行”都在 LLM 之外完成。

9. 一次完整任务的端到端执行流程

我们用一个真实例子：

“帮我把服务器日志里昨天的错误整理成报告”

执行步骤：

消息进入 Gateway
转发给 Agent
Agent 调用 LLM 生成计划
调用 read_file Skill
调用 parse / summarize
生成报告
返回结果

这是一个多步、多状态流程。

10. 状态、记忆与长期运行

10.1 为什么记忆很难

LLM 本身是无状态的
Agent 却必须是有状态的

OpenClaw 的做法是：

记忆外置，推理内置

10.2 记忆类型

短期上下文
长期存储
执行日志

11. 权限、安全与为什么这东西很危险

如果你只记住一句：

OpenClaw = 给 LLM 一把真枪

风险来自： – Shell 执行 – 文件访问 – 网络能力

所以： – 一定要容器隔离 – 一定要权限分级

12. 和 AutoGPT / LangChain / Manus 的架构对比

维度	OpenClaw	AutoGPT	LangChain
控制平面	有	无	无
多端接入	强	弱	无
工程化	高	低	中
风险	高	中	低

13. 如果你要自己实现一个：最小实现清单

你只需要：

一个 Gateway（WebSocket）
一个 Agent Loop
3-5 个 Tool
一个 LLM 接口

就能做出 Mini-OpenClaw。

14. 常见误区与工程教训

在真正动手实现 OpenClaw / AI Agent 系统时，90% 的失败并不是模型不行，而是工程理解错误。

误区一：把 Agent 当成一个“大 Prompt”

很多人一开始会写出类似这样的代码：

async function agent(input: string) {
const prompt = `你是一个智能助手，请完成任务：${input}`
return llm(prompt)
}

这在 Demo 阶段看起来“能跑”，但在工程上是死路一条。

原因： – 没有状态 – 没有中间步骤 – 无法恢复执行 – 无法插入权限与审计

而 OpenClaw 的 Agent 本质是：

一个可被中断、可恢复、可审计的状态机

误区二：Agent 写成 while(true)

经典错误写法：

while (true) {
const action = await llm(context)
await execute(action)
}

问题在于： – 无法区分事件来源 – 无法处理并发 – 无法被 Gateway 正确调度

OpenClaw 的正确思路是：

onEvent(event) {
updateState(event)
if (needPlan()) plan()
if (needAct()) act()
}

这是事件驱动系统，不是脚本。

误区三：忽略权限与安全模型

一旦你给了 Agent： – shell – file – network

你做的事情本质上是：

把“系统管理员权限”交给了一个概率模型

OpenClaw 至少做了三层防护： – Gateway 隔离 – Tool 白名单 – Schema 校验

15. Gateway 深度拆解（含代码示例）

15.1 Gateway 的最小实现

一个最小 Gateway，本质上就是：

import { WebSocketServer } from “ws”

const wss = new WebSocketServer({ port: 3000 })

wss.on(“connection”, ws => {
ws.on(“message”, msg => {
const req = JSON.parse(msg.toString())
dispatch(req, ws)
})
})

但 OpenClaw 在这个基础上增加了： – 设备身份 – Token 认证 – 请求/响应配对 – Event 推送

15.2 请求协议设计

典型请求结构：

{
“type”: “req”,
“id”: “uuid”,
“method”: “agent.call”,
“params”: {
“message”: “分析日志”
}
}

对应响应：

{
“type”: “res”,
“id”: “uuid”,
“ok”: true,
“payload”: { “status”: “accepted” }
}

这是一个 强约束 RPC 协议，而不是随便传 JSON。

16. Agent Runtime 内部结构（工程级）

16.1 Agent 的核心数据结构

interface AgentState {
context: Message[]
memory: MemoryStore
plan?: ActionPlan
status: “idle” | “planning” | “acting”
}

16.2 Plan 的真实形态

interface Action {
tool: string
args: Record<string, any>
}

interface ActionPlan {
actions: Action[]
current: number
}

LLM 输出的不是“我要做什么”，而是：

{
“actions”: [
{ “tool”: “read_file”, “args”: { “path”: “/var/log/app.log” } },
{ “tool”: “summarize”, “args”: {} }
]
}

17. Tool / Skill 的设计哲学（含代码）

17.1 一个最小 Skill 示例

export const readFileSkill = {
name: “read_file”,
schema: {
type: “object”,
properties: {
path: { type: “string” }
},
required: [“path”]
},
async execute({ path }) {
return fs.readFileSync(path, “utf-8”)
}
}

17.2 为什么必须要 Schema

Schema 的作用： – 防止 Prompt Injection – 约束参数 – 给 Gateway 做校验

没有 Schema 的 Tool = 后门。

18. LLM 调用在工程中的真实位置

18.1 Planner Prompt 示例

const prompt = `
你是一个任务规划器。
当前状态：${stateSummary}
可用工具：${toolList}
请输出 JSON 行动计划。
`

注意： – LLM 被严格限制输出格式 – 输出必须能被程序消费

19. 一次真实执行的完整代码路径

Gateway → Agent.onMessage
→ Planner.plan()
→ ToolExecutor.run()
→ State.update()
→ Gateway.pushEvent

这是一个 可追踪、可回放、可审计 的执行链路。

20. 如果你现在自己写一个 Mini-OpenClaw