OpenClaw AI代理权限审计：静态分析工具的设计与CI/CD集成实践

1. 项目概述：一个为OpenClaw AI代理设计的轻量级权限审计工具

如果你正在使用或开发基于OpenClaw框架的AI代理，那么你很可能面临一个既基础又关键的安全挑战：如何清晰地知道你的AI代理被允许使用哪些工具，以及它实际使用了哪些工具？尤其是在一个复杂的开发环境中，多个代理可能拥有不同的权限配置，而它们的实际行为却隐藏在大量的会话日志和转录文件中。openclaw-tool-audit正是为了解决这个“权限与行为”的可见性问题而生的。它是一个小巧但功能聚焦的命令行工具，核心使命就是通过静态分析，对比AI代理的配置权限与实际工具调用记录，为你生成一份清晰的安全审计报告。

想象一下这样的场景：你团队里有三个OpenClaw代理，一个负责代码审查，一个负责数据查询，还有一个是拥有“超级权限”的通用助手。理论上，它们应该各司其职。但某天你突然发现，那个本应只有只读权限的数据查询代理，其日志里竟然出现了文件写入的痕迹。是配置写错了，还是出现了意料之外的工具调用链？手动翻遍JSON、YAML配置和一堆日志文件来排查，无疑是耗时且容易出错的。openclaw-tool-audit的价值就在于，它能自动化地完成这个交叉比对的过程，将潜在的权限滥用、配置错误或未使用的冗余权限直接呈现在你面前。

这个工具特别适合三类人：一是AI应用的安全工程师或架构师，需要定期审查代理行为是否符合安全基线；二是开发OpenClaw代理的工程师，在迭代权限配置后需要快速验证；三是运维或SRE人员，希望将代理工具的审计纳入CI/CD流水线，实现安全左移。它不执行任何动态拦截或策略强制执行，它的核心是提供“可见性”——而可见性，是任何有效安全管控的第一步。

2. 核心设计思路：聚焦静态分析与安全可见性

2.1 为何选择静态分析路径

在安全工具的设计上，通常有动态（运行时）和静态（预执行/后审计）两条路径。openclaw-tool-audit坚定地选择了静态分析，这背后有几个关键的考量。首先，侵入性最低。它不需要修改OpenClaw的运行时代码，不需要注入任何钩子（Hook），完全通过读取磁盘上已有的配置文件和历史会话记录来工作。这意味着你可以随时在任意一个开发、测试或生产环境的副本上运行它，而不用担心影响线上服务的稳定性或引入新的运行时风险。

其次，审计范围完整。动态监控通常只能捕获单次运行或实时发生的工具调用，而静态分析可以一次性扫描数周、数月积累的所有历史会话文件。这对于发现低频但危险的异常行为（比如一个每月只执行一次的高危操作）至关重要。通过--last参数，你可以灵活地聚焦于最近的活动，实现定期（如每周）的增量审计。

第三，便于集成与自动化。静态分析工具的输出（如JSON、Markdown）是结构化的，极易集成到现有的CI/CD流水线、安全信息与事件管理（SIEM）系统，或是生成定期的合规报告。你可以设置一个定时任务，每天凌晨扫描最新的日志，一旦发现“观察到的工具不在允许列表中”这类违规，就自动触发告警或阻断部署流程。

2.2 工具权限模型的抽象与兼容

OpenClaw本身（以及许多类似的AI代理框架）并没有一个绝对统一的工具权限配置格式。不同的团队、不同的项目可能采用不同的配置文件结构（JSON, YAML, TOML）和不同的字段名来定义允许的工具列表。openclaw-tool-audit在设计上充分考虑了这种现实复杂性，采用了启发式扫描与多格式支持的策略。

它不会要求你统一所有配置的格式，而是智能地寻找常见的“允许列表”字段。无论是在配置文件的顶层还是嵌套在某个深层对象中，只要字段名匹配allowed_tools、tools、tool_allowlist等常见模式，它都能识别出来。这种设计极大地降低了工具的接入成本。你不需要为了使用这个审计工具而去重构现有的、可能正在稳定运行的配置体系。

