サンドボックス¶

サンドボックスは、マシンへの無制限のアクセスを与えずに、エージェントが自律的に動作できる境界です。ローカルチャットが ChatGPT desktop app、Codex CLI、または IDE extension でコマンドを実行すると、それらのコマンドはデフォルトで完全なアクセス権を持って実行されるのではなく、制約された環境内で実行されます。

その環境では、エージェントが自律的に実行できる操作、たとえば変更できるファイルや、コマンドでネットワークを使用できるかどうかが定義されます。タスクがその境界内に収まる場合、エージェントは確認のために停止せず、作業を続けられます。境界を越える必要がある場合は、承認フローが引き継ぎます。

サンドボックスと承認は、連携して機能する異なる制御です。サンドボックスは技術的な境界を定義します。承認ポリシーは、境界を越える前にエージェントが停止して確認を求めるタイミングを決定します。

サンドボックスの動作¶

サンドボックスは、組み込みのファイル操作だけでなく、起動されたコマンドにも適用されます。エージェントが git、パッケージマネージャー、テストランナーなどのツールを実行すると、それらのコマンドは同じサンドボックス境界を継承します。

Codex は各 OS でプラットフォームネイティブの強制機能を使用します。実装は macOS、Linux、WSL2、ネイティブ Windows で異なりますが、すべての環境で考え方は同じです。つまり、明確な制限の範囲内で日常的なタスクを自律的に実行できるよう、エージェントに境界付きの作業場所を提供します。

重要な理由¶

サンドボックスは、承認疲れを軽減します。低リスクのコマンドを実行するたびに確認を求めるのではなく、エージェントは、あらかじめ承認した境界内でファイルの読み取り、編集、日常的なプロジェクトコマンドの実行を行えます。

また、エージェントを使った作業に対する、より明確な信頼モデルも提供します。単にエージェントの意図を信頼するのではなく、エージェントが強制された制限の範囲内で動作していることを信頼できます。これにより、エージェントがいつ停止して支援を求めるのかを把握しながら、エージェントに独立して作業させやすくなります。

はじめに¶

デフォルトの権限モードでは、サンドボックスが自動的に適用されます。

前提条件¶

macOS では、組み込みの Seatbelt フレームワークを使用するため、サンドボックスはそのまま動作します。

Windows では、PowerShell で実行するとネイティブの Windows サンドボックスが使用され、WSL2 で実行すると Linux のサンドボックス実装が使用されます。

Linux と WSL2 では、まずパッケージマネージャーを使用して bubblewrap をインストールします。

<Tabs id="codex-sandboxing-prerequisites" param="sandbox-os" tabs={[ { id: "ubuntu-debian", label: "Ubuntu/Debian" }, { id: "fedora", label: "Fedora" }, ]}

sudo apt install bubblewrap

sudo dnf install bubblewrap

Codex は、PATH 上で最初に見つかった bwrap 実行可能ファイルを使用します。bwrap 実行可能ファイルが利用できない場合、Codex はバンドルされたヘルパーにフォールバックしますが、そのヘルパーには非特権ユーザー名前空間の作成をサポートする機能が必要です。bwrap を提供するディストリビューションパッケージをインストールすると、この設定の信頼性を維持できます。

bwrap が見つからない場合、またはヘルパーが必要なユーザー名前空間を作成できない場合、Codex は起動時に警告を表示します。この AppArmor 設定を制限するディストリビューションでは、bwrap AppArmor プロファイルを読み込むことをおすすめします。これにより、グローバルに制限を無効化せずに bwrap を引き続き動作させられます。

Ubuntu AppArmor に関する注意: Ubuntu 25.04 では、Ubuntu のパッケージリポジトリから bubblewrap をインストールすれば、追加の AppArmor 設定なしで動作するはずです。bwrap-userns-restrict プロファイルは、apparmor パッケージの /etc/apparmor.d/bwrap-userns-restrict に含まれています。

Ubuntu 24.04 では、bubblewrap のインストール後も、必要なユーザー名前空間を作成できないという警告が Codex に表示されることがあります。追加のプロファイルをコピーして読み込みます。

sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

apparmor_parser -r は、再起動せずにプロファイルをカーネルへ読み込みます。すべての AppArmor プロファイルを再読み込みすることもできます。

sudo systemctl reload apparmor.service

そのプロファイルを利用できない場合、または問題が解決しない場合は、次のコマンドで AppArmor の非特権ユーザー名前空間制限を無効にできます。

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

権限の仕組み¶

