OpenClaw源码深度解析：打造生产级AI Agent的四大核心模块与实战路线图

本文深入剖析了OpenClaw AI Agent框架的四大核心模块执行循环、工具系统、记忆系统和插件系统详细阐述了每个模块的实现细节和关键技术。文章还提供了从零开始构建AI Agent的路线图包括搭建核心循环、增加容错机制、实现记忆功能、设计工具安全策略以及开放扩展等步骤并给出了OpenClaw对应的实现方案和优先级建议。对于想要了解如何构建生产级AI Agent的开发者来说本文提供了宝贵的参考和指导。本文假设你熟悉 TypeScript 和 LLM API 的基本概念。如果你还不了解 Function Calling建议先阅读 OpenAI Tool Use 文档。https://platform.openai.com/docs/guides/function-callingOpenClaw 是一个跑在生产环境里的 AI Agent 框架代码量不小但核心就四个模块——执行循环、工具系统、记忆系统、插件系统。这篇文章把每个模块拆开看看里面怎么写的最后整理一份自己做 Agent 时可以参考的清单。一、先看全景开始翻代码之前先搞清楚 OpenClaw 大概长什么样。一句话说Gateway 接收消息 → Agent 循环调用 LLM 工具 → 记忆系统提供上下文 → 插件扩展一切。四个模块各管各的耦合度不高。后面逐个看先扫一眼目录结构目录一句话说明src/agents/Agent 执行循环、工具注册、模型管理src/memory/记忆索引、嵌入向量、混合检索src/gateway/WebSocket 网关、认证、RPCsrc/plugin-sdk/插件 SDK、Hook 系统src/channels/通道抽象层状态机、路由、线程绑定extensions/73 个插件通道 / LLM Provider / 工具扩展二、Agent 核心循环很多教程里的 Agent 就是一个while循环加一次 LLM 调用。但真跑在线上的 Agent得处理网络抖动、API 限流、上下文爆掉、工具死循环这些破事。OpenClaw 的核心入口在src/agents/pi-embedded-runner/run.ts。2.1 主干逻辑把容错代码全去掉核心循环其实就这点东西LLM 决定要不要调工具调了就把结果喂回去来回循环直到 LLM 觉得可以直接回复了。这个工具循环是所有 Agent 框架的共同骨架。2.2 加上容错实际跑起来上面的循环随时可能断。OpenClaw 加了三层防护分别是上下文压缩compact.ts对话太长超出模型窗口时用 Context Engine 对历史做摘要保留关键信息不是直接砍掉前面的消息。模型 Failoverrun.tsAuth 过期、API 限流、余额不足自动冷却当前 Auth Profile换一个继续。整个重试循环上限 160 次Auth 还能提前 5 分钟自动续期。工具熔断器tool-loop-detection.ts用 30 次调用的滑动窗口检测三种异常——同一工具反复调、两个工具乒乓互调、轮询类工具没进展。10 次注入警告提示词20 次强制提示停下30 次直接终止。2.3 流式处理Agent 不会等 LLM 把整段话说完才动而是通过事件订阅pi-embedded-subscribe.ts边收边处理。核心状态大概长这样// src/agents/pi-embedded-subscribe.ts — 简化后的核心状态{ assistantTexts: string[] // 逐步累积的回复文本 toolMetas: ToolMetaEntry[] // 每次工具调用的元数据 blockBuffer: string // 流式分块缓冲区 blockState: { thinking: boolean // 当前是否在 think 标签内 final: boolean // 当前是否在 final 标签内 } messagingToolSentTexts: string[] // 已通过消息工具发送的文本去重用上限 200 条}事件处理器监听message_start/message_update/message_end/tool_execution_start/tool_execution_end这些事件在语义边界处切分文本块推给用户。所以用户不用等 Agent 跑完所有工具调用才看到第一个字。三、工具系统LLM 只会生成文本工具系统让它能读写文件、跑命令、搜网页、发消息——光会说不行还得能干活。3.1 工具长什么样一个工具就是一个 JSON Schema 加一个执行函数没什么花活// src/agents/tools/ 下的典型工具定义{ name: web_search, // LLM 看到的工具名 description: Search the web, // LLM 据此判断何时调用 parameters: Type.Object({ // JSON SchemaLLM 按此生成参数 query: Type.String() }), async execute(toolCallId, args, signal) { const results await search(args.query) return { content: [{ type: text, text: results }] } }}src/agents/openclaw-tools.ts注册了所有内置工具按能力域分类能力域代表工具做什么文件操作read,write,apply-patch读写代码和配置文件命令执行exec,process在沙箱中运行 Shell 命令Web 交互web_search,browser搜索引擎查询、浏览器自动化消息通信message,sessions_send向 Discord / Slack 等通道发消息多媒体image_generate,tts图像生成、语音合成子 Agentsessions_spawn派生子 Agent 执行子任务3.2 安全管线工具不是 LLM 说调就能调的每次调用都要过一条管线权限检查tool-policy.tscron这种工具只有 Owner 能调其他人直接拒绝。策略过滤根据消息来源和模型 Provider 的兼容性动态裁剪可用工具列表。循环检测tool-loop-detection.ts就是前面说的 30 次滑动窗口熔断器。沙箱执行exec类工具跑在隔离沙箱里改文件、跑系统命令这种操作需要用户点确认。3.3 动态注册除了内置工具插件可以根据运行时状态动态注册api.registerTool((ctx: OpenClawPluginToolContext) { if (!ctx.config.featureEnabled) return null // 条件不满足时不注册 return { name: conditional_tool, parameters: Type.Object({ query: Type.String() }), async execute(toolCallId, args) { /* ... */ } }})工具集可以根据用户配置、通道类型、模型能力等条件灵活调整不用一股脑全暴露给 LLM。四、记忆系统没有记忆的 Agent 每次对话都是从头来。记忆系统让 Agent 能跨会话记住用户偏好、项目背景和之前做过的决定。OpenClaw 的记忆系统是整个项目里最有意思的部分。4.1 就两件事存和取看着简单但每个环节都有不少细节。4.2 存从 Markdown 到向量数据从哪来两个来源memory 源工作区中的MEMORY.md和memory/*.md文件通常由用户或 Agent 主动维护sessions 源Agent 的历史会话记录JSONL 格式自动采集索引管线文件发现后经过变更检测、分块、嵌入、写入四个阶段几个值得注意的点增量索引用 SHA256 哈希检测文件有没有变只处理改过的文件不用每次全量重建。嵌入缓存embedding_cache表按内容哈希去重同样的文本不会重复调嵌入 API。缓存满了自动清理旧的。Batch 处理支持 OpenAI / Gemini / Voyage 的 Batch API 批量生成向量。Batch 连续挂 2 次就自动退回逐条调用不影响整体可用性。存在哪SQLite Schema每个 Agent 有自己的 SQLite 数据库~/.openclaw/memory/{agentId}.sqlite。为什么用 SQLite 不用 Pinecone / Milvus很简单——不需要额外装数据库服务一个文件就是全部记忆拷到另一台机器直接能用。sqlite-vec 扩展的向量搜索性能对这个场景完全够。核心表结构省略了部分字段-- 分块存储文本 嵌入向量CREATETABLE chunks (idTEXT PRIMARY KEY, -- SHA256(source:path:line:hash:model)pathTEXTNOTNULL, -- 源文件路径sourceTEXTNOTNULL, -- memory | sessions start_line INTEGERNOTNULL, end_line INTEGERNOTNULL,textTEXTNOTNULL, -- 分块原文 embedding TEXTNOTNULL, -- 向量JSON float 数组 updated_at INTEGERNOTNULL);-- 向量索引sqlite-vec 虚拟表CREATEVIRTUALTABLE chunks_vec USING vec0(idTEXT PRIMARY KEY, embedding FLOAT[N] -- N 嵌入维度如 OpenAI 为 1536);-- 全文索引FTS5CREATEVIRTUALTABLE chunks_fts USING fts5(text, id UNINDEXED, ...);-- 嵌入缓存按内容哈希去重CREATETABLE embedding_cache ( provider TEXT, modelTEXT, provider_key TEXT, hashTEXT, embedding TEXT, dims INTEGER, updated_at INTEGER, PRIMARY KEY (provider, model, provider_key, hash));三张表分工明确chunks存原始数据chunks_vec做向量近邻搜索chunks_fts做关键词全文检索。4.3 取混合检索纯向量搜索擅长语义匹配“怎么部署能匹配到上线流程”但会漏掉精确关键词纯全文搜索反过来。OpenClaw 把两者拼在一起再加上时间衰减和去重排序形成四步检索管线每一步在干什么Step 1 — 向量搜索通过 sqlite-vec 计算查询向量与每个 chunk 向量的余弦相似度返回 [0, 1] 范围的得分。Step 2 — 全文搜索FTS5 返回 BM25 排名负数归一化为 [0, 1]Step 3 — 加权合并语义匹配权重给高一点因为多数查询是模糊意图不是精确关键词Step 4 — 后处理时间衰减temporal-decay.tsλ半衰期 30 天。带日期的文件比如memory/2026-03-15.md会随时间降权MEMORY.md这种常驻文件不受影响。MMR 重排mmr.tsλλ。用 Jaccard 相似度衡量候选结果之间的重复度避免返回一堆内容差不多的片段。最终返回的结果结构type MemorySearchResult { path: string; // 来源文件 startLine: number; // 分块起始行 endLine: number; // 分块结束行 score: number; // 综合得分 [0, 1] snippet: string; // 截断到 700 字符的摘要 source: memory | sessions;};4.4 嵌入提供商支持 6 种嵌入提供商。auto模式按优先级依次试Ollama 得手动指定优先级Provider类型Batch API默认模型1Local本地-embeddinggemma-300m2OpenAI远程✅text-embedding-3-small3Gemini远程✅text-embedding-0044Voyage远程✅voyage-35Mistral远程-mistral-embed手动Ollama本地-nomic-embed-text4.5 降级策略记忆系统最实用的一点不要求所有组件都正常能用多少用多少。没有嵌入 API Key关键词搜索照样能用sqlite-vec 加载失败FTS5 兜底。比起缺一个组件就整个报错这种做法靠谱得多。4.6 实时同步记忆不是建好就完事了文件在改、新对话在产生索引得跟上文件监听WatchMEMORY.md和memory/**/*.md变更后防抖 1.5s 触发重新索引会话监听订阅 Session Transcript 更新事件防抖 5s 后增量索引新内容同步时机搜索前自动同步确保结果最新、会话开始时同步、可配置定时同步并发控制4 路并行索引处理Session 写锁防止并发冲突五、插件系统OpenClaw 的 73 个扩展——Discord 通道、Anthropic Provider 这些——全走统一的插件 SDK没有硬编码的特殊通道。5.1 插件生命周期发现从 bundled内置、global全局安装、workspace工作区三个位置扫描插件加载通过jiti动态导入插件模块支持 TypeScript 直接加载注册插件调用 SDK API 注册工具、Hook、CLI 命令和后台服务激活所有插件注册完毕后统一激活插件注册表缓存上限 128 条5.2 两种插件形态通用插件——注册工具和 HookdefinePluginEntry({ id: my-plugin, name: My Plugin, register(api) { api.registerTool({ name: my_tool, ... }) api.on(before_agent_start, async () { return { prependContext: 注入额外上下文 } }) }})通道插件——接入新的消息通道defineChannelPluginEntry({ id: discord, plugin: discordPlugin, // 实现 ChannelPlugin 接口 setRuntime: setDiscordRuntime, // 接收运行时能力 registerFull: registerHooks // 注册通道特有的 Hook 和工具})5.3 25 个 Hook插件可以在 Agent 生命周期的 25 个节点插入自己的逻辑。不用 fork 核心代码就能改 Agent 的行为阶段代表 Hook典型用途模型选择before_model_resolve,before_prompt_build覆盖默认模型、注入系统上下文LLM 交互llm_input,llm_output审计日志、内容过滤、token 统计工具调用before_tool_call,after_tool_call,tool_result_persist调用拦截、结果持久化消息处理message_received,message_sending,message_sent消息预处理、格式转换、发送确认会话管理session_start,session_end,before_compaction初始化、清理、压缩前干预子 Agentsubagent_spawning,subagent_ended子任务分发策略、结果汇总网关gateway_start,gateway_stop服务启停时的资源管理六、GatewayGateway 是 Agent 和外面世界之间的中间层。不管消息从 Discord、Slack、Telegram 还是 Web UI 来都统一走 Gateway 路由到 Agent。6.1 结构6.2 一条消息的旅程比如用户在 Discord 里发了一句话到 Agent 回复中间经过这些环节其中会话状态机src/channels/run-state-machine.ts比较关键。每个会话有自己的状态idle → running → drafting → completed保证同一个会话不会被并发请求搞乱。通道健康监控channel-health-monitor.ts一直在检测各通道连接状态断了自动重连。七、做 Agent 的路线图前面六章看完了 OpenClaw 怎么做的这章整理一下如果自己从零开始做一个 Agent按什么顺序推进比较合理。7.1 先搭核心循环这是 Agent 的骨架最小可用版本。需要三个东西System Prompt 构建器别把 System Prompt 写死。OpenClaw 在system-prompt.ts里动态拼装——运行时信息OS、时区、模型名、可用工具列表、通道能力描述、用户自定义指令按需注入。同一个 Agent 在不同环境下表现才能一致。LLM 调用层一定要用流式streaming不要用阻塞调用。OpenClaw 通过事件订阅pi-embedded-subscribe.ts实时处理text_delta和tool_call事件用户能马上看到输出不用干等。工具循环LLM 返回tool_use就执行对应工具把结果作为tool_result喂回去直到 LLM 不再请求工具。这个循环所有 Agent 框架都一样。7.2 加容错裸循环跑 demo 没问题上线必须加容错。按重要程度排容错机制解决什么问题OpenClaw 的实现上下文压缩对话太长超出模型窗口compact.ts调用 Context Engine 做摘要压缩Auth FailoverAPI Key 过期、限流、计费失败run.ts自动切换备用 Auth Profile / 备用模型工具熔断器Agent 陷入工具调用死循环tool-loop-detection.ts滑动窗口 三级熔断流式去重消息工具和直接回复内容重复pi-embedded-subscribe.ts跟踪已发送文本上下文压缩是最容易被忽略但最要命的。没有它长对话必崩。OpenClaw 的做法是溢出时用 Context Engine 对历史做摘要保留关键信息后重试不是简单砍掉前面的消息。7.3 做记忆这是让 Agent 从一次性对话变成持续助手的关键一步。OpenClaw 的方案可以直接抄最小实现选个嵌入模型text-embedding-3-small便宜够用SQLite sqlite-vec 存向量不用搭 Milvus省事加 FTS5 全文索引兜底混合检索0.7 × 向量得分 0.3 × BM25 得分进阶增量索引SHA256 变更检测不用每次全量重建嵌入缓存按内容哈希去重少调几次 API时间衰减让旧记忆自然淡出MMR 重排保证结果不重复降级策略嵌入挂了用 FTSFTS 也挂了就不检索但 Agent 本身不能挂为什么不用向量数据库服务单用户或小团队的 AgentSQLite 够了。一个.sqlite文件就是全部记忆拷到另一台机器就能跑。等真需要多租户、分布式检索的时候再迁移不迟。7.4 设计工具安全策略Agent 能调工具就意味着能产生副作用——写文件、发消息、跑命令。安全策略不是可选的。OpenClaw 的分层做法可以参考一句话只读的放行有副作用的隔离并确认。再加上循环检测熔断器兜底就行。7.5 开放扩展Agent 要支持新通道、新工具、新 Provider 的时候不该每次都改核心代码。OpenClaw 的插件系统可以参考定义 Hook 点在核心流程的关键位置模型选择、Prompt 构建、工具调用前后、消息收发暴露 Hook让插件能插入逻辑。统一注册 APIregisterTool()、registerHook()、registerService()三个方法覆盖大部分扩展场景。运行时能力注入通过PluginRuntime把核心能力配置读写、媒体处理、子 Agent 管理暴露给插件不让插件直接碰内部模块。不用一开始就做 25 个 Hook。先从几个高频的开始before_prompt_build注入上下文、before_tool_call/after_tool_call工具拦截、message_received消息预处理。后面按需加。7.6 总结成表上面的路线图压缩一下阶段要做的事OpenClaw 对应实现优先级骨架工具循环 流式输出attempt.tspi-embedded-subscribe.tsP0骨架动态 System Promptsystem-prompt.tsP0容错上下文压缩compact.tsP0容错Auth / 模型 Failoverrun.ts重试循环P1容错工具循环熔断tool-loop-detection.tsP1记忆SQLite 向量 FTSmemory/manager.tssqlite-vec.tsP1记忆混合检索 降级hybrid.tsembeddings.tsP1安全工具权限 沙箱tool-policy.tsbash-tools.exec.tsP1扩展插件 SDK Hookplugin-sdk/core.tsP2扩展多通道接入gateway/server.tschannels/P2P0 是最小可用版本要有的P1 是上线前得补的P2 是用户量上来之后再考虑的。附录核心文件速查你想了解…去看这个文件Agent 主循环src/agents/pi-embedded-runner/run.ts单次 LLM 调用 工具循环src/agents/pi-embedded-runner/run/attempt.ts流式事件处理src/agents/pi-embedded-subscribe.tsSystem Prompt 构建src/agents/pi-embedded-runner/system-prompt.ts上下文压缩src/agents/pi-embedded-runner/compact.ts工具注册src/agents/openclaw-tools.ts工具安全策略src/agents/tool-policy.ts工具循环检测src/agents/tool-loop-detection.ts记忆管理器src/memory/manager.ts混合检索算法src/memory/hybrid.ts向量存储src/memory/sqlite-vec.ts嵌入提供商工厂src/memory/embeddings.ts时间衰减src/memory/temporal-decay.tsMMR 重排src/memory/mmr.ts插件 SDKsrc/plugin-sdk/core.tsGateway 服务器src/gateway/server.ts消息路由src/routing/resolve-route.ts会话状态机src/channels/run-state-machine.ts2026年AI行业最大的机会毫无疑问就在应用层字节跳动已有7个团队全速布局Agent大模型岗位暴增69%年薪破百万腾讯、京东、百度开放招聘技术岗80%与AI相关……如今超过60%的企业都在推进AI产品落地而真正能交付项目的大模型应用开发工程师****却极度稀缺落地AI应用绝对不是写几个prompt调几个API就能搞定的企业真正需要的是能搞定这三项核心能力的人✅RAG融入外部信息修正模型输出给模型装靠谱大脑✅Agent智能体让AI自主干活通过工具调用Tools环境交互多步推理完成复杂任务。比如做智能客服等等……✅微调针对特定任务优化让模型适配业务目前脉脉上有超过1000家企业发布大模型相关岗位人工智能岗平均月薪7.8w实习生日薪高达4000远超其他行业收入水平技术的稀缺性才是你「值钱」的关键具备AI能力的程序员比传统开发高出不止一截有的人早就转行AI方向拿到百万年薪AI浪潮正在重构程序员的核心竞争力现在入场仍是最佳时机我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】⭐️从大模型微调到AI Agent智能体搭建剖析AI技术的应用场景用实战经验落地AI技术。从GPT到最火的开源模型让你从容面对AI技术革新大模型微调掌握主流大模型如DeepSeek、Qwen等的微调技术针对特定场景优化模型性能。学习如何利用领域数据如制造、医药、金融等进行模型定制提升任务准确性和效率。RAG应用开发深入理解检索增强生成Retrieval-Augmented Generation, RAG技术构建高效的知识检索与生成系统。应用于垂类场景如法律文档分析、医疗诊断辅助、金融报告生成等实现精准信息提取与内容生成。AI Agent智能体搭建学习如何设计和开发AI Agent实现多任务协同、自主决策和复杂问题解决。构建垂类场景下的智能助手如制造业中的设备故障诊断Agent、金融领域的投资分析Agent等。如果你也有以下诉求快速链接产品/业务团队参与前沿项目构建技术壁垒从竞争者中脱颖而出避开35岁裁员危险期顺利拿下高薪岗迭代技术水平延长未来20年的新职业发展……那这节课你一定要来听因为留给普通程序员的时间真的不多了立即扫码即可免费预约「AI技术原理 实战应用 职业发展」「大模型应用开发实战公开课」还有靠谱的内推机会直聘权益完课后赠送大模型应用案例集、AI商业落地白皮书