このドキュメントは ~/.codex/config.toml で設定可能な全ての項目を詳しく説明します。

はじめに

Codex CLIは、OpenAIが提供するローカル実行型のコーディングエージェントです。このツールの動作は、ホームディレクトリに配置する設定ファイル ~/.codex/config.toml によって細かくカスタマイズできます。

このドキュメントについて

本ドキュメントでは、Codex CLI v0.46.0 で利用可能な全ての設定項目を網羅的に解説しています。各設定項目には以下の情報を記載しています：

型: 設定値のデータ型（文字列、数値、ブール値など）
デフォルト値: 設定を省略した場合の既定値
説明: 設定項目の役割と動作
例: 実際の設定記述例

設定ファイルの場所

Codexの設定ファイルは、デフォルトで以下の場所に配置されます：

~/.codex/config.toml

CODEX_HOME 環境変数を設定している場合は、$CODEX_HOME/config.toml が使用されます。

設定の優先順位

Codexは複数の方法で設定を指定でき、以下の優先順位で適用されます：

コマンドライン引数（最高優先度）
- 例: codex --model gpt-5 --approval-policy never
- 例: codex --config model=gpt-5
アクティブプロファイル
- --profile フラグまたは config.toml の profile 設定
config.toml のルートレベル設定
- 設定ファイルに直接記述された値
デフォルト値（最低優先度）
- Codex CLI に組み込まれた既定値

目次

基本設定
モデル設定
承認ポリシー
サンドボックス設定
シェル環境ポリシー
MCPサーバー設定
モデルプロバイダー設定
プロファイル設定
履歴設定
通知設定
TUI設定
OpenTelemetry設定
ツール設定
フィーチャーフラグ
プロジェクト設定
その他の設定

基本設定

`model`

型: 文字列
デフォルト: "gpt-5-codex" (macOS/Linux), "gpt-5" (Windows)
説明: Codexが使用するモデル

例:

model = "gpt-5"
model = "gpt-5-codex"
model = "claude-3-5-sonnet"

`review_model`

型: 文字列
デフォルト: "gpt-5-codex"
説明: /review コマンド専用のモデル
例:
```
review_model = "gpt-5"
```

`model_provider`

型: 文字列
デフォルト: "openai"
説明: model_providers マップで定義されたプロバイダーのキー

例:

model_provider = "openai"
model_provider = "anthropic"
model_provider = "ollama"

モデル設定

`model_context_window`

型: 数値（オプション）
デフォルト: モデルから自動推論
説明: モデルのコンテキストウィンドウサイズ（トークン数）
例:
```
model_context_window = 200000
```

`model_max_output_tokens`

型: 数値（オプション）
デフォルト: モデルから自動推論
説明: 最大出力トークン数
例:
```
model_max_output_tokens = 16000
```

`model_auto_compact_token_limit`

型: 数値（オプション）
デフォルト: なし（自動コンパクトなし）
説明: 自動コンパクトをトリガーするトークン使用量の閾値

例:

model_auto_compact_token_limit = 150000

`model_reasoning_effort`

型: 列挙型（オプション）
値: "minimal", "low", "medium", "high"
デフォルト: なし
説明: Responses APIでのreasoning effort設定
例:
```
model_reasoning_effort = "high"
```

`model_reasoning_summary`

型: 列挙型（オプション）
値: "auto", "concise", "detailed", "none"
デフォルト: "auto"
説明: reasoningサマリーの詳細度
例:
```
model_reasoning_summary = "detailed"
```

`model_verbosity`

型: 列挙型（オプション）
値: "low", "medium", "high"
デフォルト: なし
説明: GPT-5モデルのtext.verbosity設定
例:
```
model_verbosity = "medium"
```

`model_supports_reasoning_summaries`

型: ブール値（オプション）
デフォルト: false
説明: reasoningサマリーサポートを強制的に有効化

例:

model_supports_reasoning_summaries = true

`model_reasoning_summary_format`

型: 列挙型（オプション）
値: "none", "experimental"
デフォルト: "none"
説明: reasoningサマリーフォーマットを強制設定

