OpenClaw Hooks 事件脚本完整实操指南

一、核心概念

1. 什么是 Hooks

Hooks 是事件驱动型触发器：网关 / 智能体触发指定事件时，自动执行预先编写的脚本，实现全流程自动化。

区别于其他自动化能力：

Hooks：事件触发（会话启停、工具调用、网关启停），被动执行
Cron：定时触发（按时分日月周）
Heartbeat：固定周期轮询
Standing Orders：常驻指令，约束智能体行为

2. 支持的事件总览

会话事件

表格

事件标识	触发时机	典型用途
`/new`	执行 `/new` 新建会话	推送欢迎语、初始化环境
`/reset`	执行 `/reset` 重置会话	清理临时文件、重置状态
`/stop`	执行 `/stop` 停止会话	保存进度、告别提示
`compaction`	会话上下文压缩	记录压缩日志、统计 Token

系统事件

表格

事件标识	触发时机	典型用途
`gateway:start`	网关启动	上线通知、自检、加载配置
`gateway:stop`	网关停止	下线通知、收尾备份

消息事件

表格

事件标识	触发时机	典型用途
`message:incoming`	收到用户消息	内容审计、关键词拦截、日志
`message:outgoing`	智能体发出回复	回复质检、对外日志

工具事件

表格

事件标识	触发时机	典型用途
`tool:before`	调用工具之前	权限校验、调用审计
`tool:after`	调用工具之后	结果记录、异常监控

二、目录、格式与权限

1. 目录优先级（从高到低）

智能体独立 Hooks：~/.openclaw/agents/{agentId}/hooks/（仅当前 Agent 生效）
全局 Hooks：~/.openclaw/hooks/（所有智能体全局生效）

同名事件脚本，智能体级会覆盖全局级。

2. 脚本标准格式

文件头部必须声明解释器与监听事件，格式固定：

bash

运行

#!/bin/bash
# hook: 事件名1,事件名2
# description: 脚本用途（可选）

# 你的业务逻辑

支持多语言，示例：

Bash（最常用）

bash

运行

#!/bin/bash
# hook: /new
echo "新会话已开启"

Python

python

运行

#!/usr/bin/env python3
# hook: gateway:start
print("网关启动成功")

Node.js

javascript

运行

#!/usr/bin/env node
// hook: message:incoming
console.log("收到新消息")

3. 执行权限（必做）

所有 Hook 脚本必须添加可执行权限，否则无法运行：

bash

运行

chmod +x 脚本路径

三、内置环境变量（获取上下文）

脚本运行时自动注入变量，可直接读取会话、渠道、用户等信息：

表格

环境变量	含义
`OPENCLAW_HOOK_EVENT`	当前触发的事件名
`OPENCLAW_AGENT_ID`	当前智能体 ID
`OPENCLAW_SESSION_ID`	会话唯一 ID
`OPENCLAW_CHANNEL`	所属渠道（telegram/webchat 等）
`OPENCLAW_CONTACT`	联系人 / 群组标识
`OPENCLAW_TOOL_NAME`	工具事件专用：当前调用的工具名
`OPENCLAW_MESSAGE_CONTENT`	消息事件专用：消息原文

示例：根据事件分支执行

bash

运行

#!/bin/bash
# hook: /new,/reset,/stop

case "$OPENCLAW_HOOK_EVENT" in
"/new")
  echo "👋 欢迎使用，会话已创建"
  ;;
"/reset")
  echo "🔄 会话已重置"
  ;;
"/stop")
  echo "👋 会话已结束"
  ;;
esac

四、CLI 管理命令

1. 查看全部已注册 Hooks

bash

运行

openclaw hooks list

区分展示全局脚本和各智能体独立脚本。

2. 添加 Hook

bash

运行

# 交互式添加
openclaw hooks add

# 命令行直接指定事件+脚本
openclaw hooks add --event "/new" --script ~/.openclaw/hooks/welcome.sh

3. 移除 Hook

bash

运行

# 按脚本名删除
openclaw hooks remove welcome.sh

# 交互式选择删除
openclaw hooks remove

4. 手动测试脚本（不影响真实会话）

bash

运行

openclaw hooks test welcome.sh

5. 查看 Hook 运行日志

bash

运行

openclaw logs --filter hooks

五、从零创建第一个 Hook（实操案例）

目标：新建会话时自动推送欢迎语

bash

运行

mkdir -p ~/.openclaw/hooks

编写脚本

bash

运行

cat > ~/.openclaw/hooks/welcome.sh << 'EOF'
#!/bin/bash
# hook: /new
# description: 新会话欢迎提示
echo "✨ 你好！输入 /reset 重置会话，/stop 结束对话"
EOF

添加执行权限

bash

运行

chmod +x ~/.openclaw/hooks/welcome.sh

注册生效

bash

运行

openclaw hooks add --event "/new" --script ~/.openclaw/hooks/welcome.sh

测试在对话中发送 /new，即可看到欢迎语。

六、高频实用场景模板（直接复制使用）

场景 1：会话重置 → 自动清理临时文件

bash

运行

#!/bin/bash
# hook: /reset
# description: 重置会话清理临时目录

