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

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

接続の仕組み

OpenAI はエージェントハーネスを実行します。ユーザーは、独自の環境内でエグゼキューターである codex exec-server を実行します。エグゼキューターはハーネスからのリクエストに応じて、シェルコマンドの実行、ファイルの読み書き、ローカルの 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 exec-server が読み取る CODEX_API_KEY としてサンドボックスに渡します。アプリケーションの 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 を使ってハンドラーを実装します。プロビジョニングの管理責任とクリーンアップのポリシーを明確にしてください。