注意：这种灵活性是一把双刃剑。它虽然方便，但也意味着如果你们的配置使用了极其冷门的字段名（例如permitted_instruments），工具可能会漏扫。因此，在首次全面部署审计工具时，建议先用--json输出模式详细检查一遍，确认工具是否正确识别了你所有代理的权限配置。如果有遗漏，你可能需要通过--config参数显式指定配置文件路径，或者考虑向项目提交一个Pull Request来扩展支持的字段名模式。

2.3 会话日志解析的挑战与策略

与配置解析类似，工具调用记录的来源——会话或转录文件——也充满了多样性。它们可能是结构化的JSON/JSONL，也可能是纯文本的日志或Markdown格式的对话记录。工具调用事件可能被记录为{"type": "tool_call", "name": "..."}，也可能是{"function": {"name": "..."}}或其他变体。

openclaw-tool-audit采用了双引擎解析策略来应对。对于结构化文件（JSON/JSONL），它内置了一系列已知的、从常见AI SDK和框架中归纳出的工具调用数据结构模式进行匹配。对于纯文本文件，则使用一组相对保守的正则表达式模式（如寻找to=tool_name这样的模式）进行提取。这种策略确保了在绝大多数通用场景下的高检出率，同时避免了因模式过于宽泛而导致的误报（例如将普通文本中的单词误识别为工具名）。

然而，这里存在一个精确性与覆盖率的权衡。文本解析毕竟是“最佳实践”（best-effort），对于高度定制化、非标准的日志格式，它可能会失效。工具的官方文档也明确指出了这一点。因此，对于关键的生产环境，建议规范日志格式，尽量使用工具能够可靠解析的结构化格式（如JSONL）来记录会话，这是保证审计有效性的基础。

3. 安装与快速上手：从零到第一份审计报告

3.1 多种安装方式详解

openclaw-tool-audit提供了几种主流的安装方式，以适应不同的使用习惯和环境。

1. 使用 pipx 安装（推荐用于独立CLI工具）pipx是一个用于安装和运行Python应用的工具，它的优势是为每个应用创建独立的虚拟环境，避免依赖冲突。如果你的系统上还没有pipx，通常可以通过系统的包管理器安装（如brew install pipx在macOS，或apt install pipx在Ubuntu）。安装好pipx后，执行以下命令：

pipx install openclaw-tool-audit

这个命令会从PyPI下载最新的稳定版，并创建一个名为openclaw-tool-audit的全局可执行命令。这是最干净、最推荐给最终用户的安装方式。

2. 使用 Homebrew 安装（macOS/Linux用户）对于习惯使用Homebrew的macOS或Linux用户，项目作者维护了一个自定义的Tap（软件源仓库）。安装命令如下：

brew install pfrederiksen/tap/openclaw-tool-audit

执行后，Homebrew会自动处理依赖和链接，同样会提供一个全局命令。这种方式的好处是更新方便（brew upgrade pfrederiksen/tap/openclaw-tool-audit），并且与系统其他brew管理的软件包风格统一。

3. 从源码安装（适合开发者或尝鲜最新特性）如果你想直接使用开发中的最新代码，或者有意参与贡献，可以从GitHub克隆仓库并进行本地安装：

git clone https://github.com/pfrederiksen/openclaw-tool-audit.git cd openclaw-tool-audit python -m pip install -e .

-e参数代表“可编辑模式”（editable mode），安装后你对本地源码的修改会立刻反映到工具的行为上，非常适合调试和开发。

安装完成后，在任何终端输入openclaw-tool-audit --help，如果看到详细的选项说明，就证明安装成功了。

3.2 理解默认的扫描路径

工具开箱即用，因为它预设了一套符合OpenClaw常见项目结构的默认搜索路径。这是其“零配置启动”理念的体现。

对于代理配置（Allowed Tools）：工具会按顺序扫描以下目录，寻找代理配置文件：

