# hook-guard

Adopt this skill: https://proskills.md/skills/other/wavmson-openclaw-skill-hook-guard

Page: https://proskills.md/skills/other/wavmson-openclaw-skill-hook-guard
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 5419
upstream: https://github.com/wavmson/openclaw-skill-hook-guard/blob/HEAD/SKILL.md

````text
---
name: hook-guard
description: "钩子守卫。为 Agent 操作添加安全防护层——文件修改前自动备份、危险命令执行前拦截确认、敏感操作自动告警通知用户。触发词：安全检查、hook guard、守卫、备份保护、安全模式、操作审计。也可在 AGENTS.md 中配置为始终生效。"
---

# Hook Guard — 钩子守卫

为 Agent 的每一步操作加上安全防护网。

## 什么时候用

- 始终生效（推荐在 AGENTS.md 中配置为默认行为）
- 用户说"安全模式"、"开启守卫"、"hook guard"
- 执行高风险任务前（部署、批量修改、删除操作）
- Agent 自行判断当前操作需要额外防护

## 核心理念

Agent 拥有强大的工具权限——能读写文件、执行命令、发送消息、操作数据库。
权力越大，责任越大。Hook Guard 在关键操作前后插入安全检查点：

- **执行前（Pre-hook）**：该不该做？需不需要确认？
- **执行中（Guard）**：自动备份、记录日志
- **执行后（Post-hook）**：通知用户、验证结果

## 三类防护钩子

### 🔴 Red Hook — 危险操作拦截

触发条件：检测到以下操作时**立即暂停**，等待用户确认。

**文件操作：**
- `rm`、`rm -rf`、`trash` 大量文件（>5 个）
- 覆盖写入已有的重要文件（MEMORY.md、AGENTS.md、配置文件等）
- 删除 `.git` 目录或 Git 历史

**命令执行：**
- 含 `sudo` 的命令
- `systemctl stop/disable` 系统服务
- `docker rm`、`docker system prune`
- 修改 SSH 配置、防火墙规则
- `kill -9`、`pkill` 进程管理

**外部操作：**
- 发送消息到新的聊天/群（首次接触）
- 发布到公开平台（小红书、Twitter 等）
- 修改 DNS、域名配置
- 操作生产环境

拦截报告格式：

```
🔴 危险操作拦截
━━━━━━━━━━━━

⚠️ 操作：rm -rf /home/wavm/important-project/
📁 影响：将永久删除 342 个文件
🔒 风险：不可逆操作

建议：
1. 改用 trash（可恢复）
2. 先备份到 /tmp/backup-YYYYMMDD/

⏳ 等待确认（回复"继续"执行，"取消"放弃）
```

### 🟡 Yellow Hook — 自动备份 + 通知

触发条件：检测到以下操作时**自动备份后执行**，并通知用户。

**自动备份的场景：**
- 编辑配置文件（openclaw.json、.env、nginx.conf 等）
- 覆盖写入工作区文件
- 修改 cron jobs
- 更新数据库记录

**备份机制：**
- 备份路径：`~/.openclaw/workspace-main/.hook-guard/backups/YYYY-MM-DD/`
- 文件名：`{原始文件名}.{HHmmss}.bak`
- 保留最近 7 天的备份，自动清理旧备份

**通知格式：**

```
🟡 自动备份
文件：openclaw.json
备份：.hook-guard/backups/2026-04-02/openclaw.json.143022.bak
操作：修改 maxTokens 配置
```

### 🟢 Green Hook — 静默日志

触发条件：常规操作，只记录日志不打扰用户。

**记录的操作：**
- 读取文件
- 搜索操作
- 查看日历/任务
- 网络搜索

**日志位置：** `~/.openclaw/workspace-main/.hook-guard/audit.log`

日志格式：
```
[2026-04-02 14:30:22] READ /home/wavm/.openclaw/workspace-main/MEMORY.md
[2026-04-02 14:30:25] EXEC ls -la /tmp/
[2026-04-02 14:31:00] SEARCH web "OpenClaw skills"
```

## 执行流程

### 每次操作前

1. **分类**：判断操作属于 Red/Yellow/Green 哪个级别
2. **Red**：生成拦截报告 → 等待用户确认 → 确认后执行
3. **Yellow**：自动备份原始状态 → 执行操作 → 通知用户
4. **Green**：记录日志 → 正常执行

### 定期维护

- 每天清理 7 天前的备份文件
- 审计日志保留 30 天
- 可通过 "查看守卫报告" 获取统计摘要

## 配置

在 AGENTS.md 中添加以下规则使 Hook Guard 始终生效：

```markdown
## 安全规则（Hook Guard）

- 执行 rm/trash 前检查影响范围，>5 个文件需确认
- 修改配置文件前自动备份到 .hook-guard/backups/
- sudo 命令必须用户确认
- 发送外部消息前确认接收方和内容
- trash > rm（可恢复优于不可逆）
```

## 守卫报告

用户说"守卫报告"或"guard report"时，生成统计摘要：

```
🛡️ Hook Guard 报告
━━━━━━━━━━━━━━━━

📅 时间范围：最近 24 小时

🔴 拦截：2 次
  - rm -rf /tmp/old-project/ → 用户确认后改用 trash
  - sudo systemctl restart nginx → 用户确认后执行

🟡 备份：5 次
  - openclaw.json（2 次修改）
  - cron/jobs.json（1 次修改）
  - memory/2026-04-02.md（2 次追加）

🟢 日志：47 条操作记录

💾 备份空间：2.3 MB（7 天保留）
```

## 规则

- **永不绕过 Red Hook**：即使用户说"别问了直接做"，危险操作仍需单次确认
- **备份不占大空间**：只备份被修改的文件，不备份整个目录
- **日志不含敏感内容**：只记录操作类型和路径，不记录文件内容
- **用户可调整级别**：可以把某些 Yellow 操作升级为 Red，或降级为 Green
- **不影响性能**：Green 日志异步写入，不阻塞操作

## 与其他 Skill 配合

- **Smart Compact**：压缩前 Hook Guard 自动备份当前对话状态
- **Session Resume**：Hook Guard 的拦截记录可以跨 session 恢复
- **Swarm Coord**：子 Agent 的操作同样受 Hook Guard 保护
- **Memory-Dream**：审计日志是 Dream 整合时的参考信息源
````

## File: README.md
upstream: https://github.com/wavmson/openclaw-skill-hook-guard/blob/HEAD/README.md

````text
# 🛡️ Hook Guard — 钩子守卫 Skill

> 给你的 AI Agent 装上安全气囊。危险操作拦截确认，重要文件自动备份，所有行为可审计追溯。

---

## 中文说明

### 这是什么？

AI Agent 拥有强大权限：读写文件、执行命令、发消息、改配置。但能力越强越容易出事：

- 😱 Agent 误删了重要文件
- 💥 一个 rm -rf 清空了项目目录
- 📤 没确认就把消息发到了老板群
- ⚙️ 改错配置导致服务挂了

Hook Guard 是 Agent 的安全防护层。三级钩子系统覆盖所有操作。

### 安装

**通过 ClawHub 安装（推荐）：**

```bash
clawhub install hook-guard
```

**从 GitHub 克隆：**

```bash
git clone https://github.com/wavmson/openclaw-skill-hook-guard.git \
  ~/.openclaw/skills/hook-guard
```

安装后重启 Gateway：

```bash
openclaw gateway restart
```

### 三级防护体系

| 级别 | 名称 | 触发场景 | 处理方式 |
|------|------|----------|----------|
| 🔴 Red | 危险拦截 | 删除文件、sudo、发布到公开平台 | 暂停执行，等待用户确认 |
| 🟡 Yellow | 自动备份 | 修改配置、覆盖文件、改 cron | 备份后执行，通知用户 |
| 🟢 Green | 静默日志 | 读取文件、搜索、查看信息 | 只记录日志，不打扰 |

### Red Hook 示例

Agent 准备执行危险操作时：

```
🔴 危险操作拦截
━━━━━━━━━━━━

操作：rm -rf /home/wavm/important-project/
影响：将永久删除 342 个文件
风险：不可逆操作

建议：
1. 改用 trash（可恢复）
2. 先备份到 /tmp/

等待确认（回复"继续"执行，"取消"放弃）
```

### Yellow Hook 示例

修改配置文件时自动备份：

```
🟡 自动备份
文件：openclaw.json
备份：.hook-guard/backups/2026-04-02/openclaw.json.143022.bak
操作：修改 maxTokens 配置
```

### 守卫报告

说"守卫报告"或"guard report"查看统计：

```
🛡️ Hook Guard 报告（最近 24 小时）

🔴 拦截：2 次
🟡 备份：5 次（2.3 MB）
🟢 日志：47 条操作记录

最近拦截：
  - rm -rf /tmp/old-project/ → 改用 trash
  - sudo systemctl restart nginx → 确认后执行
```

### 设计原则

