这里写自定义目录标题
欢迎使用Markdown编辑器
背景/痛点
在 openclaw 项目做深之后，很多问题不会出现在"能不能跑起来"这一层，而是出现在"如何把框架行为管住"。比如：
每次任务执行前都要校验租户权限；
模型调用前要自动注入 traceId；
工具执行后要记录耗时和输入输出摘要；
异常发生时要统一上报，而不是散落在业务代码里；
框架关闭前要释放连接池、缓存句柄、临时文件。
如果这些逻辑全部写在业务流程中，代码很快会变成"面条式编排"：主链路里夹杂大量日志、监控、鉴权、限流、兜底逻辑。短期能跑，长期不可维护。
openclaw 的钩子函数适合解决这类问题。它的价值不在于"多一个扩展点"，而在于把横切逻辑从业务链路中剥离出来，让框架生命周期中的关键节点可以被我们接管。
核心内容讲解
钩子函数本质上是生命周期回调。openclaw 在执行不同阶段时，会主动调用我们注册的函数。常见阶段可以抽象为：
阶段
典型用途
onInit
初始化配置、加载环境变量、创建客户端
beforeRun
参数校验、权限判断、上下文补全
beforeToolCall
工具调用前限流、审计、参数改写
afterToolCall
记录耗时、清洗结果、写入指标
onError
异常收敛、告警、错误包装
onShutdown
释放资源、关闭连接
我个人更推荐把 hook 当成"框架治理层"，而不是业务逻辑层。举个反例：把订单创建逻辑写进 beforeRun ，这就很危险，因为后续排查问题时会发现业务状态变化隐藏在生命周期里，定位成本非常高。
比较合理的边界是：
hook 负责增强、校验、观测、兜底；
service 负责业务计算和状态变更；
tool 负责外部能力封装；
agent/workflow 负责流程编排。
这样拆分之后，后期加监控、灰度、审计，都不会频繁修改核心业务代码。
实战代码/案例
下面用一个偏真实的场景：我们有一个 openclaw agent，需要调用多个 tool 处理用户请求。现在希望统一实现三件事：
为每次运行生成 traceId ；
统计工具调用耗时；
异常时统一上报并返回可读错误。
示例使用 TypeScript 风格伪代码，重点看设计方式。
ts
// hooks/observabilityHook.ts
type HookContext = {
traceId?: string;
userId?: string;
input?: any;
meta?: Record ;
};
type ToolCallPayload = {
toolName: string;
args: Record ;
};
export const observabilityHook = {
async onInit(ctx: HookContext) {
// 初始化全局元信息，避免后续 hook 判断空对象
ctx.meta = ctx.meta || {};
ctx.meta.startedAt = Date.now();
console.log("[openclaw:init] framework initialized");
},
async beforeRun(ctx: HookContext) {
// 为本次执行链路生成 traceId
ctx.traceId = ctx.traceId || trace_${Date.now()}_${Math.random().toString(16).slice(2)} ;
// 参数基础校验：不建议在这里写复杂业务规则
if (!ctx.input) {
throw new Error("EMPTY_INPUT: input can not be empty");
}
console.log(`[openclaw:beforeRun] traceId=${ctx.traceId}, userId=${ctx.userId}`);
},
async beforeToolCall(ctx: HookContext, payload: ToolCallPayload) {
// 记录工具开始时间，按 toolName 分组
ctx.meta = ctx.meta || {};
ctx.meta.toolStartTime = ctx.meta.toolStartTime || {};
ctx.meta.toolStartTime[payload.toolName] = Date.now();
// 对敏感工具做参数审计
if (payload.toolName === "paymentTool") {
console.log(`[audit] traceId=${ctx.traceId}, payment args checked`);
}
// 也可以在这里做参数修正，例如统一注入 traceId
payload.args.traceId = ctx.traceId;
},
async afterToolCall(ctx: HookContext, payload: ToolCallPayload, result: any) {
const start = ctx.meta?.toolStartTime?.[payload.toolName];
const cost = start ? Date.now() - start : -1;
console.log(
`[openclaw:afterToolCall] traceId=${ctx.traceId}, tool=${payload.toolName}, cost=${cost}ms`
);
// 注意：日志中不要直接打印完整 result，避免泄露敏感数据
console.log("[tool:result:summary]", {
success: !!result,
type: typeof result
});
},
async onError(ctx: HookContext, error: Error) {
// 统一异常收敛，真实项目可接入 Sentry、Prometheus、企业微信机器人等
console.error("[openclaw:error]", {
traceId: ctx.traceId,
message: error.message,
stack: error.stack?.split("\n").slice(0, 3).join("\n")
});
// 可以选择重新包装错误，避免底层异常直接暴露给前端
return {
code: "OPENCLAW_RUNTIME_ERROR",
message: "任务执行失败，请稍后重试",
traceId: ctx.traceId
};
},
async onShutdown(ctx: HookContext) {
const totalCost = Date.now() - (ctx.meta?.startedAt || Date.now());
console.log(`[openclaw:shutdown] traceId=${ctx.traceId}, totalCost=${totalCost}ms`);
// 这里可以关闭数据库连接、缓存客户端、文件句柄等
}
};
接下来把 hook 注册到 openclaw 应用中。实际项目中我建议不要把所有 hook 写在一个文件里，而是按职责拆分，例如 authHook 、 rateLimitHook 、 observabilityHook 。
```ts
// app.ts
import { createOpenClawApp } from "openclaw";
import { observabilityHook } from "./hooks/observabilityHook";
const app = createOpenClawApp({
name: "advanced-hook-demo",
hooks: [
observabilityHook
],
tools: {
async searchTool(args: any) {
// 模拟外部检索工具
return {
query: args.query,
traceId: args.traceId,
items: ["doc1", "doc2"]
};
},
async paymentTool(args: any) {
// 模拟敏感工具调用
if (!args.amount || args.amount <= 0) {
throw new Error("INVALID_AMOUNT");
}
return {
status: "paid",
amount: args.amount
};
}
}
});
async function main() {
const result = await app.run({
userId: "u_10001",
input: {
query: "openclaw hook usage",
amount: 99
}
});
console.log("final result:", result);
}
main();
在实际落地时，还需要考虑 hook 的执行顺序。比如鉴权必须在工具调用前完成，日志 hook 可以放在更外层，异常 hook 通常要兜住所有阶段。
一个比较稳妥的注册顺序如下：
```ts
hooks: [
traceHook, // 先生成链路标识
authHook, // 再做权限判断
rateLimitHook, // 然后做限流
observabilityHook, // 记录过程指标
errorHook // 最后兜底异常
]
这里有个经验点：不要让多个 hook 同时修改同一个字段。例如 ctx.userId 如果既被 authHook 修改，又被 traceHook 修改，后期会很难排查。我的做法是约定上下文字段归属：
字段
负责 hook
traceId
traceHook
user
authHook
quota
rateLimitHook
metrics
observabilityHook
如果确实需要共享数据，建议写到明确的命名空间里：
```ts
ctx.meta = {
trace: {
traceId: "trace_xxx"
},
auth: {
userId: "u_10001",
roles: ["admin"]
},
metrics: {
startAt: Date.now()
}
};
这样虽然代码略显啰嗦，但换来的是可维护性。尤其在多人协作的 openclaw 项目中，上下文污染是非常常见的隐性问题。
总结与思考
openclaw 钩子函数最适合处理框架生命周期中的横切问题，比如日志、鉴权、限流、监控、异常收敛和资源释放。它不是为了让我们把业务逻辑藏得更深，而是为了让主流程更干净。
从商业价值看，hook 能帮助团队更快建设稳定性能力。很多企业项目并不是输在算法或模型，而是输在工程治理：出了问题无法追踪，调用成本无法统计，权限边界不清晰，异常信息直接暴露给用户。把这些能力沉淀为 hook，可以让每个 openclaw 应用天然具备可观测、可审计、可扩展的基础能力。
从程序员成长角度看，熟练使用 hook 代表你开始从"功能实现者"转向"框架治理者"。写业务代码解决的是单点问题，设计生命周期扩展点解决的是一类问题。真正有价值的工程经验，往往就藏在这些看似不起眼的治理细节里。
云盏科技官网 #小龙虾 #云盏科技 #ai技术论坛 #skills市场你好！ 这是你第一次使用 **Markdown编辑器** 所展示的欢迎页。如果你想学习如何使用Markdown编辑器, 可以仔细阅读这篇文章，了解一下Markdown的基本语法知识。
## 新的改变
我们对Markdown编辑器进行了一些功能拓展与语法支持，除了标准的Markdown编辑器功能，我们增加了如下几点新功能，帮助你用它写博客：
1. **全新的界面设计** ，将会带来全新的写作体验；
2. 在创作中心设置你喜爱的代码高亮样式，Markdown **将代码片显示选择的高亮样式** 进行展示；
3. 增加了 **图片拖拽** 功能，你可以将本地的图片直接拖拽到编辑区域直接展示；
4. 全新的 **KaTeX数学公式** 语法；
5. 增加了支持**甘特图的mermaid语法[^1]** 功能；
6. 增加了 **多屏幕编辑** Markdown文章功能；
7. 增加了 **焦点写作模式、预览模式、简洁写作模式、左右区域同步滚轮设置** 等功能，功能按钮位于编辑区域与预览区域中间；
8. 增加了 **检查列表** 功能。
[^1]: [mermaid语法说明](https://mermaid.js.org/intro/)
## 功能快捷键
撤销：<kbd>Ctrl/Command</kbd> + <kbd>Z</kbd>
重做：<kbd>Ctrl/Command</kbd> + <kbd>Y</kbd>
加粗：<kbd>Ctrl/Command</kbd> + <kbd>B</kbd>
斜体：<kbd>Ctrl/Command</kbd> + <kbd>I</kbd>
标题：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>H</kbd>
无序列表：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>U</kbd>
有序列表：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>O</kbd>
检查列表：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd>
插入代码：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd>
插入链接：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>L</kbd>
插入图片：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>G</kbd>
查找：<kbd>Ctrl/Command</kbd> + <kbd>F</kbd>
替换：<kbd>Ctrl/Command</kbd> + <kbd>G</kbd>
## 合理的创建标题，有助于目录的生成
直接输入1次<kbd>#</kbd>，并按下<kbd>space</kbd>后，将生成1级标题。
输入2次<kbd>#</kbd>，并按下<kbd>space</kbd>后，将生成2级标题。
以此类推，我们支持6级标题。有助于使用`TOC`语法后生成一个完美的目录。
## 如何改变文本的样式
*强调文本* _强调文本_
**加粗文本** __加粗文本__
==标记文本==
~~删除文本~~
> 引用文本
H~2~O is是液体。
2^10^ 运算结果是 1024.
## 插入链接与图片
链接: [link](https://www.csdn.net/).
图片: 
带尺寸的图片: 
居中的图片: 
居中并且带尺寸的图片: 
当然，我们为了让用户更加便捷，我们增加了图片拖拽功能。
## 如何插入一段漂亮的代码片
去[博客设置](https://mp.csdn.net/console/configBlog)页面，选择一款你喜欢的代码片高亮样式，下面展示同样高亮的 `代码片`.
```javascript
// An highlighted block
var foo = 'bar';生成一个适合你的列表
- 项目
- 项目
- 项目
- 项目
- 项目1
- 项目2
- 项目3
- 计划任务
- 完成任务
创建一个表格
一个简单的表格是这么创建的：
| 项目 | Value |
|---|---|
| 电脑 | $1600 |
| 手机 | $12 |
| 导管 | $1 |
设定内容居中、居左、居右
使用:---------:居中
使用:----------居左
使用----------:居右
| 第一列 | 第二列 | 第三列 |
|---|---|---|
| 第一列文本居中 | 第二列文本居右 | 第三列文本居左 |
SmartyPants
SmartyPants 是一个文本转换工具，主要功能是将普通的 ASCII 标点符号自动转换为更美观的印刷体标点符号。例如：
| 原始符号 | 转换后 | 说明 |
|---|---|---|
"引号" |
"引号" | 直引号变弯引号 |
'单引号' |
'单引号' | 直单引号变弯单引号 |
-- |
-- | 两个连字符变短破折号 |
--- |
--- | 三个连字符变长破折号 |
... |
... | 三个点变省略号 |
创建一个自定义列表
:
Text-to- conversion tool
:
John
:
Luke
如何创建一个注脚
一个具有注脚的文本。[1](#1)
注释也是必不可少的
Markdown将文本转换为 。
KaTeX数学公式
您可以使用渲染LaTeX数学表达式 KaTeX:
Gamma公式展示 Γ ( n ) = ( n − 1 ) ! ∀ n ∈ N \Gamma(n) = (n-1)!\quad\forall n\in\mathbb N Γ(n)=(n−1)!∀n∈N 是通过欧拉积分
Γ ( z ) = ∫ 0 ∞ t z − 1 e − t d t . \Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,. Γ(z)=∫0∞tz−1e−tdt.
你可以找到更多关于的信息 LaTeX 数学表达式here.
新的甘特图功能，丰富你的文章
2014-01-07 2014-01-09 2014-01-11 2014-01-13 2014-01-15 2014-01-17 2014-01-19 2014-01-21 已完成 进行中 计划一 计划二 现有任务 Adding GANTT diagram functionality to mermaid
- 关于 甘特图 语法，参考 这儿,
UML图表
可以使用UML图表进行渲染，例如下面产生的一个序列图：
王五 李四 张三 王五 李四 张三 李四想了很长时间, 文字太长了 不适合放在一行. 你好！李四, 最近怎么样? 你最近怎么样，王五？ 我很好，谢谢! 我很好，谢谢! 打量着王五... 很好... 王五, 你怎么样?
- 关于 UML图表 语法，参考 这儿,
流程图
链接
长方形
圆
圆角长方形
菱形
- 关于 Mermaid 语法，参考 这儿,
FLowchart流程图
我们依旧会支持flowchart.js的流程图语法：
Created with Raphaël 2.3.0 开始 我的操作 确认？ 结束 yes no
- 关于 Flowchart流程图 语法，参考 这儿.
导出与导入
导出
如果你想尝试使用此编辑器, 你可以在此篇文章任意编辑。当你完成了一篇文章的写作, 在上方工具栏找到 文章导出 ，生成一个.md文件或者.html文件进行本地保存。
导入
如果你想加载一篇你写过的.md文件，在上方工具栏可以选择导入功能进行对应扩展名的文件导入，
继续你的创作。
- 注脚的解释 ↩︎
*[HTML]: 超文本标记语言