Skip to main content

​
Hooks

Hooks 提供了一个可扩展的事件驱动系统，用于响应代理命令和事件来自动执行操作。Hooks 会从指定目录中自动发现，并且可以通过 CLI 命令进行管理。

​
入门导览

Hooks 是在某些事件发生时运行的小脚本。主要有两种类型：
  • Hooks（本页内容）：当代理事件触发时，在网关内部运行
  • Webhooks：外部 HTTP webhook，允许其他系统触发 OpenClaw 中的工作

​
快速开始

​
列出可用 Hooks

openclaw hooks list

​
启用 Hook

openclaw hooks enable session-memory

​
检查 Hook 状态

openclaw hooks check

​
获取详细信息

openclaw hooks info session-memory

​
内置 Hooks

OpenClaw 自带四个自动发现的内置 hooks：

​
💾 session-memory

当执行 /new 时将会话上下文保存到代理工作区。 
openclaw hooks enable session-memory
输出目录：~/.openclaw/workspace/memory/ 文件名示例：
  • 2026-01-16-vendor-pitch.md
  • 2026-01-16-api-design.md

​
📎 bootstrap-extra-files

在 agent:bootstrap 阶段注入额外的启动文件。 
openclaw hooks enable bootstrap-extra-files
配置示例： 
{
  hooks: {
    internal: {
      enabled: true,
      entries: {
        "bootstrap-extra-files": {
          enabled: true,
          paths: ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
        }
      }
    }
  }
}

​
📝 command-logger

将所有命令事件记录到集中审计文件。 
openclaw hooks enable command-logger
输出：~/.openclaw/logs/commands.log 查看日志： 
tail -n 20 ~/.openclaw/logs/commands.log
cat ~/.openclaw/logs/commands.log | jq .

​
🚀 boot-md

网关启动时运行 BOOT.md。 
openclaw hooks enable boot-md

​
事件类型

​
命令事件

  • command:new — 发出 /new 命令时
  • command:reset — 发出 /reset 命令时
  • command:stop — 发出 /stop 命令时

​
会话事件

  • session:compact:before — 压缩历史摘要之前
  • session:compact:after — 压缩完成

​
代理事件

  • agent:bootstrap — 在注入工作区 bootstrap 文件之前

​
网关事件

  • gateway:startup — 频道启动及 hooks 加载后

​
消息事件

  • message:received — 收取任一渠道入站消息
  • message:transcribed — 消息已全解析（包含音频转录）
  • message:preprocessed — 所有媒体和链接解析完毕后触发
  • message:sent — 出站消息发送成功时

​
创建自定义 Hooks

​
1. 选择位置

  • 工作区 hooks：<workspace>/hooks/
  • 管理 hooks：~/.openclaw/hooks/

​
2. 创建目录结构

mkdir -p ~/.openclaw/hooks/my-hook
cd ~/.openclaw/hooks/my-hook

​
3. 创建 HOOK.md

---
name: my-hook
description: "执行一些有用操作"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# 我的自定义 Hook

当你执行 `/new` 时，本 hook 会做一些有用的事情。

​
4. 创建 handler.ts

const handler = async (event) => {
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log("[my-hook] 运行中！");
  // 您的逻辑写这里
};

export default handler;

​
5. 启用并测试

# 确认 hook 是否被发现
openclaw hooks list

# 启用 hook
openclaw hooks enable my-hook

# 重启网关
openclaw gateway restart

​
配置

​
新配置格式（推荐）

{
  hooks: {
    internal: {
      enabled: true,
      entries: {
        "session-memory": { enabled: true },
        "command-logger": { enabled: false }
      }
    }
  }
}

​
针对某个 Hook 的配置

{
  hooks: {
    internal: {
      enabled: true,
      entries: {
        "my-hook": {
          enabled: true,
          env: {
            MY_CUSTOM_VAR: "value"
          }
        }
      }
    }
  }
}

​
Hook 发现机制

Hooks 会自动从三个目录中发现（优先级按顺序）：
  1. 工作区 hooks：<workspace>/hooks/
  2. 管理 hooks：~/.openclaw/hooks/
  3. 内置 hooks：<openclaw>/dist/hooks/bundled/

​
CLI 命令

​
列出 Hooks

openclaw hooks list
openclaw hooks list --eligible  # 只显示合格的
openclaw hooks list --verbose   # 详细显示
openclaw hooks list --json      # JSON 输出

​
查看 Hook 信息

openclaw hooks info session-memory
openclaw hooks info session-memory --json

​
检查条件

openclaw hooks check
openclaw hooks check --json

​
启用 / 禁用

openclaw hooks enable session-memory
openclaw hooks disable command-logger

​
故障排查

​
Hook 未被发现

  1. 检查目录结构： 
    ls -la ~/.openclaw/hooks/my-hook/
# 应包含 HOOK.md，handler.ts
  2. 验证 HOOK.md 格式
  3. 列出所有已发现的 hook： 
    openclaw hooks list

​
Hook 不合格

openclaw hooks info my-hook
关注缺失的：
  • 二进制程序（检查 PATH）
  • 环境变量
  • 配置
  • OS 兼容性

​
Hook 不执行

  1. 确认 hook 已启用： 
    openclaw hooks list
  2. 重启网关进程
  3. 查看网关日志： 
    openclaw logs --follow | grep hook

​
相关文档