例:

model_reasoning_summary_format = "experimental"

承認ポリシー

`approval_policy`

型: 列挙型（オプション）
値: "untrusted", "on-failure", "on-request", "never"
デフォルト: "untrusted"
説明: コマンド実行時の承認ポリシー
詳細:
- "untrusted": すべてのコマンドで承認を要求
- "on-failure": コマンドが失敗した場合のみ承認を要求
- "on-request": モデルが明示的に要求した場合のみ承認
- "never": 承認を要求しない（自動実行）
例:
```
approval_policy = "on-failure"
```

サンドボックス設定

`sandbox_mode`

型: 列挙型（オプション）
値: "read-only", "workspace-write", "danger-full-access"
デフォルト: "read-only"
説明: OSレベルのサンドボックスポリシー
詳細:
- "read-only": ファイル読み取りのみ、編集・コマンド実行は承認が必要
- "workspace-write": ワークスペース内の読み書きとコマンド実行が可能
- "danger-full-access": 全ディスクとネットワークへのアクセスが可能（危険）
例:
```
sandbox_mode = "workspace-write"
```

`sandbox_workspace_write`

型: テーブル（オプション）
説明: workspace-write モード時の詳細設定
サブフィールド:

`sandbox_workspace_write.writable_roots`

型: 配列（文字列）
デフォルト: []
説明: 追加の書き込み可能ルート

例:

[sandbox_workspace_write]
writable_roots = ["/tmp", "/var/cache"]

`sandbox_workspace_write.network_access`

型: ブール値
デフォルト: false
説明: ネットワークアクセスを許可

例:

[sandbox_workspace_write]
network_access = true

`sandbox_workspace_write.exclude_tmpdir_env_var`

型: ブール値
デフォルト: false
説明: $TMPDIR を書き込み可能ルートから除外

例:

[sandbox_workspace_write]
exclude_tmpdir_env_var = true

`sandbox_workspace_write.exclude_slash_tmp`

型: ブール値
デフォルト: false
説明: /tmp を書き込み可能ルートから除外

例:

[sandbox_workspace_write]
exclude_slash_tmp = true

シェル環境ポリシー

`shell_environment_policy`

型: テーブル
説明: shell または local_shell ツール実行時の環境変数ポリシー
サブフィールド:

`shell_environment_policy.inherit`

型: 列挙型（オプション）
値: "all", "core", "none"
デフォルト: "all"
説明: 環境変数の継承ポリシー
詳細:
- "all": 親プロセスの環境を完全に継承
- "core": HOME, PATH, USER などのコア変数のみ継承
- "none": 環境変数を継承しない

例:

[shell_environment_policy]
inherit = "core"

`shell_environment_policy.ignore_default_excludes`

型: ブール値（オプション）
デフォルト: false
説明: true にすると、KEY, SECRET, TOKEN を含む変数名の除外をスキップ

例:

[shell_environment_policy]
ignore_default_excludes = true

`shell_environment_policy.exclude`

型: 配列（文字列、オプション）
デフォルト: []
説明: 除外する環境変数名のglobパターン（大文字小文字を区別しない）

例:

[shell_environment_policy]
exclude = ["AWS_*", "AZURE_*", "*_SECRET"]

`shell_environment_policy.set`

型: テーブル（文字列キー・値、オプション）
デフォルト: {}
説明: 明示的に設定する環境変数

例:

[shell_environment_policy]
set = { PATH = "/usr/bin", MY_FLAG = "1" }

`shell_environment_policy.include_only`

型: 配列（文字列、オプション）
デフォルト: []
説明: 空でない場合、パターンにマッチする変数のみ保持（ホワイトリスト）

例:

[shell_environment_policy]
include_only = ["PATH", "HOME", "USER"]

`shell_environment_policy.experimental_use_profile`

型: ブール値（オプション）
デフォルト: false
説明: シェルプロファイルを使用してコマンドを実行

例:

[shell_environment_policy]
experimental_use_profile = true

完全な例:

[shell_environment_policy]
inherit = "none"
set = { PATH = "/usr/bin", MY_VAR = "value" }

MCPサーバー設定

`mcp_servers`

型: テーブル（マップ）
説明: Model Context Protocol (MCP) サーバーの定義
キー: サーバー名（任意の文字列）

STDIO サーバー

[mcp_servers.server_name]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
env = { "API_KEY" = "value" }
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 60

フィールド:

command: 起動コマンド（必須）
args: コマンド引数（オプション）
env: 環境変数（オプション）
enabled: サーバーを有効化（デフォルト: true）
startup_timeout_sec: 起動タイムアウト（秒、デフォルト: 10）
tool_timeout_sec: ツール実行タイムアウト（秒、デフォルト: 60）

Streamable HTTP サーバー

experimental_use_rmcp_client = true

[mcp_servers.figma]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_TOKEN"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 30

フィールド:

url: サーバーURL（必須）
bearer_token_env_var: Bearer トークンを含む環境変数名（オプション）
enabled: サーバーを有効化（デフォルト: true）
startup_timeout_sec: 起動タイムアウト（秒）
tool_timeout_sec: ツール実行タイムアウト（秒）

`mcp_oauth_credentials_store`

型: 列挙型（オプション）
値: "auto", "keyring", "file"
デフォルト: "auto"
説明: MCP OAuth認証情報の保存先
詳細:
- "keyring": OSのキーリングサービスを使用
- "file": $CODEX_HOME/.credentials.json に保存
- "auto": キーリングが利用可能ならキーリング、それ以外はファイル

例:

mcp_oauth_credentials_store = "keyring"

モデルプロバイダー設定

`model_providers`

型: テーブル（マップ）
説明: カスタムモデルプロバイダーの定義
キー: プロバイダーID（model_provider で参照）

[model_providers.custom_openai]
name = "カスタムOpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"  # または "chat"
query_params = { "api-version" = "2024-02-15-preview" }
http_headers = { "X-Custom-Header" = "value" }
env_http_headers = { "Authorization" = "CUSTOM_AUTH_ENV_VAR" }
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

フィールド:

name: 表示名（必須）
base_url: API のベースURL（必須）
env_key: APIキーを含む環境変数名（オプション）
wire_api: プロトコル（"chat" または "responses"、デフォルト: "chat"）
query_params: 追加のクエリパラメータ（オプション）
http_headers: 静的HTTPヘッダー（オプション、APIキーの直接指定に使用可能）
env_http_headers: 環境変数から読み込むヘッダー（オプション）
request_max_retries: HTTPリクエストの最大リトライ回数（デフォルト: 4）
stream_max_retries: SSEストリームの最大リトライ回数（デフォルト: 5）
stream_idle_timeout_ms: SSEアイドルタイムアウト（ミリ秒、デフォルト: 300000）

APIキーを直接指定する方法

環境変数を使わずに、config.toml に直接APIキーを記述する方法が3つあります：

方法1: http_headers で Authorization ヘッダーを直接指定

最も一般的な方法です。env_key を省略し、http_headers で Authorization ヘッダーを直接指定します：

[model_providers.my_provider]
name = "My Custom Provider"
base_url = "https://api.example.com/v1"
wire_api = "chat"
http_headers = { "Authorization" = "Bearer sk-your-api-key-here" }

方法2: http_headers でカスタムヘッダーを指定

プロバイダーが Authorization 以外のヘッダーを使用する場合：

[model_providers.custom_api]
name = "Custom API"
base_url = "https://api.example.com"
http_headers = { "X-API-Key" = "your-api-key-here" }

方法3: ~/.codex/auth.json にAPIキーを保存（OpenAI専用）

OpenAI APIキーのみ、auth.json ファイルに保存できます：

# コマンドでログイン
codex login --api-key sk-your-openai-key

# または手動で作成
cat > ~/.codex/auth.json << 'EOF'
{
  "openai_api_key": "sk-your-openai-key"
}
EOF

この方法は model_providers.openai で env_key が設定されていても、auth.json の値が優先されます。

