XSafeAI/XSafeClaw

[English](README.md) · [中文文档](README_zh.md)

XSafeClaw：监控并保护您的 Agent 🚀

🚀 快速入门  ·  📖 文档  ·  🌐 项目网站  ·  ▶️ YouTube 演示

## 🎬 XSafeClaw 简介

## 📰 新闻 _{版本发布说明和项目里程碑。} | | 日期 | 更新内容 | | :--: | :--------- | :----------------------------------------------------------- | | 🔥 | 2026-05-09 | 发布 v1.0.8 — 各模型的 token 用量和成本核算现已支持在 OpenClaw、Hermes 和 Nanobot 间统一运行；支持并发多会话消息；内存扫描类型在所有 runtime 中保持一致。 | | 🔥 | 2026-04-29 | 发布 v1.0.7 — Nanobot 连接现已完全集成：XSafeClaw 可以连接正在运行的 Nanobot 实例，建立受监控的会话，并在统一视图中与 OpenClaw 和 Hermes 一同展示 Nanobot 的活动。 | | 🔥 | 2026-04-26 | 发布 v1.0.5 — Nanobot 的引导接入现在遵循跨平台的官方安装流程，API 密钥配置前的设置不再失败，并且 Agent Valley 的独立页面已接入所需的 React Query provider。 | | 🔥 | 2026-04-25 | 发布 v1.0.4 — XSafeClaw 现已公开支持 OpenClaw、nanobot 和 Hermes 并行运行，同时修复了几个已知 bug。 | | 🔥 | 2026-04-23 | Hermes 和 runtime 自动启动 — XSafeClaw 现在可以同时发现 OpenClaw、Hermes 和 nanobot，并在服务器启动时尽最大努力启动已安装的网关。 | | 🔥 | 2026-04-18 | nanobot 本地 runtime 支持 — XSafeClaw 现在可以发现本地的 nanobot 实例，通过 `nanobot gateway` 启动受监控的聊天会话，并在 Agent Valley 中将混合 runtime 的会话一同展示。 | | 🔥 | 2026-04-13 | 发布 v 1.0.0 — XSafeClaw 首次公开发布，包含 Claw Monitor、Safe Chat、Asset Shield、Guard、Agent Office 和 Onboard Setup。 | ## 🔍 什么是 XSafeClaw？ XSafeClaw 是一个面向 AI Agent 的开源安全平台，旨在让 Agent 的行为变得可见、可控且值得信赖。它将复杂的 Agent 执行过程转化为直观的可视化“Safe Agent Valley”，提供实时监控、风险拦截、human-in-the-loop 治理和自动化红队测试——所有这些只需一个 `xsafeclaw start` 命令即可使用。当前的 runtime 注册表可以同时发现本地的 OpenClaw、Hermes Agent 和 nanobot 安装，然后在 Agent Town 中让您按会话选择 runtime。 | 模块 | 描述 | | :------------------- | :----------------------------------------------------------- | | **Claw Monitor** | 实时会话时间轴，包含跨 OpenClaw、Hermes 和 nanobot 会话的事件跟踪、token 用量、工具调用检查、技能与内存扫描 | | **Safe Chat** | 通过各 runtime 的 gateway/API 与 OpenClaw、Hermes 或 nanobot 进行安全对话 | | **Asset Shield** | 文件系统扫描，包含风险分类（L0–L3）、软件审计、硬件清单 | | **Agent Guard** | 轨迹级别和工具调用级别的安全评估，支持 human-in-the-loop 审批 | | **Pixel Office** | 基于 PixiJS 的 2D 可视化，展示所有 Agent 的状态和活动 | | **Onboard Setup** | OpenClaw、Hermes 和 nanobot 的交互式设置，包括模型配置和 runtime guard 集成 | ## 🚀 快速入门 ``` pip install xsafeclaw xsafeclaw start ``` 浏览器会自动打开 `http://127.0.0.1:6874`。如果未安装受支持的 runtime，Web UI 将引导您完成 OpenClaw、Hermes 或 nanobot 的设置。 常用选项： ``` xsafeclaw start --port 8080 # custom port xsafeclaw start --host 0.0.0.0 # accessible from LAN xsafeclaw start --no-browser --reload # headless dev mode ``` ## 🛡️ Guard：工作原理 XSafeClaw 的 guard 系统通过两层防御来保护用户： 1. **轨迹级别评估** — 完整的对话历史将发送给 guard 模型（AgentDoG），该模型会评估整个交互序列是否存在多轮对话中出现的潜在风险。 2. **工具调用拦截** — 每次工具调用都会通过一个 `before_tool_call` hook。如果 guard 模型认为其不安全，该调用将被保留在一个待处理队列中等待人工审查。 ``` Agent wants to run a tool │ ▼ Guard Model evaluates │ ┌────┴────┐ │ │ Safe Unsafe │ │ ▼ ▼ Execute Hold for human review ┌────┴────┐ │ │ Approve Reject │ │ ▼ ▼ Execute Block + notify agent ``` 当被拒绝（或在 5 分钟后超时）时，Agent 将被指示**停止所有后续操作**，**向用户告知风险**，并**等待明确确认**。 ## 🏗️ 架构 ``` Browser (:6874) │ ┌───────────┴───────────┐ │ FastAPI Server │ ├───────────────────────┤ │ Runtime Registry │◄── OpenClaw / Hermes / nanobot discovery │ Runtime Autostart │◄── best-effort gateway startup │ Guard Service │◄── AgentDoG model │ File Watcher │◄── runtime JSONL sessions │ Asset Scanner │◄── file/software/hardware scanning └───────────┬───────────┘ │ SQLite DB │ ~/.xsafeclaw/ │ ┌───────────────────┼───────────────────┐ │ │ │ OpenClaw Agent Hermes Agent nanobot Agent safeclaw plugin Hermes plugin XSafeClaw hook ws://:18789 http://:8642 gateway + websocket └───────────────────┴───────────────────┘ │ POST /api/guard/tool-check ``` | 层级 | 技术 | | :---------- | :------------------------------------------------ | | 后端 | Python 3.11, FastAPI, SQLAlchemy (async), uvicorn | | 前端 | React 19, TypeScript, Vite, Tailwind CSS 4 | | 数据库 | SQLite (via aiosqlite) | | Guard 模型 | AgentDoG (可配置的 base URL 和模型) | | 运行环境 | 本地 OpenClaw、Hermes Agent 和 nanobot，支持按会话选择 | 运行时可在 `http://localhost:6874/docs` 获取完整的 API 文档。 ## 📦 安装说明 有关详细的安装步骤，请参阅 **[安装指南](docs/installation.md)**。 ``` # 从 PyPI 安装（推荐） pip install xsafeclaw # 从 GitHub 安装 pip install git+https://github.com/XSafeAI/XSafeClaw.git # 从源码安装 git clone https://github.com/XSafeAI/XSafeClaw.git cd XSafeClaw && pip install . # 开发 git clone https://github.com/XSafeAI/XSafeClaw.git cd XSafeClaw && pip install -e ".[dev]" ``` ### 🔌 安装 Guard 插件 安装和配置流程会自动安装匹配的 Guard 集成。如果您正在手动配置 runtime，请使用下方特定于 runtime 的路径。 对于 OpenClaw，复制 TypeScript 插件： ``` cp -r plugins/safeclaw-guard ~/.openclaw/extensions/safeclaw-guard ``` 然后添加到 `~/.openclaw/openclaw.json`： ``` { "plugins": { "entries": { "safeclaw-guard": { "path": "~/.openclaw/extensions/safeclaw-guard" } } } } ``` 对于 Hermes，将 Python 插件复制到 Hermes 的插件目录： ``` mkdir -p ~/.hermes/plugins/safeclaw-guard cp -r plugins/safeclaw-guard-hermes/* ~/.hermes/plugins/safeclaw-guard/ ``` 对于 nanobot，复制 Python 插件，并确保 XSafeClaw 包在 nanobot 的 uv 工具环境中可用： ``` mkdir -p ~/.nanobot/plugins/safeclaw-guard cp -r plugins/safeclaw-guard-nanobot/* ~/.nanobot/plugins/safeclaw-guard/ uv tool install nanobot-ai --with-editable . --force ``` Nanobot 配置页面在您保存时会自动执行此操作：它会复制插件，将 hook 条目写入 `~/.nanobot/config.json`，并将 `SAFETY.md` / `PERMISSION.md` 部署到 nanobot 工作区。该插件会在每次 nanobot agent 轮次中注入这些安全模板，并通过 XSafeClaw Guard 检查工具调用。 在您进行配置之前，Provider、模型和 API 密钥会保持为空。 出于兼容性考虑，旧版的 setup endpoint 仍然存在，并且仅创建一个没有 provider/model 默认值的骨架配置： ``` curl -X POST http://127.0.0.1:6874/api/system/nanobot/init-default ``` ### Runtime 网关 XSafeClaw 会在服务器启动和设置完成后，尽最大努力自动启动已安装的 runtime： - OpenClaw: `openclaw gateway start --json`，默认为 `ws://127.0.0.1:18789`。 - Hermes: 启用 HTTP API 并启动/重启 `hermes gateway`，默认为 `http://127.0.0.1:8642`。 - nanobot: 以后台方式运行 `nanobot gateway --port `，默认健康检查端口为 `18790`，WebSocket 频道为 `ws://127.0.0.1:8765/`。 手动命令对于故障排除仍然很有用： ``` openclaw gateway start hermes gateway nanobot gateway --port 18790 --verbose ``` 如果您手动编辑了 runtime 配置文件，请重启受影响的 gateway 以便其重新加载新设置。当前的集成不需要使用 `nanobot serve`。 ## ⚙️ 配置 XSafeClaw 开箱即用，具有合理的默认设置。复制 `.env.example` 到 `.env` 进行自定义： | 变量 | 默认值 | 描述 | | :------- | :------ | :---------- | | `API_PORT` | `6874` | XSafeClaw API 端口 | | `API_HOST` | `0.0.0.0` | 绑定地址 | | `DATA_DIR` | `~/.xsafeclaw` | SQLite 数据库和本地状态目录 | | `PLATFORM` | `auto` | 默认实例提示：`auto`、`openclaw`、`hermes` 或 `nanobot`；所有已发现的 runtime 仍可被选择 | | `AUTO_START_RUNTIMES` | `true` | 尽最大努力为已安装的 OpenClaw、Hermes 和 nanobot runtime 自动启动 gateway | | `OPENCLAW_SESSIONS_DIR` | `~/.openclaw/agents/main/sessions` | OpenClaw 会话目录 | | `HERMES_HOME` | `~/.hermes` | Hermes 主目录 | | `HERMES_API_PORT` | `8642` | Hermes HTTP API 端口 | | `HERMES_API_KEY` | *(空)* | 必须与 `~/.hermes/.env` 中的 `API_SERVER_KEY` 匹配 | | `~/.nanobot/config.json` | *(在 Nanobot Configure 中保存时创建)* | nanobot config、gateway、workspace、WebSocket 和 XSafeClaw hook 设置 | | `GUARD_BASE_URL` / `GUARD_BASE_MODEL` | AgentDoG 默认值 | Guard 模型的 endpoint 和模型 ID | OpenClaw 的配置位于 `~/.openclaw/openclaw.json`，Hermes 的配置位于 `~/.hermes/.env` 和 `~/.hermes/config.yaml`，nanobot 的配置位于 `~/.nanobot/config.json`。请查看 `.env.example` 获取完整列表。 ## 🔧 开发 前置条件：Python 3.11+、Node.js 18+、[uv](https://docs.astral.sh/uv/)（推荐） ``` # 安装 uv 项目管理器（如果你尚未安装） curl -LsSf https://astral.sh/uv/install.sh | sh ``` ``` git clone https://github.com/XSafeAI/XSafeClaw.git && cd XSafeClaw # Backend uv venv && uv pip install -e ".[dev]" python run.py # http://localhost:6874, auto-reload # 用于本地测试的 Optional runtime CLI uv tool install nanobot-ai --with-editable . --force openclaw gateway start hermes gateway nanobot gateway --port 18790 --verbose # Frontend（独立终端） cd frontend && npm install && npm run dev # http://localhost:3003, HMR # 为生产环境构建 Frontend cd frontend && npm run build # outputs ignored Vite artifacts to src/xsafeclaw/static/ ``` 对于 Linux/macOS 上的仓库开发循环，`bash setup.sh` 会一次性安装后端和前端依赖，而 `bash start.sh` 会在 `:6874` 上运行 Vite，并在 `:3022` 上代理 FastAPI 后端。 ## 🙏 致谢 - [**OpenClaw**](https://github.com/openclaw/openclaw) — XSafeClaw 旨在保护的个人 AI 助手平台。OpenClaw 开放的插件架构使我们的 guard 集成成为可能。 - [**Hermes Agent**](https://github.com/NousResearch/hermes-agent) — 本地 Python Agent runtime 和多平台网关，现已成为 XSafeClaw 的一等运行时。 - [**nanobot**](https://github.com/HKUDS/nanobot) — 通过 XSafeClaw 的网关、WebSocket 和 Python hook 支持集成的轻量级本地 Agent runtime。 - [**AgentDoG**](https://github.com/AI45Lab/AgentDoG) — 面向 AI Agent 安全的诊断护栏框架。XSafeClaw 的 guard 模块由 AgentDoG 的轨迹级别风险评估和细粒度安全分类法提供支持。 - [**ISC-Bench**](https://github.com/wuyoscar/ISC-Bench) — 关于前沿 LLM 中内部安全崩溃的研究。ISC-Bench 对任务驱动型安全失效的洞察为我们的红队测试设计提供了参考。 - [**AgentHazard**](https://github.com/Yunhao-Feng/AgentHazard) — 用于评估计算机使用 Agent 有害行为的基准。AgentHazard 的攻击分类学和执行层面的风险类别塑造了我们的威胁建模。 ## ⚠️ 免责声明 ## 💼 商业用途 XSafeClaw 采用 MIT 许可证开源，仅供学术研究和个人使用。如需**商业授权、企业部署或合作**，请联系： **邮箱：** xingjunma@fudan.edu.cn ## 📄 许可证 [MIT](LICENSE)

标签：AI安全, AV绕过, Chat Copilot, CISA项目, FastAPI, LLM代理, Python, React, Syscalls, XSafeClaw, 会话管理, 后端开发, 复旦大学, 大模型安全, 安全测试, 安全网关, 审计系统, 开源平台, 攻击性安全, 文档安全, 无后门, 智能体安全, 监控与防护, 网络安全, 逆向工具, 隐私保护