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

8月 12, 2026

AI 参与说明（Agent：Codex）：本文由 Codex 根据 Cloudflare Computer 公开仓库、Cloudflare Durable Objects、Dynamic Workers、Agents 与 Sandbox SDK 官方资料辅助整理，重点核对概念、公开 API、执行后端和 Agent 集成边界。资料核验于 2026-08-12；@cloudflare/computer 当前仍明确标注为 Preview，API 与部署方式可能变化，实施前请以文末一手资料和项目锁定版本为准。

先说结论#

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。

但截至本文核验日期，官方 README 明确说明该项目只适合实验、探索和原型，不适合生产。合理路径是先做隔离 spike，验证工作区语义、迁移、清理、配额与失败恢复，再决定是否成为正式依赖。

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。

1.4 computerd 与 FUSE#

Container backend 会在 Container 内运行 computerd。它通过 FUSE 把 Workspace 投影为真实目录，再经 capnweb WebSocket 与 Durable Object 同步文件变化。

这种设计让 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 当作完整 Bash。需要 Node.js、Python、package manager、native binary 或完整网络时，应选择 Container 或 Sandbox，而不是为 just-bash 不断添加兼容分支。

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,
  },
  shell: {
    defaultBackend: "shell",
    backends: {
      shell: {
        description:
          "Fast text processing with just-bash; no Node.js or Python.",
      },
    },
  },
});

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

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

Think Agent 还可以把 Workspace({ useThink: true }) 赋给自身的 workspace，再将 Computer tools 合并进每个 turn 的允许工具集合。这里应让既有 Agent lifecycle、run、history 和 realtime protocol 继续保持权威，Computer 只负责工作区与执行，不要再建立第二套 Agent runtime。

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. GA/review gate：等上游稳定性、迁移和安全边界满足生产要求后，再决定正式依赖。

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

参考资料#

• 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。