1. ./.openclaw/agents- 当前项目下的隐藏目录
2. ./agents- 当前项目下的显式目录
3. ~/.openclaw/agents- 用户主目录下的全局配置

这个顺序是精心设计的。它优先查找项目特定的配置（./），再查找用户全局配置（~），这符合“项目配置覆盖全局配置”的常见惯例。如果你的项目结构正好符合这个约定，那么直接运行openclaw-tool-audit就能开始工作。

对于会话记录（Observed Tools）：工具会扫描更广泛的路径来寻找工具调用记录：

1. ./.openclaw/sessions
2. ./sessions
3. ~/.openclaw/sessions
4. ~/.openclaw/transcripts
5. ~/.openclaw/agents/<agentId>/sessions-这是一个关键路径

第五条路径~/.openclaw/agents/<agentId>/sessions非常重要。当会话文件本身没有包含明确的代理ID元数据时，工具会尝试从文件路径中推断。例如，一个位于~/.openclaw/agents/code_reviewer/sessions/session_20231001.json的文件，会被自动归属到名为code_reviewer的代理名下。这种路径推断机制大大增强了工具在混合日志环境下的实用性。

3.3 生成你的第一份审计报告

假设你已经有一个OpenClaw项目在~/my_ai_project目录下，并且按照默认路径存放了配置和日志。最简单的审计就是进入项目根目录并运行：

cd ~/my_ai_project openclaw-tool-audit

你会立刻在终端看到一份人类可读的摘要报告。报告通常会包含以下几个部分：

• 各代理允许的工具列表：列出从配置文件中读取到的所有被许可的工具。
• 各代理观察到的工具及调用次数：这是从会话文件中统计出的实际使用情况。
• 未使用的允许工具：配置了但一次都没被调用过的工具。这部分是权限精简的主要依据，过多的未使用工具会增加不必要的攻击面。
• 观察到但未允许的工具：这是高风险信号！意味着代理执行了超出其权限范围的操作。需要立即审查是配置遗漏，还是发生了异常或恶意的工具调用。
• 最常使用的工具：帮助你了解代理的核心行为模式。
• 可疑的宽泛授权：工具会运用启发式方法，标记出可能过于宽泛的权限，比如直接允许shell、*（通配符），或者一个代理的允许列表中大部分工具都从未被使用。

如果你想获得更结构化的输出以便后续处理，可以加上--json参数：

openclaw-tool-audit --json > audit_report.json

生成的JSON文件可以被其他脚本、监控平台或数据可视化工具轻松消费。

4. 高级用法与定制化审计策略

4.1 过滤与聚焦：精准定位问题

当你的环境中有数十个代理和成千上万的会话日志时，全量扫描的输出可能会信息过载。openclaw-tool-audit提供了多个过滤选项来帮助你聚焦。

按代理筛选：如果你只关心某个特定代理（例如名为data_agent的代理）的权限情况，可以使用--agent参数：

openclaw-tool-audit --agent data_agent

这会让输出只显示与该代理相关的审计结果，界面非常清爽。

按时间范围筛选：安全审计常常关注近期活动。--last参数允许你只审计在特定时间范围内修改过的会话文件。它支持小时（h）、天（d）、周（w）为单位。

# 审计过去7天的活动 openclaw-tool-audit --last 7d # 审计过去24小时的活动 openclaw-tool-audit --last 24h

这里有一个重要的实操细节：--last参数是基于文件的修改时间（mtime），而非日志事件内部的时间戳。这意味着，如果你将旧日志文件复制到一个新目录，或者用脚本批量处理了日志文件导致其mtime更新，它们可能会被纳入近期审计范围。反之，如果一个日志文件很久没被写入但内部记录了最近的事件，它可能被过滤掉。对于时间精度要求极高的场景，你需要确保日志轮转或归档策略与工具的过滤逻辑相匹配。

