Hooks

Hooks 提供了一个可扩展的事件驱动系统,用于自动响应 Agent 命令和事件。Hooks 会从目录中自动发现,并可以通过 CLI 命令管理,类似于 OpenClaw 中 Skill 的工作方式。

快速了解

Hooks 是在某些事情发生时运行的小脚本。有两种类型:

  • Hooks(本页内容):在 Gateway 内部运行,当 Agent 事件触发时执行,比如 /new、/reset、/stop 或生命周期事件。
  • Webhooks:外部 HTTP webhook,让其他系统触发 OpenClaw 中的工作。参见 Webhook Hooks 或使用 openclaw webhooks 查看 Gmail 辅助命令。

Hooks 也可以打包在 Plugin 中;参见 Plugins。

常见用途:

  • 重置 Session 时保存记忆快照
  • 保留命令审计跟踪,用于故障排除或合规
  • Session 开始或结束时触发后续自动化
  • 事件触发时向 Agent Workspace 写入文件或调用外部 API

如果你会写一个小的 TypeScript 函数,就能写 Hook。Hooks 会自动发现,你可以通过 CLI 启用或禁用它们。

概述

Hook 系统让你可以:

  • 执行 /new 命令时将 Session 上下文保存到内存
  • 记录所有命令用于审计
  • 在 Agent 生命周期事件上触发自定义自动化
  • 扩展 OpenClaw 的行为而无需修改核心代码

快速开始

内置 Hooks

OpenClaw 自带四个会自动发现的内置 Hooks:

  • 💾 session-memory:执行 /new 时将 Session 上下文保存到你的 Agent Workspace(默认 ~/.openclaw/workspace/memory/)
  • 📝 command-logger:将所有命令事件记录到 ~/.openclaw/logs/commands.log
  • 🚀 boot-md:Gateway 启动时运行 BOOT.md(需要启用内部 hooks)
  • 😈 soul-evil:在清除窗口期间或随机情况下,将注入的 SOUL.md 内容替换为 SOUL_EVIL.md

列出可用的 Hooks:

openclaw hooks list

启用一个 Hook:

openclaw hooks enable session-memory

检查 Hook 状态:

openclaw hooks check

获取详细信息:

openclaw hooks info session-memory

引导配置

在引导配置过程中(openclaw onboard),系统会提示你启用推荐的 Hooks。向导会自动发现符合条件的 Hooks 并展示供你选择。

Hook 发现机制

Hooks 会从三个目录自动发现(按优先级顺序):

  1. Workspace hooks: <workspace>/hooks/(每个 Agent 独立,最高优先级)
  2. Managed hooks: ~/.openclaw/hooks/(用户安装,跨 Workspace 共享)
  3. Bundled hooks: <openclaw>/dist/hooks/bundled/(OpenClaw 自带)

Managed hook 目录可以是单个 Hook 或 Hook pack(包目录)。

每个 Hook 是一个包含以下内容的目录:

my-hook/
├── HOOK.md          # 元数据 + 文档
└── handler.ts       # 处理器实现

Hook Packs (npm/归档文件)

Hook packs 是标准的 npm 包,通过 package.json 中的 openclaw.hooks 导出一个或多个 Hooks。安装方式:

openclaw hooks install <path-or-spec>

示例 package.json:

{
  "name": "@acme/my-hooks",
  "version": "0.1.0",
  "openclaw": {
    "hooks": ["./hooks/my-hook", "./hooks/other-hook"]
  }
}

每个条目指向一个包含 HOOK.md 和 handler.ts(或 index.ts)的 Hook 目录。 Hook packs 可以包含依赖项;它们会被安装到 ~/.openclaw/hooks/<id> 下。

Hook 结构

HOOK.md 格式

HOOK.md 文件在 YAML frontmatter 中包含元数据,加上 Markdown 文档:

---
name: my-hook
description: "这个 hook 的简短描述"
homepage: https://docs.openclaw.ai/hooks#my-hook
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

详细文档写在这里...

## 功能说明

- 监听 `/new` 命令
- 执行某些操作
- 记录结果

## 要求

- 必须安装 Node.js

## 配置

无需配置。

元数据字段

