EdgeClaw 深度解析：断网也能跑的端云协同 AI Agent 部署教程与原理拆解

当前可见 60% 的内容

快速摘要
EdgeClaw 是基于 OpenClaw 构建的端云协同 AI 智能体，由清华大学 THUNLP、中国人民大学、AI9Stars、面壁智能和 OpenBMB 联合开发。它的核心价值在于：通过 GuardClaw 隐私中间件实现三级安全分级（S1 安全直通、S2 脱敏转发、S3 本地处理），让你的敏感数据绝不上云。本地推理基于面壁智能的 MiniCPM 系列端侧模型，配合 Ollama 即可一条命令跑起来，量化版 8GB 内存就能运行。整个系统通过 10 个 Hook 覆盖 AI Agent 完整生命周期，从消息接收到记忆同步全链路守护。往下看，莫潇羽@无忆研习社为你详细拆解这个项目的底层原理、安装部署全流程，以及每一个技术细节。

一、OpenClaw 是什么？为什么需要 EdgeClaw？

在聊 EdgeClaw 之前，我们必须先搞清楚 OpenClaw 到底是个什么东西——因为 EdgeClaw 就是在它的基础上长出来的。

OpenClaw（前身是 Clawdbot、Moltbot）是 2026 年初开源社区中增长最快的 AI Agent 项目之一，由奥地利开发者 Peter Steinberger 发起，在 GitHub 上的 Star 数已经突破 24 万。它的核心定位是一个本地运行的 AI 智能体网关：你在自己的电脑上跑一个 Gateway 进程，然后通过各种即时通讯平台（Telegram、Discord、WhatsApp、飞书、钉钉等 20 多个平台）给它下指令，它就会调用大语言模型来理解你的意图，再通过本地工具（Shell 命令、文件系统、浏览器自动化等）帮你执行任务。

简单来说，OpenClaw 不是一个只会聊天的机器人，而是一个真正能干活的 AI 助手——它能读写文件、处理邮件、运行代码、操作浏览器、调度定时任务，甚至可以管理多个子 Agent 协同工作。它采用「微核 + 插件 + 统一网关」的架构，底层推理服务完全可插拔，你可以随时切换不同厂商的大模型。

从技术架构上看，OpenClaw 的工作流程大致是这样的：你通过聊天平台发送一条消息 → Channel Bridge（通道桥接器）接收并转换为标准格式 → Gateway（网关）作为核心控制平面进行消息路由 → 大模型接收请求并进行推理 → 如果需要执行操作，调用对应的工具（文件读写、Shell 命令、浏览器操作等） → 将结果写入记忆系统 → 通过聊天平台返回给你。整个过程中，Gateway 是唯一常驻的进程，占用一个端口（默认 18789），所有数据都存储在本地的 ~/.openclaw/ 目录下，包括配置文件、会话历史（JSONL 格式）、记忆文件（Markdown 格式）等。

OpenClaw 还有一个非常丰富的 Skills 生态系统——通过 ClawHub 技能市场，你可以获取各种功能扩展模块，涵盖邮件管理、日程提醒、代码审查、内容创作、数据分析等多个领域。每个 Skill 本质上是一个包含 SKILL.md 说明文件的目录，Agent 会根据任务需求自动选择合适的 Skill 来完成工作。

但 OpenClaw 有一个绕不开的问题：虽然它本身部署在你的本地电脑上，但做推理的时候还是得调用云端大模型的 API。这意味着什么？你发给它的每条消息、你让它读取的每个文件、每一次工具调用的结果，都会被发送到云端进行处理。你的私人文件、工作文档、各种账号密码、API 密钥……这些数据实际上都经过了第三方云服务。

对于个人用户来说，这可能还勉强能接受。但对于企业场景、涉及财务数据的场景、包含技术机密的开发场景，这就是一个严重的隐私隐患。更何况，2026 年初开源社区已经出现了针对 OpenClaw 的恶意插件事件（被称为「利爪浩劫」ClawHavoc），有攻击者在 ClawHub 上传了大量伪装成正常工具的恶意技能包，窃取用户的 API 密钥和 SSH 私钥，这进一步凸显了 AI Agent 生态中数据安全问题的严峻性。