⚠️ セキュリティ上の注意

config.toml に直接APIキーを記述する場合：

ファイル権限に注意: config.toml は通常 600 (所有者のみ読み書き可能) に設定してください
```
chmod 600 ~/.codex/config.toml
```
バージョン管理に含めない: プロジェクトの config.toml をGitにコミットしないでください
推奨される方法: セキュリティ上、環境変数（env_key）の使用を推奨します
```
export MY_API_KEY="sk-your-key"
```
```
[model_providers.my_provider]
env_key = "MY_API_KEY"
```

プロファイル設定

`profile`

型: 文字列（オプション）
説明: デフォルトで使用するプロファイル名
例:
```
profile = "gpt5"
```

`profiles`

型: テーブル（マップ）
説明: 設定値のグループを定義（--profile で切り替え）
キー: プロファイル名

[profiles.gpt5]
model = "gpt-5"
model_provider = "openai"
approval_policy = "never"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"
model_verbosity = "medium"
chatgpt_base_url = "https://chatgpt.com"
experimental_instructions_file = "/path/to/instructions.md"
include_plan_tool = true
include_apply_patch_tool = true
include_view_image_tool = true
experimental_use_unified_exec_tool = false
experimental_use_exec_command_tool = true
experimental_use_rmcp_client = true
experimental_use_freeform_apply_patch = true
tools_web_search = true
tools_view_image = true

[profiles.gpt5.features]
unified_exec = false
streamable_shell = true
rmcp_client = true
plan_tool = true
apply_patch_freeform = true
view_image_tool = true
web_search_request = true

プロファイルで設定可能なフィールド:

モデル関連: model, model_provider, model_reasoning_effort, model_reasoning_summary, model_verbosity
ポリシー: approval_policy
ツール: include_plan_tool, include_apply_patch_tool, include_view_image_tool
実験的機能: experimental_* フラグ
フィーチャー: features テーブル

履歴設定

`history`

型: テーブル
説明: ~/.codex/history.jsonl への書き込み設定

[history]
persistence = "save-all"  # または "none"
max_bytes = 1000000       # 現在未実装

フィールド:

persistence: 履歴の永続化ポリシー
- "save-all": すべての履歴を保存（デフォルト）
- "none": 履歴を保存しない
max_bytes: 履歴ファイルの最大サイズ（バイト、現在未実装）

通知設定

`notify`

型: 配列（文字列、オプション）
説明: イベント発生時に実行する外部プログラム

例:

notify = ["python3", "/Users/name/.codex/notify.py"]
notify = ["notify-send", "Codex"]

動作:

プログラムにJSON形式の引数が渡される
現在サポートされるイベント: "agent-turn-complete"

JSON例:

{
  "type": "agent-turn-complete",
  "thread-id": "b5f6c1c2-1111-2222-3333-444455556666",
  "turn-id": "12345",
  "input-messages": ["タスク内容"],
  "last-assistant-message": "完了メッセージ"
}

TUI設定

`tui`

型: テーブル
説明: TUI (Terminal User Interface) 固有の設定

[tui]
notifications = true
# または
notifications = ["agent-turn-complete", "approval-requested"]

フィールド:

notifications: デスクトップ通知の設定
- true: すべての通知を有効化
- false: 通知を無効化（デフォルト）
- ["agent-turn-complete", "approval-requested"]: 特定の通知タイプのみ有効化

注意:

OSC 9エスケープコードを使用
macOS Terminal.appとVS Codeターミナルは非対応
iTerm2、Ghostty、WezTermは対応

OpenTelemetry設定

`otel`

型: テーブル（オプション）
説明: OpenTelemetryテレメトリーの設定

[otel]
environment = "staging"
log_user_prompt = false
exporter = "none"  # または以下のいずれか

フィールド:

`otel.environment`

型: 文字列
デフォルト: "dev"
説明: 環境タグ（dev/staging/prod/test）

`otel.log_user_prompt`

型: ブール値
デフォルト: false
説明: ユーザープロンプトをログに記録

