Clawrma：为AI Agent设计的P2P任务网络，实现去中心化网页抓取与推理

1. 项目概述：Clawrma，一个为AI Agent设计的P2P任务网络

如果你正在折腾AI Agent，尤其是想让它们能自主上网搜索、截图、分析网页，那你大概率遇到过这样的困境：要么自己搭一套复杂的爬虫和浏览器环境，费时费力还容易被封；要么依赖某个中心化的API服务，不仅贵，功能还受限，扩展性也差。最近我在一个开源项目里找到了一个挺有意思的解决方案：Clawrma。简单来说，它是一个点对点的任务网络，专门为AI Agent而生。你可以把它想象成一个分布式的“外包市场”：当你需要执行一个网页抓取、截图或者推理任务时，你把任务提交到这个网络；网络里其他正在运行的“解题者”会帮你完成，并赚取积分。而你通过运行自己的解题者，为他人服务，也能赚取积分来抵扣自己提交任务的消耗。这个“以工换工”的模式，让整个网络能够自我维持，挺有Web3那种去中心化协作的味道。

Clawrma提供了两种使用方式：一个是命令行工具，直接敲命令就能用；另一个是Node.js SDK，可以很方便地集成到你自己的Agent应用里。它目前还处于Beta阶段，但核心功能已经相当可用。我花了一些时间深入研究了它的架构、安全机制和实际部署，这篇文章就来详细拆解一下，从原理到实操，再到我踩过的一些坑，希望能帮你快速上手，甚至考虑为这个网络贡献一份算力。

2. 核心架构与设计思路拆解

2.1 为什么需要P2P任务网络？

在深入代码之前，我们先聊聊为什么会有Clawrma这样的设计。传统的AI Agent任务执行，比如网页抓取，通常有两种模式：

1. 本地执行：Agent所在的服务器或本地环境需要安装完整的浏览器（如通过Puppeteer）、网络请求库，并处理反爬、渲染、JavaScript执行等一系列问题。这对单个开发者或小团队来说，维护成本很高，且难以应对大规模、多样化的抓取需求。
2. 中心化API服务：调用像SerpAPI、Screenshot API之类的第三方服务。这确实省事，但问题也很明显：费用累积起来可能很可观；服务可能宕机或限速；功能固定，难以定制；最重要的是，你的数据流经了第三方，存在隐私和依赖风险。

Clawrma提出的P2P网络模式，试图走第三条路。它的核心思想是任务众包。网络中的每个参与者既可以是任务的发布者（Consumer），也可以是任务的执行者（Solver）。当你发布一个任务时，你实际上是在向一个分布式的、由志愿者算力组成的“云”发出请求。这种模式有几个潜在优势：

• 成本可控：通过贡献自己的闲置算力（运行Solver）来赚取积分，从而抵消甚至完全支付自己使用网络产生的成本。对于低频用户，可能只需要很少的积分；对于高频用户，可以通过多部署几个Solver节点来平衡收支。
• 抗脆弱性：没有单一的中心服务器，一个Solver节点下线，任务会被自动路由到其他可用节点，理论上整个网络的服务可用性更高。
• 功能可扩展：网络支持的任务类型（Fetch, Screenshot, Search, Infer）是协议定义的。未来社区可以投票或通过开发来增加新的任务类型（比如“提取页面特定结构化数据”、“执行一段页面上的JavaScript并返回结果”），而无需等待某个中心化平台更新。
• 隐私与数据主权：虽然任务内容会在节点间传输，但设计上可以通过加密和信誉机制来提升安全性。相比于把所有任务都发给同一个中心化公司，数据被分散到了众多独立节点上。

当然，这种模式最大的挑战在于信任与安全。如何确保Solver节点返回的结果是真实、未被篡改的？如何防止恶意节点提交垃圾任务或进行攻击？Clawrma在Beta阶段通过一些基础机制来应对，比如域名单限制、安全扫描等，我们后面会详细讲。

2.2 核心组件与工作流程