事实上，OpenClaw 自身的维护者也曾在社区中发出过警告，提醒用户注意安全风险。网络安全研究机构对 OpenClaw 进行测试后发现，由于该框架需要访问邮箱、日历、消息平台等敏感服务，配置不当或实例暴露会带来严重的安全和隐私风险。此外，Agent 还容易受到提示注入攻击——恶意指令可以被嵌入到数据中，诱导大模型将其当作合法的用户指令来执行。这些问题在国内使用场景中同样存在，尤其是涉及企业内部数据、客户信息、知识产权等领域。

EdgeClaw 就是冲着这个问题来的。 莫潇羽@无忆研习社在深入研究后发现，EdgeClaw 的设计思路非常清晰：不是让你在「隐私安全」和「AI 能力」之间二选一，而是两个都要。公开数据继续享受云端大模型的推理能力，敏感数据留在本地零风险。

二、EdgeClaw 的整体架构：端云协同是怎么回事？

理解 EdgeClaw，关键在于理解「端云协同」这四个字。

传统的 AI Agent 架构中，「端侧」（也就是你的本地设备）长期被忽视——所有数据和任务一股脑涌向云端。EdgeClaw 重新激活了端侧的价值，让本地设备不再只是一个「消息中转站」，而是变成了一个有感知能力、有决策能力的安全守卫。

EdgeClaw 的架构可以用一句话概括：端侧负责感知数据属性（判断敏感度和复杂度），云端负责推理和生成。端侧补云端的盲区（敏感数据不上云），云端补端侧的短板（做不了的复杂任务交给云）。

具体来说，EdgeClaw 在 OpenClaw 的基础上，增加了三个核心组件：

GuardClaw 隐私路由中间件——这是整个系统的大脑，负责自动判断每条消息的敏感程度，然后决定走云端还是本地。
本地推理后端——推荐使用面壁智能的 MiniCPM 系列端侧模型，通过 Ollama 运行，也支持 vLLM、LMStudio、SGLang 等其他兼容 OpenAI API 的推理后端。
双轨记忆与会话管理系统——云端模型和本地模型各自维护独立的记忆和会话历史，确保隐私数据不会通过上下文窗口泄露。

如果用一个类比来理解的话：OpenClaw 是一台发动机，EdgeClaw 是装好了安全系统的整车。发动机的所有能力它都有（20+ IM 平台接入、浏览器操作、文件读写、50+ Skills、子 Agent 系统等等），但多了一套完整的安全防护体系。

项目地址：https://github.com/OpenBMB/EdgeClaw （MIT 协议开源）

从项目时间线来看，EdgeClaw 于 2026 年 2 月 12 日正式开源，随后在 3 月 13 日更新了性价比感知协同功能（自动判断任务复杂度，为云端匹配合适的模型）。项目采用 TypeScript 编写，Fork 自 OpenClaw 主仓库，这意味着 OpenClaw 后续的功能更新，EdgeClaw 也可以相对方便地进行同步合并。

三、GuardClaw 隐私中间件：核心原理深度拆解

GuardClaw 是 EdgeClaw 最核心的创新，也是理解整个项目技术原理的关键。莫潇羽@无忆研习社在这里为大家做一个尽可能详细的拆解。

3.1 三级安全分级机制

GuardClaw 的核心逻辑其实很简单：自动判断每条消息的敏感程度，然后决定走云端还是本地。 每一条用户消息、每一次工具调用、每一段 Agent 输出，都会被实时检测并自动分为三个等级：

S1（安全）：内容不含任何敏感信息，可以直接发给云端大模型处理。比如「写一首春天的诗」「帮我翻译这段英文」这类请求。
S2（敏感）：内容包含一定的个人信息，但经过脱敏处理后可以安全地发给云端。比如消息中包含了电话号码、邮箱地址、家庭住址等——系统会先把这些信息替换成占位符（如 [REDACTED:PHONE]），然后再转发给云端模型。
S3（私密）：内容涉及高度机密信息，完全由本地模型处理，绝不外传。比如你的工资单、SSH 密钥、数据库连接字符串、私钥文件等。

整个过程是全自动的，不需要你手动选择「这个用本地，那个用云端」。当然，如果你什么都不想上云，也可以在配置中把所有请求都路由到本地模型，这就等于是一个纯本地运行的 OpenClaw。

3.2 双检测引擎：一快一准

敏感度的判断依赖两个并行运行的检测引擎，一个快、一个准：

规则检测器（延迟约 0ms） 采用正则匹配和关键词扫描，能够瞬间识别出明确的敏感模式。比如它能识别出：

