如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

自行託管的沙盒

將你的運算資源和檔案連接到智慧體工作階段。

如果你想更直接地掌控智慧體的執行環境,或想使用自己信任的運算資源,可以連接自己的環境。這個環境可以是筆記型電腦、容器或遠端沙盒。如果希望由 OpenAI 佈建環境,請使用 OpenAI 託管的沙盒。

連線的運作方式

OpenAI 負責執行智慧體的任務執行框架。你則在自己的環境中執行 codex exec-server,也就是執行器。執行器會依照任務執行框架的要求執行 shell 指令、讀寫檔案,以及使用本機 MCP 伺服器。

執行器會使用環境 ID 和權限受限的 API 金鑰向 API 註冊,接著透過 WebSocket 建立連線,以接收指令並回傳結果。所有連線都由執行器對外發起。如果連線中斷,執行器會重新連線。

沙盒執行器主動連線到 Agents API,以接收指令並回傳結果。環境金鑰和環境 ID 存放在沙盒中。

準備環境

準備智慧體所需的檔案和相依套件。請依使用者或工作負載隔離環境。共用環境的智慧體可以存取相同的檔案、憑證和其他資源。

如要透過 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 實作事件處理常式。請明確指定由誰負責佈建,以及如何清理資源。