只显示有问题的情况：在CI流水线中，你可能只关心那些存在“配置了但未使用”的冗余权限，或者存在“使用了但未配置”的越权行为的代理。--unused-only参数正是为此而生：

openclaw-tool-audit --unused-only

这个命令会过滤掉那些“权限配置与实际使用完全吻合”的“干净”代理，只输出存在潜在问题的代理信息，使得报告更加 actionable。

4.2 输出格式与集成：适配不同工作流

工具支持多种输出格式，以适应不同的下游处理需求。

1. 终端默认输出（人类可读）这是交互式使用时的默认选择，格式清晰，用颜色和缩进区分不同信息块，适合开发者快速浏览。

2. JSON 输出（机器可读）如前所述，--json参数输出结构化的JSON。这是与自动化系统集成的首选格式。你可以编写一个简单的Python脚本解析这个JSON，当发现observed_but_not_allowed数组非空时，就发送一个高优先级的告警到Slack或钉钉。

3. Markdown 输出（文档与报告）--markdown参数会生成格式良好的Markdown文档。这份文档可以直接粘贴到GitHub Issue、Confluence页面，或者作为每周安全周报的附件。它比纯文本更美观，比JSON更易读。

openclaw-tool-audit --markdown > WEEKLY_AUDIT_REPORT.md

结合--broadest-first参数，你可以让报告按风险排序（将授权最宽泛的代理排在最前面）：

openclaw-tool-audit --markdown --broadest-first > PRIORITIZED_REPORT.md

4. 自定义配置与日志路径如果你的项目结构不遵循默认约定，或者你想审计一个特定位置的配置集，可以使用--config和--sessions参数。这两个参数都可以重复使用，指定多个路径。

# 审计指定目录下的配置和日志 openclaw-tool-audit --config /path/to/agent/configs --sessions /var/log/openclaw/sessions # 混合审计多个来源 openclaw-tool-audit --config ./prod_configs --config ~/backup/old_configs --sessions ./logs

这个功能非常强大，允许你对归档的历史配置、不同环境的配置进行一次性对比审计。

4.3 深入解析“可疑的宽泛授权”启发式规则

工具输出的“可疑的宽泛授权”部分是其安全智能的体现。它不仅仅是简单罗列工具名，而是应用了一系列启发式规则来识别潜在的风险配置。了解这些规则有助于你更好地解读结果：

1. 通配符匹配：直接扫描配置中是否包含*、.*、all、any这类字眼。允许所有工具是最高风险的行为。
2. 高危能力令牌：维护了一个内置的“高危工具类别”列表。例如：
   • shell、bash、cmd：直接授予系统Shell访问权限。
   • filesystem、write_file、delete：不受限制的文件系统操作。
   • network、web、fetch、curl：发起任意网络请求。
   • github、git、repo_write：直接操作代码仓库。 这些工具本身可能有必要，但授权时需要格外谨慎，最好结合具体的参数限制（但当前工具版本主要做名称级审计）。
3. 低使用率的宽泛列表：如果一个代理的允许工具列表很长（比如超过20个），但实际观察到的工具只有寥寥几个，这本身就是一个风险信号。它意味着攻击面被不必要地扩大了。工具会计算一个“使用率”（已使用工具数 / 允许工具总数），并对使用率过低的代理给出提示。

实操心得：不要盲目地将所有被标记为“可疑”的授权都视为错误。例如，一个“管理后台”代理可能确实需要shell权限来执行运维脚本。关键是将此作为一个强制性的审查点。每次看到这个标记，你都应该停下来问自己：“这个代理真的需要这个权限吗？有没有更细粒度的替代方案？这个权限的使用是否有严格的日志记录和监控？” 这个工具的价值在于它强制你面对这些安全问题，而不是替你做出决策。

5. 集成到CI/CD流水线：实现安全左移

将openclaw-tool-audit集成到持续集成/持续部署（CI/CD）流水线中，是将其价值最大化的关键。这实现了“安全左移”，即在代码提交和构建阶段就发现权限问题，而不是等到生产环境出事。

5.1 基础GitHub Actions集成示例