# 规则检测器能匹配的典型模式
API Key 格式：sk-xxxxxxxxxxxxxxxx
数据库连接串：mysql://user:pass@host:3306/db
PEM 密钥头：-----BEGIN RSA PRIVATE KEY-----
SSH 私钥路径：~/.ssh/id_rsa
AWS 凭证路径：~/.aws/credentials

这个引擎的优势是速度极快，快到几乎无感。但它的局限也很明显——只能识别已知的、有明确格式特征的敏感信息。

本地 LLM 检测器（延迟约 1-2 秒） 使用本地运行的小模型（如 MiniCPM 4.1）做语义理解，能处理更微妙的情况。比如你说「帮我看看工资单有没有问题」——这条消息本身没有任何敏感关键词，但模型能理解「工资单」意味着财务隐私，自动将其标记为 S3 级别。再比如「分析一下我上个月的银行流水」，模型同样能理解其中的隐私含义。

两个引擎并行运行，取最高敏感级别作为最终结果。也就是说，只要有一个引擎认为内容敏感，就按照更高的安全标准来处理。这种「宁可误判、不可漏判」的策略，最大程度地保障了数据安全。

我们通过一个具体的例子来理解双引擎是如何协同工作的。假设用户发送了这样一条消息：「帮我分析一下最近三个月的公司财务报表，看看哪些部门超支了」。规则检测器会首先扫描这条消息——它发现消息中没有手机号、没有 API Key、没有 PEM 密钥头等明确的敏感格式，所以规则检测器的判断结果是 S1（安全）。与此同时，本地 LLM 检测器也在分析这条消息——它理解到「公司财务报表」「部门超支」这些语义意味着涉及企业内部财务数据，属于商业机密范畴，所以给出 S3（私密）的判断。最终系统取两者中的最高级别——S3，将这条请求路由到本地 Guard Agent 处理。整个过程对用户来说是完全透明的，他只需要正常提问，不需要关心后端的路由逻辑。

3.3 S2 数据流：脱敏转发的完整过程

当一条消息被判定为 S2 级别时，EdgeClaw 会执行以下处理流程：

用户消息（含个人信息）
    │
    ▼
本地 LLM 检测 → 判定为 S2
    │
    ▼
本地 LLM 提取个人信息 → 生成 JSON 数组
    │
    ▼
编程替换个人信息 → [REDACTED:PHONE], [REDACTED:ADDRESS]
    │
    ▼
Privacy Proxy（localhost:8403）
    ├── 剥离个人信息标记
    ├── 转发到云端模型
    └── 透传响应（支持 SSE 流式传输）

举个例子，假设你发送了这样一条消息：「帮我给张三打电话，号码是 13800138000，告诉他明天下午两点在北京市朝阳区建国路 88 号见面」。EdgeClaw 会先提取出其中的手机号和地址信息，然后将消息改写为：「帮我给张三打电话，号码是 [REDACTED:PHONE]，告诉他明天下午两点在 [REDACTED:ADDRESS] 见面」，再发给云端模型处理。云端模型会基于脱敏后的内容来理解你的意图并生成回复，但它永远不会看到你的真实手机号和地址。

值得一提的是，这个脱敏过程使用的 Privacy Proxy 运行在本地的 8403 端口上，它会剥离 PII（个人可识别信息）标记后将请求转发到云端，同时支持 SSE（Server-Sent Events）流式传输，确保在脱敏的同时不影响响应速度和流式输出的体验。这个代理是透明的——对于云端模型来说，它接收到的就是一条普通的请求，完全不知道有些信息已经被替换了。

另外一个技术细节是，PII 的提取和替换是分两步完成的：第一步由本地 LLM 识别并提取出所有个人信息实体，输出为 JSON 数组格式（包含实体类型和值）；第二步通过编程方式（非 LLM）进行精确的字符串替换。这种「LLM 负责理解，程序负责执行」的分工方式，既保证了识别的准确性，又保证了替换的可靠性。

3.4 S3 数据流：完全本地处理

当消息被判定为 S3 级别时，处理流程更加简单直接：

用户消息（含私密数据）
    │
    ▼
检测 → 判定为 S3
    │
    ▼
转发到本地 Guard Agent
    ├── 使用本地 LLM（Ollama / vLLM）
    ├── 完整数据可见，全本地推理
    └── 云端历史只写入占位符标记

