scheduler

name	scheduler
description	管理 OmniClaw 定时任务，支持创建、修改、删除定时推送任务

Scheduler 定时任务管理

概述

OmniClaw 的定时任务存放在工作区根目录的 schedules/ 目录下，每个任务一个独立的 .json 文件。 Bot 会实时监听该目录的变化，保存文件后约 300ms 自动热加载，无需重启。

• 新增文件：自动注册并开始调度
• 修改文件：自动用新配置替换旧任务
• 删除文件：自动停止并移除对应调度

文件格式

文件名建议与 id 保持一致，例如 schedules/morning-market.json：

{
  "id": "唯一任务ID",
  "cron": "0 9 * * 1-5",
  "prompt": "发给 opencode 执行的任务指令",
  "gateway": "feishu",
  "receiver": {
    "type": "chat_id",
    "id": "接收方的ID"
  }
}

字段说明

字段	必填	说明
id	✅	任务唯一标识，英文字母+连字符，不能重复
cron	✅	5段标准 cron 表达式，时区为 Asia/Shanghai
prompt	✅	触发时发给 opencode 执行的完整指令
gateway	✅	发送平台：feishu / telegram / terminal
receiver.type	✅	接收方类型（见下表）
receiver.id	⚠️	接收方的 ID 值（terminal 网关可为空，其他必填）

receiver.id 默认规则

创建任务时，默认将推送目标设为请求人所在的当前会话（群/频道）。

Brain 会在每条消息前自动注入 Sender Context，包含 gateway、session_id（当前群/会话）、sender_id（发送者个人 ID）。创建 schedule 文件时：

• gateway → 默认填写请求来源网关（如 feishu）
• receiver.type → 默认 chat_id
• receiver.id → 默认填写当前会话 ID（session_id，即请求所在的群/频道）
• 用户明确指定其他接收人时 → 以用户指定为准

receiver.type 取值

type	含义
chat_id	飞书群聊
open_id	飞书用户（open_id）
user_id	飞书用户（user_id）

cron 表达式格式

┌─ 分钟 (0-59)
│ ┌─ 小时 (0-23)
│ │ ┌─ 日 (1-31)
│ │ │ ┌─ 月 (1-12)
│ │ │ │ ┌─ 星期 (0-7，0和7都是周日)
│ │ │ │ │
* * * * *

常用示例：

cron	含义
0 9 * * 1-5	工作日早上 9:00
30 18 * * 1-5	工作日下午 18:30
0 9 * * 1	每周一早上 9:00
0 8 * * *	每天早上 8:00
0 */2 * * *	每2小时整点

操作示例

创建新定时任务

用户说：「每个工作日早上9点推送快手股价到飞书群 oc_xxx」

操作：在 schedules/ 目录下创建 daily-kuaishou-stock.json：

{
  "id": "daily-kuaishou-stock",
  "cron": "0 9 * * 1-5",
  "prompt": "使用长桥API查询快手(01024.HK)的最新行情，包括现价、涨跌幅、成交量，生成简洁的每日早报。",
  "gateway": "feishu",
  "receiver": {
    "type": "chat_id",
    "id": "oc_xxx"
  }
}

删除定时任务

用户说：「删除 daily-kuaishou-stock 这个定时任务」

操作：删除 schedules/daily-kuaishou-stock.json 文件。

修改定时任务

用户说：「把早报改成早上8点发」

操作：编辑 schedules/daily-kuaishou-stock.json，将 cron 改为 "0 8 * * 1-5"，保存。

查看所有定时任务

操作：列出并展示 schedules/ 目录下所有 .json 文件的内容。

立即触发测试（不等 cron 时间）

用户说：「测试一下 daily-kuaishou-stock 这个定时任务」/ 「立即执行一次这个任务看看效果」

操作：通过 Trigger API 立即执行该任务一次（结果会推送到任务配置的原始接收方）：

curl -s -X POST http://127.0.0.1:3099/trigger/daily-kuaishou-stock

返回示例：

• {"ok":true} → 触发成功，任务已在后台执行，结果将发送到任务配置的 receiver
• {"ok":false,"error":"Schedule \"...\" not found"} → 任务 ID 不存在，检查 schedules/ 目录下文件名与 id 字段是否一致

Trigger API 端口默认为 3099，可通过环境变量 TRIGGER_PORT 修改。每条消息的 Sender Context 中会注明当前实际端口。

注意事项

1. id 字段必须唯一，与文件名保持一致（{id}.json）
2. receiver.id 非 terminal 网关必须填写，否则任务会被跳过；默认填写请求人的 ID
3. 文件保存后约 300ms 自动热加载，无需重启 Bot
4. prompt 写得越具体，执行结果越准确；建议指明数据来源（如长桥API）、输出格式、目标对象