Hooks 钩子

概述

Hooks 允许你在消息处理的不同阶段插入自定义逻辑，实现消息过滤、内容转换、日志记录等功能。它是 OpenClaw 自动化体系中最灵活的扩展点。

Hook 类型

Hook	触发时机	典型用途
pre-process	消息到达 Agent 前	消息过滤、内容清洗、敏感词拦截
post-process	Agent 响应后	格式转换、日志记录、通知转发
on-error	出错时触发	错误告警、自动重试、降级处理

配置方式

在 openclaw.json 中配置 Hooks：

{
  "hooks": {
    "pre-process": [
      {
        "name": "敏感词过滤",
        "script": "scripts/filter.js",
        "enabled": true
      }
    ],
    "post-process": [
      {
        "name": "日志记录",
        "script": "scripts/logger.js",
        "enabled": true
      }
    ],
    "on-error": [
      {
        "name": "错误通知",
        "script": "scripts/error-notify.js",
        "enabled": true
      }
    ]
  }
}

使用场景

消息过滤

在消息到达 Agent 前进行预处理：

• 过滤垃圾信息和广告
• 拦截包含敏感信息的消息
• 将语音消息自动转为文字

响应增强

在 Agent 响应后进行后处理：

• 自动翻译为指定语言
• 添加格式化（如 Markdown 渲染）
• 将重要响应同步到其他渠道

安全审计

记录和监控所有交互：

• 记录所有工具调用到审计日志
• 检测异常行为模式
• 在执行危险操作前发送确认请求

二次确认

对危险操作要求用户确认：

{
  "security": {
    "requireConfirmation": ["delete", "rm", "restart", "shutdown"]
  }
}

当指令包含这些关键词时，OpenClaw 会先询问「确定要执行吗？回复 yes 确认」。

内置 Hooks

OpenClaw 预置了 4 个开箱即用的 Hook，在安装时可选择启用。初次使用建议先跳过（Skip for now），后续按需在设置菜单中逐个开启。

Hook	触发时机	功能	适用场景
boot-md	网关启动时	执行 BOOT.md 文件中的预设规则	需要固定启动流程、强制遵循规则
bootstrap-extra-files	Agent 引导阶段	将额外工作区规则文件注入上下文	拥有完整的 Bootstrap 文件体系
command-logger	每次命令执行时	将所有命令事件记录到审计文件	需要追踪操作历史、安全审计
session-memory	执行 /new 命令时	自动保存当前会话上下文	希望在新建会话前保留记忆

Bootstrap 文件体系

bootstrap-extra-files 支持注入以下工作区文件：

• AGENTS.md — Agent 角色定义
• SOUL.md — Agent 人格与风格
• TOOLS.md — 可用工具清单
• IDENTITY.md — 身份标识
• USER.md — 用户偏好
• HEARTBEAT.md — 心跳规则
• BOOTSTRAP.md — 引导入口

按需启用

• 固定启动规则 → 启用 boot-md
• 操作审计需求 → 启用 command-logger
• 会话记忆保留 → 启用 session-memory
• 不确定 → 先跳过，不影响核心功能，后续随时可在设置中开启

下一步

• 定时任务 — 让 Agent 按时间表主动工作
• Webhooks — 接收外部系统事件