S3 级别的消息会被完全交给本地运行的 Guard Agent 处理。Guard Agent 使用本地大模型（比如通过 Ollama 运行的 MiniCPM 4.1）进行推理，整个过程完全在你的设备上完成，没有任何数据离开你的机器。同时，云端的会话历史中只会写入一个占位符（类似「🔒 此消息由本地处理」），保持对话的上下文连贯性，但不暴露任何实际内容。

3.5 双轨记忆：云端和本地各看各的

这是 EdgeClaw 设计中一个非常巧妙的细节。AI Agent 不同于简单的一问一答，它有完整的记忆系统——它需要记住你之前说过的话、你的偏好、你的工作上下文。如果不加以隔离，敏感数据就可能通过记忆系统泄露给云端模型。

EdgeClaw 的解决方案是维护两套独立的记忆文件：

~/.openclaw/workspace/
├── MEMORY.md           ← 云端模型看到的（自动脱敏版本）
├── MEMORY-FULL.md      ← 本地模型看到的（完整数据）
│
agents/{id}/sessions/
├── full/               ← 完整历史（含 Guard Agent 交互）
└── clean/              ← 清洁历史（供云端模型使用）

云端模型永远看不到 MEMORY-FULL.md 和 sessions/full/ 目录下的内容。这个隔离是通过 Hook 系统在文件访问层实现的——即使云端模型尝试读取这些文件，也会被拦截。从根本上杜绝了隐私数据通过上下文窗口泄露给云服务的可能性。

EdgeClaw 的官方文档中还给出了两个形式化的安全保证定理，这在开源项目中是比较少见的，体现了团队对安全性的严谨态度：

云端不可见性定理：对于任意被判定为 S3 级别的数据 x，其原始内容在云端完全不可见。用数学表达就是：对所有 x，如果 Detect(x) = S3，则 x 不属于 Cloud(x)。

脱敏完整性定理：对于任意被判定为 S2 级别的数据 x，其云端可见形式中不包含任何原始隐私实体值。即对所有 x，如果 Detect(x) = S2，则从 x 中提取出的每一个隐私实体 (type, value)，其 value 都不出现在 Cloud(x) 中。

这两个定理从理论上保证了 EdgeClaw 的安全性：S3 级数据永远不会离开本地，S2 级数据在离开本地之前必定经过完整的脱敏处理。当然，理论保证的前提是检测引擎能够正确识别所有敏感信息——这也是为什么 EdgeClaw 采用了双引擎并行、取最高敏感级别的策略，尽可能减少漏检的风险。

四、全链路安全防护：10 个 Hook 覆盖完整生命周期

莫潇羽@无忆研习社认为这是 EdgeClaw 设计中最值得关注的部分之一。

AI Agent 的工作不是简单的「收到消息 → 调用模型 → 返回结果」。它有一个完整的执行流程——接收消息、选择模型、构建提示词、调用工具、获取工具结果、写入会话历史、同步记忆……每一个环节都可能涉及敏感数据的流转。

EdgeClaw 不是只在入口做一次检查就完事了，而是在整个 Agent 生命周期中设置了 10 个 Hook（钩子），覆盖了从消息到达到会话结束的每一个关键节点。这里莫潇羽@无忆研习社逐一解释每个 Hook 的作用和触发时机，帮助你建立一个完整的心智模型：

