claw-farm：为每个用户部署独立AI智能体的基础设施解决方案

1. 项目概述：为每个用户部署一个独立的AI智能体

如果你正在构建一个需要为每个用户提供专属AI智能体（Agent）的服务，那么你肯定遇到过这个难题：核心的业务逻辑还没开始写，大量的基础设施“脏活累活”就已经让你焦头烂额了。想象一下，你需要为成千上万个用户分别管理独立的运行环境、隔离他们的API密钥、自动处理敏感信息、还要保证每个智能体的记忆持久化且互不干扰。这听起来就像是在盖楼之前，先要自己烧砖、和水泥、打地基，等这些都做完了，可能已经没力气去设计漂亮的户型了。

claw-farm就是为了解决这个痛点而生的。它不是一个AI框架，而是一个基础设施工具包。它的核心哲学是：你只管设计和实现那个聪明的“大脑”（Agent逻辑），而所有繁琐的“管道工程”（部署、隔离、安全、运维）都交给它来处理。简单来说，它让你能像启动一个Web服务一样简单，去启动和管理成千上万个彼此隔离、安全可控的AI智能体实例。

2. 核心设计思路：为什么需要“一用户一智能体”架构？

在深入技术细节之前，我们先聊聊为什么这种架构在今天变得如此重要。传统的AI服务往往是“一对多”的：一个强大的后端智能体服务所有用户。这在很多场景下没问题，但当你的服务需要深度个性化、长期记忆、或者涉及用户隐私数据时，这种架构的弊端就显现出来了。

2.1 传统单体智能体服务的三大痛点

首先，状态与记忆混杂。所有用户的对话历史、偏好数据都堆在同一个智能体的上下文中，不仅容易达到上下文长度限制，更严重的是可能发生数据泄露或逻辑串扰。用户A问“我上周买的股票怎么样？”，智能体可能会错误地引用用户B的投资记录来回答。

其次，安全与隐私的挑战。用户的API密钥、个人身份信息（PII）如果直接暴露给智能体，或者在传递给大语言模型（LLM）的API时未加处理，会带来巨大的合规风险。一个设计不当的提示词（Prompt）可能诱导模型输出其他用户的敏感信息。

最后，运维复杂度爆炸。当你想为某个VIP用户升级智能体版本、调试一个特定问题，或者只是简单地重启服务时，你不得不中断所有用户的服务。更别提进行A/B测试、灰度发布这些现代软件工程的基本操作了，在单体架构下几乎难以实施。

2.2claw-farm的解决方案：隔离即服务

claw-farm提出的“一用户一智能体”模型，本质上是对上述痛点的系统性回应。它的设计目标非常明确：

1. 强隔离：每个用户的智能体运行在完全独立的容器中，拥有自己的网络命名空间、文件系统和进程空间。从底层根除数据混用的可能性。
2. 安全管道：在智能体和外部LLM API之间插入一个可配置的安全代理层。所有进出流量都经过标准化处理，如自动脱敏、密钥代管、内容审计。
3. 标准化生命周期管理：提供统一的命令行工具（CLI）来创建、启动、停止、销毁和升级单个或多个智能体实例，将容器编排的复杂性完全封装。
4. 记忆与配置的分离：将智能体的“人格”（提示词模板、技能配置）和“记忆”（用户对话历史、知识库）解耦。人格可以像代码一样统一管理和分发，而记忆则作为用户数据持久化存储，并可随时从原始数据重建。

这种架构带来的直接好处是，开发者可以将绝大部分精力投入到智能体本身的逻辑创新上，而无需成为Docker、网络安全和分布式系统方面的专家。claw-farm充当了那个可靠的“物业管家”，负责维护好每一间“公寓”（用户智能体）的基础设施。

3. 快速上手：从零部署你的第一个多用户智能体农场

理论说再多，不如动手试一下。我们假设你已经有一个基本的开发环境（macOS/Linux， 或者WSL2下的Windows），并且按照项目要求安装了Bun和Docker。下面我们一步步来搭建一个简单的“宠物顾问”智能体服务，为不同的宠物主人提供专属建议。

3.1 环境准备与项目初始化

