技能审计（skills-audit）

一种面向安全的技能，用于安全地管理 OpenClaw 技能。该包包含可执行的 Python 脚本（非纯指令型），具备六大核心能力：

1. 威胁扫描（静态分析）
2. 仅追加式审计日志（本地 NDJSON 格式）
3. 技能监控与通知（变更时推送告警）
4. 文件级差异 + 内容差异（基于 git 快照）
5. 基线审批机制（已批准技能不再重复告警）
6. 语义分析（危险函数识别 + 能力分析）

该技能执行的是对被审计技能的 静态分析 —— 它 不会执行被审计技能自身的代码。但审计工具本身会执行 本地可信命令/子进程，例如 git、Python 辅助脚本，以及为快照生成、差异比对和通知生成所必需的受控本地进程调用。

依赖要求

• Python ≥ 3.9，仅使用标准库（无第三方依赖）
• git（用于内容差异快照及本地仓库历史）
• 一个常规的本地 shell / 进程运行环境，供审计工具自身执行受控子进程
• 详见 scripts/requirements.txt

核心能力

1) 威胁扫描（静态风险分析）

skills_audit.py 对已安装的技能目录执行静态检查。若配置了 QianXin Token，则会基于 整个 workspace/skills 包的稳定 MD5 值 向 QianXin SafeSkill 查询，而非上传包本身：

• 网络指标：URL / 域名、curl/wget/requests 的使用情况
• 危险命令：curl|sh、wget|bash、eval、动态 exec、base64 管道
• 可疑行为：持久化（cron/systemd）、敏感路径（~/.ssh、~/.aws、/etc）
• 可选 QianXin 情报：使用用户提供的 Token，对完整 workspace/skills 包进行稳定 MD5 查询

输出字段：

• risk.level：low | medium | high | extreme
• risk.decision：allow | allow_with_caution | require_sandbox | deny
• risk.risk_signals[]：证据（文件 + 代码片段）
• risk.network.domains[]：提取出的域名列表
• risk.source：local 或 qianxin-md5

QianXin 配置说明：

• 配置文件：config/intelligent.json
• 默认为 enabled: false
• token 默认为空字符串
• 用户可在下载后填写自己的 Token 并将 enabled 设为 true 来启用
• 若处于禁用状态、Token 为空或查询失败，则自动回退至本地静态分析

2) 审计日志（仅追加式 NDJSON）

所有检测结果均以 NDJSON 格式追加写入：

• ~/.openclaw/skills-audit/logs.ndjson

用于差异比对的状态快照：

• ~/.openclaw/skills-audit/state.json

Schema 定义于 log-template.json。关键字段说明：

• sha256：SKILL.md 的 SHA-256 值（完整性校验字段）
• diff：git 提交信息 + 各文件统计信息
• file_changes：文件级新增 / 删除 / 修改列表
• approved：基线审批状态

3) 技能监控与推送通知

周期性监控 workspace/skills 目录中的新增、变更与删除操作。

• 无变更 → 无输出
• 检测到变更 → 发送一条通知
• 基线已批准且未变更的技能，不纳入通知范围

通知模板：templates/notify.txt（定制方法参见 templates/README.md）。

4) 文件级差异 + 内容差异（Git 快照）

每次扫描均将 skills 目录快照为本地 git 仓库（~/.openclaw/skills-audit/snapshots/）：

• 每次扫描 = 一次 git commit
• 通过 git diff HEAD~1 HEAD 检测变更
• 通知中包含各文件变更摘要（+N -N 行）

分级显示策略：

• ≤ 5 个变更文件：全部展示，并标注 +N -N
• 6–20 个：展示前 3 个 + “X more omitted”
• > 20 个：展示前 3 个 + 省略 + ⚠️ 大规模变更警告
• > 8 个技能变更：高风险项展开，低风险项压缩

查看完整差异：

git -C ~/.openclaw/skills-audit/snapshots diff HEAD~1 HEAD
git -C ~/.openclaw/skills-audit/snapshots diff HEAD~1 HEAD -- skills//
git -C ~/.openclaw/skills-audit/snapshots log --oneline

6) 语义分析（危险函数 + 能力分析）

每次扫描还会在审计日志中生成 semantic_analysis 字段：

• 危险函数分析：识别 eval、exec、os.system、subprocess（含 shell=True）、curl|sh、wget|bash 等模式
• 能力分析：推断技能是否具备网络、文件系统、进程执行、cron/调度器、git 或配置处理等能力
• 综合判定：分别评估执行能力风险与恶意意图风险；以语义意图作为首要决策维度，最终输出 level / decision / reason

注意事项：