before_model_resolve（模型选择前）：运行路由管线，做出路由决策——这条消息该走云端还是本地？该用哪个模型？
before_prompt_build（提示词构建前）：注入 Guard Prompt 或 S2 标记，确保发给云端的提示词中不包含原始敏感数据。
before_tool_call（工具调用前）：文件访问守卫和子代理守卫——如果 Agent 要读取 ~/.ssh 或 ~/.aws 下的文件，这个 Hook 会拦截并判断是否需要本地处理。这个 Hook 的存在至关重要，因为 AI Agent 在执行任务时经常需要访问文件系统。假设你让 Agent 帮你整理项目配置，它可能会读到 .env 文件中的各种密钥和连接字符串。没有这个 Hook，这些信息会随着工具调用的结果被发送到云端。有了这个 Hook，EdgeClaw 会在工具实际执行之前检查目标路径和操作内容，如果涉及敏感文件，就将整个操作链路切换到本地 Guard Agent。
after_tool_call（工具调用后）：对工具返回的结果进行检测——工具可能读取了一个包含敏感信息的文件，返回结果中可能含有密码或密钥。即使工具调用本身看起来是安全的（比如「读取 config.yaml 文件」），返回的内容中也可能包含敏感信息。这个 Hook 会对每一次工具返回的结果进行二次检测，确保没有敏感数据通过工具调用链路泄露到云端。
tool_result_persist（结果持久化）：双轨会话写入——完整结果写入本地历史，脱敏结果写入云端历史。
before_message_write（消息写入前）：S3 级消息替换为占位符，S2 级消息写入脱敏版本。
session_end（会话结束）：触发记忆同步，确保两套记忆文件（MEMORY.md 和 MEMORY-FULL.md）保持一致但各有侧重。
message_sending（出站消息）：最后一道防线——检测即将发送出去的消息，如果发现敏感数据，进行脱敏或直接取消发送。
before_agent_start（子代理启动前）：当主 Agent 要启动子 Agent 来处理子任务时，这个 Hook 会检查任务内容是否包含敏感信息。
message_received（收到消息）：观察性日志，记录但不干预，用于审计和回溯。

EdgeClaw 通过 Hook 机制自动拦截和路由，无需修改 OpenClaw 的任何业务逻辑代码。这意味着你可以把它当作 OpenClaw 的一个「即插即用」的安全增强层——装上就生效，不用改一行代码。

这种零侵入的设计哲学是 EdgeClaw 的一大亮点。在实际工程中，修改底层框架的代码往往意味着巨大的维护成本——每次上游更新都需要处理冲突，每个自定义修改都需要长期维护。而 EdgeClaw 选择通过标准的插件接口和 Hook 机制来实现所有功能，完全不碰 OpenClaw 的核心代码。这不仅降低了维护成本，也让后续跟进 OpenClaw 的版本更新变得简单得多。

从安全审计的角度来看，这种设计也是有好处的。因为所有的隐私保护逻辑都集中在 extensions/guardclaw/ 这一个目录下，代码量相对集中和可控，审计起来也更加方便。团队中负责安全的成员可以单独审查这部分代码，而不需要理解整个 OpenClaw 的庞大代码库。

五、性价比感知协同：不只是安全，还帮你省资源

除了隐私保护，EdgeClaw 还有一个很实用的功能：性价比感知路由。

在日常使用 AI 编程助手或 AI Agent 的过程中，大部分请求其实都是查文件、看代码、简单问答、格式化文本这类轻量任务。如果每一个请求都用最贵的模型来处理，纯属浪费。EdgeClaw 的性价比感知协同功能会用本地小模型做一个「LLM-as-Judge」（让本地 LLM 充当裁判），自动判断每个请求的复杂度，然后路由到不同级别的模型：

SIMPLE（简单任务）：查询、翻译、格式化、打招呼 → 使用轻量模型
MEDIUM（中等任务）：代码生成、单文件编辑、邮件撰写 → 使用中等模型
COMPLEX（复杂任务）：系统设计、多文件重构、跨文档分析 → 使用高级模型
REASONING（推理任务）：数学证明、形式逻辑、实验设计 → 使用专用推理模型

为了避免重复判断，系统还内置了智能缓存机制——基于 SHA-256 哈希的 Prompt 缓存，TTL 为 5 分钟。相同或高度相似的请求不会重复进行复杂度判断，进一步降低了延迟开销。

为什么用 LLM-as-Judge 来做复杂度判断，而不是用简单的关键词规则？因为关键词规则虽然速度快，但完全不理解语义，误判率非常高。比如「帮我写一个排序算法」和「帮我设计一个分布式排序系统的完整架构」，从关键词角度看都包含「排序」，但复杂度天差地别。而本地小模型（如 MiniCPM 4.1）能够准确理解任务的实际复杂度，并且支持多语言——无论你用中文还是英文下达指令，它都能正确判断。代价是多了一次本地模型调用（约 1-2 秒延迟），但考虑到后续可能节省的云端资源开销，这个投入是值得的。

根据 EdgeClaw 官方文档的描述，在典型的编程助手工作流中，性价比感知路由可以将 60% 到 80% 的请求转发到更经济的模型。这对于长期、高频使用 AI Agent 的个人和团队来说，是一个不可忽视的优化。

安全路由和性价比路由运行在同一个管线中，通过权重和两阶段短路策略协同工作：

