@ drakon- systems/ 屏蔽- 实时
ShieldCortex实时防御扫描和可选内存提取的OpenClaw插件.
兼容性
- 节点.js 需要22.14+LTS或24+节点(
^22.14.0 || >=24.0.0) (中文(简体) ). 这个shieldcortex同行船舶better-sqlite3^13,它使用节点-API 10;节点23不支持. - 打开Claw —— 说 2026.4.23 所需员额 —— 2026.4.23 为声明插件添加主机包链接
openclaw作为同伴的依赖关系(#70462 (英语))),它让任何未来openclaw/plugin-sdk/*在不重复运行时捆绑的情况下解析导入 - OpenClaw 2026.5.12 谈话 执行 - 那个
before_agent_run输入门最早出现于2026.5.9-β.1,而最早的船在2026.5.12. 地板下面的一切都正常 但对话防火墙是只观察的 对话防火墙(中文(简体) ) - 盾形顶点 - 所需5.x(
^5.0.0,宣布的对等依赖; 在同一版本的船舶两个包件)
OpenClaw 被宣布为 选项 端点依赖,所以安装包不会拉入 OpenClaw 的复制: OpenClaw 主机提供. 该可选旗帜仅涉及缺失的对等相;它不会在上文最低的OpenClaw 2026.4.23下提供支持.
OpenClaw 发现的包装说明
只有奉献 @drakon-systems/shieldcortex-realtime 插件宣布 OpenClaw 插件元数据(openclaw.extensions + 一个根 openclaw.plugin.json) (中文(简体) ). 主要内容 shieldcortex 软件包保存 openclaw.hooks ——记录文件所需 openclaw hooks install 流动——但 从42.0起,它不再宣布 openclaw.extensions 因此 OpenClaw 的 npm 发现不能将光主包错误为插件 .
为什么这很重要。 实时插件的 peerDependencies.shieldcortex 导致 OpenClaw 在自己的npm 树上安装主包(~/.openclaw/npm/node_modules/shieldcortex) (中文(简体) ). 与旧合同(pre-v4.2.0.0) OpenClaw扫描了光碟,找到了 openclaw.extensions,将其注册为此插件的复制件,并释放 duplicate plugin id detected; global plugin will be overridden by global pluginB. 功能上的缺陷——权利 dist/index.js 总是赢,但警告是噪音。 删除 openclaw.extensions 从主包中可以隐去赤相复制到发现;警告消失,专用插件仍然是唯一的注册目标.
防御根头 openclaw.plugin.json 被保存在主包上作为shim对OpenClaw版本的一回放出,这些版本可能仍然可以参考;一旦确认清楚,可以在后续版本中删除. 历史:v4.18.2事件(Jarvis,2026-05-16)是: plugin manifest not found 因为软件包已声明 openclaw.extensions 无 根的显示。 v4.18.3 添加了运单;v4.20.0 移除了最初需要它的声明.
OpenClaw 2026.4.23中已知的限制
- 福克子代理上下文为主机所有. 添加 OpenClaw 2026.4.23
ContextEngine.prepareSubagentSpawn({ contextMode: "isolated" | "fork" })在插件- sdk 上ContextEngine接口,但产卵本身是由主机运行时间启动的 – 插件只能对生命周期作出反应,不能调用sessions_spawn直接说 因此,从孤立的划痕记录(如批次扫描)中受益的工作仍在主会话中进行。 如果上游暴露出一个可调用插件的产卵API,扫描卸载将会被重新审视. - 不公开
systemPromptAddition在插件- sdk 中切换 . Hook 元数据 ({ name, description })被打入并稳定,但SDK并没有暴露出一个结构化的钩来为有效的系统快取贡献. SC的"靴子"注射在v2026.2.26被禁用,原因(它使用私人内部),OpenClaw的"本土记忆搜索"现在在会话开始时处理上下文回想.
它会做什么
| 钩子 | 行动 |
|---|---|
llm_input | 只观察. 通过希尔德柯特斯防御管道扫描提示和历史. OpenClaw将这个钩子归为"Conversation observation":它没有屏蔽合同,因此这里的检测无法阻止转弯. 威胁经过审核,警示,可以向Shield Cortex Cloud转发. |
before_agent_run | 对话防火墙的执行点. 记录输入门——等待它,其结果决定运行是否进行。 行为设定于 interceptor.conversation.posture (见 对话防火墙) (中文(简体) ). |
llm_output | 何时 openclawAutoMemory 实值 true,从助理回复中取出高信号记忆,并用新颖的过滤和去dupe(参见 自动记忆) (中文(简体) ). |
before_tool_call | 在工具执行前运行动作守护 。 警卫被关闭,除非 actionGuard.enabled 实值 true (见 配置) (中文(简体) ). 灾难性的外壳/文件/网络/暴动总是被阻断,而公认的危险行动是: 默认执行: 出席会议的届会获得迅速批准,未出席的届会闭幕 failurePolicy设置 actionGuard.enforce: false 选择向下以示警告和允许,或预先批准具体操作 actionGuard.autoApprove。 。 。 . |
session_end | 重置截取器的每个会话缓存, 释放该会话的扫描- 无法获取的提醒窗口,以及(与 agent_end)写作 action_guard_degraded 行动卫队在会议期间否认或警告。 甚至在 interceptor.enabled 实值 false因为对话的大门 保持每个会场状态不管。 钩子都无法阻挡、批准或拖延转弯. |
agent_end | 与退化运行的汇总器相同 session_end与它同源。 OpenClaw 2026.5.7+; 旧宿主警告返回 session_end 仍然总结. |
/shieldcortex-status | 斜线命令报告插件运行时状态 . |
扫描和内存路径是火和遗忘的:如果无法使用ShieldCortex,它们不会拖住OpenClaw转圈. 行动卫队一旦启用,就是故意的例外——它打开工具呼叫内线,由于4.47.5不能装入的警卫返回到一个没有依赖性的扫描仪上,它仍然否认明确的灾难性行动(无法关闭),而不是允许一切.
安装
1. 安装ShieldCortex
此插件解决主 shieldcortex 运行时的软件包,所以CLI也必须安装在机器可以到达的地方.
npm install -g shieldcortex
若为 shieldcortex 还没上 PATH设置 binaryPath 在插件配置中.
2. 安装插件
openclaw plugins install @drakon-systems/shieldcortex-realtime
如果您也想要伴奏会话钩, 请从主包中安装 :
openclaw skills install shieldcortex
安装后重新启动 OpenClaw :
openclaw gateway restart
地方发展
从单列波根可以直接链接工作插件目录 :
openclaw plugins install --link /path/to/ShieldCortex/plugins/openclaw
配置
插件读取配置 plugins.entries.shieldcortex-realtime.config 在您的 OpenClaw 配置中将其合并 ~/.shieldcortex/config.json。 。 。 .
示例
{
"plugins": {
"entries": {
"shieldcortex-realtime": {
"enabled": true,
"hooks": {
"allowConversationAccess": true
},
"config": {
"binaryPath": "/usr/local/bin/shieldcortex",
"openclawAutoMemory": true,
"openclawAutoMemoryDedupe": true,
"openclawAutoMemoryNoveltyThreshold": 0.88,
"openclawAutoMemoryMaxRecent": 300
}
}
}
}
}
支持的插件配置密钥 :
binaryPath: 绝对路径shieldcortex二进制cloudApiKey: 用于实时威胁转发的可选 ShieldCortex Cloud API 密钥cloudBaseUrl: 可选 API 基础 URL 覆盖openclawAutoMemory: 启用或禁用输出内存提取openclawAutoMemoryDedupe: 启用或禁用重复压制openclawAutoMemoryNoveltyThreshold:去dupe相似阈值,0.6改为0.99openclawAutoMemoryMaxRecent:去dupe缓存大小,50改为1000interceptor.conversation.posture: 对话防火墙如何用检测——off编号 :observe(默认) /enforce。见 对话防火墙。 。 。 .interceptor.failurePolicy: 当无法不经关注而获得裁决时, 将作出永久裁决( 默认 ):low编号 :medium允许,high编号 :critical拒绝)
行动卫队的防守
actionGuard 是一个 顶级 插件的密钥 config 对象。 这是
警犬的位置和写作的
{ "config": { "actionGuard": {
"enabled": true,
"enforce": true,
"notify": { "enabled": true, "webhookUrl": "https://hook.example/shieldcortex" }
} } }
interceptor.actionGuard 是一个 贬值的别名,仍然接受这样的配置
在顶级密钥存在之前写出 。 两个地点
对照插件的图案和清单验证 configSchema两者
由解析器读取;在相冲突的密钥上,顶级值获胜,按密钥计算,
而顶层块未提及的任何内容均从别名中填入.
下面所有东西都与你们使用的任意一种相对:
actionGuard.enabled: 打开或关闭工具前行动警卫(默认)false; 未签名的配置让"警卫"离开)actionGuard.enforce: 执行危险操作标记(默认)true当卫队在岗的时候;false选择向下警告和提醒。 灾难行动只有在Guard启用时才被封锁.actionGuard.autoApprove: 合法需要特定危险行动的无人看管人员的操作许可清单条目actionGuard.auditAllows: 审计识别( 敏感层) 允许决定, 因此“ 扫描和允许” 与“ 从未扫描过 ” 区分( 默认)true;良性许可从未审计)actionGuard.notify: 经营者通知运输(enabled, (中文(简体) ),webhookUrl, (中文(简体) ),webhookSecret, (中文(简体) ),openclaw, (中文(简体) ),timeoutMs) (中文(简体) ). 关闭,除非enabled没错true用于通话和对话-防火墙探测.
对话防火墙
3个姿势 interceptor.conversation.posture数字 :
| 姿态 | 行为 |
|---|---|
off | 谈话完全没有扫描 无论是 钩. 没有扫描仪运行,没有写审计行,没有转发任何信息. |
observe | 默认. 扫描,审计,提醒操作员——但永远不要停止转弯. |
enforce | 另外阻断运行 before_agent_run 当判决是肮脏的. |
off 也支配着观察钩. 任何扫描器,任何
审计书写和任何云对两者的呼唤 llm_input 财务报告和审定财务报表 before_agent_run这样
切换它的成本 一个配置每个转弯读取, 没有生成记录
任何地方的对话.
observe 这是故意的默认: 这正是在姿态存在之前运出的东西,现在 名称 而不是隐含的保护,而后卫的虚假阳性率仍未被计量(第1行)182号) (中文(简体) ). 每转弯前都有一个没有测量的阻断器,这将是比这个解决的更糟糕的事件. 未识别的值解决 下来 改为 observe从不起来.
两件事情都关上门了 都老实报告
-
运营商同意 -
hooks.allowConversationAccess。 。 。 . OpenClaw 拒绝 每个 用于未捆绑的插件的对话钩子,除非主机配置带赠款.llm_input财务报告和审定财务报表llm_output在所有建筑中都列在清单中;before_agent_run在2026.5.9-β.1中加入,因此,在目前的东道主上,赠款也开启了防火墙的执行点。 主机配置需要 :{ "plugins": { "entries": { "shieldcortex-realtime": { "enabled": true, "hooks": { "allowConversationAccess": true } } } } }这是每盒 同意书: 它授权一个插件来读取主机上的每一段对话. 插件本身从不写, 普通安装也从不添加——
/shieldcortex-status财务报告和审定财务报表shieldcortex doctor报告其缺席情况 "对话扫描隐含性:对话访问不准许" 而不是悄悄地要求保护。 没有它,注册成功,并被宿主用诊断来丢下钩子;注册线是意图,而不是接受.要安装者写,请明确:
shieldcortex openclaw install --allow-conversation-access # or, for automation: SHIELDCORTEX_ALLOW_CONVERSATION_ACCESS=1 shieldcortex openclaw install这对 每个 安装模式 — 本地
openclaw plugins install路径以及本地复制回落——安装器状态 后继的赠与状态,无论是哪种方式,都从配置中读出而不是 从国旗上重述.shieldcortex repair写也一样,但只有当 在运行中给予同样的同意: 修复一个安装不同意 拓宽它可能读取的内容./shieldcortex-status将赠款报告为 插件加载快照页:1 插件在加载时读取一次,再也没有再读取过. 编辑密钥 只有在网关之后才能生效——对网关和这条线生效 重新启动 . -
东道楼-大门有一层.
before_agent_run首先出现在 OpenClaw 中 2026.5.9-beta.1 (中文(简体) ) 和第一批在 2026.5.12 (中文(简体) ) (2026.5.7没有这样的钩子). 在该层下方,主机默默地放下了注册,所以插件将平面报告为只观察,而不是声称执行. 它首先从已安装的主机自身的已运出钩子声明中检测到这一点,并且从它的版本中检测到它只是作为倒置;无法读取的安装被报告为 不详,从来没有像支持。 这个插件中的其他一切仍然在基站引擎层工作.
当发现起火时
命令很重要,首先证据是:
- 决策行是本地写的,在任何东西离开盒子之前. 这个
带有结果(
blocked编号 :observed编号 :unavailable),姿态,a 稳定eventId,以及内容摘要和长度—— 永远不要及时的文本, (中文(简体) ), 它在这个路径上通过假设是敌对输入。 挂载通知 频道、崩溃或网关重启中层警报器不再可以使用 记录一个街区与它. - 然后接线员被通知,通过同一运输 行动警卫
使用量(
actionGuard.notify: 运行时间所在的网关自己的频道 提供接合器,否则配置的网钩——即载有 今天的警报,因为没有OpenClaw的建筑 我们检查过暴露了这样一个接合. 对话警报是一个独特的事件(conversation_threat)和携带 无核准/无人控制 ——他们背后没有不断的呼唤. 等待着 在钩子的自身超时下, 被束缚得很好. - 然后第二行记录了警报发生的事数字 :
type: "notification_delivery",由同一人按键决定eventId,与configured编号 :delivered编号 :via编号 :detail。“没有人被配置”是 频道的名称没有它的 证书.
扫描器故障无法打开, 声音很大 . 如果扫描仪无法运行, 转弯
收益 未扫描 报告为 unavailable 它从来没有记录或
变成干净的.
扫描范围为5秒. before_agent_run 正在等待着
网关,所以用户的回合等待它, 扫描仪的倒回路径靴
通过 MCP 服务器 npx,这能承受15 s cold的上调——准确地说
进程内防御模块未能加载的主机,即:
已经退化了 超过最后期限时, 扫描被视为无法使用: 转弯
收益,审计行和警报都这么说。 截止时间消息命名为
——永远不要及时.
重复的不提供警报是每场的费率有限;审计是
没有. 无法使用的扫描仪通常是缺失或损坏的安装,所以
重现于 每个 转 立即发出会话提示中的第一个事件;
之后,每5分钟最多发出一次警报 供该届会议审议和警报
这结束一个安静的咒语 报告它覆盖了多少事件。 窗户是
每个会场按目的:一个网关多路转接许多并行会场,以及一个
届会的一再失败绝不能让 第一个 从另一个报告.
每个会话窗口在 session_end (登记与否)
行动后卫拦截器被启用,跟踪图被绑定在这样一条
从未发射的主机 session_end 无法无限地增长它。 每个
发生时仍然写着自己的审计行 unavailableCount, (中文(简体) ),
alertSuppressed,以及 alertSuppressedSinceLastAlert 所以警报中有个漏洞
流决不会被误认为失败中的漏洞。 被压制的事件
没有写送货行,因为没有试图送货.
故障细节在任何地方都会被编辑,而不仅仅是在磁盘上. 扫描仪和 运输错误可以自由引用它们无法到达的终点,而且 URL通常会在路径中携带其证书. 每个 https URL 有原因 或细节在写到审计行之前 简化为来源 在操作员警报中,作为块理由返回,或打印到控制台上—— 一个网关的 stdout 被传送到一个日志汇总器, 就像审计文件一样频繁 同步,所以三个都不是"异想天开"的.
不加载的屏蔽配置会降解为同一不可用的路径 .
如果 ShieldCortex 运行时间无法解决或 ~/.shieldcortex/config.json
无法读取, 插件不会静默: 它警告每个插件装入一次
(捆绑并编辑,它从未声称盾牌配置已装入)
页:1 openclaw.json 插件配置, 使姿态仍能解决, 扫描
然后报告 unavailable 制作普通审计行和操作员警报
见上文。 转弯还继续.
报告失败的审计书,绝不假定. 如果决定行
无法持续( 无法写入审计目录、 完整磁盘) , 决定本身
操作员发出警报
携带 auditPersistence=failed 因此,这是很清楚的 警报是唯一的记录
活动.
自动记忆
当 openclawAutoMemory 实值 true; 当键没有被触发时, 则关闭。 新的全局非 CI npm 安装, 无 ~/.shieldcortex/config.json 创建一个带有 openclawAutoMemory: true,所以它就在那里;一个已有的配置文件永远不会被更改,所以升级会保留您的值。 这些配置值不会安装插件或钩子,也不会打开"动作守护". 它以分解来补充你现有的记忆设置,以避免吵闹的重复.
您可以通过ShieldCortex本身管理相同的设置 :
shieldcortex config --openclaw-auto-memory true
shieldcortex config --openclaw-auto-memory false
或者通过编辑 ~/.shieldcortex/config.json数字 :
{
"openclawAutoMemory": true,
"openclawAutoMemoryDedupe": true,
"openclawAutoMemoryNoveltyThreshold": 0.88,
"openclawAutoMemoryMaxRecent": 300
}
云层转发
威胁转发是可选的。 在ShieldCortex中配置它 :
{
"cloudApiKey": "sc_...",
"cloudBaseUrl": "https://api.shieldcortex.ai"
}
或者在插件条目配置中,如果您想要插件特定覆盖.
审计记录
实时事件写给:
~/.shieldcortex/audit/realtime-YYYY-MM-DD.jsonl
每行都是JSON对象,具有输入扫描,威胁,输出-记忆活性.
对话路径上没有一行带有即时文本 . 维持下去
llm_input 观察行和观察行 before_agent_run 大门行:两行
记录 chars (单位:千美元) contentSha256 前缀, 足够
将两行关联到同一信件而不存储信件 。 (至多
联合国 llm_input 威胁行携带100个字符 preview 会 议 日 程 和 议 程
即时 —— 刚刚绊倒了注射检测器的正文—— 输入日志
时间轴:
对话 - 防火墙探测器写道 两个 横行, 两行都有标记
hook: "before_agent_run" 并加入一个共享 eventId数字 :
| 行数 | 字段 |
|---|---|
决定type: "threat" 或者说 "scan_unavailable"(中文(简体) ) | outcome (单位:千美元)blocked 编号 : observed 编号 : unavailable, (中文(简体) ), posture,扫描仪 verdict, (中文(简体) ), chars页:1 contentSha256 前缀,和 notifyPending |
交货type: "notification_delivery"(中文(简体) ) | configured, (中文(简体) ), delivered, (中文(简体) ), via (只有频道名称), detail |
决定行是写着的 在此之前 试图通知,所以
挂起的运输或一个已死的过程不能抹去块的记录.
交货行随后随附,当其结果实际已知时——
没有任何地方 声称在运输前发送了警报
这么说的 一行,这里 type 实值 scan_unavailable 表示转弯跑 无
正在扫描这不是一个干净的判决.
设定 SHIELDCORTEX_AUDIT_DIR 来写这些行的别处
~/.shieldcortex/audit (被测试套间使用,因此测试运行永远无法附加)
给一个真正的主机的安全日志.