TMP_DIR="$HOME/.openclaw/agents/$OPENCLAW_AGENT_ID/tmp"
[ -d "$TMP_DIR" ] && rm -rf "$TMP_DIR"/*
echo "🧹 临时文件已清空"

场景 2：工具调用前后 → 审计日志

bash

运行

#!/bin/bash
# hook: tool:before
# description: 记录工具调用日志

LOG="$HOME/.openclaw/logs/tool-audit.log"
TIME=$(date +"%Y-%m-%d %H:%M:%S")
echo "[$TIME] Agent:$OPENCLAW_AGENT_ID | Session:$OPENCLAW_SESSION_ID | Tool:$OPENCLAW_TOOL_NAME" >> "$LOG"

场景 3：网关启动 → Webhook 推送上线通知

bash

运行

#!/bin/bash
# hook: gateway:start
# description: 网关启动推送通知

WEBHOOK="https://你的推送地址"
TIME=$(date +"%Y-%m-%d %H:%M:%S")
curl -s -X POST "$WEBHOOK" -d "text=🚀 OpenClaw 网关已启动 时间:$TIME"

场景 4：消息入站 → 敏感词提醒

bash

运行

#!/bin/bash
# hook: message:incoming
# description: 检测密码/密钥类敏感词

if echo "$OPENCLAW_MESSAGE_CONTENT" | grep -qi "密码\|key\|secret\|token"; then
  echo "⚠️ 请勿在对话中发送账号、密码、密钥等敏感信息"
fi

场景 5：会话压缩 → 记录日志

bash

运行

#!/bin/bash
# hook: compaction
# description: 会话压缩日志

LOG="$HOME/.openclaw/logs/compaction.log"
TIME=$(date +"%Y-%m-%d %H:%M:%S")
echo "[$TIME] 会话 $OPENCLAW_SESSION_ID 已执行上下文压缩" >> "$LOG"

七、执行顺序、异常与调优

1. 多脚本执行顺序

同一事件存在多个 Hook 时：

先执行 全局 Hooks（按文件名字母序）
再执行 当前智能体 Hooks（按文件名字母序）

自定义顺序：文件名加数字前缀

plaintext

01-log.sh   # 最先执行
02-check.sh
03-notify.sh # 最后执行

2. 错误处理规则

单个脚本执行失败 / 报错，不会中断后续 Hook，仅写入日志
脚本有默认超时（30s），超时会被强制终止
非关键命令建议加 || true，避免整体脚本退出： bash运行some_cmd || true

3. 耗时任务处理（后台运行）

长耗时操作放到后台，防止阻塞主流程：

bash

运行

#!/bin/bash
# hook: gateway:start
# description: 后台执行耗时初始化

nohup bash -c "
  # 耗时逻辑
  sleep 10
  curl https://xxx.com/init
" > /dev/null 2>&1 &

echo "后台初始化任务已启动"

4. 脚本语法调试

bash

运行

# 检查 bash 语法错误
bash -n 脚本路径

# 本地直接运行测试
bash 脚本路径

八、最佳实践 & 避坑

脚本轻量化 Hook 追求快速执行，复杂计算、大文件下载一律放后台。
做好日志 统一日志目录，方便后期排障。
防止循环触发 若脚本主动发送消息，会触发 message:outgoing，避免连环调用。
权限管控 仅给脚本必要权限，不要使用 root 运行。
区分全局 / 智能体脚本 通用逻辑放全局，个性化逻辑放到对应智能体 hooks 目录。
上线前必测试 先用 openclaw hooks test 验证，再正式投入使用。

九、命令速查表

表格

功能	命令
查看所有 Hooks	`openclaw hooks list`
添加 Hook	`openclaw hooks add`
删除 Hook	`openclaw hooks remove`
手动测试脚本	`openclaw hooks test 脚本名`
查看 Hook 日志	`openclaw logs --filter hooks`
添加执行权限	`chmod +x 脚本路径`

OpenClaw Hooks 事件脚本 完整实操指南

一、核心概念

1. 什么是 Hooks

2. 支持的事件总览

会话事件

系统事件

消息事件

工具事件

二、目录、格式与权限

1. 目录优先级（从高到低）

2. 脚本标准格式

Bash（最常用）

Python

Node.js

3. 执行权限（必做）

三、内置环境变量（获取上下文）

四、CLI 管理命令

1. 查看全部已注册 Hooks

2. 添加 Hook

3. 移除 Hook

4. 手动测试脚本（不影响真实会话）

5. 查看 Hook 运行日志

五、从零创建第一个 Hook（实操案例）

六、高频实用场景模板（直接复制使用）

场景 1：会话重置 → 自动清理临时文件

场景 2：工具调用前后 → 审计日志

场景 3：网关启动 → Webhook 推送上线通知

场景 4：消息入站 → 敏感词提醒

场景 5：会话压缩 → 记录日志

七、执行顺序、异常与调优

1. 多脚本执行顺序

2. 错误处理规则

3. 耗时任务处理（后台运行）

4. 脚本语法调试

八、最佳实践 & 避坑

九、命令速查表

OpenClaw Hooks 事件脚本完整实操指南