用户消息
    │
    ▼
RouterPipeline.run()
    │
    ├── Phase 1: 快速路由器（权重 ≥ 50）并行执行
    │       └── security router → 三级敏感度检测
    │
    ├── 短路判断: 若 Phase 1 发现敏感数据 → 跳过 Phase 2
    │
    └── Phase 2: 慢速路由器（权重 < 50）按需执行
            └── cost-aware router → LLM Judge 任务复杂度分类

设计哲学很清晰：安全优先。安全路由器权重更高、先执行，如果发现敏感数据就直接短路处理，不浪费时间再判断复杂度。只有安全通过（S1）后，才启动性价比感知协同来优化资源分配。

六、本地模型选择：MiniCPM 全系列端侧模型

EdgeClaw 的本地推理推荐使用面壁智能自主研发的 MiniCPM 系列端侧模型。这里莫潇羽@无忆研习社给大家做一个简要的介绍。

MiniCPM 是面壁智能和清华大学联合研发的高效端侧大模型系列，以「小钢炮」著称——参数量小，但性能强悍。目前 EdgeClaw 推荐使用的是 MiniCPM 4.1，它是一个 8B 参数的模型，具备以下特点：

采用 InfLLM v2 稀疏注意力架构，每个 token 只需计算不到 5% 的注意力，显著降低长文本处理开销
在 128K 长文本场景下，相比同级别的 Qwen3-8B 仅需 25% 的缓存存储空间
支持「高效双频换挡」机制：长文本自动用稀疏注意力，短文本自动用稠密注意力
在知识、推理、编程、指令遵循等综合能力方面达到同级别最优水平
可在 Ollama、vLLM、SGLang、llama.cpp、LlamaFactory 等多种框架上部署

对于硬件要求，量化版本通常 8GB 内存就能跑起来。如果你选择更大参数的型号，相应地增加内存即可。

具体到 MiniCPM 4.1 在 EdgeClaw 中的角色，它主要承担两项工作：第一是作为隐私检测的语义引擎，负责理解消息内容中是否包含隐含的隐私信息（这是规则检测器无法覆盖的语义层面的判断）；第二是作为 Guard Agent 的推理后端，当消息被判定为 S3 级别时，由它来完成完整的任务处理。

面壁智能团队在端侧模型领域有着深厚的技术积累。MiniCPM 系列从 2024 年 2 月首次发布以来，已经迭代了多个版本，全平台下载量累计突破千万次。其核心技术路线是「大模型密度定律」（Densing Law）——通过提升模型的知识密度，实现同等参数规模下更强的性能表现。MiniCPM 4.1 在 15 个权威评测基准上取得了同尺寸模型第一的综合成绩，涵盖知识（C-Eval、CMMLU、MMLU）、推理（GSM8K、Math-500）、编程（HumanEval、MBPP）、指令遵循（IFEval）等多个维度。

在模型部署方面，MiniCPM 4.1 的适配范围也非常广泛。除了 Ollama 之外，它还支持在 vLLM、SGLang、llama.cpp、LlamaFactory、XTuner 等多种主流推理和微调框架上运行。在硬件层面，已经完成了对 Intel、高通、联发科（MTK）、华为昇腾等多个主流芯片平台的适配，这意味着在国产化环境下也能顺畅运行。

除了 MiniCPM 4.1 作为基座语言模型，MiniCPM 家族还有多模态版本（MiniCPM-V 4.5，支持图像和视频理解）、全模态版本（MiniCPM-o 4.5，支持语音输入输出）等，你可以根据实际需求和硬件条件选择合适的型号。当然，EdgeClaw 并不强制你使用 MiniCPM——任何兼容 OpenAI API 的本地模型都可以接入，比如 Qwen 系列、Llama 系列等。

七、手把手部署教程：从零开始跑通 EdgeClaw

接下来是实操环节。莫潇羽@无忆研习社带你从零开始，一步步把 EdgeClaw 在本地跑起来。

7.1 环境准备

在开始之前，你需要确认以下基本环境：

