@drakon-systems/shieldcortex-realtime

中文文档
5.20.0发布于 2026/11/12MITES Module零依赖构建来源已验证近 30 天下载 5808

ShieldCortex实时防御扫描和可选内存提取的OpenClaw插件.

中文使用文档
文档目录16 节
  1. 兼容性
  2. OpenClaw 发现的包装说明
  3. OpenClaw 2026.4.23中已知的限制
  4. 它会做什么
  5. 安装
  6. 1. 安装ShieldCortex
  7. 2. 安装插件
  8. 地方发展
  9. 配置
  10. 行动卫队的防守
  11. 对话防火墙
  12. 两件事情都关上门了 都老实报告
  13. 当发现起火时
  14. 自动记忆
  15. 云层转发
  16. 审计记录

@ 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.99
  • openclawAutoMemoryMaxRecent:去dupe缓存大小, 50 改为 1000
  • interceptor.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从不起来.

两件事情都关上门了 都老实报告

  1. 运营商同意 - 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 插件在加载时读取一次,再也没有再读取过. 编辑密钥 只有在网关之后才能生效——对网关和这条线生效 重新启动 .

  2. 东道楼-大门有一层. before_agent_run 首先出现在 OpenClaw 中 2026.5.9-beta.1 (中文(简体) ) 和第一批在 2026.5.12 (中文(简体) ) (2026.5.7没有这样的钩子). 在该层下方,主机默默地放下了注册,所以插件将平面报告为只观察,而不是声称执行. 它首先从已安装的主机自身的已运出钩子声明中检测到这一点,并且从它的版本中检测到它只是作为倒置;无法读取的安装被报告为 不详,从来没有像支持。 这个插件中的其他一切仍然在基站引擎层工作.

当发现起火时

命令很重要,首先证据是:

  1. 决策行是本地写的,在任何东西离开盒子之前. 这个 带有结果(blocked 编号 : observed 编号 : unavailable),姿态,a 稳定 eventId,以及内容摘要和长度—— 永远不要及时的文本, (中文(简体) ), 它在这个路径上通过假设是敌对输入。 挂载通知 频道、崩溃或网关重启中层警报器不再可以使用 记录一个街区与它.
  2. 然后接线员被通知,通过同一运输 行动警卫 使用量(actionGuard.notify: 运行时间所在的网关自己的频道 提供接合器,否则配置的网钩——即载有 今天的警报,因为没有OpenClaw的建筑 我们检查过暴露了这样一个接合. 对话警报是一个独特的事件(conversation_threat)和携带 无核准/无人控制 ——他们背后没有不断的呼唤. 等待着 在钩子的自身超时下, 被束缚得很好.
  3. 然后第二行记录了警报发生的事数字 : 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 (被测试套间使用,因此测试运行永远无法附加) 给一个真正的主机的安全日志.

版本与发布记录

@drakon-systems/shieldcortex-realtime 共发布 227 个版本,首次发布于 2026/03/15;过去 12 个月发布了 227 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.20.0latest2026/11/121 天前
5.19.02026/11/094 天前
5.18.22026/11/085 天前
5.18.12026/11/076 天前
5.18.02026/11/067 天前
5.17.42026/11/049 天前

关于 @drakon-systems/shieldcortex-realtime 的常见问题

@drakon-systems/shieldcortex-realtime 是什么?

ShieldCortex实时防御扫描和可选内存提取的OpenClaw插件.

如何安装 @drakon-systems/shieldcortex-realtime?

在项目目录运行 npm install @drakon-systems/shieldcortex-realtime,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:shieldcortex(^5.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@drakon-systems/shieldcortex-realtime 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/drakon-systems__shieldcortex-realtime 是否存在。

@drakon-systems/shieldcortex-realtime 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@drakon-systems/shieldcortex-realtime 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js ^22.14.0 || >=24.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@drakon-systems/shieldcortex-realtime 可以商用吗?

@drakon-systems/shieldcortex-realtime 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@drakon-systems/shieldcortex-realtime 的下载量有多少?

根据 npm 官方下载统计,@drakon-systems/shieldcortex-realtime 在 2026/10/13 – 2026/11/11 这 30 天内被下载 5,808 次,日均约 194 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@drakon-systems/shieldcortex-realtime 还在维护吗?

最新版本 5.20.0 发布于 2026/11/12(1 天前);至今共发布 227 个版本,其中过去 12 个月发布了 227 个;首次发布于 2026/03/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。