OpenClaw 自动化与扩展：cron、hooks、Nodes、Skill 与 Plugin

先用这张决策表

你想做什么	优先选择	为什么
每天 9 点发提醒或检查报告	cron / Scheduled tasks	时间驱动，Gateway 负责持久化和运行历史
每 15 分钟跑一次队列探针	cron command payload	确定性脚本，不必启动模型对话
/new 后保存上下文或写日志	internal hooks	Gateway 内部命令事件触发
消息发送后同步一份审计日志	internal hooks	message:sent 属于内部事件
阻止某个工具调用或改写提示	plugin hooks	需要运行时策略、优先级和拦截语义
Gmail、GitHub、监控系统推送事件	webhook / mapped hooks	外部系统主动发 HTTP 请求
浏览器网页登录后做周期检查	cron + Browser	但必须先处理登录态和人工边界

如果你只能先记一条：定时用 cron，内部副作用用 hooks，外部推送用 webhook，运行时拦截用 plugin hooks。

cron 适合什么

官方 Scheduled tasks 文档把 cron 描述为 Gateway 内置调度器。它会持久化 jobs、运行状态和历史记录；重启后不会因为内存丢失而忘记任务。

适合 cron 的任务：

• 每天汇总站点数据、工单、告警或日志。
• 每小时检查一个公开状态页或队列长度。
• 在固定时间提醒用户处理审批。
• 周期性运行一个确定性脚本，并把结果发到聊天渠道或 webhook endpoint。
• 给长期助手一个固定节奏的后台检查。

不适合 cron 的任务：

• 外部事件一发生就要立刻响应。
• 需要拦截工具调用、阻止消息或修改运行时策略。
• 每次都依赖人工登录、验证码或不可预测网页状态。
• 失败后无法被看到，也没人负责处理。

示例：确定性队列探针更适合 command payload，而不是模型对话。

openclaw cron create "*/15 * * * *" \
  --name "Queue depth probe" \
  --command "scripts/check-queue.sh" \
  --command-cwd "/srv/app" \
  --announce \
  --channel telegram \
  --to "-1001234567890"

这个任务回答的是“每 15 分钟执行脚本并回报结果”。如果你把它写成“让 Agent 想办法看看队列”，反而更不稳定。

hooks 适合什么

官方 hooks 文档把 internal hooks 定义为 Gateway 内部发生某些事件时运行的小脚本。典型事件包括：

• command:new
• command:reset
• command:stop
• session:compact:before
• session:compact:after
• agent:bootstrap
• gateway:startup
• gateway:shutdown
• gateway:pre-restart
• message:received
• message:transcribed
• message:preprocessed
• message:sent

它适合做“事件后的副作用”，例如：

• /new 后保存一份 session 摘要。
• /reset 后写审计日志。
• gateway:pre-restart 时给当前会话发短通知。
• message:sent 后同步一份轻量 telemetry。
• agent:bootstrap 前注入工作区额外文件。

internal hooks 不适合做复杂策略拦截。如果你要重写 prompt、阻止工具、取消外发消息或加 middleware，应看 plugin hooks，而不是把逻辑塞进文件式 hook。

webhook 适合什么

webhook 适合“外部系统知道发生了什么，并希望通知 OpenClaw”。

常见例子：

• GitHub issue / PR 事件推送给 OpenClaw。
• 监控系统发现异常，请 OpenClaw 生成排查摘要。
• Gmail PubSub 触发 inbox 检查。
• 自有业务系统把订单、工单、告警推给 OpenClaw。

官方 Scheduled tasks 文档里的 hook endpoint 设计强调了几条安全边界：

• 请求应带 Authorization: Bearer <token> 或 x-openclaw-token。
• query-string token 会被拒绝。
• hook endpoint 应放在 loopback、tailnet 或可信反向代理后面。
• 使用专用 hook token，不要复用 Gateway auth token。
• 限制 hooks path、allowed agent IDs 和 session key 形态。
• payload 默认需要安全边界包装。

这说明 webhook 的重点不是“能不能接 HTTP”，而是“谁能触发、能触发哪个 agent、触发后能影响什么”。

