基于Cloudflare Workers构建OpenClaw多用户平台：架构设计与部署实践

1. 项目概述：一个为OpenClaw设计的现代化多用户平台

如果你正在寻找一个开源的、能够替代官方OpenClaw WebUI的方案，并且希望它具备企业级的用户管理、数据隔离和现代化界面，那么xh-code-techQX/openclaw-platform这个项目绝对值得你花时间深入研究。我自己在部署和使用OpenClaw的过程中，一直对官方界面相对简单的功能感到不便，尤其是在需要团队协作或者管理多个独立项目时。这个平台的出现，恰好解决了这些痛点。

简单来说，openclaw-platform是一个完整的、前后端分离的多用户平台，它在你本地的OpenClaw服务之上，构建了一层强大的管理和代理层。它的核心价值在于，将单用户的AI助手工具，转变为一个可安全共享、具备完善权限和资源隔离的SaaS化平台。无论你是想在小团队内部安全地共享一个高性能的AI模型服务，还是想为自己的多个项目创建独立、互不干扰的AI工作空间，这个项目都提供了一个近乎“开箱即用”的解决方案。

它的技术栈也相当现代和务实：前端使用React + TypeScript + Tailwind CSS，确保了开发效率和界面美观；后端逻辑则部署在Cloudflare Workers上，利用其全球边缘网络实现低延迟的API代理和业务逻辑处理；用户数据、工作空间配置和上传的文件，则分别通过Cloudflare KV和R2进行存储，实现了无服务器架构下的持久化。整个架构清晰地将认证、代理、业务逻辑和存储解耦，不仅性能出色，扩展性也极强。

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

在决定是否采用一个开源项目时，我习惯先彻底理解它的设计思路和架构，这能帮助我预判未来的维护成本和扩展可能性。openclaw-platform的架构设计体现了清晰的边界划分和关注点分离原则。

2.1 三层架构：前端、边缘代理与后端服务

项目采用了经典的三层架构，但每一层的技术选型都颇具匠心：

1. 前端层：基于Vite构建的React应用。它不直接与后端的OpenClaw服务器通信，而是将所有请求发送到Cloudflare Worker。这样做的好处是，前端开发者完全无需关心后端的网络位置和认证细节，只需要与一个统一的、安全的API网关交互。前端负责呈现工作空间、文件列表、聊天界面等所有用户交互。

2. 边缘代理与业务逻辑层：这是整个平台的大脑，部署在Cloudflare Workers上。它承担了多重角色：

   • API网关：接收所有前端请求，进行统一的认证、限流、CORS处理。
   • 业务路由器：根据请求路径，将请求分发到对应的处理模块（如认证auth.js、工作空间workspace.js、文件files.js）。
   • 反向代理：对于需要调用底层OpenClaw AI能力的请求（如/v1/chat/completions），它会验证用户权限和工作空间后，将请求转发到真正的OpenClaw服务器，并将响应返回给前端。这层代理是实现多用户隔离和安全控制的关键。

3. 后端服务层：即你原本就在运行的OpenClaw服务器。在这个架构中，它退化为一个纯粹的“AI模型计算服务”，只负责接收处理请求并返回AI生成结果。其原有的简单HTTP接口被前面的Worker层封装和增强。

为什么选择Cloudflare Workers？这是设计中的一个关键决策。首先，Workers作为边缘计算服务，能让全球用户以最低延迟访问你的平台。其次，它提供了KV（键值存储）、R2（对象存储）等原生存储服务，与Worker集成度极高，无需自己维护数据库和文件服务器。最后，它的无服务器特性意味着你无需管理服务器，只需为实际的请求量付费，对于中小型应用来说成本可控且运维简单。

2.2 数据隔离的实现机制

“多用户”和“工作空间隔离”是这个平台的核心卖点。它是如何实现的呢？

• 用户级隔离：所有API请求都必须携带有效的JWT令牌。Worker的认证模块会解析令牌，提取用户ID。此后，任何数据操作（查询工作空间、上传文件）都会与这个用户ID绑定。例如，在KV中存储用户工作空间列表时，键名可能是user:workspaces:${userId}，从根源上确保用户只能访问自己的数据。

• 工作空间级隔离：这是更细粒度的隔离。每个用户可以创建多个工作空间（想象成不同的项目或对话线程）。工作空间拥有独立的配置、聊天会话历史和文件存储区。当用户通过前端选择一个工作空间进行聊天时，前端会在请求头中携带工作空间ID。Worker的proxy.js在将请求转发给OpenClaw后端时，会确保该请求的上下文（可能通过特定的HTTP头或参数）限定在此工作空间内，从而避免不同工作空间的对话历史相互污染。

