Cloudflare Computer 技术解析：持久 Workspace、执行后端与 Agent 集成

Cloudflare Computer

AI 参与说明（Agent：Codex）：本文由 Codex 根据 Cloudflare Computer 公开仓库、Cloudflare Durable Objects、Dynamic Workers、Agents 与 Sandbox SDK 官方资料辅助整理，重点核对概念、公开 API、执行后端和 Agent 集成边界。初版资料核验于 2026-08-12。

DeepWiki：cloudflare/computer

资料修订（2026-10-20，Agent：Codex）：依据当前仓库更新组件成熟度、Container 同步语义与 Agent tools 配置。API 与部署方式以项目锁定版本及文末一手资料为准。

资料修订（2026-11-01，Agent：Cursor）：按 b681446 补上 Worker JavaScript 源码模块可以使用 ws:* 名字。未运行该 backend。模型 grok-4.7-high-fast，提供方 xAI，执行入口 Cursor Cloud。reasoning effort 未作为独立字段取得运行记录。

先说结论

Cloudflare Computer 不是一台传统虚拟机，也不是 Cloudflare Sandbox SDK 的替代品。它是一个面向 Agent 的 Durable Workspace：把文件系统的权威状态保存在 Durable Object 的 SQLite 中，再通过统一的 workspace.runtime.exec() 把同一份文件交给不同执行后端。

它最有价值的三个特征是：

• Agent 的工作目录可以跨 Durable Object restart 和 eviction 保留，不依赖活跃 Container 的临时磁盘。
• 文件 API、Git、Agent tools 与执行后端围绕同一个 Workspace 组合，不必为每种 runtime 建立独立文件状态。
• 可以先只接入持久文件系统，再按需求增加 Worker Shell、Worker JavaScript 或完整 Linux Container。

截至 2026-10-20，官方按组件声明成熟度：Workspace、文件系统、WorkerJavaScriptBackend、Agent tools 与 Git 为 stable；ContainerBackend、computerd、WorkerShellBackend 和容器同步协议仍为 experimental，LegacyContainerBackend 已 deprecated。顶层包适合生产不代表所有后端都适合生产，采用时应按所用组件检查状态。当前状态表

1. 核心概念

1.1 Workspace

Workspace 是 Computer 的核心 facade，主要包含：

Workspace 可以完全不配置执行后端。此时它仍是一个有用的持久虚拟文件系统，适合保存 Agent 的草稿、计划、代码片段和小型生成物。

1.2 Durable Object SQLite 是权威状态

Computer 把 Workspace 的权威文件状态放在拥有它的 Durable Object SQLite 中。Durable Object restart 或 eviction 会丢失内存状态，但不会丢失已经提交的 SQLite 数据。

这与“把文件写进 Container 磁盘”有本质区别：Cloudflare Sandbox 的活跃 Container 停止后，未持久化的文件和进程会消失；Computer 则把 Container 看作可更换的执行投影，Workspace 才是长期状态。

一个自然的建模方式是“一条 Agent session 或一个用户 workspace 对应一个 Durable Object”。不要把所有租户的工作目录放进全局单例对象；单个 Durable Object 天然是单线程协调单元，也会成为该 workspace 的容量与吞吐边界。Durable Objects Rules

1.3 Execution Backend

workspace.runtime.exec(source, { backend }) 是统一入口，但 source 的语义由后端决定：

一个 Workspace 可以注册多个 backend。backend 按需连接，调用者也可以为每次执行显式选择 backend。

Worker JavaScript 把宿主提供的库放在 ws:* 说明符下。b681446 起，源码模块也可以使用同样的简单名字，模型说明里把它写成宿主提供的库。宿主模块只导出函数；要向 isolate 里的代码提供对象，宿主把自己的函数模块包进一份源码模块，例如 ws:weather 的源码 import ws:weather-host。这类源码模块放在模块目录里，不和调用方的 Workspace 文件放在一起，也不能 import Workspace 文件。本文没有运行 Worker JavaScript backend。Source modules

1.4 computerd 与 FUSE

Container backend 会在 Container 内运行 computerd。它通过 FUSE 将容器侧文件状态挂载为真实目录，再经 capnweb RPC 与 Durable Object 同步。Container 持有独立文件镜像，并不是每次文件读写都直接访问 DO。

默认命令执行以 push → spawn → events/result → pull 建立同步边界。完整消费 run.result() 或事件流后，后置 pull 才完成；命令可能成功而同步仍为 pending，调用方需要检查同步状态。computerd 不自行运行持续后台同步循环，因此常驻浏览器、桌面或服务在命令之外写入的文件，需要明确安排同步时机。Command synchronization、computerd

这种设计让 node、python、npm 等普通程序可以像访问本地文件一样访问 Workspace，但同步和内容寻址会产生开销。官方基准显示，它更适合 Agent 规模的小型工作区，而不是大型 monorepo、巨型依赖树或高吞吐顺序 I/O。Computer Performance

2. Computer 与其他 Cloudflare runtime 的区别