/hooks/wake 和 /hooks/agent 怎么理解

官方文档把外部触发分成两个常见方向：

endpoint	适合场景	结果
POST /hooks/wake	给 main session 放入一个系统事件	像提醒或轻量通知，进入主会话 wake 流
POST /hooks/agent	运行一个 isolated agent turn	更适合外部系统触发一次独立任务

如果只是“新邮件到了，请提醒我看”，wake 更自然。如果是“监控告警来了，请单独分析这条告警并回传结果”，agent 更像合适入口。

最小请求形态可以这样理解：

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email"}'

这只是示意。生产环境里还要处理网络边界、token 轮换、agent 限制、timeout、失败通知和日志。

和 Browser 自动化怎么组合

Browser 很容易和 automation 结合，但也最容易出事故。

适合后台化的 Browser 任务：

• 打开公开状态页，截图留证。
• 进入测试账号后台，读取只读指标。
• 检查文档站、价格页、页面可用性。
• 运行一个不涉及登录态的网页 smoke check。

不适合直接后台化的 Browser 任务：

• 每次都需要验证码或 2FA。
• 依赖个人真实 session，且运行时无人值守。
• 会发布、删除、付款、导出客户数据。
• 失败后会重复提交表单或触发风控。

如果你的任务依赖 Browser，先看 OpenClaw Browser 工具 和 Browser 登录流，再决定是否进入 cron。

上线前安全清单

每条自动化上线前，至少检查这些项：

• 触发源：时间、内部事件、外部 HTTP、插件策略，是否选对。
• 权限范围：能触发哪个 agent、哪个 session、哪些工具、哪些网页。
• 认证方式：hook token 是否专用，是否避免 query token，是否有轮换方式。
• 网络边界：endpoint 是否只在 loopback、tailnet 或可信代理后面。
• 失败可见性：错误会发到哪里，谁看到，多久处理。
• 停止方式：如何 disable job、remove hook、撤销 token 或关闭入口。
• 回滚策略：自动化做错时，业务侧如何恢复。
• 审计记录：谁创建，为什么创建，最后一次验证是什么时候。

自动化越靠近生产环境，越要像运维系统一样管理，而不是像临时 prompt 一样管理。

常见坑

• 把所有任务都塞进 cron，导致事件来了也只能等下一轮轮询。
• 把 internal hooks 当成 plugin policy hook，用错拦截面。
• webhook endpoint 暴露到公网，却没有可信代理、专用 token 或 agent 限制。
• query string 里放 token，泄露到日志和浏览器历史。
• cron 失败没有通知，长期以为任务在正常运行。
• 后台 Browser 任务依赖个人登录态，但执行时无人处理验证码和风控。
• 自动化没有 owner，出问题时没人知道该停哪一条 job。

排错顺序

自动化不按预期运行时，按这个顺序排查：

1. 触发是否发生：cron 是否 due，hook 事件是否被 Gateway 看到，webhook 请求是否到达。
2. 入口是否启用：hooks 是否 enabled，cron job 是否 enabled，plugin hook 是否安装并加载。
3. 认证是否通过：token、path、allowedAgentIds、session key 限制是否挡住了请求。
4. 运行上下文是否正确：main、isolated、current、custom session 是否符合任务需求。
5. 执行结果是否可见：run history、background task、chat delivery 或 webhook delivery 是否有记录。
6. 业务动作是否越界：如果自动化卡在 Browser、审批或外部 API，可能是风险边界设计正确地把它挡住了。

OpenClaw Nodes 接入指南

假设 Gateway 在服务器上，而你想查询另一台 Mac 上是否装了 Git。你需要的是把那台 Mac 接为 Node，然后调用它声明的能力；不需要在 Mac 上再搭一套完整的消息机器人。

本页使用 v2026.9.2 官方文档作为基线。本站在同一台 Mac 上，用两个独立状态目录完成了 Gateway → headless Node → 能力批准 → 程序查找实验。**这不等于验证了远程网络、设置码连接、摄像头或定位。**先对照两端 openclaw --version，再开始连接。

