钩子

钩子提供了一个可扩展的事件驱动系统,用于自动化响应代理命令和事件的操作。钩子会从目录自动发现,可以通过 CLI 命令进行管理,类似于 OpenClaw 中技能的工作方式。

入门指导

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

钩子(本页):在代理事件(如 /new、/reset、/stop 或生命周期事件)触发时在网关内运行。
Webhooks:外部 HTTP webhooks,让其他系统在 OpenClaw 中触发工作。请参阅 Webhook 钩子或使用 openclaw webhooks 获取 Gmail 辅助命令。

钩子也可以捆绑在插件中;请参阅插件。常见用途:

当您重置会话时保存内存快照
保留命令审计跟踪以进行故障排除或合规性检查
当会话开始或结束时触发后续自动化
当事件触发时将文件写入代理工作区或调用外部 API

如果您可以编写一个小的 TypeScript 函数,您就可以编写钩子。钩子会自动发现,您可以通过 CLI 启用或禁用它们。

概述

钩子系统允许您:

在发出 /new 时将会话上下文保存到内存
记录所有命令以进行审计
在代理生命周期事件上触发自定义自动化
在不修改核心代码的情况下扩展 OpenClaw 的行为

入门

捆绑钩子

OpenClaw 附带四个自动发现的捆绑钩子:

💾 session-memory:当您发出 /new 时,将会话上下文保存到您的代理工作区(默认 ~/.openclaw/workspace/memory/)
📝 command-logger:将所有命令事件记录到 ~/.openclaw/logs/commands.log
🚀 boot-md:当网关启动时运行 BOOT.md(需要启用内部钩子)
😈 soul-evil:在清除窗口期间或随机情况下用 SOUL_EVIL.md 交换注入的 SOUL.md 内容

列出可用钩子:

openclaw hooks list

启用钩子:

openclaw hooks enable session-memory

检查钩子状态:

openclaw hooks check

获取详细信息:

openclaw hooks info session-memory

入职

在入职期间(openclaw onboard),系统会提示您启用推荐的钩子。向导会自动发现合格的钩子并呈现供选择。

钩子发现

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

工作区钩子:<workspace>/hooks/(每个代理,最高优先级)
托管钩子:~/.openclaw/hooks/(用户安装,跨工作区共享)
捆绑钩子:<openclaw>/dist/hooks/bundled/(随 OpenClaw 一起提供)

托管钩子目录可以是单个钩子或钩子包(包目录)。每个钩子是一个包含以下内容的目录:

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

钩子包(npm/archives)

钩子包是标准的 npm 包,通过 package.json 中的 openclaw.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)的钩子目录。钩子包可以包含依赖项;它们将安装在 ~/.openclaw/hooks/<id> 下。

钩子结构

HOOK.md 格式

HOOK.md 文件包含 YAML 前置元数据加 Markdown 文档:

---
name: my-hook
description: "此钩子功能的简短描述"
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 的显示表情符号(例如,"💾")
events:要监听的事件数组(例如,["command:new", "command:reset"])
export:要使用的命名导出(默认为 "default")
homepage:文档 URL
requires:可选要求
- bins:PATH 上所需的二进制文件(例如,["git", "node"])
- anyBins:至少必须存在这些二进制文件之一
- env:所需的环境变量
- config:所需的配置路径(例如,["workspace.dir"])
- os:所需平台(例如,["darwin", "linux"])
always:绕过资格检查(布尔值)
install:安装方法(用于捆绑钩子:[{"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,          // 会话标识符
  timestamp: Date,             // 事件发生时间
  messages: string[],          // 将消息推送到此处以发送给用户
  context: {
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // 例如,'whatsapp', 'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: OpenClawConfig
  }
}

事件类型

命令事件

在发出代理命令时触发:

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

代理事件

agent:bootstrap:在注入工作区引导文件之前(钩子可以修改 context.bootstrapFiles)

网关事件

在网关启动时触发:

gateway:startup:通道启动并加载钩子后

工具结果钩子(插件 API)

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

tool_result_persist:在工具结果写入会话记录之前转换它们。必须是同步的;返回更新的工具结果有效载荷或 undefined 以保持原样。请参阅代理循环。

未来事件

计划的事件类型:

session:start:新会话开始时
session:end:会话结束时
agent:error:代理遇到错误时
message:sent:发送消息时
message:received:接收消息时

创建自定义钩子

1. 选择位置

工作区钩子(<workspace>/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"]}}
---

# My Custom 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. 启用和测试

# 验证钩子已被发现
openclaw hooks list

# 启用它
openclaw hooks enable my-hook

# 重启您的网关进程(macOS 上的菜单栏应用程序重启,或重启您的开发进程)

# 触发事件
# 通过您的消息通道发送 /new

配置

新配置格式(推荐)

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

每个钩子的配置

钩子可以有自定义配置:

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

额外目录

从其他目录加载钩子:

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

迁移:对新钩子使用基于发现的新系统。旧处理程序在基于目录的钩子之后加载。

CLI 命令

列出钩子

# 列出所有钩子
openclaw hooks list

# 仅显示合格钩子
openclaw hooks list --eligible

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

# JSON 输出
openclaw hooks list --json

钩子信息

# 显示有关钩子的详细信息
openclaw hooks info session-memory

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

检查资格

# 显示资格摘要
openclaw hooks check

# JSON 输出
openclaw hooks check --json

启用/禁用

# 启用钩子
openclaw hooks enable session-memory

# 禁用钩子
openclaw hooks disable command-logger

捆绑钩子

session-memory

当您发出 /new 时,将会话上下文保存到内存。事件:command:new 要求:必须配置 workspace.dir 输出:<workspace>/memory/YYYY-MM-DD-slug.md(默认为 ~/.openclaw/workspace) 它做什么:

使用重置前的会话条目定位正确的记录
提取最后 15 行对话
使用 LLM 生成描述性文件名缩写
将会话元数据保存到日期内存文件

示例输出:

# 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 它做什么:

捕获事件详细信息(命令操作、时间戳、会话键、发送者 ID、来源)
以 JSONL 格式附加到日志文件
在后台静默运行

示例日志条目:

{"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_EVIL.md 交换注入的 SOUL.md 内容。事件:agent:bootstrap 文档:SOUL Evil 钩子输出:不写入文件;交换仅在内存中发生。启用:

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

当网关启动时运行 BOOT.md(通道启动后)。必须启用内部钩子才能运行此钩子。事件:gateway:startup 要求:必须配置 workspace.dir 它做什么:

从您的工作区读取 BOOT.md
通过代理运行器运行指令
通过消息工具发送任何请求的出站消息

启用:

openclaw hooks enable boot-md

最佳实践

保持处理程序快速

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

// ✓ 好 - 异步工作,立即返回
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"]}}      # 通用 - 更多开销

调试

启用钩子日志记录

网关在启动时记录钩子加载:

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

检查发现

列出所有已发现的钩子:

openclaw hooks list --verbose

检查注册

在您的处理程序中,记录何时被调用:

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

验证资格

检查钩子为什么不合格:

openclaw hooks info my-hook

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

测试

网关日志

监控网关日志以查看钩子执行:

# macOS
./scripts/clawlog.sh -f

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

直接测试钩子

单独测试您的处理程序:

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:在网关启动时加载钩子
src/auto-reply/reply/commands-core.ts:触发命令事件

发现流程

网关启动
    ↓
扫描目录(工作区 → 托管 → 捆绑)
    ↓
解析 HOOK.md 文件
    ↓
检查资格(bins, env, config, os)
    ↓
从合格钩子加载处理程序
    ↓
为事件注册处理程序

事件流

用户发送 /new
    ↓
命令验证
    ↓
创建钩子事件
    ↓
触发钩子(所有注册的处理程序)
    ↓
命令处理继续
    ↓
会话重置

故障排除

钩子未被发现

检查目录结构:

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

验证 HOOK.md 格式:

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

列出所有已发现的钩子:
```
openclaw hooks list
```

钩子不合格

检查要求:

openclaw hooks info my-hook

查找缺少的:

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

钩子未执行

验证钩子已启用:

openclaw hooks list
# 已启用的钩子旁边应显示 ✓

重启您的网关进程以重新加载钩子。
检查网关日志中的错误:
```
./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"
        }
      ]
    }
  }
}

之后:

创建钩子目录:

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

创建 HOOK.md:

---
name: my-hook
description: "我的自定义钩子"
metadata: {"openclaw":{"emoji":"🎯","events":["command:new"]}}
---

# My Hook

做一些有用的事情。

更新配置:

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

验证并重启您的网关进程:

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

迁移的好处:

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

开始使用

帮助

安装与更新

CLI

核心概念

Gateway 与运维

Web 与界面

Channels

Providers

自动化与 Hooks

Tools 与 Skills

Nodes 与媒体

平台

macOS Companion App

参考与模板

​钩子

​入门指导

​概述

​入门

​捆绑钩子

​入职

​钩子发现

​钩子包(npm/archives)

​钩子结构

​HOOK.md 格式

​元数据字段

​处理程序实现

​事件上下文

​事件类型

​命令事件

​代理事件

​网关事件

​工具结果钩子(插件 API)

​未来事件

​创建自定义钩子

​1. 选择位置

​2. 创建目录结构

​3. 创建 HOOK.md

​4. 创建 handler.ts

​5. 启用和测试

​配置

​新配置格式(推荐)

​每个钩子的配置

​额外目录

​旧配置格式(仍受支持)

​CLI 命令

​列出钩子

​钩子信息

​检查资格

​启用/禁用

​捆绑钩子

​session-memory

​command-logger

​soul-evil

​boot-md

​最佳实践

​保持处理程序快速

​优雅地处理错误

​尽早过滤事件

​使用特定事件键

​调试

​启用钩子日志记录

​检查发现

​检查注册

​验证资格

​测试

​网关日志

​直接测试钩子

​架构

​核心组件

​发现流程

​事件流

​故障排除

​钩子未被发现

​钩子不合格

​钩子未执行

​处理程序错误

​迁移指南

​从旧配置到发现

​另请参阅

钩子

入门指导

概述

入门

捆绑钩子

入职

钩子发现

钩子包(npm/archives)

钩子结构

HOOK.md 格式

元数据字段

处理程序实现

事件上下文

事件类型

命令事件

代理事件

网关事件

工具结果钩子(插件 API)

未来事件

创建自定义钩子

1. 选择位置

2. 创建目录结构

3. 创建 HOOK.md

4. 创建 handler.ts

5. 启用和测试

配置

新配置格式(推荐)

每个钩子的配置

额外目录

旧配置格式(仍受支持)

CLI 命令

列出钩子

钩子信息

检查资格

启用/禁用

捆绑钩子

session-memory

command-logger

soul-evil

boot-md

最佳实践

保持处理程序快速

优雅地处理错误

尽早过滤事件

使用特定事件键

调试

启用钩子日志记录

检查发现

检查注册

验证资格

测试

网关日志

直接测试钩子

架构

核心组件

发现流程

事件流

故障排除

钩子未被发现

钩子不合格

钩子未执行

处理程序错误

迁移指南

从旧配置到发现

另请参阅