首先，克隆仓库并安装依赖。由于项目尚未发布到npm，我们需要从源码运行。

# 1. 克隆项目 git clone https://github.com/PermissionLabs/claw-farm.git cd claw-farm # 2. 使用 Bun 安装依赖（Bun的安装速度在此处是巨大优势） bun install # 3. 为了方便，将 claw-farm 命令添加到你的 shell 环境 # 这里假设你的项目路径是 ~/projects/claw-farm echo 'alias claw-farm="bun run ~/projects/claw-farm/src/index.ts"' >> ~/.zshrc # 或 ~/.bashrc source ~/.zshrc

现在，你可以使用claw-farm命令了。让我们创建一个新的智能体项目，并指定它为多用户模式。

# 初始化一个名为 `pet-advisor` 的多用户智能体项目 claw-farm init pet-advisor --multi

执行这个命令后，你会在当前目录下看到一个名为pet-advisor的新文件夹。这就是你的智能体项目根目录。让我们看看里面有什么：

pet-advisor/ ├── .claw/ # claw-farm 的配置和模板目录（通常无需手动修改） ├── agent/ # **你的智能体逻辑代码放在这里** │ ├── index.ts # 智能体主入口文件 │ └── ... # 其他你需要的文件 ├── .env.example # 环境变量示例文件 ├── docker-compose.yml # 由 claw-farm 生成的容器编排配置 ├── policy.yaml # 安全策略配置文件（非常重要！） └── README.md # 项目说明

注意：--multi标志是关键。它告诉claw-farm这个项目需要支持为不同用户生成多个实例。它会生成相应的Docker Compose模板和网络配置，为多实例隔离做好准备。

3.2 配置LLM提供商与安全策略

智能体需要调用大模型API。我们以Google的Gemini API为例。首先，复制环境变量文件并填入你的API密钥。

cd pet-advisor cp .env.example .env # 使用你喜欢的编辑器打开 .env 文件，例如 vi .env 或 code .

在.env文件中，你需要设置类似如下的内容：

# 你的 Gemini API 密钥 GEMINI_API_KEY=your_actual_gemini_api_key_here # 可选：其他LLM提供商的密钥，如 OpenAI, Anthropic 等 # OPENAI_API_KEY=sk-... # ANTHROPIC_API_KEY=sk-ant-...

接下来，我们看看policy.yaml文件。这个文件定义了安全代理层的行为，是claw-farm安全能力的核心。初始生成的策略文件已经包含了一些安全中间件（Middleware）。

# policy.yaml 示例摘要 proxy: provider: gemini # 指定使用的LLM提供商 pipeline: - name: pii-redactor mode: redact # 模式：redact(替换为占位符), mask(部分隐藏), or remove(完全删除) - name: secret-scanner action: block # 检测到疑似密钥等秘密信息时的操作：block(拦截), log(仅记录), or redact(替换) - name: audit-logger path: ./audit/logs.jsonl # 审计日志路径

这个配置意味着，所有从智能体发往Gemini API的请求，都会先经过pii-redactor（自动识别并处理邮箱、电话等个人信息），再经过secret-scanner（检查是否意外泄露API密钥等），最后所有交互都会被audit-logger记录。从Gemini返回的响应也会经过secret-scanner的检查，防止模型意外输出敏感信息。

实操心得：在开发初期，你可以将secret-scanner的action设为log，以便观察哪些内容被标记，而不会阻塞流程。在生产环境务必设为block或redact。

3.3 编写你的第一个智能体逻辑

现在，打开agent/index.ts文件。这是你智能体的“大脑”。claw-farm默认集成了openclaw或picoclaw作为运行时（Runtime），它们提供了一套与智能体交互的标准化接口。一个最简单的智能体，就是一个能接收输入、调用LLM、并返回输出的函数。

让我们修改它，创建一个简单的宠物顾问：

