企业官网建设流程全解析

ESP-Claw定时调度器实战：创建Scheduled任务让ESP32设备自动工作

【免费下载链接】esp-clawESP-Claw, a "Chat Coding" AI agent framework for IoT devices项目地址: https://gitcode.com/gh_mirrors/es/esp-claw

本文带你实战ESP-Claw 定时调度器（cap_scheduler）：只需一条对话指令，就能给 ESP32 设备创建 Scheduled 定时任务，实现"每天 8 点自动提醒""每 30 秒巡检一次"等自动化场景，无需写一行 C 代码。

为什么 ESP32 需要定时调度功能？

传统 IoT 设备只是"被动执行"——收到指令才动作。而 ESP-Claw 把 Agent Runtime 跑在 ESP32 芯片上，设备可以自主决定何时做什么。

调度器就是这个"自主性"的基石：它让设备按时间自动产生事件，配合事件路由系统，完成从"提醒→执行→通知"的完整闭环。

ESP-Claw 调度器的工作原理

理解一个核心设计：调度与执行分离。

• 调度器（cap_scheduler）：只负责"什么时候触发"，到点后向事件路由系统发布一个事件；
• 事件路由器（claw_event_router）：负责"触发后干什么"——发消息、唤醒 Agent、运行 Lua 脚本、调用能力接口等。

这种设计带来两大好处：

1. 灵活复用：同一条定时事件可以绑定任意动作，改动作不用改调度；
2. 状态可恢复：调度定义存在schedules.json，运行状态存在.state状态文件中，设备重启后不会丢任务、不会重复触发。

三种定时类型：once / interval / cron

💡 选型口诀：要"几点几分"用 cron，要"每隔多久"用 interval，只跑一次用 once。

注意：cron只支持 5 段式（分 时 日 月 周），字段形式仅限*、*/N或单个数字，不支持 6 段带秒写法。

实战：3 步创建第一个 Scheduled 任务

第 1 步：用对话或工具添加调度项

对设备说一句"每天早上 8 点提醒我看天气"，LLM 会自动调用scheduler_add创建调度项。你也可以通过 Web 配置页面 或控制台手动添加，核心就是一条 JSON：

{ "id": "daily_agent_check", "kind": "cron", "cron_expr": "0 8 * * *", "enabled": true, "event_type": "schedule", "event_key": "daily_agent_check", "text": "请查一下今天的天气，告诉我出门要注意什么" }

⚠️ 通过scheduler_add调用时，schedule_json必须传JSON 字符串（需转义），而不是嵌套对象——这是最常见的踩坑点。

第 2 步：验证调度项

调用scheduler_list查看全部调度项的运行状态（状态、上次触发时间last_fire_ms、运行次数run_count、漏跑次数missed_count一目了然）。

第 3 步：配置路由规则，决定触发后干什么

在router_rules.json中为这个事件添加动作规则，例如匹配到schedule事件后发送 IM 消息或唤醒 Agent：

{ "id": "handle_daily_check", "match": { "event_type": "schedule", "event_key": "daily_agent_check" }, "actions": [ { "type": "run_agent", "input": { "session_policy": "chat" } } ] }

支持的动作类型包括run_agent（唤醒 Agent）、send_message（发 IM 消息）、run_script（跑 Lua 脚本）、call_cap（调能力接口）等，定时任务的"手脚"全靠它。

时间同步：cron 任务不触发的常见原因

cron和once任务依赖系统时间，必须等 SNTP 时间同步成功后才会触发。设备刚上电时时钟可能不准，ESP-Claw 在首次同步成功后会调用cap_scheduler_handle_time_sync()做时间校准（rebase），自动修正参考时间点，避免漏跑或重复触发。

而interval任务若未设置起止时间，上电即开始计时，不依赖网络授时——断网也能跑。

常见问题速查

延伸阅读：源码与文档

• 调度器核心源码：cap_scheduler.c
• 头文件与 API 定义：cap_scheduler.h
• LLM 技能说明（含完整示例）：SKILL.md
• 路由规则技能说明：SKILL.md
• 官方参考文档：cap-scheduler.mdx

从"设备等你下指令"到"设备自己按时干活"，ESP-Claw 调度器 + 事件路由的组合，是打造 ESP32 边缘智能体最实用的自动化套件。🚀

【免费下载链接】esp-clawESP-Claw, a "Chat Coding" AI agent framework for IoT devices项目地址: https://gitcode.com/gh_mirrors/es/esp-claw