• 当前实现为 本地 LLM 风格启发式分析，不依赖任何外部模型
• 这是 强制性规则：每个新增或变更的技能，在执行 skills_audit.py scan 时必须经过语义分析
• 若 semantic_analysis 缺失或无法生成结果，扫描应失败，而非静默跳过
• 为降低自审计误报率，低信号文件（如规则配置、日志模板、技能文档、config/semantic-patterns.json）将从高权重危险函数评分中排除
• 风险规则扫描现区分命中上下文：real_execution / rule_sample / doc_example / config_sample
• 对于 skills_audit.py 自身，语义检测与风险扫描均优先关注真实执行路径，而非默认将模式字符串表视为危险执行
• 语义分析现已将执行能力与恶意意图分离，因此正常的工程能力不会自动推导为恶意结果
• 受控本地调用（如 subprocess.run([...], shell=False) 且 argv 固定）被视为工程能力，而非自动判定为恶意意图
• 该字段设计为向前兼容，后续可接入真正由 LLM 支持的语义扫描器

5) 基线审批机制

通过 ~/.openclaw/skills-audit/baseline.json 管理已批准技能：

• 已批准技能（匹配 tree_sha256）不再触发重复告警
• 任意文件变更将自动使审批失效 → 重新触发风险检测

python3 {baseDir}/scripts/skills_audit.py approve --skill weather --workspace 
python3 {baseDir}/scripts/skills_audit.py approve --all --workspace 
python3 {baseDir}/scripts/skills_audit.py baseline --list
python3 {baseDir}/scripts/skills_audit.py baseline --revoke --skill weather

初始化与手动监控设置（Agent 指令）

当 Agent 首次加载此技能时，可能执行 本地初始化，但 不得自动创建 cron 任务。相反，它应引导用户显式创建监控：

1. 检查 ~/.openclaw/skills-audit/state.json 是否存在
2. 若不存在，则执行初始化：

   python3 {baseDir}/scripts/skills_audit.py init --workspace 
   

3. 检查是否存在名为 skills-audit-watch 的 cron 任务（openclaw cron list）
4. 若不存在：
   • 禁止自动创建 cron
   • 提示用户可手动创建
   • 提供建议命令示例（需由用户自行执行，或仅在获得用户明确授权后执行）：

   openclaw cron add 
     --name "skills-audit-watch" 
     --cron "*/1 * * * *" 
     --tz "Asia/Shanghai" 
     --session isolated 
     --message "python3 {baseDir}/scripts/skills_watch_and_notify.py --workspace " 
     --announce 
     --channel  
     --to 
   

5. 提醒用户在启用前验证推送目标，尤其当原始差异或大规模变更详情可能外发时
6. 不得默认向外部通道推送大规模原始差异内容；应优先发送简洁摘要，详情按需提供

设计原则：skills-audit 仅负责扫描、日志记录与通知文本生成；调度与投递应由用户主导，而非默认自动创建。

查看变更详情（Agent 强制流程）

⚠️ 强制性规则：当用户询问技能变更详情时，Agent 必须 使用 show 命令获取结构化变更数据。默认应先提供 安全摘要，而非直接向外发送完整原始差异内容。

触发语句（用户可能表达）：

• “what changed” / “show diff” / “what's different” / “change details”
• “具体改了什么” / “哪里变了” / “看一下变更”
• 任何请求差异 / 变更 / 修改详情的表述

固定执行流程（不可跳过）：

1. 若用户提及特定技能：

   python3 {baseDir}/scripts/skills_audit.py show --skill 
   

2. 若未指定具体技能：

   python3 {baseDir}/scripts/skills_audit.py show
   

3. 默认仅发送源自 show 输出的 安全摘要（变更文件、行数、主要变更点），以避免对外暴露敏感差异内容
4. 仅当用户 明确要求原始 / 完整内容 时，才发送完整的 show 输出，并应警示用户：差异中可能出现敏感信息
5. 查看更早历史，请使用 --commit-range：

   python3 {baseDir}/scripts/skills_audit.py show --commit-range HEAD~3..HEAD~2
   

禁止行为：

• ❌ 绕过结构化 show 输出路径，直接运行 git diff
• ❌ 默认不经警示即向外部通道发送原始完整差异内容
• ❌ 自动向外部通道推送大规模原始变更内容
• ✅ 优先采用基于 show 的安全摘要；仅在用户明确请求时提供完整原始内容

手动使用方式

初始化

python3 {baseDir}/scripts/skills_audit.py init --workspace /root/.openclaw/workspace

手动扫描

python3 {baseDir}/scripts/skills_audit.py scan --workspace /root/.openclaw/workspace --who user --channel local

本地通知测试

python3 {baseDir}/scripts/skills_watch_and_notify.py --workspace /root/.openclaw/workspace

安全须知

• 仅限静态分析：审计过程中绝不执行未知技能代码。
• 当 risk.level 为 high 或 extreme 时，必须经人工复核或置于 sandbox 中执行。
• 推荐使用 OpenClaw cron add / cron edit 进行任务调度。
• 完整性校验使用 SHA-256。