README_zh.md

June 21, 2026 · View on GitHub

English · 中文文档

XSafeClaw：监控并保护你的智能体 🚀

XSafeClaw Logo

Python 3.11+ FastAPI React 19 License: MIT

🔥🔥 现已支持 OpenClaw、Hermes 和 Nanobot！🔥🔥

AI 智能体不只是新软件，它们是可以被「说服」去做危险事情的软件。随着智能体从聊天机器人演变为能够浏览网页、执行代码、接入真实工作流的主动系统，我们在还没想好如何「上锁」之前，就已经把基础设施的钥匙交给了语言模型。

这从根本上打破了传统安全假设。在常规系统中，行为由代码定义；在智能体中，行为在运行时由指令、检索内容、记忆和长链路决策循环动态涌现。攻击者不再需要利用漏洞，他们可以操纵智能体的推理、重定向其执行轨迹，或将小权限逐步扩大。提示注入、工具滥用、静默权限提升不是边缘情况，而是执行模型的结构性属性。大多数团队只在事后读日志时才发现问题——那是取证，不是安全。

XSafeClaw 正是为此而生。它是一个开源智能体防御平台，将智能体安全视为实时控制问题，而非事后复盘。在智能体时代，没有防御的能力不是进步，而是未受管理的暴露风险。

🚀 快速开始  ·  📖 安装文档  ·  🌐 项目官网  ·  🌍 Star 用户星图  ·  ▶️ 演示视频

🎬 XSafeClaw 介绍

XSafeClaw：来自复旦大学的开源智能体安全平台

📰 最新动态

版本发布与项目里程碑。

日期更新
🔥2026-06-12v1.1.1 发布并已上传至 PyPI — 优化 Agent Town 任务界面、OpenClaw 配置与 gateway 连接稳定性，完善重置清理、会话标签、标题展示、Smart Router 标签处理和后端页面视觉效果。
🔥2026-06-10v1.1.0 发布并已上传至 PyPI — Runtime Guard 完善审批请求展示与 Hermes 会话上下文守卫覆盖，新增智能体推荐、预算控制，并优化后端页面与 Agent Valley 视觉体验。
🔥2026-05-22v1.0.9 发布 — 安全对话与 Agent Valley 的聊天回复现已正常渲染 Markdown，OpenClaw、Hermes、Nanobot 的标题、列表、表格、代码块与分隔线都会按可读格式展示。
🔥2026-05-09v1.0.8 发布 — 跨 OpenClaw、Hermes、Nanobot 三运行时的逐模型 Token 用量与成本核算现已统一；支持并发多会话消息；各运行时的 Memory 扫描类型已对齐。
🔥2026-04-29v1.0.7 发布 — Nanobot 连接功能正式集成：XSafeClaw 现可主动连接运行中的 Nanobot 实例，建立受 Guard 保护的对话会话，并将 Nanobot 活动与 OpenClaw、Hermes 统一呈现在同一视图中。
🔥2026-04-26v1.0.5 发布 — nanobot 引导安装现在遵循官方跨平台安装流程，未配置 API key 时 Setup 不会误判失败，Agent Valley 独立页面也补上了 React Query Provider。
🔥2026-04-25v1.0.4 发布 — XSafeClaw 公开支持 OpenClaw、nanobot、Hermes 同时并列运行，并修复了若干已知问题。
🔥2026-04-23支持 Hermes 与运行时自动启动 — XSafeClaw 现在可以并列发现 OpenClaw、Hermes 与 nanobot，并在服务启动时 best-effort 自动拉起已安装运行时的 gateway。
🔥2026-04-18支持本机 nanobot 运行时 — XSafeClaw 现在可以发现本机 nanobot 实例，通过 nanobot gateway 创建受 Guard 保护的聊天会话，并在 Agent Valley 中同时展示混合运行时会话。
🔥2026-04-13v1.0.0 发布 — XSafeClaw 首个公开版本，包含安全监控、安全对话、资产防护、Guard 守卫、智能体办公室与引导安装全部模块。

🔍 XSafeClaw 是什么？

XSafeClaw 是一个开源 AI 智能体安全平台，旨在让智能体行为变得可见、可控、可信赖。它将复杂的智能体执行过程转化为直观的可视化「安全智能体谷」，提供实时监控、风险拦截、人机协同治理与自动化红队测试——只需一条 xsafeclaw start 命令即可启动。当前运行时注册表会并列发现宿主机上的 OpenClaw、Hermes Agent 与 nanobot，并允许在 Agent Town 中为每个会话选择运行时。

