For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主要導覽

自行託管的沙盒

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

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

連線運作方式

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

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

沙盒執行器會主動建立連至 Agents API 的對外連線,並交換指令與結果。沙盒持有環境金鑰和環境 ID。

準備環境

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

在環境內建立工作目錄並安裝 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.readapi.agents.write 權限,以執行工作階段操作,並授予 api.responses.write 權限以進行模型推論。如果應用程式會管理保管庫,請再加上 api.vaults.readapi.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.idsession.environment.remote_url 傳給執行器。請原樣使用遠端 URL,重新連線時也不要變更。如要使用已儲存的智慧體,請參閱設定智慧體

你可以在不同工作階段中重複使用環境映像檔、workspace_directorycapability_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:連線失敗。請檢查環境錯誤和執行器日誌。

繼續接收串流,以取得該回合的執行結果與輸出。如要從應用程式或透過 Webhooks 管理啟動、重新連線與關閉,請參閱環境生命週期

沙盒供應商

選擇沙盒供應商,以執行程式碼及處理檔案。請參閱沙盒生命週期,比較由應用程式管理與由 Webhooks 管理的佈建方式。

供應商指南
ModalModal 設定
CloudflareCloudflare 設定
VercelVercel 設定
DaytonaDaytona 設定
BlaxelBlaxel 設定
E2BE2B 設定
RunloopRunloop 設定
DigitalOceanDigitalOcean 設定
Oracle Cloud Infrastructure (OCI)OCI 設定

若採用由 Webhooks 管理的佈建方式,請參照沙盒生命週期,並使用供應商的 SDK 或 API 實作處理常式。請明確界定佈建的負責方與清理政策。