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 Agent，ZaloClaw都提供了坚实的地基。

2. 核心架构与设计思路拆解

2.1 为什么选择“插件+客户端模拟”的路径？

在官方API缺位的情况下，实现Zalo自动化通常有几种思路：逆向工程官方App协议、使用无头浏览器（如Puppeteer）模拟操作，或者依赖第三方封装库。ZaloClaw选择了最后一种，并在此基础上构建了面向AI Agent的抽象层。

技术选型解析：zca-js作为基石zca-js是一个非官方的Zalo客户端Node.js库，它通过逆向工程实现了与Zalo服务器的通信协议。选择它作为底层依赖，是基于以下几个考量：

1. 协议稳定性：相较于直接逆向不断变化的App协议，zca-js作为一个中间层，封装了复杂的登录、加密、请求构造逻辑，提供了相对稳定的接口。
2. 功能覆盖度：zca-js实现了Zalo客户端的大部分核心功能，为ZaloClaw暴露147个Actions提供了可能。
3. 社区与维护：虽然是非官方项目，但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的配置系统非常灵活，遵循“全局 -> 群组 -> 用户”的覆盖逻辑：

1. 账户级配置：定义基础的DM策略、群组策略、允许/拒绝列表。
2. 群组级覆盖：在groups字段下，可以为特定的群组ID（或使用"*"作为默认配置）设置独立的规则，例如是否始终响应、允许哪些用户触发等。这让你可以为工作群、客户群、粉丝群设置不同的机器人行为。
3. 运行时动态修改：通过group-mention、block-user-in-group等工具Action，AI Agent可以在运行时动态调整某个群组的配置，实现自适应管理。

凭证的安全存储登录Zalo后获得的Cookie等凭证信息，被安全地存储在本地文件系统中（通常位于~/.openclaw/data/plugins/zaloclaw/目录下）。credentials.ts模块负责这些敏感信息的读写和加密（如果配置了加密选项），避免了在代码中硬编码凭证的风险。首次登录需要通过QR码扫码，后续启动则会自动加载已存储的凭证实现静默登录，直到凭证过期。

3. 核心功能解析与实操要点

3.1 丰富的工具集：147个Actions详解与使用场景

ZaloClaw将zca-js的能力封装成一个名为zaloclaw的单一工具（Tool），AI 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平台层面彻底拉黑用户，两者用途不同，需谨慎选择。

内容与互动域

• 投票（Polls）：create-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 环境准备与依赖安装

在开始之前，请确保你的系统满足以下条件：

1. Node.js环境：版本必须 >= 22。建议使用nvm（Node Version Manager）来管理Node版本，避免权限和版本冲突问题。

# 使用nvm安装并切换至Node.js 22 nvm install 22 nvm use 22 node --version # 确认版本为 v22.x.x

2. OpenClaw框架：版本需 >= 2026.2.0。请根据OpenClaw官方文档进行安装和基础配置。确保openclaw命令行工具可用。
3. 一个有效的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助手需要：

1. 识别图片中的商品。
2. 查询库存系统。
3. 用富文本格式回复库存情况，并@提问的客户。
4. 如果库存充足，自动发送一个包含商品链接的快捷消息卡片。

实现思路：

1. 图像识别：配置AI Agent的视觉能力（如果模型支持），或通过工具调用将图片发送到专门的图像识别API（如CLIP+向量数据库检索）。
2. 库存查询：编写一个自定义的OpenClaw工具（如query-inventory），连接你的内部数据库或ERP系统。
3. 组合调用：在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 常见问题与解决方案速查表

在实际部署和运行中，你可能会遇到以下问题。这里提供一份快速排查指南。

5.3 性能优化与稳定性建议

1. 资源管理：zca-js会维护一个浏览器实例或无头客户端。确保运行OpenClaw的服务器有足够的内存（建议至少1GB可用内存）。如果运行多个插件或Agent，需相应增加资源。
2. 错误处理与重试：在网络波动或Zalo服务暂时不可用时，工具调用可能会失败。在构建AI工作流时，应考虑增加重试机制，特别是对于重要的发送消息操作。
3. 日志与监控：充分利用OpenClaw的日志系统。将日志级别调整为DEBUG可以获取zca-js和ZaloClaw更详细的运行信息，便于排查复杂问题。可以考虑将日志接入外部监控系统（如ELK、Grafana）。
4. 备份配置：定期备份你的~/.openclaw/openclaw.json配置文件。在升级OpenClaw或ZaloClaw插件前，尤其要做好备份。

最后的经验之谈：ZaloClaw是一个强大但依赖逆向工程稳定性的工具。它的优势在于提供了无与伦比的Zalo自动化深度。然而，这也意味着当Zalo应用更新时，底层zca-js库可能会暂时失效，需要等待维护者更新。因此，在将其用于关键业务流程时，建议有一个备用的沟通方案（如邮件或备用聊天平台），并密切关注项目的GitHub仓库，及时更新插件版本。对于绝大多数自动化、客服和社群管理任务，只要合理设置频率限制和遵守平台规范，它都能稳定、出色地工作。