# OpenClaw 极简安全实践指南 (Security Practice Guide)
[](https://github.com/openclaw/openclaw)
[](https://opensource.org/licenses/MIT)
[](#)
*其他语言版本: [English](README.md), [简体中文](README_zh-CN.md).*
专为 **高权限自主智能体 (OpenClaw)** 量身定制的权威安全实践指南。它将传统“主机静态防御”的范式转变为“智能体零信任架构 (Zero-Trust Architecture)”，有效应对破坏性操作、提示词注入、供应链投毒和高危业务逻辑执行等智能体专属风险。
⚠️愉快玩耍前，先看底部免责声明与常见问题
⚠️愉快玩耍前，先看底部免责声明与常见问题
⚠️愉快玩耍前，先看底部免责声明与常见问题
## 🎯 适用场景与核心原则
> **本指南是面向 OpenClaw 本身（Agent-facing）的，不是传统“仅供人类手动操作”的加固清单。**
> 实际使用中，你可以把本指南直接发给 OpenClaw，让它先评估可靠性，再自动完成防御矩阵部署，大幅降低手工配置成本。
> **重要边界说明：本指南并不能让 OpenClaw“完全安全”。**
> 安全是复杂的系统工程，不存在绝对安全。
> 本指南只在其定义的威胁模型、适用场景和操作假设下发挥作用。
> **最终的安全兜底与关键判断，仍然在使用者自己。**
### 适用场景
- OpenClaw 运行在高权限环境（具备终端 / Root 能力）
- OpenClaw 持续安装并使用 Skills / MCPs / 脚本 / 工具
- 目标是在能力最大化前提下，实现风险可控与审计可追溯
### 核心原则
1. **日常零摩擦**：尽量降低用户手工安全配置负担，且用户日常操作几乎无感，除非遇到指南认为的红线
2. **高危必确认**：不可逆或敏感操作必须暂停并由人类确认
3. **每晚显性化巡检**：所有核心指标都要明确汇报（包含绿灯项）
4. **默认零信任**：始终假设提示词注入、供应链投毒、业务逻辑滥用可能发生
### 模型建议（重要）
这份指南主要由 OpenClaw 理解并执行。
建议优先使用**最新、推理能力更强的模型**（例如 Gemini / Opus / Kimi / MiniMax 等系列中的高阶模型）。
更“聪明”的模型通常在以下方面明显更稳：
- 长上下文安全约束理解
- 隐性指令/注入模式识别
- 部署步骤一致性与低错误率执行
✅ 这也是本指南能**显著降低用户配置成本**的关键：OpenClaw 可自行完成大部分“理解 → 部署 → 验证”流程。
## 🌟 为什么需要本指南？
让类似 OpenClaw 这样的 AI Agent 拥有 Root 或终端访问权限极其强大，但也伴随着巨大的固有风险。传统的安全措施（如 `chattr +i`、防火墙）要么与 Agent 的自动化工作流不兼容，要么不足以抵御针对大语言模型 (LLM) 的特有攻击（如 Prompt Injection）。
本指南提供了一套经过实战检验的、极简的 **三层防御矩阵**：
1. **事前 (Pre-action)**: 行为黑名单与严格的技能包安装审计协议（防供应链投毒）
2. **事中 (In-action)**: 权限收窄与跨技能业务风控前置检查 (Pre-flight Checks)
3. **事后 (Post-action)**: 每晚自动化显性巡检（覆盖 13 项核心指标）与大脑 Git 灾备同步
## 🚀 极简部署流程 (Zero-Friction Flow)
在 AI 时代，部署安全防线不应该由人类手动敲代码。**您可以让您的 OpenClaw 为您自动完成一切：**
1. **下载指南**: 选择版本：
- 稳定版：[OpenClaw 极简安全实践指南.md](docs/OpenClaw极简安全实践指南.md)（v2.7）
- 增强版：[OpenClaw 极简安全实践指南 v2.8.md](docs/OpenClaw极简安全实践指南v2.8.md)（v2.8 Beta）
2. **发送给 Agent**: 在聊天窗口中，将该 markdown 文件直接发送给您的 OpenClaw Agent
3. **让 AI 评估**: 向您的 Agent 发送指令：“*请阅读这份安全指南，在部署前先识别与我们当前环境可能存在的风险或冲突。*”
4. **部署**: 确认无误后，发送指令：
- v2.8：“*请按照指南中的 Agent 辅助部署工作流执行。*”
- v2.7：“*请完全按照这份指南，为我部署防御矩阵。包括写入红/黄线规则、收窄权限，并部署夜间巡检 Cron Job。*”
5. **验收测试（可选）**: 部署完成后，请按照 [验证与攻防演练手册](docs/Validation-Guide-zh.md) 对 Agent 进行一次突击测试，确保红线生效
*(注：本仓库 `scripts/` 目录下的巡检脚本仅作开源展示与人类参考之用，**您完全不需要手动复制或运行它**，Agent 会自动从指南文档中提取逻辑并为您编写部署。)*
## 📖 目录导览
### 核心文档（稳定版 — v2.7）
* [**OpenClaw 极简安全实践指南 v2.7 (中文版)**](docs/OpenClaw极简安全实践指南.md) - 完整指南文档
* [**OpenClaw Security Practice Guide v2.7 (English)**](docs/OpenClaw-Security-Practice-Guide.md) - The complete guide in English
### 🆕 v2.8 Beta — 增强版，经实战验证
> ⚠️ **Beta 版本**：v2.8 经数百小时生产环境运维验证，但仍在持续迭代中。v2.7 仍为稳定版。如需最新增强，请使用 v2.8。
* [**OpenClaw 极简安全实践指南 v2.8 Beta (中文版)**](docs/OpenClaw极简安全实践指南v2.8.md) - 增强版，含实战验证的改进
* [**OpenClaw Security Practice Guide v2.8 Beta (English)**](docs/OpenClaw-Security-Practice-Guide-v2.8.md) - Enhanced guide with production-verified improvements
**相较 v2.7 的核心增强：**
- 🤖 **Agent 辅助部署工作流** — 5 步自动化部署（认知内化 → 权限收窄 → 部署巡检 → 配置灾备（可选）→ 交付验收）
- 🛡️ **`--light-context` Cron 防劫持** — 防止 workspace context 劫持隔离巡检 session
- 📝 **巡检脚本编码规范** — `set -uo pipefail`、边界锚点、显式健康状态输出、统计摘要行
- 📂 **报告持久化路径** — 报告保存到 `$OC/security-reports/`（不用 `/tmp`，重启不丢）+ 30 天轮转
- 🔄 **升级后基线重建流程** — 引擎升级后重建哈希基线的完整步骤
- 🔍 **增强代码审计协议** — 二次下载检测、高危文件类型预警、升级裁决流程
- ⚡ **Token 优化** — 强制在 Bash 内预筛选（`head`/`grep`）后再交给 LLM 处理
- 🧠 **7 条实战踩坑记录** — 超时、模型选择、message 策略、已知误报排除等真实教训
### 验证与攻防演练
为了防止您的 AI 助手由于“过于听话”而绕过防线，请务必参考以下手册进行对抗演练：
* [安全验证与攻防演练手册 (中文版)](docs/Validation-Guide-zh.md) - 端到端防御验证实操
* [Security Validation & Red Teaming Guide (English)](docs/Validation-Guide-en.md) - How to test your defenses
### 工具与脚本
* [`scripts/nightly-security-audit.sh`](scripts/nightly-security-audit.sh) - v2.7 参考巡检脚本（仅供查阅，无需手动安装）
* [`scripts/nightly-security-audit-v2.8.sh`](scripts/nightly-security-audit-v2.8.sh) - **v2.8 Beta** 参考脚本，含已知问题排除、报告持久化、30 天轮转、Token 优化输出
## 🤝 贡献
欢迎提交 Contributions, Issues 和 Feature Requests！
感谢：慢雾安全团队（[@SlowMist_Team](https://x.com/SlowMist_Team)）、Edmund.X（[@leixing0309](https://x.com/leixing0309)）、zhixianio（[@zhixianio](https://x.com/zhixianio)）、Feng Liu（[@fishkiller](https://x.com/fishkiller)）
## ⚠️ 免责声明与常见问题（Disclaimer & FAQ）
### 1. 适用范围与能力前提
本指南假定执行者（人类或 AI Agent，尤其是 AI Agent）具备以下能力：
- 理解 Linux 基础系统管理概念（文件权限、chattr、cron 等）
- 能够准确区分红线/黄线/安全命令的边界
- 能够在执行前理解命令的完整语义和副作用
**如果执行者（尤其是 AI 模型）不具备上述能力，请勿直接套用本指南。** 能力不足的模型可能误解指令含义，导致比不配置安全策略更严重的后果。
### 2. AI 模型执行风险
本指南的核心机制“行为层自检”依赖 AI Agent 自主判断命令是否触及红线，这带来以下固有风险：
- **误判**：能力较弱的模型可能将安全命令误判为红线（阻断正常工作），或将危险命令误判为安全（导致安全事故）
- **理解偏差**：模型可能对红线命令做过于字面的匹配（只拦 `rm -rf /` 但不拦 `find / -delete`），或过于宽泛（把所有 `curl` 都当红线）
- **执行偏差**：模型在实施 `chattr +i` 等防护措施时，错误的参数可能导致系统不可用（如锁错文件影响 OpenClaw 正常运行）
- **指南被注入**：如果本指南以 prompt 形式注入 Agent，恶意 Skill 可能通过 prompt injection 篡改指南内容，使 Agent “认为”红线规则已被修改
**本指南作者不对因 AI 模型误解、误执行本指南内容所造成的任何损失承担责任，包括但不限于：数据丢失、服务中断、配置损坏、安全漏洞暴露、密钥泄露。**
### 3. 非银弹声明
本指南提供的是**纵深防御的基础框架**，不是完整的安全解决方案：
- 不能防御 OpenClaw 引擎本身、底层 OS 或依赖组件的未知漏洞
- 不能替代专业安全审计（生产环境或涉及真实资产的场景应另行评估）
- 巡检属于事后检测，只能发现已发生的异常，无法回滚已造成的损害
### 4. 环境假设
本指南基于以下环境编写，偏离时请自行评估：
- 单用户、个人用途的 Linux 服务器
- OpenClaw 以 root 权限运行，追求能力最大化
- 网络可达 GitHub（Git 备份）和 Telegram 等 API（巡检通知）
### 5. 版本与时效性
本指南基于编写时的 OpenClaw 版本，后续版本可能引入原生安全机制使部分措施过时或冲突。请定期检查兼容性。
---
## 常见问题（FAQ）
### 💡 实验与体验篇
#### Q1: 这份指南是一次怎样的实验？为什么不直接做成 Skill？
**这是一次给 AI 植入安全“思想钢印”的实验。**
我们尝试过构建专门的安全 Skill，但发现直接向 OpenClaw 脑中植入包含“事前、事中、事后”策略的 Markdown 钢印更有意思。Skill 本质上只是挂载的工具，而“思想钢印”能够改变 Agent 的基础认知。如果你确实需要一个 Skill，你也完全可以通过多与它对话让它自己生成一个。总之，只要机器不金贵，尽情折腾。
#### Q2: 部署后 OpenClaw 会变得束手束脚吗？
**取决于你与模型的磨合，请务必找到平衡点（强烈建议不要被束手束脚，会烦死）。**
特别像 OpenAI 系的模型本身就很严格。如果你完全顺着它的思路走，它可能什么都不敢干。安全和业务永远是权衡：安全太过不好，没有也不好。这就是我们在“核心原则”中强调“日常零摩擦”的原因。如果觉得防线过紧，由于模型差异，你在部署前可以多和你的 🦞 对话，把担忧和需求沟通清楚，再让其落地。
#### Q3: 这份指南只针对 Linux Root，我的环境是 Mac / Win 怎么办？
**没有完美适配，但有 Trick（投喂技巧）。**
你可以把 `OpenClaw极简安全实践指南.md` 直接喂给你的 OpenClaw，因为大模型拥有举一反三的能力。模型会自动给你关于系统兼容性的建议，然后**你可以直接让它尝试为你生成一份“适配后”的专属指南**，再考虑是否要落地。
#### Q4: 植入安全“思想钢印”后，还有什么进阶乐趣？
一旦你的 Agent 理解了这份指南背后的安全设计理念，此后如果你给它安装其他优秀的安全 Skill 或企业级解决方案，更有意思的化学反应就会发生：**你的 OpenClaw 会主动根据它脑海里的这层安全记忆，去对比、打分并分析那些新来的安全工具。**
#### Q5: 灾备（Git Backup）部分是强制的吗？
**不是必选。**
灾备的必要性取决于你个人对记忆与隐私数据的在意程度。如果你只希望保障运行时安全，不希望远端同步数据，完全可以直接删掉那个机制。你甚至可以让 Agent 先对敏感信息“加密后再备份”。
---
### 🔧 实操与技术篇
#### Q6: 我用的模型比较弱（如小参数模型），能用这个指南吗？
**不建议直接使用完整指南。** 行为层自检要求模型能准确解析命令语义、理解间接危害、在多步操作中保持安全上下文。如果模型做不到，建议：只使用 `chattr +i`（纯系统级，不依赖模型能力），并将 Skill 安装安检交由人类手动完成。
#### Q7: 红线列表是否完备？
**不可能完备。** Linux 下实现同一破坏效果的方式很多（`find / -delete`、Python 脚本删除、DNS 隧道外发数据等）。指南中“拿不准按红线处理”是兜底原则，但最终依赖模型的判断能力。
#### Q8: Skill 安检是否只需要做一次？
不是。Skill 更新、OpenClaw 引擎更新、Skill 行为异常、巡检指纹校验不匹配时都需要重新安检。
#### Q9: `chattr +i` 会不会影响 OpenClaw 正常运行？
**可能会。** `openclaw.json` 加锁后 OpenClaw 自身也无法更新该文件，升级或配置变更会报 `Operation not permitted`。需要修改时先 `sudo chattr -i` 解锁，改完再重新加锁。另外，**绝对不要对 `exec-approvals.json` 加锁**（指南中已说明），否则引擎运行时写入元数据会失败。
#### Q10: 如果模型误执行了 `chattr +i` 到错误的文件怎么办？
手动修复：
```bash
# 查找所有被设置了 immutable 属性的文件
sudo lsattr -R /home/ 2>/dev/null | grep '\-i\-'
# 解锁误锁的文件
sudo chattr -i <文件路径>
```
如果误锁了关键系统文件（如 `/etc/passwd`），可能需要进入 recovery mode 修复。
#### Q11: 巡检脚本本身会不会有安全风险？
巡检脚本以 root 权限运行，如果被篡改就等于一个每晚自动执行的后门。建议对巡检脚本本身也做 `chattr +i` 保护，Telegram Bot Token 单独存放并设为 `chmod 600`。
#### Q12: 如果 OpenClaw 引擎本身有安全漏洞怎么办？
本指南的防护措施都建立在“引擎本身可信”的假设上，无法防御引擎层漏洞。建议关注 OpenClaw 官方安全公告，及时更新。
## 📝 许可协议
本项目采用 [MIT](LICENSE) 协议。