> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/08_automation_ops/8.1_hooks.md).

# 8.1 Hooks 生命周期与事件切入点

本节讨论 Hooks 的工程落点：把治理逻辑从主执行链解耦出来，并保证 Hook 自身不会成为新故障源。先从 OpenClaw 提供的具体 Hook 能力入手，再展开设计模式与稳定性约束。

## 8.1.1 Hooks 的职责边界

Hooks 适合承载横切能力，而不是业务主流程。常见场景包括：

* 输入治理：限流、黑白名单、格式校验。
* 执行观测：工具调用审计、风险打标、策略记录。
* 输出治理：脱敏、格式收敛、审计补充字段。

边界原则：Hook 负责“治理与观测”，主链负责“任务推进”。

## 8.1.2 OpenClaw 的 Hook 机制与当前配置入口

在当前版本中，Hook 是 Gateway 内部事件上的目录式扩展点。Hook 包含 `HOOK.md` 与 `handler.ts`，可来自 OpenClaw bundled、插件、托管安装目录或 workspace 目录；启用、检查和诊断入口统一走 `openclaw hooks`。

常用命令包括：

* `openclaw hooks list`
* `openclaw hooks info <hook>`
* `openclaw hooks check`
* `openclaw hooks enable <hook>`
* `openclaw hooks disable <hook>`

也就是说，当前版本更稳妥的理解方式是：**Hook 是 Gateway 生命周期中的可发现切入点，配置层的 `hooks.internal.entries` 只是一部分启用状态，不应被理解成“当前版本只有固定两个内置项”**。是否存在更多 entry、附加目录加载或安装记录，应以本地版本的 `openclaw hooks list`、`config schema`、`--help` 与官方文档为准。

当前实例可直接观察到的最小配置形态如下：

```jsonc
{
  hooks: {
    internal: {
      enabled: true,
      entries: {
        "session-memory": { enabled: true },
        "boot-md": { enabled: true }
      }
    }
  }
}
```

此外，OpenClaw 的工具策略（`tools.deny`/`tools.allow`，详见 [5.2](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/05_tools_skills/5.2_tool_policy.md)）和结构化日志事件（`openclaw logs --follow --json`）提供了补充性的治理与观测能力，与 Hook 机制协同工作。

> \[!NOTE] Hook 加载取决于是否启用、配置或开启广泛发现。排障时先用 `openclaw hooks list/info/check` 确认实际发现与启用状态，再结合 `doctor` 与结构化日志定位问题。

## 8.1.3 事件切入模型：先按官方事件定位，再映射治理职责

OpenClaw 的内部 Hook 不是固定的“输入 / 执行 / 输出”三段枚举，而是围绕具体事件触发。当前内部事件包括 `command:new`、`command:reset`、`command:stop`、`command`、`session:compact:before`、`session:compact:after`、`session:patch`、`agent:bootstrap`、`gateway:startup`、`gateway:shutdown`、`gateway:pre-restart`、`message:received`、`message:transcribed`、`message:preprocessed`、`message:sent`。工程上仍可把治理职责映射为输入治理、执行观测、输出治理三类，但排障和配置时要回到本机 `openclaw hooks list/info/check` 输出的真实事件名。

```mermaid
flowchart LR
  subgraph input["输入段"]
    I1["限流/黑白名单"] --> I2["格式校验"]
  end
  subgraph exec["执行段"]
    E1["工具调用审计"] --> E2["风险打标"]
  end
  subgraph output["输出段"]
    O1["脱敏"] --> O2["格式收敛"]
  end

  req["入口请求"] --> input
  input -->|"准入通过"| main["主链路推理"]
  main --> exec
  exec --> result["生成结果"]
  result --> output
  output --> resp["回传响应"]
  input -->|"插件决策 Hook 可拦截"| reject["早拒绝"]
```

图 8-1：Hooks 在主链路三段生命周期中的切入点

| 阶段  | 目标                        | 禁止事项          |
| --- | ------------------------- | ------------- |
| 输入段 | 降噪、准入校验；若使用插件决策 Hook，可早拒绝 | 长耗时外部调用、不可逆写入 |
| 执行段 | 记录关键决策、风险拦截               | 改写核心业务状态      |
| 输出段 | 脱敏和格式治理                   | 临时扩权、绕过策略放行   |

## 8.1.4 稳定性约束：超时、降级、幂等

Hook 本身必须受约束，否则会拖垮主链。

* 超时上限：每个 Hook 都要有独立超时，超时后按策略降级。
* 失败语义：内部 Hook 返回 `void`，主要通过追加消息或修改事件内容做观测/补充，异常会被记录且不应阻断后续 handler；需要 block、cancel、override 或 require approval 时，应使用支持决策结果的 typed plugin hooks。
* 幂等要求：重试情况下不得产生重复外部副作用。

对审计类内部 Hook，建议保持轻量并告警；对合规拦截类逻辑，应使用插件决策 Hook，并显式设计 block / fail-open / fail-closed 语义。

## 8.1.5 结构化事件：保证可审计与可回放

建议所有 Hook 事件使用统一结构，最少包含：时间、链路、阶段、动作、结果。

```jsonc
{
  "ts": "YYYY-MM-DDTHH:MM:SSZ",
  "traceId": "t-YYYYMMDD-001",
  "stage": "input",
  "hook": "rate_limit_guard",
  "event": "rejected",
  "reason": "rate_limit_exceeded"
}
```

## 8.1.6 验收与排障

上线后建议固定做两类检查：

1. 正常流量：确认 Hook 不引入明显时延。
2. 异常流量：确认拦截和降级行为符合预期。

```bash
openclaw status --deep
openclaw logs --json --limit 500 \
  | jq -r 'select(.type=="log") | (.raw | fromjson? // {}) | .event // empty' \
  | sort | uniq -c | sort -nr | head
```

> 注意：实际字段名请以 `logs --json` 输出为准。建议验收前先“不带过滤规则”打印一条原始日志，明确具体的日志字段结构，再运用 `jq` 过滤。