Codexのエージェントモードとサンドボックス設定・使い分け

エージェントモードとサンドボックスは別の設定

Codexを使い始めると、「エージェントモードにしたら何でも変更できる」と考えがちです。しかし、エージェントモードはコードを理解して複数の道具を組み合わせる動作の入口であり、実際にどのファイルを読めるか、書き込めるか、外部ネットワークへ出られるかは別の許可設定で決まります。ここを混同すると、読み取りだけの調査に広すぎる権限を与えたり、編集を頼んだのに書き込み境界で止まったりします。最初に「何を考えさせるか」と「どこまで触れさせるか」を分けて決めることが大切です。公式のCodex設定リファレンスでも、sandbox_modeはコマンド実行時のファイルシステムとネットワークの方針として説明されています。

エージェントモードが決めること

エージェントモードでは、単発の回答だけでなく、リポジトリの構成を読み、関連ファイルを探し、コマンドを実行し、結果を見て次の確認へ進むという一連の作業を依頼できます。たとえば「ログイン画面のテストが失敗する理由を調べ、原因候補と確認方法を示して」と頼めば、該当ファイルとテスト結果を照合することが中心になります。ここで重要なのは、エージェントモードを選んだことと、ファイルを変更する許可を与えたことは同じではない点です。調査と編集を分ければ、最初の返答を読んでから次の権限へ進めます。

サンドボックスが決めること

サンドボックスは、Codexがコマンドを使うときの境界です。現在の設定には、読み取りだけを許すread-only、作業フォルダー内の変更を許すworkspace-write、制限を大きく外すdanger-full-accessがあります。設定リファレンスはこの三つをsandbox_modeの値として示し、workspace-writeでは追加の書き込み先や外部ネットワークの許可も個別に指定できると説明しています。モデルが「このファイルを直したい」と判断しても、境界の外側へ書き込めるとは限りません。止まることは故障ではなく、設定が機能している結果の場合があります。

二つを一緒に見る理由

長い作業ほど、読む、考える、書く、試すという動作が何度も続きます。そのたびに権限を変えると、どの時点で状態が変わったのか分かりにくくなります。そこで、依頼の最初に作業目的と対象範囲を決め、調査はread-only、局所的な修正はworkspace-writeというように段階を分けます。エージェントに任せる範囲を広げる場合も、サンドボックスの境界、承認の有無、変更後に人が読む場所を同時に確認すれば、便利さと確認可能性を両立できます。

2026年9月にサンドボックスを見直す理由

サンドボックスは昔からある安全機能に見えますが、Codexの入口と作業の長さが増えるほど、設定の意味を具体的に見直す価値が上がります。2026年9月9日のCodex 0.154.0では、セッションを分けて扱うworktreeと、Windowsで背景のCodexサーバーを共有する機能がリリースノートに記載されました。さらに9月10日のAgents API発表では、Codexを支える基盤を使い、ファイルやコードを扱う環境を選べる仕組みが公開ベータとして説明されています。単一のファイルを短く直す利用から、複数の作業場所や長い調査を扱う利用へ広がるほど、境界を曖昧にしないことが重要になります。

Codex 0.154.0で確認できる変更

公式リリースには、--worktreeまたは/worktreeで新しいセッションや分岐したセッション用の分離されたチェックアウトを作り、後から閲覧や再開を行える実験的機能が記載されています。またWindowsセッションが背景のCodexサーバーを共有できるようになったことも示されています（出典: openai/codex 0.154.0）。これらは便利な機能ですが、作業場所が分かれたからといって、すべての場所へ書き込めるという意味ではありません。どのセッションがどのフォルダーを対象にしているかを、開始時に確かめてください。

Agents APIが示すサンドボックスの考え方

9月10日の公式発表では、OpenAIが管理するサンドボックス、利用者側の基盤、提携先の環境から、エージェントが動く場所を選べると説明されています。OpenAI管理のサンドボックスは、CodexやChatGPTを支える仕組みを使い、コードを実行し、ファイルを扱い、成果物を作るための環境です（出典: Introducing the Agents API）。これはローカルのCodex CLI設定をそのまま置き換える話ではありませんが、「モデルの賢さ」と「作業環境の境界」を分けて考える重要性を分かりやすく示しています。

時事情報を設定へ反映するときの注意

新しいリリースを読んだ直後は、便利そうな機能をすべて有効にしたくなります。しかしリリースノートが示すのは、版番号と変更点であり、手元のプロジェクトに適した権限まで決めるものではありません。版番号を確認し、現在のサンドボックスと対象フォルダーを記録し、短い読み取り作業を一度行ってから編集へ進みます。機能追加を利用するかどうかは、既存のコードやデータをどこまで触れる必要があるかで判断してください。

3つのサンドボックス設定を使い分ける

