文档
Hooks

Hooks

适用范围

使用本页面当：

  • 您想要 /new、/reset、/stop 和 agent 生命周期事件的事件驱动自动化
  • 您想要构建、安装或调试 hooks

Hooks 提供了一个可扩展的事件驱动系统，用于自动化响应 agent 命令和事件的操作。Hooks 从目录中自动发现，可以通过 CLI 命令管理，类似于 Moltbot 中 skills 的工作方式。

了解基础知识

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

  • Hooks（此页面）：当 agent 事件触发时在网关内运行，例如 /new、/reset、/stop 或生命周期事件。
  • Webhooks：外部 HTTP webhook，允许其他系统在 Moltbot 中触发工作。参见 Webhook Hooks 或使用 moltbot webhooks 进行 Gmail 辅助命令。

Hooks 也可以在插件内捆绑；参见 Plugins。

常见用途：

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

如果您可以编写一个小型 TypeScript 函数，就可以编写 hook。Hooks 是自动发现的，您可以通过 CLI 启用或禁用它们。

概述

hooks 系统允许您：

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

入门指南

捆绑的 Hooks

Moltbot 附带了四个自动发现的捆绑 hook：

  • 💾 session-memory：当您发出 /new 时将会话上下文保存到 agent 工作区（默认 ~/clawd/memory/）
  • 📝 command-logger：将所有命令事件记录到 ~/.moltbot/logs/commands.log
  • 🚀 boot-md：在网关启动时运行 BOOT.md（需要启用内部 hooks）
  • 😈 soul-evil：在清除窗口期间或通过随机机会将注入的 SOUL.md 内容交换为 SOUL_EVIL.md

列出可用的 hooks：

moltbot hooks list

启用一个 hook：

moltbot hooks enable session-memory

检查 hook 状态：

moltbot hooks check

获取详细信息：

moltbot hooks info session-memory

入门引导

在入门引导期间（moltbot onboard），系统会提示您启用推荐的 hooks。向导会自动发现符合条件的 hooks 并显示它们供您选择。

Hook 发现

Hooks 从三个目录中自动发现（按优先级顺序）：

  1. 工作区 hooks：<workspace>/hooks/（每个 agent，最高优先级）
  2. 托管 hooks：~/.moltbot/hooks/（用户安装，跨工作区共享）
  3. 捆绑 hooks：<moltbot>/dist/hooks/bundled/（随 Moltbot 提供）

托管的 hook 目录可以是单个 hook或hook 包（包目录）。

每个 hook 是一个包含以下内容的目录：

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

Hook 包（npm/档案）

Hook 包是标准 npm 包，通过 package.json 中的 moltbot.hooks 导出一个或多个 hooks。使用以下命令安装：

moltbot hooks install <path-or-spec>

示例 package.json：

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

每个条目指向一个包含 HOOK.md 和 handler.ts（或 index.ts）的 hook 目录。Hook 包可以附带依赖项；它们将安装在 ~/.moltbot/hooks/<id> 下。

Hook 结构

HOOK.md 格式

HOOK.md 文件包含 YAML frontmatter 中的元数据加上 Markdown 文档：

---
name: my-hook
description: "Short description of what this hook does"
homepage: https://docs.clawd.bot/hooks#my-hook
metadata: {"moltbot":{"emoji":"🔗","events":["command:new"],"requires":{"bins":["node"]}}}
---

# My Hook

Detailed documentation goes here...

## What It Does

- Listens for `/new` commands
- Performs some action
- Logs the result

## Requirements

- Node.js must be installed

## Configuration

No configuration needed.

元数据字段

metadata.moltbot 对象支持：

  • 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：安装方法（对于捆绑 hooks：[{"id":"bundled","kind":"bundled"}]）

Handler 实现

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

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

const myHandler: HookHandler = async (event) => {
  // Only trigger on 'new' command
  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()}`);

  // Your custom logic here

  // Optionally send message to user
  event.messages.push('✨ My hook executed!');
};

export default myHandler;

事件上下文

每个事件包括：

{
  type: 'command' | 'session' | 'agent' | 'gateway',
  action: string,              // e.g., 'new', 'reset', 'stop'
  sessionKey: string,          // Session identifier
  timestamp: Date,             // When the event occurred
  messages: string[],          // Push messages here to send to user
  context: {
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // e.g., 'whatsapp', 'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: MoltbotConfig
  }
}

事件类型

命令事件

发出 agent 命令时触发：

  • command：所有命令事件（通用侦听器）
  • command:new：发出 /new 命令时
  • command:reset：发出 /reset 命令时
  • command:stop：发出 /stop 命令时

Agent 事件

  • agent:bootstrap：在注入工作区引导文件之前（hooks 可以改变 context.bootstrapFiles）

网关事件

网关启动时触发：

  • gateway:startup：频道启动并且 hooks 加载后

工具结果 Hooks（插件 API）

这些 hooks 不是事件流侦听器；它们允许插件在 Moltbot 持久化工具结果之前同步调整它们。

  • tool_result_persist：在将工具结果写入会话记录之前转换工具结果。必须是同步的；返回更新的工具结果有效负载或 undefined 以保持原样。参见 Agent Loop。

未来事件

计划的事件类型：

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

创建自定义 Hooks

1. 选择位置

  • 工作区 hooks（<workspace>/hooks/）：每个 agent，最高优先级
  • 托管 hooks（~/.moltbot/hooks/）：跨工作区共享

2. 创建目录结构 

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

3. 创建 HOOK.md 

---
name: my-hook
description: "Does something useful"
metadata: {"moltbot":{"emoji":"🎯","events":["command:new"]}}
---

# My Custom Hook

This hook does something useful when you issue `/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!');
  // Your logic here
};

