Codexの権限プロファイル:安全なエージェント実行のためのconfig.toml設定例

Codexの権限プロファイルは、エージェントのコマンドが何を読み取り、何を書き込み、どこにアクセスできるかを決めます。ここでは、検証済みのconfig.toml設定例を紹介します。インターネットへのオープンなアクセスなしでApidog CLIを実行するAPI作業用プロファイルも含まれます。

INEZA Felin-Michel

INEZA Felin-Michel

20 11月 2026

Codexの権限プロファイル:安全なエージェント実行のためのconfig.toml設定例

Apidog エンタープライズ

オンプレミスデプロイ

SSO & RBAC

SOC 2 準拠

Apidog Enterpriseを見る

Codexのパーミッションプロファイルとは、config.toml に記述する名前付きポリシーで、マシン上でCodexが実行するコマンドが何を読み取り、書き込み、ネットワーク上でどこに到達できるかを決めるものです。default_permissions で1つ選択し、組み込みプロファイル(:read-only、:workspace、:danger-full-access)をベースに、read、write、deny のパスとドメインの許可リストを追加していきます。

このガイドでは、よくある構成向けにそのままコピーして使える config.toml のサンプルを紹介します。API開発向けのサンプルも含まれており、インターネットを開放することなく、コーディングエージェントが自分のAPIホストに対して Apidog CLI のテストを実行できるようにします。

Codexのパーミッションプロファイルとは?

パーミッションプロファイルは、Codex用の再利用可能なサンドボックスポリシーです。ファイルシステムのルール(コマンドが読み取り・書き込み・アクセス禁止できるパス)と、ネットワークのルール(コマンドがネットワークに到達できるか、どのドメインに到達できるか)を組み合わせたものです。Codexはこれを、macOSではSeatbelt、LinuxとWSLではbubblewrapとseccomp、WindowsではMXCを使って強制します。

OpenAIはこの設計を、2026年11月18日公開のInside the Codex sandboxで説明しています。作業をコンテナに移すのではなく、Codexは既存の環境内でコマンドを制約するため、ネイティブなツールチェーンもそのまま動作します。

Codexには3つの組み込みプロファイルが用意されています:

プロファイル ファイルシステム ネットワーク
:read-only コマンドは読み取り可能、書き込み不可 オフ
:workspace ワークスペースルートと一時ディレクトリ内への書き込みが可能。.git、.agents、.codex、.aws は読み取り専用のまま オフ
:danger-full-access ローカルサンドボックスの制限なし 全開放、直接接続

パーミッションのドキュメントでは、この機能はまだベータ版と表記されているため、リリース間でキーが変わる可能性があります。

config.toml のどこに permissions テーブルを書くか

プロファイルは ~/.codex/config.toml(またはプロジェクトやシステムのレイヤー)に記述します。重要なトップレベルの要素は2つです:

ここでつまずきやすいルールが1つあります。パーミッションプロファイルは、従来のサンドボックス設定と併用できません。読み込まれた設定ファイルのいずれかに sandbox_mode が含まれている場合、または --sandbox を渡した場合、Codexは古い設定を使用して default_permissions を無視します。切り替える前に sandbox_mode と [sandbox_workspace_write] を削除してください。

プロファイルは通常の設定の優先順位モデルに従います。テーブルは再帰的にマージされるため、チームの設定で組織のプロファイルにドメインを1つ、あるいはパスを1つ追加する際に、全体を書き直す必要はありません。

ファイルシステムのルール:read、write、deny

各ファイルシステムエントリは、パスを read、write、deny のいずれかに対応付けます。より具体的なパスが広いパスよりも優先され、2つのエントリが同じパスを対象とする場合は、deny が write より、write が read より優先されます。

よく使うパスの形式は次のとおりです:

組み込みのセーフガードを再構築せずに継承するには、extends を使います。以下は :workspace のデフォルトを維持しつつ、機密情報をロックダウンするプロファイルです:

default_permissions = "dev"

[permissions.dev]
description = "Workspace edits, secrets denied, no network."
extends = ":workspace"

[permissions.dev.filesystem]
"~/build-cache" = "write"

[permissions.dev.filesystem.":workspace_roots"]
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"

:workspace_roots 下のルールはすべてのルートに適用されるため、secrets は各プロジェクトルート内の secrets フォルダを意味します。プロファイルは :read-only、:workspace、または別の名前付きプロファイルを拡張できます。:danger-full-access は拡張できません。

Linux、WSL、ネイティブWindowsでは、範囲を限定しない ** のdenyグロブを使う場合、サンドボックスが起動する前にCodexが展開できるよう、[permissions.<name>.filesystem] 下に glob_scan_max_depth(1 以上)が必要になることがあります。

