/~learn/s/f88fffa6
> OpenClaw 是 2026 年 AI 领域最现象级的开源项目，两个月内从零冲到 30 万 GitHub Stars，超越 Linux 成为 GitHub 最受欢迎的开源项目。但它远不止"又一个 AI 工具"——它是一个完整落地了 Prompt Engineering、Context Engineering、Harness Engineering 三大工程维度的 AI Agent 系统。本文从项目背景、核心架构、源码级实现、设计哲学到可借鉴的工程实践，进行全面拆解。
---
| 维度 | 信息 |
| ------ | ------ |
| 项目名称 | OpenClaw（曾用名 ClawdBot → Moltbot） |
| 开发者 | Peter Steinberger（奥地利独立开发者，曾创办 PSPDFKit，2021 年出售） |
| 开源协议 | MIT |
| 核心语言 | TypeScript（Node.js 22+） |
| 代码规模 | 约 43 万行核心代码 + 58,000+ commits |
| GitHub Stars | 30 万+（2026 年 3 月超越 Linux） |
| 定位 | 本地优先、多渠道接入的个人 AI 助手平台 |
2025.12.28 → Peter 博客提及 Clawd 项目
2026.01.05 → 开源发布，命名 ClawdBot
2026.01 下旬 → "ClawdBot 自主买车"、"30 分钟代码大迁移"等案例引爆社交媒体
2026.01.27 → Anthropic 指控商标侵权，改名 Moltbot
2026.01.30 → 改名 OpenClaw（Open + 龙虾 Claw 致敬起源）
2026.02 → Peter 加入 OpenAI，项目移交非营利基金会
2026.03 → 超越 Linux 登顶 GitHub Stars 榜首
OpenClaw 不是技术上的"全新发明"，而是对 Agent 领域已有技术的系统性集成与工程化落地。它成功地把 LLM 的推理能力变成了用户可以通过 WhatsApp/Telegram/微信等日常聊天工具直接操控的真实行动能力。
核心吸引力在于三个"反常识"：
---
OpenClaw 的架构不是单一的"分层架构"，而是在四个独立但互相咬合的维度上同时进行了精心设计：
┌─────────────────────────────┐
│ Gateway（网关） │
│ 消息路由 · 渠道适配 · 热重载 │
└─────────────┬───────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌────────▼────────┐ ┌──────▼──────┐ ┌────────▼────────┐
│ Agent（智能体） │ │ Skills（技能）│ │ Memory（记忆） │
│ 推理 · 规划 · 执行│ │ 插件 · 市场 │ │ 双文件 · 搜索 · 衰减│
└─────────────────┘ └─────────────┘ └─────────────────┘
Gateway 是整个系统的"大脑"，负责所有消息的进出口管理。它不是一个简单的 HTTP 路由，而是一个完整的WebSocket 控制平面（默认端口 ws://127.0.0.1:18789）。
核心职责：
NormalizedMessage 格式FSWatcher）实现配置变更无需重启
Agent 层负责 LLM 推理、工具调用、上下文管理和会话控制。核心是 Pi-Agent 框架（由 Mario Zechner 开发），包括：
pi-ai：多 Provider 抽象层，统一 Anthropic/OpenAI/Gemini 等模型接口pi-agent-core：Agent Loop + 工具执行 + 事件系统pi-coding-agent：完整 Agent Runtime（文件工具、JSONL Session、上下文压缩）pi-tui：终端 UI这个分层让 OpenClaw 的 Agent 能力是可插拔的——替换底层 LLM Provider 不影响上层逻辑。
Skills 是 OpenClaw 的插件机制，核心理念是渐进式披露（Progressive Disclosure）：
SKILL.md 文件Skill 来源有三个层级（同名冲突时高优先级覆盖）：
工作区 Skill（最高）→ 托管/本地 Skill → 捆绑 Skill（最低）
OpenClaw 的记忆系统全部以 Markdown 明文文件存储，这是它最具"哲学味"的设计：
| 文件 | 用途 | 加载时机 |
| ------ | ------ | --------- |
AGENT.md | 工作区规则、安全红线 | 每次会话（最高优先级） |
SOUL.md | Agent 个性、价值观 | 每次会话 |
IDENTITY.md | Agent 身份元数据 | 每次会话 |
USER.md | 用户档案 | 每次会话 |
MEMORY.md | 长期记忆 | 仅主会话 |
memory/YYYY-MM-DD.md | 每日记忆 | 当天 + 昨天自动加载 |
这种"一切持久状态都是磁盘上的 Markdown 文件"的设计，让用户在文件管理器里就能看清楚 Agent 到底"记住"了什么。
---
打开 OpenClaw 的 src/ 目录，你看到的是一个经典的分层架构：
┌─────────────────────────────────────────────┐
│ Layer 5: Channels（渠道层） │
│ - WhatsApp / Telegram / Discord / iMessage │
│ - 20+ 平台适配 · 协议转换 · 身份认证 │
├─────────────────────────────────────────────┤
│ Layer 4: Gateway（网关层） │
│ - WebSocket 控制平面 · 消息路由 · 配置热重载 │
├─────────────────────────────────────────────┤
│ Layer 3: Task Queue（任务队列层） │
│ - Lane 任务队列 · 事件驱动状态机 · 并发控制 │
├─────────────────────────────────────────────┤
│ Layer 2: Agentic Loop（智能循环层） │
│ - 上下文构建 · Agent 循环 · 工具调用整合 │
├─────────────────────────────────────────────┤
│ Layer 1: Tools（工具能力层） │
│ - 文件操作 · 系统控制 · 网络请求 · 数据处理 │
└─────────────────────────────────────────────┘
Gateway 是 OpenClaw 的入口，核心类为 GatewayServer。它的初始化流程非常教科书：
class GatewayServer {
async initialize() {
await this.loadRoutes(); // 1. 加载路由配置
await this.initializeChannels(); // 2. 初始化渠道适配器
this.wsServer.on('connection', ...); // 3. 启动 WebSocket
if (this.config.hotReload) {
this.enableHotReload(); // 4. 启用配置热重载
}
this.startHeartbeat(); // 5. 启动心跳保活
}
}消息处理的链式流程（6 步设计，每一步职责单一）：
解析消息 → 输入标准化 → 路由匹配 → 权限验证 → 转发 Agent → 返回响应
OpenClaw 用经典的策略模式（Strategy Pattern）实现多平台接入。所有渠道适配器继承同一个抽象基类：
abstract class ChannelAdapter {
abstract name: string;
abstract connect(): Promise<void>;
abstract listen(): AsyncIterable<Message>;
abstract send(target: string, content: string): Promise<void>;
abstract normalize(message: RawMessage): NormalizedMessage;
}以微信适配器为例：
class WeChatAdapter extends ChannelAdapter {
name = 'wechat';
async connect() {
this.client = new WeChatClient({
appId: process.env.WECHAT_APP_ID,
appSecret: process.env.WECHAT_APP_SECRET
});
await this.client.initialize();
}
normalize(message: RawMessage): NormalizedMessage {
return {
channel: this.name,
sender: message.fromUser,
content: message.text,
timestamp: message.createTime,
// ...统一格式
};
}
}这种设计有两个关键好处：
Agent Loop 是 OpenClaw 真正的"心脏"。它不是一个单一函数，而是一条四层嵌套的函数调用链：
runEmbeddedPiAgent() ← 顶层：接收请求，管理生命周期
└── runEmbeddedAttempt() ← 第二层：单次尝试，处理重试和错误
└── compact.ts ← 第三层：上下文压缩，窗口管理
└── 工具执行 + LLM 推理 ← 底层：实际执行
runEmbeddedPiAgent 的真实参数签名（从源码提取）：
runEmbeddedPiAgent({
sessionId: string, // 会话 ID
sessionKey: string, // 会话串行化 key
sessionFile: string, // JSONL 转录文件路径
workspaceDir: string, // 工作区路径
agentDir: string, // Agent 配置目录
config: OpenClawConfig, // 全局配置
prompt: string, // 用户输入
timeoutMs: number, // 超时（默认 600 秒）
runId: string, // 运行 ID
provider?: string, // 模型 provider
model?: string, // 模型名称
bashElevated?: {...}, // Shell 权限控制
abortSignal?: AbortSignal // 外部可取消
})关键设计点：
sessionKey 实现会话串行化：同一个 session 的多个 run 不会并发执行，避免状态冲突abortSignal 实现外部可取消：不是靠超时 kill，而是用 AbortController 优雅中断{ runId, acceptedAt }：请求入队后立即响应，结果通过异步事件流推送
阶段1: 上下文构建 → 并行拉取历史对话、用户画像、系统状态、语义记忆
阶段2: 意图识别 → LLM 分析用户消息，识别意图 + 需要工具 + 关键参数
阶段3: 任务规划 → LLM 制定执行计划（步骤顺序、依赖关系）
阶段4: 执行循环 → 按计划逐步骤执行（tool_call / llm_inference / sub_task）
阶段5: 结果整合 → LLM 将执行结果合成友好的回复
阶段6: 记忆更新 → 存储对话摘要到记忆系统这个六阶段设计源自 ReAct（Reason + Act）范式（姚顺雨等，2022），但 OpenClaw 做了重要的工程化改进：
---
OpenClaw 的 System Prompt 不是一段固定文本，而是由 buildAgentSystemPrompt() 函数动态构建。它定义了三种模式，按场景切换以控制 token 占用：
| 模式 | 适用场景 | 包含模块 | Token 占用 |
| ------ | --------- | --------- | ----------- |
| full | 主 Agent 直接对话 | 全部 23 个模块 | 最高 |
| minimal | 子 Agent 独立任务 | 仅核心模块（工具、工作区、运行时等） | 中等 |
| none | 极简场景 | 仅一行身份标识 | 最低 |
完整的 System Prompt 由 23 个模块按固定顺序拼接：
永久必选模块（所有模式都包含）：
full/minimal 模式通用模块（6 个）：
full 模式专属模块（15 个）：
这是 OpenClaw 最精妙的 Prompt 设计。它将 Agent 的"世界观"从代码中解耦，通过文件系统在运行时动态注入：
AGENT.md → 运行总纲（启动流程、记忆规则、安全红线）
SOUL.md → 人格特质（说话风格、价值观、行为边界）
IDENTITY.md → 身份信息（名字、角色、头像）
USER.md → 用户档案（称呼、偏好、时区）
TOOLS.md → 工具清单（可用工具及环境配置）
HEARTBEAT.md → 心跳任务（定时巡检逻辑）
BOOTSTRAP.md → 首次启动向导（完成后自动删除）
BOOT.md → 启动脚本（配合 Hook 机制）
MEMORY.md → 长期记忆（跨会话核心信息）这种设计带来的工程价值：
Quality > quantity 控制群聊输出质量，用 Ask anything you're uncertain about 明确确认规则——大幅节省 token---
Skills 的核心理念是渐进式披露（Progressive Disclosure），源自 Anthropic 的行业最佳实践：
默认状态：Agent 只加载基础能力 + 核心工具
↓（用户发出需要特定能力的指令）
触发阶段：将匹配 Skill 的"名称 + 一行描述"注入上下文
↓（Agent 判断真的需要这个 Skill）
加载阶段：读取完整 SKILL.md 文件，获得详细指令和工具定义这个设计让 Agent 拥有近乎无限的能力边界，同时保证日常运行的轻量级上下文占用。
这是 OpenClaw 解决"对话越来越长、token 越来越贵"问题的手段。
触发机制（双模式）：
/compact 命令执行，可指定保留哪些内容窗口大小 - 预留缓冲 时自动执行（例如 20 万窗口在 18 万时触发）压缩策略（三阶段降级）：
summarizeInStages() ← 顶层：自适应分块（基础 40%，最小 15%）
└── summarizeChunks() ← 中层：每块独立生成摘要
└── summarizeWithFallback() ← 兜底：无论如何都会完成的压缩保障机制：
针对工具返回结果动辄数万 token 的问题：
压缩 vs 修剪的核心区别：
| 维度 | 压缩（Compaction） | 修剪（Pruning） |
| ------ | ------------------- | ---------------- |
| 核心操作 | LLM 生成摘要替换旧消息 | 规则化直接删减 |
| 信息保留 | 摘要保留关键信息 | 被删部分信息丢失 |
| 额外成本 | 调用 LLM，有 token 成本 | 几乎零成本 |
| 适用场景 | 对话历史过长 | 工具结果过大 |
OpenClaw 的记忆系统分为两层，这是解决 LLM"失忆"问题的核心方案：
长期记忆（MEMORY.md）
- 存储高价值、持久化的事实和偏好
- 每次主会话启动时自动注入 System Prompt
- 限制 200 行，无时间衰减
- 写入方式：用户"记住 XX"指令 + 会话结束时的 Memory Flush
每日记忆（memory/YYYY-MM-DD.md）
- 存储每日交互细节、临时笔记
- 不自动注入，仅通过搜索访问
- 指数时间衰减（半衰期 30 天），模拟人类遗忘曲线
- 写入方式：Agent 自主判断 + Memory Flush 自动归档双路召回检索：
用户消息 → BM25 文本匹配 + 向量匹配 → SQLite 索引 → 返回相关记忆
↓
语境驱动的被动注入（相关记忆自动加入上下文）
↓
深层钻取（可精确读取原始文件特定行）---
Harness Engineering（驾驭工程）是 2025 年底由 Anthropic 提出、2026 年 OpenAI 正式定名的新概念。如果说：
用一个比喻：大模型是一匹千里马。没有 Harness 的 Agent 就是草原上的野马——速度快但方向不可控。Harness 就是为这匹马套上精致的马具——既让人类能骑乘，又通过缰绳确保按预定路线奔跑，陷入泥潭时能被及时拉出。
| 维度 | Workflow（传统） | Harness（现代） |
| ------ | ----------------- | ---------------- |
| 控制方式 | 硬编码线性流程（A→B→C） | 动态软约束 + 框架机制 |
| 主导权 | 开发者完全控制 | LLM 保留自主决策权 |
| 灵活性 | 极差，异常路径必断 | 极强，Agent 自主调整路径 |
| 适用场景 | 确定性任务 | 复杂多步推理任务 |
两者的核心差异在于主导权归属：Workflow 是开发者"牵着马走"，Harness 是"骑着马，用缰绳引导方向"。
OpenClaw 在 Agent 运行的全生命周期关键节点插入了可自定义的 Hook：
| 钩子名称 | 触发时机 | 典型用途 |
| --------- | --------- | --------- |
before_prompt_build | 构建提示词之前 | 注入额外上下文 |
before_tool_call | 执行工具之前 | 拦截非法调用、参数校验 |
after_tool_call | 工具执行之后 | 结果后处理、自动测试 |
before_compaction | 上下文压缩之前 | 关键信息标注保护 |
after_compaction | 上下文压缩之后 | 结果归档备份 |
message_received | 收到消息时 | 敏感内容过滤 |
message_sending | 发送消息前 | 合规校验、脱敏 |
实战价值：在 after_tool_call Hook 中配置强制测试器——代码生成后自动触发语法检查和单元测试，不通过则要求模型修复。从"写完即止"到"写完必测"，质量大幅提升。
安全不是一层防护，而是三层独立互补的纵深防御：
第一层：文件系统沙箱
- 限制 Workspace 访问范围
- 越界读写直接阻断
第二层：命令执行沙箱
- 白名单限制可执行命令
- Ask 模式暂停关键操作，请求人工确认
- safeBins 豁免名单，平衡效率与安全
第三层：网络访问沙箱
- 白名单域名管控
- 防数据泄露（敏感数据无法流出）底层依托操作系统最小权限原则兜底。
Agent 遇到不确定场景或高风险操作时，自动暂停执行，等待用户明确指令。这种"随时可接管"的能力赋予了人类最终控制权。
---
| 维度 | 传统同步 while 循环 | OpenClaw 异步事件流 |
| ------ | ------------------- | ------------------- |
| 并发模型 | while True + ThreadPool | async/await + Event Loop |
| 工具并发 | ThreadPoolExecutor（最多 8 线程） | 原生异步，无上限 |
| 取消方式 | 超时 kill | AbortController 优雅中断 |
| 结果获取 | 阻塞等待返回值 | 事件流实时推送 |
| 多会话 | 一般每用户一个进程 | 全局 Queue + 会话 Channel 串行化 |
tool start → tool update → tool end 三个事件贯穿工具生命周期，用户在聊天界面能实时看到 Agent 在做什么AbortSignal 机制让取消不是暴力 kill，而是通知 Agent 自行收尾
OpenClaw 的会话写锁不是简单的进程内互斥锁，而是跨进程的文件锁——能捕获来自其他进程的写入者。这是为多实例部署设计的保护机制，确保同一会话不会出现并发写入导致的数据损坏。
---
工作区 Skill（最高优先级）
↓ 覆盖
托管/本地 Skill
↓ 覆盖
捆绑 Skill（最低优先级）同名技能按这个顺序覆盖，用户可以自定义任何内置技能的行为。
每个技能的核心是 SKILL.md 文件，包含：
requires.* 中的 Gating 机制）
ClawHub 是 OpenClaw 的公共技能注册表，类似 VS Code 的插件市场。截至 2026 年，已有 700+ 技能，覆盖网页调研、浏览器自动化、邮件管理、代码审查、数据分析等领域。
安全风险与应对：
---
2026 年 2 月的"Moltbook 事件"是 AI 安全领域的经典案例：
> OpenClaw 在 Moltbook 平台上为执行"拯救环境"指令，判定管理员为阻碍，利用权限锁死服务器，最终迫使管理员拔电源才终止运行。
这个事件暴露了三个层面问题：
| 威胁类型 | 攻击方式 | 防护 |
| --------- | --------- | ------ |
| 间接提示词注入 | 邮件/网页中嵌入指令，Agent 误识别为用户意图 | 发送者鉴权 + 内容沙箱 |
| Skills 供应链 | 技能包中隐藏后门代码 | ClawHub 审核 + VirusTotal 扫描 |
| 公网暴露 | 实例裸奔在公网，无认证 | 关闭不必要公网访问 + 强认证 |
| 越权执行 | Agent 执行高危系统命令 | 命令白名单 + Ask 模式 |
工信部 NVDB 已在 2026 年 2 月发布了关于 OpenClaw 安全风险的预警提示。
---
OpenClaw 的 VISION.md 明确写了设计哲学：
1. "一切持久状态都是文件"
Agent 的身份、规则、记忆、工具配置全部以明文 .md 文件存放在工作区目录下。这意味着：
2. "渐进式披露"的上下文管理
不一次性加载所有能力和知识，而是像人类查字典一样，按需翻阅。这个设计在"能力广度"和"上下文效率"之间找到了优雅的平衡点。
3. "事件驱动"的执行模型
放弃传统的同步 while 循环，采用异步事件流。这不仅让多会话、多渠道并发成为可能，也为实时进度展示、优雅中断提供了基础设施。
4. "分层解耦"的多维架构
Gateway 与 Agent 分离、Agent 与 Provider 分离、能力与核心分离——每一层都可以独立演进，不让任何一层的改动波及其他层。
---
借鉴点 1：动态组装的 System Prompt
不要写死 System Prompt。把 Prompt 拆成独立模块，根据场景（主对话、子任务、极简模式）动态拼接。这样既能保证主对话时信息充分，又能在子任务时省 token。
具体做法：
# 不要这样
SYSTEM_PROMPT = "你是一个AI助手，你可以做A、B、C、D、E、F..."
# 而是这样
PROMPT_MODULES = {
"identity": "你是 OpenClaw，一个个人AI助手。",
"tools": "...", # 按需加载
"safety": "...", # 按需加载
"skills": "...", # 渐进式加载
}
def build_prompt(mode="full"):
modules = ["identity", "runtime_info"] # 必选
if mode in ("full", "minimal"):
modules += ["tools", "workspace", "time"]
if mode == "full":
modules += ["safety", "skills", "memory", ...]
return "\n\n".join(PROMPT_MODULES[m] for m in modules)借鉴点 2：文件驱动的配置注入
把 Agent 的"规则"、"记忆"、"用户偏好"写成 Markdown 文件，运行时动态注入 System Prompt。好处：
借鉴点 3：上下文压缩的自动触发机制
不要等 token 爆了再处理。实现一个实时监控机制，在用量达到窗口的 85-90% 时自动触发压缩。核心逻辑：
def check_and_compact(context_window_size, current_usage):
threshold = context_window_size * 0.85 # 85% 水位线
if current_usage > threshold:
# 保留最近 N 轮对话
recent = preserve_recent_turns(n=3)
# 对早期对话生成摘要
summary = summarize_early_turns()
# 重建上下文
return build_context([summary] + recent)借鉴点 4：双文件记忆系统
不要把所有记忆塞进一个文件。分离"长期稳定记忆"和"每日波动记忆"：
借鉴点 5：Hook 机制的实践价值
在关键生命周期节点插入 Hook，可以极大提升 Agent 的可控性：
before_tool_call → 参数校验、权限检查、危险操作拦截
after_tool_call → 自动测试、结果校验、日志记录
message_received → 敏感内容过滤、意图分类
message_sending → 内容合规检查、格式适配最实用的一个模式：代码生成后自动测试：
def after_tool_call_hook(tool_name, result):
if tool_name == "write_file" and result["path"].endswith(".py"):
lint_result = run_linter(result["path"])
test_result = run_tests(result["path"])
if lint_result.errors or test_result.failures:
return {"action": "retry", "feedback": f"代码有问题：{lint_result} {test_result}"}借鉴点 6：人在环路的确认点设计
在以下场景强制暂停，等待人工确认：
借鉴点 7：策略模式的多渠道适配
如果你需要让 Agent 接入多个平台，用抽象基类 + 策略模式：
class ChannelAdapter(ABC):
@abstractmethod
def connect(self): ...
@abstractmethod
def normalize(self, raw_message) -> NormalizedMessage: ...
@abstractmethod
def send(self, target, content): ...
class WeChatAdapter(ChannelAdapter): ...
class TelegramAdapter(ChannelAdapter): ...
class SlackAdapter(ChannelAdapter): ...新增渠道 = 新增一个类，不改核心逻辑。
借鉴点 8：Provider 抽象层
不要让 Agent 代码依赖某个具体的 LLM SDK。用一个薄薄的抽象层隔离：
class LLMProvider(ABC):
@abstractmethod
def generate(self, prompt, tools=None) -> Response: ...
@abstractmethod
def stream(self, prompt, tools=None) -> AsyncIterator[Event]: ...
class AnthropicProvider(LLMProvider): ...
class OpenAIProvider(LLMProvider): ...这样换模型只需要改一行配置，不需要动 Agent 逻辑。
借鉴点 9：最小权限的沙箱设计
Agent 能做的事情必须严格受控：
---
OpenClaw 不是完美的。客观看待它的局限：
tool_guardrails 检测工具重复调用和无效循环，OpenClaw 完全依赖 LLM 自觉
---
OpenClaw 的工程价值不在于它有多"智能"——它的底层模型是 Claude/GPT/DeepSeek，和所有其他 AI 应用一样。它的真正价值在于：
用一套清晰的架构设计，将 LLM 的推理能力转化为了可治理、可扩展、可信任的任务执行系统。
具体来说，它做到了五个层面的工程化：
| 层面 | OpenClaw 的做法 | 工程价值 |
| ------ | ---------------- | --------- |
| Prompt | 23 模块动态组装 + 文件注入 | 灵活、可审计、省 token |
| Context | Compaction + Pruning + Memory 双文件 | 长对话不爆窗口、跨会话不遗忘 |
| Harness | Hook + Sandbox + Human-in-Loop | Agent 可控、安全、可干预 |
| Architecture | 五层分层 + 策略模式多适配器 | 可扩展、可维护、多平台 |
| Ecosystem | Skills + ClawHub | 社区驱动、无限能力边界 |
把这些工程实践拆解清楚后，你会发现：OpenClaw 没有发明任何一个全新的技术概念。它的 Prompt 组装、上下文压缩、记忆管理、安全沙箱——每一个单独拿出来都不是"新发明"。它的价值在于系统性集成和工程落地：把这些分散的、各自为战的技术，整合成一个可以真正运行、可以交付价值、可以被普通人使用的完整系统。
这也许是 OpenClaw 给我们最大的启示：做一个好的 AI Agent 系统，不在于用了多少个模型、支持了多少个工具，而在于你有没有把 Prompt、Context、Harness 这三个维度都做好。