Cloudflare Computer 实战指南：如何 10 分钟给 AI Agent 配一套可执行的云端工作区

Cloudflare Computer 实战指南：如何 10 分钟给 AI Agent 配一套可执行的云端工作区

【免费下载链接】computerGive your agent a computer 👾项目地址: https://gitcode.com/GitHub_Trending/computer1/computer

Cloudflare Computer 是一个为 AI Agent 提供持久化虚拟文件系统和执行沙箱的开源项目，用 SQLite 保存文件状态，提供容器、Worker Shell、Worker JavaScript 三种可插拔执行后端，适合需要给 Agent 配云端工作区和真实命令执行能力的开发者。

工作原理：云端工作区是怎样建起来的

这一节回答两个核心问题：文件状态存在哪、命令在哪执行。文件状态全部存放在 Durable Object（Cloudflare 的有状态服务端对象）里的 SQLite 数据库中，它是唯一可信源（source of truth），无论后端切换多少次、进程重启多少次，所有 readFile、writeFile 操作都指向这里。执行走三条路径，但统一收敛在workspace.runtime.exec()这一个入口上：Container 后端在沙箱容器里拉起computerd守护进程，用 FUSE（用户态文件系统接口）把 SQLite 状态投影成真实挂载点，变更经 capnweb RPC 通道回同步；Worker Shell 后端在 Dynamic Worker（运行时动态加载的 Worker 实例）里跑 just-bash 这类 shell 命令；Worker JavaScript 后端则在 Dynamic Worker 中执行 ESM 模块。因为同一份文件系统对两侧可见，你用 fs 写进去的文件 exec 立即可见，反之亦然。

核心能力拆解：三种执行后端怎么选

这一节解决"我的命令该走哪条后端"的问题。一个 Workspace 可以一次注册多个后端，用稳定 ID 区分、首次使用时懒加载；workspace.runtime.exec()由 backend 参数决定走哪条路，也可以不挂任何后端，只把它当纯文件系统用。

三者之外的第四块能力是工具集：@cloudflare/computer/tools里的createAITools()直接暴露 read / write / edit / ls / find / grep / delete 等 AI SDK 工具，可选 exec 与 publish（把产物发布成可分享链接），自带分页、字节上限、行号与统一 diff 返回，接 AI SDK 时不用自己造轮子。

动手体验：三步装好工作区 💬

这一节给出最小可运行路径：装包、建工作区、执行第一个操作。

第一步，在 Worker/Agent 项目里安装核心包：

npm install @cloudflare/computer

第二步，在 Durable Object 中创建 Workspace。storage 指向 DO 存储（虚拟文件系统住在这里），backends 注册执行后端：

const workspace = new Workspace({ storage: this.ctx.storage, backends: [new CloudflareContainerBackend({ /* … */ })], }); await workspace.ready();

第三步，像 Node fs/promises 一样操作。路径全部为绝对路径、API 全异步，这里写一个文件并用 exec 读回验证：

await workspace.fs.writeFile("/workspace/hello.txt", "hi"); const run = await workspace.runtime.exec("cat /workspace/hello.txt", { encoding: "utf8" }); const { stdout, exitCode } = await run.result();

想要完整体验，推荐从 examples/think 示例起步：它是一个带 Computer 工作区的聊天 Agent，同时接了快速 Worker Shell 和完整容器两个后端，你在终端输入消息，Agent 会自主调用 read、write、exec 工具在云端工作区里干活：

git clone https://gitcode.com/GitHub_Trending/computer1/computer cd computer && npm install cd examples/think npm run dev # 终端 1：启动 Worker（需要 Docker） npm run chat # 终端 2：打开终端聊天 UI

适用边界与注意事项：性能边界在哪里

这一节说明引入前需要知道的边界。项目目前处于 PREVIEW 阶段，API 不稳定，官方明确提示暂不建议直接用于生产。

• ✅ 擅长元数据密集型操作：内存 inode 表让 stat、rm、建目录树、find、git 操作快于真实 ext4 磁盘，最高约 1.8 倍优势；
• ⚠️ 短板在大文件顺序 I/O：64 MiB 读写明显慢于磁盘与 tmpfs，一次 854 包的完整 npm install 约为 ext4 的 2 倍耗时；
• 总容量约 10GB（与 DO 共享存储），容器侧文件系统驻留内存，适合 Agent 规模的工作区，不适合完整 monorepo。

以上数据来自官方基准 docs/19_performance.md，文中也给了复现脚本。

深入探索：五个值得读的设计入口

这一节集中列出深入理解本项目的关键资源：

• docs/01_vfs.md — 工作区树布局、保留路径与挂载点
• docs/02_sync_protocol.md — DO 与沙箱容器间的同步协议与 push/pull 语义
• docs/09_tool_interface.md — AI SDK 工具接口细节
• examples/think/ — 终端聊天 Agent 示例，双后端接入方式
• packages/computer/ — 顶层包 README：入口点表与完整用法示例

结语

一句话回扣定位：Cloudflare Computer = 持久化虚拟文件系统 + 可插拔执行沙箱 + 现成 Agent 工具集。最上手的路线是从 examples/think 开始：跑通npm run dev和npm run chat，十分钟内就能和一台真正在云端工作区干活的 Agent 对话起来 👾

【免费下载链接】computerGive your agent a computer 👾项目地址: https://gitcode.com/GitHub_Trending/computer1/computer