ESP-Claw 事件驱动自动化指南5 条 router_rules.json 规则实现自定义命令与秒级触发【免费下载链接】esp-clawESP-Claw, a Chat Coding AI agent framework for IoT devices项目地址: https://gitcode.com/gh_mirrors/es/esp-clawESP-Claw 是面向 IoT 设备的 AI Agent 框架它通过事件驱动机制让你无需重启设备就能用一份 router_rules.json 自定义命令规则实现 IM 指令秒级响应、定时任务自动执行和 Lua 脚本编排。本文带你从零理解 ESP-Claw 的事件路由原理手把手学会编写、调试和热加载你的第一条自动化规则。ESP-Claw 事件驱动架构为什么秒级触发不依赖大模型传统 IoT 应用里想让设备收到消息就亮灯往往要写死在 C 代码里改一次逻辑就得重新烧录。ESP-Claw 的解法是把所有消息统一抽象为Event事件再由Event Router事件路由器按 JSON 规则匹配执行。如图所示简单指令如感应灯、定时开关直接走L1 事件路由层毫秒级响应、零 LLM 开销只有模糊复杂指令才交给 LLM 思考器处理。这正是自定义命令能做到秒级触发的根本原因。核心组件一览组件职责源码位置claw_event_router事件调度器按规则匹配并执行动作components/claw_modules/claw_event_router/cap_router_mgr让 LLM 也能增删改查规则components/claw_capabilities/cap_router_mgr/cap_scheduler时间触发中心到点发布事件components/claw_capabilities/cap_scheduler/规则文件用户可编辑的自动化规则集application/edge_agent/fatfs_image/ 下的router_rules.jsonrouter_rules.json 快速上手读懂一条规则的 4 个字段规则文件位于设备存储的/fatfs/router_rules/router_rules.json是一个 JSON 数组。每条规则只需关心 4 个字段id规则唯一标识如im_session_commandmatch匹配条件决定什么事件命中这条规则actions命中后要执行的动作列表consume_on_match命中后是否吃掉事件阻止继续匹配后面的规则match中最常用的字段字段说明示例event_type事件类型必填message、trigger、scheduletext要匹配的文本默认精确匹配/sessiontext_match_rule设为prefix可匹配命令前缀用户发/run xxx也能命中/runsource_cap/chat_id按事件来源、聊天 ID 过滤claw_core完整字段定义参见官方 Schemarouter_rules.schema.json。最快配置方法用 prefix 匹配打造自定义命令想让设备支持/light on这样的自定义命令只需一条规则。match.text设为命令词并配合text_match_rule: prefix路由器会自动裁剪输入文本把命令后面的参数暴露为模板变量{{match.remainder}}{ id: run_script_command, match: { event_type: message, event_key: text, content_type: text, text: /run, text_match_rule: prefix }, actions: [ { type: run_script, input: { path: /fatfs/skills/runner/scripts/run.lua, args: { command: {{match.remainder}} } } } ] }事件驱动自动化实战6 种动作覆盖全部场景actions支持 6 种动作类型这是 ESP-Claw 自动化的全部武器库动作类型典型用途call_cap不经过大模型直接调用某个能力run_agent异步提交给 LLM Agent响应经out_message事件回流run_script运行 Lua 脚本适合轻量逻辑编排send_message向 IM 通道QQ/微信/飞书/Telegram发消息emit_event派生新事件串联多条规则形成事件链drop静默丢弃事件edge_agent 内置的规则集展示了典型用法im_any_message_agent把 IM 文本消息路由给 Agentagent_out_message_send_message再把 Agent 回复发回原会话两条规则首尾衔接构成完整的提问-回答闭环{ id: agent_out_message_send_message, consume_on_match: true, match: { source_cap: claw_core, event_type: out_message, content_type: text }, actions: [ { type: send_message, input: { channel: {{event.source_channel}}, chat_id: {{event.chat_id}}, message: {{event.text}} } } ] } 小技巧ack字段可在命中瞬间回一句确认消息让 IM 用户体验到秒回效果。定时调度 事件路由让设备自己到点干活cap_scheduler 是时间触发中心支持once一次性、interval间隔和cron5 段式表达式三种调度类型。它只负责到点发布事件具体行为仍由路由规则决定——这就是调度与执行分离的设计。以每天 7 点提醒为例需要两步第一步添加调度项schedules.json{ id: morning_reminder, kind: cron, cron_expr: 0 7 * * *, enabled: true, event_type: schedule, event_key: reminder, text: 早上好记得喝水。 }第二步添加匹配规则router_rules.json{ id: handle_morning_reminder, match: { event_type: schedule, event_key: reminder }, actions: [ { type: send_message, input: { channel: telegram, chat_id: YOUR_CHAT_ID, message: {{event.text}} } } ] }也可以直接在 Console 里操作无需编辑文件scheduler --add --json json # 新增调度项 scheduler --trigger id # 立即触发一次测试用 auto emit_trigger tester schedule reminder {ok:true} # 模拟一条定时事件调试与热加载auto 命令让规则修改即时生效改完规则不用重新烧录edge_agent提供两组功能等价的 Console 命令auto来自应用层event_router来自 cap_router_mgrauto reload # 修改后执行此命令规则立即生效 auto rules # 列出当前全部规则 auto add_rule json # 新增一条规则 auto last # 查看最近一次事件的处理统计auto last的输出是排错利器matchedtrue matched_rules1 action_count2 failed_actions0 route1 first_rule_idhandle-message重点关注matched是否命中、failed_actions失败动作数和last_error错误码。除了 Console还可以通过Web 配置页如上图的文件系统管理功能直接编辑router_rules.json改完记得执行auto reload使其生效。更妙的是ESP-Claw 的 LLM Agent 自身也注册了add_router_rule、update_router_rule、scheduler_add等工具——你甚至可以用自然语言让 Agent 帮你写规则每天早上 8 点提醒我打卡Agent 会自动调用调度与路由工具完成全部配置。常见问题规则不生效怎么排查命令没命中检查text是否精确匹配了用户输入。想匹配/light on和/light off需设text_match_rule: prefix动作失败run_script、send_message等动作的参数必须放在actions[*].input中而不是动作对象顶层规则数量受限达到上限时add_router_rule会返回错误先用auto rules检查现状定时任务不触发cron任务依赖 SNTP 时间同步成功设备上电时若时钟不准首次同步后调度器会自动校准不会重复或遗漏触发Agent 回复没发回 IM确认存在匹配out_message事件的send_message规则见上文示例总结ESP-Claw 的事件驱动架构把 IoT 自动化拆成了两层简单的积木router_rules.json定义什么事件触发什么动作——prefix 匹配打造自定义命令6 种动作覆盖从直连硬件到 LLM 调用的全部场景cap_scheduler定义什么时候触发——配合路由规则即可实现定时自动化整套机制热加载、可调试、可被 LLM 自维护让你的 ESP32 设备从此无需重新烧录就能持续进化。更多规则细节可查阅官方文档 docs/src/content/docs/zh-cn/reference-project/dataflow-and-automation.mdx 与 claw-event-router。【免费下载链接】esp-clawESP-Claw, a Chat Coding AI agent framework for IoT devices项目地址: https://gitcode.com/gh_mirrors/es/esp-claw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/8 18:47:37 · 阅读 1.2k ESP-Claw 事件驱动自动化指南：5 条 router_rules.json 规则实现自定义命令与秒级触发
ESP-Claw 事件驱动自动化指南5 条 router_rules.json 规则实现自定义命令与秒级触发【免费下载链接】esp-clawESP-Claw, a Chat Coding AI agent framework for IoT devices项目地址: https://gitcode.com/gh_mirrors/es/esp-clawESP-Claw 是面向 IoT 设备的 AI Agent 框架它通过事件驱动机制让你无需重启设备就能用一份 router_rules.json 自定义命令规则实现 IM 指令秒级响应、定时任务自动执行和 Lua 脚本编排。本文带你从零理解 ESP-Claw 的事件路由原理手把手学会编写、调试和热加载你的第一条自动化规则。ESP-Claw 事件驱动架构为什么秒级触发不依赖大模型传统 IoT 应用里想让设备收到消息就亮灯往往要写死在 C 代码里改一次逻辑就得重新烧录。ESP-Claw 的解法是把所有消息统一抽象为Event事件再由Event Router事件路由器按 JSON 规则匹配执行。如图所示简单指令如感应灯、定时开关直接走L1 事件路由层毫秒级响应、零 LLM 开销只有模糊复杂指令才交给 LLM 思考器处理。这正是自定义命令能做到秒级触发的根本原因。核心组件一览组件职责源码位置claw_event_router事件调度器按规则匹配并执行动作components/claw_modules/claw_event_router/cap_router_mgr让 LLM 也能增删改查规则components/claw_capabilities/cap_router_mgr/cap_scheduler时间触发中心到点发布事件components/claw_capabilities/cap_scheduler/规则文件用户可编辑的自动化规则集application/edge_agent/fatfs_image/ 下的router_rules.jsonrouter_rules.json 快速上手读懂一条规则的 4 个字段规则文件位于设备存储的/fatfs/router_rules/router_rules.json是一个 JSON 数组。每条规则只需关心 4 个字段id规则唯一标识如im_session_commandmatch匹配条件决定什么事件命中这条规则actions命中后要执行的动作列表consume_on_match命中后是否吃掉事件阻止继续匹配后面的规则match中最常用的字段字段说明示例event_type事件类型必填message、trigger、scheduletext要匹配的文本默认精确匹配/sessiontext_match_rule设为prefix可匹配命令前缀用户发/run xxx也能命中/runsource_cap/chat_id按事件来源、聊天 ID 过滤claw_core完整字段定义参见官方 Schemarouter_rules.schema.json。最快配置方法用 prefix 匹配打造自定义命令想让设备支持/light on这样的自定义命令只需一条规则。match.text设为命令词并配合text_match_rule: prefix路由器会自动裁剪输入文本把命令后面的参数暴露为模板变量{{match.remainder}}{ id: run_script_command, match: { event_type: message, event_key: text, content_type: text, text: /run, text_match_rule: prefix }, actions: [ { type: run_script, input: { path: /fatfs/skills/runner/scripts/run.lua, args: { command: {{match.remainder}} } } } ] }事件驱动自动化实战6 种动作覆盖全部场景actions支持 6 种动作类型这是 ESP-Claw 自动化的全部武器库动作类型典型用途call_cap不经过大模型直接调用某个能力run_agent异步提交给 LLM Agent响应经out_message事件回流run_script运行 Lua 脚本适合轻量逻辑编排send_message向 IM 通道QQ/微信/飞书/Telegram发消息emit_event派生新事件串联多条规则形成事件链drop静默丢弃事件edge_agent 内置的规则集展示了典型用法im_any_message_agent把 IM 文本消息路由给 Agentagent_out_message_send_message再把 Agent 回复发回原会话两条规则首尾衔接构成完整的提问-回答闭环{ id: agent_out_message_send_message, consume_on_match: true, match: { source_cap: claw_core, event_type: out_message, content_type: text }, actions: [ { type: send_message, input: { channel: {{event.source_channel}}, chat_id: {{event.chat_id}}, message: {{event.text}} } } ] } 小技巧ack字段可在命中瞬间回一句确认消息让 IM 用户体验到秒回效果。定时调度 事件路由让设备自己到点干活cap_scheduler 是时间触发中心支持once一次性、interval间隔和cron5 段式表达式三种调度类型。它只负责到点发布事件具体行为仍由路由规则决定——这就是调度与执行分离的设计。以每天 7 点提醒为例需要两步第一步添加调度项schedules.json{ id: morning_reminder, kind: cron, cron_expr: 0 7 * * *, enabled: true, event_type: schedule, event_key: reminder, text: 早上好记得喝水。 }第二步添加匹配规则router_rules.json{ id: handle_morning_reminder, match: { event_type: schedule, event_key: reminder }, actions: [ { type: send_message, input: { channel: telegram, chat_id: YOUR_CHAT_ID, message: {{event.text}} } } ] }也可以直接在 Console 里操作无需编辑文件scheduler --add --json json # 新增调度项 scheduler --trigger id # 立即触发一次测试用 auto emit_trigger tester schedule reminder {ok:true} # 模拟一条定时事件调试与热加载auto 命令让规则修改即时生效改完规则不用重新烧录edge_agent提供两组功能等价的 Console 命令auto来自应用层event_router来自 cap_router_mgrauto reload # 修改后执行此命令规则立即生效 auto rules # 列出当前全部规则 auto add_rule json # 新增一条规则 auto last # 查看最近一次事件的处理统计auto last的输出是排错利器matchedtrue matched_rules1 action_count2 failed_actions0 route1 first_rule_idhandle-message重点关注matched是否命中、failed_actions失败动作数和last_error错误码。除了 Console还可以通过Web 配置页如上图的文件系统管理功能直接编辑router_rules.json改完记得执行auto reload使其生效。更妙的是ESP-Claw 的 LLM Agent 自身也注册了add_router_rule、update_router_rule、scheduler_add等工具——你甚至可以用自然语言让 Agent 帮你写规则每天早上 8 点提醒我打卡Agent 会自动调用调度与路由工具完成全部配置。常见问题规则不生效怎么排查命令没命中检查text是否精确匹配了用户输入。想匹配/light on和/light off需设text_match_rule: prefix动作失败run_script、send_message等动作的参数必须放在actions[*].input中而不是动作对象顶层规则数量受限达到上限时add_router_rule会返回错误先用auto rules检查现状定时任务不触发cron任务依赖 SNTP 时间同步成功设备上电时若时钟不准首次同步后调度器会自动校准不会重复或遗漏触发Agent 回复没发回 IM确认存在匹配out_message事件的send_message规则见上文示例总结ESP-Claw 的事件驱动架构把 IoT 自动化拆成了两层简单的积木router_rules.json定义什么事件触发什么动作——prefix 匹配打造自定义命令6 种动作覆盖从直连硬件到 LLM 调用的全部场景cap_scheduler定义什么时候触发——配合路由规则即可实现定时自动化整套机制热加载、可调试、可被 LLM 自维护让你的 ESP32 设备从此无需重新烧录就能持续进化。更多规则细节可查阅官方文档 docs/src/content/docs/zh-cn/reference-project/dataflow-and-automation.mdx 与 claw-event-router。【免费下载链接】esp-clawESP-Claw, a Chat Coding AI agent framework for IoT devices项目地址: https://gitcode.com/gh_mirrors/es/esp-claw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考