// agent/index.ts import { Claw } from '@permissionlabs/openclaw'; // 或 picoclaw，取决于初始化时的选择 export default async function agent(claw: Claw) { // 从上下文中获取用户信息。在spawn实例时，我们可以传入用户特定的上下文。 const userName = claw.context.get('userName') || '主人'; const petName = claw.context.get('petName'); const petBreed = claw.context.get('petBreed'); // 构建一个个性化的系统提示词 let systemPrompt = `你是一个专业、友善的宠物顾问。你的任务是帮助宠物主人解决他们的问题。`; if (petName && petBreed) { systemPrompt += ` 你正在与 ${userName} 交流，他/她的宠物是一只名叫 ${petName} 的 ${petBreed}。请在所有回答中体现出你对 ${petName} 的关心。`; } // 设置系统指令 claw.instruction(systemPrompt); // 主循环：等待用户输入，处理，返回响应 while (true) { const userMessage = await claw.listen(); // 这里可以添加你的自定义逻辑，比如查询数据库、调用工具等。 // 但在这个简单例子中，我们直接让LLM回复。 const response = await claw.think(`用户说：${userMessage}`); await claw.say(response); } }

这个智能体会读取创建时传入的上下文（比如宠物名字和品种），并将其融入系统提示词，使得每次交互都更具个性化。

3.4 生成并运行用户专属实例

最激动人心的部分来了：为不同的用户生成独立的智能体实例。我们不需要手动写Docker命令或修改配置。

# 回到项目根目录的上一级（即包含 pet-advisor 文件夹的目录） cd .. # 为用户“alice”生成并启动一个智能体实例，并传入她的宠物信息 claw-farm spawn pet-advisor --user alice --context "userName=Alice" --context "petName=Poppy" --context "petBreed=Maltese" # 再为用户“bob”生成一个实例 claw-farm spawn pet-advisor --user bob --context "userName=Bob" --context "petName=Max" --context "petBreed=Golden Retriever"

执行上述命令后，claw-farm会完成以下工作：

1. 为alice创建一个独立的Docker容器，其容器名、网络、数据卷都带有alice的标识。
2. 将我们通过--context传递的键值对注入到该容器的环境中，智能体代码可以通过claw.context.get()读取。
3. 根据policy.yaml配置，启动安全代理容器，作为该智能体容器与Gemini API之间的网关。
4. 启动智能体容器本身，并运行我们编写的agent/index.ts逻辑。

现在，两个完全隔离的智能体就在后台运行了。你可以查看所有运行中的实例：

claw-farm instances pet-advisor

输出会显示类似这样的信息：

