Shroud：为AI智能体打造企业级隐私保护层，安全调用LLM API

1. 项目概述：为AI智能体穿上“隐身衣”

在AI智能体（Agent）技术快速渗透到企业核心业务流程的今天，我们正面临一个前所未有的隐私与安全悖论。一方面，像OpenClaw、Hermes Agent这样的智能体平台，能够以前所未有的效率处理网络故障排查、安全事件响应、合规审计等复杂任务。它们通过调用强大的大语言模型（LLM）API来获取推理能力。但另一方面，每一次向云端LLM发送的提示词（Prompt），都可能是一次无意的数据泄露。想象一下，你的智能体正在分析一份防火墙配置日志，其中包含了内部子网划分（如10.1.0.0/24）、核心交换机的主机名（CORE-SW-01）、甚至是用于设备管理的SNMP社区字符串。这些信息一旦被发送至第三方API，就如同将你的网络拓扑图公之于众。

Shroud正是为了解决这一核心矛盾而生的。它不是一个简单的字符串替换工具，而是一个运行在智能体与LLM之间的、具备上下文感知能力的隐私保护层。它的核心使命是：在数据离开你的进程之前，将其中所有敏感的基础设施信息和用户隐私数据，替换为格式保持一致的、确定性的假数据。LLM接收并处理这些“看起来真实”的假数据，完成推理和工具调用。当LLM的响应或工具执行结果返回时，Shroud再透明地将假数据恢复为真实值。对于最终用户和下游工具而言，整个过程是无感的，他们看到的、用到的始终是真实数据。但对于云端LLM提供商，他们从未接触过你的真实资产信息。

这不仅仅是关于个人身份信息（PII）的保护。对于运维、电信、能源、金融等行业，基础设施即机密。一个BGP AS号、一个VLAN ID、一个Modbus寄存器地址，其敏感性不亚于一张信用卡号。Shroud内置了超过130种实体类型的检测器，覆盖了从常见的邮箱、电话、IP地址，到专业的网络凭证、OT/SCADA标识符、云资源ARN等方方面面。它让企业能够安心地将AI智能体部署到生产环境，在享受AI带来的效率革命的同时，牢牢守住数据安全的底线。

2. 核心设计思路：在透明与安全之间取得平衡

设计一个有效的隐私保护中间件，远比简单的“查找-替换”复杂。它需要在多个相互冲突的目标间取得精妙的平衡：既要足够“聪明”以准确识别敏感信息，又要避免过度扫描导致误报影响智能体功能；既要确保替换的不可逆性（对LLM而言），又要保证还原的绝对准确性；既要支持复杂的、嵌套的工具调用链，又要保持极低的性能开销。Shroud的架构正是围绕这些挑战构建的。

2.1 确定性混淆与透明还原：隐私保护的基石

Shroud最核心的机制是确定性混淆。这意味着对于同一段输入文本和同一个密钥（secretKey），混淆后的输出永远是相同的。例如，邮箱admin@corp.com在本次会话中可能被替换为user-a1b2@example.net，那么在整个会话生命周期内，所有出现的admin@corp.com都会被一致地替换为同一个假邮箱。这个特性带来了几个关键优势：

1. 保护提示词缓存（Prompt Caching）：像Anthropic、OpenAI这样的提供商，会利用提示词缓存来降低重复计算的成本。如果每次混淆都生成随机的假数据，那么即使输入语义相同，提示词也会因token不同而被视为新请求，导致缓存失效，增加成本和延迟。确定性混淆确保了系统提示词前缀在不同对话轮次中保持完全一致，从而完美兼容提供商的缓存机制。
2. 保证LLM的上下文一致性：LLM需要在一个会话中追踪实体。如果同一个真实IP在第一轮被替换成100.64.1.1，在第二轮被替换成100.64.2.2，LLM将无法建立正确的关联，推理会出错。确定性混淆保证了实体在会话中的稳定指代。
3. 支持复杂的工具链：当LLM基于假数据生成一个工具调用（例如，ping 100.64.1.1），Shroud必须在工具执行前，将参数100.64.1.1准确地还原为真实IP。确定性映射使得这个反向查找快速且准确。

