Hooks（钩子）是 OpenClaw 最强大的自动化原语—— 在消息流的每个关键节点插入自定义逻辑， 无需修改核心代码，就能改变 AI 的行为。
Hooks 触发时机
消息流：
用户发消息
↓ [hook: on-message-receive] — 消息到达时
Gateway 处理
↓ [hook: before-agent-run] — AI 开始处理前
AI 运行
↓ [hook: on-tool-call] — AI 每次调用工具时
↓ [hook: after-agent-run] — AI 完成处理后
回复用户
↓ [hook: before-send] — 消息发出前
消息发出
↓ [hook: on-error] — 发生错误时
基础 Hook 配置
json
{
"hooks": {
"on-message-receive": [
{
"name": "log-all-messages",
"enabled": true,
"action": "log",
"level": "info"
}
],
"before-send": [
{
"name": "format-check",
"enabled": true,
"action": "transform",
"script": "./hooks/format-check.js"
}
]
}
}实战案例一：自动记录关键对话到 Notion
javascript
// hooks/save-to-notion.js
module.exports = async function afterAgentRun(context) {
const { message, response, channel } = context;
// 只记录包含特定关键词的对话
const keywords = ['决定', '方案', 'plan', 'decision'];
const isImportant = keywords.some(kw =>
message.text.includes(kw) || response.text.includes(kw)
);
if (!isImportant) return;
await fetch('https://api.notion.com/v1/pages', {
method: 'POST',
headers: {
'Authorization': 'Bearer ' + process.env.NOTION_TOKEN,
'Notion-Version': '2022-06-28',
'Content-Type': 'application/json',
},
body: JSON.stringify({
parent: { database_id: process.env.NOTION_DB_ID },
properties: {
Title: { title: [{ text: { content: message.text.slice(0, 50) } }] },
Channel: { select: { name: channel } },
Date: { date: { start: new Date().toISOString() } },
}
})
});
};配置：
json
{
"hooks": {
"after-agent-run": [
{
"name": "save-to-notion",
"script": "./hooks/save-to-notion.js"
}
]
}
}实战案例二：收到紧急关键词立即推送通知
javascript
// hooks/urgent-alert.js
module.exports = async function onMessageReceive(context) {
const urgentKeywords = ['紧急', 'urgent', 'ASAP', '宕机', 'down'];
const isUrgent = urgentKeywords.some(kw =>
context.message.text.toLowerCase().includes(kw.toLowerCase())
);
if (!isUrgent) return;
// 通过 Bark 推送到手机
const key = process.env.BARK_KEY;
const msg = encodeURIComponent(context.message.text.slice(0, 100));
await fetch('https://api.day.app/' + key + '/紧急消息/' + msg);
};实战案例三：exec 工具调用前需要二次确认
javascript
// hooks/exec-confirm.js
module.exports = async function onToolCall(context) {
const { toolName, toolParams } = context;
if (toolName !== 'exec') return;
const dangerPatterns = ['rm ', 'drop ', 'delete ', 'format'];
const isDangerous = dangerPatterns.some(p =>
toolParams.command?.toLowerCase().includes(p)
);
if (isDangerous) {
context.interrupt({
message: '警告：AI 即将执行命令：' + toolParams.command + '\n确认执行请回复 confirm',
waitFor: 'confirm',
timeout: 30000
});
}
};消息内容自动转换
javascript
// hooks/auto-translate-hint.js
// 收到英文消息时自动在前面加翻译提示
module.exports = async function onMessageReceive(context) {
const text = context.message.text;
const isEnglish = /^[\x00-\x7F]+$/.test(text) && text.length > 10;
if (!isEnglish) return;
context.message.text = '[以下是英文消息，请用中文回复]\n' + text;
};条件触发：只在特定渠道生效
json
{
"hooks": {
"after-agent-run": [
{
"name": "save-to-notion",
"script": "./hooks/save-to-notion.js",
"conditions": {
"channels": ["telegram", "slack"],
"messageContains": ["决定", "方案", "plan"]
}
}
]
}
}Hook 执行优先级
SOUL.md（最高优先级，定义基础人格）
↓
Standing Orders（用户动态规则）
↓
Hooks（程序化拦截和转换）
↓
Agent 实际执行（最终行为）
来源：OpenClaw 官方文档 - docs.openclaw.ai/automation/hooks