ClawHub

Zworker

Data & APIs

控制zworker AI自动化任务应用，支持任务管理、定时计划控制、用户信息同步和消息通知转发。当用户提到“zworker”关键词时使用此技能，例如：同步用户信息、获取任务列表、执行任务、管理定时计划、获取并发送通知等。技能通过HTTP接口与本地运行的zworker应用（localhost:18803）通信。

Install

openclaw skills install zworker

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. 如果还有下一页数据，提示可获取更多数据

输出格式：

- 任务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. 如果还有下一页数据，提示可获取更多数据

输出格式：

- 计划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编码返回，确保网络环境安全
More in Data & APIs