1. 先决定是否真的需要 Node

你的目标	应选择什么	首次验证
在 Telegram 接收消息	Gateway 上的渠道配置	私聊收到回复
理解聊天中已经上传的图片	媒体理解与可用模型	能回答图片内容
在另一台电脑查找程序或执行命令	headless Node，或已有桌面节点应用	查看 system.which 等能力
使用 Mac 的相机、屏幕等原生能力	macOS 节点应用及系统授权	describe 中有对应命令
获取手机画面或位置	对应移动端节点应用	支持该能力、前台状态和权限满足

**Node 是设备能力入口，不是图片理解模型。**消息先到 Gateway，由它组织模型请求和调用；设备负责执行自己暴露的能力。设备没有声明的功能，不能靠在提示词里要求来补上。

2. 准备连接时，给两端命名

在自己的记录里写下：Gateway 在哪台机器、Node 是哪台机器、各自的版本、计划调用什么能力。本文使用显示名 Lab Node，它只是便于辨认，不是身份认证。

同一台 Mac 若已经通过菜单栏应用接入为节点，不要再启动一个 CLI Node 来“增强它”；官方说明中应用已有配套运行进程。先使用现有节点检查能力。

首次连接建议使用自己的测试 Gateway 和测试设备。Node 会扩展 Gateway 可控制的机器范围，因此不能把未知 Gateway 的配对命令粘到工作电脑执行。

3. 接入 headless Node

对于尚未接入的测试设备，可在 Gateway 的 Control UI Devices 页面创建 Node host setup link。复制界面给出的完整命令，在目标 Node 机器运行。对应形式是：

openclaw node run --pair "oc-pair://实际设置码"

引号里的文字只是示例，必须使用你自己界面生成的实际值。该版本的设置码用于一次性初始连接，有有效期，不应出现在公开截图或记录模板中。

这一方式把连接端点、初始凭据和可用的 TLS 信息一起传给 Node，适合首次练习。已有明确网络与认证配置时，也可按 Node CLI 原文 使用 --host、--port 和 TLS 参数；不要把一条缺少认证信息的主机地址命令误当成完整安装流程。

保留 Node 终端运行。前台进程退出后，设备通常不再在线；首次验收不要求安装后台服务。

4. 查配对与连接，再查能力

在 Gateway 的终端执行：

openclaw devices list
openclaw nodes status

如果设备已通过设置码完成配对，不要重复审批。若存在待处理设备请求，核对来源、设备身份与声明角色后，使用你自己的实际请求 ID：

openclaw devices approve "实际请求ID"

随后复制目标 Node 的完整 ID。不要仅凭重名的显示名选择设备：

openclaw nodes describe --node "实际节点ID"

记录连接状态、平台、命令能力和权限。paired 与 connected 是两件事：前者表示有配对关系，后者表示当前在线。配对成功也不等于所有能力都可以调用。

如果需要批准新增命令能力，运行：

openclaw nodes pending

核对请求属于刚接入的设备，并查看完整能力列表。确认愿意授予这个范围后，用该请求的实际 ID：

openclaw nodes approve "实际能力请求ID"
openclaw nodes describe --node "实际节点ID"

这是批准该设备声明的能力范围，不是仅允许下一次 Git 查询。若范围大于你愿意授予的权限，停止并调整设备配置，不要为了完成练习全部接受。设备请求 ID、能力请求 ID 和节点 ID 不能混用。

5. 用一次程序查找验证调用链

在已声明并允许 system.which 的 macOS/Linux 测试节点上，查询 Git 是否存在。在 Gateway 终端运行下面命令，替换节点 ID；JSON 参数的单引号写法面向 macOS/Linux shell：

openclaw nodes invoke --node "实际节点ID" --command system.which --params '{"bins":["git"]}'

这一步查找程序路径，不是执行 Git，更不会自动安装它。

结果	应怎样判断
返回 Git 的路径	节点完成了查找；记录路径；shell 执行要另外测试
返回未找到或空结果	调用可能成功，只是节点环境没有 Git；不能当成配对失败
超时或设备离线	回到 nodes status，查看前台进程与连接
命令不允许或能力不存在	核对 describe 的声明和批准范围

