Skip to content

Bot Hooks ​

Bot Hooks 可以让 Bot 在工具调用、对话 turn、记忆、workspace 活动、审批、压缩和 subagent 等流程前后运行小型自动化规则。每个 Bot 都有自己的配置文件:

text
/data/.memoh/hooks.json

打开 Bot 详情页,进入 Hooks tab,就可以从 UI 编辑这个文件。


Hooks Tab ​

Hooks tab 是 Bot hook 配置的 JSON 编辑器。它可以:

  • 显示 /data/.memoh/hooks.json 是否存在
  • 显示用户配置是否启用
  • 统计已启用 hook 和 action 数量
  • 列出支持的事件目录
  • 标出哪些事件已经接入运行时
  • 重新加载和保存 JSON 配置
  • 插入起步模板
  • 用一条合成事件测试当前 effective hooks 配置

如果文件不存在,UI 和服务会创建一份启用的空配置:

json
{
  "version": 1,
  "enabled": true,
  "hooks": []
}

这个 tab 不提供可视化规则构建器,需要直接编辑 JSON。


配置结构 ​

json
{
  "version": 1,
  "enabled": true,
  "defaults": {
    "timeout": "10s",
    "on_error": "fail",
    "max_output_bytes": 65536,
    "trigger_nested_hooks": false
  },
  "env": {
    "HOOK_LOG": "/data/.memoh/hooks.log"
  },
  "hooks": [
    {
      "name": "review shell commands",
      "event": "PreToolUse",
      "matcher": "^exec$",
      "enabled": true,
      "priority": 10,
      "actions": [
        {
          "type": "command",
          "command": "python3 /data/.memoh/review-command.py",
          "timeout": "5s",
          "on_error": "block"
        }
      ]
    }
  ]
}

顶层字段:

字段说明
version必填的 schema 版本。当前版本为 1。
enabled启用或停用这个用户配置文件里的 hooks。默认 true。
defaults.timeout默认 action 超时时间。支持 10s 这类 Go duration,也支持整数秒。默认 10s。
defaults.on_error默认错误处理:ignore、fail 或 block。默认 fail。
defaults.max_output_bytes每个 command action 捕获 stdout/stderr 的最大字节数。默认 65536。
defaults.trigger_nested_hooksschema 会解析这个字段,默认 false;Hooks UI 目前没有单独控件。
env用户配置里的 command action 会使用的额外环境变量。
hooks规则列表。命中后按 priority 从高到低运行,同优先级保持文件顺序。

Hook 字段:

字段说明
name可选的展示/调试名称。
event必填,必须来自事件目录。
matcher可选正则表达式,会匹配请求里的最佳目标文本。
enabled启用或停用这个 hook。默认 true。
priority数字越大越先运行。
actionshook 命中后要运行的 action。
conditionsschema 中保留给未来扩展;目前匹配时使用 event、enabled 和 matcher。

matcher 的目标文本按下面顺序从 hook 请求里选择:

  • tool.name
  • approval.tool_name
  • channel.platform
  • memory.scope
  • extra.command、extra.path、extra.operation 或 extra.scope
  • 事件名称

Action 类型 ​

目前支持两类 action:command 和 tool。

Command Action ​

json
{
  "type": "command",
  "command": "mkdir -p .memoh && cat >> .memoh/hooks.log",
  "work_dir": "/data",
  "timeout": "10s",
  "on_error": "ignore"
}

command action 会在 Bot workspace 容器内运行。hook 请求会作为 JSON 通过 stdin 传入,末尾带换行。

工作目录解析顺序:

  1. action.work_dir
  2. 请求里的 workspace CWD
  3. /data

环境变量包括:

  • 当前配置顶层的 env
  • MEMOH_HOOK_EVENT
  • MEMOH_HOOK_NAME
  • MEMOH_BOT_ID
  • MEMOH_SESSION_ID

如果 stdout 是 JSON,command 可以返回:

json
{
  "decision": "append_context",
  "reason": "extra context added",
  "append_context": "Use the production-safe command variant.",
  "metadata": {
    "source": "hook"
  }
}

如果 stdout 不是 JSON,Memoh 会把 action 当成 allow,并把原始 stdout 放进 action metadata。非零退出码会被视为 action 错误。

Tool Action ​

json
{
  "type": "tool",
  "tool": "record_event",
  "input": {
    "source": "hook"
  },
  "timeout": "10s",
  "on_error": "fail"
}