下面是一个简单的GitHub Actions工作流配置示例，它会在每次向main分支推送代码或发起Pull Request时，运行工具审计，并将结果以注释形式添加到PR中。

# .github/workflows/audit-tools.yml name: Audit OpenClaw Tool Permissions on: push: branches: [ main ] pull_request: branches: [ main ] jobs: audit: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.10' - name: Install openclaw-tool-audit run: pipx install openclaw-tool-audit - name: Run tool audit id: audit run: | # 运行审计，并将JSON输出保存到变量 REPORT_JSON=$(openclaw-tool-audit --json) # 将JSON进行压缩转义，以便后续步骤使用 echo "report_json<<EOF" >> $GITHUB_OUTPUT echo "$REPORT_JSON" >> $GITHUB_OUTPUT echo "EOF" >> $GITHUB_OUTPUT # 同时运行一次人类可读的检查，如果发现违规则让步骤失败 if openclaw-tool-audit --unused-only | grep -q "observed-but-not-allowed"; then echo "❌ 发现越权工具使用！" >&2 exit 1 fi - name: Upload audit report (on failure) if: failure() && github.event_name == 'pull_request' uses: actions/github-script@v7 with: script: | const report = `### 🔍 OpenClaw 工具权限审计失败 在本次更改中发现了工具权限问题。以下是详细的JSON报告，请仔细审查： \`\`\`json ${process.env.REPORT_JSON} \`\`\` **请检查以下方面：** 1. \`observed_but_not_allowed\` 字段是否为空？非空表示存在越权使用。 2. 是否有多余的未使用工具（\`unused_allowed_tools\`）可以移除？ 3. 是否有代理被标记为 \`suspicious_broad_allowance\`？ `; github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: report });

这个工作流做了几件事：

1. 安装与运行：在CI环境中安装openclaw-tool-audit并执行审计。
2. 质量门禁：使用--unused-only配合grep检查是否有“越权使用”的情况。如果存在，则主动使构建失败，这是安全左移的核心——不让有问题的配置流入主分支。
3. 反馈到PR：如果是在Pull Request中失败，它会将详细的JSON报告以评论形式贴到PR里，方便开发者查看具体是哪个代理、哪个工具出了问题。

5.2 进阶：与配置管理及门禁策略结合

对于更成熟的安全体系，你可以将审计结果与动态配置管理和访问控制策略结合起来。

1. 生成权限基线文件：你可以定期（例如每天）在受控的预生产环境运行一次全量审计，将结果保存为“黄金基线”（golden baseline）。

openclaw-tool-audit --json > baseline_permissions.json

然后，在CI流水线中，不仅检查是否有“越权”，还可以检查当前PR引入的配置变更，与“黄金基线”相比是否出现了权限的异常扩张。例如，一个负责数据清洗的代理突然要求增加shell权限，这需要额外的审批流程。

2. 与Secrets管理联动：有些工具调用可能需要API密钥或其他密钥。你可以在审计报告中关联工具名与所需的密钥类型。如果发现一个代理使用了需要高权限密钥的工具（如github_push），但其配置中关联的密钥却是低权限的，这本身就是一个矛盾点，可以触发告警。

3. 自动化修复建议（高级）：对于unused_allowed_tools（未使用的允许工具），CI流水线甚至可以尝试生成自动化的修复建议。例如，在审计失败后，评论中可以直接附上修改配置文件的建议diff：

建议从 `data_agent` 的配置中移除以下未使用的工具： - unused_tool_a - unused_tool_b

这能极大提升开发者的修复效率。

6. 常见问题排查与实战技巧

6.1 工具找不到配置或会话文件

这是新手最常见的问题。通常是因为你的项目结构不符合工具的默认搜索路径假设。

症状：运行openclaw-tool-audit后，输出显示“No agent configurations found”或“No session files found”，或者列表为空。

排查步骤：

