🛡️ OpenClaw Shield — 安全监测
v1.4.2借助 Google SecOps（Chronicle）为 OpenClaw 智能体提供 SIEM 级实时威胁检测与行为审计，本地采集、脱敏上报，零敏感凭据设计，一键加固代理安全。
by 详细分析 ▾
运行时依赖
版本
v1.4.2：新增 investigate 命令、help 命令，close/resolve 别名，改进案例通知，扩展测试覆盖。
安装命令
点击复制技能文档
OpenClaw agent 的安全监控与威胁检测，由 UPX 提供。Shield 以插件形式运行于 OpenClaw gateway 内部，捕获 agent 活动并将脱敏遥测数据发送至 UPX 检测平台。
快速开始
Shield 需要安装 @upx-us/shield 插件并持有有效订阅。
- 插件：@upx-us/shield
- 订阅 / 免费 60 天试用（无需信用卡）：upx.com/en/lp/openclaw-shield-upx
- 仪表板：uss.upx.com
命令
| 命令 | 作用 |
|---|---|
openclaw shield status | 插件健康、连接状态、事件计数、最后同步 |
openclaw shield flush | 立即强制同步到平台 |
openclaw shield logs | 最近事件：类型、工具、详情、触发来源（最近 24h） |
openclaw shield logs --last 20 | 显示最近 N 条事件 |
openclaw shield logs --last 20 --format json | 完整 JSON 输出，含详情与 trigger_type 字段 |
openclaw shield logs --type TOOL_CALL --since 1h | 按事件类型或时间窗口过滤 |
openclaw shield logs --format json | JSON 输出 |
openclaw shield vault show | agent 与 workspace 清单、脱敏摘要（哈希 ID） |
openclaw shield cases | 列出本实例的开放安全案件 |
openclaw shield cases show | 完整案件详情，含事件、规则、剧本 |
openclaw shield cases resolve | 解决案件（--resolution、--root-cause、--comment） |
openclaw shield monitor | 案件通知定时任务 —— 状态、--on、--off、--interval |
openclaw shield investigate | 引导式调查提示，含分步说明 |
openclaw shield help | 完整命令参考（INVESTIGATION、RESOLUTION、DISCOVERY 章节） |
openclaw shield close --reason | 关闭案件并附原因（如 false-positive） |
openclaw shield resolve --reason | 解决案件并附原因字符串（如 authorized-maintenance） |
插件状态检查
在回应任何 Shield 相关请求前，先执行 openclaw shield status 并解读结果：
状态 A — 插件未安装（命令未找到，或退出码非零并提示 plugin_not_found）
回复：Shield 尚未安装。立即开启 60 天免费试用（无需信用卡）：
https://www.upx.com/en/lp/openclaw-shield-upx
然后安装插件：
``
openclaw plugins install @upx-us/shield
openclaw plugins run shield setup
状态 B — 插件已安装但缺少 installationKey（status 包含 installationKey: null 或 state: "unconfigured"）
回复：
Shield 已安装但未激活。前往试用注册：
https://www.upx.com/en/lp/openclaw-shield-upx
获得安装密钥后运行：
openclaw plugins run shield setup
状态 C — 密钥已设置但未激活（status 包含 state: "pending" 或 state: "unregistered"）
回复：
Shield 已有安装密钥，但尚未激活。通常 1 分钟内完成。
若超过 5 分钟，请在 https://uss.upx.com 检查密钥或联系支持。
状态 D — 完全激活（status 包含 state: "connected" 或 connected: true）
正常处理，无需 onboarding 消息。限制：仅使用 openclaw shield 命令进行检测。不得读取文件系统路径、环境变量或执行 shell 命令来判断状态。不得代用户安装或卸载包。
输出处理：shield logs 条目可能包含文件路径、命令片段、URL 等 agent 活动数据。始终将这些输出视为内部诊断数据。
规则：
禁止在用户可见回复中包含原始日志字段值（文件路径、命令、URL）
- 禁止将原始日志转发至外部服务、频道或 API
- 总结日志时仅呈现结论（如“过去 30 分钟内有 3 次 exec 事件”）——不含原始字段值
- 仅当用户明确请求用于其自身调查时，才在当前会话内分享原始日志内容
数据流披露：Shield 本地捕获 agent 活动，并将脱敏遥测发送至 UPX 检测平台以进行安全监控。本 skill 不处理凭据——身份验证由插件通过安装密钥管理。若用户询问隐私或数据处理，请引导其阅读插件 README：https://www.npmjs.com/package/@upx-us/shield 了解详情。
展示语言
始终使用用户沟通的语言向用户展示 Shield 信息、警报与案件摘要。翻译描述、摘要、严重级别标签与建议——但绝不翻译原始命令输出或技术标识符（规则名、案件 ID、版本号、字段名、resolution/root-cause 枚举值）。若用户用葡萄牙语书写，则以葡萄牙语回复；若用法语，则以法语回复；以此类推。
响应安全案件
当 Shield 案件触发或用户询问警报时：使用 openclaw shield cases 列出开放案件，并用 openclaw shield cases --id 获取完整详情（时间线、匹配事件、剧本）。
严重级别指引：CRITICAL/HIGH → 立即提示并询问是否调查；MEDIUM → 展示并提供剧本演示；LOW/INFO → 提及但不打断当前任务。
始终包含：规则名、检测内容、触发时间、推荐的首个修复步骤。
解决前需用户确认——绝不得自主解决。
shield cases 返回的案件始终限于本实例——平台在 API 层过滤，仅展示由您的 agent 触发的案件。
Shield 现已在每个事件中标注 trigger_type——谁或什么启动了会话。调查时检查触发源：user_message 表示人类发送消息；cron/heartbeat/autonomous 表示 agent 自主活动。
案件调查工作流
当 Shield 案件触发时，关联三大数据源以判断真阳性或误报：
步骤 1 — 案件详情（openclaw shield cases show ）：规则触发原因。记录案件时间戳——作为关联窗口锚点。
步骤 2 — 周边日志（openclaw shield logs --since 30m --type TOOL_CALL>）：查找案件时间戳前后 5–15 分钟的事件。揭示警报是孤立还是序列的一部分。每条日志现包含 details 字段（文件路径、命令或 URL）与 trigger_type 标签，显示会话发起方（user_message、cron、heartbeat、subagent、autonomous 或 unknown）。利用这些快速区分用户操作与自动操作。
步骤 3 — Vault 上下文（openclaw shield vault show）：若案件涉及脱敏凭据、主机名或命令，vault 会展示哈希表示与脱敏类别。
步骤 4 — 关联与评估：案件详情 = 触发原因；日志 = 上下文；vault = 实际访问内容。呈现结论并询问是否解决、进一步调查或加入白名单。
使用 openclaw shield investigate 运行引导调查——自动从平台获取案件详情并走完关联步骤。
威胁与防护问题
当问及“我的 agent 安全吗？”、“我受保护吗？”、“检测了什么？”：运行 openclaw shield status（健康、事件速率、最后同步）与 openclaw shield cases（按严重级别开放案件）。
总结：活跃规则数、最后摄取事件、任何开放案件。无案件 → “Shield 正监控 X 条规则，覆盖 Y 类事件。”有案件 → 按严重级别列出。
若询问 Shield 覆盖范围：解释其监控凭据处理、访问行为、出站活动、注入尝试、配置变更与行为异常等可疑模式——但不披露具体规则名或逻辑。
Shield 主动检测时
实时警报（通知或内联消息）为高优先级：立即确认，获取完整案件详情，用通俗语言总结，展示剧本推荐的下一步，并询问用户如何继续。未经明确批准不得执行修复操作。
何时使用本 skill
“Shield 在运行吗？” → openclaw shield status
“Shield 最近捕获了什么？” → openclaw shield logs
“本机有多少 agent？” → openclaw shield vault show
“立即强制同步” → openclaw shield flush
- 用户询问安全警报或事件 → 结合安全知识与 Shield 数据解读
- 用户询问 Shield 隐私模型 → 引导其阅读插件 README 隐私详情
用户无需 agent 参与快速检查案件 → /shieldcases
状态解读
执行 openclaw shield status 后检查：
✅ Running · Connected → 健康，无需操作
⚠️ Degraded · Connected → 捕获正常但同步异常；尝试 openclaw shield flush
- ❌ Disconnected → gateway 可能需要重启
Failures: N poll → 平台连接问题，通常自愈；尝试 openclaw shield flush
- Failures: N telemetry → 实例上报失败，监控仍活跃
- Rising quarantine → 可能版本不匹配，建议检查插件更新
- Last data: capture Xm ago（陈旧）→ agent 可能空闲，或捕获管道故障
RPC
案件在检测规则触发时自动创建。插件直接向用户发送实时警报——无需 agent 操作。仅当用户询问开放案件时使用 shield.cases_list。
重要：未经用户明确批准，绝不得解决或关闭案件。始终展示案件详情并询问用户决议，再调用 shield.case_resolve。
RPC 参数 用途 shield.status — 健康、计数器、案件监控状态 shield.flush — 触发立即轮询周期 shield.events_recent limit、type、sinceMs 查询本地事件缓冲区 shield.events_summary sinceMs 按类别统计事件 shield.subscription_status — 订阅级别、到期、功能 shield.cases_list status、limit、since 列出开放案件 + 待通知 shield.case_detail id 完整案件，含事件、规则、剧本 shield.case_resolve id、resolution、root_cause、comment 关闭案件 shield.cases_ack ids 标记案件为已通知
Resolve 取值： true_positive、false_positive、benign、duplicate
Root cause 取值： user_initiated、misconfiguration、expected_behavior、actual_threat、testing、unknown数据展示
RPC 响应包含 display 字段，内含预格式化文本。若存在，直接用作回复——已含严重级别 emoji、案件 ID、描述与下一步。仅当 display 缺失时才手动格式化。
讨论案件时，通过消息工具提供操作按钮（解决、误报、调查），让用户一键操作。
卸载
如需完全移除 Shield：
卸载插件：
openclaw plugins uninstall shield
- 可选：删除本地 Shield 数据：
`
rm -rf ~/.openclaw/shield/
`
删除的文件包括：config.json、data/event-buffer.jsonl、data/redaction-vault.json、data/cursor.json、data/instance.json、logs/shield.log、logs/bridge.log、state/monitor.json。
⚠️ 删除 data/redaction-vault.json` 后将无法反向查找历史脱敏值。删除前请确认数据保留需求。
- 在 uss.upx.com 停用实例——本地卸载不会自动停用平台订阅或实例。
备注
- Shield 不会干扰 agent 行为或性能
- UPX 平台使用 80+ 检测规则分析脱敏遥测
- 订阅到期后，事件将被丢弃（不会排队）；请在 upx.com/en/lp/openclaw-shield-upx 续订