夜雨聆风OpenClaw 是一个本地优先的 AI 助手平台——它让你可以用聊天的方式让 AI 帮你执行各种现实任务，比如查天气、控制智能家居、处理文件、甚至操作你的电脑。这一切都运行在你自己的设备上（电脑或树莓派），隐私安全，可定制性强。
这篇文章会用一个完整的故事，从你发出一条消息开始，一步步拆解 OpenClaw 内部发生了什么。我们会用大量比喻，并在括号里标注对应的技术术语，让你既理解逻辑，又知道专业名词。最后会总结 OpenClaw 的核心设计思想。
一、开篇：从一条消息说起
假设你已经在电脑上安装并配置好了 OpenClaw，并且把它连到了 Telegram（或微信、Slack 等聊天软件）。
现在你在手机上打开 Telegram，给 OpenClaw 发了一条消息：
“北京天气怎么样？”
接下来，OpenClaw 会经历三个核心阶段：
上下文组装：把“你是谁、AI 能做什么、双方记得什么”整理成一份结构化的“工作说明书”。
模型决策：让 AI 大脑（大模型）读懂说明书，判断“是否需要用工具”“用哪个工具”“需要什么参数”。
指令翻译与执行：把 AI 的决策转换成具体动作，在本地安全执行，最后把结果回复给你。
下面我们跟着这条消息，完整走一遍这个流程。
二、阶段一：上下文组装——给 AI 大脑准备“工作说明书”
🔍 谁在干这件事？
OpenClaw 的核心组件 Gateway（网关） 是这个环节的核心执行者。
你可以把它想象成一家公司的 前台：它负责接听用户的“咨询电话”（接收消息），整理所有和当前任务相关的材料，为后续“老板（AI 模型）”做决策提供完整依据。
具体来说，Gateway 会调用 runEmbeddedPiAgent 程序完成上下文组装的核心工作——这个程序就像前台的“专属助理”，专门负责整理材料、打包说明书。
📁 材料从哪里来？
前台需要从“公司档案室”调取材料，这个档案室对应你设备上的固定文件夹：~/.openclaw/workspace/
补充：
~是系统默认的用户目录，Windows 下是C:\Users\你的用户名\.openclaw\workspace\，Mac/Linux 是/home/你的用户名/.openclaw/workspace/
档案室里存着六类核心材料，每一类都对应 AI 助手的关键能力：
| 材料类型 | 文件名/路径 | 通俗比喻 | 核心作用（技术说明） |
|---|---|---|---|
| 人格设定 | SOUL.md | 员工的性格/说话风格 | 定义 AI 的语气（如“简洁”“幽默”）、身份（如“个人助理”） |
| 用户档案 | USER.md | 客户专属档案 | 存储你的基础信息（如姓名、时区、常用单位） |
| 行为准则 | AGENTS.md | 员工工作手册 | 定义高级规则（如群聊礼仪、记忆筛选标准、权限边界） |
| 长期记忆 | MEMORY.md | 重要事项备忘录 | 存储经过筛选的持久化信息（如“用户偏好摄氏度”） |
| 短期对话 | memory/YYYY-MM-DD.md | 近期聊天记录 | 按日期分文件存储完整对话，避免单文件过大，方便回溯 |
| 技能清单 | skills/ 下的子文件夹 | 员工技能库 | 每个文件夹对应一个功能（查天气/处理文件），内含 SKILL.md（技能说明）和可执行脚本 |
🧩 如何组装？
前台不会简单拼接所有文件（否则会超出模型的处理上限），而是交给 档案管理员（ContextEngine） 智能处理：
筛选记忆：从长期记忆中提取和当前问题相关的内容（比如你之前问过北京天气），从短期对话中截取最近几条（保证上下文连贯）；
整理技能：从
skills/中提取所有可用技能的核心信息——技能名称、作用、所需参数（如“天气工具需要城市名”）；结构化打包：把上述内容整合为两部分，形成最终的“工作说明书”：
自然语言版系统提示：用模型能理解的语言，说明 AI 的身份、记忆、可用技能；
结构化版工具列表：以 JSON 格式列出所有技能的名称和参数要求，确保模型能精准调用。
💡 核心思想：上下文组装是 OpenClaw 的“灵魂”。它让 AI 从“通用聊天机器人”变成“有记忆、有个性、有工具的专属助理”。ContextEngine 是可插拔的——你可以自定义记忆管理方式（比如用向量数据库做语义搜索、用数据库存储无限对话），既保证 AI “记性好”，又不超出模型的 token 限制。
三、阶段二：模型决策——AI 大脑决定用什么工具
🧠 谁在决策？
AI 大脑是大语言模型（LLM），既可以是云端模型（如 GPT-4、Claude），也可以是本地运行的开源模型（如 Llama 3、Qwen）。
它的核心职责只有一个：理解问题 + 做出决策，不负责实际执行操作。
🤔 它是怎么思考的？
Gateway 把“工作说明书”（系统提示 + 工具列表 + 你的问题）通过 API（云端模型）或本地接口（开源模型）发给 LLM。
LLM 读完后，会输出一份结构化的指令单——核心是“是否用工具”“用哪个工具”“传什么参数”。
示例指令单（JSON 格式）：
{"tool": "weather","parameters": {"city": "Beijing","unit": "celsius"}}
📌 关键技术细节
云端模型（如 GPT-4）：会在响应的
tool_calls字段中返回标准化的工具调用指令；本地开源模型（如 Llama 3）：通过 Prompt 工程引导模型输出符合格式的 JSON（比如在系统提示中明确指令单的格式要求）；
无工具调用场景：如果问题不需要工具（如“你好”），模型会直接输出自然语言回答，跳过后续执行步骤。
📦 输出返回给谁？
指令单会原路返回给 Gateway（前台），等待下一步调度。
💡 核心思想：OpenClaw 不自研模型，而是兼容所有支持“函数调用/结构化输出”的 LLM。这种“模型无关”的设计让它可以灵活切换大脑（比如云端换本地、GPT 换 Llama），适配不同的隐私/性能需求。
四、阶段三：指令翻译与执行——从 JSON 到真实动作
Gateway 收到指令单后，需要把抽象的 JSON 转换成具体的操作，这分为三步：
1. 找到能干活的人（任务路由）
Gateway 内置了 员工花名册（Registry）——记录所有在线的执行端（Pi-embedded）、每个执行端的技能（如“树莓派会控制智能家居，电脑会处理文件”）。
Registry 会根据指令单里的工具名（如 weather），匹配到“会查天气”的执行端（比如你的电脑）。
为什么需要多个执行端？
不同设备有不同能力：电脑适合处理文件/操作软件，树莓派适合控制智能家居，你可以把技能分散部署在不同设备上，Gateway 自动分发任务，最大化设备利用率。
2. 翻译成执行端能懂的“密电码”（协议转换）
Gateway 和执行端之间不用 JSON 通信（文本格式体积大、解析慢），而是用 Protobuf——一种轻量的二进制协议（可以理解为“内部速记符号”）。
Gateway 会把 JSON 指令单转换成 Protobuf 格式，再通过 WebSocket 长连接 发给选定的执行端（长连接能保证实时通信，避免反复建立连接）。
3. 执行端动手干活（沙箱安全执行）
执行端（Pi-embedded）收到消息后，不会直接运行脚本（避免恶意代码/依赖冲突破坏系统），而是在隔离沙箱中执行：
🛡️ 沙箱执行的完整步骤：
创建临时文件夹（Linux/Mac：
/tmp/openclaw-sandbox-12345；Windows：C:\Users\用户名\AppData\Local\Temp\openclaw-sandbox-12345）；在临时文件夹中启动 Python 虚拟环境（venv）——安装该技能专属的依赖（如查天气需要
requests），避免和系统/其他技能的依赖冲突；复制技能脚本（如
skills/weather/__main__.py）到沙箱，传入参数（--city Beijing --unit celsius）运行；脚本调用第三方 API（如天气 API）获取数据，输出结果；
执行端捕获脚本输出，若脚本超时（默认 30 秒）/报错，立即终止并返回错误信息；
执行完成后，清理沙箱临时文件（避免占用存储空间）。
最后，执行端把结果打包成 Protobuf 格式，通过 WebSocket 发回 Gateway。
💡 核心思想：沙箱是 OpenClaw 的“安全底线”。本地运行代码存在系统安全风险，沙箱通过“隔离环境 + 临时目录 + 超时限制”，保证即使技能脚本出错/有恶意代码，也不会影响你的设备和数据。
五、结果返回——你收到最终回答
Gateway 收到执行端返回的结果后，会把二进制的 Protobuf 转回文本格式，再整理成自然语言（比如“北京今天15℃，晴朗，微风”），最后通过你使用的聊天软件（如 Telegram）发给你。
至此，从“发消息”到“收回答”的完整流程结束。
六、核心总结：OpenClaw 的三大核心设计
| 核心设计 | 具体实现 | 核心价值 |
|---|---|---|
| 大脑与肢体分离（Gateway + Pi-embedded） | Gateway 管对话/调度，执行端管本地操作 | 云端模型（强理解能力）+ 本地执行（隐私安全），兼顾能力与隐私 |
| 技能即文件夹（Skills） | 每个技能 = 一个文件夹 + SKILL.md + 脚本 | 零代码门槛扩展功能：创建文件夹、写说明+脚本，AI 自动识别使用 |
| 记忆与上下文可插拔（ContextEngine） | 可自定义记忆管理策略（数据库存储/语义搜索） | 解决 LLM 上下文有限的问题，让 AI 既“记得久”又“不超载” |
七、文字流程图：一步一步看全流程
为了让你更直观地理解整个过程，下面用文字把每一步串联起来：
1. 你发送消息
你通过 Telegram 发送：“北京天气怎么样？”
↓
2. Gateway（前台）接收
Gateway 调用 runEmbeddedPiAgent，加载 skills/ 下的所有技能说明（SKILL.md）。
↓
3. ContextEngine 整理材料
读取 SOUL.md、USER.md、MEMORY.md、近期对话记录。
从长期记忆中筛选与“北京天气”相关的内容。
生成系统提示（自然语言） + 工具列表（JSON）。
↓
4. 发给 AI 大脑（LLM）
将系统提示 + 工具列表 + 用户问题一起发送给大模型（GPT-4、Llama 3 等）。
↓
5. AI 输出指令单模型返回 JSON 格式的指令，例如：
{"tool": "weather", "parameters": {"city": "Beijing", "unit": "celsius"}}↓
6. Gateway 路由任务
查询 Registry（员工花名册），找到能执行
weather的执行端（比如你的电脑）。将 JSON 指令转换为 Protobuf 二进制格式。
通过 WebSocket 长连接发送给对应的 Pi-embedded 执行端。
↓
7. 执行端沙箱运行
创建临时文件夹（如
/tmp/openclaw-sandbox-12345）。在该文件夹中启动 Python 虚拟环境，安装
weather技能所需的依赖（如requests）。运行
skills/weather/__main__.py，传入参数--city Beijing --unit celsius。脚本调用第三方天气 API，获取实时天气数据。
捕获脚本输出，若超时或出错则立即终止。
↓
8. 结果返回 Gateway
执行端将结果（如“北京今天15℃，晴朗”）打包成 Protobuf 格式，通过 WebSocket 发回 Gateway。
↓
9. 你收到最终回答
Gateway 将结果转为自然语言文本，通过 Telegram 发给你。
八、为什么这样设计？——解决 AI 落地的三大核心痛点
| 行业痛点 | OpenClaw 的解决方案 |
|---|---|
| 隐私与能力不可兼得（用云端模型泄露数据，用本地模型能力弱） | 大脑（LLM）与肢体（执行端）分离：云端模型做决策，本地执行端处理敏感操作，数据不离开设备 |
| 扩展功能太复杂（改核心代码/等官方更新） | 技能即文件夹：新增功能只需创建文件夹+写说明+脚本，无需修改核心逻辑，即插即用 |
| AI 记不住上下文（对话超过 token 就遗忘） | 可插拔 ContextEngine：用数据库存储完整对话，每次只给模型传“相关记忆+摘要”，兼顾记性和效率 |
最后的话
OpenClaw 的本质是本地优先的 AI 代理框架——它不追求“造模型”，而是聚焦“让 AI 落地做事”：
用 Gateway 解决“对话管理+任务调度”，用 Pi-embedded 解决“安全执行+设备适配”，用“技能文件夹”解决“无限扩展”，用 ContextEngine 解决“记忆问题”。
无论你是想做智能家居助手、自动化办公机器人，还是能操作电脑的 AI 秘书，OpenClaw 都提供了一套“安全、灵活、易扩展”的基础架构。
如果你理解了上述流程，就掌握了 OpenClaw 的核心逻辑——接下来只需安装部署、写第一个技能脚本，就能体验让 AI 真正“动手”帮你做事的乐趣。
总结
OpenClaw 的核心流程是“上下文组装→模型决策→安全执行”，通过 Gateway 与 Pi-embedded 分离实现“云端智能+本地隐私”；
技能以文件夹形式存在，零门槛扩展功能，沙箱执行保证本地操作安全；
可插拔的 ContextEngine 解决了 LLM 上下文有限的问题，让 AI 既有长期记忆，又不超出处理能力。