`otel.exporter`

型: 列挙型/テーブル
値: "none", otlp-http, otlp-grpc
デフォルト: "none"

OTLP HTTP エクスポーター:

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",  # または "json"
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

OTLP gRPC エクスポーター:

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

記録されるイベント:

codex.conversation_starts
codex.api_request
codex.sse_event
codex.user_prompt
codex.tool_decision
codex.tool_result

ツール設定

`tools`

型: テーブル（オプション）
説明: 個別ツールの有効/無効設定

[tools]
web_search = true        # または web_search_request
view_image = true

フィールド:

web_search (エイリアス: web_search_request): Webサーチツールを有効化
view_image: 画像表示ツールを有効化

フィーチャーフラグ

`features`

型: テーブル（オプション）
説明: 実験的機能や新機能のトグル
フォーマット: キーと値のマップ（true/false）

[features]
unified_exec = false
streamable_shell = true
rmcp_client = true
plan_tool = true
apply_patch_freeform = true
view_image_tool = true
web_search_request = true
approve_all = false

利用可能なフィーチャー:

キー	説明	デフォルト	ステージ
`unified_exec`	統一PTYベースのexecツール	`false`	Experimental
`streamable_shell`	ストリーム可能なexec-command/write-stdinツール	デフォルト依存	Experimental
`rmcp_client`	公式Rust MCPクライアント	デフォルト依存	Experimental
`plan_tool`	planツールを含める	デフォルト依存	Stable
`apply_patch_freeform`	freeform apply_patchツール	`false`	Experimental
`view_image_tool`	view_imageツールを含める	デフォルト依存	Stable
`web_search_request`	モデルがWebサーチをリクエスト可能	デフォルト依存	Experimental
`approve_all`	すべての承認リクエストを自動承認	`false`	Experimental

プロジェクト設定

`projects`

型: テーブル（マップ、オプション）
説明: プロジェクト/ワークツリー固有の設定
キー: プロジェクトパス

[projects."/path/to/trusted/project"]
trust_level = "trusted"

フィールド:

trust_level: 信頼レベル（現在は "trusted" のみ認識される）

その他の設定

`instructions`

型: 文字列（オプション）
説明: システムインストラクション（現在無視される）
代替: experimental_instructions_file または AGENTS.md を使用

例:

instructions = "カスタムインストラクション"

`experimental_instructions_file`

型: パス（文字列、オプション）
説明: 組み込みインストラクションを置き換えるファイル

例:

experimental_instructions_file = "/path/to/custom_instructions.md"

`project_doc_max_bytes`

型: 数値（オプション）
デフォルト: 32768 (32 KiB)
説明: AGENTS.md から読み込む最大バイト数
例:
```
project_doc_max_bytes = 65536
```

`project_doc_fallback_filenames`

型: 配列（文字列、オプション）
デフォルト: []
説明: AGENTS.md が見つからない場合の代替ファイル名

例:

project_doc_fallback_filenames = ["CLAUDE.md", ".exampleagentrules.md"]

`file_opener`

型: 列挙型（オプション）
値: "vscode", "vscode-insiders", "windsurf", "cursor", "none"
デフォルト: "vscode"
説明: ファイル引用のハイパーリンクに使用するURIスキーム
例:
```
file_opener = "cursor"
```

`hide_agent_reasoning`

型: ブール値（オプション）
デフォルト: false
説明: エージェントのreasoningイベントを非表示
例:
```
hide_agent_reasoning = true
```

`show_raw_agent_reasoning`

型: ブール値（オプション）
デフォルト: false
説明: 生のreasoning contentを表示（サポートされている場合）
例:
```
show_raw_agent_reasoning = true
```

`chatgpt_base_url`

型: 文字列（オプション）
説明: ChatGPT認証フローのベースURL

例:

chatgpt_base_url = "https://chatgpt.com"

`disable_paste_burst`

型: ブール値（オプション）
デフォルト: false
説明: バーストペースト検出を無効化
例:
```
disable_paste_burst = true
```

`windows_wsl_setup_acknowledged`