• 文件存储隔离：文件上传到R2时，其存储路径会包含用户ID和工作空间ID，例如files/${userId}/${workspaceId}/${filename}。这样，在提供文件下载链接或列表时，可以精确地根据当前用户和所选工作空间进行过滤。R2本身不提供细粒度的权限控制，但通过这种命名约定和Worker层的逻辑校验，同样实现了安全的隔离。

这种“用户→工作空间→文件”的层级隔离模型，非常贴合实际团队协作的使用场景，既保证了隐私性，又提供了灵活性。

3. 核心功能模块深度解析

了解了整体架构，我们再深入到各个核心功能模块，看看它们具体是如何运作的，以及在实际部署中需要注意哪些细节。

3.1 基于JWT的认证与授权流程

平台的认证系统是标准且安全的JWT方案，但其中一些实现细节值得关注。

1. 注册与登录：用户在前端提交凭证（用户名/密码）。auth.js中的处理逻辑会：

   • 密码加盐哈希：绝不会明文存储密码。它使用如bcrypt的算法，生成一个随机的“盐”，与密码组合后哈希，将哈希值和盐存入KV（例如user:creds:${username}）。即使KV数据泄露，攻击者也无法直接获得原始密码。
   • 生成JWT：登录成功后，使用一个高强度的、保存在Worker秘密环境变量JWT_SECRET中的密钥，生成一个包含用户ID、角色和过期时间的JWT令牌，返回给前端。

2. 令牌的使用与刷新：前端将JWT存储在内存或安全的HttpOnly Cookie中，并在后续所有API请求的Authorization头中携带（格式：Bearer <token>）。Worker的全局security.js中间件会拦截所有请求，验证令牌的有效性和过期时间。

   • 访问令牌：通常有效期较短（如15分钟），用于常规API调用。
   • 刷新令牌：有效期较长（如7天），存储在KV中，仅用于调用/api/auth/refresh端点来获取新的访问令牌，而无需用户重新登录。这种机制在保证安全的同时，提升了用户体验。

实操心得：关于JWT_SECRET项目要求你通过wrangler secret put JWT_SECRET设置密钥。这里有个关键点：这个密钥一旦设置，就无法通过命令行查看。务必在首次部署前，用一个足够长且随机的字符串（例如用openssl rand -base64 32生成）作为密钥，并妥善备份。如果丢失，所有已发行的令牌将失效，用户需要重新登录。同理，ENCRYPTION_KEY用于加密可能存储在KV中的敏感数据，其重要性亦然。

3.2 工作空间管理与会话隔离

工作空间是组织对话的核心单元。其API设计是RESTful的，实现清晰。

• 创建与配置：创建工作时，可以指定名称、绑定的AI模型（如gpt-4）、系统提示词等。这些配置信息会以加密形式存储在KV的workspace:config:${workspaceId}中。加密是为了防止KV内容被直接窥探，增加一层安全防护。

• 会话隔离的实现：这是与原生OpenClaw区别最大的地方。原生服务通常只有一个全局的对话历史。在此平台中，当用户在工作空间A中聊天时，Worker的proxy.js在转发请求给OpenClaw时，会携带一个唯一标识该工作空间会话的标识符（例如X-Workspace-Session-Id: ${workspaceId}）。OpenClaw后端需要具备根据此标识符维护独立会话上下文的能力。这通常意味着需要对OpenClaw的后端代码进行小幅改造或配置，使其支持“会话ID”的概念。这是部署前必须确认的一点。

• 前端状态管理：前端应用需要精心管理当前选中的工作空间ID。通常使用React Context或全局状态管理库（如Zustand），在用户切换工作空间时，更新所有后续API请求的上下文。这确保了聊天界面、文件列表等组件展示的都是正确工作空间下的内容。

3.3 文件上传、存储与分享机制

文件管理功能让AI助手能够处理用户上传的文档、图片等，极大地扩展了其应用场景。

1. 上传流程：

   • 前端将文件通过FormData提交到/api/files/upload，并必须在请求中指定所属的workspaceId。
   • Worker的files.js模块会进行安全校验：检查文件类型（白名单）、大小（限制如10MB）、以及用户是否有权向该工作空间上传文件。
   • 校验通过后，生成一个唯一的文件ID（如UUID），将文件流式上传到Cloudflare R2的对应路径（files/${userId}/${workspaceId}/${fileId}）。
   • 同时，文件的元数据（原始文件名、大小、MIME类型、上传时间、存储路径）会以加密形式存入KV（file:meta:${fileId}），并建立索引（user:files:${userId}列表包含该文件ID）。