日常の選択肢は、read-only、workspace-write、danger-full-accessの三つです。前二つを中心に使い、最後の設定は目的と対象を明確に説明できる場合だけ検討します。CLIでは起動時に--sandboxを付けて指定でき、公式CLIリファレンスはworkspace-writeと--ask-for-approval on-requestを組み合わせる使い方を案内しています（出典: Codex CLIリファレンス）。ここでは、何を確認し、どの段階で次へ進むかを設定ごとに整理します。

Step 1: read-onlyで対象を読む

初めて触るリポジトリ、原因を調べるだけの依頼、変更案を比較したい段階ではread-onlyを選びます。Codexには「画面の表示が崩れる原因を調べ、変更せずに候補を説明して」と伝え、ファイル一覧、設定、テストの結果を読むところまでに限定します。起動例は次のとおりです。

codex --sandbox read-only --ask-for-approval on-request

この段階で編集を頼んでも、書き込み操作は境界で止まります。止まった場合は、失敗と決めつけず、読み取り結果を確認し、対象ファイルが本当に作業フォルダー内にあるかを調べます。調査結果に納得してから次の設定へ進むと、不要な変更を減らせます。

Step 2: workspace-writeで局所的に直す

修正対象が明確になり、テストや整形も同じ作業フォルダー内で完結するならworkspace-writeを選びます。公式リファレンス上、この設定は作業フォルダー内の書き込みを基本にし、追加の書き込み先や外部ネットワークを別項目で調整できます。起動例は次のとおりです。

codex --sandbox workspace-write --ask-for-approval on-request

依頼文には「src/login.tsと対応するテストだけを変更し、変更後に既存テストを実行して差分を説明する」のように、対象と確認方法を書きます。フォルダー内だから無制限に変更してよいと考えず、差分を読む時間を最初から予定に含めることがポイントです。

Step 3: 広い権限は理由を確認してから使う

依存関係の取得、システム側の設定、作業フォルダー外の資料参照など、workspace-writeでは足りない作業があります。その場合も、まず追加の読み取り先や書き込み先を個別に指定できないかを調べます。danger-full-accessはファイルとネットワークの境界を大きく外す設定なので、対象、目的、終了条件を自分で説明できる短い作業に限るべきです。公式リファレンスが示す値を使う場合も、広い権限を選んだことを記録し、作業後に通常の設定へ戻します。

承認設定とサンドボックスを組み合わせる

サンドボックスだけを厳しくしても、利用者が何を確認するかが曖昧なら安全性は十分ではありません。逆に承認を毎回求めても、どのフォルダーへ書き込めるかが広すぎれば、確認の負担が増えるだけです。Codexでは、サンドボックスが技術的な実行範囲を決め、承認設定が人に確認を求めるタイミングを決めます。この二つを別の軸として選ぶと、調査、局所修正、外部接続が必要な作業を落ち着いて切り替えられます。

on-requestを基本にする

--ask-for-approval on-requestは、コマンドを実行する前に確認が必要な場面でCodexを止める選択肢です。read-onlyなら不要な書き込みを境界で止め、workspace-writeなら書き込み可能な範囲を残しながら、想定外の操作に気づけます。確認画面が出たときは、コマンドの目的、対象パス、変更内容を読み、依頼した作業と一致しているかを見てから判断してください。表示されたコマンドを読まずに許可する習慣にすると、設定の意味が薄れます。

変更を許可する条件を文章で示す

Codexへ指示するときは、「何を変更してよいか」と「何を変更してはいけないか」を同じ依頼に書きます。たとえば対象をsrc/とtests/に限定し、設定ファイルや生成物には触れないと指定します。テストが失敗した場合は、原因を説明するところまでにして、追加修正は確認後に頼む方法もあります。境界を文章で示すと、承認画面に出た操作が依頼内容と一致するかを比較しやすくなります。

承認と広い権限を同時に緩めない

workspace-writeからdanger-full-accessへ変えるときに、承認もneverへ変えると、ファイル範囲と確認機会を同時に失います。原因が書き込み先の不足なら追加ディレクトリ、ネットワーク接続の不足ならその項目だけを検討し、二つの設定を一度に広げないでください。公式CLIリファレンスも、作業フォルダー内で済む作業にはworkspace-writeを使い、広い権限を避ける考え方を示しています。

Windowsでエージェントモードを確認する

Windowsでは、Codex CLI、PowerShell、Windows Terminal、ファイルシステムの権限が重なります。同じ「書き込めない」という症状でも、サンドボックスが拒否した場合、シェルがコマンドを解釈できない場合、対象フォルダーにアクセスできない場合では対処が違います。OpenAIはWindows向けサンドボックスの構築背景を説明する記事で、Codexが端末上でコマンドやファイルを扱うため、OSの制約と使いやすさを両立する必要があると説明しています（出典: Building a safe, effective sandbox to enable Codex on Windows）。まず版と状態を記録し、次に短い確認を行いましょう。