export default handler;

5. 启用和测试 

# Verify hook is discovered
moltbot hooks list

# Enable it
moltbot hooks enable my-hook

# Restart your gateway process (menu bar app restart on macOS, or restart your dev process)

# Trigger the event
# Send /new via your messaging channel

配置

新配置格式（推荐） 

{
  "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 使用新的基于发现的系统。传统 handlers 在基于目录的 hooks 之后加载。

CLI 命令

列出 Hooks 

# List all hooks
moltbot hooks list

# Show only eligible hooks
moltbot hooks list --eligible

# Verbose output (show missing requirements)
moltbot hooks list --verbose

# JSON output
moltbot hooks list --json

Hook 信息 

# Show detailed info about a hook
moltbot hooks info session-memory

# JSON output
moltbot hooks info session-memory --json

检查资格 

# Show eligibility summary
moltbot hooks check

# JSON output
moltbot hooks check --json

启用/禁用 

# Enable a hook
moltbot hooks enable session-memory

# Disable a hook
moltbot hooks disable command-logger

捆绑的 Hooks

session-memory

当您发出 /new 时将会话上下文保存到内存。

事件：command:new

要求：必须配置 workspace.dir

输出：<workspace>/memory/YYYY-MM-DD-slug.md（默认为 ~/clawd）

它的作用：

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

示例输出：

# 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 生成失败，则回退时间戳）

启用：

moltbot hooks enable session-memory

command-logger

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

事件：command

要求：无

输出：~/.moltbot/logs/commands.log

它的作用：

  1. 捕获事件详细信息（命令操作、时间戳、会话密钥、发送者 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"}

查看日志：

# View recent commands
tail -n 20 ~/.moltbot/logs/commands.log

# Pretty-print with jq
cat ~/.moltbot/logs/commands.log | jq .

# Filter by action
grep '"action":"new"' ~/.moltbot/logs/commands.log | jq .

启用：

moltbot hooks enable command-logger

soul-evil

在清除窗口期间或通过随机机会将注入的 SOUL.md 内容交换为 SOUL_EVIL.md。

事件：agent:bootstrap

文档：SOUL Evil Hook

输出：不写入文件；交换仅在内存中进行。

启用：

moltbot 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（频道启动后）。 必须启用内部 hooks 才能运行此程序。

事件：gateway:startup

要求：必须配置 workspace.dir

它的作用：

  1. 从工作区读取 BOOT.md
  2. 通过 agent 运行程序运行指令
  3. 通过消息工具发送任何请求的出站消息

启用：

moltbot hooks enable boot-md

最佳实践

保持 Handlers 快速

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

// ✓ Good - async work, returns immediately
const handler: HookHandler = async (event) => {
  void processInBackground(event); // Fire and forget
};

// ✗ Bad - blocks command processing
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));
    // Don't throw - let other handlers run
  }
};

尽早过滤事件

如果事件不相关，则提前返回：

const handler: HookHandler = async (event) => {
  // Only handle 'new' commands
  if (event.type !== 'command' || event.action !== 'new') {
    return;
  }

  // Your logic here
};

使用特定的事件键

尽可能在元数据中指定精确的事件：

metadata: {"moltbot":{"events":["command:new"]}}  # Specific

而不是：

metadata: {"moltbot":{"events":["command"]}}      # General - more overhead

调试

启用 Hook 日志记录

网关在启动时记录 hook 加载情况：

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

检查发现

列出所有发现的 hooks：

moltbot hooks list --verbose

检查注册

在您的 handler 中，记录调用时间：

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

验证资格

检查 hook 为什么不符合资格：

moltbot hooks info my-hook

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

测试

网关日志

监控网关日志以查看 hook 执行情况：

# macOS
./scripts/clawlog.sh -f

# Other platforms
tail -f ~/.moltbot/gateway.log

直接测试 Hooks

隔离测试您的 handlers：

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);

  // Assert side effects
});

架构

核心组件

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

发现流程 

网关启动
    ↓
扫描目录（工作区 → 托管 → 捆绑）
    ↓
解析 HOOK.md 文件
    ↓
检查资格（bins、env、config、os）
    ↓
从符合条件的 hooks 加载 handlers
    ↓
为事件注册 handlers

事件流程 

用户发送 /new
    ↓
命令验证
    ↓
创建 hook 事件
    ↓
触发 hook（所有已注册的 handlers）
    ↓
命令处理继续
    ↓
会话重置

故障排除

Hook 未发现

  1. 检查目录结构：

    ls -la ~/.moltbot/hooks/my-hook/
# Should show: HOOK.md, handler.ts

  2. 验证 HOOK.md 格式：

    cat ~/.moltbot/hooks/my-hook/HOOK.md
# Should have YAML frontmatter with name and metadata

  3. 列出所有发现的 hooks：

    moltbot hooks list

Hook 不符合资格

检查要求：

moltbot hooks info my-hook

查找缺少：

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

Hook 未执行

  1. 验证 hook 是否启用：

    moltbot hooks list
# Should show ✓ next to enabled hooks

  2. 重启您的网关进程以便 hooks 重新加载。

  3. 检查网关日志中的错误：

    ./scripts/clawlog.sh | grep hook

Handler 错误

检查 TypeScript/导入错误：

# Test import directly
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 ~/.moltbot/hooks/my-hook
mv ./hooks/handlers/my-handler.ts ~/.moltbot/hooks/my-hook/handler.ts

  2. 创建 HOOK.md：

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

# My Hook

Does something useful.

  3. 更新配置：

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

  4. 验证并重启您的网关进程：

    moltbot hooks list
# Should show: 🎯 my-hook ✓

迁移的好处：

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

另请参阅

Date & TimeLogging