File Watcher Trigger

自动监控文件夹，当文件创建、修改、删除时，触发 Agent 执行任务。

---

功能特性

• 📁 监控指定目录（支持子目录递归）
• 🔍 文件过滤（通配符模式：*.pdf, report-*.xlsx）
• ⏱️ 事件防抖（避免频繁触发）
• 🎯 支持多种触发事件：onCreate、onModify、onDelete
• 📝 变量注入：文件名、路径、大小等占位符
• 🚀 自动唤醒 Agent 执行自定义任务

---

安装

openclawmp install trigger/@your-username/file-watcher-trigger

---

配置

基础配置 config.yaml

# 监控的目录
watch:
  path: ~/Downloads
  # 文件匹配模式（glob）
  patterns:
    - "*.pdf"
    - "*.md"
    - "report-*.xlsx"
  # 是否递归子目录
  recursive: false
  # 防抖时间（ms）：文件变化后等待多久再触发
  debounceMs: 1000

# 触发后执行的 Agent 任务
agent:
  # Agent ID（main 或自定义）
  agentId: main
  # 发送给 Agent 的消息模板
  prompt: |
    文件事件：{{eventType}}
    文件名：{{filename}}
    路径：{{filepath}}
    大小：{{size}} bytes
    
    请处理这个文件。
  # 超时时间（秒）
  timeoutSeconds: 300

---

变量占位符

---

事件类型

注意：

• modified 可能会连续触发多次（防抖可缓解）
• deleted 触发时文件已不存在，不能读取内容

---

高级配置

1. 多规则配置

rules:
  # 规则1：PDF 自动摘要
  - pattern: "*.pdf"
    event: created
    prompt: "请总结这个 PDF 文档：{{filepath}}"
    timeoutSeconds: 600

  # 规则2：Markdown 文件预览
  - pattern: "*.md"
    event: modified
    prompt: "这个 Markdown 被修改了：{{basename}}。请预览前 10 行：\n\n$(head -10 {{filepath}})"
    shell: true  # 支持 shell 命令

2. 条件过滤

conditions:
  minSize: 1024  # 至少 1KB 才触发
  maxSize: 104857600  # 最大 100MB
  # 自定义 JS 表达式（基于元数据）
  custom: |
    eventType === 'created' && filename.endsWith('.pdf')

3. 延迟启动

startup:
  delayMs: 5000  # 启动后等待 5 秒再开始监控
  initialScan: true  # 启动时扫描现有文件（可选）
  ignoreExisting: true  # 忽略启动时已存在的文件

---

安装与使用

1. 手动放置文件

# 创建目录
mkdir -p ~/.openclaw/triggers/file-watcher

# 复制所有文件
cp -r ~/.openclaw/workspace/file-watcher-trigger/* ~/.openclaw/triggers/file-watcher/

2. 编辑配置

nano ~/.openclaw/triggers/file-watcher/config.yaml

3. 启用 Trigger

在 Agent 配置中加载：

{
  "identity": {
    "name": "主 Agent"
  },
  "workspace": "default",
  "triggers": [
    {
      "type": "file-watcher",
      "configPath": "~/.openclaw/triggers/file-watcher/config.yaml",
      "enabled": true
    }
  ]
}

4. 重启 Gateway

openclaw gateway restart

---

目录结构

file-watcher-trigger/ ├── README.md # 本文档 ├── trigger.js # 触发器实现（Node.js） ├── package.json # 依赖声明（chokidar） └── config.yaml.example # 配置示例

---

实现原理

1. 启动时：读取配置，建立文件系统监听（使用 chokidar）
2. 事件触发：文件变化 → 防抖 → 匹配 pattern → 生成 prompt
3. 唤醒 Agent：调用 sessions_spawn 或发送系统事件
4. 执行完成：记录日志（可选：触发后移动/归档文件）

---

安全注意事项

• ⚠️ 不要监控敏感目录（如 ~/.ssh、~/Documents 私密文件）
• ⚠️ prompt 模板避免注入攻击（用户提供的文件名要转义）
• ⚠️ 配置合理超时，避免 Agent 处理超大文件卡死
• ✅ 建议使用 ignoreExisting 避免启动时批量触发

---

故障排查

---

License

MIT © 2026