Step 1: CLIの版と現在の状態を記録する

PowerShellまたはWindows Terminalで版番号を確認し、Codexの会話内では/statusを実行します。公式CLIリファレンスによれば、/statusでは現在のモデル、承認方針、書き込み可能なルート、利用状況などを確認できます。版番号や状態を残しておけば、更新後に挙動が変わったとき、設定の変更と版の変更を分けて考えられます。

codex --version

Step 2: Windowsのサンドボックス設定を確認する

Windows版Codexで初期の制限付きサンドボックスを使っている場合、公式CLIリファレンスには/setup-default-sandboxが案内されています。会話画面でこのコマンドを入力すると、表示された管理者向けの設定手順に沿って、標準のWindowsサンドボックスを整えられます。表示されない場合は、現在の実行方式や版が対象かを確認し、管理者権限を無理に追加せず、まず/statusの結果を控えてください。

Step 3: 外部フォルダーは読み取り先を絞る

作業フォルダーの外にある資料を読む必要があるときは、Windows版の/sandbox-add-read-dirを使える場合があります。公式リファレンスは、既存の絶対パスを指定し、後続のサンドボックス内コマンドにそのディレクトリの読み取りを許可する操作として説明しています。ドライブ全体を指定せず、資料を置いた一つのフォルダーに絞ることで、誤読や不要な参照を減らせます。

/sandbox-add-read-dir C:\work\reference

Step 4: PowerShellの失敗と境界の拒否を分ける

コマンドが失敗したら、エラーメッセージにパスが拒否されたと出ているのか、PowerShellの文法や実行ファイルが見つからないのかを分けます。前者ならサンドボックスの読み取り・書き込み範囲を確認し、後者ならシェルの版やPATHを調べます。/statusで書き込み可能なルートを確認し、同じ短いコマンドを作業フォルダー内と外で比べると、境界による拒否かどうかを判断しやすくなります。

config.tomlで設定を保存する

毎回起動オプションを入力したくない場合は、Codexのconfig.tomlへ標準設定を置けます。ただし、設定ファイルを一度作ったら終わりではありません。個人設定、プロジェクト設定、管理側の制約、起動時の指定が重なり、後から読んだ人にとって現在の値が分かりにくくなることがあります。最初は一つの設定だけを置き、/statusで実際に適用された状態を確認してください。公式のConfiguration Referenceでは、値の意味と利用できる範囲が項目ごとに整理されています。

読み取り中心の標準設定

調査用の環境では、次のようにread-onlyを標準にすると、依頼を送っただけでファイルが変わる可能性を抑えられます。

sandbox_mode = "read-only"

編集したいときだけ、起動時の--sandbox workspace-writeで一時的に広げる方法もあります。設定を保存する場所を増やすより、まず「調査用」と「編集用」の使い分けを手順として決めるほうが、現在の状態を見失いにくくなります。

workspace-writeの書き込み範囲を補う

作業フォルダー内の編集に加えて、検証用の資料フォルダーへ書き込む必要があるときは、workspace-writeの追加ルートを検討できます。公式リファレンスの項目名に合わせると、例は次のようになります。

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false
writable_roots = ["C:/work/sample-output"]

この例では外部ネットワークを許可せず、追加の書き込み先を一つに限定しています。パスは実際の作業場所に合わせて変更し、存在しない場所や広すぎるドライブ直下を指定しないでください。設定を変えたら、書き込みを頼む前に/statusで反映結果を確認します。

設定の優先順位を記録する

同じ名前の値が複数の場所にある場合、どの設定が最後に適用されたかを推測しないことが重要です。設定を変更した日時、変更したファイル、起動時に付けたオプション、/statusで確認した結果を短く残します。Codex 0.154.0以降の新しいセッション機能を試すときも、セッションの場所と設定を一緒に記録してください。機能が増えたときほど、版番号と設定を同じメモで照合すると切り分けが容易になります。

用途別に選ぶ実践例

同じエージェントモードでも、依頼の目的によって適したサンドボックスは変わります。レビュー、バグ調査、局所修正、依存関係の確認を一つの設定で済ませようとすると、権限が広すぎるか、必要な作業が途中で止まります。ここでは、開発者がよく行う作業を「読んで判断する」「範囲を限定して直す」「外部接続を含む確認をする」に分け、依頼文と設定の組み合わせを考えます。

レビューと原因調査はread-only

差分を読んで問題点を挙げる、テストの失敗理由を調べる、利用しているライブラリの呼び出し箇所を探す、といった作業はread-onlyから始めます。「変更案は説明するが、ファイルは書き換えない」と明記すると、結果を読むことに集中できます。提案が妥当だと判断したら、別のターンでworkspace-writeへ切り替え、変更対象を明記して実施します。調査と変更を同じ権限で始めないことが、差分を小さく保つコツです。