Diagram of how a Codex permission profile filters filesystem paths and network requests before a command runs

ネットワークのルール:オフ、開放、許可リスト

ネットワークには3つの状態があり、2つの設定で制御されます:

  1. ネットワークオフ(enabled = false、:workspace のデフォルト):コマンドはネットワークに到達できません。
  2. ネットワークオン、プロキシオフ:コマンドは直接、制限なくアクセスできます。ドメインのルールは無視されます。
  3. ネットワークオン、プロキシオン:トラフィックはCodexのネットワークプロキシを経由し、プロファイルのドメインルールが適用されます。

注意すべきは2番目の状態です。permissions.<name>.network.enabled = true を設定しても、プロキシは起動しません。トップレベルに以下も必要です:

[features]
network_proxy = true

ドメインパターンでは、完全一致のホスト(api.example.com)、サブドメインのみを対象とする *.example.com、アペックスとサブドメインを対象とする **.example.com、そして許可専用のグローバルワイルドカードとして * が使えます。denyエントリはallowエントリを上書きし、allow エントリがない状態でプロキシが有効な場合は、すべての外部通信がブロックされます。

プロキシが有効な場合、ローカルおよびプライベートネットワークのターゲットもデフォルトでブロックされます。ローカルサービスに到達するには、"localhost" = "allow" や "127.0.0.1" = "allow" のように、リテラルのホストを許可リストに追加します。

API作業向けのCodexパーミッションプロファイル

以下はAPI開発向けにテストしたプロファイルです。ワークスペース内のコードを編集し、.env ファイルや secrets フォルダを決して読み取らず、あなたのAPIホストとApidogにのみ到達できます:

default_permissions = "api-work"

[features]
network_proxy = true

[permissions.api-work]
description = "Workspace edits, no secrets, API hosts only."
extends = ":workspace"

