本书共 16 章，分为 4 大部分，全面剖析 OpenClaw 源码架构。第一部分讲解架构全景，包括整体设计哲学、目录结构、启动流程、配置系统；第二部分深入核心模块，涵盖 Gateway 网关、Agent 执行循环、会话管理、工具系统；第三部分追踪完整数据流，从消息接收、路由分发、工具调用到响应流式传输；第四部分探讨扩展机制，包括 Skills 加载器、Channel 插件系统、记忆后端、安全沙箱。
本地优先 · 网关架构 · 上下文工程 · 二道贩子模式 · 四个反共识洞察
OpenClaw 是一个自托管、多渠道的 AI Agent 网关，它将 messaging platforms（WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等）连接到 AI coding agents。它作为单个持久进程运行，管理会话、路由消息、执行工具并协调 Agent 交互。
@mariozechner/pi-agent-core、@mariozechner/pi-ai、@mariozechner/pi-coding-agentOpenClawSchema）OpenClaw 的所有状态、配置、会话历史都存储在本地（默认 ~/.openclaw），确保用户对数据有完全控制权：
~/.openclaw 目录即可完整迁移到新机器~/.openclaw/
├── openclaw.json # 主配置文件（JSON5）
├── .env # 环境变量覆盖
├── credentials/ # OAuth/API Key 存储
│ └── whatsapp/<accountId>/creds.json
├── agents/
│ ├── main/
│ │ ├── agent/auth-profiles.json # 认证配置文件
│ │ └── sessions/sessions.json # 会话历史
│ ├── researcher/
│ │ └── ...
│ └── writer/
│ └── ...
├── workspace/ # 默认工作区
│ ├── AGENTS.md
│ ├── SOUL.md
│ ├── MEMORY.md
│ ├── memory/YYYY-MM-DD.md
│ └── skills/
├── logs/ # 日志文件
└── state/ # 运行时状态OpenClaw 将自己定位为 Gateway（网关），而非简单的聊天机器人。网关是整个系统的控制平面：
这是 OpenClaw 最核心的竞争力。它不是简单地调用模型 API，而是精心构建完整的运行时上下文：
在最核心的 attempt.ts 中，OpenClaw 实际上把球踢给了外部 SDK —— Pi SDK：
// 真正的模型调用在 Pi SDK 中
export async function runEmbeddedAttempt(ctx: AttemptContext) {
// 1. 准备工作目录和沙箱环境
const workDir = resolveUserPath(ctx.userPath);
const sandbox = resolveSandboxContext(ctx.sandboxMode);
// 2. 加载 Skills 和上下文文件
const skills = loadWorkspaceSkillEntries(workDir);
const bootstrap = resolveBootstrapContextForRun(...);
// 3. 创建工具集（部分来自 Pi SDK）
const tools = createOpenClawCodingTools({
exec, process, apply_patch, // OpenClaw 自研
read, write, edit, glob, grep // 来自 pi-coding-agent
});
// 4. 构建超长的 system prompt
const systemPrompt = buildEmbeddedSystemPrompt({
workDir, tools, skills, bootstrap, ctx.metadata
});
// 5. 创建 Agent Session（Pi SDK）
const session = createAgentSession({ model, tools, systemPrompt });
// 6. 流式调用模型（Pi SDK 内部实现）
const streamFn = session.agent.streamFn;
const result = await streamFn(effectivePrompt);
// 7. 订阅流式事件
subscribeEmbeddedPiSession(session, {
onPartialReply, onBlockReply, onToolCall, onTurnEnd
});
return result;
}这个模式揭示了一个重要趋势：
大家平时最爱讨论的是：装哪个模型、接哪些 Skill、能不能配十个龙虾专家。但从系统结构看，OpenClaw 真正最值钱的地方，其实是它怎么把用户消息嵌进一个完整运行时：
也正因为这样，它给人的感觉是更懂你、更懂场景、更理解你的意图，乃至懂得主动行动完成任务。这背后不是说 AI 具备了人的意识，也没到 AGI 时代提前到来那么夸张，而是靠充分的上下文装配实现了一种"智能增值"。
很多人以为 OpenClaw 内部实现了复杂的模型调用逻辑。但看了源码才发现，在最核心的 attempt.ts 里，它其实是把球踢给了外部 SDK —— Pi。
OpenClaw 本身并不生产智能，它更像是一个极其出色的包工头。它负责把脏活累活（鉴权、文件读写、工具调用、上下文管理）都干完了，最后把整理得干干净净的数据喂给 SDK。
很多人谈 Agent，还停留在设定角色、给几个规则，再加一点历史对话的水平。但 OpenClaw 的 system prompt 做的事情，是把工具能力、调用风格、安全边界、Workspace、Sandbox、Docs、Skills、Memory、Reply tags、Voice 等都显式地翻译进 prompt 中。
这个思路很工程化，也很现实。因为大模型不是天然懂你，它只是被喂了一个尽可能完整的世界状态。
你如果只从用户界面看，会觉得它像一个会聊天、会调用工具的机器人。但从架构看，它更是一个本地优先的消息操作系统：前面接很多渠道，里面有统一控制平面，下面挂 agent runtime、tools、nodes、session store、skills、web UI、CLI、memory。
auto-reply/monitor.ts → monitorWebChannel() · 建立统一会话、频道、工具、事件分发能力
inbound/monitor.ts · 去重合并 → 权限检查 → 媒体下载 → 标准化封装 → 防抖队列
auto-reply/monitor/on-message.ts · resolveAgentRoute() · 根据 bindings 路由到 Agent
get-reply.ts · 确认 Agent → 准备 workspace → 理解媒体 → 加载历史 → 解析指令
get-reply-run.ts · runPreparedReply() · 整理模型配置 → 处理特殊指令 → 校验思考等级
agent-runner.ts · runReplyAgent() · 队列管理 → 记忆刷新 → 失败重试 → 成本统计
agent-runner-execution.ts · runAgentTurnWithFallback() · 注册上下文 → 容错布置 → 路径选择
run.ts · runEmbeddedPiAgent() · 确认排队规则 → 补齐模型细节 → 遍历认证配置
attempt.ts · runEmbeddedAttempt() · 准备环境 → 加载 Skills → 构建 system prompt → Pi SDK 流式调用
process-message.ts · dispatchReplyWithBufferedBlockDispatcher() · 整理碎片 → 分块发送 → 送达用户
| 步骤 | 操作 | 命令/链接 | 预计时间 |
|---|---|---|---|
| 1. Fork 仓库 | GitHub 上 Fork 主仓库 | github.com/openclaw/openclaw | 1 分钟 |
| 2. 克隆代码 | Clone 到本地并安装依赖 | git clone && pnpm install |
5 分钟 |
| 3. 选择方向 | Bug 修复、新功能、文档改进 | 查看 Issues 列表 | 10 分钟 |
| 4. 创建分支 | 基于 main 创建 feature 分支 | git checkout -b feat/xxx |
1 分钟 |
| 5. 开发测试 | 编写代码 + 单元测试 + 手动测试 | pnpm test |
数小时 - 数天 |
| 6. 提交 PR | Push 并创建 Pull Request | 遵循 PR 模板 | 30 分钟 |
| 7. Code Review | 回应 reviewer 意见并修改 | GitHub Comments | 数小时 - 数天 |
| 8. 合并发布 | 通过 CI 后合并到 main | 等待下一个 release | 1-7 天 |