ClawSentry¶

Agent Harness Protocol (AHP) 参考实现

面向 AI Agent 运行时的统一安全监督网关 —— 归一化多框架事件，三层递进决策，实时可视化监控。

什么是 ClawSentry？¶

AHP（Agent Harness Protocol） 是一套开放的 AI Agent 安全监督协议规范，定义了事件归一化、风险评估和决策执行的标准接口。

ClawSentry 是该协议的 Python 参考实现。它以 Sidecar 形式部署，拦截 Agent 运行时的工具调用事件，通过三层递进式决策模型（规则 → 语义 → Agent 审查）做出 ALLOW / DENY / DEFER 判决，并提供实时监控仪表板。

核心定位

AHP 是协议，ClawSentry 是实现。协议定义"说什么"，实现决定"怎么做"。

核心亮点¶

三层决策¶

L1 规则 (<1ms) → L2 语义 (<3s) → L3 Agent (<30s)

逐层升级，兼顾速度与深度

双框架接入¶

a3s-code + OpenClaw

统一 AHP 协议归一化事件

实时监控¶

SSE 推送 + CLI Watch + Web 仪表板

决策/告警/会话全链路可观测

安全优先¶

Fail-closed 高危 + Bearer Token + HMAC 签名

生产级安全加固

架构总览¶

graph TB
    subgraph Agents["Agent 框架"]
        A3S["a3s-code<br/>(stdio / HTTP)"]
        OC["OpenClaw<br/>(WebSocket / Webhook)"]
    end

    subgraph Adapters["适配器层"]
        A3SA["A3S Adapter"]
        OCA["OpenClaw Adapter"]
    end

    subgraph Core["ClawSentry 核心"]
        CE["CanonicalEvent<br/>(AHP 统一协议)"]
        L1["L1 规则引擎<br/>D1-D5 五维评分 · <1ms"]
        L2["L2 语义分析<br/>RuleBased / LLM · <3s"]
        L3["L3 审查 Agent<br/>多轮工具推理 · <30s"]
        PE["PolicyEngine<br/>决策编排"]
    end

    subgraph State["状态与存储"]
        SR["SessionRegistry<br/>会话追踪"]
        TS["TrajectoryStore<br/>轨迹持久化"]
        EB["EventBus<br/>事件广播"]
        AR["AlertRegistry<br/>告警聚合"]
    end

    subgraph Output["输出通道"]
        SSE["SSE 实时推送"]
        CLI["clawsentry watch<br/>终端监控"]
        WEB["Web 仪表板<br/>React SPA"]
        API["REST API<br/>报表 & 管理"]
    end

    A3S --> A3SA
    OC --> OCA
    A3SA --> CE
    OCA --> CE
    CE --> PE
    PE --> L1
    L1 -->|"需升级"| L2
    L2 -->|"需升级"| L3
    L1 & L2 & L3 --> PE
    PE --> SR
    PE --> TS
    SR --> EB
    EB --> SSE
    EB --> AR
    SSE --> CLI
    SSE --> WEB
    AR --> API

快速安装¶

基础安装含 LLM 支持完整安装开发环境

pip install clawsentry

pip install clawsentry[llm]

pip install clawsentry[all]

git clone https://github.com/Elroyper/ClawSentry.git
cd ClawSentry
pip install -e ".[dev]"

环境要求

Python >= 3.11
核心依赖：FastAPI, Uvicorn, Pydantic v2
可选依赖组：[llm]（Anthropic / OpenAI）、[enforcement]（WebSocket）、[dev]（测试）

三层决策模型¶

层级	名称	延迟	机制	适用场景
L1	规则引擎	<1ms	D1-D5 五维评分（命令危险度/参数敏感度/上下文合理性/历史行为/作用域权限）	明确的黑白名单、已知危险模式
L2	语义分析	<3s	RuleBased / LLM / Composite 三种实现，SemanticAnalyzer 协议	需要上下文理解的灰度命令
L3	审查 Agent	<30s	AgentAnalyzer + ReadOnlyToolkit + SkillRegistry，多轮工具调用推理	复杂意图判断、需要取证分析

                  ┌─ ALLOW/DENY ──→ 直接返回
  Event ──→ L1 ──┤
                  └─ 不确定 ──→ L2 ──┬─ ALLOW/DENY ──→ 返回
                                      └─ 不确定 ──→ L3 ──→ 最终判决