型: ブール値（オプション）
説明: WindowsのWSLオンボーディング画面の確認状態
例:
```
windows_wsl_setup_acknowledged = true
```

`disable_response_storage`

型: ブール値（オプション）
デフォルト: false
説明: ZDR組織で必須（レスポンスストレージを無効化）
例:
```
disable_response_storage = true
```

`responses_originator_header_internal_override`

型: 文字列（オプション）
説明: originator ヘッダーの値をオーバーライド（内部用）

例:

responses_originator_header_internal_override = "custom_originator"

レガシー設定（非推奨）

以下の設定は features テーブルに移行されました。後方互換性のために残っていますが、新規設定では features の使用を推奨します。

`experimental_use_exec_command_tool`

型: ブール値（オプション）
説明: 実験的exec commandツールを使用
移行先: features.streamable_shell

例:

experimental_use_exec_command_tool = true

`experimental_use_unified_exec_tool`

型: ブール値（オプション）
説明: 統一execツールを使用
移行先: features.unified_exec

例:

experimental_use_unified_exec_tool = true

`experimental_use_rmcp_client`

型: ブール値（オプション）
説明: 公式Rust MCPクライアントを使用
移行先: features.rmcp_client
例:
```
experimental_use_rmcp_client = true
```

`experimental_use_freeform_apply_patch`

型: ブール値（オプション）
説明: freeform apply_patchツールを使用
移行先: features.apply_patch_freeform

例:

experimental_use_freeform_apply_patch = true

完全な設定例

# 基本設定
model = "gpt-5"
review_model = "gpt-5-codex"
model_provider = "openai"
approval_policy = "on-failure"
sandbox_mode = "workspace-write"

# モデル設定
model_context_window = 200000
model_max_output_tokens = 16000
model_auto_compact_token_limit = 150000
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"
model_verbosity = "medium"

# シェル環境ポリシー
[shell_environment_policy]
inherit = "core"
exclude = ["AWS_*", "AZURE_*"]
set = { PATH = "/usr/local/bin:/usr/bin" }

# サンドボックス設定
[sandbox_workspace_write]
writable_roots = ["/tmp"]
network_access = true
exclude_tmpdir_env_var = false
exclude_slash_tmp = false

# MCPサーバー
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
startup_timeout_sec = 15
tool_timeout_sec = 120

# モデルプロバイダー
[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
request_max_retries = 5

# プロファイル
profile = "gpt5"

[profiles.gpt5]
model = "gpt-5"
approval_policy = "never"
model_reasoning_effort = "high"

[profiles.gpt3]
model = "gpt-3.5-turbo"
model_provider = "openai"

# 履歴設定
[history]
persistence = "save-all"

# 通知設定
notify = ["notify-send", "Codex"]

[tui]
notifications = ["agent-turn-complete", "approval-requested"]

# OpenTelemetry
[otel]
environment = "dev"
log_user_prompt = false
exporter = "none"

# ツール設定
[tools]
web_search = true
view_image = true

# フィーチャーフラグ
[features]
unified_exec = false
streamable_shell = true
rmcp_client = true
plan_tool = true
view_image_tool = true
web_search_request = true

# プロジェクト設定
[projects."/path/to/trusted/project"]
trust_level = "trusted"

# その他
file_opener = "cursor"
hide_agent_reasoning = false
show_raw_agent_reasoning = false
project_doc_max_bytes = 32768
project_doc_fallback_filenames = ["CLAUDE.md"]

コマンドライン優先順位

設定値は以下の優先順位で適用されます：

コマンドライン引数 (最高優先度)
- --model gpt-5
- --approval-policy never
- --config key=value
アクティブプロファイル
- --profile gpt5 または config.toml の profile = "gpt5"
config.toml のルートレベル設定
- model = "gpt-5-codex"
デフォルト値 (最低優先度)
- Codex組み込みのデフォルト

関連ドキュメント

参考資料

現時点(2025年10月16日 openai/codex version 0.46.0)での内容となります。
この記事が何かの参考になれば幸いです。