Project: pet-advisor Instances: - alice (RUNNING, URL: http://localhost:18790) - bob (RUNNING, URL: http://localhost:18791)

每个实例会被分配一个不同的本地端口。你可以用curl或浏览器访问这些端点（通常是一个WebSocket或HTTP接口，具体取决于运行时）与智能体交互。

3.5 数据持久化与记忆重建

“一用户一智能体”架构的核心优势之一是独立的持久化记忆。claw-farm默认使用mem0或类似的向量记忆系统。每个用户的对话历史、智能体学到的知识，都会存储在以用户ID命名的独立数据卷中。

这意味着，即使你停止了alice的容器，她的记忆仍然安全地保存在磁盘上。当你再次spawn时，记忆会被自动加载。更强大的是，claw-farm采用了“原始数据+可重建索引”的设计。

# 假设我们更新了智能体的记忆索引逻辑，需要为所有用户重建记忆 claw-farm memory:rebuild pet-advisor --user alice # 或者为所有用户重建 claw-farm memory:rebuild pet-advisor --all

这个命令会读取每个用户存储的原始对话数据（不可变的日志），然后使用最新的索引逻辑重新处理，生成新的记忆向量。这保证了记忆系统的可维护性和可升级性，避免了数据锁死在旧的索引格式中。

4. 深入架构：安全代理层与SDK集成

CLI工具虽然方便，但你可能希望将claw-farm的安全能力集成到自己现有的Node.js/TypeScript后端服务器中。这就是SDK的用武之地。当你初始化项目时使用--proxy-mode none，claw-farm就不会为你启动代理容器，而是让你自己掌控服务器，同时复用其安全模块。

4.1 SDK核心模块解析

claw-farm的SDK将其安全管道中的各个环节解耦成了独立的、可组合的中间件。每个中间件都是一个简单的函数，接收请求/响应对象，并返回可能修改后的新对象。这种设计模式提供了极大的灵活性。

让我们看一个在自定义Express服务器中集成SDK的例子：

// 你的服务器文件，例如 server.ts import express from 'express'; import { createLlmProxy, gemini, piiRedactor, secretScanner, auditLogger } from '@permissionlabs/claw-farm/security'; const app = express(); app.use(express.json()); // 1. 创建LLM代理实例 const { proxy, middleware } = createLlmProxy({ provider: gemini({ apiKey: process.env.GEMINI_API_KEY!, // 可以在这里覆盖Gemini的默认参数，如模型版本、温度等 defaultParams: { temperature: 0.7 } }), pipeline: [ // 2. 构建安全处理管道 piiRedactor({ mode: 'redact', // 将PII替换为[EMAIL], [PHONE]等标签 entities: ['email', 'phone', 'credit-card'], // 指定要检测的实体类型 }), // 3. 自定义中间件：例如，添加用户ID到请求元数据 async (request, context) => { // context 可以包含从请求头/会话中提取的用户信息 request.metadata = { ...request.metadata, userId: context.userId }; return request; }, secretScanner({ action: 'block', // 可以自定义正则表达式来检测你业务中特有的敏感模式 customPatterns: [/my-company-internal-\w{32}/], }), auditLogger({ path: './logs/audit.jsonl', // 可以自定义日志格式，例如脱敏后再记录 formatter: (entry) => JSON.stringify({ timestamp: entry.timestamp, userId: entry.context.userId, // 不记录具体的请求响应体，只记录元数据，以满足更严格的合规要求 action: entry.action, model: entry.request.model, }), }), ], }); // 一个模拟的AI处理端点 app.post('/api/chat', async (req, res) => { try { const userMessage = req.body.message; const userId = req.session.userId; // 假设从会话中获取 // 使用代理发送请求，管道中的中间件会依次执行 const response = await proxy.send({ messages: [{ role: 'user', content: userMessage }], model: 'gemini-2.0-flash', }, { userId }); // 将userId传入context，供中间件使用 res.json({ reply: response.choices[0]?.message?.content }); } catch (error) { // 安全中间件可能会抛出错误（如secretScanner检测到密钥并action为'block'） if (error.name === 'SecretDetectedError') { res.status(400).json({ error: '请求包含敏感信息，已被拦截。' }); } else { res.status(500).json({ error: '处理请求时出错。' }); } } }); app.listen(3000, () => console.log('Server running on port 3000'));

在这个例子中，我们完全掌控了Web服务器，但将最复杂、最容易出错的安全逻辑——PII处理、密钥扫描、审计日志——委托给了claw-farm的SDK。这些模块都经过实战测试，并且与CLI工具使用的代码完全相同，确保了行为的一致性。

4.2 安全管道的工作原理

理解管道（Pipeline）的工作流程对于调试和定制至关重要。当调用proxy.send()时，数据流如下：

1. 请求阶段（Outbound）：你的应用程序构造一个LLM请求对象。
2. 管道处理：该请求对象依次流经pipeline数组中定义的每个中间件。每个中间件都可以读取和修改请求（例如，piiRedactor会修改messages中的文本内容）。
3. 发送至提供商：处理后的请求被发送到真正的LLM API（如Gemini）。
4. 响应阶段（Inbound）：收到LLM的响应。
5. 逆向管道处理：响应对象会反向再次流经同一个pipeline数组（从最后一个中间件到第一个）。这允许中间件在响应阶段也进行操作（例如，secretScanner会检查响应文本中是否包含密钥）。
6. 返回给应用：最终处理后的响应返回给你的代码。

重要提示：中间件的执行顺序很重要。通常，piiRedactor应该放在靠前的位置，确保任何日志记录中间件（如auditLogger）记录的是已经脱敏的数据。secretScanner放在靠后的位置，以便检查最终发出的请求和收到的响应。

5. 生产环境部署与运维考量

将玩具项目变成可服务的产品，还需要考虑部署、监控、升级等运维问题。claw-farm提供了一些工具来简化这些工作。

5.1 生成云部署配置

虽然开发时使用Docker Compose很方便，但在生产环境（如Kubernetes）你可能需要更复杂的配置。claw-farm可以生成一个适配性更强的Docker Compose文件作为起点。

# 生成一个更适合生产环境的 compose 文件 claw-farm cloud:compose docker-compose.prod.yml

生成的docker-compose.prod.yml文件会包含一些生产化配置，例如：

• 指定明确的镜像版本标签，而非latest。
• 配置资源限制（CPU， 内存）。
• 设置更合理的重启策略（restart: unless-stopped）。
• 将数据卷映射到宿主机特定目录或命名卷，便于备份。
• 分离不同服务（代理、智能体、记忆数据库）到不同容器。

你可以基于这个文件进一步修改，以适应你的云平台（如AWS ECS， Google Cloud Run的配置通常需要进一步转换）。

5.2 升级与迁移

智能体逻辑和基础设施都在迭代。claw-farm提供了平滑的升级路径。

升级智能体项目模板：如果你更新了claw-farm本身，或者想将项目升级到新的基础模板，可以使用：

claw-farm upgrade pet-advisor

这个命令会重新生成docker-compose.yml，.claw/目录下的模板文件等，但会保留你的agent/目录和policy.yaml文件（除非使用--force-policy覆盖）。

切换运行时：你可能一开始用了轻量级的picoclaw，后来需要openclaw的更丰富功能。

claw-farm migrate-runtime pet-advisor --to openclaw

此命令会更新项目配置，将底层运行时从picoclaw切换到openclaw。注意：这可能需要你根据新的运行时API调整agent/index.ts中的代码。

5.3 监控与日志

运维的核心是可观测性。claw-farm本身不提供完整的监控套件，但它为集成铺平了道路。

• 容器日志：每个智能体实例作为一个Docker容器，其标准输出和错误日志可以通过docker logs <container_id>或你熟悉的日志收集工具（如Fluentd， Loki）来捕获。这是查看智能体业务逻辑日志的主要方式。
• 审计日志：通过policy.yaml中的audit-logger中间件配置的路径，所有经过安全代理的LLM请求和响应都会被记录。这些结构化的JSONL日志是进行安全审计、用量分析和调试模型问题的宝贵数据源。你需要确保这个日志文件被收集到你的中央日志系统（如ELK， Datadog）。
• 健康检查：你可以在agent/index.ts中实现一个简单的健康检查端点，或者依赖运行时提供的健康检查接口。在Docker Compose或Kubernetes配置中配置healthcheck，以便编排器能感知实例状态。

6. 常见问题与故障排查实录

在实际使用中，你肯定会遇到各种问题。下面是我在开发和测试过程中遇到的一些典型情况及其解决方法。

6.1 容器启动失败

问题：运行claw-farm spawn或claw-farm up后，容器很快退出，状态为Exited (1)。

排查步骤：

1. 查看容器日志：这是最快的方法。首先用claw-farm instances或docker ps -a找到退出的容器ID，然后运行docker logs <container_id>。
2. 常见原因1：环境变量缺失。日志中可能出现GEMINI_API_KEY is not defined。检查你的.env文件是否在项目根目录，变量名是否正确，以及是否已通过source加载（对于CLI模式，.env文件会被自动加载）。
3. 常见原因2：端口冲突。claw-farm会为每个实例分配一个递增的端口（如18789， 18790...）。如果某个端口已被占用，容器会启动失败。你可以通过claw-farm instances查看已占用的端口，或者手动在docker-compose.yml中为特定实例指定端口。
4. 常见原因3：智能体代码语法错误。如果你的agent/index.ts有TypeScript编译错误，容器可能无法启动。建议先在项目目录下运行bun run build（如果配置了）或tsc --noEmit来检查代码。

6.2 安全代理拦截了正常请求

问题：智能体无法收到LLM的回复，或者请求被拒绝，日志显示SecretDetectedError或类似信息。

排查步骤：

1. 检查审计日志：查看audit-logger配置路径下的日志文件。它会详细记录每个被拦截的请求和原因。例如，你可能发现secret-scanner将一段包含类似sk-开头字符串的示例代码误判为API密钥。
2. 调整策略配置：在policy.yaml中，针对开发环境，可以先将secret-scanner的action从block改为log。这样请求不会被拦截，但你仍然能在日志中看到警告，从而确认是否是误报。
3. 自定义模式：如果误报是由于你业务中特定的文本模式引起的，可以在secret-scanner配置中添加allowedPatterns或调整customPatterns，将这些模式加入白名单或更精确地定义黑名单。
4. 检查PII脱敏：有时pii-redactor可能过于激进，将一些非PII但格式类似的文本（如产品序列号）也替换掉了，导致LLM无法理解。可以调整其entities列表，或暂时关闭它以确认问题。

6.3 多用户实例间出现干扰

问题：用户A的数据似乎出现在了用户B的对话中。

排查步骤：

1. 确认隔离性：首先，用docker network ls和docker network inspect <network_name>检查claw-farm为多用户项目创建的网络。每个用户的智能体容器和其对应的代理容器应该在一个独立的、以用户ID命名的网络中，并且不同用户的网络之间不应有连接。
2. 检查数据卷：运行docker volume ls，查看数据卷命名。每个用户的记忆数据卷名称应包含其用户ID。确保没有配置错误导致卷被共享。
3. 审查智能体代码：这是最可能的原因。检查你的agent/index.ts代码，是否使用了全局变量、静态变量来存储状态？例如，如果你在模块级别定义了一个数组来存储对话，那么这个数组将在所有导入该模块的实例间共享。必须确保所有用户状态都通过claw.context或记忆系统（如claw.memory）来存储和读取，这些是claw-farm能保证按用户隔离的。
4. 检查外部依赖：如果你的智能体连接了外部数据库或API，请确保查询时包含了用户ID作为过滤条件。

6.4 性能与资源占用

问题：当用户实例增多时，服务器负载很高。

排查与优化：

1. 资源限制：在生成的docker-compose.yml中，为每个服务（特别是智能体容器）添加资源限制。

   services: agent-${USER}: # ... deploy: resources: limits: cpus: '0.5' memory: 512M reservations: cpus: '0.1' memory: 256M

   这可以防止单个失控的实例拖垮整个主机。
2. 运行时选择：picoclaw运行时比openclaw更轻量，启动更快，内存占用更小。如果你的智能体逻辑不复杂，可以考虑使用picoclaw。
3. 实例调度：对于成百上千的用户，在一台机器上运行所有容器是不现实的。你需要结合claw-farm cloud:compose生成的配置，将其适配到Kubernetes等编排系统，实现跨节点的调度和自动扩缩容。claw-farm负责打包和定义单个实例，而编排系统负责在大规模下管理这些实例的生命周期。
4. 冷启动与预热：容器冷启动会有延迟。对于体验要求高的场景，可以考虑使用守护进程池或基于活跃度的自动spawn/despawn策略，这需要你在业务层进行额外开发。

7. 扩展思路：超越基础聊天

claw-farm解决了基础设施问题，释放了你的创造力。以下是一些可以基于此架构构建的更复杂场景：

场景一：个性化学习助手每个学生一个智能体。智能体持续跟踪学生的学习进度、错题本、兴趣点。通过长期记忆，它能记得学生三个月前在哪个数学概念上遇到困难，并在复习时提供针对性练习。所有学习数据完全隔离，家长和老师可以放心。

场景二：企业级AI客服坐席为每个客服代表配备一个AI副驾驶。智能体学习了该客服负责的产品线知识库、沟通话术和历史工单。当客服与用户交谈时，智能体实时提供话术建议、知识检索和工单填写辅助。不同客服之间的数据和性能表现完全独立，便于管理和考核。

场景三：游戏中的个性化NPC为每个玩家生成一个独特的NPC伙伴。这个NPC记得玩家在游戏世界中的选择、成就和关系，并据此发展出独特的对话和剧情线。claw-farm的隔离性保证了玩家A的剧情绝不会泄露给玩家B，而持久化记忆让NPC在玩家下线数月后依然“记得”他们。

实现这些场景，你只需要专注于设计智能体的决策逻辑、工具调用（如查询数据库、调用游戏引擎API）和记忆索引策略。claw-farm会确保这个强大的、有状态的智能体，能够安全、稳定、可扩展地服务于每一个独立的用户。