1. 确认路径：首先，使用pwd确认你所在的目录是否正确。工具是基于当前工作目录进行相对路径搜索的。
2. 使用--config和--sessions显式指定：不要猜测，直接使用绝对路径或明确的相对路径来指定位置。

   # 先找到你的文件在哪 find . -name "*.yaml" -o -name "*.json" | grep -E "(agent|config)" find . -name "*.jsonl" -o -name "*.log" | head -20 # 然后用找到的路径运行工具 openclaw-tool-audit --config ./my_configs/agents.yaml --sessions ./logs/

3. 检查文件格式和权限：确保配置文件是工具支持的格式（.json,.yaml,.yml,.toml），并且当前用户有读取权限。对于会话文件，同样检查格式（.json,.jsonl,.ndjson,.txt,.md,.log）和权限。
4. 检查文件内容：工具是通过搜索特定字段名来识别配置的。用文本编辑器打开你的配置文件，确认里面确实包含类似allowed_tools: [...]或"tools": [...]这样的结构。如果你们的配置字段名非常独特，你可能需要暂时将其改为工具能识别的字段名，或者向项目提Issue。

6.2 观察到工具数量为0或明显偏少

这意味着工具成功读取了会话文件，但没有从中解析出任何工具调用记录。

排查步骤：

1. 确认会话文件格式：如果你的日志是纯文本，工具依赖正则表达式匹配。运行一个简单的测试：

   # 检查你的日志文件中是否存在工具调用的典型模式 grep -n "to=" your_session.log | head -5 grep -n "tool_call" your_session.log | head -5

   如果grep也找不到，说明日志格式可能完全自定义，超出了工具的解析能力。
2. 测试结构化解析：如果你的文件是JSON格式，尝试用jq工具查看其结构：

   head -1 your_session.jsonl | jq .

   查看输出中是否存在tool_calls、function、recipient_name等工具识别部分提到的字段。如果没有，你需要调整日志记录逻辑，使其符合工具支持的某种格式。
3. 使用--json输出调试：运行openclaw-tool-audit --json，查看输出的JSON中，对应代理的observed_tools字段是否为空对象{}，以及原始文件解析是否有错误信息。工具的JSON输出有时会包含更详细的诊断信息。

6.3 代理归属错误或混淆

当多个代理的日志混在一起，或者路径推断不准确时，可能会出现A代理的工具调用被算到B代理头上的情况。

症状：审计报告显示某个“只读”代理使用了write_file工具，但检查其专属日志目录却发现没有相关记录。

解决方案：

1. 优先使用元数据：最可靠的方法是在记录会话时，确保每个事件都包含明确的agent_id或类似的元数据字段。这样工具就能准确归属，不受路径影响。
2. 隔离日志路径：如果无法修改日志格式，那就通过目录结构进行物理隔离。确保每个代理的会话文件都存放在其专属的、以代理ID命名的目录下，例如sessions/agent_a/...和sessions/agent_b/...。然后使用--sessions参数分别指定这些目录进行审计。
3. 分别审计：如果问题复杂，最直接的办法就是对每个代理单独运行一次审计：

   openclaw-tool-audit --agent agent_a --sessions ./sessions/agent_a openclaw-tool-audit --agent agent_b --sessions ./sessions/agent_b

6.4 处理误报与漏报

任何静态分析工具都可能存在误报（将正常行为报为问题）和漏报（未能发现真正的问题）。

对于误报（False Positives）：

• “可疑的宽泛授权”误报：比如一个内部使用的“超级管理”代理，确实需要shell权限。对于这种情况，你可以在CI脚本中设置白名单，忽略特定代理的特定警告。

  # 在CI脚本中，过滤掉对‘admin_agent’的‘broad_allowance’警告 openclaw-tool-audit --json | jq 'del(.agents[] | select(.id == "admin_agent").suspicious_broad_allowance)'

• “未使用的允许工具”误报：有些工具可能是为备用场景或低频任务配置的。你可以建立一个“已知且可接受的未使用工具列表”，在审计后对比过滤。

对于漏报（False Negatives）：

• 工具名变体：如果你们内部使用的工具名格式非常独特（例如com.company.department.tool），工具的文本模式可能匹配不上。此时，你需要扩展工具的解析逻辑。考虑到这是一个开源项目，最有效的方式是贡献代码：你可以研究项目源码中tool_patterns相关的部分，添加你们公司特有的模式，然后向原作者提交Pull Request。这不仅能解决自己的问题，也能惠及社区。
• 二进制或加密日志：如果你们的会话日志是二进制格式或经过加密，本工具无法处理。你需要一个前置的解密或转换步骤，将日志转换为工具能识别的明文格式（如JSONL）后再进行审计。

7. 项目开发、贡献与发布流程

7.1 本地开发环境搭建

如果你想深入研究工具原理，修复bug，或者添加新功能（比如支持一种新的配置文件格式），搭建本地开发环境非常简单。

# 1. 克隆仓库 git clone https://github.com/pfrederiksen/openclaw-tool-audit.git cd openclaw-tool-audit # 2. 创建虚拟环境（推荐） python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows # 3. 以可编辑模式安装，并包含开发依赖 python -m pip install -e ".[dev]" # 4. 运行测试套件，确保一切正常 pytest -v

安装[dev]额外依赖会包含pytest、black（代码格式化）、isort（导入排序）等工具，方便你进行代码风格检查和测试。

7.2 理解核心代码结构

项目代码结构清晰，核心逻辑主要分布在以下几个文件：

• openclaw_tool_audit/__main__.py：命令行入口点，负责参数解析和流程调度。
• openclaw_tool_audit/config_reader.py：负责从各种格式的文件中读取和解析代理配置，提取“允许的工具列表”。其中的_find_allowed_tools函数包含了字段名搜索的启发式逻辑。
• openclaw_tool_audit/session_reader.py：负责从会话/转录文件中解析出观察到的工具调用。_parse_structured和_parse_text函数分别是处理结构化文件和纯文本文件的核心。
• openclaw_tool_audit/audit.py：核心的审计逻辑所在。它接收从上面两个模块来的数据（允许的工具集、观察到的工具集），进行比对、统计，并生成最终的报告数据结构。
• openclaw_tool_audit/report.py：负责将审计结果渲染成终端文本、JSON或Markdown格式。

如果你想添加对新配置文件格式（比如XML）的支持，主要修改config_reader.py。如果想支持新的日志事件结构，则要修改session_reader.py中的模式匹配列表。

7.3 发布新版本流程

项目的发布流程高度自动化，基于Git标签驱动。这为维护者提供了极大的便利。

发布步骤：

1. 准备发布：确保pyproject.toml中的版本号已更新，所有代码更改已提交并推送到主分支。
2. 创建标签：使用git tag命令创建一个新的语义化版本标签。

   git tag v0.2.0 # 例如，从0.1.0升级到0.2.0

3. 推送标签：将标签推送到GitHub远程仓库。

   git push origin v0.2.0

4. 自动化流程接管：推送标签会触发仓库中预设的GitHub Actions工作流。这个工作流会自动执行以下操作：
   • 构建包：根据pyproject.toml构建标准的Python分发包。
   • 发布到PyPI：将构建好的包上传到Python官方包索引。这需要预先在仓库Secrets中配置好PYPI_API_TOKEN或启用Trusted Publishing。
   • 创建GitHub Release：在GitHub上基于该标签创建一个正式的发布版本，并附上变更说明。
   • 更新Homebrew Formula：自动向pfrederiksen/homebrew-tap仓库提交一个PR，更新Homebrew安装的formula文件。这需要配置HOMEBREW_TAP_TOKEN。

关键安全提示：整个流程中，绝对不要将PyPI API令牌等敏感信息硬编码在代码或配置文件中。必须通过GitHub仓库的Settings -> Secrets and variables -> Actions页面进行配置。这是保障开源项目发布安全的基本要求。自动化发布不仅减少了人为错误，也使得版本管理更加规范和可追溯。