为了实现这一点，Shroud使用HMAC（基于哈希的消息认证码）结合一个持久化盐值（persistentSalt）来为每个检测到的实体生成一个唯一的、确定性的标识符，然后根据该标识符和实体类型，从一个格式保持的假数据生成器中产生对应的假值。

2.2 上下文感知检测：超越正则表达式

单纯依靠正则表达式进行敏感信息检测，误报率和漏报率都会很高。例如，一个版本号v1.2.3可能被误判为IP地址，一个普通的单词“deny”可能被误判为信用卡号（符合Luhn算法校验的巧合）。Shroud的ContextDetector引入了多层智能过滤和增强逻辑：

• 上下文关键词增强：当文本块中出现如interface、hostname、router ospf、username等配置关键词时，附近检测到的实体（如IP、主机名、密码）的置信度会获得显著提升（例如+10%）。这模仿了运维人员阅读配置时的直觉。
• 实体聚类与传播：如果在一个小范围内（如200字符内）同时检测到人名、邮箱和电话号码，它们会相互“佐证”，各自获得置信度提升。这有效识别了联系信息块。
• 主机名传播学习：一旦在类似hostname CORE-RTR-01的上下文中识别出CORE-RTR-01是一个主机名，Shroud会记住这个实体。在后续消息中，即使CORE-RTR-01单独出现，没有上下文，也能被准确识别并混淆。这解决了配置引用带来的碎片化问题。
• 常见词衰减：对于内置词典中的常见单词（如“permit”、“default”、“test”），即使其格式偶然匹配某种模式（如信用卡），其置信度也会被大幅降低（如-50%），从而避免误报。
• 文档与示例过滤：自动跳过已知的文档专用地址（如IPv6的2001:db8::/32）、环回地址（127.0.0.1,::1）、示例域名（example.com）和邮箱。这确保了技术文档的交流不受影响。

2.3 智能URL分类：内外有别，动态决策

URL的处理是另一个设计难点。智能体需要访问真实的公网资源（如GitHub、Stack Overflow、公开API文档）来执行任务，但必须隐藏所有内部链接（如Confluence wiki、Jira面板、管理后台）。Shroud采用了一种混合策略：

1. 静态知名域名放行列表：对于github.com、youtube.com、wikipedia.org、npmjs.com等公认的公共平台域名，直接放行，不进行DNS查询，以提升性能。
2. 动态DNS解析验证：对于不在放行列表中的域名，Shroud会在before_prompt_build钩子中异步发起DNS查询，并将结果缓存。如果域名解析到公网IP（非RFC 1918、非CGNAT、非环回地址），则视为外部URL，予以放行。如果解析到内网IP或解析失败（NXDOMAIN），则视为内部基础设施，进行混淆。
3. 缓存未命中时的安全默认策略：在会话的第一条消息，或DNS查询超时时，URL的解析结果可能尚未就绪。此时，Shroud采取保守策略，默认进行混淆。这是一种“安全失败”模式，优先保证隐私。随着对话进行，缓存逐渐预热，后续提及的同一公网域名将被正确放行。

这种设计确保了LLM能获取必要的公开网络信息，同时将企业内网拓扑彻底隐藏。

3. 集成与部署实战：无缝接入你的智能体生态

Shroud被设计为即插即用，支持当前主流的AI智能体平台。其核心是一个无运行时依赖的Node.js模块，通过不同的“包装器”适配各种环境。

3.1 在OpenClaw中部署（推荐）

OpenClaw是目前集成度最高、体验最完整的平台。确保你的OpenClaw版本在2026.3.24及以上。

# 1. 检查版本 openclaw --version # 2. 安装插件 openclaw plugins install shroud-privacy # 3. 编辑配置文件 vim ~/.openclaw/openclaw.json