操作系统：macOS、Linux 或 Windows（推荐 macOS 或 Linux，因为 Ollama 和 Node.js 在这两个平台上的兼容性更好，社区支持也更完善）
Node.js：22 或更高版本（EdgeClaw 基于 OpenClaw 构建，而 OpenClaw 要求 Node.js 22+）
pnpm：Node.js 的包管理器（如果没有，可以通过 npm install -g pnpm 安装）
Git：用于克隆项目仓库
内存：至少 8GB（运行量化版 MiniCPM 4.1 的最低要求），推荐 16GB 以获得更流畅的体验
硬盘空间：至少 10GB（用于存放模型文件和项目代码，其中模型文件约占 4-5GB）
网络连接：首次安装需要从 GitHub 克隆代码、从 npm 下载依赖包、从 Ollama 模型库下载模型，这些步骤都需要网络。安装完成后，如果你选择纯本地模式，就可以断网运行了

7.2 安装 Ollama（本地推理后端）

Ollama 是 EdgeClaw 推荐的本地推理后端，它能让你用一条命令就跑起各种开源大模型。安装方法如下：

macOS 用户：

brew install ollama

Linux 用户：

curl -fsSL https://ollama.ai/install.sh | sh

Windows 用户：

前往 Ollama 官网（https://ollama.com）下载 Windows 安装包，双击安装即可。安装包大约 1.2GB，安装过程中不允许选择安装位置，默认安装到系统盘。安装完成后，Ollama 会在后台自动启动服务，你可以在系统右下角的任务栏看到 Ollama 的图标。

安装完成后，验证是否安装成功：

ollama --version

如果能看到版本号输出，说明安装成功。

7.3 拉取本地模型

接下来，拉取 EdgeClaw 推荐的 MiniCPM 4.1 模型：

ollama pull openbmb/minicpm4.1

这个命令会从 Ollama 模型库下载 MiniCPM 4.1 的量化版本，文件大小大约 4-5GB，根据你的网络速度，可能需要几分钟到几十分钟不等。

下载完成后，启动 Ollama 服务：

ollama serve

Ollama 默认在 11434 端口启动 API 服务。你可以通过浏览器访问 http://localhost:11434，如果看到「Ollama is running」的提示，说明服务已经在正常运行了。

你可以打开另一个终端窗口，快速测试一下模型是否能正常工作：

ollama run openbmb/minicpm4.1

如果进入了对话模式，能正常和模型聊天，说明本地推理后端已经准备就绪。按 Ctrl+D 或输入 /bye 退出对话模式。

7.4 克隆并构建 EdgeClaw

# 克隆项目
git clone https://github.com/openbmb/edgeclaw.git
cd edgeclaw

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 构建 UI 界面
pnpm ui:build

# 初始化配置
pnpm openclaw onboard --install-daemon

这几步会完成项目代码的下载、依赖安装、编译构建和初始化配置。如果一切顺利，不会有报错信息。

如果在 pnpm install 步骤遇到网络问题（国内用户比较常见），可以尝试配置 npm 镜像源来加速依赖下载：

# 配置国内镜像源
npm config set registry https://registry.npmmirror.com

如果在 pnpm build 阶段报错，首先确认你的 Node.js 版本是否为 22 或更高。可以通过 node --version 命令检查。如果版本过低，建议使用 nvm（Node Version Manager）来安装和管理多个 Node.js 版本：

# 安装 nvm（如果尚未安装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 安装并切换到 Node.js 22
nvm install 22
nvm use 22

7.5 配置 GuardClaw 插件

这是最关键的一步——启用 EdgeClaw 的隐私保护功能。打开项目目录下的 openclaw.json 配置文件，添加 GuardClaw 插件配置：

{
  "plugins": {
    "entries": {
      "GuardClaw": {
        "enabled": true,
        "config": {
          "privacy": {
            "enabled": true,
            "localModel": {
              "enabled": true,
              "provider": "ollama",
              "model": "openbmb/minicpm4.1",
              "endpoint": "http://localhost:11434"
            },
            "guardAgent": {
              "id": "guard",
              "workspace": "~/.openclaw/workspace-guard",
              "model": "ollama/openbmb/minicpm4.1"
            }
          }
        }
      }
    }
  }
}

这段配置告诉 EdgeClaw：启用 GuardClaw 隐私中间件，使用本地 Ollama 运行的 MiniCPM 4.1 模型作为检测引擎，并配置一个专门用于处理 S3 级别任务的 Guard Agent。

7.6 注册 Guard Agent