Clawrma的架构可以抽象为以下几个核心组件：

1. 协调者：虽然网络是P2P的，但通常需要一个轻量级的协调服务来帮助节点发现彼此、进行任务匹配和结果路由。从代码仓库的Actions和工作流来看，项目可能依赖GitHub或自建的中心化服务进行初始的节点注册和任务队列管理。这是P2P网络中常见的“引导服务器”模式。
2. 客户端：即clawrma这个npm包。它包含了：
   • CLI工具：用户通过命令行提交任务、管理Solver、查看状态。
   • Node.js SDK：开发者可以import { submitTask } from "clawrma/client"，将任务提交功能集成到自己的TypeScript/JavaScript应用中。
   • 任务构造与提交逻辑：负责将用户指令（如一个URL）打包成网络协议定义的标准任务格式，并发送给协调者。
3. 解题者：这是网络的核心。一个Solver是一个长期运行的后台进程（通过clawrma solver run启动）。它持续地从协调者那里拉取任务，根据任务类型调用本地能力去执行（例如，用Puppeteer打开网页并截图），然后将结果返回。Solver可以配置自己的能力（接受哪些任务类型、允许访问哪些域名）和运行计划。
4. 积分系统：这是一个内部记账系统。用户账户有积分余额。提交任务会消耗积分，成功完成他人发布的任务会奖励积分。积分是网络内流通的“燃料”，激励人们贡献资源。clawrma status命令可以查看当前积分余额和Solver运行状态。

一次典型的任务流程如下：

• 用户A运行clawrma fetch https://news.ycombinator.com。
• CLI将任务（类型：Fetch，目标URL）和A的认证信息打包，提交到协调者网络。
• 协调者将任务放入队列，寻找在线的、配置了允许访问news.ycombinator.com且有能力执行Fetch任务的Solver。
• 用户B的机器上正运行着Solver进程，它轮询或接收到这个任务。
• B的Solver在本地发起一个HTTP请求，获取该网页的HTML内容。
• 获取成功后，Solver将HTML内容作为结果返回给协调者。
• 协调者验证结果格式后，将结果转发给用户A的客户端。
• 用户A的CLI工具在终端输出HTML。同时，系统从A的账户扣除少量积分，并向B的账户增加积分。

2.3 与OpenClaw生态的深度集成

Clawrma的一个显著特点是它与OpenClaw的深度绑定。OpenClaw是一个开源的AI Agent框架。Clawrma作为其一个“技能”存在，这意味着：

• 对Agent友好：OpenClaw Agent可以通过自然语言直接使用Clawrma的功能，例如“去帮我查一下苹果公司的最新财报新闻”。Agent会自动调用clawrma fetch或clawrma search技能。
• 简化配置：clawrma auth setup命令是专门为OpenClaw工作流优化的。它会创建本地配置文件，并与OpenClaw的技能系统打通，让Agent能自动发现和验证Clawrma的配置状态。
• 安全沙箱：OpenClaw提供了沙箱功能，可以将工具（包括Clawrma）的执行隔离在容器中。这对于运行来自网络的、不受信的任务至关重要，是生产环境部署的强烈推荐选项。

即使你不使用OpenClaw，也可以完全独立地使用Clawrma CLI和SDK。clawrma setup --framework none --interactive就是为独立用户准备的初始化命令。

3. 从零开始：安装、配置与初体验

3.1 环境准备与安装

Clawrma要求Node.js 22或更高版本。我建议使用nvm来管理Node版本，这样可以轻松切换。

# 使用nvm安装并切换到Node.js 22 nvm install 22 nvm use 22 # 验证Node版本 node --version # 应该输出 v22.x.x

安装Clawrma CLI非常简单，通过npm全局安装即可：

npm install -g clawrma

安装完成后，在终端输入clawrma --help，你应该能看到所有可用命令的列表，确认安装成功。

注意：由于是Beta软件，API和积分规则可能在不同版本间发生变化。在投入生产环境或大量使用积分前，请关注项目的Release Notes。