在配置文件的plugins.entries部分添加或修改shroud-privacy的配置：

{ "plugins": { "entries": { "shroud-privacy": { "enabled": true, "config": { "auditEnabled": true, // 开启审计日志，方便观察 "minConfidence": 0.0, // 检测所有置信度>=0的实体 "secretKey": "", // 留空则自动生成（会话级）。如需跨会话一致，请设置固定值。 "persistentSalt": "your-company-unique-salt", // 建议设置，确保不同服务器间映射一致 "canaryEnabled": false // 高级功能：用于追踪潜在的数据泄露 } } } } }

关键配置项解析：

• secretKey：这是混淆算法的HMAC密钥。如果留空，Shroud会为每个会话自动生成一个随机密钥。这意味着同一个实体在不同会话中会被混淆成不同的假值。这对于单次会话是安全的，但如果你需要跨会话进行分析（例如，日志聚合），或者需要在多个独立的OpenClaw网关实例间保持相同的混淆结果，就必须设置一个固定且保密的secretKey。
• persistentSalt：一个额外的盐值，与secretKey结合使用，进一步增强映射的确定性。同样，为了跨会话一致性，建议设置。
• auditEnabled：强烈建议在调试阶段开启。它会在OpenClaw的日志中输出类似[shroud][audit] OBFUSCATE ...的记录，让你清晰看到哪些实体被检测和替换，而不会记录任何原始敏感数据。

配置完成后，重启OpenClaw网关以使插件生效：

openclaw gateway restart

3.2 在Hermes Agent中部署

对于使用Hermes Agent的用户，集成更为简单，因为它直接利用了底层的插件系统。

# 安装插件 hermes plugins install wkeything/shroud

安装后，无需任何额外配置。Shroud会自动拦截所有发往LLM提供者（OpenRouter、Anthropic、OpenAI等）的流量并进行混淆处理。Hermes Agent版本会自动启用按工具字段范围限定（Field Scoping），这能显著减少在工具返回的结构化数据（如ID、时间戳、哈希值）上的误报。

你可以通过以下命令验证Shroud的运行状态和统计信息：

# 查看实时的检测统计和规则命中情况 cat ~/.hermes/shroud-stats.json | python3 -m json.tool

3.3 通过Agent Privacy Protocol (APP) 集成任意智能体

这是Shroud最强大的部分——APP协议。它定义了一套基于stdin/stdout的JSON-RPC 2.0接口，使得任何编程语言编写的AI智能体都能获得同等级别的隐私保护。你无需依赖OpenClaw或Hermes。

部署APP服务器：首先，在你的项目中安装Shroud，并启动APP服务器守护进程。

npm install shroud-privacy # 启动APP服务器，指定Shroud引擎路径 node node_modules/shroud-privacy/app-server.mjs node_modules/shroud-privacy/dist

服务器启动后，会输出握手信息，然后等待JSON-RPC请求。

Python客户端示例：Shroud提供了一个轻量级的Python客户端 (shroud_client.py)，你可以直接复制到你的项目中。

from shroud_client import ShroudClient def process_with_llm(user_query): # 初始化客户端，它会自动启动和管理APP服务器子进程 with ShroudClient() as shroud: # 1. 识别当前智能体（可选，用于统计和会话隔离） shroud.identify(agent="my_custom_agent", version="1.0.0") # 2. 混淆用户输入 obfuscated_result = shroud.obfuscate(user_query) safe_prompt = obfuscated_result.text # 包含假数据的文本 print(f"检测到 {obfuscated_result.entity_count} 个实体，已混淆。") # 3. 将混淆后的文本发送给LLM llm_response = call_llm_api(safe_prompt) # 4. 还原LLM的响应 deobfuscated_result = shroud.deobfuscate(llm_response) safe_response = deobfuscated_result.text # 已恢复真实数据的文本 # 5. （可选）处理工具调用 # 假设LLM返回了一个工具调用请求：{"tool": "ping", "args": {"target": "100.64.0.12"}} tool_call = json.loads(llm_response) # 解析LLM响应 if tool_call.get("tool"): # 在调用真实工具前，还原参数 deobfuscated_args = shroud.deobfuscate(json.dumps(tool_call["args"])) real_target = json.loads(deobfuscated_args.text)["target"] # 得到真实IP，如 10.1.0.1 tool_result = execute_ping(real_target) # 在将工具结果存储或返回给LLM前，再次混淆 obfuscated_result = shroud.obfuscate(tool_result) store_result(obfuscated_result.text) return safe_response # 使用示例 user_input = "请检查主机 db-server-01 (IP: 10.2.5.10) 的日志，联系人 alice@example.com。" final_output = process_with_llm(user_input) print(final_output) # 输出已还原的真实信息

APP协议的核心方法：

• identify: 注册智能体，用于会话管理和统计。
• obfuscate: 核心混淆方法。
• deobfuscate: 核心还原方法。
• tool_call/tool_result: 用于在复杂的多步工具调用链中跟踪和隔离数据流，确保工具参数和结果也得到正确处理。

4. 高级配置与调优：打造专属的隐私防线

Shroud提供了细粒度的配置选项，以适应不同组织的安全策略和业务场景。所有配置都支持热重载（部分核心项除外），无需重启服务。

4.1 配置文件管理与热重载

Shroud在首次运行时，会在~/.shroud/目录下生成一个详细的JSONC（支持注释的JSON）配置文件：shroud.config.json。这个文件包含了所有内置检测规则的完整列表及其默认参数。

修改配置并热重载：

1. 编辑~/.shroud/shroud.config.json。
2. 保存文件。
3. Shroud会在2秒内自动检测到文件变化并重新加载配置。控制台会输出[shroud][config] Configuration reloaded的日志。

配置优先级：环境变量 > 配置文件 (shroud.config.json) > 插件配置 (openclaw.json) > 默认值。例如，你可以通过export SHROUD_SECRET_KEY=my-secure-key来覆盖配置文件中的设置。

4.2 按工具字段范围限定：精准扫描，减少误报

默认情况下，Shroud会扫描消息中的每一个字符串字段。这对于安全至上的场景是好的，但会产生误报。例如，一个Read工具返回的文件内容中的路径/home/user/data.txt会被混淆，但这可能正是智能体需要读取的路径。

字段范围限定（Field Scoping）允许你为特定的工具定义哪些字段需要被扫描。这大幅提升了准确性和实用性。

// 在 ~/.shroud/shroud.config.json 中添加 { "fieldScoping": { "toolFields": { "Read": { "scanFields": ["content", "text"] // 只扫描内容和文本字段 }, "Bash": { "scanFields": ["output", "stdout", "stderr"] // 只扫描输出字段 }, "gmail_*": { // 通配符匹配所有gmail相关工具 "scanFields": ["subject", "body", "snippet", "from", "to"] }, "github_*": { "scanFields": ["title", "body", "description", "comment"] } }, "neverScanFields": [ // 永远不扫描的字段（通常是元数据） "id", "created_at", "updated_at", "sha", "hash", "ref", "type", "status" ], "defaultScanFields": [] // 对于未匹配的工具，扫描所有字段（安全默认值） } }

4.3 自定义检测规则与规则覆盖

你可以完全控制检测逻辑，包括禁用内置规则、修改其置信度，或添加全新的规则。

禁用不需要的规则：

{ "rules": { "phone_us": { "enabled": false }, // 禁用美国电话号码检测（如果你的业务不在美国） "gps_coordinate": { "enabled": false } // 禁用GPS坐标检测 } }

添加自定义规则（例如，检测内部工单号）：

{ "rules": { "internal_ticket": { "pattern": "\\b(?:TICKET|INC)-\\d{6}\\b", // 正则表达式 "category": "custom", // 分类，用于统计和审计 "confidence": 0.95, // 置信度 "enabled": true }, "internal_api_key": { "pattern": "\\bsk_(?:test|live)_[a-zA-Z0-9]{24}\\b", "category": "api_key", "confidence": 0.98, "enabled": true } } }

4.4 混淆级别与审计日志

Shroud提供三种混淆输出模式，适用于不同场景：

审计日志是运维的“眼睛”。开启后，你可以在OpenClaw日志中看到类似下面的条目：

[shroud][audit] OBFUSCATE req=abc123 | entities=3 | chars=850->868 (delta=+18) | modified=YES | byCat=email:1,ip_address:2

这告诉你：一次混淆请求发生了，替换了3个实体（1个邮箱，2个IP），文本长度增加了18个字符（由于假数据可能更长）。关键点：审计日志只记录元数据和计数，绝不记录原始值或真实的假值映射，这本身也是一种隐私保护。

如果需要更深入的审计（用于取证），可以启用证明哈希（auditIncludeProofHashes: true）。这会为输入和输出文本生成一个加盐的SHA-256哈希片段，用于在发生可疑泄露时，在不暴露原文的情况下进行比对验证。

5. 实战问题排查与经验分享

在实际部署和使用Shroud的过程中，你可能会遇到一些典型问题。以下是我在多个生产环境中总结出的排查清单和技巧。

5.1 常见问题速查表

5.2 调试与验证技巧

1. 使用shroud-stats工具：这是一个强大的命令行工具，可以实时查看引擎状态。

# 查看所有检测规则的命中次数和状态 shroud-stats # 以JSON格式输出，便于脚本处理 shroud-stats --json # 测试一段文本，看会被检测出什么 shroud-stats --test "我的邮箱是 test@company.com，服务器IP是 192.168.1.1"

输出会清晰显示检测到的实体类型、位置、置信度以及将被替换成的假值样例。

2. 理解“确定性”在测试中的重要性：在编写自动化测试时，由于Shroud的确定性，你可以为一段固定的输入和固定的secretKey/persistentSalt断言其输出。这使测试变得简单可靠。

3. 处理嵌套和编码数据：Shroud支持递归反混淆（默认3层），能处理JSON字符串中的嵌套实体。例如，如果LLM返回{"error": "Cannot connect to 100.64.0.12"}，这个JSON字符串本身会被反混淆，其中的假IP100.64.0.12会被还原。但要注意，如果数据是经过Base64或URL编码的，Shroud的检测器可能无法直接识别。在这种情况下，可能需要智能体在调用Shroud之前先进行解码。

5.3 给智能体开发者的建议

如果你正在构建一个需要集成Shroud的AI智能体，以下几点经验至关重要：

• 将Shroud视为数据管道的一个环节：它的输入是原始文本（或结构化数据的字符串表示），输出是安全文本。理想情况下，所有进出LLM的文本数据流都应经过Shroud。
• 妥善处理工具调用边界：这是最容易出错的地方。确保在将LLM生成的工具参数传递给实际工具之前，调用deobfuscate。同样，在将工具执行结果返回给LLM或存储到历史记录之前，调用obfuscate。APP协议的tool_call和tool_result方法就是为此设计的。
• 为LLM提供上下文：务必在系统提示词中告知LLM Shroud的存在和基本行为，避免LLM对混淆后的数据产生困惑或做出错误提示。
• 监控审计日志：定期检查审计日志，了解哪些类型的实体最常被混淆，这有助于你调整检测规则和置信度，在安全性和功能性之间找到最佳平衡点。

Shroud不是一个“设置即忘”的银弹，而是一个需要根据你的具体数据流和业务场景进行调优的强大工具。通过理解其工作原理，合理配置，并建立有效的监控，你可以极大地提升AI智能体在企业环境中应用的安全性，让技术创新不再以牺牲数据隐私为代价。