OpenClaw 后台任务主动推送神器：openclaw-notify 技能完全解析

假设你正在开发一个耗时数据处理技能，你可以在它的SKILL.md## 任务完成处理（必须）任务执行完毕后，**只执行一次**以下命令通知主会话：```bashopenclaw gateway wake --text "Done: [简要描述结果]" --mode now如果任务失败，请将Done改为Failed，并在消息中说明原因。然后在你的实际执行脚本（比如 Python）中，在最后加上：```

haolove527

1273人浏览 · 2026-03-10 14:30:00

haolove527 · 2026-03-10 14:30:00 发布

OpenClaw 后台任务主动推送神器：openclaw-notify 技能完全解析

你是否有过这样的经历：让 AI 跑一个耗时任务（比如处理 1GB 日志、批量生成图片、爬取整站数据），然后只能开着终端，时不时看一眼进度？如果能像外卖 App 那样，任务完成后手机“叮”一声自动推送结果，该多爽。

今天要介绍的 openclaw-notify 技能，就是 OpenClaw 生态里专门解决这个痛点的“明星技能”。它让子 Agent 或后台进程能在任务结束时，主动“叫醒”主会话，并把结果通过飞书、Telegram 等通道实时推送到你的手机上。本文将带你从原理到实战，彻底搞懂这个技能。

文章目录

OpenClaw 后台任务主动推送神器：openclaw-notify 技能完全解析

1. 为什么需要 `openclaw-notify`？

在 OpenClaw 的架构中，当你通过主 Agent（比如你在飞书里聊天的那个）启动一个耗时任务时，通常有两种做法：

同步执行：主 Agent 一直等着任务结束，期间无法处理其他消息。如果任务要跑 10 分钟，你就得干等 10 分钟。
异步派发：主 Agent 把任务丢给子 Agent 或后台进程，然后立即回复“任务已开始”，自己继续处理新消息。但问题来了——任务完成后，子 Agent 如何通知主 Agent 结果？

openclaw-notify 就是为了解决这个“异步结果回调”而生的。它提供了一个简单的命令，让任何子进程都能把结果“塞回”原来的会话，并触发你配置的所有通知通道（飞书、桌面通知等）。

在这里插入图片描述

2. 核心原理：一张图看懂

关键点：

wake 命令是子 Agent 与 Gateway 通信的“暗号”。
Gateway 收到后，会找到这条任务对应的原会话，并把消息作为新消息塞进去。
主 Agent 收到消息后，会像处理普通用户消息一样处理它——通常就是调用 message 工具通过通道推送给用户。
整个过程完全异步，不阻塞主会话。

3. 安装：两种方式，30 秒搞定

方式一：直接对 OpenClaw 说（推荐）

在飞书/Telegram 里对你的 OpenClaw 机器人说：

“请帮我安装 openclaw-notify 技能”

如果系统配置了自动安装权限，它会自动完成。

方式二：使用 CLI

openclaw skills install openclaw-notify

或者从 ClawHub 安装：

clawhub install linuxlewis-agent-skills-openclaw-notify

安装后，用以下命令确认：

openclaw skills list | grep notify

你应该会看到 openclaw-notify (1.0.1) 之类的输出。

4. 使用详解：命令参数与最佳实践

4.1 核心命令格式

openclaw gateway wake --text "通知内容" --mode now

4.2 参数说明

参数	必填	默认值	说明
`--text`	是	无	通知正文，支持 Markdown、链接、文件路径等
`--mode`	否	`now`	`now`（立即推送）或 `queue`（排队推送，一般用 now）
`--title`	否	无	可选标题，部分通道支持（如桌面通知）
`--tags`	否	无	逗号分隔的标签，用于分类（如 `done,failed`）

4.3 三种标准状态（强烈推荐遵循）

社区约定俗成的三种前缀，方便主 Agent 快速理解状态：