バグ修正はworkspace-write

再現テスト、対象ファイルの修正、関連テストの実行までを作業フォルダー内で行うならworkspace-writeが合います。依頼には、再現方法、変更対象、実行するテスト、終了条件を書きます。テストが通った場合も、どのファイルが変わったか、意図しない変更がないかを確認してください。エージェントが複数の候補を試した場合は、最終的に採用した差分だけを残し、途中の変更をそのまま受け入れないようにします。

パッケージ確認はネットワークを別に考える

パッケージの情報を取得したり、外部サービスへ接続して動作を試したりする場合、書き込み範囲とネットワークの許可は別の論点です。workspace-writeのままネットワークを許可するのか、必要な資料を先に用意して接続なしで進めるのかを決めます。公式設定リファレンスのnetwork_accessはworkspace-write内の外向き通信を許可する項目です。必要な時間だけ有効にし、作業が終わったら元の設定へ戻す方針にすると、あとで状態を確認しやすくなります。

分離した作業場所では対象を再確認する

0.154.0のworktree対応を使う場合は、いま開いているセッションがどのチェックアウトを見ているのかを確認します。分離されているから安全だと決めつけず、パス、ブランチ、変更一覧を短く確認してから編集を始めてください。別の作業場所に結果が保存されると、元のフォルダーに反映されていないことを「失敗」と誤解しがちです。作業場所の確認とサンドボックスの確認を別々に行うことで、結果の所在を見失いません。

うまくいかないときの切り分け

サンドボックスは、問題が起きたときの手がかりも提供します。書き込みが拒否された、ネットワークが使えない、Windowsで設定が有効にならない、という症状を一つの「Codexの不具合」として扱わないことが大切です。版番号、実行入口、対象パス、現在のsandbox mode、承認方針を記録し、同じ短い操作を一つだけ変えて比較します。ここでは、よくある症状と確認の順番をまとめます。

書き込みが拒否された場合

まず対象パスが現在の作業フォルダー内にあるか、シンボリックリンクや別ドライブを経由していないかを確認します。workspace-writeでも、追加ルートに含まれない場所や保護されたファイルは書き込めない場合があります。/statusで書き込み可能なルートを確認し、対象を作業フォルダー内へ移すか、必要な一つのディレクトリだけを追加します。広い権限へ直ちに変更するのではなく、境界を狭いまま原因を特定してください。

ネットワークが使えない場合

workspace-writeを選んでいても、外部ネットワークが常に許可されるとは限りません。sandbox_workspace_write.network_accessの値と、組織やプロジェクト側の制約を確認します。ネットワークが不要なテストなら、事前に取得した資料やキャッシュを使い、接続なしで再現できるかを試します。接続が必要な場合は、対象と目的を明確にしてから一時的に設定を見直し、取得した内容を確認して次の作業へ進みます。

Windowsで標準設定が出ない場合

/setup-default-sandboxが表示されない、または実行後も状態が変わらない場合は、Codexの版、ネイティブWindows実行か別の環境経由か、管理者向け手順が完了したかを順に確認します。OpenAIのWindows向け解説は、OSの仕組みを利用して安全な実行境界を作る背景を説明しています。PowerShellのエラーとCodexの拒否を分けるため、同じコマンドを通常の端末で実行した結果と、Codex内で実行した結果を比較するのも有効です。

新しい版へ更新した後に挙動が変わった場合

Codexの版を更新した後は、モデルや依頼文を同時に変えず、同じ小さな確認を行います。codex --version、/status、対象パス、結果を記録し、設定ファイルの差分を確認してください。0.154.0のようにWindowsセッションや分離作業場所が追加された版では、入口や作業場所の違いが見え方に影響することがあります。新機能の名前だけを根拠に広い許可へ変えず、公式リリースと設定リファレンスを照合してから採用します。

まとめ：まず読む、次に狭く書く

Codexのエージェントモードを安心して使う要点は、エージェントに考えさせる範囲と、サンドボックスが許す操作範囲を分けることです。調査やレビューはread-only、対象が定まった修正とテストはworkspace-write、どうしても必要な例外だけを個別に検討します。承認設定をon-requestにし、/statusでモデル、書き込み可能な場所、承認方針を確認すれば、実際の状態と想定のずれに気づけます。

9月のCodex 0.154.0とAgents APIの発表は、作業場所の分離、長いセッション、サンドボックス基盤の重要性を改めて示しました。新しい機能を試すときほど、版番号、対象フォルダー、設定値、変更差分を一緒に記録してください。小さな読み取りから始め、必要な範囲だけを段階的に広げることが、エージェントの便利さを保ちながらコードとデータを守る現実的な使い方です。