opentask-client（开放任务客户端）

opentask-client Skill

分布式任务管理系统，为 OpenClaw 容器分配和管理任务。

环境变量配置

必须在 OpenClaw 中配置以下环境变量：

配置方式：

🎯 如何获取实例标识 (assigned_to)

assigned_to 是任务分配的目标实例标识，有以下获取方式：

方式 1：OpenClaw Runtime 元数据（推荐）

OpenClaw 会自动注入 Runtime 信息到系统提示：

Runtime: agent=main | host=xxx | ...

Agent 值即为当前实例标识：

方式 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"

服务信息

快速使用

获取待执行任务

# 使用 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. **获取待执行任务**

curl -s -H "X-Bot-Key: $OPENTASK_API_KEY" \ "$OPENTASK_HOST/api/tasks/pending?assigned_to=$OPENTASK_BOT_NAME" | python3 -m json.tool

2. **有任务则执行**
   - 获取第一条任务 ID
   - 调用 `/api/tasks/{id}/start` 开始执行
   - 执行任务逻辑
   - 完成后调用 `/api/tasks/{id}/complete`

3. **无任务则 HEARTBEAT_OK**

priority 值

status 值

日志记录

每次状态变更都会写入 bot_task_log 表：

完整 API 文档

详细 API 接口说明请参考 api.md。

使用示例

场景 1：HEARTBEAT 检查任务

# 从 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 使用以下数据库表（需在部署时创建）：

数据库连接信息由部署环境决定，不在此文档中硬编码。