Zworker 技能#

概述#

zworker 是一个AI自动化任务的Electron应用，本技能提供与zworker应用交互的完整能力，包括：

• 同步用户信息：将OpenClaw的channel和userid同步到zworker
• 消息通知处理：获取zworker的通知并转发到指定用户
• 任务管理：获取、执行zworker任务
• 定时计划管理：获取、启用、关闭zworker的定时计划

所有操作通过zworker暴露的HTTP接口（ http://localhost:18803）完成，HTTP接口均以UTF-8的编码返回，因此你需要按UTF-8编码方式接收和输出数据。

快速开始#

前置条件#

1. zworker应用正在运行，HTTP服务监听在 http://localhost:18803
2. OpenClaw环境已配置好message工具，能够向各channel发送消息

核心功能#

1. 同步用户信息至zworker#

触发语句： 帮我调用zworker技能，同步用户信息至zworker、 帮我同步用户信息至zworker

工作流程：

1. 读取当前OpenClaw的openclaw.json文件中的channels字段，获取当前可用的channel以及该channel的userid（ 如果openclaw.json没有找到userid，你必须想尽办法拿到，拿不到就过滤掉该数据），把数据平铺得到 [{channel: 'xxx', userid: 'xxx'}, ...]，作为下一步的users参数，如果users数据里面存在不真实的userid，直接报错和终止流程
2. 调用 POST /control/setClawUserInfo 接口，把user信息同步到zworker，参数格式为 { users: [{channel: '', userid: ''}, ...] }
3. 调用 POST /control/setClawUserInfo 接口同步到zworker
4. 输出同步结果

输出：

• 成功： 已成功同步用户信息至zworker，请返回zworker继续操作。
• 失败： 用户信息同步失败 + 原因

2. 获取zworker消息并发送给指定用户#

触发语句： 帮我调用zworker技能，发送zworker的消息通知、 帮我获取并发送zworker的消息通知

工作流程：

1. 调用 GET /control/getClawMessage 接口， clawType 参数必须传入，且固定传入 QClaw，
2. 解析返回的 {channel: 'xxx', userid: 'xxx', message: 'xxx'}
3. 如果channel和message非空，使用message工具将消息发送到指定channel和userid
   • 如果userid为空，发送到该channel的默认绑定用户或最近聊天的用户
4. 输出发送的消息内容或错误信息

输出：

• 成功：输出message字段内容
• 失败： zworker消息获取/发送失败 + 原因

3. 获取zworker任务列表#

触发语句： 帮我调用zworker技能，获取zworker的任务列表、 帮我获取zworker的任务列表、 获取下一页zworker任务数据、 查找名称为[xxx]的zworker任务

工作流程：

1. 解析用户请求中的任务名称过滤条件和分页参数
2. 调用 GET /control/getTaskList 接口，传入 name、 pageNumber、 limit、 encodingMethod 参数，其中 encodingMethod 是当前调用接口的上下文编码，可传入 utf-8 或 gbk
3. 以下参数带有默认值： pageNumber=1、 limit=24
4. 严格按照输出格式输出任务ID和任务名称，任务名称已按 encodingMethod 进行编码
5. 如果还有下一页数据，提示可获取更多数据

输出格式：

text

- 任务A（任务ID：1）
- 任务B（任务ID：2）
...
当前仅返回前24条任务数，如果需要获取更多可以继续跟我说，比如：获取下一页数据

4. 执行zworker任务#

触发语句： 帮我调用zworker技能，执行id为[12312]的zworker任务、 帮我执行id为[12312]的zworker任务、 帮我执行名称为[xxx自动化执行]的zworker任务

工作流程：

1. 解析用户请求中的任务ID或名称
2. 调用 POST /control/runTask 接口，传入 id 或 name 参数
3. 检查返回的 success 字段

输出：

• 成功： 已成功触发任务执行
• 失败： 触发任务执行失败 + 原因

5. 获取zworker定时计划列表#

触发语句： 帮我调用zworker技能，获取定时计划列表、 帮我获取zworker的定时计划列表、 查找名称为[xxx]的zworker计划

工作流程：

1. 解析用户请求中的计划名称过滤条件和分页参数
2. 调用 GET /control/getScheduleList 接口，传入 name、 pageNumber、 limit、 encodingMethod 参数，其中 encodingMethod 是当前调用接口的上下文编码，可传入 utf-8 或 gbk
3. 以下参数带有默认值： pageNumber=1、 limit=24
4. 严格按照输出格式输出计划ID、计划名称、状态（已启动/未启动）
5. 如果还有下一页数据，提示可获取更多数据

输出格式：

text

- 计划A（计划ID：1，状态：已启动）
- 计划B（计划ID：2，状态：未启动）
...
当前仅返回前24条计划数，如果需要获取更多可以继续跟我说，比如：获取下一页数据

6. 启动zworker定时计划#

触发语句： 帮我调用zworker技能，启用id为[12321]的定时计划、 帮我启用id为[12321]的zworker定时计划、 帮我启动名称为[xxx]的计划

工作流程：

1. 解析用户请求中的计划ID或名称
2. 调用 POST /control/setSchedule 接口，传入 enable=1 和 id 或 name 参数
3. 检查返回的 success 字段

输出：

• 成功： 已成功启动定时计划
• 失败： 定时计划启动失败 + 原因

7. 关闭zworker定时计划#

触发语句： 帮我调用zworker技能，关闭id为[12321]的定时计划、 帮我关闭id为[12321]的zworker定时计划、 帮我关闭名称为[xxx]的计划

工作流程：

1. 解析用户请求中的计划ID或名称
2. 调用 POST /control/setSchedule 接口，传入 enable=0 和 id 或 name 参数
3. 检查返回的 success 字段

输出：

• 成功： 已成功关闭定时计划
• 失败： 定时计划关闭失败 + 原因

技术细节#

HTTP接口基础#

• 基础URL： http://localhost:18803
• 认证：当前无需认证（本地网络）
• 超时：建议设置5秒超时
• 错误处理：检查HTTP状态码和返回的 success 字段

接口规范#

详细接口定义见 references/api_endpoints.md

脚本使用#

本技能提供以下Python脚本，位于 scripts/ 目录：

1. zworker_api.py - 通用HTTP客户端，封装所有接口调用
2. sync_users.py - 同步用户信息到zworker
3. fetch_notifications.py - 获取并发送zworker消息通知
4. list_tasks.py - 获取任务列表（支持分页和过滤）
5. run_task.py - 执行任务（按ID或名称）
6. list_schedules.py - 获取定时计划列表（支持分页和过滤）
7. enable_schedule.py - 启用定时计划
8. disable_schedule.py - 关闭定时计划

配置与存储#

• 用户列表：通过OpenClaw的 cli、gateway 等工具获取当前channel和userid

故障排除#

1. 连接失败：检查zworker应用是否运行，端口18803是否可访问
2. 认证错误：当前无需认证，未来可能需要API密钥
3. 消息发送失败：检查目标channel是否配置正确，userid是否存在

注意事项#

1. 用户信息同步应在channel配置变更后执行
2. 消息通知功能依赖cron任务定期执行，也可手动触发
3. 所有HTTP接口为本地调用，确保网络环境安全
4. 所有HTTP接口均以UTF-8编码返回，确保网络环境安全