OpenMozi：轻量级国产生态AI助手框架，快速集成QQ/飞书/钉钉

1. 项目概述为什么我们需要一个“国产生态优先”的AI助手框架如果你最近在折腾AI助手想把大模型的能力接入到日常的办公软件里比如在飞书群里让AI帮你写周报或者在QQ群里让它查资料那你大概率会遇到一个头疼的问题市面上的框架要么太重动辄几十万行代码学习成本高得吓人要么就是对国内常用的通讯软件支持得不好配置起来像在走迷宫。我自己就踩过不少坑从配置Webhook到处理各种回调光是让机器人在钉钉上回句话可能就得花上大半天。OpenMozi这个项目就是在这种背景下诞生的。它的定位非常清晰一个轻量级、专注于国产生态的AI助手框架。简单来说它用大约1.6万行代码实现了AI Agent的核心功能并且原生支持QQ、飞书、钉钉和企业微信。这背后其实反映了一个很实际的需求很多国内团队和个人开发者他们的主要沟通阵地就是这些平台他们需要一个开箱即用、配置简单、代码清晰易懂的解决方案而不是一个功能庞杂、需要深厚功底才能驾驭的“巨无霸”。它的核心价值在于“专注”和“轻量”。它没有试图去覆盖所有海外平台比如Slack、Telegram而是把精力集中在国内最主流的几个通讯工具上。同时它基于成熟的底层库pi-coding-agent和pi-ai构建自己则专注于做好“连接器”和“适配器”的工作。这意味着对于想学习AI Agent工作原理或者想快速为团队搭建一个智能助手的开发者来说OpenMozi是一个绝佳的起点。代码量少结构清晰你很容易就能看懂消息是怎么从飞书接收经过AI处理再返回去的整个流程。1.1 核心设计思路在简洁与功能之间找到平衡OpenMozi的设计哲学可以从它与另一个知名项目Moltbot的对比中看得一清二楚。Moltbot是一个功能非常全面的个人AI助手框架但它的代码量超过了50万行。对于大多数只是想实现一个团队机器人的开发者来说这无异于用高射炮打蚊子。OpenMozi选择了另一条路做减法但做精核心。它用Moltbot大约3%的代码量实现了AI助手最核心的几大模块多模型调用通过pi-ai统一层支持DeepSeek、通义千问、智谱AI等国产模型也兼容OpenAI、Claude。多平台通道为QQ、飞书、钉钉提供了长连接适配器无需公网IP和复杂的回调配置。Agent运行时基于pi-coding-agent处理消息循环、工具调用和上下文管理。可扩展架构通过Skills技能和Plugins插件系统允许用户无需修改核心代码就能增加功能。这种设计带来的直接好处就是易于理解和二次开发。当你需要定制一个特殊功能或者排查一个问题时你不需要在数十个目录、上千个文件中寻找线索。整个项目的结构一目了然主要逻辑集中在几个核心目录下阅读源码的学习成本大大降低。注意选择框架时一定要明确自己的场景。如果你的需求是集成海外平台或者需要极其复杂的工作流编排那么Moltbot这类全功能框架可能更合适。但如果你需要一个为国内环境优化、快速上手的轻量级解决方案OpenMozi的优势就非常明显了。2. 核心模块深度解析OpenMozi是如何工作的要真正用好一个框架不能只停留在“跑起来”的层面理解其内部各个模块的职责和协作方式至关重要。这样当出现问题时你才能快速定位当需要扩展时你才知道从哪里下手。OpenMozi的架构清晰地分为了几个层次我们可以把它想象成一个智能客服中心。2.1 通道层 (Channels)消息的“前台接待”src/channels/目录下的代码就是机器人的“耳朵”和“嘴巴”。它负责与外部通讯平台如飞书、钉钉进行对接将不同平台格式各异的消息统一转换成框架内部能理解的格式反之亦然。这里有一个关键设计对QQ、飞书、钉钉优先采用长连接WebSocket/Stream模式。这与传统的Webhook回调模式有本质区别Webhook模式需要你有一个公网IP或域名配置回调地址。平台会把消息推送到你这个地址。对个人开发者或内网环境不友好。长连接模式你的机器人程序主动与平台服务器建立一个持久连接并通过这个连接收发消息。最大的好处就是不需要公网IP在家庭网络或公司内网也能直接运行。以飞书为例启动OpenMozi后它会主动连接飞书的WebSocket网关。当你在飞书群里机器人时消息会通过这个长连接实时推送到你的OpenMozi服务处理完后再通过同一个连接发回去。整个过程对网络环境要求更低部署更简单。各平台连接方式对比平台连接模式需要公网IP核心配置项飞书WebSocket 长连接否appId,appSecret钉钉Stream 长连接否appKey,appSecretQQWebSocket 长连接否appId,clientSecret企业微信HTTP Webhook 回调是corpId,agentId,token等实操心得在初次配置时强烈建议从一个平台开始比如先用--web-only模式在浏览器里测试通核心的AI对话功能然后再单独配置飞书或钉钉。同时配置多个平台时如果某个平台连接失败日志可能会混杂增加排查难度。2.2 模型与提供商层 (Providers)AI的“大脑供应商”src/providers/模块的作用是解耦。它基于pi-ai库将不同AI服务提供商如DeepSeek、OpenAI的API差异封装起来向上提供统一的调用接口。你可以这样理解Agent核心模块不需要关心对面是DeepSeek还是通义千问它只需要说“请处理这条消息”Providers层负责找到正确的“供应商”并完成对话。OpenMozi预置了丰富的国产模型支持这是它“国产生态优先”的集中体现提供商环境变量特点与适用场景DeepSeekDEEPSEEK_API_KEY性价比高推理能力强适合通用对话和代码任务。豆包 (火山引擎)DOUBAO_API_KEY字节系Seed系列模型在深度思考任务上表现不错上下文长。DashScope (阿里云)DASHSCOPE_API_KEY通义千问商业版稳定性好适合企业级高并发场景。智谱AIZHIPU_API_KEYGLM系列技术背景强常有免费额度适合尝鲜和轻度使用。Kimi (Moonshot)KIMI_API_KEY以超长上下文处理能力著称适合需要分析长文档的场景。阶跃星辰STEPFUN_API_KEYStep系列模型在推理和多模态方面有特色。配置的优先级与灵活性 OpenMozi的配置系统很灵活。你可以通过mozi onboard向导生成一个~/.mozi/config.local.json5文件这是最高优先级的配置。在这个文件里你不仅可以填写API密钥还可以覆盖模型的默认参数。比如你觉得DeepSeek的默认maxTokens太小可以在这里单独为它指定一个更大的值。// ~/.mozi/config.local.json5 示例片段 { providers: { deepseek: { apiKey: sk-your-deepseek-key-here, // 覆盖默认模型列表中的某个模型参数 models: [ { id: deepseek-chat, name: DeepSeek Chat, contextWindow: 128000, // 修改上下文窗口 maxTokens: 8192, // 修改单次回复最大token数 supportsVision: false, supportsTools: true } ] } } }2.3 Agent核心与工具层思维的“决策中枢”与“双手”这是最核心的部分位于src/agents/和src/tools/。Agent基于pi-coding-agent运行它管理着一个消息循环接收用户输入。结合历史会话上下文和可用工具列表调用大模型。模型可能返回纯文本也可能返回一个“工具调用”请求。如果返回工具调用Agent就找到对应的工具函数执行它比如读取文件、搜索网页。将工具执行的结果作为新的上下文再次送给模型。循环直到模型返回最终的自然语言结果。将结果通过Channels层返回给用户。工具系统是Agent能力延伸的关键。OpenMozi内置了25个工具分为几大类文件操作read_file,write_file,edit_file。这让AI可以帮你读写本地项目文件。系统命令bash。这是一个需要谨慎使用的强大工具它允许AI在服务器上执行Shell命令。网络能力web_search,web_fetch。让AI能获取实时信息。记忆与定时memory_*,cron_*。实现跨会话记忆和定时任务。重要安全提示bash工具极其强大也极其危险。在生产环境中启用前务必在配置中考虑安全限制例如通过插件系统对可执行的命令范围进行约束或仅限受信任的用户使用。切勿在开放环境中让AI拥有无限制的系统命令执行权。2.4 技能系统 (Skills)为AI注入“专业知识”这是OpenMozi一个非常巧妙的设计位于src/skills/。Skills系统允许你通过编写Markdown文件SKILL.md来扩展AI的能力而无需修改任何JavaScript/TypeScript代码。它的工作原理是在启动时框架会扫描指定的技能目录读取所有SKILL.md文件将其中的内容主要是YAML头信息和Markdown正文进行解析和整合然后注入到每次请求AI时的系统提示词System Prompt中。这意味着你可以给AI设定角色、规则、专业知识。例如你可以创建一个“代码评审专家”技能--- name: code-reviewer title: 代码评审助手 description: 专注于审查JavaScript/TypeScript代码提供改进建议。 priority: 50 --- 你是一个经验丰富的代码评审专家擅长发现JavaScript/TypeScript代码中的问题。 ## 评审原则 1. 首先检查代码安全性避免SQL注入、XSS等漏洞。 2. 关注代码可读性和一致性命名、格式。 3. 检查性能瓶颈和潜在的内存泄漏。 4. 对异步操作Promise, async/await的错误处理进行重点审查。 5. 提供具体的、可操作的修改建议并解释原因。 ## 输出格式 请按以下结构给出评审意见 - **安全问题**... - **代码风格**... - **性能建议**... - **最佳实践**...当这个技能被启用后AI在回答任何与代码相关的问题时都会自带这份“评审原则”回答会更专业、更符合你的预期。技能加载有三个优先级方便管理和覆盖工作区级(./.mozi/skills/)优先级最高只对当前项目生效。用户级(~/.mozi/skills/)对所有项目生效。内置级(skills/)框架自带优先级最低。3. 从零开始手把手搭建你的第一个企业微信机器人理论讲得再多不如动手做一遍。我们以配置相对复杂一点的企业微信因为需要公网为例展示从环境准备到机器人回应的完整流程。选择企业微信是因为它的配置步骤最具代表性涉及内网穿透搞懂了它其他平台就更不在话下。3.1 环境准备与初始化首先确保你的系统满足基础要求Node.js版本 18。建议使用LTS版本可以通过node -v检查。包管理器npm、yarn或pnpm均可。OpenMozi推荐使用pnpm速度更快。网络能正常访问外网用于下载包和调用AI API。安装OpenMozi 有两种方式对于只是想使用的用户全局安装CLI工具最方便。# 使用npm全局安装最推荐新手的方式 npm install -g mozi-bot # 安装后验证是否成功 mozi --version如果看到版本号输出说明安装成功。运行配置向导 OpenMozi提供了一个交互式的配置向导mozi onboard它会一步步引导你完成所有必要配置。mozi onboard接下来你会看到一个命令行交互界面依次配置选择模型提供商比如按空格键选中DeepSeek然后回车。输入API密钥将你的DeepSeek API Key粘贴进去。其他模型类似。选择通讯平台这里我们选中WeCom(企业微信)。配置服务器一般用默认的3000端口和0.0.0.0即可。配置Agent设置默认模型、温度等。初次使用保持默认。配置记忆系统是否启用长期记忆默认启用。向导结束后会在你的用户目录下生成~/.mozi/config.local.json5文件。这是我们所有配置的核心。3.2 企业微信后台配置详解企业微信采用Webhook回调需要你的服务有一个公网可访问的地址。对于开发测试我们使用内网穿透工具来模拟公网地址。这里以国内比较常用的ngrok或frp为例也可以使用一些服务商提供的免费隧道。第一步启动OpenMozi服务并获取穿透地址先临时启动服务让ngrok能代理到它。mozi start --web-only --port 3000使用ngrok创建隧道假设你已安装ngrok并登录。ngrok http 3000ngrok会显示一个临时的公网地址如https://abc123.ngrok-free.app。记下这个地址例如https://abc123.ngrok-free.app。第二步在企业微信管理后台创建应用登录 企业微信管理后台 。进入“应用管理” - “自建应用” - “创建应用”。填写应用名称如“Mozi助手”、上传Logo选择可见范围可以选你自己或某个部门。创建成功后进入应用详情页记录以下关键信息AgentId应用详情页顶部。CorpId我的企业 - 企业信息 - 企业ID。Secret应用详情页 - “权限管理”部分点击“查看Secret”。第三步配置接收消息在应用详情页找到“接收消息”设置点击“配置”。URL填写你的ngrok地址加上OpenMozi的企业微信回调路径。格式为你的公网地址/mozi/wecom/callback。例如https://abc123.ngrok-free.app/mozi/wecom/callback。Token自己定义一个字符串如YourToken123用于验证消息。EncodingAESKey点击“随机生成”即可。点击“保存”。此时企业微信会向你填写的URL发送一个验证请求。因为我们的OpenMozi服务还没配置好这些参数所以验证会失败这是正常的。我们先去配置OpenMozi。3.3 配置OpenMozi连接企业微信现在我们需要修改OpenMozi的配置文件填入从企业微信获取的信息。 打开~/.mozi/config.local.json5文件找到channels部分添加wecom配置{ // ... 其他配置如providers... channels: { // ... 其他平台配置 ... wecom: { corpId: 你的企业CorpId, // 例如wwxxxxxxxxxxxxxxx corpSecret: 你的应用Secret, // 从应用详情页获取 agentId: 你的应用AgentId, // 数字例如1000002 token: YourToken123, // 必须与后台配置的Token完全一致 encodingAESKey: 你生成的EncodingAESKey // 必须与后台完全一致 } } }关键点token和encodingAESKey必须与企业微信后台填写的一字不差否则消息解密会失败。重启服务 保存配置文件然后停止之前用--web-only启动的服务用完整模式重启这样才会加载企业微信通道。# 如果之前服务在运行先按 CtrlC 停止 mozi start # 或者指定端口 mozi start --port 3000观察启动日志应该能看到类似[WeCom] Initializing...和[WeCom] Callback server listening at /mozi/wecom/callback的信息。第四步完成企业微信验证回到企业微信管理后台的“接收消息”配置页面再次点击“保存”。这次OpenMozi已经运行并配置了正确的Token和AESKey应该能成功通过验证页面会提示“配置成功”。3.4 测试与交互在企业微信手机App或PC客户端找到你刚刚创建的应用可能在“工作台”里。向这个应用发送一条消息比如“你好”。查看OpenMozi的服务日志。你应该能看到接收消息、调用AI模型、返回响应的日志。稍等片刻在企业微信中就能收到AI的回复了。避坑指南URL地址确保ngrok隧道稳定如果重启ngrok地址会变需要回企业微信后台更新URL。Token和AESKey这是最常见的错误来源务必核对无误注意不要有多余的空格。网络超时企业微信服务器回调你的服务有超时限制通常5秒。如果你的AI模型响应太慢可能导致企业微信收不到回复。可以考虑在Agent配置中调整超时设置或者使用响应更快的模型。日志排查如果收不到回复首先查看OpenMozi的日志 (mozi logs -f)看是否收到了消息AI调用是否成功。企业微信后台也有“调试工具”可以查看消息发送状态。至此你已经成功将一个AI助手接入了企业微信。对于飞书、钉钉和QQ由于它们使用长连接配置步骤更简单通常只需要在对应开放平台创建应用获取appId和appSecret填入配置即可无需处理回调URL和内网穿透。4. 高级功能实战打造一个能记忆、会定制的专属助手基础对话功能实现后OpenMozi真正强大的地方在于它的可扩展性。通过Skills和记忆系统你可以打造一个真正“懂你”的个性化助手。4.1 利用Skills系统创建领域专家助手假设你是一个运维工程师希望AI能帮你分析服务器日志。你可以创建一个log-analyzer技能。创建技能目录和文件# 在用户级技能目录创建 mkdir -p ~/.mozi/skills/log-analyzer创建文件~/.mozi/skills/log-analyzer/SKILL.md内容如下--- name: log-analyzer title: Linux 服务器日志分析专家 description: 专门分析 Nginx、Systemd 等常见日志识别错误、警告和性能瓶颈。 version: 1.0 tags: - ops - linux - log priority: 30 --- 你是一个资深的Linux运维专家专注于服务器日志分析。当用户提供日志内容或片段时请按以下流程工作 ## 分析流程 1. **日志归类**首先识别日志来源Nginx访问/错误日志、Systemd Journal、内核日志dmesg、应用日志等。 2. **时间线梳理**如果日志包含时间戳尝试梳理事件发生的顺序。 3. **模式识别**寻找高频错误码如502、404、异常关键词ERROR、FATAL、WARN、资源耗尽提示OOM, disk full。 4. **关联分析**将不同的错误信息关联起来推测根本原因例如数据库连接失败导致应用报错。 5. **行动建议**提供具体的、可执行的排查命令或修复建议。 ## 输出格式 请用以下结构组织回答 ### 日志摘要 - **来源**[识别出的日志类型] - **时间范围**[如有] - **关键问题**[用一两句话概括核心问题] ### ⚠️ 发现的问题 使用列表形式每条包含错误级别、错误信息、可能原因 ### ️ 建议的排查步骤 1. [第一步命令或检查] 2. [第二步命令或检查] ... ### 潜在优化建议 针对性能瓶颈或配置问题保存文件后无需重启服务。OpenMozi的技能系统支持热加载取决于配置或者你重启一下服务mozi restart。测试效果 现在当你向机器人粘贴一段Nginx错误日志时它的回复会变得非常有条理和专业直接按照你定义的格式输出分析结果而不是泛泛而谈。这就是Skills系统注入专业知识的力量。4.2 活用记忆系统让AI记住你的偏好记忆系统默认是开启的。它的行为是隐式的AI会在对话中自动判断何时该记住一些信息。例如你“我住在北京。”AI调用memory_store工具存储“用户居住在北京”这条信息可能打上location,user-preference标签。你“明天天气怎么样”AI在组织查询天气的请求前先调用memory_query工具查询location相关的记忆得到“北京”然后生成查询“北京明天天气”。你也可以通过配置调整记忆系统的行为或者手动管理记忆。记忆文件存储在~/.mozi/memory/目录下是JSON格式方便查看和备份。4.3 实现自动化定时任务与主动推送这是OpenMozi的另一个亮点。你不仅可以让AI被动响应还可以让它主动工作。场景每天上午10点让AI检查某个API状态并将结果推送到钉钉群。实现步骤确保钉钉通道已正确配置并连接。通过对话创建定时任务。你可以直接对机器人说“创建一个定时任务名字叫‘每日API健康检查’。每天上午10点执行。执行内容是调用web_fetch工具获取 https://api.example.com/health 的内容分析状态是否正常然后将结果摘要发送到钉钉群‘技术部’。”AI会理解你的意图并使用cron_add工具来创建这个任务。你需要告诉它钉钉群的chatId机器人所在群的群ID。任务创建后会被保存到~/.mozi/cron/jobs.json。到每天10点OpenMozi的定时任务调度器会自动触发一个agentTurnAI会执行你设定的消息内容并将最终结果通过outbound出站模块推送到指定的钉钉群。技术原理 定时任务模块 (src/cron/) 使用了一个轻量级的调度器。agentTurn类型的任务本质上是模拟了一个用户对话回合。调度器在指定时间触发创建一个临时的会话将你预设的message例如“检查API健康”发送给AI。AI会像处理普通对话一样进行思考、调用工具如web_fetch生成回复。最后如果任务配置了deliver: true框架会将AI的最终回复通过对应的Channel如钉钉的主动消息接口发送出去。注意事项主动消息推送功能在某些平台有限制。例如QQ机器人要求接收用户必须在24小时内与机器人有过互动才能向其发送主动消息。钉钉和飞书的企业应用通常限制较少。在使用前请务必查阅对应平台的官方文档了解主动消息推送的规则和频率限制避免触发风控。5. 常见问题与排查技巧实录在实际部署和使用过程中你肯定会遇到各种各样的问题。下面是我在多次部署中总结的一些典型问题和解决方法。5.1 通道连接失败问题现象启动服务时日志显示飞书/钉钉/QQ连接失败或不断重连。检查点1应用凭证appId,appSecret,appKey等是否填写正确尤其在复制粘贴时注意首尾不要有空格。检查点2网络环境确保运行OpenMozi的服务器可以访问对应平台的开放API地址。有些公司内网有防火墙限制需要配置代理。可以在配置文件的channels.xxx部分尝试添加proxy配置如果框架支持或需要修改底层HTTP客户端配置。检查点3平台配置以飞书为例需要在 飞书开放平台 创建“企业自建应用”并开启“机器人”能力。确保“权限管理”里勾选了“获取群组信息”、“发送消息”等必要权限。创建应用后一定要发布到企业否则机器人无法使用。检查点4日志级别使用mozi start --log-level debug或修改配置中logging.level为debug查看更详细的握手和通信日志有助于定位问题。5.2 AI模型无响应或响应慢问题现象消息发出后长时间收不到回复或日志显示模型调用超时。检查点1API密钥与余额首先确认对应模型的API密钥有效并且账户有足够的余额或免费额度。可以尝试在命令行用curl或直接访问模型提供商的控制台进行测试。检查点2网络连通性确认服务器能访问模型API的域名。例如DeepSeek的API域名为api.deepseek.com。可以尝试ping或curl -v测试。检查点3模型参数检查config.local.json5中agent部分的timeoutSeconds设置是否太短。对于较复杂的任务或慢速模型可以适当调大比如设置为120。检查点4上下文过长如果对话历史很长AI处理速度会变慢。OpenMozi内置的上下文压缩功能会自动工作但你也可以手动在配置中调整agent的maxTokens或模型的contextWindow限制单次处理的长度。5.3 工具调用失败问题现象AI尝试调用bash或read_file等工具时失败。检查点1文件路径权限read_file,write_file等工具受限于运行OpenMozi进程的系统用户权限。确保该用户对目标文件/目录有读写权限。出于安全考虑不要以root身份运行服务。检查点2bash命令环境bash工具在子进程中执行命令。某些交互式命令或需要特定环境变量如PATH的命令可能执行失败。可以在技能或系统提示词中引导AI使用绝对路径命令如/usr/bin/git而不是git。检查点3工具参数AI有时会生成不符合工具参数要求的调用。查看日志中工具调用的具体参数检查是否格式错误。这通常需要优化你的系统提示词或技能描述更清晰地告诉AI某个工具该如何使用。5.4 技能未生效问题现象创建了SKILL.md文件但AI的回复似乎没有体现技能内容。检查点1技能加载路径确认SKILL.md文件放在了正确的目录用户级~/.mozi/skills/或工作区级./.mozi/skills/。检查配置文件skills.userDir和skills.workspaceDir是否正确。检查点2技能优先级与禁用列表检查配置中skills.disabled是否包含了你的技能名或者skills.only白名单是否没有包含它。同名技能工作区级的会覆盖用户级的。检查点3技能格式检查SKILL.md的YAML frontmatter 格式是否正确特别是三个短横线---不能少。Markdown正文内容是否清晰、无歧义。检查点4查看日志启动时日志会输出加载了哪些技能。使用mozi start --log-level info查看是否有相关加载日志或是否有格式错误警告。5.5 部署在Docker中无法持久化数据问题现象使用Docker运行重启容器后会话记录、记忆、定时任务都丢失了。原因Docker容器内的文件系统是临时的容器停止后数据就没了。解决方案必须使用Docker volume或绑定挂载bind mount将数据目录持久化到宿主机。# docker-compose.yml 关键部分 services: mozi: image: mozi-bot:latest volumes: - mozi-data:/home/mozi/.mozi # 使用命名volume # 或者使用绑定挂载 # - ./mozi-data:/home/mozi/.mozi volumes: mozi-data: # 声明volume这样~/.mozi目录下的所有数据config, sessions, memory, cron, skills, logs都会保存在宿主机上容器重启也不会丢失。5.6 性能优化与小技巧会话存储方式默认会话可能存储在内存中。对于长期运行的服务可以考虑配置为文件存储避免内存占用过高。查看src/sessions/下的代码了解如何配置不同的存储后端。模型降级备用在配置文件中可以配置多个模型提供商。当主模型如DeepSeek调用失败或超时时可以编写简单的故障转移逻辑可能需要修改插件或Agent初始化代码自动切换到备用模型如智谱AI。善用系统提示词除了Skills在agent.systemPrompt配置中设定的系统提示词是所有对话的基石。在这里定义AI的基础角色、行为准则和回复风格效果最为显著。监控与日志将~/.mozi/logs/目录下的日志接入到你的日志监控系统如ELK、Loki。关注错误日志和慢响应日志便于及时发现API异常或性能瓶颈。通过以上五个部分的拆解从设计理念、核心模块、实战配置、高级功能到问题排查你应该对OpenMozi有了一个全面而深入的理解。这个框架的精髓在于“够用且优雅”它没有追求大而全而是在国产生态这个细分场景下把核心体验做到了极致。无论是用于学习Agent架构还是快速搭建一个团队内部的智能助手它都是一个非常值得投入时间和精力的优秀项目。