Cloudflare Containers 跑 Codex：OpenAI Agents API 的部署邊界

2026-09-12

伺服器

Cloudflare

/

AI

/

開發工具

/

設定管理

/

最佳實踐

想把 Codex 放進 Cloudflare Containers，最先要釐清的不是某一個 wrangler 指令，而是誰負責 orchestration、誰執行程式碼，以及哪一把 key 可以看到什麼。Cloudflare 官方的 OpenAI Agents API 教學把這三件事拆開：OpenAI 管理 agent session 與協調流程，Worker 管理每個 session 的 Container，Container 內執行 codex exec-server 與 workspace 裡的程式碼。

直接答案是：把 OpenAI Agents API 當控制平面，把 Cloudflare Worker／Durable Object 當 session 管理層，把 Container 當受控執行平面。 這個架構可以讓 workspace 留在 Cloudflare 帳號內，但不代表 secrets、Webhook、出站網路與第三方 Plugin 已經自動安全。

本文依 Cloudflare 官方 Sandbox 教學、Changelog 與 Sandbox SDK 範本整理；下列部署命令是說明用範例，我沒有在本機建立或部署你的帳號資源。

先畫出四層責任#

元件	主要責任	不要誤解成
OpenAI Agents API	建立 session、協調 agent、處理 context compaction、recovery 與後續輸入	不等於把你的 workspace 複製到 OpenAI
Worker	驗證 signed webhook、接收事件、找到 session 對應的 Durable Object、啟動或連回 Container	不是在 Worker runtime 內直接跑完整 Codex 工作區
Durable Object	讓一個 Codex session 有穩定的狀態與 Container 對應	不是秘密保管箱，也不是任意程式碼的隔離邊界
Cloudflare Container	執行 `codex exec-server`、工具與 `/workspace` 內的程式碼	不代表模型推理或 orchestration 都在 Cloudflare 完成

官方範本的核心路徑是：每個 session 對應一個 Durable Object；收到建立或 action event 後，Worker 維持對應的 Container，Container 內的 executor 再向 OpenAI 建立連線。後續輸入可以重新連回同一個 session，而不是每次都從空白目錄開始。

開始前的前置條件#

Cloudflare 教學列出的準備項目包括：

可使用 Cloudflare Containers 的帳號與計費設定。
已開通 OpenAI Agents API，並有對應的 API key。
curl，用於檢查 Worker 的 health endpoint 或送出測試請求。
若從範本手動開始，準備 Node 24+、npm、Docker 與 Wrangler。

官方範本位於 Cloudflare Sandbox SDK 的 openai/agents-api 目錄。開始前先 fork 或複製到自己的 repository，確認範本版本、OpenAI API 方案、Containers 可用區域與預算上限，不要把範例環境當成 production baseline。

金鑰要分成 app 與 executor#

不要讓 Worker 和 Container 共用一把全能 key。教學使用的環境變數名稱與權限邊界如下，值請放在平台的 secret store，不要寫進 image、repository 或文章：

變數	使用位置	官方教學中的目的
`OPENAI_API_KEY`	Worker app	讓 app 讀取或管理 agent 資源；使用 `api.agents.read` 等必要權限
`OPENAI_EXECUTOR_API_KEY`	Container executor	受限地讀取模型並連接 agent environment；至少分開 `api.model.read` 與 `api.agents.environments.connect` 的用途
`OPENAI_AGENT_ID`	Worker	指定要執行的 agent，不是 secret
`OPENAI_WEBHOOK_SECRET`	Worker	驗證 OpenAI signed webhook；驗證失敗時不能改寫 session state
`EXECUTOR_CLIENT_SECRET`	Worker／executor handshake	保護 Worker 與執行器之間的連線，兩邊的值要用 secret store 注入

限制 key scope 還不夠；官方也要求相關 key 屬於同一個 org／project，以及相同的 user 或 service account。部署前先記錄「哪個元件擁有哪些權限」，之後才有辦法從 log 判斷是認證失敗還是 Container 問題。

