# Codex サンドボックスと config.toml：承認・書き込み・ネットワーク

> Codex の sandbox と approval policy を分けて理解し、最小権限で file と network の境界を設定しながら Windows、WSL2、Linux、macOS の失敗を切り分けます。

- Source: https://www.aifreeapi.com/ja/posts/codex-config-toml
- Language: ja
- Published: 2026-08-15
- Updated: 2026-08-16
- Publisher: AI Free API (https://www.aifreeapi.com)

Codex のサンドボックスは local command の技術的な実行境界です。command が書き込める file と network access を制限します。`approval_policy` は別の制御で、境界を越える必要があるとき、いつ Codex が止まって確認するかを決めます。一方を変えても、もう一方が自動で変わるわけではありません。公式の [Sandbox documentation](https://learn.chatgpt.com/docs/sandboxing) によれば、Codex が起動する `git`、package manager、test runner も同じ境界を引き継ぎます。

通常の local development では `workspace-write` と `on-request` が出発点になります。workspace 内の作業は継続し、実際に境界を越えるときだけ approval を出せます。`read-only` は確認向けです。`danger-full-access` は filesystem と network の sandbox 制限を外すため、install failure や path mistake の一般的な直し方ではありません。また `approval_policy = "never"` は「確認しない」という意味であり、それだけで full access にはなりません。

その上で、個人用の既定値は `~/.codex/config.toml`、repository 固有の値は trusted project 内の `.codex/config.toml` と分けます。繰り返し使う mode は profile、一度だけ試す値は CLI override が向いています。1つの権限問題を直すために巨大な sample を貼ると、model、provider、network、MCP まで同時に変わり、原因を失います。

編集前には対象ファイルだけをバックアップしてください。1つの table を直すために `~/.codex` 全体を削除すると、認証状態、profiles、rules など正常な情報まで失う可能性があります。

## 「どのファイルか」より先に「誰の設定か」を決める

Codex の通常設定は、優先度の高い順に次のように解決されます。

1. CLI flag と `--config` override
2. trusted project の `.codex/config.toml`（現在のディレクトリに近いものが優先）
3. `--profile` で選択した profile ファイル
4. user config の `~/.codex/config.toml`
5. Unix の `/etc/codex/config.toml`（存在する場合）
6. built-in default

公式の [Configuration precedence](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence) にこの順序が示されています。user config を直しても変化しない場合、保存ミスとは限りません。上位の project、profile、CLI が値を上書きしている可能性があります。

![Codex の CLI、project、profile、user、system、default の優先順位](https://www.aifreeapi.com/posts/ja/codex-config-toml/img/ownership-board.webp)

設定の置き場所は次の基準で決めると整理できます。

| 目的 | 置き場所 | 判断理由 |
|---|---|---|
| 自分の標準 model、reasoning、通知、個人 MCP | user config | 複数 project で使う |
| 1つの repo の実行境界 | trusted project config | 方針を repo と一緒に扱う |
| read-only review などの作業モード | 独立 profile | base を重複させず切り替える |
| 一時的な検証 | CLI override | 永続設定に残さない |
| 組織が強制する制約 | managed requirements | user が回避できない境界にする |

ただし project config では、machine-local な provider、auth、profile 選択、notification、telemetry 系のキーを上書きできません。現在の対象には `model_provider`、`model_providers`、`profile`、`otel` などが含まれます。正確な一覧は最新の [Configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference#configtoml) を使い、該当キーは user レベルへ置きます。

## sandbox と approval を2軸で選ぶ

個人設定の安全な出発点は、たとえば次の2行です。

```toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

役割を分けると設定を誤りにくくなります。

| Control | 決めること | 決めないこと |
|---|---|---|
| `sandbox_mode` | command が触れられる filesystem と network | 境界で approval が表示されるか |
| `approval_policy` | いつ止まって確認するか | その action が技術的に可能か |
| `approvals_reviewer` | eligible approval を誰が確認するか | sandbox 自体の範囲 |

現在の公式定義では、共通の sandbox mode は `read-only`、`workspace-write`、`danger-full-access`、approval policy は `untrusted`、`on-request`、`never` です。CLI では `/permissions`、IDE と desktop app では composer 下の control から active permissions を変更できます。ただし表示項目は version や organization policy で変わるため、古い screenshot ではなく [How permissions work](https://learn.chatgpt.com/docs/sandboxing#how-permissions-work) を確認します。

必要なのが別 repository への書き込みだけなら、host 全体を開かず writable root を追加できます。

```toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
writable_roots = ["/absolute/path/to/second-repo"]
network_access = false
```

home directory や disk root を指定すると境界が広すぎます。`network_access` は workspace-write sandbox 内の subprocess が外向き network を使えるかという設定です。web search、apps、MCP、remote browser とは別 control です。browser で page を読めても、`npm install` や test process が internet に接続できる証明にはなりません。

## OS ごとに sandbox の成立条件が違う

考え方は同じでも enforcement は platform-native です。公式の [Getting started](https://learn.chatgpt.com/docs/sandboxing#getting-started) を基準にすると、最初の確認点は次のように変わります。

| Environment | 実装 | permissions を広げる前に確認する点 |
|---|---|---|
| macOS | built-in Seatbelt | target path が workspace 内か |
| native Windows | Codex native Windows sandbox | sandbox setup と device policy |
| WSL2 | Linux sandbox implementation | WSL2 と `bubblewrap` |
| Linux | `bubblewrap` と OS isolation | `bwrap`、user namespace、AppArmor |

Ubuntu/Debian では distribution package を先に入れます。

```bash
sudo apt install bubblewrap
```

Fedora では次です。

```bash
sudo dnf install bubblewrap
```

install 後も user namespace や AppArmor warning が残る場合、system-wide restriction を先に無効化せず、公式ページの distribution-specific 手順を確認します。Docker 内では outer container が namespace や seccomp を妨げることもあります。外側の isolation を確認してから container 内の Codex mode を判断してください。bare host で同じ full access を選ぶこととは risk が異なります。

## Profile は main config の table ではない

read-only の確認作業を繰り返すなら、別ファイルに差分だけを書きます。

```toml
# ~/.codex/read-review.config.toml
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "read-only"
```

```bash
codex --profile read-review
```

profile は差分だけを持たせます。format は client version で変わりうるため、古い `[profiles.name]` sample を使う前に current [Advanced Config: Profiles](https://learn.chatgpt.com/docs/config-file/config-advanced#profiles) を確認します。

## MCP は「読めた」と「動いた」を分ける

STDIO server は local process として起動します。

```toml
[mcp_servers.docs]
command = "docs-server"
args = ["--read-only"]
env_vars = ["DOCS_TOKEN"]
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true
```

streamable HTTP server では URL と credential の参照方法を分けます。

```toml
[mcp_servers.tasks]
url = "https://mcp.example.internal/mcp"
bearer_token_env_var = "TASKS_MCP_TOKEN"
enabled = true
```

実 token を repo、記事、サポート用 screenshot に書かないでください。OpenAI の [MCP documentation](https://learn.chatgpt.com/docs/extend/mcp) は STDIO、streamable HTTP、OAuth、environment header、timeout、tool allow/deny を個別に説明しています。

まず installed CLI が認識した定義を確認します。

```bash
codex mcp list
codex mcp --help
```

OAuth 対応 server では `codex mcp login <server-name>` も使えます。ただし list に表示されることは、command の存在、URL への到達、認証成功、tool の正常動作までは証明しません。

## 復旧は一番手前の未確認ポイントから

最近の Codex CLI には `--strict-config` と `doctor` がありますが、古い version では利用できない場合があります。最初に local help を見ます。

```bash
codex --version
codex --help
codex doctor --help
```

対応している場合は、次の read-only check が使えます。

```bash
codex --strict-config doctor --summary
```

strict config は未認識 field を error にし、doctor は installation、config、auth、runtime の問題を調べます。成功しても provider request や MCP tool の成功を保証するものではありません。

![Codex 設定を file、TOML、precedence、permission、provider、MCP の順に復旧するフロー](https://www.aifreeapi.com/posts/ja/codex-config-toml/img/recovery-flow.webp)

症状ごとに入口を変えます。

| 症状 | 最初に確認すること |
|---|---|
| 1つの repo だけ値が無視される | project trust と近い `.codex/config.toml` |
| CLI は動くが IDE は credential 不足 | IDE process が environment variable を受け取っているか |
| unknown field で起動しない | client version と current reference |
| repo は読めるが書けない | active sandbox と target workspace root |
| package install や API test だけ network failure | subprocess network、proxy/DNS、approval |
| native Windows で sandbox setup が失敗 | native/WSL2 route と device policy |
| model を変えても route が変わらない | `model_provider`、profile、project、CLI override |
| MCP は表示されるが使えない | command/URL、auth、timeout、個別 tool |
| managed device で強い権限を選べない | 組織の `requirements.toml` |

Business/Enterprise の managed environment では、`requirements.toml` が approval、permission profile、web search、MCP allowlist、plugin、feature を制限できます。user の値が強制ルールに反すると、Codex は許可された値へ fallback して通知できます。詳細は [Admin-enforced requirements](https://learn.chatgpt.com/docs/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml) にあります。別の local file に同じ値を書いても解決しません。

1回の変更には1つの観測可能な目的を持たせてください。まず read、次に workspace 内の1つの write、その後に project-owned test を確認し、本当に必要な directory や network だけを試します。これで「config が読まれていない」「sandbox が正しく拒否した」「approval が出せない」「OS が sandbox を作れない」を分離できます。

設定ではなく coding agent の選択が目的なら、別の [Claude Code と Codex の比較](/ja/posts/claude-code-vs-codex) が適切です。