不要把 system.which 改成 system.run 继续尝试。该版本的通用 nodes invoke 会阻止 system.run / system.run.prepare；shell 执行应走 Agent 的 exec 工具、host=node 和目标主机审批。这也是 执行审批教程 与本页分开的原因。

本站实际遇到的一次失败

在 macOS / Node 24.15.0 / OpenClaw 2026.9.2 实验中，节点已经返回 connected: true、paired: true，但 commands 仍为空，approvalState 为 pending-approval。这时调用返回：

node pairing changed while invocation was active

等待并重试没有解决问题。重新检查 describe 后，我们找到待批准的能力请求；批准并再次 describe 后，状态变为 approved，命令列表才包含 system.which。随后同一查找返回：

{
  "ok": true,
  "command": "system.which",
  "payload": { "bins": { "git": "/usr/bin/git" } }
}

这是实际响应的字段节选，不是所有设备的标准输出。下载前后状态记录。这次定位的关键是检查已批准的能力，而不是重复重启、重新安装 Git 或放开执行策略。

6. 相机与位置属于另一组验收

完成连接不代表已取得相机、录屏或位置权限。如果你的任务确实需要这些能力，再用自己的测试设备选择其中一项：

openclaw nodes camera list --node "实际节点ID"
openclaw nodes camera snap --node "实际节点ID"

拍摄前让画面只包含测试物体。检查命令返回的保存位置，打开实际图片，确认不是旧文件；返回一段文字描述不能代替图片验收。移动端相机调用还可能要求应用在前台，后台时可能返回 NODE_BACKGROUND_UNAVAILABLE。

位置调用的形式是 openclaw nodes location get --node "实际节点ID"。它会访问设备位置，不是普通网络探测。只在任务需要且设备主人同意时使用，并核对权限、数据时效与精度；不在公开验收表记录真实坐标。

7. 完成记录并安全停止

下载节点验收表。至少填写一次 status、describe 和实际调用结果，明确自己验证的是哪项能力。

临时 Node 完成后可在运行终端按 Ctrl+C，再从 Gateway 检查设备已离线。停止进程不等于撤销配对；若不再信任该连接，按当前设备管理页面撤销对应节点。撤销前核对 ID，避免影响另一台设备的任务。

继续使用浏览器能力可阅读 Browser 工具；准备处理真实文件前，先核对 安全加固与权限边界。

OpenClaw Tool、Skill 还是 Plugin

这不是三个同义词。Tool 是 Agent 能调用的动作，Skill 是教 Agent 怎样使用已有能力的说明，Plugin 是把新运行能力装进 OpenClaw 的代码包。 Tool policy 则负责收窄 Agent 能看到和调用的动作。

旧教程常把 ClawHub 当成“Skill 市场”，也容易把任何重复任务都升级为 Plugin。当前官方文档已经明确：ClawHub 同时托管 Skills 和 Plugins；Plugin 还能携带 Skill，但 Skill 本身不会授予工具权限。

• 下载六案例决策表 CSV
• 下载扩展安装审查表

先用四个问题完成路由

按顺序问，不要从“市场里有什么”开始：

1. OpenClaw 当前是否已经有完成动作的 Tool？
2. 需求是一次调用，还是一套需要反复复用的步骤与验收规则？
3. 是否必须加入新代码、渠道、模型提供商、hook 或协议？
4. 是否涉及凭据、后台服务、启动停止和卸载残留？

情况	首选	原因
已有能力，只做一次动作	Tool	直接调用即可
已有能力，需要稳定流程	Skill	保存步骤、边界与验收
已有能力，但权限过宽	Tool policy	收窄现有工具，不增加扩展
缺少运行能力或集成	Plugin	加入代码、合同和生命周期

如果一个“Skill”要求你先运行陌生安装脚本、启动后台服务或放入新二进制，它实际上已经跨入代码供应链审查范围，不能只按提示词文件看待。

1. 用六个固定案例校准判断

