OpenClaw Hooks：完整的开发人员指南 (2026)

OpenClaw Hook Discovery 的工作原理

网关使用 自动目录扫描 发现钩子。启动时，它会扫描配置的钩子目录并加载它找到的任何有效的钩子包。

激活钩子之前有两个重要的先决条件：

1. 挂钩必须是 明确启用 — 仅一个钩子目录是不够的
2. 至少 必须配置一个钩子条目 在您的网关设置中

每个钩子包只需要两个文件：

• HOOK.md — 元数据文件，声明钩子的名称、版本、描述、生命周期事件订阅以及任何所需的权限
• handler.ts （或 handler.js） — 包含事件触发时运行的实际逻辑的实现文件

每个开发人员都应该了解的四个生命周期事件

预工具使用 是最强大的——这是唯一可以做到的事件 中止 执行之前的工具调用。如果您的挂钩在 PreToolUse 期间返回拒绝信号，则代理永远不会调用该工具。

后期工具使用 是自动化的主力。文件写好了吗？运行你的 linter。测试修改了？执行套件。代码已提交？触发构建。

分步：从头开始编写您的第一个自定义 Hook

大多数文档都会向您显示命令。这向您展示了从无到有的完整路径。

第 1 步 — 创建钩子目录

mkdir -p .OpenClaw/hooks/auto-lint

步骤 2 — 写入 HOOK.md 元数据

# auto-lint

**Version:** 1.0.0
**Event:** PostToolUse
**Description:** Runs ESLint on any file written by the agent
**Tools:** write_file, edit_file

Tools 字段将您的挂钩范围限定为特定工具调用。没有它，钩子就会启动 每一个 PostToolUse 事件 — 通常不是您想要的。

第 3 步 — 实施 handler.ts

import { PostToolUseEvent } from "@OpenClaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const filePath = event.toolResult?.path;
  if (!filePath) return;

  try {
    execSync(`npx eslint --fix "${filePath}"`, { stdio: "inherit" });
  } catch (err) {
    console.error(`[auto-lint] ESLint failed on ${filePath}`);
  }
}

第 4 步 — 通过 CLI 启用

OpenClaw hooks enable auto-lint

第 5 步 — 验证其已加载

OpenClaw hooks list

您应该看到 auto-lint 的状态为 enabled。启动一个会话，写入一个文件，然后观察 linter 的触发。

用于 Hook 处理程序的 JavaScript 与 TypeScript — 2026 年选择什么

SDK 附带完整的 TypeScript 类型，从 2026 SDK 版本开始， TypeScript 是推荐的默认值 用于新钩子。

如果您正在编写一个钩子，您将致力于版本控制或与团队共享，请使用 TypeScript。对于一次性的本地护栏，纯 JavaScript 就可以了——只需将其命名为 handler.js 并跳过编译步骤。

OpenClaw Hooks CLI 参考

管理 Hook Pack — 安装、更新和 --dry-run 工作流程

Hook 包将多个相关的 hook 捆绑为一个可安装单元。安装工作流程验证 完整性哈希 在将任何内容写入磁盘之前。

# Preview what would be installed without committing
OpenClaw hooks install productivity-pack --dry-run

# Install non-interactively (for CI environments)
OpenClaw hooks install productivity-pack --yes

# Update all installed packs
OpenClaw hooks update --all

捆绑 Hook 参考：OpenClaw 附带什么

运行 OpenClaw hooks inspect session-memory 以查看其完整配置选项。大多数捆绑的钩子都附带合理的默认值，但会公开配置字段以进行自定义。

真实世界的 Hook 用例（带有工作示例）

1. 文件保护护栏（PreToolUse）

防止代理接触您的 .env 文件：

import { PreToolUseEvent } from "@OpenClaw/sdk";

export default function handler(event: PreToolUseEvent) {
  const target = event.toolInput?.path ?? "";
  if (target.includes(".env")) {
    return { abort: true, reason: "Modification of .env files is blocked by policy." };
  }
}

将其放入 .OpenClaw/hooks/protect-env/ 中，并与订阅 PreToolUse 的匹配 HOOK.md 范围为 write_file 和 edit_file。代理在其上下文中收到拒绝原因，并且不会重试。

2. 会话停止时的 Slack 通知

import { StopEvent } from "@OpenClaw/sdk";

export default async function handler(event: StopEvent) {
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `OpenClaw session ended. Files modified: ${event.session.filesModified ?? 0}`
    })
  });
}

将此挂钩订阅 Stop 事件。每个会话结束都会触发一条带有摘要的 Slack 消息。不需要外部服务器——网关进程直接发出出站请求。

3. 自动格式化+PostToolUse测试

import { PostToolUseEvent } from "@OpenClaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const file = event.toolResult?.path;
  if (!file?.endsWith(".ts")) return;

  execSync(`prettier --write "${file}"`);
  execSync("npm test -- --passWithNoTests", { stdio: "inherit" });
}

在每个 TypeScript 文件写入、格式化、然后运行测试套件后都会触发此事件。大型项目速度缓慢 - 使用 HOOK.md 中的 Tools 字段严格限制其范围。

团队的钩子——在共享项目中加强护栏

将 .OpenClaw/hooks/ 目录提交给版本控制。每个自动克隆存储库的开发人员都具有相同的钩子配置。

• 将关键挂钩锁定到项目配置中的 enabled — 防止队友意外禁用文件防护
• 使用 HOOK.md 描述来记录意图 — 将它们视为代码注释，队友会阅读它们
• 范围挂钩工具级粒度 - 宽钩会减慢所有代理交互，产生摩擦，导致队友禁用它们
• 在 monorepos 中，父目录中的钩子适用于所有嵌套项目，除非在子目录级别覆盖

CI/CD 集成 — 以非交互方式运行 OpenClaw Hooks

在 GitHub Actions 或任何无头环境中，交互式确认提示将挂起您的管道。使用 --yes 跳过它：

- name: Install hooks non-interactively
  run: OpenClaw hooks install qa-pack --yes

- name: Run OpenClaw session
  env:
    OpenClaw_HOOKS_ENABLED: "true"
    SLACK_WEBHOOK_URL: secrets.SLACK_WEBHOOK_URL
  run: OpenClaw run --task "audit dependencies" --yes

Hook 安全性：运行的内容、可以访问的内容以及如何保持安全

这是大多数文档完全跳过的部分 - 如果您要安装社区挂钩包，这是最重要的部分。

哪些钩子可以访问： Hook 脚本继承 Gateway进程的全部权限。如果网关以您的用户帐户运行，您的挂钩可以读取该帐户可以读取的任何文件、发出网络请求、执行子进程以及访问包括机密在内的环境变量。

钩包审核清单

在安装任何第三方包之前运行此操作：

OpenClaw hooks inspect 命令显示已安装挂钩的完整源路径 - 使用它在更新后重新审查处理程序代码。

OpenClaw 钩子不触发时的故障排除

常见问题解答

最后的想法 - 为您的工作流程选择正确的 Hook 策略

从解决真正难题的一个钩子开始——文件保护或写入后的 linter。在分层之前先让它端到端地工作。钩子的力量是复合的：具有三个范围良好的钩子的会话平稳运行比具有十个您不信任的范围较小的钩子的会话要可靠得多。