[permissions.api-work.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"secrets" = "deny"

[permissions.api-work.network]
enabled = true

[permissions.api-work.network.domains]
"api.your-company.com" = "allow"      # the API under test
"staging-api.your-company.com" = "allow"
"**.apidog.com" = "allow"             # Apidog CLI and its API

2つのホストは、テストが実際にアクセスするホストに置き換えてください。Apidog CLIはあなたのマシンからテスト対象のAPIへテストリクエストを送信するため、Apidogだけでなく、そのAPIホストも許可リストに追加する必要があります。ローカルサーバーをテストする場合は、"localhost" = "allow" を追加してください。

パッケージのインストールは、セッション内ではなくセッション前に済ませてください。npm install -g apidog-cli@latest を実行するには registry.npmjs.org へのアクセスが必要ですが、このプロファイルは意図的にそれをブロックしています。

テスト実行でありがちな落とし穴を1つ紹介します。プロキシアプリやVPNをフェイクIP DNSモードで使っているMacでは、許可されたすべてのホストが 198.18.x.x アドレスに解決されました。ローカル/プライベートのガードがそれらをプライベートとみなしてブロックし、Codexは「local/private network addresses are blocked by the sandbox policy」と報告しました。[permissions.api-work.network] 下に allow_local_binding = true を追加すると解決しましたが、これにより許可リストのホスト名がプライベートアドレスに解決された場合も通すようになるため、必要なときだけ設定してください。

codex sandbox でプロファイルをテストする

何かが実際にブロックされるのを確認するまでは、プロファイルを信頼しないでください。codex sandbox コマンドは、指定したプロファイルで任意のコマンドを実行し、カレントディレクトリをワークスペースルートとして扱います:

codex sandbox --permission-profile api-work -- cat README.md .env

上記のプロファイルで実行したところ、まずREADMEが表示され、続けて以下のメッセージが出ました:

cat: .env: Operation not permitted

ワークスペース外への書き込みも同様に失敗し(Operation not permitted)、ワークスペース内の新しいファイルは作成できました。ネットワークについては、許可リストにないホストをプロキシがブロックするかを確認してください:

codex sandbox -P api-work -- curl -sI https://example.org

プロキシは 403 Forbidden と x-proxy-error: blocked-by-allowlist を返し、一方 apidog.com は 200 を返しました。macOSでは、コマンド終了後にSeatbeltの拒否を出力する --log-denials を追加できます。

codex sandbox を使って、Codexが単独ではサンドボックス化しないプロセスをラップすることもできます。OpenAIの記事では、config.toml 内のstdio MCPサーバーはサンドボックスなしで実行されると述べており、"~/mcp-data" = "write" と network.enabled = false を設定した memory-mcp プロファイルで、サーバーの npx コマンドをラップする例を紹介しています。

/permissions でセッション中にプロファイルを切り替える

Codex CLIで /permissions と入力するとピッカーが開きます。名前付きプロファイルがある場合は、説明とともに一覧表示されます。直接選択するには:

/permissions api-work --approval-policy=on-request --reviewer=user

これで現在のセッションのプロファイルが設定され、承認リクエストはあなた宛てに送られます。プロファイルと承認は別々の制御です。プロファイルはサンドボックス化されたコマンドが何に触れられるかを決め、承認ポリシーはCodexがその範囲を出る前にいつ確認するかを決めます。その他のセッションコマンドについては、CLIコマンドリファレンスに一覧があります。

Apidog CLIでCodexにAPIをテストさせる

api-work を有効にすると、Codexはインターネットを開放せずに実際のAPIテストを実行できます。Apidog CLI は、エンドポイント、テストケース、テスト実行のためのコマンドをエージェントに提供し、エージェントが読めるJSON出力を返します。セットアップはサンドボックスの外で一度だけ行います:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

次に、Codexに1つのプロンプトを渡します:

Using Apidog CLI, create a test case in project <projectId> for
GET /orders/{id} on endpoint <endpointId> that asserts a 200 status and
a non-empty "items" array. Run it against environment <envId> and
summarize any failures.

Codexはペイロードのスキーマを読み取り、JSONを検証して、テストケースを実行します:

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog test-case run --project <projectId> --endpoint <endpointId> -e <envId> -r cli,json

私たちのテストでは、**.apidog.com のみを許可リストにした api-work サンドボックス内で、apidog auth status と apidog project list の両方が実行できました。トークンは ~/.apidog に保存され、プロファイルは読み取りはできても変更はできません。詳細な手順については、CodexでApidog CLIを使う方法を参照してください。同じ実行をCIパイプラインに移す場合は、-r cli,json を -r junit に置き換えます。ApidogのFreeプランは最大4ユーザーまで利用できます。

Flow diagram of Codex running Apidog CLI inside the api-work profile, with the network proxy allowing the API host and Apidog and blocking other domains

プロファイルを信頼する前に知っておくべき制限

パーミッションプロファイルは影響範囲を縮小しますが、それだけでエージェントが安全になるわけではありません。ドキュメントとOpenAIの記事では、次のような制限が挙げられています:

Codexサンドボックスを回避するワークアラウンドを使ったことがあるなら、狭いカスタムプロファイルの方が通常はクリーンな解決策です。マシン全体でポリシーを適用する必要があるチームは、Codexセキュリティクックブックと、管理された allowed_permission_profiles を参照してください。

FAQ

Codexのデフォルトのパーミッションプロファイルは?

頼るべきデフォルトはありません。ドキュメントでは、予測可能な動作のために default_permissions を明示的に設定することを推奨しています。ほとんどのコーディング作業では、:workspace が妥当なベースです。ワークスペースルートと一時ディレクトリへの書き込みが可能で、ネットワークはオフです。

ドメインのルールが無視されるのはなぜ?

多くの場合、features.network_proxy がありません。network.enabled = true でプロキシがない場合、コマンドは直接、制限なくネットワークにアクセスできます。また、読み込まれた設定のいずれかで sandbox_mode が設定されていないか確認してください。設定されていると、プロファイルが完全に無効になります。

Codexが.envファイルを読まないようにするには?

[permissions.<name>.filesystem.":workspace_roots"] の下に "**/*.env" = "deny" を追加します。Linux、WSL、Windowsでは、範囲を限定しない ** パターン用に glob_scan_max_depth を設定し、すでに実行中のプロセスには新たなマッチが追加されないことに注意してください。

Codexのパーミッションプロファイルでlocalhostを許可できますか?

できます。"localhost" = "allow" や "127.0.0.1" = "allow" のように、リテラルのホストを許可リストに追加します。allow_local_binding = true は、許可リストのホスト名がローカルまたはプライベートアドレスに解決される場合にのみ設定してください。

パーミッションプロファイルはMCPサーバーをサンドボックス化しますか?

いいえ。config.toml のstdio MCPサーバーはサンドボックスなしで起動します。サーバーのコマンドを専用のプロファイルとともに codex sandbox --permission-profile <name> -- でラップしてください。

--sandbox フラグとプロファイルを併用できますか?

いいえ。--sandbox を渡すか sandbox_mode を設定すると、Codexは default_permissions の代わりに古いサンドボックス設定を使用します。セッションごとにどちらか一方のシステムを選んでください。

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる