OpenClaw Zalo Personal 渠道
即时通讯
中等
使用非官方 zca-cli 工具将 OpenClaw 连接到你的 Zalo 个人账号。与 Zalo Bot Platform 集成不同，此渠道让你的 AI 助手通过真实的 Zalo 个人账号运行——支持群聊、媒体和好友列表。通过扫描二维码进行身份验证，就像关联新设备一样简单。
快速信息
难度中等
分类即时通讯
支持功能数3 / 6
Zalo Personal 支持的功能
文本消息
支持
媒体与文件
支持
消息反应
不支持
消息线程
不支持
语音消息
不支持
群聊
支持
Zalo Personal 前置条件
- 一个 Zalo 个人账号（标准账号，非 Official Account）
- 已安装 zca 二进制文件并可在系统 PATH 中访问
- OpenClaw Gateway 已运行并配置完成
- Zalo 手机应用用于登录时扫描二维码
Zalo Personal 快速设置
1
安装 zalouser 插件和 zca-cli
使用 'openclaw plugins install @openclaw/zalouser' 安装 OpenClaw 插件。然后安装 zca-cli 工具并确保它在 PATH 中。通过 'zca --version' 验证安装。
2
通过二维码登录
运行 'openclaw channels login --channel zalouser' 在终端显示二维码。打开手机上的 Zalo 应用，扫描二维码完成身份验证。
3
配置并开始聊天
将 zalouser 渠道配置添加到 ~/.openclaw/openclaw.json，设置你偏好的 dmPolicy 和 groupPolicy。使用 'openclaw start' 启动 Gateway，然后向你的 Zalo 账号发送消息进行测试。
Zalo Personal 配置示例
config.json
{
"channels": {
"zalouser": {
"enabled": true,
"dmPolicy": "pairing",
"groupPolicy": "open"
}
}
}Zalo Personal 深入了解
架构概览
OpenClaw 通过 zca-cli 工具连接到 Zalo——这是一个用于 Zalo 个人账号的非官方命令行客户端。与 Zalo Bot Platform 集成（使用 HTTP API）不同，此渠道使用 zca 二进制文件监听入站消息并发送出站回复。
Gateway 在后台运行 'zca listen' 进程实时接收消息，并使用 'zca msg' 发送回复。这种方式完全在本地运行——无需公网 URL、Webhook 或 HTTPS 证书。
因为使用的是个人账号，Bot 可以参与群聊、访问好友列表、发送媒体——这些功能在官方 Bot Platform 上不可用。
这是一个非官方集成。使用它可能导致 Zalo 暂停或封禁账号。建议使用专用账号而非主要个人账号。
zca-cli 工具处理协议层。请保持更新以维持与 Zalo 服务的兼容性。
这是一个使用非官方工具的实验性集成。Zalo 可能会暂停或封禁使用第三方自动化的账号。使用风险自负。
安装 zca-cli
zca-cli 二进制文件是此渠道的前置依赖。它必须安装并在系统 PATH 中可访问，Gateway 才能使用 Zalo Personal 渠道。
安装后，在终端运行 'zca --version' 验证是否正常工作。如果命令未找到，请检查 PATH 配置或重新安装。
terminal
zca --version如果 zca 已安装但不在 PATH 中，可以在 shell 配置文件（~/.bashrc、~/.zshrc 等）中将其目录添加到 PATH。
二维码身份验证
身份验证通过用 Zalo 手机应用扫描二维码完成——类似于关联新设备。无需 API Token 或 Bot Token。
运行登录命令在终端显示二维码。打开手机上的 Zalo，导航到二维码扫描器，扫描二维码。会话将建立并在本地保存凭证。
如果登录在重启后不持久，尝试先登出再重新登录以刷新会话。
terminal
# 登录
openclaw channels login --channel zalouser
# 如果登录不持久，重新验证
openclaw channels logout --channel zalouser
openclaw channels login --channel zalouser扫描二维码时保持手机联网。会话通过 Zalo 服务器验证。
私聊策略
私聊策略控制谁可以通过私信与你的 AI 助手互动。OpenClaw 支持四种策略：
• pairing（默认）— 新联系人首次发消息时收到配对码。通过 'openclaw pairing approve zalouser <code>' 批准。配对码在 1 小时后过期。
• allowlist — 只有 allowFrom 列表中的用户 ID 或名称可以与 Bot 交互。名称通过 'zca friend find' 解析为 ID。
• open — 任何向该账号发消息的人都会收到回复。
• disabled — 完全关闭私聊处理。
openclaw.json
{
"channels": {
"zalouser": {
"dmPolicy": "allowlist",
"allowFrom": ["123456789", "好友名称"]
}
}
}'open' 策略允许任何人与你的个人账号互动。由于这是一个对你的联系人可见的真实 Zalo 账号，请谨慎使用。
群聊管理
与 Zalo Bot Platform 集成不同，Zalo Personal 完全支持群聊。默认情况下，groupPolicy 设置为 'open'，意味着 Bot 会在所有群聊中响应。
你可以使用 'allowlist' 策略配合 groups 映射来限制群聊访问。群组可以通过数字 ID 或名称引用。
将 groupPolicy 设为 'disabled' 可完全忽略所有群消息。
openclaw.json
{
"channels": {
"zalouser": {
"groupPolicy": "allowlist",
"groups": {
"123456789": { "allow": true },
"工作群": { "allow": true }
}
}
}
}使用 'openclaw directory groups list --channel zalouser --query "名称"' 查找群组 ID 和名称。
群组名称区分大小写。请使用 Zalo 应用中显示的准确名称。
消息处理
OpenClaw 支持通过 Zalo Personal 发送文本消息、图片、文件和链接。文本消息会在约 2,000 个字符处自动分段，以符合 Zalo 客户端限制。
来自联系人和群组的入站消息通过 'zca listen' 进程接收并转发给 AI。出站回复使用 'zca msg' 发送。
由于字符限制，流式响应默认被阻止。
较长的 AI 回复会自动在约 2,000 字符边界处拆分为多条消息。
媒体发送能力取决于已安装的 zca-cli 版本。请保持更新以获得最佳兼容性。
多账号设置
OpenClaw 支持同时运行多个 Zalo 个人账号，通过映射到不同的 zca 配置文件实现。每个账号有自己的配置文件名、私聊策略和群聊设置。
如果你想为不同用途运行独立的 AI 助手（例如工作账号和个人账号），这非常有用。
openclaw.json
{
"channels": {
"zalouser": {
"enabled": true,
"defaultAccount": "default",
"accounts": {
"work": {
"enabled": true,
"profile": "work"
},
"personal": {
"enabled": true,
"profile": "personal"
}
}
}
}
}通讯录与发现
Zalo Personal 渠道提供通讯录命令，用于发现账号上的好友和群组。这些命令对于查找用户 ID（用于白名单）或群组 ID（用于群聊策略）非常有用。
你可以查看自己的资料、按名称搜索好友、按名称搜索群组——全部通过命令行完成。
terminal
# 查看你的资料
openclaw directory self --channel zalouser
# 搜索好友
openclaw directory peers list --channel zalouser --query "名称"
# 搜索群组
openclaw directory groups list --channel zalouser --query "工作"Zalo Personal 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | false | 启用或禁用 Zalo Personal 渠道 |
| dmPolicy | string | "pairing" | 控制谁可以私聊 Bot。选项：pairing、allowlist、open、disabled |
| allowFrom | string[] | [] | 允许与 Bot 交互的用户 ID 或名称列表（当 dmPolicy 为 allowlist 时使用） |
| groupPolicy | string | "open" | 控制群聊行为。选项：open、allowlist、disabled |
| groups | object | {} | 群组 ID 或名称到权限对象的映射（当 groupPolicy 为 allowlist 时使用） |
| defaultAccount | string | "default" | 默认使用的 zca 配置文件名称 |
| accounts.<id>.enabled | boolean | true | 在多账号模式下启用或禁用特定账号 |
| accounts.<id>.profile | string | "" | 特定账号的 zca 配置文件名称 |
enabled
Type: booleanDefault: false
启用或禁用 Zalo Personal 渠道
dmPolicy
Type: stringDefault: "pairing"
控制谁可以私聊 Bot。选项：pairing、allowlist、open、disabled
allowFrom
Type: string[]Default: []
允许与 Bot 交互的用户 ID 或名称列表（当 dmPolicy 为 allowlist 时使用）
groupPolicy
Type: stringDefault: "open"
控制群聊行为。选项：open、allowlist、disabled
groups
Type: objectDefault: {}
群组 ID 或名称到权限对象的映射（当 groupPolicy 为 allowlist 时使用）
defaultAccount
Type: stringDefault: "default"
默认使用的 zca 配置文件名称
accounts.<id>.enabled
Type: booleanDefault: true
在多账号模式下启用或禁用特定账号
accounts.<id>.profile
Type: stringDefault: ""
特定账号的 zca 配置文件名称
Zalo Personal 常见问题
Zalo Personal 故障排查
找不到 zca 命令
zca-cli 二进制文件未安装或不在系统 PATH 中。
安装 zca-cli 并确保它在 PATH 中。通过 'zca --version' 验证。如果已安装但找不到，将安装目录添加到 ~/.bashrc 或 ~/.zshrc 的 PATH 中。
二维码登录失败或会话不持久
Zalo 会话可能已过期或初始认证未完成。
尝试先登出再重新登录：'openclaw channels logout --channel zalouser' 然后 'openclaw channels login --channel zalouser'。确保扫描二维码时手机网络连接稳定。
Bot 不响应群消息
groupPolicy 可能设置为 'disabled' 或 'allowlist' 但该群未列入。
检查 groupPolicy 设置。如果使用 'allowlist'，确保群组 ID 或名称已在 groups 配置中列出。使用 'openclaw directory groups list --channel zalouser' 查找正确的群组 ID。
收不到消息
zca listen 进程可能未运行，或会话已过期。
运行 'openclaw channels status --probe' 诊断连接。如果会话已过期，通过二维码重新登录。检查 Gateway 日志获取具体错误信息。
账号被暂停或封禁
Zalo 检测到账号上的非官方自动化行为。
这是使用非官方集成的已知风险。联系 Zalo 客服尝试恢复账号。考虑切换到官方 Zalo Bot Platform 集成（zalo 渠道），虽然不支持群聊，但没有封号风险。