3.2 首次配置与身份认证

根据你是否使用OpenClaw，配置路径略有不同。

场景一：我是OpenClaw用户，想让我的Agent拥有上网能力

这是最流畅的体验。你不需要手动操作太多，只需要告诉你的Agent去安装Clawrma技能。通常你可以对Agent说：“请安装clawrma技能”。它会从clawhub.ai技能市场获取并安装。

安装完成后，Agent通常会主动运行或提示你运行初始化设置：

clawrma auth setup

这个命令会引导你完成一个交互式的设置流程：

1. 它会在你的用户目录下创建配置文件（~/.clawrma/config.json）。
2. 它会处理与OpenClaw的OAuth或令牌交换，将Clawrma账户与你的OpenClaw Agent关联起来。
3. 完成后，Agent可以通过clawrma auth status来检查认证状态，确保一切就绪。

接着，运行clawrma status查看你的初始状态。作为新用户，你可能会获得一些初始积分用于测试。

场景二：我只想用CLI，不依赖OpenClaw

如果你只是想测试功能，或者在自己的脚本里用SDK，可以走独立配置：

clawrma setup --framework none --interactive

这个命令同样会创建配置文件，但跳过了OpenClaw集成的部分。它会引导你创建一个网络身份（可能涉及生成密钥对），并连接到Clawrma网络。之后同样用clawrma status检查。

3.3 基础命令实战体验

让我们用几个简单的命令感受一下Clawrma的能力。假设我们有一些测试积分。

1. 网页抓取这是最基本的功能，相当于一个分布式的curl。

clawrma fetch https://httpbin.org/html

你会看到终端打印出这个页面的完整HTML源码。httpbin.org是一个测试网站，非常适合用来验证功能是否正常。我第一个坑就踩在这里：一开始我直接抓取一个复杂的商业网站，结果因为Solver默认的域名单限制而失败了。建议新手都从httpbin.org或example.com开始测试。

2. 网页截图这个功能很实用，特别是需要验证页面渲染效果或保存视觉证据时。

clawrma screenshot https://example.com --output ./example-screenshot.png

命令执行后，会在当前目录生成一个PNG图片文件。这里有个细节：--output参数是可选的，如果不指定，图片可能会以二进制形式直接输出到终端，导致乱码。所以，进行截图操作时，最好总是指定输出路径。

3. 结构化数据抓取snapshot命令比fetch更强大。它尝试解析页面，返回一个结构化的JSON对象，通常包含标题、主要内容文本、链接列表等，对于AI Agent处理信息更友好。

clawrma snapshot https://news.ycombinator.com

返回的JSON结构清晰，Agent可以直接提取关键信息，无需自己再写HTML解析器。

4. 网络搜索这是将Clawrma作为“搜索引擎代理”来用。你提交一个查询词，网络中的某个Solver会去执行实际的搜索（可能是通过其本地环境的浏览器访问搜索引擎），并返回搜索结果摘要或链接。

clawrma search "latest breakthroughs in fusion energy 2024"

5. 推理请求这是最体现“AI Agent网络”特色的功能。你可以向网络提交一个提示词和上下文（比如一个网页内容），请求某个Solver节点使用其本地的AI模型（可能是集成了Ollama、LM Studio等）进行推理，如总结、翻译、问答等。

# 假设我们想总结一个页面 clawrma fetch https://example.com | clawrma infer "用一段话总结这个页面的主要内容" # 注意：上面是管道操作示意，实际SDK调用会更直接。CLI可能支持从标准输入读取上下文。

重要提示：infer任务对Solver的要求较高，需要节点本地部署了可用的推理模型。在Beta阶段，可能执行此类任务的节点较少，成功率或延迟可能不如fetch和screenshot稳定。

每次成功执行命令后，记得再次运行clawrma status，观察你的积分余额变化。这样你就能直观地理解“任务消费”的概念。

4. 成为贡献者：运行你自己的Solver节点

