Openclaw Guard / 龙虾卫士

因为个人精力有限，项目暂时搁置

Openclaw Guard（龙虾卫士）是一个面向 OpenClaw 的非侵入式安全增强客户端与本地控制面。

项目目标不是替换 OpenClaw，而是在不修改 OpenClaw 源码的前提下，为 OpenClaw 增加更清晰的安全交互、更可控的执行前审批、更完整的基线扫描与审计能力，并把这些能力集中到一个可直接使用的前端工作台中。

项目简介

它适合以下场景：

高安全终端或内网环境中的 OpenClaw 部署
需要对危险动作做“先审批、再执行”的本地防护
需要对 OpenClaw 配置、运行状态、基线风险和审计日志进行集中管理
需要保留 OpenClaw 原有工程结构，不希望修改官方源码

核心特性

非侵入式接入 OpenClaw
- 不修改 OpenClaw 源码
- 通过 OpenClaw 原生 Hook、Gateway 调用、本地插件桥与 Guard Web 前端完成联动
对话式工作台
- 从 Guard 前端直接与 OpenClaw 对话
- 支持模型切换、会话重置、状态检测、运行时调试
执行前风险控制
- 删除、写入、配置修改、危险命令、外联、渠道发送、技能执行等动作会先经过 Guard 决策
- 支持 allow / ask / block / escalate
- 高风险动作需要明确确认后才继续执行
基线扫描与风险展示
- 扫描 OpenClaw 配置、运行用户、网络暴露、日志、依赖与 Hook 状态
- 输出 JSON / HTML / PDF 报告与整改脚本
- 前端提供动态扫描界面、检查项详情和整改建议
审计与导出
- SQLite + JSONL 双写审计
- 支持 JSON / CSV 导出
- 适配本地取证与后续集成
普通用户模式
- 提供 normal 一键启动入口
- 默认打开更简洁的操作界面

界面预览

对话页面

动作审查页面

基线扫描页面

项目结构

OpenclawGuard/
├── openclaw_guard/         # 核心后端代码
│   ├── baseline.py         # 基线扫描与报告生成
│   ├── behavior.py         # 行为事件采集与整理
│   ├── control.py          # 审批与执行决策
│   ├── detection.py        # 规则引擎与风险判定
│   ├── discovery.py        # OpenClaw 环境发现
│   ├── hook_runtime.py     # OpenClaw Hook 插件写入与检查
│   ├── manager.py          # 统一编排层
│   ├── openclaw_adapter.py # OpenClaw Gateway / Session / Chat 适配
│   ├── ui.py               # 前端静态资源生成
│   ├── web.py              # 本地 HTTP 服务与 API
│   └── whitelist.py        # 白名单匹配
├── docs/                   # VuePress 文档站
├── pics/                   # README / 文档截图
├── tests/                  # 自动化测试
├── scripts/                # 安装与卸载脚本
├── docker/                 # Docker 部署文件
└── k8s/                    # Kubernetes / Sidecar 示例

工作原理

Openclaw Guard 的核心链路可以概括为：

Guard 自动发现本机 OpenClaw 配置、工作区、日志目录与 Gateway 状态
Guard 将本地 Hook 插件写入 OpenClaw 配置，并通过 OpenClaw 官方插件机制接入 before_tool_call / after_tool_call
用户从 Guard 前端发起对话或操作
OpenClaw 在真正调用工具前，先把请求交给 Guard 判定
Guard 根据规则、白名单、上下文与风险等级给出 allow / ask / block / escalate
若需要审批，前端会展示待确认动作；用户明确确认后，OpenClaw 才会继续执行
执行结果、日志和审计记录会统一写回 Guard

快速开始

1. 环境要求

Python 3.13+
Node.js 与 npm
已可正常运行的 OpenClaw

2. 安装

cd OpenclawGuard
bash scripts/install.sh
source .venv/bin/activate

3. 一键启动普通模式

python -m openclaw_guard.main normal

该命令会：

自动发现 OpenClaw 配置
准备 runtime/、output/、exports/ 等目录
自动补齐一份基线扫描结果
启动本地 Web 服务
打开简洁模式界面

4. 启动完整模式

python -m openclaw_guard.main launch

5. 仅做自检

python -m openclaw_guard.main normal --once --no-browser

常用命令

启动普通模式

python -m openclaw_guard.main normal

启动完整模式

python -m openclaw_guard.main launch --no-browser

运行基线扫描

python -m openclaw_guard.main baseline --config-path ~/.openclaw/openclaw.json

导出审计数据

python -m openclaw_guard.main export-audit

摄入一条行为事件

python -m openclaw_guard.main action --event-file examples/dangerous-delete.json

前端能力

当前前端已经支持以下主要功能：

聊天与会话管理
OpenClaw 连接状态检测
当前模型与 Agent 状态展示
模型切换
新建会话
待确认动作审批
动作分页浏览
技能管理
渠道管理
运行时 Hook 状态检查
基线扫描与整改建议查看
审计导出
运行时调试信息与日志查看

目标是让普通用户尽量不需要直接去改配置文件、翻日志目录或手动调用命令行接口。

输出目录