flowchart TD
    request["User / Agent request"] --> worker["Worker：authentication、authorization、quota"]
    worker --> agent["Agent Durable Object"]
    agent --> workspace["Computer Workspace<br/>authoritative VFS in DO SQLite"]
    workspace --> files["workspace.fs / git / tools"]
    workspace --> runtime["workspace.runtime.exec()"]
    runtime --> shell["Dynamic Worker<br/>Worker Shell / JavaScript"]
    runtime --> container["Cloudflare Container<br/>computerd + FUSE"]
    worker --> sandbox["Independent Sandbox capability<br/>processes、preview、terminal、code interpreter"]

可以用下面的判断区分它们：

• Durable Objects 提供对象身份、顺序协调、私有 SQLite、Alarm 与 WebSocket；Computer 建立在这层之上。
• Dynamic Workers 动态加载 Worker code，适合低延迟、受控 binding 与轻量隔离执行；Computer 的两个 Worker backend 使用这类能力。
• Containers 提供完整 Linux 进程环境；Computer 的 Container backend 用它运行 computerd 和命令。
• Sandbox SDK 提供成熟的命令、文件、process、session、terminal、preview、backup 和 storage API，适合通用不可信代码执行环境。Sandbox SDK
• Computer 关注 Agent 的持久工作目录，以及同一文件状态在多个执行后端之间的可移植性。

如果产品只需要执行一次 Python 或启动一个 preview server，优先使用 Sandbox SDK。如果产品需要一个与 Agent Durable Object 同生命周期、可跨轮次保存的小型工作目录，Computer 才具有独特价值。

3. 最小使用方式：只启用持久文件系统

安装当前项目锁定的版本：

npm install --save-exact @cloudflare/computer

Worker 需要 nodejs_compat。以下示例不配置执行后端，因此不需要 Worker Loader：

import { DurableObject } from "cloudflare:workers";
import { getWorkspace, withWorkspace } from "@cloudflare/computer";

export class WorkspaceAgent extends withWorkspace(
  class extends DurableObject<Env> {},
  (self) => ({ storage: self.ctx.storage }),
) {}

export default {
  async fetch(_request: Request, env: Env): Promise<Response> {
    const id = env.WORKSPACE_AGENT.idFromName("demo-workspace");

    using workspace = await getWorkspace(env.WORKSPACE_AGENT.get(id));

    await workspace.fs.mkdir("/notes", { recursive: true });
    await workspace.fs.writeFile(
      "/notes/plan.md",
      "# Plan\n\n- Validate the workspace lifecycle.\n",
    );

    const content = await workspace.fs.readFile("/notes/plan.md", "utf8");
    return new Response(content, {
      headers: { "content-type": "text/markdown; charset=utf-8" },
    });
  },
} satisfies ExportedHandler<Env>;

Wrangler 需要 Durable Object binding 和 SQLite class：

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-12",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [
      {
        "name": "WORKSPACE_AGENT",
        "class_name": "WorkspaceAgent"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["WorkspaceAgent"]
    }
  ]
}

跨 Worker → Durable Object RPC 使用 getWorkspace() 时，需要释放远端 stub。官方示例使用 using 管理 Workspace 和 exec handle；长生命周期 isolate 若不断创建但不释放 stub，会在对端积累资源。

4. 增加 Worker Shell backend

Worker Shell 适合低成本文本处理，不提供完整 Linux binary，也默认没有公开网络。配置时增加 experimental flag 与 Worker Loader binding：

{
  "compatibility_flags": ["nodejs_compat", "experimental"],
  "worker_loaders": [{ "binding": "LOADER" }]
}

然后给 Workspace 注册 backend：

import { Workspace } from "@cloudflare/computer";
import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";

const workspace = new Workspace({
  storage: this.ctx.storage,
  backends: [
    new WorkerShellBackend({
      id: "shell",
      loader: this.env.LOADER,
      workspace: {
        binding: "WORKSPACE_AGENT",
        id: this.ctx.id.toString(),
      },
      ctx: this.ctx,
    }),
  ],
});

await workspace.fs.writeFile("/notes/todo.txt", "TODO: verify cleanup\n");

using run = await workspace.runtime.exec(
  "grep -R TODO /notes",
  { backend: "shell", encoding: "utf8" },
);

const result = await run.result();
console.log(result.stdout, result.exitCode);

Worker Shell 支持的是 just-bash 与显式配置的命令组，不是完整 Linux。需要原生 Node.js、Python 原生依赖、package manager 或其他 native binary 时，应选择 Container 或 Sandbox；不能因为命令名称相同就假设实现和 Linux 完全一致。

5. 作为 Agent tools 使用

@cloudflare/computer/tools 可以为 AI SDK 或 Agent harness 生成 read、write、edit、ls 和可选的 exec tools：

import { createAITools } from "@cloudflare/computer/tools";

const workspaceTools = createAITools({
  workspace,
  read: {
    maxBytes: 32 * 1024,
    maxLines: 800,
  },
  exec: {
    shell: {
      description: "Use just-bash for supported file and text operations.",
    },
  },
});

在真实 Agent 中，不应直接把返回的全部 tools 无条件暴露给模型。至少还要增加：

