GuardClaw：为AI助手构建本地隐私执行层的实战指南

1. 项目概述：为你的AI助手装上隐私“利爪”

如果你和我一样，每天都在用各种AI助手处理工作，从写代码、分析数据到整理会议纪要，那你肯定也思考过同一个问题：我发给云端AI的那些信息，真的安全吗？一封邮件草稿里可能夹带着客户电话，一段待分析的日志可能藏着数据库连接字符串，甚至一次简单的代码调试请求，都可能无意中暴露内部服务器的IP地址。过去，我们只能寄希望于AI服务商的“承诺”，或者手动在发送前绞尽脑汁地审查每一句话——既低效，又难免疏漏。

GuardClaw 的出现，彻底改变了这个局面。它不是一个简单的过滤器，而是一个运行在你本机、深度集成到AI工作流中的隐私执行层。你可以把它想象成你AI助手的一个“隐私副驾驶”。它的核心工作非常简单粗暴：在你与云端AI（无论是OpenAI的GPT、Anthropic的Claude，还是其他任何通过OpenClaw接入的模型）的每一次对话中，GuardClaw都会实时拦截并审查所有流出你电脑的消息、工具调用以及工具返回的结果。

它的审查基于一套清晰、可审计的三级分类规则（S1安全，S2敏感，S3私密），并采用“规则优先，模型辅助”的检测策略。敏感信息（如密码、API密钥）会被本地代理剥离后再转发；绝密信息（如SSH私钥、病历）则根本不会离开你的设备，而是交由一个专门的本机模型来处理。这意味着，你的私人数据获得了“物理隔离”级别的保护。自从我把GuardClaw集成到我的开发环境后，我再也不用在让AI帮忙分析日志前，手动去替换里面的IP和密钥了，这种心理上的安全感，是任何服务条款都无法给予的。

2. 核心架构与隐私分级设计解析

GuardClaw的威力，源于其清晰且强制的隐私分级体系。这套体系不是模糊的建议，而是嵌入到数据流每一个环节的硬性规则。理解它，是有效使用这个工具的关键。

2.1 三级分类体系：从“放行”到“隔离”

GuardClaw将所有内容划分为三个安全等级，我习惯把它们看作数据出境的“护照签证”状态：

S1 (Safe - 安全通行)这是最普通的级别。任何被归类为S1的内容，比如讨论公开的编程概念、询问天气、生成创意文案，都会原封不动地发送到你配置的云端AI提供商。GuardClaw对其不做任何修改，保证AI能力的完整性和响应速度。判断依据主要是排除法：即不属于S2和S3的内容。

S2 (Sensitive - 敏感脱敏)这个级别涵盖个人身份信息（PII）和一般性凭证。例如，电子邮件地址、电话号码、身份证号、非特指的“密码”、“API密钥”等词汇，以及常见的内部网络地址段（如192.168.x.x,10.x.x.x）。对于S2内容，GuardClaw会启动其隐私代理。这个代理在本地运行，它会像一位严谨的编辑，将消息中的敏感字段替换为无害的占位符（如[EMAIL_REDACTED],[IP_REDACTED]），然后将“清洁”后的版本发送至云端。云端AI处理的是脱敏后的文本，但因为你本地的GuardClaw持有原始上下文，它能在AI回复后，将占位符逆向恢复，让你在界面上看到完整的对话。这个过程对你几乎是透明的。

S3 (Private - 私密本地)这是最高警戒级别。涉及核心安全资产或极度隐私的数据，例如SSH私钥文件内容（-----BEGIN RSA PRIVATE KEY-----）、具体的AWS密钥对（AKIA...）、.env配置文件内容、或明确的医疗健康信息。一旦被检测为S3，这条消息将完全禁止发送至云端。取而代之的是，GuardClaw会将其路由到一个你预先配置好的、完全在本地运行的守护代理模型。这个本地模型会处理你的请求，并将结果返回。整个交互循环被严格限制在你的设备内部，形成一道“空气间隙”。

2.2 检测引擎：规则与智能的协同

如何准确分类？GuardClaw采用了一个分层检测管道，兼顾了速度、准确性和可解释性。

1. 规则引擎（快速、确定）：这是第一道，也是最快的一道防线。它基于你配置文件（~/.openclaw/guardclaw.json）中定义的keywords（关键词）、patterns（正则表达式）和paths（文件路径模式）进行匹配。例如，你可以设置任何包含“ssh”或路径匹配“*/.ssh/id_rsa”的内容直接标记为S3。这部分逻辑是确定性的，执行速度在微秒级，能捕获绝大多数已知模式的敏感信息。