运行过程中，Guard 会生成以下内容：

基线扫描输出

output/reports/compliance-report.json
output/reports/compliance-report.html
output/reports/compliance-report.pdf
output/fixes/baseline-remediation.sh

审计与导出

output/audit/audit.db
output/audit/audit.jsonl
exports/audit-export.json
exports/audit-export.csv

运行时数据

runtime/ui/
runtime/guard.log
runtime/controlled-actions.json
runtime/latest-baseline.json
runtime/openclaw-guard-plugin/

文档站

本项目附带完整 VuePress 文档站，位于 docs/。

本地预览：

cd docs
npm install
npm run docs:dev

构建静态站点：

cd docs
npm run docs:build

部署方式

本地部署

直接使用 Python 启动：

python -m openclaw_guard.main normal

Docker

参考：

docker/Dockerfile

Kubernetes / Sidecar

参考：

k8s/openclaw-guard-sidecar.yaml

与 OpenClaw 的集成说明

Openclaw Guard 遵循“非侵入式”原则：

不修改 OpenClaw 源码
不替换系统库
不要求改动 OpenClaw 官方前端代码

它主要通过以下方式与 OpenClaw 交互：

OpenClaw Gateway RPC
OpenClaw sessions.patch / chat.send / chat.history / agent.wait
OpenClaw 原生 Hook
本地运行时插件桥

如果 Guard 已写入 Hook 插件但仍未生效，通常需要按你的实际启动方式重启 OpenClaw Gateway。

例如：

cd /path/to/openclaw
npm run openclaw gateway

测试

运行完整测试：

python -m unittest discover -s tests -v

FAQ

1. Guard 会修改 OpenClaw 源码吗？

不会。Openclaw Guard 设计上遵循非侵入式原则，不修改 OpenClaw 官方源码文件。当前集成方式主要依赖：

Gateway RPC
OpenClaw 原生 Hook
本地运行时插件桥
Guard 自己的前端与本地 HTTP 服务

2. 为什么 Guard 已启动，但仍提示运行时不可达？

通常有以下几种原因：

OpenClaw Gateway 尚未启动
Gateway 已启动，但当前鉴权信息与 Guard 读取到的配置不一致
Hook 插件已经写入配置，但当前运行中的 Gateway 进程还没有重启加载它
本机回环地址、局域网绑定方式或端口暴露状态与当前配置不一致

建议优先检查：

openclaw.json 中的 gateway 配置
Guard 设置页中的运行时调试信息
runtime/guard.log

3. 为什么模型切换后，实际回复模型和界面显示不一致？

当前版本已经优先使用 OpenClaw 会话中的真实 session key 和 canonical model 标识来切模型，并在切换后回读会话模型确认结果。如果仍然不一致，通常说明：

当前运行中的 OpenClaw 会话不是 Guard 正在控制的那一个
Gateway 返回的是旧会话状态
当前 provider 已限流或不可用，OpenClaw 在运行时做了降级或回退

4. 危险动作什么时候会被拦截？

当前重点覆盖这些动作：

删除文件
写入文件
修改配置
外联请求
渠道发送
技能执行
OpenClaw 工具层 Hook 进入的高风险工具调用

其中高风险动作会先进入审批，不会直接继续执行。

5. 普通用户应该怎么启动？

推荐直接使用：

python -m openclaw_guard.main normal

这个模式会自动准备运行目录、补一份基线扫描结果，并打开更简洁的前端界面。

已知边界

当前版本已经能完成真实对话、模型切换、Hook 接入、动作审批、基线扫描与审计导出，但仍有这些边界：

ptrace / eBPF 目前主要是能力探测与接口预留，主执行链依赖 OpenClaw 原生 Hook
某些不走 before_tool_call 的内部运行路径，仍需要继续补充覆盖
运行时链路依赖 OpenClaw Gateway 的实际可达性与鉴权配置
前端仍在持续优化中，当前版本已支持局部 patch、增量消息刷新和轻量状态轮询，但还会继续打磨

参考资料

许可证

本项目采用 Apache-2.0 开源协议。

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
docker		docker
docs		docs
examples		examples
k8s		k8s
openclaw_guard		openclaw_guard
pics		pics
scripts		scripts
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Openclaw Guard / 龙虾卫士

目录

项目简介

核心特性

界面预览

对话页面

动作审查页面

基线扫描页面

项目结构

工作原理

快速开始

1. 环境要求

2. 安装

3. 一键启动普通模式

4. 启动完整模式

5. 仅做自检

常用命令

启动普通模式

启动完整模式

运行基线扫描

导出审计数据

摄入一条行为事件

前端能力

输出目录

基线扫描输出

审计与导出

运行时数据

文档站

部署方式

本地部署

Docker

Kubernetes / Sidecar

与 OpenClaw 的集成说明

测试

FAQ

1. Guard 会修改 OpenClaw 源码吗？

2. 为什么 Guard 已启动，但仍提示运行时不可达？

3. 为什么模型切换后，实际回复模型和界面显示不一致？

4. 危险动作什么时候会被拦截？

5. 普通用户应该怎么启动？

已知边界

参考资料

许可证

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages