1. 项目概述与核心价值如果你对AI Agent智能体感兴趣并且已经看腻了网上那些“一个while循环调用大模型”的玩具级教程那么这个项目——OpenClaw Mini——就是为你准备的。它不是一个简单的API封装而是一个系统级AI Agent架构的精简复现旨在剥离OpenClaw这个超过43万行代码的复杂生产系统提炼出其最核心、最值得学习的架构设计思想。简单来说它回答了一个关键问题一个真正可用、可维护、能处理复杂交互的AI Agent其内部到底是如何运转的它不仅仅是一个“会调用工具的聊天机器人”而是一个具备会话持久化、上下文管理、长期记忆、主动唤醒能力的准系统。通过这个项目你可以清晰地看到Agent Loop的双层循环设计、基于事件流的异步通信、会话的JSONL持久化策略以及如何将本地CLI服务升级为支持多客户端连接的WebSocket网关。对于希望从“调用API”进阶到“设计系统”的开发者而言这是一个绝佳的学习样板。2. 核心架构与模块分层解析OpenClaw Mini的代码结构经过精心设计按照学习路径和功能层次清晰地分为了四个层级。这种分层不仅有助于理解也反映了构建一个健壮Agent系统的通用思路。2.1 核心层任何Agent的基石这是项目的重中之重包含了构建一个功能性Agent所必需的最小核心组件。理解这一层你就掌握了现代AI Agent架构的通用范式。2.1.1 Agent与事件流订阅与推送模式传统的“请求-响应”模式在需要实时反馈和复杂状态管理的Agent场景中显得笨拙。OpenClaw Mini采用了事件驱动架构。Agent类作为总入口内部维护了一个事件发射器。当你调用agent.subscribe(callback)时就订阅了一个事件流。随后在agent.run()执行过程中内部的各种状态变化如开始思考、流式输出文本、开始执行工具、发生错误都会转化为不同类型的事件MiniAgentEvent实时推送给订阅者。这种设计的好处是解耦与灵活性。前端UI可以监听message_delta事件来实时显示流式回复监控系统可以监听agent_error事件而日志系统可以记录所有事件。它让Agent的内部状态变得可观测、可响应。2.1.2 Agent Loop超越单次调用的双层循环网上常见的Agent示例是一个简单的while循环调用模型 - 解析工具调用 - 执行工具 - 将结果追加到对话历史 - 再次调用模型。这在遇到“模型要求继续”follow-up或需要注入系统指令steering时就会捉襟见肘。OpenClaw Mini的Agent Loop实现了双层循环机制外层循环负责处理“回合”。当模型返回end_turn: false或产生了工具调用时意味着本轮对话尚未结束需要进入下一轮。外层循环控制着最大的对话轮次防止无限循环。内层循环在一轮对话中负责处理“工具执行链”。模型可能一次调用多个工具内层循环会依次执行它们并将每个工具的结果作为新的上下文消息追加然后再次请求模型直到模型不再调用工具或给出最终答复。这个循环结构是Agent具备“自主完成任务”能力的关键它使得Agent能进行多步推理和操作。2.1.3 会话与上下文管理记忆的载体没有记忆的AI只是一次性函数。Session模块负责对话历史的持久化。它采用JSONL格式每行一个JSON对象将消息追加到磁盘文件。这种格式的优点是容错性强即使某一行损坏也不影响其他数据的读取。在实现上它采用了“内存缓存延迟落盘”的策略首次出现助手消息前历史只存在于内存一旦出现则一次性写入文件头和历史条目后续消息则高效地appendFile。这避免了为只有用户消息的会话创建空文件。仅有持久化还不够大模型的上下文窗口是有限的。Context模块负责上下文的加载与优化。它主要做两件事裁剪优先移除旧的、冗长的tool_result消息因为工具执行结果往往很占篇幅保留最近的完整记录。压缩当对话历史超过设定阈值时将更早的历史消息通过大模型进行摘要用一段简短的“历史摘要”替换掉大量原始消息从而在保留核心信息的前提下大幅节省Token。2.2 扩展层让Agent更“智能”在核心能力之上OpenClaw Mini实现了OpenClaw特有的高级功能这些是区分普通Agent和“智能体”的关键。2.2.1 长期记忆Memory模块让Agent能够记住跨会话的信息。本项目的实现是一个简化版基于关键词匹配和相关性评分进行检索。当用户查询时系统会将查询语句分词然后在记忆库中搜索包含这些关键词的条目并计算相关性分数进行排序。OpenClaw完整版则集成了向量数据库进行语义搜索并配合BM25进行关键词搜索能力更强。2.2.2 技能系统Skills模块允许你为Agent定义“技能”。每个技能对应一个Markdown文件如HEARTBEAT.md文件头部用YAML格式定义元数据如触发词、描述正文部分是技能的具体内容或指令。当用户输入匹配到某个技能的触发词时该技能的内容会被动态注入到上下文中从而激活Agent的特定行为模式。2.2.3 主动唤醒Heartbeat是Agent“活”起来的表现。它让Agent可以定时或按条件主动执行任务而不是被动响应用户输入。其设计采用了两层架构Wake层接收来自定时器、Cron表达式、外部请求等多种来源的唤醒信号并通过一个250毫秒的合并窗口进行去抖防止高频触发。Runner层负责实际执行唤醒任务。它会检查是否在活跃时间段读取HEARTBEAT.md技能文件如果内容为空则跳过并通过“重复抑制”机制避免在24小时内发送相同的消息。2.3 网关层从本地工具到网络服务这是将Agent能力产品化的关键一步。Gateway模块将一个本地CLI程序转变为一个可通过网络访问的WebSocket RPC服务。2.3.1 核心通信协议网关定义了一套简单的帧协议包含三种类型的帧Request客户端请求、Response服务端响应、Event服务端主动推送的事件。每个帧都有唯一的id和序列号seq用于请求-响应匹配和保证事件顺序。2.3.2 安全握手连接建立后服务端会首先发送一个包含随机数nonce的connect.challenge事件。客户端必须使用预共享的token和这个nonce计算一个签名并在connect请求中回传。服务端使用crypto.timingSafeEqual进行常数时间比较以防止基于响应时间的旁路攻击。2.3.3 ACK-then-Stream模式这是处理耗时操作如Agent运行的经典模式。当客户端发送chat.send请求后服务端会立即返回一个ACK响应确认请求已接收并分配了runId。随后Agent的实际运行过程被异步执行其产生的事件流思考过程、流式回复、工具调用等通过broadcast机制以Event帧的形式推送给所有订阅了该会话的客户端。这种设计实现了请求的快速响应和结果的异步流式推送用户体验更好。2.3.4 健壮性设计背压控制当客户端消费速度过慢时服务端会丢弃非关键的老事件防止内存溢出。心跳与重连客户端和服务端通过定时发送tick事件维持连接。客户端检测到连接断开后会采用指数退避策略1s, 2s, 4s...最大30s自动重连。序列号间隙检测客户端通过检查收到事件的seq号是否连续来判断是否有事件丢失必要时触发重同步。2.4 工程层生产环境的守护者这一层包含了诸多生产级应用所需的防护和控制逻辑对于学习核心架构而言可以暂时跳过但它们体现了工程化的重要性。会话键管理规范化会话的唯一标识符格式如agent:id:session。工具策略实现工具访问的三级控制允许、拒绝、未指定用于权限管理。命令队列控制任务执行的并发例如保证同一会话内的请求串行执行不同会话间可以并行。守卫如Tool Result Guard自动补全缺失的工具结果消息Context Window Guard在上下文即将超出模型限制时主动触发压缩或报错。沙箱路径对工具如文件读写可访问的路径进行安全检查防止越权操作。3. 从零开始实践与深度配置了解了架构我们动手把它跑起来并深入看看各个模块是如何配置和协同工作的。3.1 环境准备与初次运行首先确保你的开发环境是Node.js 20或更高版本。克隆项目并安装依赖git clone gitgithub.com:voocel/openclaw-mini.git cd openclaw-mini pnpm install项目使用.env文件管理配置。复制示例文件并根据你的情况修改cp .env.example .env打开.env文件最关键的配置是选择一个模型提供商并设置API Key。以Anthropic的Claude为例# 指定使用 Anthropic 作为提供商 OPENCLAW_MINI_PROVIDERanthropic # 指定模型名称 OPENCLAW_MINI_MODELclaude-3-5-sonnet-20241022 # 你的 Anthropic API Key ANTHROPIC_API_KEYsk-your-api-key-here如果你需要使用代理或自建的API端点可以配置BASE_URLOPENCLAW_MINI_BASE_URLhttps://your-proxy.com/api/anthropic配置完成后运行测试以确保基础功能正常pnpm test接着以开发模式启动基础的CLI Agentpnpm dev此时你应该会进入一个交互式命令行界面可以直接与Agent对话它会利用内置工具如文件列表、读取、执行命令等来响应你。3.2 接入其他大模型OpenClaw Mini通过provider抽象层支持多种模型。国内许多模型服务都兼容OpenAI API格式这使得接入非常方便。例如接入智谱AI的GLM-4-Flash模型# 使用 OpenAI 兼容的提供商 OPENCLAW_MINI_PROVIDERopenai # 指定模型名称根据平台提供的名称填写 OPENCLAW_MINI_MODELglm-4-flash # 智谱AI的API端点 OPENCLAW_MINI_BASE_URLhttps://open.bigmodel.cn/api/paas/v4 # 对于不支持“扩展思考”功能的模型需要关闭此选项 OPENCLAW_MINI_REASONINGnone # 你的平台API Key OPENAI_API_KEYyour-zhipu-api-key关键点解析REASONING参数reasoning参数控制是否启用模型的“扩展思考”功能如Claude的Chain-of-Thought。对于不支持此功能或你希望节省Token的模型设置为none。其他可选值如medium、high等会影响模型内部“思考”的详细程度从而影响响应速度和Token消耗。3.3 以编程方式使用Agent除了CLI你可以在自己的Node.js项目中将其作为库引入。首先安装npm包或链接本地版本# 从npm安装发布后 pnpm add openclaw-mini # 或在项目目录下链接本地开发版本 pnpm link --global # 在openclaw-mini目录执行 pnpm link openclaw-mini # 在你的项目目录执行然后在你的代码中初始化并使用Agentimport { Agent } from openclaw-mini; // 或者使用 CommonJS: const { Agent } require(openclaw-mini); async function main() { // 1. 创建Agent实例 const agent new Agent({ provider: anthropic, // 或 openai, google 等 model: claude-3-5-sonnet-20241022, // 可选覆盖环境变量 apiKey: process.env.ANTHROPIC_API_KEY, // 可选可从环境变量自动读取 agentId: my-assistant, // Agent标识用于会话分组 workspaceDir: /path/to/workspace, // 工具执行的默认工作目录 reasoning: medium, // 扩展思考级别 }); // 2. 订阅事件实时获取运行状态 const unsubscribe agent.subscribe((event) { switch (event.type) { case thinking_delta: // 模型内部的“思考”过程如果模型支持且reasoning不为none process.stdout.write(event.delta); break; case message_delta: // 最终答复的流式输出 process.stdout.write(event.delta); break; case tool_execution_start: console.log(\n[执行工具: ${event.toolName}], JSON.stringify(event.args)); break; case tool_execution_result: console.log(\n[工具结果] ${event.toolName}:, event.result.substring(0, 100) ...); break; case agent_error: console.error(\n[Agent错误], event.error); break; } }); // 3. 运行Agent try { const sessionKey project-analysis-session; const userQuery 请分析当前目录下的package.json文件并告诉我主要依赖有哪些; const result await agent.run(sessionKey, userQuery); console.log(\n 任务完成 ); console.log(总对话轮次: ${result.turns}); console.log(工具调用次数: ${result.toolCalls}); console.log(最终回复长度: ${result.text.length} 字符); } catch (error) { console.error(运行Agent失败:, error); } finally { // 4. 取消订阅 unsubscribe(); } } main();3.4 探索Gateway网络服务Gateway模式是项目的一大亮点它展示了如何将AI Agent能力服务化。3.4.1 启动Gateway服务在一个终端中运行以下命令启动Gateway服务器pnpm gateway # 默认会在 http://localhost:18789 启动一个HTTP/WebSocket服务器你可以通过参数自定义配置pnpm gateway -- --port 8080 --token mySecretToken--token参数设置了连接认证的密钥客户端连接时必须提供相同的token。3.4.2 连接Gateway客户端在另一个终端启动客户端连接到Gatewaypnpm gateway:connect # 默认连接本地的默认端口和令牌如果启动时未指定token则客户端也不需要连接成功后你会进入一个交互式客户端界面。你可以直接输入消息与远程的Agent对话。客户端还支持一些内置命令/health查看Gateway服务器状态。/sessions列出当前所有活跃的会话。/quit断开连接。3.4.3 理解背后的通信流程客户端通过WebSocket连接到ws://localhost:18789。服务端发送一个挑战challenge包含一个随机数nonce。客户端使用配置的token和nonce计算签名并发起connect请求。服务端验证签名成功后返回HelloOk建立连接。客户端发送chat.send请求包含会话键和消息。服务端立即返回ACK然后异步启动Agent处理。Agent处理过程中产生的所有事件都被服务端广播给所有订阅了该会话的客户端。客户端接收到流式的事件实时渲染思考过程和回复。4. 核心设计模式深度剖析与实战技巧OpenClaw Mini浓缩了OpenClaw系统中的精华设计模式。理解这些模式你就能将其应用到自己的AI项目中。4.1 EventStream异步迭代器与推送模式的结合这是整个系统异步通信的基石。EventStream是一个同时实现了异步迭代器(asyncIterator)和推送(push)接口的对象。// 简化示意 function createMiniAgentStream() { const queue new AsyncQueue(); // 一个异步队列 let ended false; let finalResult: any null; return { // 推送端内部循环调用此方法发送事件 push(event: MiniAgentEvent) { if (!ended) queue.enqueue(event); }, // 结束流并设置最终结果 end(result: MiniAgentResult) { ended true; finalResult result; queue.enqueue(Symbol(end)); // 发送结束信号 }, // 消费端外部通过for-await-of消费事件 [Symbol.asyncIterator]() { return { async next() { const value await queue.dequeue(); if (value Symbol(end)) { return { done: true, value: finalResult }; } return { done: false, value }; }, }; }, }; }实战技巧在你自己实现需要产生异步事件流的函数时如文件处理、长轮询任务可以借鉴此模式。它让生产者agent-loop和消费者subscribe回调或for-await-of循环解耦代码清晰且易于测试。4.2 上下文压缩在有限窗口内保留最大信息当对话历史越来越长必然会触及模型的上下文窗口限制。直接截断最旧的消息是最差的方式会丢失关键信息。OpenClaw Mini实现了自适应分块摘要压缩。工作流程监控每次准备发送请求给模型前计算当前上下文的Token总数。判断如果总数超过安全阈值例如窗口上限的80%则触发压缩流程。选择从最旧的消息开始选取一定数量或时间范围的连续消息作为“待压缩块”。通常会跳过最近的消息和非常重要的系统消息。摘要调用大模型API对选中的消息块生成一个简洁的摘要。提示词类似于“请将以下对话历史总结成一段简短的段落保留关于[主题]的关键决策和事实。”替换用生成的摘要消息替换掉原来的那一大块消息。注意事项压缩有损摘要必然会丢失细节。对于需要精确引用的对话如代码片段、具体数字要谨慎使用或避免压缩。成本考量摘要本身也需要调用模型产生Token费用。需要权衡压缩节省的Token和摘要花费的Token。分层策略可以结合多种策略。例如优先删除完整的tool_result裁剪其次对较旧的user/assistant对话进行摘要永远保留最新的几条完整交互。4.3 工具系统抽象与安全执行Agent的能力边界由其工具决定。OpenClaw Mini的工具系统提供了清晰的抽象。// 工具定义接口 interface Tool { name: string; description: string; parameters: JSONSchema; // 工具参数的JSON Schema定义 execute(args: any, context: ToolContext): Promisestring; } // 工具上下文提供执行环境 interface ToolContext { workspaceDir: string; sessionKey: string; // ... 其他元数据 }内置工具示例list_files列出目录内容。read_file读取文件内容可指定行数范围。write_file写入文件内容。execute_command在安全子进程中执行Shell命令。search_memory查询长期记忆如果启用。安全实践参数验证利用JSON Schema在调用前验证参数格式避免运行时错误。路径沙箱所有文件操作工具都应将路径解析限制在workspaceDir或其子目录下防止目录遍历攻击。命令执行限制execute_command工具在生产环境中应受到严格限制可以考虑白名单机制或超时控制。OpenClaw Mini的工程层包含了sandbox-paths和tool-policy模块来处理这些安全问题。自定义工具你可以很容易地添加自己的工具。只需创建一个实现Tool接口的对象并在初始化Agent时通过tools选项传入。这极大地扩展了Agent的能力例如连接数据库、调用外部API、发送邮件等。4.4 Gateway的背压与流量控制当多个客户端通过Gateway连接同一个Agent会话时服务端需要向所有客户端广播事件。如果某个客户端网络很慢消费事件的速度跟不上服务端产生的速度就会导致消息在该客户端的连接缓冲区中堆积最终可能耗尽内存。OpenClaw Mini的解决方案是分级背压控制// 简化示意 function broadcastToSession(sessionKey: string, event: EventFrame) { const clients getClientsForSession(sessionKey); for (const client of clients) { if (client.isSlow()) { // 对于慢客户端丢弃非关键的历史事件 if (event.type chat_delta client.hasPendingDelta) { // 合并旧的delta只发送最新的 client.mergeDelta(event); continue; } // 或者直接丢弃某些低优先级的事件 if (shouldDropForSlowClient(event)) { continue; } } client.send(event); } }设计要点识别慢消费者通过检查客户端的发送队列长度或上次发送成功的时间来判断。事件优先级将事件分类。例如chat_delta流式文本片段可以合并或丢弃旧的而tool_execution_start工具开始和agent_error错误是关键事件必须送达。主动断开在极端情况下如果客户端长时间无法恢复服务端可以主动断开连接让其触发重连逻辑从而清空积压状态。5. 常见问题排查与性能调优在实际使用和基于此项目进行二次开发时你可能会遇到以下问题。5.1 连接与认证问题问题现象可能原因解决方案CLI运行pnpm dev报错Missing API key1..env文件未配置。2. 环境变量名错误。3. 系统未加载.env文件。1. 确认cp .env.example .env并已编辑。2. 检查.env中变量名与代码读取的变量名是否一致如ANTHROPIC_API_KEY。3. 尝试在命令前显式指定ANTHROPIC_API_KEYsk-xxx pnpm dev。Gateway客户端连接失败1. Gateway服务未启动。2. 端口被占用。3. Token不匹配。1. 确保在另一个终端运行了pnpm gateway。2. 使用--port指定不同端口并确保客户端连接地址正确。3. 检查服务端启动时的--token和客户端连接时使用的token是否一致。如果服务端未设token客户端也不应提供。使用国内模型API报超时或4031. 网络不通。2. API Key无效或过期。3.BASE_URL格式错误。1. 使用curl测试API端点是否可达。2. 在对应模型平台的控制台检查API Key状态和余额。3. 确保BASE_URL是完整的v1/completions接口的基地址例如https://open.bigmodel.cn/api/paas/v4。5.2 Agent运行与逻辑问题问题现象可能原因解决方案Agent陷入无限循环或工具调用过多1. 模型未能正确理解任务边界。2. 工具结果未能有效推动任务完成。3.maxOuterTurns或maxInnerSteps设置过高。1. 优化系统提示词AGENTS.md明确任务目标和停止条件。2. 检查工具返回的结果是否清晰、格式正确便于模型解析。3. 在Agent配置中调低maxTurns或maxSteps参数强制限制轮次。上下文窗口溢出错误1. 对话历史过长。2. 文件读取等工具返回了巨量内容。1. 确保Context的压缩功能已启用并调整其触发阈值contextWindowGuard相关配置。2. 为read_file等工具增加行数限制或提供文件摘要功能而非全文返回。工具执行失败如文件找不到1.workspaceDir路径配置错误。2. 相对路径解析问题。3. 权限不足。1. 确认Agent初始化时传入的workspaceDir是存在的绝对路径。2. 工具内部应将用户提供的路径与workspaceDir安全地拼接。检查sandbox-paths逻辑。3. 确保Node.js进程对工作目录有读写权限。5.3 性能调优建议会话持久化性能JSONL的追加写入性能很好。但如果单个会话文件过大如超过10MB读取和加载整个历史时可能会有延迟。可以考虑实现分页加载或为超大会话文件建立索引。内存使用Session模块在内存中缓存了活跃会话的历史。如果同时有成千上万个活跃会话内存压力会很大。生产环境需要引入LRU缓存并定期将不活跃的会话持久化到磁盘后从内存中移除。模型响应延迟大模型API调用是主要延迟来源。可以通过以下方式优化流式响应始终启用流式stream: true让用户能尽早看到部分结果。超时设置为API调用设置合理的超时如120秒并实现重试机制对可重试的错误如网络超时。并发控制通过command-queue模块控制同一时间发往同一模型提供商的请求数量避免被限流。Gateway扩展性当前Gateway是单实例。要支持水平扩展需要将会话状态如广播订阅关系外置到Redis等共享存储中并将WebSocket连接与具体的Agent执行器解耦。5.4 调试与开发技巧启用详细日志在开发时可以修改agent-events.ts或订阅所有事件将事件的详细内容打印到控制台有助于理解Agent的内部状态流转。使用测试套件项目自带的pnpm test运行了核心功能的单元测试。在添加新功能或修改现有逻辑时优先编写或补充测试用例。对照OpenClaw源码当对Mini版的某个设计有疑问时直接去查阅OpenClaw主仓库的对应模块项目文档中已给出对应关系。这是理解设计决策背后深层原因的最佳途径。从简单用例开始先运行pnpm example:basic确保最基本的对话流程正常。再逐步尝试自定义工具、启用记忆、连接Gateway等复杂功能隔离问题范围。这个项目就像一份精心绘制的地图指引你穿越AI Agent系统设计的复杂丛林。它不是要你照搬每一行代码而是希望你通过理解这些模式——事件流、双层循环、上下文管理、网关设计——来构建属于你自己的、更强大、更专用的智能体系统。