1. 项目概述一个轻量级个人AI助手的探索之旅最近在AI Agent领域OpenClaw这个项目引起了我的注意。它提出了一种构建个人AI助手的架构思路但直接上手研究一个成熟项目有时不如自己动手“造轮子”来得透彻。于是我启动了一个名为“clawlet”的编码练习项目。本质上clawlet是一个处于pre-alpha阶段的、轻量级的个人AI助手实现。它不是一个成熟可用的产品而更像是一个解剖麻雀的实验台核心目的是通过代码实践深入理解OpenClaw这类项目的设计哲学、技术栈选型和内部运作机制。这个项目目前基于Node.js构建其核心工作流是在本地运行一个大语言模型LLM然后通过一个命令行界面CLI或者Telegram机器人与这个本地模型进行交互。你可以把它想象成一个完全在你掌控之下的“数字伙伴”它运行在你的电脑上处理你的请求并能在你指定的“工作空间”文件夹内进行文件读写等基础操作。目前它主要面向macOS平台尤其是Apple Silicon芯片通过一个脚本便捷地利用苹果的MLX框架来运行本地模型。整个项目的状态正如其README所言“尚未完全工作绝对谈不上有用”但这恰恰是学习型项目的魅力所在——每一行代码都是为了理解原理每一个功能都是为了验证想法。2. 核心架构与设计思路拆解2.1 为何选择“复刻”OpenClaw作为学习路径在AI Agent层出不穷的今天选择OpenClaw作为蓝本进行学习是基于几个很实际的考量。首先OpenClaw本身采用TypeScript开发这对于前端或全栈开发者来说技术栈非常友好降低了入门门槛。其次它的设计相对清晰模块化程度高涵盖了从对话管理、工具调用到记忆存储等AI Agent的核心组件是一个很好的教学案例。最后通过动手实现一个简化版clawlet我可以强迫自己深入每个模块的细节而不是停留在API调用的表面。例如OpenClaw中复杂的技能Skill系统、权限控制和记忆管理在clawlet中我都需要思考如何用最直接的方式实现其核心思想这个过程能暴露很多在单纯阅读代码时忽略的问题。2.2 Clawlet的轻量化架构设计clawlet的设计目标非常明确轻量、可理解、模块化。它没有追求大而全的企业级功能而是聚焦于几个关键环节确保每个环节都可以独立运行和调试。通信层Messaging这是用户与AI交互的入口。clawlet实现了两种方式命令行接口CLI和Telegram Bot。CLI模式最适合开发和调试所有交互日志一目了然。Telegram Bot模式则提供了移动端交互的可能性增加了实用性。这两种方式都通过一个统一的适配器将用户输入转发给核心的“大脑”LLM并将“大脑”的思考结果返回给用户。核心引擎LLM Orchestrator这是系统的心脏。它负责接收用户消息结合上下文历史、系统指令、用户身份、助手身份以及各种记忆和知识构造出最终的提示词Prompt发送给本地运行的LLM。更重要的是它需要解析LLM的返回识别出其中可能包含的“工具调用”请求例如read_file然后安全地执行对应的技能Skill并将结果反馈给LLM形成多轮对话。这个过程就是所谓的“推理循环”ReAct模式的一种简化体现。技能系统Skills这是AI的“手和脚”。每个技能对应一个或多个工具调用例如读写文件、搜索记忆、查询知识库等。clawlet通过SKILL.md文件来定义技能其中包含了技能的描述、参数格式以及对应的执行函数。一个关键的设计是权限控制clawlet实现了基础的权限处理确保AI不能随意访问系统关键区域只能在你设定的“工作空间”内操作。记忆与知识系统Memory Knowledge这是AI的“经验与学识”。clawlet区分了几种不同类型的记忆会话历史Session History短期记忆保存在内存中维持当前对话的连贯性。每日记忆Daily Memory以Markdown文件形式按日期存储记录每天的重要交互格式如memory/2024-01-01/1200-meeting-notes.md。长期记忆Long-term Memory存储在轻量级数据库如SQLite中并支持关键词搜索。这里会结构化地存储关于“人”、“事”、“偏好”、“承诺”、“决定”、“经验教训”等实体及其关联。知识库Knowledge这里采用了更高级的检索方式包括向量搜索用于语义相似性查找、图搜索用于查找关联实体和冲突搜索用于发现矛盾或更新的信息。这为AI提供了强大的背景信息查询能力。身份与配置Identity Configuration通过SYSTEM_INSTRUCTIONS、SOUL.md、USER.md、IDENTITY.md等文件你可以深度定制AI的行为、价值观“灵魂”、你的个人资料以及AI助手的人格设定。这使得clawlet从一个通用工具变成一个真正个性化的助手。2.3 技术栈选型背后的逻辑运行时Node.js选择Node.js而非Go或Python主要为了与OpenClaw对标便于代码级的学习和对比。同时Node.js的异步非阻塞特性非常适合处理AI Agent中大量的I/O操作网络请求、文件读写、数据库查询。本地LLM服务MLX mlx-openai-server为了在Apple Silicon Mac上获得最佳的本地推理性能和最简单的部署方式选择了苹果官方的MLX框架。mlx-openai-server这个工具则扮演了关键角色它将在MLX上运行的模型包装成一个兼容OpenAI API格式的本地服务。这样clawlet的核心代码就可以使用标准的openaiNode.js库来调用本地模型极大地简化了集成复杂度。launch-mlx.sh脚本自动化了环境搭建和服务器启动过程。包管理pnpm在开发版本中使用pnpm主要是出于其速度快、磁盘空间利用率高的优点对于需要安装多个依赖的Node.js项目体验很好。发布到npm后用户则可以通过npx直接运行无需关心包管理工具。数据库与向量存储为了保持轻量长期记忆很可能选用SQLite。向量搜索可能集成xenova/transformers用于生成嵌入向量并使用hnswlib-node或vectordb这类轻量级向量库进行存储和检索。图搜索可能基于关系数据库中的关联表实现或集成一个微型图数据库。注意技术选型紧密围绕“学习”和“轻量”两个目标。在生产环境中可能需要考虑更强大的向量数据库如Qdrant、更成熟的任务队列等但在这里简单、可运行、易理解是第一位的。3. 环境准备与核心组件部署实操3.1 基础环境搭建macOS Focus由于clawlet目前主要支持macOS以下步骤以macOSApple Silicon为例。确保你的系统已安装Homebrew和Node.js建议LTS版本。# 1. 克隆项目仓库假设你从GitHub克隆 git clone repository-url cd clawlet # 2. 安装项目依赖开发版 # 项目使用pnpm如果没有请先安装brew install pnpm pnpm install3.2 本地LLM引擎的部署与调优这是整个项目的基石。clawlet依赖一个本地运行的、兼容OpenAI API的LLM服务。步骤一运行MLX启动脚本项目根目录下的launch-mlx.sh脚本是为你准备好的“一键部署”工具。我们来看看它做了什么以及你可能需要的手动调整# 赋予脚本执行权限 chmod x ./launch-mlx.sh # 执行脚本 ./launch-mlx.sh这个脚本通常会执行以下操作检查并安装Python 3.11通过Homebrew。创建并激活一个Python虚拟环境.venv。使用pip安装mlx-lm和mlx-openai-server。可能还会下载一个预设的模型如Qwen2.5-Coder-7B-Instruct-4bit。启动mlx-openai-server在127.0.0.1:8000端口提供服务。步骤二验证与配置LLM服务脚本执行成功后你应该能在终端看到服务器启动的日志。打开另一个终端进行测试curl http://127.0.0.1:8000/v1/models如果返回一个包含模型列表的JSON说明服务运行正常。关键配置点模型选择mlx-openai-server默认可能使用一个基础模型。对于编码助手场景建议使用代码能力强的模型。你可以修改启动命令指定模型路径或Hugging Face模型ID。例如在脚本中找到类似mlx-openai-server --model HF_REPO_ID的地方进行修改。性能与资源在launch-mlx.sh中你可能看到--max-tokens、--temp等参数。根据你的Mac内存尤其是统一内存大小调整上下文长度--max-tokens和批处理大小以避免内存溢出OOM。对于16GB内存的Mac运行7B参数的4位量化模型是比较稳妥的起点。API兼容性确保clawlet的配置指向正确的本地API地址。在clawlet的配置文件可能是.env或某个config文件中需要将LLM的baseURL设置为http://127.0.0.1:8000/v1并且apiKey可以设为任意非空字符串如“sk-no-key-required”因为本地服务器通常不验证密钥。3.3 通信渠道配置Telegram Bot实战为了让clawlet能通过Telegram与你对话需要完成以下步骤创建Telegram Bot在Telegram中搜索BotFather并开始对话。发送/newbot指令按照提示设置机器人的名字如My Clawlet Assistant和用户名必须以bot结尾如my_clawlet_bot。创建成功后BotFather会提供一个HTTP API访问令牌形如1234567890:ABCdefGHIjklMnOprSTUvWxyZ-abc123def。妥善保存此令牌。获取你的Telegram User ID在Telegram中搜索userinfobot向它发送任意消息它会回复你的用户ID。配置clawlet在clawlet项目根目录找到或创建.env文件。填入你的信息TELEGRAM_BOT_TOKEN1234567890:ABCdefGHIjklMnOprSTUvWxyZ-abc123def TELEGRAM_USERINFO_ID987654321重要安全提示TELEGRAM_USERINFO_ID是一个简单的权限控制只有此ID对应的用户才能与机器人交互。在生产环境中你需要更复杂的用户管理系统。务必不要将.env文件提交到Git仓库应将其添加到.gitignore中。启动与测试配置完成后启动clawletpnpm start或通过npx。在Telegram中找到你的机器人通过其用户名发送/start。如果配置正确你应该能收到回复。实操心得Telegram Bot的配置相对简单但网络环境可能影响连接。确保你的运行clawlet的机器可以稳定访问Telegram的API。如果出现超时可以检查网络代理设置。此外BotFather提供的令牌拥有该机器人的最高权限切勿泄露。4. 核心功能模块深度解析与实现4.1 技能系统AI的“可执行程序”技能是clawlet与外界交互的桥梁。每个技能对应一个tool_call由LLM在推理过程中提出请求由clawlet执行。技能定义SKILL.md示例一个典型的SKILL.md文件可能如下所示# read_file **Description**: Reads the content of a file from the workspace. **Parameters**: - path (string): The relative path to the file within the workspace. **Permissions**: Requires fs.read permission on the target path. **Implementation**: skills/filesystem/readFile.ts技能实现解析在对应的TypeScript文件如readFile.ts中你会看到一个标准的工具函数import fs from fs/promises; import path from path; export async function readFile(args: { path: string }, context: SkillContext) { // 1. 权限检查确保请求的路径在允许的工作空间内 const workspacePath context.workspaceRoot; const absolutePath path.resolve(workspacePath, args.path); if (!absolutePath.startsWith(workspacePath)) { throw new Error(Permission denied: Attempt to access outside workspace.); } // 2. 安全检查防止路径遍历攻击如../../../etc/passwd const normalizedPath path.normalize(args.path); if (normalizedPath.startsWith(..) || path.isAbsolute(normalizedPath)) { throw new Error(Invalid path provided.); } // 3. 执行操作 try { const content await fs.readFile(absolutePath, utf-8); return { success: true, content: content }; } catch (error: any) { return { success: false, error: Failed to read file: ${error.message} }; } }权限处理机制clawlet的权限系统可能通过一个中央的PermissionManager来实现。每个技能在注册时声明所需的权限如fs.read:/projects/。当Orchestrator准备调用技能时会先查询当前会话的上下文用户身份、对话历史等并由PermissionManager判断是否放行。这种“声明式”权限比硬编码在技能函数里更灵活便于集中管理。4.2 记忆系统的多层次实现记忆系统是AI体现“智能”和“连续性”的关键。clawlet设计了多层记忆结构。会话历史短期记忆实现简单地在内存中维护一个数组保存最近的N轮对话用户消息、AI回复、工具调用及结果。通常采用“滑动窗口”机制当对话轮数超过上限时丢弃最早的记录但可能会将重要信息摘要后存入长期记忆。技巧在构造给LLM的Prompt时并非简单拼接所有历史消息。需要精心设计格式将用户消息、AI思考过程、工具调用和观察结果清晰地区分开以帮助LLM更好地理解上下文。通常采用类似[User],[Assistant],[Tool Call],[Tool Result]的标记。长期记忆与知识库存储使用SQLite存储结构化的记忆条目。每一条记忆可能包含ID、类型person, event, fact等、内容摘要、原始内容引用指向Markdown文件、创建时间、最后访问时间、关联的关键词或标签。关键词搜索在记忆存入时通过一个简单的分词库或调用LLM提取关键词并建立倒排索引。查询时对用户问题也进行分词然后进行匹配。向量搜索嵌入生成当存储一篇文档如USER.md或每日记忆到知识库时使用一个本地嵌入模型如Xenova/all-MiniLM-L6-v2将文本转换为一个高维向量embedding。向量存储将这个向量和文本的元数据ID 来源一起存入一个向量索引中例如使用hnswlib-node它是一个高效的近似最近邻ANN搜索库。检索当用户提问时将问题同样转换为向量然后在向量索引中搜索最相似的K个向量返回对应的文本片段作为上下文。图搜索这是更高级的功能。例如当记忆条目涉及“人”和“公司”时可以建立“人-就职于-公司”的关系边。使用一个轻量级图库如neo4j-driver连接本地Neo4j或使用graphology内存图来存储和遍历这些关系。当用户问“张三在哪个公司工作”时可以通过图查询快速找到答案。冲突检测这是一个有趣的特性。当存入一条新记忆如“张三的职位是高级工程师”时系统可以检索已有记忆中关于“张三”和“职位”的信息。如果发现旧记忆是“张三的职位是工程师”系统可以标记一个“冲突”并在下次用户提及相关话题时主动询问以确认最新信息。4.3 提示词工程与“灵魂”注入clawlet通过多个Markdown文件来塑造AI的行为这是其个性化程度高的原因。SYSTEM_INSTRUCTIONS这是最核心的指令。它定义了AI的核心行为准则、思考框架如要求逐步思考、使用工具和输出格式如必须用tool_call标签。这里需要写得非常详细和明确。SOUL.md这定义了AI的性格、价值观和沟通风格。例如“你是一个乐于助人且严谨的编码助手喜欢用比喻解释复杂概念但讨厌说废话。” 这个文件的内容会被注入到系统指令中让AI的回复更具“人味”。USER.md这是关于你的档案。包含你的姓名、职业、技术栈、正在进行的项目、个人偏好等。AI在回答时会参考这些信息提供更个性化的建议如“根据你常用的React技术栈我建议...”。IDENTITY.md这是AI的自我简介。给它一个名字、一个角色如“你的专属代码伙伴Claw”让它更融入对话。这些文件是如何工作的在每次对话开始时Orchestrator会将这些文件的内容、相关的记忆片段、当前会话历史按照一个预定义的模板拼接成一个巨大的Prompt发送给LLM。这个模板的设计至关重要它决定了LLM能否正确理解自己的角色、任务和可用的资源。一个简化的Prompt模板可能如下# System Instructions {system_instructions} # My Identity {identity_content} # About You (The User) {user_content} # My Soul (Communication Guidelines) {soul_content} # Relevant Memories (From long-term storage) {memories_context} # Knowledge Base Context (From vector/graph search) {knowledge_context} # Conversation History (Last 10 turns) {conversation_history} # Current Task User: {current_user_message} # Your Response (You must think step by step. You can use tools marked with tool_call...)5. 开发工作流、测试与问题排查实录5.1 从零启动与调试工作流启动顺序务必先启动本地LLM服务./launch-mlx.sh确认http://127.0.0.1:8000可访问后再启动clawlet应用pnpm start。调试模式在开发时建议优先使用CLI模式进行测试因为所有日志网络请求、工具调用、内存操作都会直接打印在终端便于排查问题。可以在启动命令中增加环境变量来开启更详细的调试日志例如DEBUGclawlet:* pnpm start。观察推理过程一个设计良好的AI Agent应该将其“思考过程”输出出来。在clawlet的CLI中你应该能看到LLM的“内部独白”用[Thought]之类的标记以及它发起的tool_call和收到的tool_result。这是诊断AI是否理解任务、是否正确选择工具的关键。5.2 常见问题与解决方案速查表以下是我在搭建和运行类似clawlet项目时遇到的一些典型问题及解决思路问题现象可能原因排查步骤与解决方案启动launch-mlx.sh失败提示Python或pip错误。1. Homebrew未安装或异常。2. Python 3.11安装失败。3. 虚拟环境创建失败。1. 检查Homebrewbrew --version。2. 尝试手动安装Python 3.11brew install python3.11。3. 手动创建venvpython3.11 -m venv .venv然后手动安装依赖source .venv/bin/activate pip install mlx-lm mlx-openai-server。LLM服务(:8000)启动成功但clawlet连接超时或报错。1. clawlet配置的API地址或端口错误。2. 本地防火墙或网络代理阻止了连接。3. MLX服务器模型加载失败。1. 用curl http://127.0.0.1:8000/v1/models测试服务是否真的就绪。2. 检查clawlet的.env或config文件确认BASE_URL和API_KEY设置正确。3. 查看MLX服务器的启动日志确认模型是否下载并加载成功。Telegram Bot无响应。1..env文件中的Token或User ID配置错误。2. 运行clawlet的服务器无法访问Telegram API网络问题。3. Bot未启用或已被禁用。1. 仔细核对.env文件确保没有多余空格或换行。2. 尝试在服务器上curl api.telegram.org测试网络连通性。3. 在Telegram中给Bot发送/start如果没反应尝试通过BotFather的/mybots菜单查看Bot状态。AI不调用工具或总是调用错误的工具。1.SYSTEM_INSTRUCTIONS中关于工具使用的指令不清晰。2. 工具的描述在SKILL.md中不够准确LLM无法理解其用途。3. Prompt中提供的工具列表格式有误。1. 强化系统指令明确要求AI在需要时使用指定格式的工具调用并举例说明。2. 优化SKILL.md中的描述使用LLM容易理解的词汇并明确参数格式。3. 在Orchestrator的日志中检查发送给LLM的Prompt中工具列表部分是否正确渲染。向量搜索返回不相关的结果。1. 嵌入模型embedding model不适合当前领域如代码搜索用了通用文本模型。2. 检索时返回的top-K数量不合适。3. 文本块chunk的大小和重叠设置不合理。1. 尝试更换更适合的嵌入模型例如对于代码可以尝试Xenova/gte-code等专用模型。2. 调整检索的topK参数增大它以获得更多上下文或结合关键词进行混合检索Hybrid Search。3. 调整知识文档的切分策略避免将完整语义割裂。项目运行缓慢内存占用高。1. 本地LLM模型过大超出硬件负载。2. 记忆/知识库检索未做缓存每次对话都全量搜索。3. 会话历史过长导致Prompt巨大。1. 换用更小或量化程度更高的模型如从7B换到3B或从4-bit换到8-bit。2. 为频繁查询的记忆和知识实现LRU缓存。3. 为长会话历史实现摘要功能将早期对话总结成一段文字而不是保留全部原始消息。5.3 性能优化与扩展思考冷启动优化本地嵌入模型和LLM模型加载较慢。可以考虑设计一个“预热”机制在应用启动时异步加载这些重型资源而不是在第一次请求时加载。检索增强生成RAG流程优化clawlet的知识检索是典型的RAG应用。优化点包括对用户查询进行重写或扩展以提高检索命中率对检索到的多个片段进行相关性排序或去重在Prompt中明确指示AI“基于以下上下文回答”并限制其胡编乱造。技能沙箱Sandbox对于文件操作、执行命令等高风险技能未来的版本应该考虑在严格的沙箱环境中运行例如使用Node.js的worker_threads配合资源限制或调用Docker容器彻底隔离潜在风险。支持更多消息平台除了CLI和Telegram可以适配Discord、Slack甚至微信通过反向代理等平台只需实现对应的消息接收和发送适配器即可。通过clawlet这个项目我深刻体会到构建一个实用的个人AI助手技术实现只是一部分更重要的是对交互逻辑、记忆管理和安全边界的细致设计。它就像在搭建一个数字大脑的雏形每一次工具调用、每一段记忆存储、每一次权限检查都是在为这个大脑划定能力和行为的边界。这个过程充满挑战但每当看到AI能根据我的指令正确读取文件、结合过往记忆回答问题那种“它真的理解了”的瞬间让所有调试的枯燥都变得值得。