2. 下载与分享：

   • 文件下载不直接暴露R2的公共URL，而是通过Worker的/api/files/:id/download端点代理。这样做的好处是，可以在提供文件流之前，再次进行权限校验（验证当前用户是否有权下载该文件）。即使有人获得了文件ID，没有有效的用户令牌也无法下载。
   • “分享”功能在代码中可能体现为生成一个有时效性的、带签名的下载URL（使用R2的预签名URL功能），或者创建一个具有特定访问权限的“分享链接”记录在KV中。这提供了更灵活的文件协作方式。

3. 与AI模型的集成：上传文件后，前端在聊天时，可以引用文件ID。当用户发送一条包含“请分析我刚上传的文档”的消息时，前端或Worker需要有能力将该文件ID解析为实际内容（可能是文本提取），并将其作为上下文的一部分发送给OpenClaw后端。这需要前后端约定好一种消息格式或扩展协议。

3.4 对OpenAI API的兼容性代理

这是平台能无缝对接各种基于OpenAI SDK应用的关键。Worker的proxy.js模块实现了OpenAI API格式的兼容。

• 请求转发与修改：当收到前往/v1/chat/completions的请求时，proxy.js会：

  1. 验证用户令牌和工作空间权限。
  2. 从当前工作空间配置中，获取预设的系统提示词，并将其与用户消息合并，构建出最终发送给OpenClaw后端的请求体。这实现了工作空间级别的“角色预设”。
  3. 将修改后的请求转发到OPENCLAW_BACKEND_URL环境变量所配置的后端地址。
  4. 接收OpenClaw返回的流式或非流式响应，并原样返回给前端。

• 模型列表端点：GET /v1/models端点通常不会直接查询OpenClaw后端（因为OpenClaw可能只模拟一两个模型）。相反，它可能返回一个在Worker中硬编码或配置的模型列表，例如[{"id": "gpt-3.5-turbo", "object": "model"}, {"id": "gpt-4", "object": "model"}]。这样，前端应用如OpenAI Playground或兼容OpenAI的客户端就能正常识别和选择“模型”。

• 流式响应支持：对于聊天补全，保持流式响应（Server-Sent Events）至关重要，以实现打字机效果。proxy.js必须能够正确处理并透传stream=true参数以及分块的响应数据。这要求Worker代码使用fetchAPI并妥善处理响应流。

4. 从零开始的完整部署实操指南

理论讲得再多，不如动手部署一遍。下面是我根据项目文档和实际经验整理的详细部署步骤，包含了许多原文档未提及的细节和避坑点。

4.1 环境准备与前置条件

在开始之前，请确保你的环境满足以下要求，并完成账户配置：

1. 本地开发环境：

   • Node.js 20+：建议使用nvm管理Node版本，确保一致性。
   • Docker & Docker Compose：用于运行OpenClaw后端服务。确保Docker守护进程正在运行。
   • Git：用于克隆代码仓库。
   • 一个可用的OpenAI或Claude API密钥：这是OpenClaw后端实际调用的AI服务。

2. Cloudflare账户配置：

   • 注册并登录Cloudflare仪表板。
   • 在“Workers & Pages”部分，你需要创建：
     • 一个Worker：用于部署业务逻辑。
     • 三个KV命名空间：分别用于存储用户数据、工作空间数据和会话数据。记下它们的ID。
     • 一个R2存储桶：用于存储用户上传的文件。注意，R2需要单独启用，可能涉及支付方式验证（虽然有免费额度）。
   • 在“Workers & Pages” -> “Overview”页面，获取你的Account ID和API Token（需要创建具有“Workers KV存储编辑”、“Workers R2存储编辑”、“Workers脚本编辑”权限的令牌）。

4.2 部署OpenClaw后端服务

这是整个平台的AI能力基石。我们使用Docker Compose来快速部署。

# 1. 克隆项目仓库 git clone https://github.com/xh-code-techQX/openclaw-platform.git cd openclaw-platform # 2. 进入服务器目录并配置环境变量 cd openclaw-server cp .env.example .env # 使用你喜欢的编辑器（如vim, nano, code）编辑 .env 文件

