OpenAI Agents API を使い、Cloudflare Containers で Codex を実行する

OpenAI Agents API ↗ は、OpenAI が管理する API を通じて、アプリケーションに Codex ハーネスへのアクセスを与えます。OpenAI がセッション、オーケストレーション、コンテキストの圧縮、回復を管理し、アプリケーションはツールを提供します。Cloudflare Containers は実行環境を提供できます。

Cloudflare Containers で、セルフホストの OpenAI Agents API セッションを実行します。各セッションには、codex exec-server を動かすコンテナを裏付ける Durable Object があります。署名付きの OpenAI Webhook がセッションのオーケストレーションを管理します。

このガイドで使う Worker とコンテナイメージは Cloudflare executor テンプレート ↗ に含まれます。

• Cloudflare Worker: 署名付きの OpenAI Webhook を受け取り、エージェントセッションごとに 1 つのコンテナを管理します。
• Cloudflare Container: codex exec-server と、エージェントが生成したコードを /workspace のファイルに対して実行します。
• Codex executor: 制限付き API キーで OpenAI へ外向き接続します。ワークスペースは Cloudflare アカウント内に残ります。

次が必要です。

• Containers へのアクセスがある Cloudflare アカウント
• OpenAI Agents API へのアクセスと OpenAI API キー
• curl
• 手動デプロイの場合は、Node.js 24 以降、npm、Docker ↗、Wrangler

このガイドでは、codex exec-server が使う制限付き OpenAI API キーを「executor キー」と呼びます。必要な権限は api.model.read と api.agents.environments.connect です。Worker が使うアプリケーションキーには api.agents.read が必要です。両方のキーは、同じ組織、プロジェクト、ユーザーまたはサービスアカウントの所有者に属している必要があります。

最も速いセットアップは Deploy to Cloudflare ボタンです。次の手順で OpenAI エージェントを作成し、実行環境をデプロイし、Webhook を登録し、/workspace でテストタスクを実行します。

export OPENAI_API_KEY="<OPENAI_API_KEY>"

curl "https://api.openai.com/v1/agents" \
	--request POST \
	--header "OpenAI-Beta: agents=v1" \
	--header "Authorization: Bearer $OPENAI_API_KEY" \
	--json '{
		"name": "sandbox-demo",
		"model": "gpt-5.6-sol"
	}'

export OPENAI_AGENT_ID="agent_..."

curl "https://api.openai.com/v1/agents/sessions" \
	--request POST \
	--header "OpenAI-Beta: agents=v1" \
	--header "Authorization: Bearer $OPENAI_API_KEY" \
	--json '{
		"agent_id": "$OPENAI_AGENT_ID",
		"environment": {
				"type": "self_hosted",
				"workspace_directory": "/workspace"
		}
	}'

export SESSION_ID="sess_..."

curl --no-buffer \
  "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  --header "OpenAI-Beta: agents=v1" \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Accept: text/event-stream"

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
	--request POST \
	--header "OpenAI-Beta: agents=v1" \
	--header "Authorization: Bearer $OPENAI_API_KEY" \
	--json '{
		"events": [
				{
						"type": "session.input.message",
						"input": [
								{
										"role": "user",
										"content": [
												{
														"type": "input_text",
														"text": "Use the shell to write hello to /workspace/hello.txt, then read it."
												}
										]
								}
						]
				}
		]
	}'

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
	--request POST \
	--header "OpenAI-Beta: agents=v1" \
	--header "Authorization: Bearer $OPENAI_API_KEY" \
	--json '{
		"events": [
				{
						"type": "session.input.message",
						"input": [
								{
										"role": "user",
										"content": [
												{
														"type": "input_text",
														"text": "Read /workspace/hello.txt again."
												}
										]
								}
						]
				}
		]
	}'

HTTP インターフェイス付きの完全な TypeScript アプリケーションは、Cloudflare Sandbox SDK リポジトリの basic Agents API の例 ↗ を参照してください。

この例は OpenAI Agents API TypeScript SDK を使い、デプロイした executor Worker を裏付けるセルフホストセッションを作成します。初回入力、続きの入力、クリーンアップのエンドポイントがあります。POST /demo エンドポイントは一連のワークフローを実行します。セッション作成、コンテナ内でのファイルの書き込みと読み取り、続きのメッセージ送信、OpenAI セッションと Cloudflare executor の削除です。