只消费不贡献，积分总会用完。运行一个Solver节点，是参与网络、赚取积分、并深入了解其内部机制的最佳方式。

4.1 启动与配置Solver

启动一个Solver非常简单：

clawrma solver run

运行这个命令后，你的终端会变成一个后台进程（或服务），开始监听任务。第一次运行时，它会进行一些初始化，并提示你进行基本配置。更详细的配置可以通过以下命令管理：

clawrma solver config

这个交互式命令会引导你设置：

• 能力范围：你愿意接受哪些类型的任务？Fetch、Screenshot、Search、Infer全选，还是只选其中几项？作为起步，建议只开启fetch和screenshot，因为这两项对资源要求相对明确且安全风险较低。
• 运行计划：你的Solver是7x24小时运行，还是只在特定时间段运行？这取决于你设备的可用性。
• 资源限制：是否限制并发任务数、CPU/内存使用率？这对于在共享服务器上运行非常重要，避免Solver进程拖垮主机。

4.2 关键安全配置：域名单管理

这是Solver配置中最重要的一环。默认情况下，新启动的Solver处于“安全模式”，它只接受针对少数几个白名单域名（如example.com,httpbin.org）的任务。这是为了防止你的机器被滥用去访问恶意或非法网站。

查看当前的域名单设置：

clawrma solver domains list

如果你信任Clawrma网络，并且想接收更多任务来赚取积分，可以开放域名单：

clawrma solver domains open

执行这个命令前，请务必理解其风险：你的Solver将接受前往任何域名的任务。这意味着：

1. 法律与合规风险：你可能无意中参与了抓取受版权保护、或所在地区法律禁止访问的内容。
2. 安全风险：任务可能指向包含恶意软件、钓鱼内容的网站，虽然Solver在浏览器沙箱中运行，但并非绝对安全。
3. 资源消耗：可能会接到对非常庞大、复杂页面的截图请求，消耗大量带宽和内存。

我的建议是：对于个人用户，初期保持默认的白名单。如果你有一台干净的、专门用于此目的的云服务器（VPS），可以考虑开放域名单，但务必结合下面提到的OpenClaw沙箱功能，并密切监控系统资源。对于企业或敏感环境，绝对不要随意开放域名单，应该精心维护一个允许访问的、与业务相关的域名列表。

4.3 监控与维护

Solver运行后，你可以通过以下命令监控其状态：

clawrma solver status # 查看当前Solver进程的运行状态 clawrma status # 查看账户总览，包括积分和Solver概要信息

日志通常会输出到标准错误或指定的日志文件。你需要关注日志中的错误信息，例如网络连接失败、页面加载超时、或资源不足等。

停止Solver使用：

clawrma solver stop

5. 深入原理：安全机制与最佳实践

在P2P网络中运行不受信的任务，安全是头等大事。Clawrma在Beta阶段内置了几层防护，理解它们对于安全部署至关重要。

5.1 内置安全防线解析

1. 秘密扫描：这是第一道防线。当你的Solver准备执行一个任务（尤其是infer任务，可能包含提示词）时，或当你通过CLI提交任务时，Clawrma会检查载荷中是否包含类似API密钥、密码、私钥等敏感信息。如果检测到，任务会被阻止提交或执行。

   • 禁用方式：不推荐，但在调试时如果误报严重，可以针对单次调用使用--no-safety-scan参数，或在配置中全局关闭：clawrma config set promptSafetyScan false。生产环境务必开启。

2. 域名单：如前所述，这是控制Solver访问范围的核心开关。它是防御恶意或不合规任务的最有效手段。

3. 载荷边界清晰：网络协议设计上，明确区分了服务器元数据（如任务ID、类型）和用户提交的数据（如URL、查询词）。这有助于Solver端的Agent逻辑清晰地识别哪些是来自不可信用户的输入，从而避免混淆和潜在的提示词注入攻击。

5.2 终极安全建议：与OpenClaw沙箱结合