• 用户和协作者 capability 校验；
• 允许访问的 path prefix；
• 单文件、总 workspace、文件数和 tool output 上限；
• 每个 run 的 tool-call 次数、执行时间和并发限制；
• destructive write/delete/exec 的审批或策略；
• prompt injection 与敏感内容防护；
• 稳定、脱敏的错误和审计事件。

接入 Think 或其他 Agent harness 时，可参考当前 Think 示例，把 Workspace 工具接入其允许的工具集合。让既有 Agent lifecycle、run、history 和 realtime protocol 继续管理任务，Computer 负责工作区与执行，避免重复维护两套任务状态。

6. 在统一 API + Chat 产品中的集成方式

假设现有系统已经有：

• 一个统一 API Worker；
• 一个基于 Durable Object 的持久 Agent；
• 一个只通过公开 REST/WebSocket 调用能力的 Chat SPA；
• 独立的产品 catalog/metadata 数据层；
• 一套通用 Sandbox capability。

推荐的 owner 划分如下：

Chat 前端可以增加 Workspace 面板，但不应直接绑定 Durable Object namespace，也不应感知 computerd、backend ID 或 SQLite table。公开接口只表达产品无关的领域语义，例如：

GET    /v1/agents/{agentId}/workspace/files?path=/
GET    /v1/agents/{agentId}/workspace/file?path=/notes/plan.md
PUT    /v1/agents/{agentId}/workspace/file
DELETE /v1/agents/{agentId}/workspace/file
POST   /v1/agents/{agentId}/workspace/executions

这些路径只是 contract 设计示意，不是 Computer 自带的 HTTP API。实现时应先定义 authentication、capability、revision、idempotency、限额、错误码和 realtime event，再由 capability service 调用 Workspace。

不要让 Workspace 自动引用或保存另一个独立 Sandbox resource ID。Agent 与 Sandbox 的产品关系应由上层应用用 opaque ID 建模；底层 capability 彼此保持独立，避免删除、授权或迁移形成隐式级联。

7. 为什么不应直接替换现有 Sandbox

Computer Container backend 与 Sandbox SDK 都能运行 Linux command，但控制面并不相同：

如果系统已经围绕 Sandbox 建立 quota、idempotency、process reconciliation、preview 安全和审计，Computer 不应旁路这些边界。更稳妥的分工是：Computer 管 Agent 的小型持久工作目录；Sandbox 管完整 Linux runtime 和产品级执行资源。

8. 生产化前必须验证什么

数据与生命周期

• Workspace schema 如何版本化，升级失败如何回滚。
• Agent 删除时是否完整清理 Computer tables、content blobs、pending sync 和 R2 artifact。
• Durable Object eviction、deployment、alarm 和 reconnect 后能否恢复。
• Container command 成功但 post-command sync 失败时，如何处理 pending sync 与重试。

安全

• path normalization、软链接、压缩包、二进制和超大文件。
• Worker Shell、Worker JavaScript 与 Container 的 egress policy。
• 模型生成 command 的最小权限、审批和 credential injection。
• 文件内容、tool output、日志和 artifact 是否可能泄露 prompt、token 或用户数据。

容量与成本

• 每 Workspace 最大 bytes、files、directories、operations 和 active executions。
• 单个 Durable Object 的热点与排队延迟。
• SQLite storage、Container duration、Dynamic Worker 和 R2 成本。
• FUSE 对 dependency install、large sequential I/O 和增量构建的实际影响。

可观测性与测试

• 使用 Computer observer 记录 operation、backend、latency、result 和 retry，不记录文件正文或 command secret。
• 用 Workers Vitest pool 覆盖 migration、isolation、duplicate command、eviction、cleanup 和权限变化。
• 在真实 develop binding 验证 Container cold start、WebSocket 回连、sync retry 和故障恢复。

9. 推荐采用路线

1. VFS-only spike：只接 workspace.fs，验证跨轮次文件价值、配额、迁移与删除。
2. 受控 Agent tools：只开放 bounded read、write、edit、ls，保持既有 Agent run 和 realtime contract。
3. Worker Shell experiment：只处理文本任务，显式 feature flag，默认无公网。
4. Container benchmark：仅在真实 Linux 是硬需求时测试 computerd，并与现有 Sandbox SDK 比较冷启动、I/O、故障与成本。
5. 按组件评估生产采用：stable 组件按业务要求验收；experimental 后端继续作为实验依赖，等待其稳定性、迁移与安全边界满足要求后再决定正式采用。

这个顺序的关键是先验证“持久工作目录是否创造产品价值”，而不是一开始就构建完整云电脑。

关联阅读

• Cloudflare Agent 电脑与远程桌面方案调研
• Browser Run 能力原理与使用指南

参考资料

• Cloudflare Computer repository
• @cloudflare/computer package README
• Computer Think example
• Computer Container example
• Computer filesystem performance
• Cloudflare Durable Objects
• Cloudflare Dynamic Workers
• Cloudflare Agents: Sandbox tool
• Cloudflare Sandbox SDK

初版整理日期：2026-08-12；最近资料核验：2026-10-20。