| 原则 | 说明 |
|------|------|
| 🔒 不可绕过 | Red Hook 危险操作必须单次确认，即使用户说过"别问了" |
| 💾 自动备份 | Yellow 操作自动保存原始状态，7 天自动清理 |
| 📝 全程可追溯 | 所有操作记录审计日志，30 天保留 |
| ⚡ 不影响性能 | Green 日志异步写入，零延迟 |
| 🎚️ 可调级别 | 用户可以升级或降级某些操作的防护等级 |

### 哪些操作会被拦截？

**🔴 Red（必须确认）：**
- 删除文件（rm、rm -rf）
- 含 sudo 的命令
- 停止系统服务
- 清理 Docker 容器/镜像
- 发送消息到新聊天
- 发布到公开平台
- 修改 DNS/域名
- 操作生产环境

**🟡 Yellow（自动备份）：**
- 修改配置文件
- 覆盖写入工作区文件
- 修改 cron 定时任务
- 更新数据库记录

**🟢 Green（只记日志）：**
- 读取文件
- 搜索操作
- 查看日历/任务
- 网络搜索

### 与记忆保护链搭配

| Skill | 职责 |
|-------|------|
| **Smart Compact** | 压缩前抢救信息 |
| **Session Resume** | 断线后恢复进度 |
| **Memory-Dream** | 定期整合长期记忆 |
| **Swarm Coord** | 多 Agent 并行协作 |
| **Hook Guard** | 操作安全防护 |

五个 Skill 形成完整的 **Agent 安全运维体系**：
- 记忆不丢（Smart Compact + Memory-Dream）
- 任务不断（Session Resume）
- 效率不低（Swarm Coord）
- 操作不炸（Hook Guard）

### 常见问题

**Q: 会不会每次都弹确认很烦？**
A: 不会。只有 Red 级操作需要确认，日常读写都是 Green 级静默记录。

**Q: 备份会不会占很多空间？**
A: 只备份被修改的单个文件，7 天自动清理，通常只占几 MB。

**Q: 子 Agent 也受保护吗？**
A: 是的。Swarm Coord 启动的子 Agent 同样遵守 Hook Guard 规则。

**Q: 能自定义哪些操作需要确认吗？**
A: 可以。在 AGENTS.md 中配置自定义规则，升级或降级操作等级。

---

## English

### The Problem

AI agents have powerful permissions — file read/write, command execution, message sending, config changes. With great power comes great risk:

- Accidentally deleting important files
- Running destructive commands without confirmation
- Sending messages to wrong recipients
- Breaking configurations

### The Solution

Hook Guard adds a safety layer with three protection levels:

| Level | Name | Trigger | Action |
|-------|------|---------|--------|
| 🔴 Red | Dangerous | Delete, sudo, publish | Pause and ask user |
| 🟡 Yellow | Important | Config edits, overwrites | Auto-backup, then proceed |
| 🟢 Green | Routine | Read, search, browse | Silent audit log |

### Install

```bash
clawhub install hook-guard
```

Or clone from GitHub:

```bash
git clone https://github.com/wavmson/openclaw-skill-hook-guard.git \
  ~/.openclaw/skills/hook-guard
```

### How It Works

**Before every operation:**
1. Classify: Red, Yellow, or Green?
2. Red → Generate interception report → Wait for user confirmation
3. Yellow → Auto-backup original state → Execute → Notify user
4. Green → Log silently → Execute normally

### Design Principles

| Principle | Description |
|-----------|-------------|
| 🔒 Non-bypassable | Red operations always need per-operation confirmation |
| 💾 Auto-backup | Yellow operations save original state (7-day retention) |
| 📝 Full audit trail | All operations logged (30-day retention) |
| ⚡ Zero overhead | Green logs are async, no performance impact |
| 🎚️ Customizable | Users can adjust protection levels per operation |

### The 5-Skill Agent Safety Stack

| Skill | Protects |
|-------|----------|
| Smart Compact | Conversation details |
| Session Resume | Task progress |
| Memory-Dream | Long-term memory |
| Swarm Coord | Team efficiency |
| Hook Guard | Operation safety |

### FAQ

**Q: Will it interrupt me constantly?**
A: No. Only Red-level operations (deletions, sudo, publishing) need confirmation. Daily work is Green-level (silent).

**Q: How much space do backups use?**
A: Only modified files are backed up. 7-day auto-cleanup keeps it under a few MB.

**Q: Does it protect sub-agents too?**
A: Yes. Agents spawned by Swarm Coord follow the same Hook Guard rules.

---

## Requirements

- [OpenClaw](https://github.com/openclaw/openclaw) with Skill support

## License

MIT

## Author

[@wavmson](https://github.com/wavmson)
````
