服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务，不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动，严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外，不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- 这份实验示例使用 Agents SDK 内部 API，尚未作为 SDK harness 导出；需要完整 Linux shell 与仓库工具时，官方指南另有 Container harness 或 sandbox 路径。
- 运行需要 Git、Node.js 24 或更高版本、pnpm、rustup 和 Cloudflare 账号；指定 Rust 工具链为 1.95.0，目标为 wasm32-unknown-unknown。
- submit() 在模型完成前返回已持久接收的回执；用相同提示和 operationId 重试时，已有操作返回 accepted: false，可用 snapshot() 查看状态。
- Durable Objects 重启后，已完成的任务步骤复用结果；被中断的步骤（包括模型调用）可能重新执行。事件重放不保证外部工具副作用只发生一次。
先界定这是哪种 Codex 示例
Cloudflare 2026 年 11 月 9 日的公告介绍了一个实验性的 Agents SDK 示例。它把 Codex 的 Rust 回合处理和协议代码适配为 WebAssembly，放在 Cloudflare Durable Object 内运行。它使用 SDK 的内部 API，不是一个已导出的 Agents SDK harness。
它也不提供完整 Codex CLI 的 Linux shell 和仓库工具环境。Cloudflare 指南把这类需求指向 Container harness 或 sandbox 相关文档；应根据需要的是模型与工具回合处理，还是完整仓库执行环境，选择相应示例。
运行前准备工具链和 Cloudflare 账号
官方指南列出的前置条件是 Git、Node.js 24 或更高版本、pnpm、rustup 和 Cloudflare 账号。先执行 git clone https://github.com/cloudflare/agents.git，进入 agents 仓库根目录，执行 pnpm install 与 pnpm nx run agents:build；随后进入 examples/next/harnesses/codex，安装指定工具链：rustup toolchain install 1.95.0 --target wasm32-unknown-unknown。
从示例目录使用 Cloudflare CLI 执行 cf auth login 登录，再运行 pnpm run start。启动脚本会先构建 WebAssembly 模块，再启动 Vite；如果有多个 Cloudflare 账号，指南建议启动前设置 CLOUDFLARE_ACCOUNT_ID。官方演示提示可提交一个把简短 README 写入 /codex/result.txt 并读回的任务，完成后刷新页面查看会话和文件是否仍可访问；这是文档中的示例流程，不是本文实际运行的结果。
本地启动仍会调用远程模型
模型调用通过 Cloudflare 账号访问远程 Workers AI，本地开发也如此。示例在 src/server.ts 中使用 AI binding，并指定 AI Gateway 的网关 ID 为 default，以 openai/gpt-6.1-sol 为模型 ID。使用该默认网关需要 Unified Billing，或已保存的 OpenAI API key。
公告和指南没有给出本示例的实际费用，也未逐一核实账号资格或地区可用性。本文解释文档中的行为，没有进行独立运行、计费或性能测试；开始前应按准备使用的账号核对权限、网关设置和实际费用。
operationId 表示已接收，不表示已完成
在示例的 Coder Durable Object 中调用 submit({ prompt, operationId }) 会先持久接收提示，再返回回执；模型此时可能仍在工作。回执含 operationId、streamId 和 accepted。重试同一提示时应沿用同一个 operationId；如果该 ID 已对应现有操作，回执会是 accepted: false。
收到回执后，用 snapshot(operationId) 查询 queued、running、completed 或 failed。完成时快照含 output，失败时含 error。因此，客户端应把“已接受”和“已完成”作为不同状态呈现，并依据同一个操作 ID 继续读取原操作的状态，而不是把提交请求已经返回当成模型工作已结束。
重启后复用已完成步骤，中断步骤可能重跑
示例把能力分在几处：Tasks 记录模型和工具步骤；Sessions 保存对话 transcript 并压缩模型上下文；Streams 持久化事件供重放；Workspace 在 Durable Object 的 SQLite 存储中保存文件。浏览器端 session hook 会先取得快照、订阅操作事件，并在重新连接时从下一条未读序号继续接收。
Durable Object 重启后，Tasks 中已完成的步骤会复用保存的结果；被中断的步骤则可能重新执行，包括模型调用。Streams 的事件重放帮助客户端恢复事件读取顺序，但不构成对外部副作用的恰好一次保证。若工具会付款、创建外部资源、发消息或改变其他系统状态，应用仍需为该外部操作设计自己的去重方式，或先核对原操作的结果，再决定是否重试。
暴露会话前加认证，并核对能力限制
官方示例路由没有认证；在向用户开放会话前，必须先加上适合应用的身份验证与授权。不要把示例路由直接暴露为多用户服务入口。
适配器支持文本、推理和 function tools，但不支持文件响应、由 provider 执行的工具或工具审批请求。需要这些能力时，先检查该实验示例是否适合目标流程，不要把其他 harness 的功能直接套用到这里。
资料来源
常见问题
maxRounds 默认 128，是否表示总共只能调用 128 次工具？
不是。maxRounds 限制每个 turn 的模型轮数，默认值为 128；指南将一轮定义为一次模型调用加上它请求的工具调用，因此不能把这个数字直接当成工具调用总数。
浏览器重连后，为什么暂时还看不到新的模型响应事件？
指南说明，模型响应事件要在对应模型轮次结束后才可用。重连后从下一条未读序号继续接收的是已持久化事件；暂时没有新事件本身不能证明操作失败，应结合原 operationId 的 snapshot() 状态判断。
不支持文件响应，为什么示例还能读写文件？
模型返回文件响应与调用文件工具是不同能力。示例把 Durable Object 的 SQLite-backed Workspace 中的读写操作注册为 workspace_read 和 workspace_write，作为 function tools 提供给模型；这不代表适配器支持文件响应或 Linux shell。