如果你想更直接地掌控智慧體的執行環境,或想使用自己信任的運算資源,可以連接自己的環境。這個環境可以是筆記型電腦、容器或遠端沙盒。如果希望由 OpenAI 佈建環境,請使用 OpenAI 託管的沙盒。
連線的運作方式
OpenAI 負責執行智慧體的任務執行框架。你則在自己的環境中執行 codex exec-server,也就是執行器。執行器會依照任務執行框架的要求執行 shell 指令、讀寫檔案,以及使用本機 MCP 伺服器。
執行器會使用環境 ID 和權限受限的 API 金鑰向 API 註冊,接著透過 WebSocket 建立連線,以接收指令並回傳結果。所有連線都由執行器對外發起。如果連線中斷,執行器會重新連線。

準備環境
準備智慧體所需的檔案和相依套件。請依使用者或工作負載隔離環境。共用環境的智慧體可以存取相同的檔案、憑證和其他資源。
如要透過 review: "auto_review" 啟用自動審查,請在容器中執行標準執行器。該容器必須支援沙盒,並允許 Codex 建立沙盒。自動審查會套用權限設定檔,以 workspace-write 為基準,並限制網路存取。啟用前,請先確認環境符合自動審查的先決條件。
在環境中建立工作目錄並安裝 Codex CLI。此範例使用 /workspace:
mkdir -p /workspace
npm install -g @openai/codex@alpha
網路存取
允許環境對下列主機發起連線:
https://api.openai.com用於註冊環境。wss://codex-cloud-environments.chatgpt.com用於接收指令和回傳結果。
驗證身分
應用程式發出請求時,請使用 OPENAI_API_KEY。授予這把金鑰 api.agents.read 和 api.agents.write 權限,以便操作工作階段,並授予 api.responses.write 權限,以便執行模型推論。如果應用程式需要管理保管庫,請一併授予 api.vaults.read 和 api.vaults.write 權限。
在平台儀表板的「智慧體」分頁建立一把獨立的環境金鑰。金鑰和工作階段必須隸屬於同一個組織和專案,且由同一個使用者或服務帳戶擁有。將其餘權限全部設為無。
在應用程式或佈建服務中,將 OPENAI_EXECUTOR_API_KEY 設為這把環境金鑰。將其值以 CODEX_API_KEY 傳入沙盒,供 codex exec-server 讀取。應用程式使用的 OPENAI_API_KEY 必須留在沙盒外。
智慧體產生的程式碼可以讀取環境金鑰,但這把金鑰僅允許連接環境,無法授權其他 API 操作。請勿將環境金鑰寫入原始碼、容器映像檔或記錄中。視需要輪替或撤銷金鑰。
建立工作階段
在環境外的應用程式中執行此範例。如果已有自行託管的工作階段,可以沿用。
import OpenAI from "openai";
const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions:
"You are a helpful coding assistant. Write clean code and verify that it works.",
},
environment: {
type: "self_hosted",
workspace_directory: "/workspace",
},
});
console.log(session);將 session.id 與應用程式的對話狀態一併儲存。將 session.environment.id 和 session.environment.remote_url 傳給執行器。請原樣使用遠端 URL,重新連線時也一樣。如要使用已儲存的智慧體,請參閱設定智慧體。
你可以在不同工作階段中重複使用環境映像檔、workspace_directory 和 capability_directories。每個工作階段都有專屬的環境 ID,也需要各自的執行器。API 的環境範本僅適用於 OpenAI 託管的環境。
啟動執行器
從應用程式開啟工作階段事件串流,以接收連線事件。依照上述步驟將環境金鑰設為 CODEX_API_KEY 後,在環境中執行下列指令。請將預留位置替換為 API 回傳的環境值:
codex exec-server \
--remote "<session.environment.remote_url>" \
--environment-id "<session.environment.id>"
智慧體工作期間,請讓執行器持續運作。
傳送任務並監控連線
保持事件串流開啟,並從應用程式傳送輸入。環境連線就緒且收到使用者輸入後,智慧體才能開始工作。
事件串流會回報下列連線狀態:
agent.session.environment.pending:工作階段正在等候執行器連線。agent.session.environment.connected:環境已就緒。agent.session.environment.failed:連線失敗。請查看環境的錯誤資訊和執行器記錄。
繼續監看事件串流,以取得這一輪的執行結果和輸出。如要從應用程式或透過 webhook 管理啟動、重新連線和關閉環境的流程,請參閱環境生命週期。
沙盒供應商
選擇沙盒供應商,以便執行程式碼和處理檔案。若要比較由應用程式管理佈建與透過 webhook 管理佈建這兩種方式,請參閱沙盒生命週期。
| 供應商 | 指南 |
|---|---|
| AWS Lambda MicroVMs | AWS 設定指南 |
| Blaxel | Blaxel 設定指南 |
| Cloudflare | Cloudflare 設定指南 |
| Databricks Sandbox | Databricks 設定指南 |
| Daytona | Daytona 設定指南 |
| DigitalOcean | DigitalOcean 設定指南 |
| E2B | E2B 設定指南 |
| Modal | Modal 設定指南 |
| Oracle Cloud Infrastructure (OCI) | OCI 設定指南 |
| Vercel | Vercel 設定指南 |
如要透過 webhook 管理佈建,請參照沙盒生命週期,使用供應商的 SDK 或 API 實作事件處理常式。請明確指定由誰負責佈建,以及如何清理資源。