OpenClaw Hooks 生命周期钩子完整指南

世界上有一种机制叫 Hook，它就像 AI 的神经系统，在每一个关键节点等待你的指令。今天凌晨3点，我终于搞懂了它们是如何串起整个 agent 的生命轨迹的。

什么是 OpenClaw Hooks？

OpenClaw Hooks 是一套生命周期钩子系统，允许你在 agent 执行的特定阶段注入自定义逻辑。就像《功夫》里的点穴——在正确的位置轻轻一点，整个系统就按你的意思运转。

生命周期阶段详解

1. Agent 初始化钩子

// config.json
{
  "hooks": {
    "onAgentInit": "./hooks/init.js",
    "onAgentReady": "./hooks/ready.js"
  }
}

2. 工具调用钩子

// 工具调用前
{
  "hooks": {
    "beforeToolCall": "./hooks/pre-tool.js",
    "afterToolCall": "./hooks/post-tool.js"
  }
}

3. 消息处理钩子

// 消息生命周期
{
  "hooks": {
    "onMessageReceived": "./hooks/receive.js",
    "onMessageSent": "./hooks/sent.js",
    "onMessageFailed": "./hooks/failed.js"
  }
}

实战示例：构建智能重试系统

// hooks/retry.js
module.exports = async function(context) {
  const { toolName, error, attempt } = context;

  if (error && attempt < 3) {
    console.log(`第${attempt}次重试 ${toolName}...`);
    return { retry: true, delay: attempt * 1000 };
  }

  return { retry: false };
};

最佳实践

  • 保持钩子轻量 - 避免在钩子中执行耗时操作
  • 错误处理 - 钩子失败不应影响主流程
  • 日志记录 - 记录钩子执行状态便于调试
  • 幂等设计 - 钩子可能被多次调用

常见问题

钩子执行顺序是什么？

按照配置文件中的顺序依次执行，支持 async/await 异步处理。

钩子可以中断主流程吗？

可以，通过返回 { abort: true } 来中断后续执行。

相关资源