セルフホスト型サンドボックス

エージェントの実行環境をより細かく制御したい場合や、信頼できるコンピューティングリソースを使いたい場合は、自分の環境を接続します。ノート PC、コンテナ、リモートサンドボックスを実行環境として利用できます。環境のプロビジョニングを OpenAI に任せる場合は、OpenAI ホスト型サンドボックスを使用してください。

接続の仕組み

OpenAI はエージェントハーネスを実行します。自分の環境では、エグゼキューターとして codex exec-server を実行します。エグゼキューターはハーネスからの要求に応じて、シェルコマンドを実行し、ファイルを読み書きし、ローカルの 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 操作には使用できません。ソースコード、コンテナイメージ、ログにキーを含めないでください。必要に応じてキーをローテーションするか、失効させてください。

セッションの作成

次の例は、環境の外部にあるアプリケーションで実行します。既存のセルフホスト型セッションがある場合は、それを再利用してください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import 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);

1
2
3
4
5
6
7
8
9
10
11
12from openai import OpenAI

client = OpenAI()

session = 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"},
)
print(session.to_json())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model:        openai.String("gpt-6-astra"),
			Instructions: openai.String("You are a helpful coding assistant. Write clean code and verify that it works."),
		},
		Environment: openai.EnvironmentParamUnion{
			OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace"},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "You are a helpful coding assistant. Write clean code and verify"
                                + " that it works.")
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .build())
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

client = OpenAI::Client.new
result = 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"
  }
)
puts result

session.id をアプリケーションの会話状態とともに保存します。session.environment.id と session.environment.remote_url をエグゼキューターに渡します。再接続時も含め、リモート URL は変更せずに使用してください。保存済みのエージェントを使用する方法は、エージェントの設定を参照してください。

環境イメージ、workspace_directory、capability_directories は複数のセッションで再利用できます。各セッションには固有の環境 ID があり、個別のエグゼキューターが必要です。API の環境テンプレートは、OpenAI ホスト型環境にのみ適用されます。

エグゼキューターの起動

接続イベントを受信するために、アプリケーションからセッションのイベントストリームを開きます。次に、前述の手順で環境キーを CODEX_API_KEY に設定した環境内で、次のコマンドを実行します。プレースホルダーは、API が返した環境の値に置き換えてください。

123codex 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 で管理する方法の比較は、サンドボックスのライフサイクルを参照してください。

Webhook でプロビジョニングを管理する場合は、サンドボックスのライフサイクルを参照し、プロバイダーの SDK または API を使ってハンドラーを実装します。プロビジョニングの責任範囲とリソースのクリーンアップ方針を明確にしてください。