模块说明
安全监控 (Claw Monitor)实时会话时间线，覆盖 OpenClaw、Hermes 与 nanobot 会话的事件追踪、Token 用量、工具调用检查、技能与记忆扫描
安全对话 (Safe Chat)通过各运行时 gateway/API 与 OpenClaw、Hermes 或 nanobot 智能体安全对话
资产防护 (Asset Shield)文件系统扫描与风险分级（L0–L3）、软件审计、硬件清单
安全守卫 (Agent Guard)轨迹级与工具调用级安全评估，支持人工审批工作流
智能体办公室 (Pixel Office)基于 PixiJS 的 2D 可视化界面，集中查看所有智能体状态与活动
引导安装 (Onboard Setup)交互式安装与配置 OpenClaw、Hermes、nanobot，包括模型配置与运行时 Guard 集成

🚀 快速开始

pip install xsafeclaw
xsafeclaw start

浏览器会自动打开 http://127.0.0.1:6874。如果尚未安装任何支持的运行时，Web 界面会引导你安装 OpenClaw、Hermes 或 nanobot。

常用选项：

xsafeclaw start --port 8080              # 自定义端口
xsafeclaw start --host 0.0.0.0           # 局域网可访问
xsafeclaw start --no-browser --reload    # 无头开发模式

🛡️ Guard：工作原理

XSafeClaw 的安全守卫通过双层防御保护用户：

  1. 轨迹级评估 — 将完整对话历史发送至守卫模型（AgentDoG），评估整个交互序列中可能跨多轮涌现的风险。

  2. 工具调用拦截 — 每次工具调用都经过 before_tool_call 钩子。如果守卫模型判定为不安全，该调用会被挂起，等待人工审批。

智能体请求执行工具
        │
        ▼
   守卫模型评估
        │
   ┌────┴────┐
   │         │
  安全      不安全
   │         │
   ▼         ▼
  执行     挂起等待人工审批
           ┌────┴────┐
           │         │
         批准       拒绝
           │         │
           ▼         ▼
         执行     阻止 + 通知智能体

当工具调用被拒绝（或超时 5 分钟未处理）时，智能体会被要求：立即停止后续操作、告知用户风险、等待用户明确确认后再继续。

🏗️ 架构

                         浏览器 (:6874)
                              │
                  ┌───────────┴───────────┐
                  │     FastAPI 服务器     │
                  ├───────────────────────┤
                  │   运行时注册表         │◄── OpenClaw / Hermes / nanobot 发现
                  │   运行时自动启动       │◄── best-effort gateway 启动
                  │   Guard 服务          │◄── AgentDoG 模型
                  │   文件监听器           │◄── 各运行时 JSONL 会话
                  │   资产扫描器           │◄── 文件/软件/硬件扫描
                  └───────────┬───────────┘
                              │
                    SQLite DB │ ~/.xsafeclaw/
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
    OpenClaw 智能体      Hermes 智能体        nanobot 智能体
    safeclaw 插件        Hermes 插件          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 (aiosqlite)
守卫模型AgentDoG（可配置 Base URL 和模型）
运行时本机 OpenClaw、Hermes Agent 与 nanobot，支持按会话选择

运行时可访问 http://localhost:6874/docs 查看完整 API 文档。

📦 安装

详细安装流程请参阅 安装指南。

Tip

需要 Python 3.11+。已发布的包会包含前端 bundle；源码仓库需要运行 cd frontend && npm run build 才能让后端直接提供嵌入式 UI，也可以使用 Vite 开发服务器。

# 从 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 插件

Setup 和 Configure 流程会自动安装对应运行时的 Guard 集成。手动接入时，按运行时使用下面的方式。

OpenClaw 使用 TypeScript 插件：

cp -r plugins/safeclaw-guard ~/.openclaw/extensions/safeclaw-guard

然后在 ~/.openclaw/openclaw.json 中添加：

{
  "plugins": {
    "entries": {
      "safeclaw-guard": {
        "path": "~/.openclaw/extensions/safeclaw-guard",
        "enabled": true,
        "config": {
          "safeclawUrl": "http://localhost:6874",
          "failOpenOnGuardError": false
        }
      }
    }
  }
}

Hermes 使用 Python 插件：