2. 本地LLM分类器（处理边缘情况）：规则总有覆盖不到的灰色地带。比如，“我父亲的生日是1990年3月21日”这句话，不包含任何关键词，但却是明确的PII。这时，可选的本地LLM分类器就派上用场了。GuardClaw会调用一个专门优化用于分类任务的小型本地模型（如推荐的lfm2-8b-a1b），让它结合上下文判断信息的敏感程度。这个步骤虽然比规则匹配慢（约600毫秒），但极大地提升了系统对复杂、隐蔽信息的识别能力。

关键经验：不要用大型的“推理模型”来充当这个分类器。像QwQ、DeepSeek-R1这类模型，虽然能力强，但它们在严格遵守输出格式（尤其是JSON）方面可能表现不稳定，极易导致检测管道解析失败。分类任务需要的是“听话”和“快速”，lfm2-8b-a1b这类混合专家模型是绝佳选择。

2.3 双轨会话与内存隔离：上下文不泄露

一个高级特性是它的双轨会话历史和内存隔离。OpenClaw的AI助手通常会维护一个会话内存（MEMORY.md）来记住上下文。GuardClaw对此进行了精妙改造：

• 清洁内存(MEMORY.md)：发送给云端AI的版本。所有被隐私代理处理过的S2内容，在这里都以脱敏形式存在。
• 完整内存(MEMORY-FULL.md)：存储在你本地的完整、未删节的对话历史。

当你开启一个新会话时，GuardClaw会根据接收方是云端模型还是本地守护代理，智能地提供对应版本的内存作为上下文。这意味着，云端AI始终在“失忆”状态下处理你的敏感任务，而本地模型则拥有完整的“记忆”。两者通过GuardClaw自动同步，你无需手动管理。

3. 实战部署与配置指南

理论很美好，但让GuardClaw在你的机器上跑起来才是关键。下面是我从零部署并调优的完整过程，涵盖了从安装、模型选择到高级配置的每一个细节。

3.1 环境准备与一键安装

首先，确保你的基础环境就绪：

• Node.js 22+：GuardClaw基于Node构建。
• OpenClaw 2026.3.x+：它是作为OpenClaw的插件运行的。
• 本地推理后端：至少需要一个，用于运行S3守护代理和可选的分类器。Ollama是最简单通用的选择。

我强烈推荐使用项目提供的一键安装脚本，它能处理大量依赖和系统服务注册的脏活累活。

# 使用官方推荐的一键安装方式 git clone https://github.com/List3r/guardclaw-openclaw-plugin.git /opt/guardclaw cd /opt/guardclaw && bash scripts/install.sh

这个脚本会：

1. 检查并提示安装缺失的依赖（如Python、pip包）。
2. 构建插件。
3. 将其链接到你的OpenClaw插件目录。
4. 在~/.openclaw/下生成默认的guardclaw.json配置文件。
5. 自动部署并启动Prompt注入检测服务：这是一个基于DeBERTa v3模型的独立FastAPI服务，运行在8404端口，用于拦截S0级别的提示词注入攻击。脚本会将其注册为系统服务（macOS的launchd或Linux的systemd），实现开机自启。
6. 最后重启OpenClaw网关使插件生效。

安装完成后，立刻验证两个核心服务：

# 1. 检查DeBERTa注入检测服务是否健康 curl http://127.0.0.1:8404/health # 应返回 {"status":"healthy"} # 2. 检查GuardClaw仪表盘 # 打开浏览器访问 http://127.0.0.1:18789/plugins/guardclaw/stats # 你应该能看到实时检测日志和统计信息面板。

3.2 模型选型与资源配置策略

这是配置中最核心、也最容易踩坑的部分。GuardClaw涉及多个模型角色，需要根据你的硬件（尤其是GPU显存）合理规划。

我的硬件配置与方案： 我使用的是一台配备32GB统一内存的Apple Silicon Mac。以下是完美运行方案：

1. 用LM Studio运行lfm2-8b-a1b：LM Studio对macOS的Metal优化极好，启动快，内存管理高效。将模型加载后，确保其API服务器运行在http://localhost:1234。
2. 用Ollama运行qwen3.5:35b和nomic-embed-text：Ollama通过ollama pull拉取这两个模型。qwen3.5:35b是处理私活的主力。
3. 内存分配：三个模型同时驻留，总占用约29GB，在32GB内存的机器上留有合理余量，系统运行流畅。