编辑openclaw-server/.env文件，以下是最关键的几个配置项及其解释：

# OpenClaw网关令牌，用于Worker与后端之间的认证。需与Worker环境变量中的OPENCLAW_GATEWAY_TOKEN保持一致。 # 建议使用 `openssl rand -base64 32` 生成一个强随机字符串。 OPENCLAW_GATEWAY_TOKEN=your_super_strong_gateway_token_here # OpenClaw网关密码，用于WebSocket连接认证（如果后端启用）。 OPENCLAW_GATEWAY_PASSWORD=your_password # 你的OpenAI API密钥。OpenClaw会使用它来调用GPT模型。 OPENAI_API_KEY=sk-your-actual-openai-api-key # （可选）你的Anthropic Claude API密钥。如果你希望使用Claude模型，请配置此项。 ANTHROPIC_API_KEY=sk-ant-your-actual-claude-api-key # （重要）后端服务监听的端口。确保18789端口在主机上未被占用。 PORT=18789

注意事项：网络与防火墙默认的docker-compose.yml会将容器的18789端口映射到主机的127.0.0.1:18789（即仅本地访问）。这是正确的安全做法，因为你的后端服务不应该直接暴露在公网，只允许本地的Cloudflare Worker（通过你后续配置的OPENCLAW_BACKEND_URL）访问。如果你的Worker将部署在Cloudflare全球网络（而非本地开发），那么后端服务需要部署在一个Cloudflare能访问到的服务器上（如你的家庭服务器、VPS），并确保其防火墙允许来自Cloudflare IP段的入站连接（或通过Cloudflare Tunnel建立安全连接）。对于本地开发测试，127.0.0.1即可。

# 3. 启动OpenClaw服务 docker-compose up -d # 使用 `docker-compose logs -f` 查看启动日志，确认服务无报错运行。 # 访问 http://localhost:18789 应该能看到OpenClaw的基础信息或API文档页面。

4.3 配置与部署Cloudflare Worker

Worker是平台的核心，配置步骤稍多，请耐心操作。

# 1. 进入Worker目录并安装依赖 cd ../cloudflare-worker npm install # 2. 配置 wrangler.toml # 编辑 wrangler.toml 文件，填入你在Cloudflare仪表板获取的 Account ID account_id = "your_cloudflare_account_id"

接下来，你需要绑定之前创建的KV命名空间和R2存储桶。在wrangler.toml中找到kv_namespaces和r2_buckets部分，进行如下配置：

# wrangler.toml 示例片段 name = "openclaw-platform-worker" main = "src/index.js" compatibility_date = "2024-03-01" kv_namespaces = [ { binding = "USER_KV", id = "your_user_kv_namespace_id", preview_id = "same_id_for_preview" }, { binding = "WORKSPACE_KV", id = "your_workspace_kv_namespace_id", preview_id = "same_id_for_preview" }, { binding = "SESSION_KV", id = "your_session_kv_namespace_id", preview_id = "same_id_for_preview" } ] r2_buckets = [ { binding = "OPENCLAW_FILES", bucket_name = "openclaw-files", preview_bucket_name = "openclaw-files" } ]

实操心得：关于Binding名称配置文件中的binding名称（如USER_KV）必须与Worker代码src/index.js或相关模块中引用的变量名完全一致。代码中会通过env.USER_KV来访问这个KV存储。如果名称不匹配，运行时会导致undefined错误。

现在，设置Worker运行所需的关键秘密（环境变量）。这些值不会写在代码或配置文件中，而是通过wrangler secret put命令安全地注入。

# 3. 设置秘密环境变量 # 首先登录Wrangler（如果你还没登录过） npx wrangler login # 按照提示完成浏览器授权。 # 设置JWT签名密钥 npx wrangler secret put JWT_SECRET # 在提示符后，粘贴一个强随机字符串（如用 openssl rand -base64 32 生成的）。 # 设置数据加密密钥（用于加密KV中存储的敏感数据） npx wrangler secret put ENCRYPTION_KEY # 同样粘贴一个强随机字符串，建议与JWT_SECRET不同。 # 设置后端OpenClaw服务的URL npx wrangler secret put OPENCLAW_BACKEND_URL # 输入你的OpenClaw后端地址。如果是本地开发，使用 `http://localhost:18789`。 # 如果是远程服务器，使用 `http://your-server-ip:18789` 或 `https://your-domain.com`。 # 设置网关令牌，必须与 openclaw-server/.env 中的 OPENCLAW_GATEWAY_TOKEN 完全一致。 npx wrangler secret put OPENCLAW_GATEWAY_TOKEN