mkdir -p ~/.hermes/plugins/safeclaw-guard
cp -r plugins/safeclaw-guard-hermes/* ~/.hermes/plugins/safeclaw-guard/

nanobot 使用单独的 Python 插件目录，并需要让 nanobot 的 uv tool 环境能导入 XSafeClaw：

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 workspace。该插件会在每轮 nanobot agent 对话中注入这些安全模板，并通过 XSafeClaw Guard 检查工具调用。

首次进入时不会预填 provider、model 或 API Key。

兼容旧流程时，初始化接口仍然保留，但它只会创建不含 provider/model 默认值的 skeleton 配置：

curl -X POST http://127.0.0.1:6874/api/system/nanobot/init-default

运行时 Gateway

XSafeClaw 会在服务启动时和安装/初始化后 best-effort 自动启动已安装运行时：

  • 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 <配置端口>，默认 health 端口 18790，WebSocket channel 为 ws://127.0.0.1:8765/。

手动命令主要用于排障：

openclaw gateway start
hermes gateway
nanobot gateway --port 18790 --verbose

如果手动修改运行时配置文件，需要重启对应 gateway 才能加载新设置。当前 nanobot 集成不需要启动 nanobot serve。

⚙️ 配置说明

XSafeClaw 默认配置开箱即用。如需自定义，将 .env.example 复制为 .env 进行修改：

变量默认值说明
API_PORT6874XSafeClaw API 端口
API_HOST0.0.0.0绑定地址
DATA_DIR~/.xsafeclawSQLite 数据库与本地状态目录
PLATFORMauto默认实例提示：auto、openclaw、hermes 或 nanobot；所有已发现运行时仍可选择
AUTO_START_RUNTIMEStrue自动尝试启动已安装的 OpenClaw、Hermes 与 nanobot gateway
OPENCLAW_SESSIONS_DIR~/.openclaw/agents/main/sessionsOpenClaw 会话目录
HERMES_HOME~/.hermesHermes 主目录
HERMES_API_PORT8642Hermes HTTP API 端口
HERMES_API_KEY（空）需与 ~/.hermes/.env 中的 API_SERVER_KEY 一致
~/.nanobot/config.json（在 Nanobot 配置页保存时生成）nanobot 配置、gateway、workspace、WebSocket 与 XSafeClaw hook 设置
GUARD_BASE_URL / GUARD_BASE_MODELAgentDoG 默认值守卫模型 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（推荐）

# 安装 uv（如尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/XSafeAI/XSafeClaw.git && cd XSafeClaw

# 后端
uv venv && uv pip install -e ".[dev]"
python run.py                    # http://localhost:6874，支持热重载

# 可选：本机运行时测试
uv tool install nanobot-ai --with-editable . --force
openclaw gateway start
hermes gateway
nanobot gateway --port 18790 --verbose

# 前端（另开终端）
cd frontend && npm install && npm run dev   # http://localhost:3003，支持 HMR

# 构建前端用于生产
cd frontend && npm run build     # 输出被 git 忽略的 Vite 产物到 src/xsafeclaw/static/

在 Linux/macOS 的仓库开发流程中，可以先运行 bash setup.sh 安装依赖，再运行 bash start.sh。该脚本会把 Vite 前端运行在 :6874，FastAPI 后端运行在 :3022 并由 Vite 代理 /api。

⭐ Star History

Star History Chart

🙏 致谢

  • OpenClaw — XSafeClaw 所守护的个人 AI 助手平台。OpenClaw 开放的插件架构使我们的安全守卫集成成为可能。
  • Hermes Agent — XSafeClaw 现在作为一等运行时支持的本机 Python 智能体与多平台 gateway。
  • nanobot — 通过 gateway、WebSocket 与 Python hook 接入 XSafeClaw 的轻量级本机智能体运行时。
  • AgentDoG — AI 智能体安全诊断守卫框架。XSafeClaw 的 Guard 模块基于 AgentDoG 的轨迹级风险评估和细粒度安全分类体系构建。
  • ISC-Bench — 前沿大语言模型内部安全崩溃研究。ISC-Bench 对任务完成驱动型安全失败的深入洞察，为我们的红队测试设计提供了重要参考。
  • AgentHazard — 计算机使用智能体有害行为评估基准。AgentHazard 的攻击分类体系和执行级风险类别为我们的威胁建模提供了借鉴。

⚠️ 免责声明

Caution

XSafeClaw 是一款用于提升 AI 智能体系统安全性的研究工具。红队测试功能仅用于防御性安全研究和评估目的。请勿将本工具用于造成伤害或从事任何恶意活动。

💼 商用联系

XSafeClaw 基于 MIT 许可证开源，可用于学术研究和个人使用。如您有商业授权、企业部署或合作需求，请联系：

邮箱： xingjunma@fudan.edu.cn

👥 贡献者

我们欢迎各种形式的贡献——Bug 报告、功能建议、文档完善和代码贡献。

📄 许可证

MIT