如果你的显存/内存不足（例如只有16GB）： 不要强行运行qwen3.5:35b。你可以调整S3策略，放弃本地处理，改为“标记并转发”模式。在配置中，将rules.policies.S3设置为"redact-and-forward"。这样，S3内容会被识别并替换为[REDACTED:PRIVATE]标记，然后转发给云端AI处理。这牺牲了一些隐私，但保证了功能可用性。

3.3 核心配置文件详解

配置文件~/.openclaw/guardclaw.json是GuardClaw的大脑。安装脚本会生成一个带注释的示例，你需要根据你的环境修改关键部分。

{ // 1. 本地模型配置（用于S1/S2的LLM分类） "localModel": { "enabled": true, "type": "openai-compatible", "provider": "lmstudio", // 也可以是 ollama, vllm 等 "model": "lfm2-8b-a1b", // 关键：务必使用推荐模型 "endpoint": "http://localhost:1234", "apiKey": "lm-studio" // LM Studio的固定key，非必需但建议填写 }, // 2. 守护代理配置（用于处理S3内容） "guardAgent": { "id": "guard", "workspace": "~/.openclaw/workspace-guard", // 守护代理的独立工作区 "model": "ollama-server/qwen3.5:35b", // 格式为 `后端/模型名` "endpoint": "http://localhost:11434" // Ollama 默认地址 }, // 3. 检测规则 - 这是你自定义隐私边界的地方 "rules": { "keywords": { "S2": ["password", "secret", "token", "key", "credential", "passwd", "auth"], "S3": ["ssh-key", "id_rsa", "private_key", ".pem", ".pfx", ".env", "AWS_SECRET_ACCESS_KEY"] }, "patterns": { "S2": [ "\\b\\d{3}-\\d{2}-\\d{4}\\b", // 美国SSN格式示例 "\\b\\d{4}[-\s]?\\d{4}[-\s]?\\d{4}[-\s]?\\d{4}\\b" // 信用卡号简化示例 ], "S3": [ "-----BEGIN (?:RSA|DSA|EC|OPENSSH) PRIVATE KEY-----", // 匹配多种私钥 "AKIA[0-9A-Z]{16}", // AWS访问密钥ID "\\b(?:sk-|eyJ)[a-zA-Z0-9_-]{40,}\\b" // 通用API密钥模式 ] }, "paths": { "S3": ["**/.ssh/*", "**/*.pem", "**/*.key", "**/secrets/*", "**/.env*"] } }, // 4. 策略定义 "policies": { "S2": "proxy", // 敏感信息：使用隐私代理脱敏后转发 "S3": "local" // 私密信息：强制本地守护代理处理 // 若资源不足，可将S3改为 "redact-and-forward" }, // 5. 模型顾问（强烈建议开启） "modelAdvisor": { "enabled": true, "checkIntervalWeeks": 2, "deberta": { "autoUpdate": true } // 自动更新注入检测模型 } }

配置心得：在rules.keywords里，我建议把你项目中特有的内部术语也加进去，比如我们内部用的“内网穿透地址”、“堡垒机”等词汇，可以设为S2。patterns部分的正则表达式需要谨慎测试，避免误伤正常文本。可以先设置得宽松一些，运行一段时间后，通过仪表盘的日志观察是否有漏网之鱼或误杀，再逐步收紧。

4. 高级特性与深度应用

GuardClaw不仅仅是一个隐私过滤器，它提供了一套完整的、可编程的AI交互安全与管理体系。

4.1 提示词注入防御（S0层）

这是GuardClaw在基础隐私分级之上新增的一层主动防御。它使用一个专门的DeBERTa v3模型，在任何用户消息到达你的主AI模型之前进行拦截和评分。如果检测到潜在的提示词注入攻击（例如试图让AI忽略之前指令、泄露系统提示词或执行恶意操作的内容），该消息会被直接阻断，并记录为S0事件。

这个服务由安装脚本自动部署。你可以在仪表盘的“检测日志”里看到所有被拦截的S0事件。它的存在，相当于在你的AI工作流门口增加了一个专业的“安检员”，从源头杜绝了一种常见的安全风险。

4.2 成本感知路由与预算护栏

这是一个能直接帮你省钱的功能。当token-saver路由器启用后，GuardClaw会在确保隐私分级的前提下，对任务进行智能路由。

工作原理：它用一个轻量级判断逻辑（或一个小型本地模型）快速评估当前消息的复杂度。简单的查询（如“总结这段文字”、“修正语法”）会被路由到更便宜的模型（例如Claude 3.5 Haiku、GPT-4o-mini）；而复杂的推理、编程任务则仍然使用高性能模型（如Claude 3.5 Sonnet、GPT-4o）。

"routers": { "token-saver": { "enabled": true, "costThreshold": 0.05, // 单位美元，预估成本低于此值走廉价模型 "simpleModel": "claude-3.5-haiku", "complexModel": "claude-3.5-sonnet" } }

结合预算护栏功能，你可以在仪表盘里设置每日或每月的最高消费限额。GuardClaw会实时追踪所有通过它路由的token消耗和估算成本，并在接近限额时发出警告或停止转发请求到付费API。

4.3 模型顾问与持续优化

modelAdvisor是一个后台智能助手，它会定期（默认每两周）执行三项检查：

1. OpenRouter比价：扫描OpenRouter市场，寻找与你当前使用的云端模型能力相近但更便宜的替代品。
2. 本地模型升级：利用LLMFit等基准数据，发现是否有更优的本地模型发布。
3. DeBERTa更新：检查HuggingFace上是否有新版本的提示词注入检测模型。

所有建议都会呈现在仪表盘的“顾问”标签页中，附上性能对比和预估节省费用。对于DeBERTa更新，如果设置了autoUpdate: true，它甚至会默默完成下载和热替换，无需重启服务。这个功能确保你的守护系统本身也在不断进化。

4.4 Docker与Kubernetes密钥集成

对于在容器化环境中使用OpenClaw的开发者，这是一个杀手级特性。GuardClaw能自动识别通过Docker或Kubernetes标准路径（/run/secrets/,/var/run/secrets/）挂载的密钥文件。

实战场景：你的应用通过环境变量DB_PASSWORD_FILE=/run/secrets/db_password来获取数据库密码。如果AI助手在执行过程中，偶然或因为调试需要读取了这个文件，传统方案下，密码明文会进入AI上下文。而有了GuardClaw：

1. 它检测到路径包含/run/secrets/，立即将整个文件内容标记为S2（敏感）。
2. 提取密码值，并在当前会话中将其加入“污染追踪”列表。
3. 此后，会话中任何地方出现这个密码字符串，在发送给云端AI前都会被替换为[REDACTED:TAINT]。

这实现了真正的“深度防御”，即使工作流复杂，也能防止密钥通过AI交互链意外泄露。

5. 故障排查与效能调优

即使配置得当，在实际运行中也可能遇到问题。以下是我遇到并解决的一些典型情况。

5.1 安装与启动常见问题

问题：安装后OpenClaw网关崩溃或无法启动。

• 排查：首先禁用GuardClaw以确认问题来源。编辑~/.openclaw/guardclaw.json，将顶层或相关模块的"enabled"设为false，然后重启网关 (openclaw gateway restart)。
• 查看日志：最关键的日志位于~/.openclaw/logs/gateway.err.log。使用tail -f ~/.openclaw/logs/gateway.err.log | grep -A 10 -B 10 GuardClaw来过滤出相关错误。
• 常见原因：
  • 本地模型端点不可达：检查localModel.endpoint和guardAgent.endpoint的URL和端口是否正确，模型服务是否已启动（如Ollama的ollama serve，LM Studio的本地服务器）。
  • 配置文件语法错误：JSON格式严格，多一个逗号或少一个引号都会导致解析失败。使用在线JSON校验器检查你的guardclaw.json。
  • Node版本不兼容：确保使用Node.js 22或更高版本。

问题：DeBERTa注入检测服务未响应。

• 检查服务状态：

  # macOS launchctl list | grep deberta # Linux (systemd用户级) systemctl --user status guardclaw-deberta

• 查看服务日志：tail -f ~/.openclaw/deberta.log
• 重启服务：

  # macOS launchctl kickstart -k gui/$(id -u)/ai.guardclaw.deberta # Linux systemctl --user restart guardclaw-deberta

• 手动测试：curl http://localhost:8404/health应返回{"status":"healthy"}。如果没有，可能是Python依赖缺失。进入插件目录的scripts/文件夹，尝试手动运行python injection_classifier.py查看具体报错。

5.2 检测效果调优

问题：误报太多（正常内容被标记为敏感）。

• 调整规则：检查rules.keywords列表是否过于宽泛。例如，如果你经常讨论“API设计”，而“API”是S2关键词，就会导致误报。可以考虑将关键词改为更具体的“api_key”、“api_secret”。
• 优化正则表达式：过于激进的正则表达式是误报的主要来源。例如，一个匹配16位数字的信用卡正则可能误伤版本号。尽量让模式更精确，或添加更多上下文限制。
• 降低LLM分类器权重：在配置中，可以调整detection部分llmClassifier的confidenceThreshold（置信度阈值），将其调高，让LLM只在非常确定时才覆盖规则结果。

问题：漏报（敏感信息未被识别）。

• 丰富关键词和模式：通过仪表盘的日志，观察哪些敏感信息溜走了。如果是新的凭证格式（如你公司特有的令牌格式），将其模式添加到rules.patterns.S2或S3中。
• 启用并优化LLM分类器：确保localModel配置正确且启用。LLM分类器特别擅长发现上下文中的PII（如“我的驾照号码是…”）。如果它未启用或运行不正常，这部分检测就会缺失。
• 检查路径规则：如果你发现特定目录下的文件内容未被识别，确认rules.paths模式是否正确。支持通配符，如“**/config/*.yaml”。

5.3 性能优化建议

• 分类器模型选择：再次强调，用于localModel的必须是像lfm2-8b-a1b这样的“分类专用”轻量模型。使用大型推理模型会显著增加每次交互的延迟（从几百毫秒到数秒）。
• 合理使用缓存：GuardClaw内部有检测结果缓存。对于重复或相似的消息，能直接返回分类结果。确保缓存是开启的（默认开启）。
• 按需调整检测粒度：如果对绝对性能有极致要求，可以考虑暂时关闭LLM分类器，完全依赖规则引擎。规则引擎的速度极快，虽然可能漏掉一些边缘案例，但对已知模式的防护依然强大。
• 监控仪表盘：定期查看仪表盘中的“性能指标”部分，关注“检测延迟”和“缓存命中率”。如果延迟持续过高，就需要按上述点进行排查。

6. 开发集成与扩展可能性

GuardClaw的架构是模块化和可扩展的，这为开发者集成到自己的AI应用或研究提供了便利。

6.1 理解插件钩子与数据流

GuardClaw通过实现OpenClaw的插件钩子来介入AI助手的工作流。核心的钩子包括：

• beforeMessageSend：在用户消息发送给AI模型前调用，执行S0（注入检测）和S1/S2/S3分类。
• beforeToolCall/afterToolCall：在AI调用工具（如读写文件、执行命令）前后进行拦截，可以基于工具路径和参数进行安全审查。
• modifyMessageForProvider：在消息最终发送给特定AI提供商（如OpenAI、Anthropic）前，进行最后的修改，例如应用隐私代理脱敏。
• getMemory/setMemory：实现双轨内存的读写逻辑。

通过阅读src/hooks.ts，你可以清晰地看到数据是如何被拦截、分类、处理和转发的。这种设计意味着你可以编写自己的“路由器”或“检测器”，插入到GuardClaw的管道中。

6.2 编写自定义路由器

GuardClaw的路由器管道是可组合的。除了内置的privacy（隐私路由）和token-saver（成本路由），你还可以在配置中定义自己的路由器。

例如，假设你想根据项目目录来路由模型：所有在~/projects/secret-project/下的文件操作，都强制使用本地模型。

"routers": { "privacy": { "enabled": true }, "token-saver": { "enabled": true }, "project-router": { "enabled": true, "type": "custom", "config": { "secretProjectPath": "~/projects/secret-project/", "localModelId": "guard" // 指向你的守护代理 } } }

你需要创建一个对应的路由器实现文件（例如custom-routers/project-router.ts），导出一个函数来检查消息或工具调用是否涉及特定路径，并返回路由决策。然后将你的自定义路由器注册到插件中。这为基于上下文的安全策略提供了无限可能。

6.3 利用学习循环进行纠正

GuardClaw内置了一个“纠正存储”机制。当你在仪表盘中手动纠正了一次自动分类（例如，系统将一段无害代码误判为S3，你将其改为S1），这次纠正会被存储并向量化。

当下次出现语义相似的查询时，系统会优先参考这些历史纠正来进行分类，从而让系统越来越符合你的个人或团队的使用习惯。这个功能默认开启，你可以在仪表盘的“纠正存储”界面查看和管理这些记录。

从部署GuardClaw到现在，它已经无声无息地处理了成千上万次我对AI的请求。最大的感受是，它提供了一种“无感的安全”。我不再需要在进行每一次对话前，在脑子里先做一次安全检查。无论是处理包含真实IP的服务器日志，还是调试需要读取环境变量的脚本，我知道GuardClaw在底层为我兜底。那种可以放心地把任何文本丢给AI助手，而不用担心会“说错话”的松弛感，极大地提升了我的工作效率和探索勇气。它不仅仅是一个工具，更像是一个值得信赖的、永远清醒的守门人，让我能更专注地利用AI的能力，而不是担忧它的风险。