OpenAI セッションを削除します。

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID" \
	--request DELETE \
	--header "OpenAI-Beta: agents=v1" \
	--header "Authorization: Bearer $OPENAI_API_KEY"

Cloudflare Container をすぐに止めるには、デプロイ時に保存した共有シークレットを使います。

export WORKER_URL="https://<YOUR_WORKER>.workers.dev"
export EXECUTOR_CLIENT_SECRET="<EXECUTOR_CLIENT_SECRET>"

curl --fail-with-body \
  --request DELETE \
  --header "Authorization: Bearer $EXECUTOR_CLIENT_SECRET" \
  "$WORKER_URL/executors/$SESSION_ID"

OpenAI セッションの削除では、コンテナのクリーンアップ Webhook は送られません。明示的なクリーンアップがないと、アイドルセッションは次の環境接続向けにスナップショットを保持します。失敗セッションの Webhook、または 404 Not Found を返すセッション参照は、コンテナを解放し、保存済みスナップショットを消します。

コンテナのスナップショットは現在プライベートベータです。Cloudflare アカウントでこの機能を有効にしたい場合は、担当の Cloudflare 担当者へ連絡してください。

EXECUTOR_SNAPSHOTS_ENABLED が true のとき、確認済みのアイドルセッションは、コンテナ停止前にコンテナ全体のスナップショットを作成します。次の環境接続はそのスナップショットを復元し、/workspace も含みます。スナップショット作成に失敗すると、Worker は現在のコンテナを動かし続け、別のライフサイクル確認を予約します。

スナップショットはベストエフォートのセッション回復であり、耐久性のあるバックアップではありません。失敗または削除したセッションと、明示的なクリーンアップは、保存済みスナップショットを消します。スナップショットが無効または使えない場合、次の executor は新しい /workspace を受け取ります。耐久性のあるファイルには、R2 FUSE マウント を使うようコンテナイメージを適応します。

executor イメージは、Cloudflare executor テンプレートの openai/agents-api/Dockerfile で定義されています。既存の apt-get install コマンドへ Debian パッケージを追加します。たとえば jq と Python を追加します。

RUN apt-get update \
    && apt-get install --yes --no-install-recommends \
      ca-certificates \
      curl \
      git \
      jq \
      python3 \
      ripgrep \
    && rm -rf /var/lib/apt/lists/*

イメージへ言語固有のツール（グローバル npm パッケージなど）もインストールできます。Dockerfile に API キーやそのほかのシークレットを置かないでください。ランタイムシークレットは Worker バインディングまたはコンテナの環境変数で渡します。

更新したイメージをビルドしてデプロイするには、openai/agents-api から npm run deploy を実行します。

実行可能な例は意図的に最小限です。本番向けに適応する前に、次のデフォルトを確認してください。

• シークレット: コントローラーキー、Webhook シークレット、EXECUTOR_CLIENT_SECRET は Worker シークレットのままです。制限付き executor キーは CODEX_API_KEY としてコンテナへ渡され、コンテナ内のプロセスが読めます。コンテナインスタンスのほかの設定方法は コンテナの環境変数とシークレット を参照してください。
• ネットワークアクセス: この例は、codex exec-server が OpenAI に届くよう外向きのインターネットアクセスを有効にします。宛先を制限したり、ほかのサービス向けの認証情報を注入したりするには コンテナの送信トラフィック制御 を使います。
• ファイル: /workspace は一時的なコンテナストレージです。エージェントが変更すべきでない耐久性のあるソースファイルが必要なときは、読み取り専用の R2 FUSE マウント を使います。
• Worker へのアクセス: OpenAI は対話型の Access ログインなしで /webhook に届く必要があります。Worker は OpenAI の Webhook 署名を検証し、手動クリーンアップエンドポイントには EXECUTOR_CLIENT_SECRET が必要です。ほかのルートを Cloudflare Access で保護する場合は、/webhook を到達可能のままにする パス固有のポリシー を使います。

詳細は Containers のアーキテクチャ を参照してください。

• Cloudflare の参照 Worker ↗
• OpenAI Agents API ドキュメント ↗
• OpenAI Python の Cloudflare Webhook の例 ↗
• OpenAI TypeScript の Cloudflare Webhook の例 ↗
• Cloudflare Containers