# 成功完成
openclaw gateway wake --text "Done: 已生成 500 条数据分析报告，文件路径：/data/report_20260309.xlsx" --mode now

# 执行失败
openclaw gateway wake --text "Failed: API 密钥过期，无法继续，请更新密钥" --mode now

# 需要人工介入（如需要用户确认）
openclaw gateway wake --text "Blocked: 需要你提供飞书群 Chat_ID 才能继续推送" --mode now

遵循这个规范，主 Agent 可以根据前缀自动决定后续动作（比如失败时重试、阻塞时询问用户）。

4.4 在自定义技能中集成的最佳实践

假设你正在开发一个耗时数据处理技能 data-processor，你可以在它的 SKILL.md 中加入以下指令：

## 任务完成处理（必须）
任务执行完毕后，**只执行一次**以下命令通知主会话：
```bash
openclaw gateway wake --text "Done: [简要描述结果]" --mode now

如果任务失败，请将 Done 改为 Failed，并在消息中说明原因。


然后在你的实际执行脚本（比如 Python）中，在最后加上：

```python
import subprocess
subprocess.run(["openclaw", "gateway", "wake", "--text", "Done: 数据处理完成，输出文件：/data/output.csv", "--mode", "now"])

这样，你的技能就拥有了“完成后自动推送”的能力。

5. 与飞书推送的完美结合

你可能会问：wake 命令推送到主会话后，主 Agent 怎么知道要通过飞书推送给我？

答案是：主 Agent 会自动处理。当主 Agent 收到这条消息时，它本质上就是收到了一条来自子 Agent 的“消息”。它会按照正常的处理流程，调用 message 工具，通过你已启用的通道（飞书、Telegram 等）推送给用户。

因此，只要你的飞书通道配置正确，wake 命令就能触发飞书推送。而且支持飞书的所有特性：

富文本（Markdown）
消息卡片
@提及特定用户
文件附件

例如，你在 text 里放一个飞书卡片 JSON，主 Agent 会原样发送。

6. 典型使用场景（附示例）

6.1 数据处理任务完成后推送报告链接

用户：“帮我分析一下这个月的销售数据，完成后推给我。”
AI 启动子任务，最后子任务执行：

openclaw gateway wake --text "Done: 销售分析报告已生成，[点击下载](https://example.com/report.pdf)" --mode now

结果：手机收到带链接的推送，点击直接下载。

6.2 代码生成技能 PR 创建后推送 GitHub 链接

子任务完成代码生成并创建 PR 后：

openclaw gateway wake --text "Done: 代码已提交，PR #123：https://github.com/xxx/pull/123" --mode now

6.3 定时任务失败报警

定时爬虫脚本发现目标网站改版，爬取失败：

openclaw gateway wake --text "Failed: 爬虫任务失败，网站结构已变，需要更新规则" --mode now

结果：立即收到失败通知，可以及时介入。

6.4 多 Agent 协作

子 Agent A 完成第一步处理后，通知主 Agent 可以开始第二步：

openclaw gateway wake --text "Done: 数据清洗完成，可以开始建模了" --mode now

7. 故障排查：收不到推送怎么办？

7.1 检查 Gateway 是否运行

openclaw gateway status

如果没有运行，重启：

sudo systemctl restart openclaw   # 或对应的启动方式

7.2 检查飞书通道状态

openclaw status

确保 feishu 显示为 ON | OK。

7.3 查看实时日志

openclaw logs --follow

尝试手动触发一次 wake 命令，看日志中是否有错误信息。常见错误：

Failed to wake session: session not found：说明 wake 命令找不到原会话。可能是因为你在子进程中丢失了环境变量（比如没继承 OPENCLAW_SESSION_ID）。解决办法是在执行 wake 前确保环境变量存在，或者在命令中显式指定 --session-id。
permission denied：子进程用户权限不足，无法执行 openclaw 命令。检查 PATH 和文件权限。