Webhook 是 session 狀態機的入口#

範本會處理的事件至少包括：

1
agent.session.created
2
agent.session.action_required
3
agent.session.in_progress
4
agent.session.idle
5
agent.session.failed

建議把一次 session 走成可觀測的流程：

created 到達 Worker，先驗證簽章與事件 ID，再取得或建立該 session 的 Durable Object。
Durable Object 啟動或取得 Container，讓 executor 執行 codex exec-server，workspace 掛在 /workspace。
in_progress 與 action_required 更新 UI 或內部狀態，但不要把 secret input 寫入一般 application log。
idle 代表目前沒有工作，不等於 Container 永久存在；官方範本的 idle timeout 預設約 30 秒，並可調整。
failed 要保留錯誤、session、Container 與 webhook event 的關聯，避免只回傳一個模糊的 500。

第一次部署時，先用 /health 確認 Worker 可回應，再註冊 webhook 事件。Webhook handler 應具備簽章驗證、重複事件去重與狀態轉移紀錄；即使範本已經幫你處理基本流程，也要把這些項目列為自己的驗收條件。

Container lifecycle 會影響體驗與成本#

Container 不是每個請求都新建一個就結束。session 需要在後續輸入時重新連回，所以 Worker 要管理啟動、ready、idle、failed 與 cleanup：

冷啟動：第一次建立 Container 需要拉起 executor 與 workspace，應在 UI 清楚顯示等待狀態。
後續輸入：同一 session 直接連回現有 executor，保留上下文與工作區，但要驗證 session ID 沒有串錯。
閒置回收：超過 idle timeout 就停止 Container，避免無限佔用資源；預熱和 snapshots 只是降低等待的最佳化，不是資料備份。
失敗回復：Container 重建後，要明確知道 workspace 是否來自 snapshot、fresh checkout 或上一個仍存在的 volume。

如果要放長時間執行的 build、測試或 migration，先定義 timeout、重試、取消、log 保留與 partial output；不要把「Agent 回傳 idle」當成任務一定成功。

一個安全的範例部署順序#

以下只示意從官方範本開始的工作順序：

1
git clone https://github.com/cloudflare/sandbox-sdk.git
2
cd sandbox-sdk/openai/agents-api
3
npm install
4
npx wrangler dev

接著在本機或 CI secret store 注入必要環境變數，再用不含敏感資料的測試 prompt 驗證：

1
curl -fsS https://YOUR_WORKER.example.com/health

正式部署前，逐項確認：

Worker 只收到 app key 與 webhook secret，Container 只收到受限 executor key。
webhook secret 不會出現在 request log、exception message 或前端 bundle。
action required 的輸入會經過明確的 user consent；需要 secret 時使用遮罩輸入，不把值回傳到 transcript。
Container 的 filesystem、出站網路、可使用的工具與 workspace 權限符合最小需求。
失敗時能按 session、event、Container instance 與 deployment version 追查。

這個整合不是什麼#

它不是把 OpenAI 模型直接搬到 Cloudflare 執行；控制平面仍由 OpenAI Agents API 管理。
它不是只在 Worker 裡加一個 /chat endpoint；session lifecycle、signed webhook 與 executor handshake 都是必要元件。
它不是自動授權任意 repository 的寫入權限；Git checkout、GitHub token、部署 credentials 與第三方服務仍要由你設計。
它不是完成一次 hello world 就能直接承載 production migration；要額外測試取消、重試、超時、重新連線、敏感輸入與 Container 回收。

若你的需求只是讓 coding agent 操作一個長期存在的自管 workspace，先比較既有的 Cloudflare Cursor Cloud Agents 自架架構；那篇的控制平面與這次 OpenAI Agents API 整合不同，不能直接互換設定。

參考資料：

Cloudflare Docs：Use OpenAI Agents API with Cloudflare Containers

Cloudflare Changelog：Using OpenAI Agents API with Cloudflare Containers

Cloudflare Sandbox SDK：OpenAI Agents API example