metadata.openclaw 对象支持:

  • emoji: CLI 显示的 emoji(例如 "💾")
  • events: 要监听的事件数组(例如 ["command:new", "command:reset"])
  • export: 要使用的命名导出(默认为 "default")
  • homepage: 文档 URL
  • requires: 可选要求
    • bins: PATH 中需要的二进制文件(例如 ["git", "node"])
    • anyBins: 至少存在其中一个二进制文件
    • env: 需要的环境变量
    • config: 需要的配置路径(例如 ["workspace.dir"])
    • os: 需要的平台(例如 ["darwin", "linux"])
  • always: 绕过资格检查(布尔值)
  • install: 安装方法(对于内置 hooks: [{"id":"bundled","kind":"bundled"}])

处理器实现

handler.ts 文件导出一个 HookHandler 函数:

import type { HookHandler } from "../../src/hooks/hooks.js";

const myHandler: HookHandler = async (event) => {
  // 仅在 'new' 命令时触发
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] New command triggered`);
  console.log(`  Session: ${event.sessionKey}`);
  console.log(`  Timestamp: ${event.timestamp.toISOString()}`);

  // 你的自定义逻辑写在这里

  // 可选:向用户发送消息
  event.messages.push("✨ My hook executed!");
};

export default myHandler;

事件上下文

每个事件包含:

{
  type: 'command' | 'session' | 'agent' | 'gateway',
  action: string,              // 例如 'new', 'reset', 'stop'
  sessionKey: string,          // Session 标识符
  timestamp: Date,             // 事件发生时间
  messages: string[],          // 推送消息到这里发送给用户
  context: {
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // 例如 'whatsapp', 'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: OpenClawConfig
  }
}

事件类型

命令事件

Agent 命令执行时触发:

  • command: 所有命令事件(通用监听器)
  • command:new: 执行 /new 命令时
  • command:reset: 执行 /reset 命令时
  • command:stop: 执行 /stop 命令时

Agent 事件

  • agent:bootstrap: Workspace Bootstrap 文件注入之前(Hooks 可以修改 context.bootstrapFiles)

Gateway 事件

Gateway 启动时触发:

  • gateway:startup: Channel 启动和 Hooks 加载之后

Tool Result Hooks (Plugin API)

这些 Hooks 不是事件流监听器;它们让 Plugin 在 OpenClaw 持久化工具结果之前同步调整结果。

  • tool_result_persist: 在工具结果写入 Session 记录之前转换它们。必须是同步的;返回更新后的工具结果负载或 undefined 保持原样。参见 Agent Loop。

未来事件

计划中的事件类型:

  • session:start: 新 Session 开始时
  • session:end: Session 结束时
  • agent:error: Agent 遇到错误时
  • message:sent: 消息发送时
  • message:received: 消息接收时

创建自定义 Hooks

1. 选择位置

  • Workspace hooks(<workspace>/hooks/): 每个 Agent 独立,最高优先级
  • Managed hooks(~/.openclaw/hooks/): 跨 Workspace 共享

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"] } }
---

# My Custom Hook

这个 Hook 在你执行 `/new` 时做一些有用的事情。

4. 创建 handler.ts

import type { HookHandler } from "../../src/hooks/hooks.js";

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

  console.log("[my-hook] Running!");
  // 你的逻辑写在这里
};

export default handler;

5. 启用并测试

# 验证 Hook 已被发现
openclaw hooks list

# 启用它
openclaw hooks enable my-hook

# 重启你的 Gateway 进程(macOS 上重启菜单栏应用,或重启你的开发进程)

# 触发事件
# 通过你的消息 Channel 发送 /new

配置

新配置格式(推荐)

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

单个 Hook 配置

Hooks 可以有自定义配置:

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

额外目录

从额外目录加载 Hooks:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "load": {
        "extraDirs": ["/path/to/more/hooks"]
      }
    }
  }
}

旧配置格式(仍然支持)

旧配置格式仍然可以向后兼容:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "handlers": [
        {
          "event": "command:new",
          "module": "./hooks/handlers/my-handler.ts",
          "export": "default"
        }
      ]
    }
  }
}

迁移说明: 新 Hooks 使用基于发现的新系统。旧的处理器会在基于目录的 Hooks 之后加载。

CLI 命令

列出 Hooks

# 列出所有 Hooks
openclaw hooks list

# 仅显示符合条件的 Hooks
openclaw hooks list --eligible

# 详细输出(显示缺失的要求)
openclaw hooks list --verbose

# JSON 输出
openclaw hooks list --json

Hook 信息

# 显示 Hook 的详细信息
openclaw hooks info session-memory

# JSON 输出
openclaw hooks info session-memory --json

检查资格

# 显示资格摘要
openclaw hooks check

# JSON 输出
openclaw hooks check --json

启用/禁用

# 启用一个 Hook
openclaw hooks enable session-memory

# 禁用一个 Hook
openclaw hooks disable command-logger

内置 Hooks

session-memory

执行 /new 时将 Session 上下文保存到内存。

事件: command:new

要求: 必须配置 workspace.dir

输出: <workspace>/memory/YYYY-MM-DD-slug.md(默认为 ~/.openclaw/workspace)

功能说明:

  1. 使用重置前的 Session 条目定位正确的记录
  2. 提取对话的最后 15 行
  3. 使用 LLM 生成描述性的文件名 slug
  4. 将 Session 元数据保存到带日期的内存文件

输出示例:

# Session: 2026-01-16 14:30:00 UTC

- **Session Key**: agent:main:main
- **Session ID**: abc123def456
- **Source**: telegram

文件名示例:

  • 2026-01-16-vendor-pitch.md
  • 2026-01-16-api-design.md
  • 2026-01-16-1430.md(如果 slug 生成失败,使用时间戳作为后备)

启用:

openclaw hooks enable session-memory

command-logger

将所有命令事件记录到集中的审计文件。

事件: command

要求: 无

输出: ~/.openclaw/logs/commands.log

功能说明:

  1. 捕获事件详情(命令操作、时间戳、Session key、发送者 ID、来源)
  2. 以 JSONL 格式追加到日志文件
  3. 在后台静默运行

日志条目示例:

{"timestamp":"2026-01-16T14:30:00.000Z","action":"new","sessionKey":"agent:main:main","senderId":"+1234567890","source":"telegram"}
{"timestamp":"2026-01-16T15:45:22.000Z","action":"stop","sessionKey":"agent:main:main","senderId":"[email protected]","source":"whatsapp"}

查看日志:

# 查看最近的命令
tail -n 20 ~/.openclaw/logs/commands.log

# 使用 jq 美化输出
cat ~/.openclaw/logs/commands.log | jq .

# 按操作过滤
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

启用:

openclaw hooks enable command-logger

soul-evil

在清除窗口期间或随机情况下,将注入的 SOUL.md 内容替换为 SOUL_EVIL.md。

事件: agent:bootstrap

文档: SOUL Evil Hook

输出: 不写入文件;仅在内存中交换。

启用:

openclaw hooks enable soul-evil

配置:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "soul-evil": {
          "enabled": true,
          "file": "SOUL_EVIL.md",
          "chance": 0.1,
          "purge": { "at": "21:00", "duration": "15m" }
        }
      }
    }
  }
}

boot-md

Gateway 启动时运行 BOOT.md(在 Channel 启动之后)。 必须启用内部 Hooks 才能运行。

事件: gateway:startup

要求: 必须配置 workspace.dir

功能说明:

  1. 从你的 Workspace 读取 BOOT.md
  2. 通过 Agent Runner 运行指令
  3. 通过消息工具发送任何请求的出站消息

启用:

openclaw hooks enable boot-md

最佳实践

保持处理器快速

Hooks 在命令处理期间运行。保持它们轻量级:

// ✓ 好 - 异步工作,立即返回
const handler: HookHandler = async (event) => {
  void processInBackground(event); // 触发后不等待
};

// ✗ 差 - 阻塞命令处理
const handler: HookHandler = async (event) => {
  await slowDatabaseQuery(event);
  await evenSlowerAPICall(event);
};

优雅地处理错误

始终包装有风险的操作:

const handler: HookHandler = async (event) => {
  try {
    await riskyOperation(event);
  } catch (err) {
    console.error("[my-handler] Failed:", err instanceof Error ? err.message : String(err));
    // 不要抛出错误 - 让其他处理器继续运行
  }
};

尽早过滤事件

如果事件不相关,尽早返回:

const handler: HookHandler = async (event) => {
  // 仅处理 'new' 命令
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  // 你的逻辑写在这里
};

使用具体的事件键

在元数据中尽可能指定确切的事件:

metadata: { "openclaw": { "events": ["command:new"] } } # 具体

而不是:

metadata: { "openclaw": { "events": ["command"] } } # 通用 - 开销更大

调试

启用 Hook 日志

Gateway 在启动时记录 Hook 加载:

Registered hook: session-memory -> command:new
Registered hook: command-logger -> command
Registered hook: boot-md -> gateway:startup

检查发现

列出所有发现的 Hooks:

openclaw hooks list --verbose

检查注册

在你的处理器中,记录它何时被调用:

const handler: HookHandler = async (event) => {
  console.log("[my-handler] Triggered:", event.type, event.action);
  // 你的逻辑
};

验证资格

检查为什么 Hook 不符合条件:

openclaw hooks info my-hook

在输出中查找缺失的要求。

测试

Gateway 日志

监控 Gateway 日志以查看 Hook 执行:

# macOS
./scripts/clawlog.sh -f

# 其他平台
tail -f ~/.openclaw/gateway.log

直接测试 Hooks

独立测试你的处理器:

import { test } from "vitest";
import { createHookEvent } from "./src/hooks/hooks.js";
import myHandler from "./hooks/my-hook/handler.js";

test("my handler works", async () => {
  const event = createHookEvent("command", "new", "test-session", {
    foo: "bar",
  });

  await myHandler(event);

  // 断言副作用
});

架构

核心组件

  • src/hooks/types.ts: 类型定义
  • src/hooks/workspace.ts: 目录扫描和加载
  • src/hooks/frontmatter.ts: HOOK.md 元数据解析
  • src/hooks/config.ts: 资格检查
  • src/hooks/hooks-status.ts: 状态报告
  • src/hooks/loader.ts: 动态模块加载器
  • src/cli/hooks-cli.ts: CLI 命令
  • src/gateway/server-startup.ts: Gateway 启动时加载 Hooks
  • src/auto-reply/reply/commands-core.ts: 触发命令事件

发现流程

Gateway 启动
    ↓
扫描目录 (workspace → managed → bundled)
    ↓
解析 HOOK.md 文件
    ↓
检查资格 (bins, env, config, os)
    ↓
从符合条件的 Hooks 加载处理器
    ↓
为事件注册处理器

事件流程

用户发送 /new
    ↓
命令验证
    ↓
创建 Hook 事件
    ↓
触发 Hook (所有已注册的处理器)
    ↓
命令处理继续
    ↓
Session 重置

故障排除

Hook 未被发现

  1. 检查目录结构:

    ls -la ~/.openclaw/hooks/my-hook/
# 应该显示: HOOK.md, handler.ts

  2. 验证 HOOK.md 格式:

    cat ~/.openclaw/hooks/my-hook/HOOK.md
# 应该有带 name 和 metadata 的 YAML frontmatter

  3. 列出所有发现的 Hooks:

    openclaw hooks list

Hook 不符合条件

检查要求:

openclaw hooks info my-hook

查找缺失的:

  • 二进制文件(检查 PATH)
  • 环境变量
  • 配置值
  • 操作系统兼容性

Hook 未执行

  1. 验证 Hook 已启用:

    openclaw hooks list
# 已启用的 Hooks 旁边应该显示 ✓

  2. 重启你的 Gateway 进程以重新加载 Hooks。

  3. 检查 Gateway 日志中的错误:

    ./scripts/clawlog.sh | grep hook

处理器错误

检查 TypeScript/导入错误:

# 直接测试导入
node -e "import('./path/to/handler.ts').then(console.log)"

迁移指南

从旧配置迁移到发现机制

之前:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "handlers": [
        {
          "event": "command:new",
          "module": "./hooks/handlers/my-handler.ts"
        }
      ]
    }
  }
}

之后:

  1. 创建 Hook 目录:

    mkdir -p ~/.openclaw/hooks/my-hook
mv ./hooks/handlers/my-handler.ts ~/.openclaw/hooks/my-hook/handler.ts

  2. 创建 HOOK.md:

    ---
name: my-hook
description: "My custom hook"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# My Hook

做一些有用的事情。

  3. 更新配置:

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

  4. 验证并重启你的 Gateway 进程:

    openclaw hooks list
# 应该显示: 🎯 my-hook ✓

迁移的好处:

  • 自动发现
  • CLI 管理
  • 资格检查
  • 更好的文档
  • 一致的结构

参见