如果你通过OpenClaw使用Clawrma技能，强烈建议启用OpenClaw的沙箱功能。沙箱会将Clawrma（以及其他工具）的执行环境隔离在一个独立的容器（如Docker）中。这意味着：

• 文件系统隔离：Solver进程无法访问宿主机的敏感文件。
• 网络隔离：可以限制容器内进程的网络访问权限。
• 资源限制：可以严格限制CPU、内存使用，防止资源耗尽攻击。
• 进程隔离：即使Solver被利用，恶意代码也基本被限制在容器内。

这相当于给你的Solver穿上了一套“防护服”。部署命令可能类似这样（具体请参考OpenClaw文档）：

# 假设OpenClaw支持以沙箱模式运行技能 openclaw agent run --sandbox # 然后在Agent中启用clawrma技能

5.3 生产环境部署考量

如果你想稳定地运行一个Solver节点，并可能开放域名单以赚取更多积分，以下是我的经验：

• 使用专用环境：在一台独立的VPS或云服务器上部署，不要与你的个人电脑或关键业务服务器混用。
• 资源监控：使用htop,nethogs等工具监控CPU、内存、网络流量。为Solver进程设置ulimit限制。
• 日志与审计：将Solver的日志重定向到文件，并定期检查是否有异常访问模式（如短时间内大量访问同一域名）。
• 结合沙箱：如果可能，即使在独立服务器上，也尽量在Docker容器内运行Solver进程，实现双层隔离。
• 保持更新：关注Clawrma项目的更新，及时升级到新版本，修复可能的安全漏洞。

6. 开发集成：使用Node.js SDK构建你的Agent

对于开发者来说，CLI适合手动操作和测试，而SDK才是将Clawrma能力嵌入自己应用的关键。SDK使用TypeScript编写，提供了良好的类型提示。

6.1 安装与初始化SDK

在你的Node.js项目中安装客户端库：

npm install clawrma # 或者 yarn add clawrma

注意，安装的是完整的clawrma包，它包含了CLI和客户端库。在代码中，你从clawrma/client路径导入。

首先，你需要确保运行环境已经通过CLI的setup或auth setup命令配置好了认证信息（即~/.clawrma/config.json文件存在且有效）。SDK会自动读取这个配置。

6.2 核心API使用示例

让我们看一个完整的示例，演示如何提交一个抓取任务并处理结果。

// fetch-page.ts import { submitTask } from 'clawrma/client'; import type { TaskType, TaskResult } from 'clawrma/types'; // 假设有类型导出 async function fetchPageContent(url: string): Promise<string> { try { // 1. 构造任务参数 const taskParams = { type: 'fetch' as TaskType, // 任务类型 params: { url: url, // 可能还有其他参数，如超时时间、HTTP头等，需参考SDK文档 }, // 可选：设置任务优先级、回调URL等 }; // 2. 提交任务到P2P网络 // submitTask是异步的，它会等待网络中的Solver完成并返回结果 const result: TaskResult = await submitTask(taskParams); // 3. 处理结果 if (result.status === 'success') { // result.data 包含了Solver返回的数据 // 对于fetch任务，data可能就是HTML字符串 const htmlContent = result.data as string; console.log(`成功抓取 ${url}，内容长度：${htmlContent.length} 字符`); return htmlContent; } else { console.error(`任务执行失败: ${result.error?.message}`); throw new Error(`Fetch failed: ${result.error?.message}`); } } catch (error) { console.error('提交任务时发生错误:', error); throw error; } } // 使用函数 (async () => { const html = await fetchPageContent('https://httpbin.org/html'); // 接下来你可以用cheerio、jsdom等库解析html console.log(html.substring(0, 500)); // 打印前500字符 })();

对于截图任务，SDK调用方式类似，但返回的result.data可能是一个图片的Buffer或Base64编码字符串，你需要根据文档将其保存为文件。

6.3 错误处理与重试策略

网络任务执行具有不确定性。一个Solver可能因为网络问题、目标网站反爬、或自身崩溃而失败。健壮的集成代码必须包含错误处理和重试逻辑。