升级策略

每层仅在无法确定时才向上升级，保证绝大多数请求在 L1 毫秒级完成。L3 是终审，永不降级——任何 L3 内部失败将降级为 confidence=0.0（fail-closed）。

双框架支持¶

a3s-codeOpenClaw

通过 stdio harness（主通道）或 HTTP Transport（备通道）接入。

# stdio 模式 — 作为 a3s-code hook 进程
clawsentry-harness

# HTTP 模式 — POST /ahp/a3s
clawsentry-gateway

详见 a3s-code 集成指南

通过 WebSocket 实时监听 + Webhook 接收 + 审批执行器 接入。

# 一键启动（自动检测 OpenClaw 配置）
clawsentry gateway

详见 OpenClaw 集成指南

CLI 命令一览¶

命令	说明
`clawsentry init <framework>`	零配置初始化（`--auto-detect` / `--setup` / `--dry-run`）
`clawsentry gateway`	启动 Gateway（智能检测框架，按需启用 WS/Webhook）
`clawsentry watch`	SSE 实时终端监控（`--interactive` 支持 DEFER 运维确认）
`clawsentry-gateway`	直接启动 HTTP Gateway 服务
`clawsentry-harness`	启动 a3s-code stdio harness
`clawsentry-stack`	全栈启动（Gateway + Adapter + 可选 WS）

REST API 概览¶

端点	方法	说明
`/health`	GET	健康检查
`/ahp`	POST	OpenClaw Webhook 决策
`/ahp/a3s`	POST	a3s-code HTTP Transport
`/ahp/resolve`	POST	DEFER 决策代理（allow-once / deny）
`/report/summary`	GET	跨框架聚合统计
`/report/stream`	GET	SSE 实时推送
`/report/sessions`	GET	活跃会话列表
`/report/session/{id}`	GET	会话轨迹回放
`/report/session/{id}/risk`	GET	会话风险详情
`/report/session/{id}/enforcement`	GET/POST	会话执法状态
`/report/alerts`	GET	告警列表
`/report/alerts/{id}/acknowledge`	POST	确认告警
`/ui/*`	GET	Web 仪表板静态文件

详见 REST API 文档

Web 安全仪表板¶

内置 React 18 + TypeScript + Vite 单页应用，暗色 SOC（安全运营中心）主题。

页面	功能
Dashboard	实时决策 feed、指标卡、饼图/柱状图
Sessions	会话列表、D1-D5 雷达图、风险曲线、决策时间线
Alerts	告警表格、过滤、确认、SSE 自动推送
DEFER Panel	审批倒计时、Allow/Deny 操作、503 降级提示

Gateway 在 /ui 路径自动挂载静态文件，无需额外配置。

详见 Web 仪表板文档

项目数据¶

指标	数据
测试用例	775+
测试耗时	~6.5s
协议版本	`sync_decision.1.0`
Python 版本	>= 3.11
许可证	MIT

文档导航¶

入门指南 ¶

安装、快速开始、核心概念

集成接入 ¶

a3s-code / OpenClaw 框架集成

配置参考 ¶

环境变量、策略调优、LLM 配置

REST API ¶

决策端点、报表监控、认证

决策详解 ¶

L1 规则 / L2 语义 / L3 Agent

Web 仪表板 ¶

暗色主题安全运营仪表板

ClawSentry¶

ClawSentry¶

什么是 ClawSentry？¶

核心亮点¶

三层决策¶

双框架接入¶

实时监控¶

安全优先¶

架构总览¶

快速安装¶

三层决策模型¶

双框架支持¶

CLI 命令一览¶

REST API 概览¶

Web 安全仪表板¶

项目数据¶

文档导航¶

入门指南¶

集成接入¶

配置参考¶

REST API¶

决策详解¶

Web 仪表板¶

入门指南 ¶

集成接入 ¶

配置参考 ¶

REST API ¶

决策详解 ¶

Web 仪表板 ¶