grabee-chen/openclaw-security-starter

## 🛡️ 痛点：OpenClaw Agent 的安全性 当使用像 **OpenClaw** 这样的高级 Autonomous Agent 时，绝对的权力需要绝对的控制。全面整合 AI 的主要障碍是**安全与完整性风险**： * 🚨 **Prompt Injections**：触发未授权操作的恶意命令。 * 💀 **过度授权的工具**：由于缺乏防护措施而导致的意外系统/文件删除。 * 🔓 **未经授权的入站请求**：没有权限边界的不安全触发器。 **本 Starter 的存在就是为了解决这个问题。** 它实施了严密的分层防御，确保你的 Agent 保持安全，在防护栏内运行，并开箱即用地防御对抗性场景。 ## 📦 包含内容 此模板为你的 OpenClaw agent 提供了一个**多层安全堆栈**，已预配置并准备好在任何完全支持 Docker 的平台上进行生产部署。 | 层级 | 文件 | 描述 | |-------|------|-------------| | **SHIELD** | `security/SHIELD.md` | 主访问边界与认证模型 | | **Agent 规则** | `security/AGENT_RULES.md` | 行为准则 — AI 可以做和不能做的事 | | **Injection Guard** | `security/PROMPT_INJECTION_GUARD.md` | 防御对抗性 prompt injection 攻击 | | **工具策略** | `security/TOOL_POLICY.md` | 最小权限工具执行权限注册表 | ## 🏗️ 项目结构 ``` openclaw-security-starter/ ├── Dockerfile # Docker-first deployment (inherits official image) ├── zbpack.json # Optional: deployment triggers ├── .gitignore # Protects secrets and runtime data │ ├── security/ │ ├── SHIELD.md # Layer 1: Access control boundary │ ├── AGENT_RULES.md # Layer 2: Behavioral rules │ ├── PROMPT_INJECTION_GUARD.md # Layer 3: Injection defense │ └── TOOL_POLICY.md # Layer 4: Tool permissions │ ├── config/ │ └── security.config.json # Runtime security parameters │ └── docs/ └── architecture.md # System architecture diagram ``` ## 🚀 部署指南 (Docker) 由于此模板已完全通过 **Docker** 容器化，你几乎可以将其部署在任何地方：从你的**本地机器 (Mac / PC)**、闲置的**家庭服务器**，到任何**云端 VPS** 或托管服务提供商。 ### 选项 1：本地 / Homelab (Mac, PC, Linux) 非常适合本地测试以及在本地台式机或服务器环境中运行。 #### 1. Fork 或 Clone 此仓库 ``` git clone https://github.com/your-org/openclaw-security-starter.git cd openclaw-security-starter ``` #### 2. 使用 Docker 运行 将你的本地安全配置挂载到容器并运行： ``` docker build -t openclaw-security . docker run -d \ -p 18789:18789 \ -v $(pwd)/security:/home/node/.openclaw/security \ -v $(pwd)/config:/home/node/.openclaw/config \ -e OPENCLAW_OWNER_ID="your_user_id" \ -e OPENCLAW_AGENT_TOKEN="your_agent_token" \ openclaw-security ``` ### 选项 2：云端部署 (示例：使用 Zeabur 部署) 这是一个经过验证的云端部署路径，使用 **Zeabur** 来说明最终的模板同步工作流。 该项目不挂载本地存储磁盘卷，而是使用 `Dockerfile` 在每次构建时自动将你的配置文件内置 (`COPY security/ /app/security/`)。 #### 1. 部署基础的 OpenClaw 模板 1. 打开你的 Zeabur 仪表板或 Marketplace。 2. 首先部署标准的 **OpenClaw** 服务，以验证 agent 是否存活并处于监听状态。 #### 2. 绑定此自定义仓库 要应用你的分层安全规则，请将此仓库直接链接到你的服务中： 1. 转到你的 Zeabur 仪表板 -> 选择你的项目 -> 选择 OpenClaw 服务 -> **Settings**。 2. 向下滚动到 **Source** -> 点击 **"Bind GitHub Repository"**。 3. 选择你 fork 的仓库，指定分支 (`main`)，然后点击 **Save & Redeploy**。 Zeabur 将提取 `Dockerfile` 并将你的安全策略直接内置到运行层中。**无需配置 Persistent Volume！** #### 3. 配置环境变量 在 Zeabur 服务设置仪表板中，确保以下设置保持不变： | 变量 | 必需 | 描述 | |----------|----------|-------------| | `OPENCLAW_OWNER_ID` | ✅ 是 | 你的 Discord/平台用户 ID（授予 OWNER 访问权限） | | `OPENCLAW_AGENT_TOKEN` | ✅ 是 | OpenClaw agent 的 API token | ## 🔐 安全层详解 ### 第 1 层 — SHIELD (访问边界) 控制**谁**可以与 agent 交互。默认情况下，只有指定的 OWNER 才能发出命令。强制要求 `@mention` 以防止意外激活。 ### 第 2 层 — Agent 规则 (行为准则) 定义 agent **会**做什么和**不会**做什么。包含绝对规则（不可更改）和可配置规则（可通过 `security.config.json` 调整）。如果发生冲突，agent 始终优先选择规则而非运行时指令。 ### 第 3 层 — Prompt Injection Guard 防御旨在**劫持** agent 行为的对抗性输入。检测关键词模式、结构异常和编码的攻击 payload。 ### 第 4 层 — 工具策略 (最小权限) 控制**可以执行哪些工具**以及**由谁执行**。使用 T0–T4 权限分级系统。在基础版中，像 `delete_file` 和 `run_query` 这样的高风险工具被物理禁用（`T0 — BLOCKED`）。 ## ⚙️ 自定义 编辑 `config/security.config.json` 以调整安全参数： ``` { "access_control": { "owner_only_mode": true, // Set to false to enable DELEGATE access "require_mention": true, // Set to false to disable @mention requirement "delegate_enabled": false // Set to true to allow delegate principals }, "rate_limiting": { "requests_per_minute_per_user": 10, "injection_attempt_threshold": 3 } } ``` ## 🛡️ 本版本不包含的内容 **基础版**是有意保持最小化的。以下内容适用于专业版和企业版： - ❌ Discord Bot 集成 - ❌ LINE 消息传递集成 - ❌ n8n 工作流触发器 - ❌ 自定义技能扩展 - ❌ Multi-agent 编排 ## 📄 许可证 此模板仅授权用于**个人、教育和非商业用途**。 * ✅ **允许**：在**你自己的个人**非营利 OpenClaw agent 节点（例如本地 PC/服务器）上进行技术测试、研究和部署。 * ❌ **禁止**：**任何商业设置、以盈利为目的的企业使用，或将这些安全文件作为数字产品模板重新打包和转售**。 完整条款请参见 `LICENSE`。

标签：AI智能体, DLL 劫持, Docker模板, Homebrew安装, Streamlit, 大语言模型, 提示词注入防护, 访问控制, 请求拦截, 防御加固