OpenClaw 源码架构与设计理念深度解析

北巷`2026-04-04 22:34

基于 github.com/openclaw/openclaw 源码与官方文档的技术分析，全面拆解 OpenClaw 的仓库结构、核心模块、运行机制与设计哲学。

一、项目定位与设计哲学

1.1 OpenClaw 是什么

OpenClaw 不是一个 AI 模型，而是一个 AI Agent 运行时框架（Runtime Framework） 。它是坐在 AI 模型和外部世界中间的单体运行时网关，负责将自然语言指令转化为真实的系统操作。

核心定位公式：

复制代码 
OpenClaw = Gateway（网关） + Agent Runtime（运行时） + Skills（技能） + Memory（记忆）

1.2 设计哲学

理念 说明
Local-first 本地优先，数据不离开用户设备，隐私安全
网关而非框架 不是 SDK/库，而是独立运行的控制平面
模型无关 支持 Claude、GPT、Gemini、DeepSeek 等任意 LLM
插件化内核 Skills、Channels、Providers 均可热插拔
工程化 Agent 从聊天机器人升级为任务调度执行系统

1.3 命名含义

  • Claw：龙虾钳子，象征"抓取、操控与执行"能力
  • Open：完全开源（MIT 协议），社区驱动
  • Molt（早期命名 Moltbot）：蜕皮，代表底层状态重置与自我进化
  • 项目前身：Clawdbot → Moltbot → OpenClaw

二、仓库顶层目录结构

复制代码 
openclaw/
├── .agent/workflows/      # 内置 Agent 工作流描述
├── .agents/               # 多 Agent 默认配置
├── .pi/                   # Agent Runtime 配置（历史遗留命名，源自早期项目代号）
├── apps/                  # 可独立部署的应用（macOS App 等）
├── extensions/            # 浏览器插件等扩展
├── packages/              # 内部共享包（TypeScript 类型等）
├── skills/                # 社区 Skills（每个子目录含一个 SKILL.md）
│   ├── weather/SKILL.md
│   ├── github/SKILL.md
│   ├── notion/SKILL.md
│   └── ...                # 50+ 个 Skills
├── src/                   # Gateway 主体源码（TypeScript/Node.js）
│   ├── gateway/           # Gateway 核心：server.ts、boot.ts 等
│   ├── agents/            # Agent Runtime（复数 agents）
│   ├── sessions/          # Session 存储与管理
│   ├── channels/          # Channel 基础抽象
│   ├── slack/             # Slack 适配器（Bolt）
│   ├── telegram/          # Telegram 适配器
│   ├── discord/           # Discord 适配器
│   ├── imessage/          # iMessage 适配器
│   ├── whatsapp/          # WhatsApp 适配器
│   ├── webchat/           # WebChat 内置前端
│   ├── providers/         # LLM Provider 抽象与实现
│   ├── tools/             # 内置工具集
│   ├── memory/            # 记忆系统
│   ├── cli/               # CLI 命令入口
│   └── utils/             # 通用工具函数
├── config/                # 默认配置模板
├── docs/                  # 官方文档
├── tests/                 # 测试用例
├── package.json           # 项目依赖与脚本
├── tsconfig.json          # TypeScript 配置
└── README.md              # 项目说明
graph TB
    Root[openclaw/] --> Apps[apps/]
    Root --> Extensions[extensions/]
    Root --> Packages[packages/]
    Root --> Skills[skills/]
    Root --> Src[src/ 核心源码]
    Root --> Config[config/]
    Root --> Docs[docs/]
    Root --> Tests[tests/]
    
    Src --> GW[gateway/]
    Src --> Agents[agents/]
    Src --> Sessions[sessions/]
    Src --> Channels[channels/]
    Src --> Providers[providers/]
    Src --> ToolsMod[tools/]
    Src --> MemoryMod[memory/]
    Src --> CLI[cli/]
    
    Skills --> Weather[weather/SKILL.md]
    Skills --> Github[github/SKILL.md]
    Skills --> More[... 50+ Skills]

三、五层服务架构

OpenClaw 源码实现了清晰的五层服务分层，每一层职责分明、松耦合。
第1层 渠道适配层 Channel Adapter
第2层 网关服务层 Gateway Server
第3层 Agent Runner 智能体运行器
第4层 Agent Runtime / Agentic Loop
第5层 Memory & Skills 记忆与技能

3.1 第一层：渠道适配层（Channel Adapter）

源码位置 ：src/channels/、src/slack/、src/telegram/ 等

把 Discord、Telegram、钉钉、飞书等不同平台的输入转成统一消息格式，同时提取附件。一个 Agent 挂多个渠道就靠这一层。

typescript 复制代码 
// 统一的 ChannelProvider 接口
interface ChannelProvider {
  name: string;
  start(): Promise<void>;
  stop(): Promise<void>;
  sendMessage(sessionId: string, message: Message): Promise<void>;
  onMessage(handler: MessageHandler): void;
}

设计要点：

  • 每个渠道实现统一的 ChannelProvider 接口
  • 消息格式归一化：不同平台的消息统一为 Message 对象
  • 附件提取：图片、文件、语音等多媒体内容统一处理
  • 支持 20+ 渠道：Slack、Telegram、Discord、WhatsApp、iMessage、微信、钉钉、飞书等

3.2 第二层：网关服务层（Gateway Server）

源码位置 ：src/gateway/server.ts、src/gateway/boot.ts

流量总入口，基于 WebSocket/HTTP 构建控制平面。
外部消息
Session Router 会话路由
Lane Queue 车道队列
Agent 分发
Session 存储
并发控制

核心组件：

组件 源码 职责
Session Router src/sessions/ 判断消息属于哪个会话，构建 SessionKey
Lane Queue src/gateway/ 车道队列做并发管理，防止请求撞车或上下文串
WebSocket Server src/gateway/server.ts 实时双向通信，跨端消息同步
HTTP API src/gateway/server-*.ts RESTful 接口，配置管理、UI 控制台
Cron Scheduler src/gateway/ 定时任务调度（HEARTBEAT 机制）
Webhook Handler src/gateway/ 外部事件推送处理

3.3 第三层：Agent Runner（智能体运行器）

源码位置 ：src/agents/pi-embedded-runner/

负责模型选择、API Key 轮换冷却、提示词拼装和上下文窗口管理。

关键职责：

  • 模型路由：根据 Agent 配置选择对应的 LLM Provider
  • API Key 管理：多 Key 轮换、冷却、限流
  • 提示词构造：将 System Prompt + 上下文 + 工具描述 + 用户输入拼装为完整 Prompt
  • 上下文窗口：Token 计算、上下文截断/压缩策略

3.4 第四层：Agent Runtime / Agentic Loop

源码位置 ：src/agents/pi-embedded-runner/run/attempt.ts

这是 OpenClaw 最核心的运行循环，严格遵循 ReAct（Reason + Act） 范式：
文本回复
工具调用
接收任务
构建上下文
调用 LLM 模型
解析响应
发送回复
执行工具
获取执行结果
更新上下文
保存记忆
完成

核心循环逻辑：

  1. 从会话历史和记忆中拼装上下文
  2. 调用 LLM 模型进行推理
  3. 模型说"我要调工具" → 系统执行工具
  4. 工具结果塞回上下文 → 模型继续推理
  5. 循环直到模型生成最终文本回复

3.5 第五层：Memory & Skills

源码位置 ：src/memory/、skills/

记忆系统和技能系统是 Agent 的"经验"和"方法论"。

四、核心配置文件体系

OpenClaw 通过一组 Markdown 配置文件定义 Agent 的身份、记忆和行为：
Agent 配置体系
AGENTS.md
SOUL.md
IDENTITY.md
USER.md
TOOLS.md
HEARTBEAT.md
BOOTSTRAP.md
MEMORY.md
核心任务 工作流程 常用命令
工作风格 对话风格 人格设定
系统中的职责定位
用户使用场景和目标
环境特定配置信息
周期性唤醒 健康检查
初始化配置
长期记忆 重要事件 学习总结

文件 职责 变更类型
AGENTS.md 核心任务、工作流程、常用命令 规范更新、流程优化
SOUL.md 工作风格、对话风格、人格设定 人设变更、边界调整
IDENTITY.md 智能体在系统中的职责定位 角色重定义
USER.md 用户使用场景和目标 用户反馈记录、偏好调整
TOOLS.md 环境特定的工具配置信息 工具增减、参数调整
HEARTBEAT.md 周期性唤醒与健康检查 定时任务配置
BOOTSTRAP.md 初始化配置 初始环境设定
MEMORY.md 长期记忆、重要事件、学习总结 记忆沉淀

设计理念：用 Markdown 而非数据库存储配置，体现了"朴素、可读、可版本控制"的工程哲学。

五、Agent Loop 核心机制深度解析

5.1 核心组件

组件 职责 源码位置
会话管理器 维护会话状态和历史记录 src/agents/pi-embedded-runner/run/attempt.ts
工具管理器 管理工具创建和执行 src/agents/pi-tools.ts
循环检测器 检测和防止工具调用循环 src/agents/tool-loop-detection.ts
工具执行器 执行具体工具操作 src/agents/pi-tools.before-tool-call.ts

5.2 循环检测机制

OpenClaw 实现了四种循环检测器，防止 Agent 陷入无限循环：

typescript 复制代码 
// 关键常量（源码）
export const TOOL_CALL_HISTORY_SIZE = 30;  // 工具调用历史窗口
export const WARNING_THRESHOLD = 10;        // 警告阈值
export const CRITICAL_THRESHOLD = 20;       // 临界阈值
export const GLOBAL_CIRCUIT_BREAKER = 50;   // 全局熔断器
graph TB
    ToolCall[工具调用] --> D1[通用重复检测]
    ToolCall --> D2[轮询无进展检测]
    ToolCall --> D3[全局熔断器]
    ToolCall --> D4[乒乓循环检测]
    
    D1 --> |相同调用重复 N 次| Warn1[警告/中断]
    D2 --> |轮询无实质结果| Warn2[警告/中断]
    D3 --> |总次数超限| Warn3[强制熔断]
    D4 --> |A调B B调A| Warn4[检测中断]
检测器 检测目标 触发条件
通用重复检测 相同工具调用的重复模式 相同参数调用超过阈值
轮询无进展检测 无效的轮询操作 轮询 N 次但结果无变化
全局熔断器 无限循环导致资源耗尽 总工具调用超过 50 次
乒乓循环检测 两个工具相互调用 A→B→A→B 模式

5.3 上下文构建流程

Agent 在调用 LLM 之前，会进行精细的上下文组装：
LLM 模型 提示词拼装 Skills 注入器 记忆系统 上下文构建器 用户消息 LLM 模型 提示词拼装 Skills 注入器 记忆系统 上下文构建器 用户消息 System Prompt + SOUL/IDENTITY + 记忆摘要 + Skills 工具描述 + 会话历史 + 用户输入 原始消息 查询相关记忆 历史上下文 + 长期记忆 加载可用 Skills 描述 工具列表 + 使用说明 拼装完整 Prompt 发送请求 模型响应

六、记忆系统架构

6.1 双模记忆设计

OpenClaw 采用 SQLite + 向量库 双模记忆方案：
记忆系统
短期记忆
长期记忆
会话历史
上下文窗口
事件日志 events.jsonl
MEMORY.md 摘要
向量数据库
SQLite 存储
本地文件系统
语义检索

6.2 核心记忆文件

文件 格式 用途
events.jsonl JSON Lines 所有事件的时间序列记录
MEMORY.md Markdown Agent 主动沉淀的重要记忆摘要
HEARTBEAT.md Markdown 周期性健康检查与状态快照
Session DB SQLite 会话级别的消息历史

6.3 记忆的"越用越懂你"原理

用户交互
事件捕获
模式识别
记忆更新
偏好学习
个性化响应

Agent 通过以下机制实现"自我进化"：

  1. 事件流记录 ：每次交互写入 events.jsonl
  2. 记忆沉淀 ：关键决策、学习总结写入 MEMORY.md
  3. 偏好提取 ：从交互模式中提取用户偏好更新 USER.md
  4. 上下文注入：下次交互时将记忆注入 Prompt

七、Skills 技能系统

7.1 设计理念

"Skill 不是一段更长的提示词，而是一个承载组织工作流的工程化单元。" --- Claude Code 团队工程师 Thariq

Skills 系统是 OpenClaw 从"能聊天"进化到"能干活"的关键。

7.2 Skill 目录结构

每个 Skill 是一个独立目录，核心是 SKILL.md 文件：

复制代码 
skills/
├── weather/
│   ├── SKILL.md              # 技能定义（YAML frontmatter + Markdown 指令）
│   └── scripts/
│       └── get_weather.mjs   # 执行脚本
├── github/
│   ├── SKILL.md
│   └── scripts/
│       └── github_api.mjs
└── custom-skill/
    ├── _meta.json            # 元数据
    ├── SKILL.md              # 技能定义
    ├── scripts/              # 脚本目录
    └── references/           # 参考资料

7.3 SKILL.md 规范

yaml 复制代码 
---
name: my-skill
description: 技能描述，AI 用来判断何时调用
version: "1.0.0"
triggers:
  - "关键词触发"
tools:
  - name: tool_name
    description: "工具描述"
    parameters:
      param1:
        type: string
        description: "参数说明"
---

# 技能指令（Markdown 正文）

## 使用说明
当用户要求 xxx 时，执行以下步骤：
1. 调用 tool_name 获取数据
2. 处理返回结果
3. 格式化输出给用户

7.4 Skill 注入与执行流程

Skill Executor Agent Runtime Prompt Builder Skill Scanner 启动阶段 Skill Executor Agent Runtime Prompt Builder Skill Scanner 启动阶段 用户发来消息 扫描 ./skills/ 目录 解析所有 SKILL.md 的 YAML frontmatter 注入技能摘要到 System Prompt 构建完整 Prompt 包含可用技能列表 LLM 推理，识别需调用的 Skill 调用对应 Skill 脚本 返回执行结果（Observation） 将结果注入上下文继续推理

7.5 五大插件注入点

OpenClaw 的插件化内核支持五种核心注入方式：

注入点 用途 示例
Channel 插件 新增通信渠道 自定义 IM、企业微信专版
Tool 插件 新增 Agent 工具 专业数据库查询、内部 API
Provider 插件 新增 AI 模型提供商 私有部署模型、自定义推理
Skill 插件 新增业务技能 行业特定工作流
ContextEngine 插件 自定义上下文管理 3.7 版新增，上下文可插拔

八、消息全链路追踪

以一条"帮我整理今天的重要邮件"从钉钉发出为例，追踪完整执行路径：
Memory System Skills Engine LLM Model Agentic Loop Agent Runner Lane Queue Session Router Gateway Server Channel Adapter 钉钉 Memory System Skills Engine LLM Model Agentic Loop Agent Runner Lane Queue Session Router Gateway Server Channel Adapter 钉钉 原始消息（钉钉协议格式） 归一化 Message 对象 消息路由 生成 SessionKey（agent+workspace+sender） 进入车道队列 分配给 Agent Runner 加载会话历史 + 长期记忆 拼装 System Prompt + Skills 描述 启动 Agentic Loop 第一轮推理 需要调用 read_email 工具 执行 read_email Skill 返回邮件列表 第二轮推理（含邮件内容） 需要调用 summarize 工具 执行摘要 Skill 返回摘要结果 第三轮推理 生成最终简报文本 保存交互记录 回传结果 格式转换 发送到钉钉

九、Provider 模型适配层

9.1 多模型驱动引擎

源码位置 ：src/providers/
Provider 适配层
Anthropic Claude
OpenAI GPT
Google Gemini
DeepSeek
本地模型 Ollama
自定义 OpenAI 兼容
Function Calling
工具执行

设计要点：

  • 统一的 Provider 接口抽象
  • 支持 API Key 轮换与冷却机制
  • 内置 Token 计算与成本估算
  • 支持流式输出（Streaming）
  • 回退策略：主模型失败自动切换备用模型

9.2 Function Calling 实现

typescript 复制代码 
// Provider 统一接口（简化示例）
interface LLMProvider {
  name: string;
  chat(params: {
    messages: Message[];
    tools?: ToolDefinition[];
    stream?: boolean;
  }): AsyncIterable<ChatChunk>;
}

LLM 通过 Function Calling 告诉 Agent："我需要调用这个工具"，Agent 执行后将结果返回给 LLM 继续推理，形成完整的 ReAct 循环。

十、安全边界设计

10.1 Trust Boundary（信任边界）

源码位置 ：src/agents/pi-tools.before-tool-call.ts

OpenClaw 定义了明确的信任边界，划分高危操作与安全操作：
低风险
高风险
禁止
是
否
操作请求
信任边界检查
自动执行
人工确认
拦截阻断
记录日志
用户批准?
执行并记录
拒绝执行
告警日志

10.2 安全实践

安全机制 实现方式
凭证管理 强制环境变量或加密 JSON5 配置
配置扫描 openclaw doctor 实时扫描配置风险
权限沙箱 RSA 签名插件 + 权限沙箱
工具白名单 可配置的工具调用白名单
操作审计 全链路日志，通过 runId 追踪
会话隔离 基于 agent + workspace + sender 的三维隔离

十一、多 Agent 协作机制

11.1 物理隔离模型

OpenClaw 的多 Agent 不是逻辑隔离，而是物理隔离：
Agent C 工作空间
Agent B 工作空间
Agent A 工作空间
Memory A
Skills A
Session A
Config A
Memory B
Skills B
Session B
Config B
Memory C
Skills C
Session C
Config C
Gateway 网关

11.2 多 Agent 配置

yaml 复制代码 
# .agents/ 目录下的多 Agent 配置
agents:
  - name: "研究员"
    model: "claude-sonnet"
    skills: ["web-search", "document-analysis"]
    soul: "擅长深度研究和信息整理"
    
  - name: "编码助手"
    model: "deepseek-v3"
    skills: ["code-gen", "code-review", "testing"]
    soul: "精通多种编程语言"
    
  - name: "项目经理"
    model: "gpt-4o"
    skills: ["planning", "task-tracking"]
    soul: "擅长任务拆解和进度管理"

11.3 跨 Agent 通信

多 Agent 之间通过 Gateway 进行消息路由：

  • Session 隔离：每个 Agent 独立 Session，互不干扰
  • 消息转发：通过 Gateway 实现 Agent 间消息传递
  • 任务委托：一个 Agent 可将子任务委托给另一个 Agent

十二、ContextEngine 插件机制（v3.7+）

12.1 问题背景

当对话轮次增多时，Token 堆积超出模型窗口限制。过去上下文管理逻辑写死在核心代码中，每次调整都是高风险手术。

12.2 插件化解决方案

v3.7 版本引入 ContextEngine 插件接口，将上下文管理逻辑从核心解耦：
原始上下文
ContextEngine 插件
策略选择
截断策略
压缩策略
摘要策略
自定义策略
处理后上下文

开发者可以自定义上下文管理策略：

  • 截断：保留最近 N 轮对话
  • 压缩：用 LLM 对历史内容做摘要压缩
  • 混合：重要信息保留全文，普通内容压缩
  • 语义筛选：基于向量相似度保留相关内容

十三、源码阅读路线图

如果你想深入 OpenClaw 源码，建议按以下路线阅读：

  1. CLI 入口

src/cli/
2. Gateway 启动

src/gateway/boot.ts
3. Channel 加载

src/channels/
4. 消息路由

src/sessions/
5. Agent Runner

src/agents/
6. Agentic Loop

attempt.ts
7. 工具调用

pi-tools.ts
8. Skills 执行

skills/
9. 记忆写入

src/memory/

阶段 重点文件 理解目标
启动流程 src/gateway/boot.ts 系统如何初始化各模块
消息处理 src/gateway/server.ts WebSocket 如何接收和分发消息
会话管理 src/sessions/ SessionKey 如何生成和路由
Agent 运行 src/agents/pi-embedded-runner/ 模型调用和提示词构造
核心循环 run/attempt.ts ReAct 循环的完整实现
工具系统 pi-tools.ts 工具注册、调用和结果处理
循环检测 tool-loop-detection.ts 四种循环检测器的实现
记忆系统 src/memory/ 短期/长期记忆的存储与检索

十四、设计总结

核心设计原则

OpenClaw 设计原则
解耦分层
本地优先
插件化内核
安全优先
工程化实践
渠道/网关/执行 三层分离
数据不离开用户设备
Skills/Channels/Providers 可热插拔
Trust Boundary + 循环检测 + 审计
Markdown 配置 + TypeScript 类型安全

四个反共识设计

反共识 说明
网关而非框架 不提供 SDK，而是一个独立运行的服务
Markdown 即配置 用 .md 文件而非 YAML/JSON 定义 Agent 人格和记忆
朴素记忆方案 用本地文件（events.jsonl）而非复杂数据库
单体架构 不做微服务拆分，单进程网关处理一切

总结

OpenClaw 的工程价值不在于它有多"智能"，而在于它用一套清晰的五层分层 + 插件化内核 + 本地优先 + 安全边界的架构，将 LLM 的推理能力转化为了可治理、可扩展、可信赖的任务执行系统。

相关推荐
kyle~2 小时前
计算机视觉---Open3D数据处理库
人工智能·计算机视觉
LONGZETECH2 小时前
在线考试系统技术解析：B/S架构落地与全流程功能实现（附院校落地参考）
架构·汽车教学软件·龙泽科技
SENKS_DIGITAL2 小时前
立体环保展厅：绘就企业绿色梦想新画卷-森克思科技
人工智能·科技·设计·艺术·展厅设计·展览设计·数字科技展览设计
程序员Shawn2 小时前
【深度学习 | 第一篇】- Pytorch与张量
人工智能·pytorch·深度学习
GISer_Jing3 小时前
Agent多代理架构：子代理核心机制解密
开发语言·人工智能·架构·aigc
roamingcode3 小时前
前端 AI Agent 多智能体协作架构：从对抗式排查到工作流解耦
前端·人工智能·架构·agent·team
songcream13 小时前
TensorFlow的一些基本概念
人工智能·python·tensorflow
智慧医院运行管理解决方案专家3 小时前
中科医信杜鹏：「数据驱动，孪生赋能」，数据资产是医院智慧管理的核心要素之一
大数据·人工智能·数字孪生·智慧医工管理
smileNicky3 小时前
Spring AI系列之Tool Calling实战指南
人工智能·spring boot·spring
热门推荐
01GitHub 镜像站点02Qwen3.5-Omni与Qwen3.6模型全面解析（含测评/案例/使用教程）032026年3月AI领域大事件：DeepSeek引领开源风暴04Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services05黄金未来走势预测06Mac 本地部署 OMLX + 通义千问 Qwen3.5-27B 保姆级教程07UV安装并设置国内源08AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南09让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南10“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）