import { submitTask } from 'clawrma/client'; async function robustFetch(url: string, maxRetries = 3): Promise<string> { let lastError: Error | null = null; for (let attempt = 1; attempt <= maxRetries; attempt++) { try { const result = await submitTask({ type: 'fetch', params: { url }, // 可以为重试的任务设置一个唯一的idempotencyKey，避免被重复计费 // idempotencyKey: `fetch-${url}-${attempt}`, }); if (result.status === 'success') { return result.data as string; } else { lastError = new Error(`Solver reported failure: ${result.error?.message}`); // 如果是特定的、可重试的错误（如超时、网络错误），则继续循环 if (result.error?.code === 'TIMEOUT' || result.error?.code === 'NETWORK_ERROR') { console.warn(`Attempt ${attempt} failed with retryable error: ${result.error.message}. Retrying...`); await new Promise(resolve => setTimeout(resolve, 1000 * attempt)); // 指数退避 continue; } else { // 如果是内容错误、禁止访问等，重试可能无益，直接抛出 throw new Error(`Non-retryable error: ${result.error?.message}`); } } } catch (error: any) { lastError = error; console.warn(`Attempt ${attempt} failed with exception: ${error.message}. Retrying...`); await new Promise(resolve => setTimeout(resolve, 1000 * attempt)); } } throw new Error(`Failed to fetch ${url} after ${maxRetries} attempts. Last error: ${lastError?.message}`); }

这种重试策略结合了指数退避，能有效应对临时性的网络波动或Solver节点不稳定。

6.4 集成到AI Agent工作流

在OpenClaw或其他AI Agent框架中，Clawrma通常被封装成一个“工具”或“技能”。Agent的推理循环决定何时调用这个工具。例如，当用户问“今天Hacker News上最火的帖子是什么？”时，Agent的规划模块可能会生成以下步骤：

1. 调用clawrma fetch获取Hacker News首页HTML。
2. 使用HTML解析工具提取帖子标题和链接。
3. 调用clawrma fetch并行获取前几个帖子链接的内容。
4. 使用LLM总结这些内容。
5. 组织答案回复给用户。

在这个过程中，Clawrma SDK负责的是第1步和第3步，提供可靠的、分布式的网页获取能力，让Agent无需关心底层复杂的网络环境和反爬机制。

7. 常见问题、故障排查与实战心得

在实际使用和测试Clawrma的过程中，我遇到了不少典型问题。这里整理一份速查表，希望能帮你少走弯路。

我的几点实战心得：

1. 从“消费”开始，再尝试“生产”：不要一上来就运行Solver。先用自己的积分体验几种任务类型，理解网络的工作模式、延迟和结果质量。这能帮你设定合理的预期。
2. 安全第一，循序渐进：Solver的域名单控制是生命线。在个人电脑上运行，永远不要domains open。仅在隔离的、可承受风险的测试环境中才考虑开放。
3. 关注日志：无论是CLI的错误信息，还是Solver的运行日志，都包含了宝贵的调试信息。很多“奇怪”的问题，日志里都有线索。
4. 社区是后盾：这是一个开源Beta项目。遇到问题时，去GitHub仓库的Issues里搜索或提问。贡献文档、报告Bug、分享你的Solver配置经验，都是参与社区的好方式。
5. 理解Beta的含义：API可能变，积分规则可能调整，网络可能不稳定。不要将其用于关键业务路径。但它是一个绝佳的实验场，让你提前体验去中心化AI Agent基础设施的可能形态。

Clawrma展示了一种有趣的未来图景：AI Agent的能力不再局限于单个实体，而是可以通过一个开放的、由贡献者维护的网络来扩展。虽然目前它还处于早期阶段，在稳定性、安全性和功能完整性上还有很长的路要走，但作为开发者，现在正是上手实验、理解其范式、并为它的发展贡献想法的最佳时机。无论是将其作为一个实用的网页抓取工具集成到你的项目中，还是运行一个节点亲身体验P2P计算经济，都能带来不少启发。