ZaloClaw：基于OpenClaw框架的Zalo个人账号AI代理插件开发指南

1. 项目概述ZaloClaw一个为OpenClaw打造的Zalo个人账号AI代理插件如果你在越南工作、生活或者你的业务与越南市场紧密相连那么Zalo这个名字对你来说一定不陌生。作为越南国民级的即时通讯应用Zalo拥有超过7500万的月活用户其渗透率之高使得它几乎成为了所有线上沟通的默认选择。然而与微信、Telegram等平台不同Zalo官方并未为个人账号提供公开、稳定的机器人API。这意味着如果你想通过自动化流程来处理客户咨询、管理社群消息或者构建一个基于Zalo的AI助手你将面临巨大的技术壁垒。ZaloClaw的出现正是为了解决这个痛点。它是一个专为OpenClaw框架设计的插件其核心使命是将你的个人Zalo账号无缝转变为一个功能齐全的AI智能体通道。简单来说它通过一个名为zca-js的第三方库模拟了Zalo客户端的行为从而绕过了官方API的限制让你能够以编程方式控制你的Zalo账号。这不仅仅是简单的“收发消息”它开放了多达147个精细化的API动作Actions涵盖了从基础的消息发送、好友管理、群组操作到高级功能如创建投票、设置提醒、管理产品目录等方方面面。想象一下这些场景一个AI客服7x24小时自动回复Zalo上的客户询盘一个社群助手自动管理群聊即答处理入群申请一个个人助理帮你自动整理Zalo聊天中的待办事项并设置提醒甚至是一个自动化营销工具根据规则向特定好友发送产品更新。ZaloClaw让这些场景从构想变为可编程的现实。它尤其适合开发者、运维工程师、跨境电商从业者以及任何希望将重复性、规则性的Zalo操作自动化的人士。无论你是想搭建一个简单的自动回复机器人还是一个复杂的、能调用多种工具完成工作流的AI AgentZaloClaw都提供了坚实的地基。2. 核心架构与设计思路拆解2.1 为什么选择“插件客户端模拟”的路径在官方API缺位的情况下实现Zalo自动化通常有几种思路逆向工程官方App协议、使用无头浏览器如Puppeteer模拟操作或者依赖第三方封装库。ZaloClaw选择了最后一种并在此基础上构建了面向AI Agent的抽象层。技术选型解析zca-js作为基石zca-js是一个非官方的Zalo客户端Node.js库它通过逆向工程实现了与Zalo服务器的通信协议。选择它作为底层依赖是基于以下几个考量协议稳定性相较于直接逆向不断变化的App协议zca-js作为一个中间层封装了复杂的登录、加密、请求构造逻辑提供了相对稳定的接口。功能覆盖度zca-js实现了Zalo客户端的大部分核心功能为ZaloClaw暴露147个Actions提供了可能。社区与维护虽然是非官方项目但zca-js有一定的活跃度Issues和更新能应对Zalo服务端的部分变更。OpenClaw插件化设计的优势ZaloClaw本身不作为独立应用运行而是作为OpenClaw的一个“通道”Channel插件。这种设计带来了显著好处生态集成直接复用OpenClaw的Agent编排、工具调用、记忆、知识库等核心能力。你的AI智能体可以同时连接Zalo、Telegram、Discord等多个平台实现统一调度。配置集中化所有通道和智能体的配置都集中在~/.openclaw/openclaw.json中管理清晰。生命周期托管插件的启动、停止、状态监控由OpenClaw框架负责开发者只需关注Zalo相关的业务逻辑。2.2 消息处理流程从Zalo到AI再返回理解消息流是掌握ZaloClaw工作原理的关键。整个过程可以被清晰地划分为几个阶段用户A在Zalo发送消息 ↓ Zalo服务器推送给zca-js客户端 ↓ zca-js触发事件 (如 onMessage) ↓ ZaloClaw monitor.ts 捕获事件 ├── 上下文提取解析消息是否为“回复”某条消息获取被引用的内容和发送者。 ├── 访问控制检查根据发送者ID、对话类型私聊/群聊、配置的dmPolicy/groupPolicy决定是否处理。 ├── Mention门控仅群聊检查是否配置了requireMention。如果为true且消息未机器人则消息会被“缓存”以备后续提及当前不予处理。 ├── 媒体处理如果消息带图片/文件且通过上述检查则启动下载将媒体文件临时存储并转换为可供AI模型理解的格式如Base64或文件路径。 ├── 上下文聚合将原始消息、发送者信息、缓存的上下文如前序未提及的消息、下载的媒体、引用信息等打包成一个结构化的“信封”Envelope。 ↓ 封装好的Envelope被发送至OpenClaw核心交由配置好的AI Agent处理 ↓ AI Agent分析意图可能调用zaloclaw工具中的某个Action如send-styled发送富文本或create-poll创建投票 ↓ Action调用请求返回至ZaloClaw send.ts ↓ send.ts调用对应的zca-js API方法执行操作如发送消息、修改群设置 ↓ 操作结果通过zca-js客户端发送至Zalo服务器 ↓ 用户A在Zalo客户端收到回复或看到操作生效这个流程中的每个环节都有其设计考量。例如“Mention门控”和“消息缓存”机制是为了避免在活跃的群聊中机器人响应每一条消息造成刷屏只在被明确时才参与对话同时又不丢失对话上下文。2.3 多账户与配置管理策略虽然当前版本主要针对单账户场景进行了优化和测试但其架构从设计上支持多账户。在配置文件中accounts对象可以包含多个命名的账户配置如default,account_b。配置的层次化覆盖ZaloClaw的配置系统非常灵活遵循“全局 - 群组 - 用户”的覆盖逻辑账户级配置定义基础的DM策略、群组策略、允许/拒绝列表。群组级覆盖在groups字段下可以为特定的群组ID或使用*作为默认配置设置独立的规则例如是否始终响应、允许哪些用户触发等。这让你可以为工作群、客户群、粉丝群设置不同的机器人行为。运行时动态修改通过group-mention、block-user-in-group等工具ActionAI Agent可以在运行时动态调整某个群组的配置实现自适应管理。凭证的安全存储登录Zalo后获得的Cookie等凭证信息被安全地存储在本地文件系统中通常位于~/.openclaw/data/plugins/zaloclaw/目录下。credentials.ts模块负责这些敏感信息的读写和加密如果配置了加密选项避免了在代码中硬编码凭证的风险。首次登录需要通过QR码扫码后续启动则会自动加载已存储的凭证实现静默登录直到凭证过期。3. 核心功能解析与实操要点3.1 丰富的工具集147个Actions详解与使用场景ZaloClaw将zca-js的能力封装成一个名为zaloclaw的单一工具ToolAI Agent通过指定action名称来调用具体功能。这147个Actions是插件的核心价值所在我们可以将其分为几个功能域来理解。消息与沟通域这是最常用的部分不仅支持发送纯文本还支持富文本样式加粗、斜体、下划线、删除线、颜色这通过将Markdown语法转换为Zalo支持的格式实现。urgency参数可以标记消息为重要或紧急在客户端有特殊展示。messageTtl参数理论上支持消息定时销毁但需要注意其依赖Zalo服务端实现可能不稳定更可靠的方式是使用set-auto-delete-chat在会话层面设置自动删除。注意发送文件send-file功能支持本地路径和URL。当使用本地路径时需确保OpenClaw服务进程有该文件的读取权限。对于大文件建议先上传到可公开访问的存储服务如云存储然后使用URL方式发送以避免进程内存问题和路径依赖。联系人、群组与社交管理域好友管理从搜索用户、发送/处理好友请求到管理好友昵称、查询在线状态实现了完整的社交链路自动化。find-user-by-username对于通过Zalo用户名而非手机号查找用户非常有用。群组管理功能极其全面涵盖创建、解散、成员增删、管理员任命、群链接管理、申请审核等。upgrade-group-to-community可以将普通群升级为“社群”获得更多管理功能。get-group-chat-history可用于备份或分析群聊记录。访问控制block-user/unblock-user是在插件层面阻止用户与机器人交互而zalo-block-user是在Zalo平台层面彻底拉黑用户两者用途不同需谨慎选择。内容与互动域投票Pollscreate-poll支持创建多选、匿名投票允许他人添加新选项并设置过期时间。这是进行群内调研、收集反馈的利器。提醒Reminders可以在特定会话中创建定时提醒支持重复设置。AI Agent可以借此实现简单的待办事项管理。快捷消息与自动回复quick-messages用于存储常用回复模板auto-replies可设置基于关键词或规则的自动回复适用于简单的客服场景。个人账户与资料域除了获取和更新个人资料、头像get-biz-account可以检查账号是否关联了企业认证信息。get-friend-board能获取Zalo的“朋友墙”信息用于社交分析。实操心得Action的调用模式在OpenClaw的Agent配置中你需要让AI模型知道它可以调用zaloclaw工具。通常这通过在Agent的system提示词或工具描述中说明来实现。一个典型的工具调用请求在OpenClaw的上下文中可能看起来像这样{ tool: zaloclaw, action: send, params: { to: 123456789, message: 您好这是AI助手发送的测试消息。, urgency: 1 } }关键在于AI模型需要根据对话上下文自行决定调用哪个Action并填充正确的参数。因此为AI提供清晰、结构化的工具描述文档如项目中的TOOLS.md至关重要。3.2 细粒度的访问控制与安全策略在开放自动化能力的同时ZaloClaw提供了一套细致的控制机制防止机器人滥用或骚扰。私聊DM策略open默认策略接受所有私聊。适合完全公开的客服机器人。pairing配对模式。当陌生人首次私聊时机器人会回复一个随机配对码用户需要回复此码才能开始对话。这有效防止了垃圾消息。allowlist白名单模式。只有allowFrom列表中指定的用户ID可以发起私聊。最适合内部工具或高权限管理。disabled禁用所有私聊。机器人仅在群组中工作。群组策略与Mention门控groupPolicy可设置为open响应所有群、allowlist仅响应指定群、disabled不响应任何群。requireMention这是群聊中最实用的功能。当设置为true时机器人会忽略所有未它的群消息。但它会“缓存”最近的消息可配置条数一旦被这些缓存的消息会作为上下文一并发送给AI使得对话连贯自然。这完美平衡了“随叫随到”和“避免刷屏”。用户级与群组级黑白名单除了全局的allowFrom和denyFrom你可以在每个群组的配置中单独设置allowUsers和denyUsers。这意味着你可以在一个公开群里只允许管理员与机器人交互。配置示例一个内部协作机器人的安全设置{ channels: { zaloclaw: { accounts: { default: { enabled: true, dmPolicy: allowlist, allowFrom: [manager_user_id_1, manager_user_id_2], groupPolicy: allowlist, groups: { internal_team_chat_id: { allow: true, requireMention: true, allowUsers: [] // 空数组表示允许所有群成员机器人 }, customer_support_group_id: { allow: true, requireMention: false, // 客服群自动响应所有消息 allowUsers: [support_staff_id_1, support_staff_id_2] } } } } } } }3.3 媒体处理与上下文增强ZaloClaw在消息处理上做了不少优化以提升AI Agent的理解和交互能力。智能图片下载与缓存当用户在群聊中发送图片时如果消息没有机器人图片不会被立即下载而是记录一个引用。只有当机器人被并需要处理相关上下文时才会触发下载。这节省了带宽和存储空间。下载的图片会被临时保存并以Base64编码或文件路径的形式提供给AI模型使其能够“看到”图片内容并进行视觉问答VQA或描述。引用回复Quote/Reply支持当用户“回复”某条特定消息时ZaloClaw能够捕获这一关系并将被回复消息的内容和发送者信息一并传递给AI。这使得AI能进行更精准的上下文对话例如回答“你刚才说的XX是什么意思”这类问题。已读回执与反应确认read-receipt功能可以自动将消息标记为已读。reaction-ack功能允许机器人在收到消息后自动添加一个反应如“心”或“赞”作为接收确认给用户即时反馈提升体验。4. 从零开始的完整部署与配置实战4.1 环境准备与依赖安装在开始之前请确保你的系统满足以下条件Node.js环境版本必须 22。建议使用nvmNode Version Manager来管理Node版本避免权限和版本冲突问题。# 使用nvm安装并切换至Node.js 22 nvm install 22 nvm use 22 node --version # 确认版本为 v22.x.xOpenClaw框架版本需 2026.2.0。请根据OpenClaw官方文档进行安装和基础配置。确保openclaw命令行工具可用。一个有效的Zalo个人账号用于扫码登录。建议使用一个专门用于自动化的账号避免对主账号造成影响。4.2 插件安装与链接我们通过Git克隆源码并进行本地链接安装便于后续开发和调试。# 1. 克隆仓库到本地目录建议放在OpenClaw工作目录附近 git clone https://github.com/monasprox/zaloclaw.git ~/projects/zaloclaw # 2. 进入插件目录并安装Node.js依赖 cd ~/projects/zaloclaw npm install # 此步骤会安装zca-js等所有依赖包。如果网络问题导致失败可尝试设置npm镜像或使用yarn。 # 3. 将插件以链接方式安装到OpenClaw openclaw plugins install --link ~/projects/zaloclaw # --link参数创建了一个符号链接OpenClaw会直接加载此目录的源码任何代码修改都会立即生效无需重新安装。 # 4. 重启OpenClaw网关服务以加载新插件 openclaw gateway restart # 等待几秒使用以下命令检查插件状态 openclaw status如果一切顺利你将在输出的通道列表里看到zaloclaw其状态可能为OFF未登录或ON已登录。4.3 首次登录与身份验证由于Zalo没有提供账号密码的API登录方式我们必须通过QR码扫码进行认证。# 在终端启动登录流程 openclaw channels login --channel zaloclaw执行上述命令后终端会显示一个QR码如果终端不支持图形会显示一个URL你可以打开URL查看二维码。此时打开你手机上的Zalo应用点击右上角的“”号选择“扫一扫”扫描终端上的二维码。扫描成功后手机Zalo会提示“确认登录网页版Zalo”点击确认。登录过程背后的原理zca-js库会模拟Zalo Web端的登录流程获取并保存登录后的会话凭证cookies。这些凭证被安全地存储在本地。首次登录后后续启动OpenClaw网关时插件会自动加载这些凭证实现静默登录直到Zalo使会话过期通常为数天或数周。4.4 深度配置详解与最佳实践安装登录后核心工作就是配置~/.openclaw/openclaw.json文件。下面是一个针对“企业内外部协同”场景的详细配置示例并附上每个关键项的解析。{ channels: { zaloclaw: { accounts: { default: { // 账户配置可配置多个如“work_account, personal_account enabled: true, // 【核心】私聊策略pairing模式在安全与便利间取得平衡 dmPolicy: pairing, // 配对模式下的初始欢迎语引导用户输入配对码 pairingMessage: 您好我是AI助手。如需与我对话请回复本次会话的配对码{pairingCode}, // 全局白名单公司管理员和IT支持人员可直接私聊 allowFrom: [admin_user_id_123, it_support_id_456], // 全局黑名单已知的骚扰账号 denyFrom: [spammer_id_789], // 【核心】群组策略默认只允许在白名单中的群组工作 groupPolicy: allowlist, // 消息样式将Markdown表格转换为带项目符号的列表兼容性更好 markdown: { tables: bullets }, // 在所有发送消息前添加前缀便于识别是机器人发送 messagePrefix: [Bot] , // 定义具体的群组规则 groups: { // “*” 是默认配置适用于所有未单独列出的群组如果groupPolicy是open *: { requireMention: true // 默认情况下在任何群都需要才响应 }, // 内部技术讨论群允许所有成员机器人用于技术问答 internal_tech_group_id_888: { allow: true, // 明确允许此群覆盖上层的allowlist requireMention: true, allowUsers: [] // 空数组表示允许所有成员 }, // 客户服务群仅客服专员可触发机器人且机器人自动响应所有消息 customer_service_group_id_999: { allow: true, requireMention: false, // 自动响应提高效率 allowUsers: [cs_agent_1_id, cs_agent_2_id] // 仅限客服人员 }, // 全员公告群完全禁用机器人避免干扰 company_announcement_id_777: { allow: false // 明确禁止在此群活动 } } } } } }, // 以下是OpenClaw Agent的配置示例展示如何让Agent使用zaloclaw工具 agents: { zalo_assistant: { model: openai:gpt-4, // 使用的AI模型 systemPrompt: 你是一个专业的Zalo助手可以帮用户发送消息、管理好友和群组、创建投票等。你可以使用zaloclaw工具来执行这些操作。在回复用户时请直接、友好。, tools: [zaloclaw] // 关键在此处声明启用zaloclaw工具 } } }配置要点解析pairingMessage这是一个未在基础配置表中列出但实际可用的参数。在dmPolicy为pairing时可以自定义发送给陌生人的初始消息{pairingCode}会被替换为实际的6位数字码。groups配置的优先级对于某个具体群组其最终行为由groupPolicy、groups.id.allow以及allowUsers/denyUsers共同决定规则从上到下应用后者覆盖前者。Agent配置关联务必在你使用的Agent配置中的tools数组里加入zaloclaw否则AI模型将无法调用该工具。5. 高级应用场景与故障排查实录5.1 构建自动化工作流案例拆解让我们设想一个跨境电商客服的场景并构建一个自动化工作流。场景客户在Zalo群中发送商品图片并问“这个有货吗”。AI助手需要识别图片中的商品。查询库存系统。用富文本格式回复库存情况并提问的客户。如果库存充足自动发送一个包含商品链接的快捷消息卡片。实现思路图像识别配置AI Agent的视觉能力如果模型支持或通过工具调用将图片发送到专门的图像识别API如CLIP向量数据库检索。库存查询编写一个自定义的OpenClaw工具如query-inventory连接你的内部数据库或ERP系统。组合调用在Agent的systemPrompt中明确其工作流程。当收到带图片的群消息时Agent应 a. 调用图像识别工具获取商品ID。 b. 调用query-inventory工具检查库存。 c. 根据结果调用zaloclaw的send-styledAction使用Markdown语法格式化回复如商品A库存15件并通过replyToMessageId参数实现引用回复。 d. 若库存10额外调用zaloclaw的send-linkAction发送商品详情页链接。这个流程展示了ZaloClaw如何作为“执行器”与AI的“决策大脑”及其他专业工具协同完成复杂任务。5.2 常见问题与解决方案速查表在实际部署和运行中你可能会遇到以下问题。这里提供一份快速排查指南。问题现象可能原因排查步骤与解决方案openclaw status显示 zaloclaw 为OFF或ERROR1. 插件未正确安装或链接。2. 登录凭证已过期。3.zca-js内部错误或网络问题。1. 运行openclaw plugins list确认zaloclaw在列表中且路径正确。2. 重新执行openclaw channels login --channel zaloclaw扫码登录。3. 查看OpenClaw日志~/.openclaw/logs/error.log寻找zca或zaloclaw相关的错误信息。扫码登录失败提示“二维码过期”或无效1. 终端显示QR码的字符画不清晰。2. 网络延迟导致二维码生成超时。3. Zalo账号有安全限制如新设备登录验证。1. 确保终端窗口足够大或使用支持直接显示图片的终端。命令有时会输出一个URL在浏览器中打开可看到清晰二维码。2. 尽快扫描通常在60秒内。重试命令。3. 尝试先在手机Zalo的“设置”-“账号安全”中检查是否有异常登录提醒或换一个常用设备登录过的账号。机器人不响应群消息1. 群组未在allowlist中或allow: false。2.requireMention为true但消息未机器人。3. 发送者在群组的denyUsers列表中。1. 检查配置文件中该群组的ID和allow设置。2. 确认消息中正确了机器人的Zalo账号显示名称。3. 检查群组配置中的allowUsers和denyUsers。可临时将requireMention设为false测试。发送消息失败提示“频率限制”或“发送失败”1. Zalo对个人账号的消息发送频率有严格限制。2. 消息内容可能触发了Zalo的反垃圾检测。1.这是最重要的限制务必为你的机器人加入延迟发送逻辑。可以在AI Agent的调用逻辑中或在send.ts中添加随机延迟如1-3秒。避免短时间内向多人或群发相同内容。2. 避免在消息中包含过多链接、敏感词汇或营销内容。丰富消息文本使其更像真人对话。AI Agent无法调用zaloclaw工具1. Agent配置中未添加zaloclaw工具。2. 工具调用的参数格式错误。3. Action名称拼写错误。1. 确认openclaw.json中对应Agent的tools列表包含zaloclaw。2. 参考TOOLS.md文档确保参数名、类型正确。例如to参数需要的是Zalo的数字ID而非用户名。3. 工具调用是大小写敏感的确认Action名称与文档完全一致如send-styled。媒体文件图片/文件发送失败1. 本地文件路径权限不足或不存在。2. URL不可访问或格式不被Zalo支持。3. 文件大小超过Zalo限制。1. 使用绝对路径并检查文件权限。2. 确保URL是公开可下载的。图片URL最好以.jpg,.png等常见格式结尾。3. Zalo对发送的文件有大小限制通常约20-30MB尝试压缩文件。会话无故断开需要频繁重新登录zca-js的会话Cookie过期或被Zalo服务器主动踢下线。这是客户端模拟方案的固有局限。确保运行ZaloClaw的设备网络稳定。可以考虑编写一个监控脚本定期检查状态并在检测到离线时自动触发重新登录流程需配合可自动扫码的方案如使用带屏幕的服务器或虚拟显示设备。5.3 性能优化与稳定性建议资源管理zca-js会维护一个浏览器实例或无头客户端。确保运行OpenClaw的服务器有足够的内存建议至少1GB可用内存。如果运行多个插件或Agent需相应增加资源。错误处理与重试在网络波动或Zalo服务暂时不可用时工具调用可能会失败。在构建AI工作流时应考虑增加重试机制特别是对于重要的发送消息操作。日志与监控充分利用OpenClaw的日志系统。将日志级别调整为DEBUG可以获取zca-js和ZaloClaw更详细的运行信息便于排查复杂问题。可以考虑将日志接入外部监控系统如ELK、Grafana。备份配置定期备份你的~/.openclaw/openclaw.json配置文件。在升级OpenClaw或ZaloClaw插件前尤其要做好备份。最后的经验之谈ZaloClaw是一个强大但依赖逆向工程稳定性的工具。它的优势在于提供了无与伦比的Zalo自动化深度。然而这也意味着当Zalo应用更新时底层zca-js库可能会暂时失效需要等待维护者更新。因此在将其用于关键业务流程时建议有一个备用的沟通方案如邮件或备用聊天平台并密切关注项目的GitHub仓库及时更新插件版本。对于绝大多数自动化、客服和社群管理任务只要合理设置频率限制和遵守平台规范它都能稳定、出色地工作。