最后，进行部署：

# 4. 部署Worker到Cloudflare npx wrangler deploy

部署成功后，命令行会输出你的Worker域名，格式如https://openclaw-platform-worker.your-subdomain.workers.dev。记下这个地址，下一步配置前端时需要用到。

4.4 构建与部署前端Web应用

前端是用户直接交互的界面，我们将它部署到Cloudflare Pages，享受全球加速。

# 1. 进入前端目录并安装依赖 cd ../web-frontend npm install # 2. 配置环境变量 # 创建 .env 文件，指定前端要连接的API地址（即你刚部署的Worker地址） echo "VITE_API_URL=https://openclaw-platform-worker.your-subdomain.workers.dev" > .env.production # 对于开发环境，可以创建 .env.development，内容可能是 `VITE_API_URL=http://localhost:8787`（如果你在本地运行wrangler dev）。 # 3. 构建生产版本 npm run build # 构建产物会生成在 `dist` 目录下。 # 4. 部署到Cloudflare Pages # 首先，在Cloudflare仪表板的“Workers & Pages”中创建一个新的Pages项目。 # 然后，在项目根目录执行： npx wrangler pages deploy dist --project-name=your-pages-project-name

部署完成后，Cloudflare Pages会给你一个预览域名，例如https://your-pages-project-name.pages.dev。访问这个地址，你应该能看到OpenClaw Platform的登录界面。

4.5 本地开发与调试流程

在开发新功能或调试时，你需要在本地运行所有三个部分。

1. 启动OpenClaw后端：在openclaw-server目录下，docker-compose up。
2. 启动Worker开发服务器：在cloudflare-worker目录下，npx wrangler dev。这会启动一个本地Worker实例，通常运行在http://localhost:8787。它会使用你之前设置的秘密环境变量（如果已设置），并连接到本地的KV/R2模拟器。
3. 启动前端开发服务器：在web-frontend目录下，确保.env.development文件中的VITE_API_URL指向本地Worker（http://localhost:8787），然后运行npm run dev。前端开发服务器通常运行在http://localhost:5173。

现在，访问http://localhost:5173，你就可以在本地进行完整的开发、测试和调试了。前端的请求会发送到本地Worker，Worker再代理到本地的OpenClaw后端。

5. 高级配置、安全加固与故障排查

平台部署起来只是第一步，要让其稳定、安全地运行，还需要进行一些高级配置和了解常见的排错方法。

5.1 关键安全配置详解

安全无小事，尤其是涉及用户数据和API密钥的平台。

• CORS配置：在cloudflare-worker/src/security.js中，确保corsHeaders只允许你信任的前端域名。在生产环境中，不要使用*。

  // 生产环境配置示例 const corsHeaders = { 'Access-Control-Allow-Origin': 'https://your-pages-project-name.pages.dev', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Workspace-Id', 'Access-Control-Allow-Credentials': 'true', // 如果需要传递Cookie };

• 速率限制：rateLimiter.js模块保护你的服务免受滥用。你需要根据实际情况调整LIMIT和WINDOW（时间窗口）。例如，对于登录接口，限制可以更严格（如每分钟5次），对于聊天接口，可以适当放宽但设置每日总量限制。考虑对不同的用户角色（如免费用户、付费用户）实施不同的限流策略。

• 秘密管理：永远不要将JWT_SECRET、ENCRYPTION_KEY、OPENAI_API_KEY等硬编码在代码或提交到仓库。务必使用wrangler secret put命令管理。对于团队协作，可以考虑使用Cloudflare的“环境变量”功能（非秘密）来存储非敏感的配置，如功能开关。

• OpenClaw后端安全：确保你的OpenClaw服务器（OPENCLAW_BACKEND_URL）不直接暴露在公网，或者至少通过防火墙/IP白名单（只允许Cloudflare的IP段或你的Worker服务IP）进行保护。因为OPENCLAW_GATEWAY_TOKEN是保护它的唯一屏障。

5.2 性能优化与扩展考量

随着用户量增长，你可能需要考虑以下方面：

• Worker全局变量与连接复用：在Worker的全局作用域中初始化数据库连接池或HTTP客户端，并在多个请求间复用，可以显著降低延迟。例如，可以创建一个全局的、指向OpenClaw后端的fetch连接池。