打开决策表，先隐藏 expected_surface 与 reason 两列。逐行写下你的选择和理由，再显示答案：

• E01：已有 browser，只缺每周登录导出流程 → Skill。
• E02：已有 exec，只想限制命令 → Tool policy。
• E03：新增 CRM API、凭据和写入 → Plugin。
• E04：已有天气工具，只查一次 → Tool。
• E05：已有文件与 shell，需要事故分级流程 → Skill。
• E06：新增内部消息渠道和原路回复 → Plugin。

六题全对后再审查真实候选。若 E02 或 E04 也选 Plugin，说明你在用安装代码代替简单配置；若 E03 或 E06 选 Skill，说明你把“怎样做”误当成“系统已经能做”。

2. 先列出现有能力

在当前工作区保存只读基线：

openclaw skills list --json > before-skills.json
openclaw plugins list --json > before-plugins.json

再检查 Agent 当前工具和策略。内置或已安装的 Tool 能完成动作时，不要为了包装感重复安装 Plugin。需要复用时，Skill 应写清触发条件、输入、调用哪些 Tools、停止条件和验收，而不是重新实现工具。

3. 在 ClawHub 搜索时先识别 family

当前原生 CLI 分开搜索：

openclaw skills search "calendar"
openclaw plugins search "calendar" --json

Skill 使用 openclaw skills install @owner/slug；ClawHub Plugin 使用明确前缀 openclaw plugins install clawhub:<package>。不要把搜索命中当成信任结论。记录 publisher、精确版本、family、扫描摘要和来源，再决定是否继续。

生产环境优先固定版本。无版本选择器通常会跟随更新线，适合探索却不利于复现实验；具体锁定行为以候选页面和当前 CLI 输出为准。

4. Skill 审查什么

至少打开 SKILL.md 和支持文件，回答：

• 什么时候触发，是否会在普通对话中误触发？
• 要求哪些 Tool、命令、路径和网络访问？
• 会读取或发送什么数据？
• 遇到缺字段、权限不足和外部失败时是否停止？
• 同名 Skill 是否被更高优先级目录覆盖？

安装后使用完整清单确认它出现在正确 workspace 和 Agent 下。一次正常任务、一次不应触发的普通问题、一次越界输入和一次缺工具测试，比“安装成功”更能说明 Skill 可用。

5. Plugin 审查什么

Plugin 是可执行代码。除发布者和文件外，还要检查 manifest 声明的 capabilities、pluginApi、最低 Gateway 版本、依赖、凭据保存、网络目的地、后台进程与卸载策略。

第三方来源要求 capability consent 时，逐项看清再继续。--force 用于明确接受某些来源流程，不应成为跳过审查的默认参数；官方 CLI 仍会执行安装策略与安全检查。

如果你只做审查，到此停止。只有你已经信任候选且确实需要它时，才按照候选官方页面给出的精确来源和版本安装。

6. 分开验证本地发现与运行健康

安装后的 Plugin 先查本地：

openclaw plugins inspect <id> --json
openclaw plugins doctor --json

plugins doctor 会检查 discovery、模块加载、兼容性和残留配置，但不会证明运行中的 Gateway 健康。启动或重载后还要检查：

openclaw health

随后跑四个金丝雀：正常调用、缺凭据、越界动作和用户取消。记录实际 Tool 名、授权提示、网络目的地、输出和日志。只看到 Plugin 出现在列表中，不能算集成完成。

7. 退出机制也是选型条件

试点前就写清禁用、卸载、凭据撤销、后台服务停止和配置残留如何处理。可以先使用 --dry-run 查看卸载计划（以当前 plugins uninstall --help 为准），再操作测试环境。

最终结论只允许三种：

• 直接使用现有 Tool / policy：没有必要增加包。
• 编写或安装 Skill：工具已足够，复用收益大于维护成本。
• 安装 Plugin：新运行能力不可替代，来源、兼容性、权限和退出路径均已验收。

“ClawHub 搜到了”不是第四种结论。ClawHub 负责分发与来源记录，真正的选择仍由能力缺口、代码边界和风险证据决定。