tool action 会按名称调用一个可用的 Bot 工具,并传入配置里的 input。如果工具结果是对象,可以返回 decision、reason 和 append_context。

mcp_tool 在代码里是保留类型,但目前会被拒绝。


决策与错误 ​

action 可以返回这些 decision:

Decision效果
allow正常继续。
deny拒绝被守卫的操作。对 PreToolUse 来说,会拒绝这次工具调用。
ask_approval在运行时支持审批接管的位置请求人工审批。
append_context在事件接入点会消费 append_context 时追加上下文,例如 prompt、model、memory 相关流程。

on_error 控制 action 失败时的行为:

值效果
ignore记录并继续下一个 action。
fail返回 action 错误。默认值。
block把失败转换为 deny decision。

事件目录 ​

Hooks tab 会从 /bots/{bot_id}/hooks/events 加载事件目录。标记为 runtime-supported 的事件已经接入当前执行路径。catalog-only 事件可以通过配置解析和测试接口,但目前没有实际的运行时路径会发出这些事件。

Event区域已接入运行时说明
PreToolUse工具是工具调用审批决策前运行。可以拒绝或要求审批。
PostToolUse工具是工具调用成功后运行。
ToolError工具是工具调用返回错误时运行。
SessionStart会话是会话创建后运行。
UserMessageReceived对话是conversation resolver 收到用户消息后运行。
BeforePromptBuildPrompt是prompt 组装前运行;append_context 可以追加到 system prompt。
AfterPromptBuildPrompt是prompt 组装后运行;append_context 可以追加到 system prompt。
BeforeModelCall模型是模型生成 step 前运行;append_context 可以作为 user message 追加。
AfterModelCall模型是模型生成 step 后运行。
TurnEndTurn是一个 turn 完成时运行。
TurnErrorTurn是一个 turn 失败时运行。
BeforeMemorySearch记忆是记忆检索前运行。
AfterMemorySearch记忆是记忆检索后运行;append_context 可以合并进记忆上下文。
BeforeMemoryWrite记忆是写入对话记忆前运行。
AfterMemoryWrite记忆是写入记忆后运行。
MemoryExtracted记忆是记忆抽取/写入准备完成后运行。
WorkspaceStartWorkspace是workspace 启动后运行。
WorkspaceStopWorkspace是workspace 停止时运行。
BeforeWorkspaceCommandWorkspace是workspace shell 命令执行前运行。可以拒绝命令。
AfterWorkspaceCommandWorkspace是workspace shell 命令执行后运行。
BeforeFileWriteWorkspace是文件写入和 patch 前运行。可以拒绝写入。
AfterFileWriteWorkspace是文件写入和 patch 后运行。
BeforeApprovalCreate审批是创建工具审批请求前运行。
ApprovalRequested审批是审批请求发出后运行。
ApprovalResolved审批是审批被处理后运行。
ApprovalTimeout审批是审批超时时运行。
PreCompact压缩是会话压缩前运行。
PostCompact压缩是会话压缩后运行。
SubagentStartSubagent是subagent 任务开始前运行。
SubagentStopSubagent是subagent 任务结束后运行。
InboundMessageNormalized消息否目前仅存在于事件目录。
BeforeOutboundMessage消息否目前仅存在于事件目录。
AfterOutboundMessage消息否目前仅存在于事件目录。
ChannelDeliveryFailed消息否目前仅存在于事件目录。

测试 Hooks ​

在 Hooks tab 的 Test 区域可以运行一条合成事件:

  1. 选择事件。
  2. 编辑 JSON payload。
  3. 点击 Run Test。
  4. 查看返回结果,包括命中的 hooks、运行的 actions、decision、action results 和 hook source metadata。

测试路径使用 effective config,并且会真正执行 action。除非你就是要验证破坏性命令或工具调用,否则不要在测试 payload 里触发它们。


安全注意事项 ​

Hooks 会在 Bot workspace 里实际执行。请把它们当成跑在那里的代码来对待。

  • 启用前审查每个 command action。
  • 小心使用 PreToolUse、BeforeWorkspaceCommand 和 BeforeFileWrite;它们可能阻断 Bot 的正常工作。
  • 保持较短 timeout,并明确设置 on_error。
  • 不要把长期有效的 secrets 直接写进 hooks.json。
  • 对高风险 hooks 使用尽量窄的 matcher。
  • 记住 command action 会通过 stdin 收到 hook 请求,其中可能包含消息文本、工具输入、路径和错误信息。

相关页面 ​

Published under AGPLv3