opentask-client Skill
分布式任务管理系统，为 OpenClaw 容器分配和管理任务。
环境变量配置
必须在 OpenClaw 中配置以下环境变量：
| 变量 | 说明 |
|---|
OPENTASK_API_KEY | API 认证密钥（从服务端获取） |
OPENTASK_HOST | 服务地址（本地或容器地址） |
OPENTASK_BOT_NAME | 当前实例标识（可选，见下方说明） |
配置方式：
| 方式 | 文件 | 说明 |
|---|
| 本地实例 | ~/.openclaw/.env | 添加环境变量 |
| Docker 容器 | openclaw.json | env 配置块 |
| 临时使用 | shell 变量 | export 命令 |
🎯 如何获取实例标识 (assigned_to)
assigned_to 是任务分配的目标实例标识，有以下获取方式：
方式 1：OpenClaw Runtime 元数据（推荐）
OpenClaw 会自动注入 Runtime 信息到系统提示：
Runtime: agent=main | host=xxx | ...
Agent 值即为当前实例标识：
| Runtime agent | 说明 |
|---|
main | 主实例（主会话） |
{container_name} | Docker 容器实例 |
方式 2：环境变量（可选）
配置 OPENTASK_BOT_NAME 环境变量：
# .env 文件
OPENTASK_BOT_NAME=anna
方式 3：容器名推断（Docker）
根据容器名自动推断：
# 容器名 openclaw-anna → assigned_to=anna
# 容器名 openclaw-trump → assigned_to=trump
BOT_NAME=$(hostname | sed 's/openclaw-//')
方式 4：HEARTBEAT.md 配置
在 HEARTBEAT.md 中硬编码（适合固定环境）：
curl "$OPENTASK_HOST/api/tasks/pending?assigned_to=main"
服务信息
| 信息 | 值 |
|---|
| 服务地址 | $OPENTASK_HOST |
| API 前缀 | /api |
| 认证 Header | X-Bot-Key |
| API Key | $OPENTASK_API_KEY |
快速使用
获取待执行任务
# 使用 Runtime agent 值
curl -H "X-Bot-Key: $OPENTASK_API_KEY" \
"$OPENTASK_HOST/api/tasks/pending?assigned_to={agent}"
返回按优先级排序的任务 (P0 > P1 > P2)。
创建任务
curl -X POST -H "X-Bot-Key: $OPENTASK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"task_name":"任务名称","assigned_to":"{target}","priority":"P1","created_by":"{creator}"}' \
"$OPENTASK_HOST/api/tasks"
开始执行
curl -X PUT -H "X-Bot-Key: $OPENTASK_API_KEY" \
"$OPENTASK_HOST/api/tasks/{id}/start"
完成任务
curl -X PUT -H "X-Bot-Key: $OPENTASK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"result":"执行成功"}' \
"$OPENTASK_HOST/api/tasks/{id}/complete"
HEARTBEAT 集成
在 HEARTBEAT.md 中添加任务检查（使用通用模板）：
## 📋 OpenTask 任务检查
### 检查步骤
1. **获取待执行任务**
```bash
curl -s -H "X-Bot-Key: $OPENTASK_API_KEY" \
"$OPENTASK_HOST/api/tasks/pending?assigned_to=$OPENTASK_BOT_NAME" | python3 -m json.tool
-
有任务则执行
- 获取第一条任务 ID
- 调用
/api/tasks/{id}/start 开始执行
- 执行任务逻辑
- 完成后调用
/api/tasks/{id}/complete
-
无任务则 HEARTBEAT_OK
---
## priority 值
| 值 | 说明 |
|------|------|
| `P0` | 紧急（立即执行，阻塞其他任务） |
| `P1` | 重要（优先执行） |
| `P2` | 一般（有空时执行） |
---
## status 值
| 值 | 说明 |
|------|------|
| `pending` | 待执行 |
| `running` | 执行中 |
| `completed` | 已完成 |
| `failed` | 失败 |
| `cancelled` | 已取消 |
---
## 日志记录
每次状态变更都会写入 `bot_task_log` 表：
| 字段 | 说明 |
|------|------|
| `task_id` | 任务 ID |
| `action` | 操作类型 (start/complete/fail/retry/cancel) |
| `old_status` | 原状态 |
| `new_status` | 新状态 |
| `message` | 操作消息 |
| `operator` | 操作者 |
| `created_time` | 操作时间 |
---
## 完整 API 文档
详细 API 接口说明请参考 [api.md](references/api.md)。
---
## 使用示例
### 场景 1：HEARTBEAT 检查任务
```bash
# 从 Runtime 获取实例标识（假设 agent=main）
BOT_NAME="main"
# 获取待执行任务
TASKS=$(curl -s -H "X-Bot-Key: $OPENTASK_API_KEY" \
"$OPENTASK_HOST/api/tasks/pending?assigned_to=$BOT_NAME")
# 解析任务数量
COUNT=$(echo "$TASKS" | python3 -c "import sys,json; print(len(json.load(sys.stdin)))")
if [ "$COUNT" -gt 0 ]; then
echo "有 $COUNT 条待执行任务"
# 开始执行第一条任务
TASK_ID=$(echo "$TASKS" | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['id'])")
curl -X PUT -H "X-Bot-Key: $OPENTASK_API_KEY" "$OPENTASK_HOST/api/tasks/$TASK_ID/start"
else
echo "HEARTBEAT_OK"
fi
场景 2：创建并执行任务
# 1. 创建任务（分配给特定实例）
TARGET="anna"
TASK=$(curl -s -X POST -H "X-Bot-Key: $OPENTASK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"task_name":"发送问候","assigned_to":"'$TARGET'","priority":"P1"}' \
"$OPENTASK_HOST/api/tasks")
TASK_ID=$(echo "$TASK" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# 2. 目标实例开始执行（在其 heartbeat 时）
# 3. 完成任务
curl -X PUT -H "X-Bot-Key: $OPENTASK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"result":"问候已发送"}' \
"$OPENTASK_HOST/api/tasks/$TASK_ID/complete"
数据库表结构
OpenTask 使用以下数据库表（需在部署时创建）：
| 表名 | 说明 |
|---|
bot_task | 任务表 |
bot_task_log | 任务日志表 |
数据库连接信息由部署环境决定，不在此文档中硬编码。