使用している環境の権限制御を使って、Codex によるローカル操作の処理方法を変更します。

承認は、Codex が操作の前に一時停止するタイミングを決定し、サンドボックスは、コマンドがアクセスできるファイルとネットワークリソースを決定します。承認で「一度だけ」や「セッション中」など異なる範囲を選べる場合は、タスクを継続できる最も狭い範囲を選択してください。プロジェクトの境界をデフォルトとして維持し、関係のないリポジトリ間でアクセスを広げるのではなく、別のプロジェクトまたは worktree を使用してください。

ChatGPT desktop app では、composer の下にある権限制御を使用します。設定によっては、メニューに Ask for approval、対象となる承認リクエストで使用できる Approve for me、Full access、名前付きまたはカスタムの権限プロファイルが含まれる場合があります。

デフォルトを設定する¶

毎回同じ動作で開始するには、config.toml でデフォルトを設定します。Config basics ではその仕組みを説明し、Configuration reference では sandbox_mode、approval_policy、approvals_reviewer、sandbox_workspace_write.writable_roots の正確なキーを説明します。これらの設定を使用して、エージェントにデフォルトでどの程度の自律性を与えるか、書き込み可能なディレクトリ、承認のために一時停止するタイミング、対象となる承認リクエストを確認する担当者を決定します。

大まかに分けると、一般的なサンドボックスモードは次のとおりです。

read-only: エージェントはファイルを調査できますが、承認なしにファイルを編集したりコマンドを実行したりすることはできません。
workspace-write: エージェントはファイルを読み取り、workspace 内で編集し、その境界内で日常的なローカルコマンドを実行できます。これは、ローカル作業におけるデフォルトの低摩擦モードです。
danger-full-access: エージェントはサンドボックスの制限なしで実行されます。これによりファイルシステムとネットワークの境界がなくなるため、エージェントに完全なアクセス権で動作させたい場合にのみ使用してください。

一般的な承認ポリシーは次のとおりです。

untrusted: エージェントは、信頼済みセットに含まれないコマンドを実行する前に確認を求めます。
on-request: エージェントはデフォルトでサンドボックス内で作業し、その境界を越える必要がある場合に確認を求めます。
never: エージェントは承認プロンプトのために停止しません。

承認がインタラクティブな場合は、approvals_reviewer を使用して確認担当者を選ぶこともできます。

user: 承認プロンプトはユーザーに表示されます。これがデフォルトです。
auto_review: 対象となる承認プロンプトはレビュアーエージェントに送られます（automatic review を参照してください）。

完全なアクセス権とは、sandbox_mode = "danger-full-access" と approval_policy = "never" を組み合わせて使用することです。一方、低リスクのローカル自動化プリセットは、sandbox_mode = "workspace-write" と approval_policy = "on-request"、または対応する CLI フラグ --sandbox workspace-write --ask-for-approval on-request の組み合わせです。そのうえで、手動承認には approvals_reviewer = "user" を維持するか、自動承認レビューには approvals_reviewer = "auto_review" を設定できます。

エージェントに複数のディレクトリをまたいで作業させる必要がある場合は、サンドボックス全体を削除せずに、書き込み可能なルートによって変更可能な場所を拡張できます。より広い、または狭い信頼境界が必要な場合は、場当たり的な例外に頼るのではなく、デフォルトのサンドボックスモードと承認ポリシーを調整してください。

ワークフローで特定の例外が必要な場合は、rules を使用します。ルールを使うと、サンドボックス外のコマンドプレフィックスを許可、確認、または禁止できます。これは、アクセス範囲を大きく広げるより適していることがよくあります。IDE 固有の設定エントリーポイントについては、Codex IDE extension settings を参照してください。

利用可能な場合、自動レビューはサンドボックスの境界を変更しません。これは、その境界における承認リクエストに対する 1 つの approvals_reviewer です。対象には、サンドボックスの権限昇格、ブロックされたネットワークアクセス、依然として承認が必要な副作用のあるツール呼び出しなどがあります。サンドボックス内ですでに許可されている操作は、追加のレビューなしで実行されます。レビュアーのライフサイクル、トリガーの種類、拒否のセマンティクス、設定の詳細については、automatic review を参照してください。

プラットフォームの詳細は、プラットフォーム固有のドキュメントに記載されています。ネイティブ Windows の設定、動作、トラブルシューティングについては、Windows を参照してください。サンドボックスと承認に関する管理者要件および組織レベルの制約については、Agent approvals & security を参照してください。