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

準備環境
準備智慧體所需的檔案與相依套件。依使用者或工作負載隔離環境。共用環境的智慧體可以存取相同的檔案、憑證及其他資源。
在環境內建立工作目錄並安裝 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:連線失敗。請檢查環境錯誤和執行器日誌。
繼續接收串流,以取得該回合的執行結果與輸出。如要從應用程式或透過 Webhooks 管理啟動、重新連線與關閉,請參閱環境生命週期。
沙盒供應商
選擇沙盒供應商,以執行程式碼及處理檔案。請參閱沙盒生命週期,比較由應用程式管理與由 Webhooks 管理的佈建方式。
| 供應商 | 指南 |
|---|---|
| Modal | Modal 設定 |
| Cloudflare | Cloudflare 設定 |
| Vercel | Vercel 設定 |
| Daytona | Daytona 設定 |
| Blaxel | Blaxel 設定 |
| E2B | E2B 設定 |
| Runloop | Runloop 設定 |
| DigitalOcean | DigitalOcean 設定 |
| Oracle Cloud Infrastructure (OCI) | OCI 設定 |
若採用由 Webhooks 管理的佈建方式,請參照沙盒生命週期,並使用供應商的 SDK 或 API 實作處理常式。請明確界定佈建的負責方與清理政策。