在同一个 openclaw.json 文件的 agents 部分，注册 Guard Agent：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace-main",
        "subagents": {
          "allowAgents": ["guard"]
        }
      },
      {
        "id": "guard",
        "workspace": "~/.openclaw/workspace-guard",
        "model": "ollama/openbmb/minicpm4.1"
      }
    ]
  }
}

这里定义了两个 Agent：main 是你的主 Agent，负责日常任务处理；guard 是安全守卫 Agent，专门处理 S3 级别的私密数据。main Agent 被配置为允许调用 guard 子 Agent。

7.7 启动 EdgeClaw

一切配置就绪后，启动服务：

pnpm openclaw gateway run

如果在启动日志中看到 GuardClaw 插件加载成功的信息，说明 EdgeClaw 已经正常运行了。此时，它会自动对所有消息进行隐私检测和路由，不需要你做任何额外操作。

7.8 验证隐私保护是否生效

你可以通过以下方式验证 EdgeClaw 的隐私保护是否正常工作：

发送一条包含明确敏感信息的消息（比如包含 API Key 格式的文本），观察日志中是否出现了 S2 或 S3 的检测标记。如果你看到类似「Privacy Level: S3, Action: redirect to local」的日志输出，说明隐私路由正在正常工作。

你也可以做一个更直观的对比测试：先发送一条普通消息（比如「今天天气怎么样」），观察日志中应该显示 S1 级别并直接走云端处理；然后发送一条包含敏感信息的消息（比如「帮我看看这个 SSH 私钥有没有问题」），观察日志中应该显示 S3 级别并切换到本地 Guard Agent 处理。通过这两条消息的对比，你就能直观地看到 EdgeClaw 的隐私路由机制确实在发挥作用。

另外一个验证方法是检查双轨记忆文件。在处理了几条消息之后，分别打开 ~/.openclaw/workspace/MEMORY.md 和 ~/.openclaw/workspace/MEMORY-FULL.md，对比两个文件的内容。你会发现 MEMORY.md 中的敏感信息已经被替换为占位符或完全移除，而 MEMORY-FULL.md 中保留着完整的对话内容。这证明了双轨记忆隔离机制在正常运行。

八、进阶配置：自定义检测规则与路由策略

EdgeClaw 的检测规则和路由策略都是完全可自定义的。这对于有特定安全需求的团队来说非常有用。

8.1 自定义检测规则

你可以在配置文件中自定义关键词、正则模式和工具路径的安全等级：

{
  "privacy": {
    "rules": {
      "keywords": {
        "S2": ["password", "api_key", "token", "secret"],
        "S3": ["ssh", "id_rsa", "private_key", ".pem", "工资", "银行卡"]
      },
      "patterns": {
        "S2": ["(?:mysql|postgres|mongodb)://[^\\s]+"],
        "S3": ["-----BEGIN (?:RSA |EC )?PRIVATE KEY-----"]
      },
      "tools": {
        "S2": {
          "tools": ["exec", "shell"],
          "paths": ["~/secrets"]
        },
        "S3": {
          "tools": ["sudo"],
          "paths": ["~/.ssh", "~/.aws", "~/.gnupg"]
        }
      }
    }
  }
}

这段配置定义了：当消息中出现「password」「api_key」等关键词时标记为 S2；出现「ssh」「private_key」「工资」等关键词时标记为 S3；当检测到数据库连接字符串的正则模式时标记为 S2；当检测到 PEM 私钥头时标记为 S3。同时，对特定工具和文件路径也设置了安全等级——比如访问 ~/.ssh 目录下的任何文件都会被标记为 S3。

8.2 自定义检测器组合

你还可以根据场景灵活配置每个检查点使用哪些检测器：

{
  "privacy": {
    "checkpoints": {
      "onUserMessage": ["ruleDetector", "localModelDetector"],
      "onToolCallProposed": ["ruleDetector"],
      "onToolCallExecuted": ["ruleDetector"]
    }
  }
}

比如在用户消息阶段同时使用规则检测器和本地模型检测器（双引擎并行），但在工具调用阶段只使用规则检测器（因为工具调用的内容通常是结构化的，规则检测已经足够准确，不需

🔒

该内容仅对更高等级社区用户开放
请谨慎解锁时效性强且发布日期较早的文章
单篇解锁后若未显示全文请刷新页面

您当前：游客 · 可见 60% 内容 · 升级至 注册用户 可见 70%

👀

游客

可见 60%

✓ 当前

注册用户

可见 70%

社区精英

可见 100%

社区守护