• R2性能与成本：R2的存储成本很低，但请求次数和流量会产生费用。对于频繁访问的图片或文件，可以结合Cloudflare的CDN缓存，在Worker中设置适当的Cache-Control响应头。对于大文件上传，可以考虑使用R2的分片上传API以提高可靠性。

• KV数据模型优化：KV适合存储小型、频繁读取的数据。避免在单个KV键下存储过大的值（如巨大的JSON数组）。对于用户的所有文件元数据列表，可以考虑分页存储，或使用一个索引键配合多个数据键的模式。

• 无状态与有状态：Worker本质上是无状态的。所有与会话相关的状态（如当前对话历史）都必须存储在KV或R2中。在设计时，要明确区分哪些数据是请求级别的（放在内存），哪些是需要持久化的（放入存储）。

5.3 常见问题与故障排查实录

以下是我在部署和测试过程中遇到的一些典型问题及解决方法：

1. 问题：前端部署后，访问页面出现空白或“Failed to fetch”错误。

   • 排查：打开浏览器开发者工具的“网络”选项卡，查看首个API请求（如/api/auth/me）的响应。
   • 可能原因A：CORS错误。响应头中没有正确的Access-Control-Allow-Origin。检查Worker的security.js中间件，确保其正确运行并包含了前端页面的域名。
   • 可能原因B：Worker返回5xx错误。查看Worker的日志。在Cloudflare仪表板的Workers详情页，有“日志”标签页。更简单的方式是在本地运行wrangler dev并查看控制台输出，通常错误信息更详细。
   • 可能原因C：前端API地址配置错误。确认web-frontend/.env.production文件中的VITE_API_URL是否完全等于你部署的Worker域名（包括https://）。

2. 问题：用户登录成功，但创建或进入工作空间后，聊天不返回任何内容。

   • 排查：查看Worker日志和OpenClaw后端日志。
   • 可能原因A：OPENCLAW_BACKEND_URL配置错误或后端服务不可达。在Worker中，尝试用一个简单的测试路由fetch一下这个URL，看是否能连通。确保后端服务的防火墙和端口配置正确。
   • 可能原因B：OPENCLAW_GATEWAY_TOKEN不匹配。Worker中设置的OPENCLAW_GATEWAY_TOKEN秘密必须与openclaw-server/.env文件中的OPENCLAW_GATEWAY_TOKEN值一字不差。检查是否有空格或换行符。
   • 可能原因C：OpenClaw后端服务本身有问题。直接使用curl或Postman向http://your-backend:18789/v1/chat/completions发送一个带正确Authorization头（Bearer token为网关令牌）的请求，看是否正常响应。

3. 问题：文件上传失败，提示“413 Request Entity Too Large”或权限错误。

   • 排查：检查R2存储桶的配置和Worker代码中的文件大小限制。
   • 可能原因A：Worker到R2的权限问题。确保wrangler.toml中R2的binding名称正确，且Worker拥有该存储桶的读写权限（通常通过API Token绑定实现，wrangler deploy已处理）。
   • 可能原因B：文件大小超过限制。在files.js的handleUpload函数中，查找对request.headers.get('Content-Length')的判断逻辑，或对流式读取大小的限制。默认限制可能较小，需要根据需求调整。
   • 可能原因C：前端未正确传递workspaceId。检查前端上传组件，确保在FormData或请求头中包含了当前有效的工作空间ID。

4. 问题：在本地开发时，Worker (wrangler dev) 无法连接到本地的OpenClaw服务。

   • 排查：这是一个常见的网络问题。
   • 解决方案：确保OPENCLAW_BACKEND_URL秘密在开发环境下指向http://localhost:18789。同时，当你运行wrangler dev时，它默认在一个独立的网络命名空间中运行。你可能需要指定--host参数或确保Docker容器将端口暴露在主机的所有接口上（0.0.0.0:18789），而不仅仅是127.0.0.1。最简单的办法是，在docker-compose.yml中，将端口映射改为"18789:18789"（不指定IP），然后OPENCLAW_BACKEND_URL设置为http://host.docker.internal:18789（如果Worker在Docker内）或http://localhost:18789（如果Worker直接跑在主机）。

这个平台项目结构清晰，文档也相对完善，但真正部署时，网络配置、环境变量和权限这三块是最容易出错的。我的经验是，按照“后端 -> Worker -> 前端”的顺序，每一步都通过简单的HTTP请求（如curl）验证服务是否正常响应，能快速定位问题所在。一旦跑通，它提供的多用户、隔离式AI助手体验，远比直接使用原版OpenClaw要强大和便捷得多。