Codex config.toml 詳細ガイド

このガイドでは、Codex CLI のモデル、Provider、権限、保存済みセッション、トークン使用量に 影響する ~/.codex/config.toml の設定を説明します。

内容は Codex CLI 0.146.0 で確認しています。Codex は更新が速いため、アップグレード後は 末尾の厳密な検証を再実行してください。初回インストールは Codex 設定 を参照してください。

API Key や Bearer Token を config.toml、リポジトリ、ドキュメント、シェル履歴に 直接保存しないでください。

品質優先の基本設定

品質を優先する個人用開発マシンでは、次の構成を基準にできます。

model_provider = "icodeeasy"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
cli_auth_credentials_store = "file"

approval_policy = "on-request"
sandbox_mode = "danger-full-access"
personality = "pragmatic"
web_search = "live"

[model_providers.icodeeasy]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Codex に ~/.codex/auth.json を生成・管理させます。環境変数は標準入力からの一度だけのインポートに使用します。

read -s OPENAI_API_KEY
printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

主ドメインの接続が遅い場合は、base_url を https://jp.icodeeasy.cc または https://sg.icodeeasy.cc に変更できます。Provider ID は変更しないでください。

設定場所と優先順位

ユーザー設定の標準パスは ~/.codex/config.toml です。優先順位は次のとおりです。

1. CLI オプションと -c / --config の一時上書き
2. 信頼済みプロジェクトの .codex/config.toml
3. 選択した ~/.codex/<name>.config.toml Profile
4. ユーザー設定
5. システム設定
6. Codex のデフォルト値

一度だけ推論強度を変更する例：

codex -c 'model_reasoning_effort="xhigh"'

TOML のトップレベルキーは最初の table より前に置きます。

model = "gpt-5.6-sol"
web_search = "live"

[model_providers.icodeeasy]
name = "I Code Easy"

table の開始後に書いたキーは、次の table までその table に属します。

モデルと推論強度

model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"

model は現在の Provider に送るモデル識別子です。選択画面に名前が表示されても、 Provider がすべての機能を提供するとは限りません。テキスト生成だけでなく、ツール呼び出し、 ストリーミング終了イベント、usage まで実際に確認してください。

利用可能な強度はモデルによって異なります。max または ultra はモデルカタログと Provider の両方が対応を示す場合だけ使用してください。plan_mode_reasoning_effort は Plan モードだけを 上書きします。model_context_window などは、現在の Provider で実際の上限を確認していない 限り手動設定しない方が安全です。

Provider ID、表示名、Base URL

model_provider = "icodeeasy"

[model_providers.icodeeasy]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

name = "OpenAI" を name = "I Code Easy" に変更しても、表示が正確になるだけです。 品質、速度、認証、キャッシュ、料金、過去のセッションには影響しません。

一方、icodeeasy は永続化される Provider ID です。削除または改名すると、古いセッションが 一覧に残っていても、再開時に次のエラーになる場合があります。

failed to load configuration: Model provider `icodeeasy` not found

新しい ID が必要な場合は、古い [model_providers.icodeeasy] 定義を互換用エイリアスとして 残してください。保存済み JSONL や状態データベースを一括編集する必要はありません。

認証、権限、承認

requires_openai_auth = true のとき、Codex は OpenAI 認証ストレージを使用します。 このサイトではファイルベースの認証情報を推奨します。

cli_auth_credentials_store = "file"

認証情報は ~/.codex/auth.json に保存されます。JSON を手動で作成・編集したり、API Key を .bashrc、.zshrc、Windows のユーザー環境変数に永続化したりしないでください。初回設定と キーのローテーションには同じログインフローを使います。

read -s OPENAI_API_KEY
printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

config.toml はモデル、Provider、Base URL、権限、ツールを管理し、auth.json は API Key または ChatGPT のログイン認証情報を保持します。auth.json はパスワードと同様に扱い、 Linux/macOS では chmod 600 ~/.codex/config.toml ~/.codex/auth.json を実行してください。 Git へのコミット、共有、公開バックアップは禁止です。キー更新は再ログイン、削除は codex logout を使用します。

長期環境変数よりも shell、tmux、IDE、バックグラウンド起動で一貫して認証情報を発見できる ため、開発用途では安定します。ただしネットワーク、レート制限、モデル互換性は改善しません。 保存方式を変えても過去の Session は非表示になりません。再開互換性では Provider ID と ローカル Session 状態が重要です。

Account: API key configured (run codex login to use ChatGPT)

この表示はエラーではなく、ChatGPT ログインではなく API Key を使用しているという意味です。

approval_policy = "on-request"
sandbox_mode = "danger-full-access"

sandbox_mode は技術的なアクセス範囲、approval_policy は確認を要求できるタイミングを 決めます。

開発専用マシンでも、新しいリポジトリ、依存スクリプト、Web ページ、hooks、MCP の内容まで 自動的に安全になるわけではありません。必要に応じて codex -s workspace-write で一時的に 制限してください。

プロジェクト信頼、Web Search、MCP

[projects."/absolute/path/to/repository"]
trust_level = "trusted"

信頼済みプロジェクトでは .codex/config.toml、hooks、rules を読み込めますが、sandbox が 自動的に danger-full-access になるわけではありません。

web_search = "live"

Web Search は cached、indexed、live、disabled から選択できます。最新の技術情報には live が便利ですが、Web の内容は信頼できない外部入力として扱ってください。

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"
enabled = true
required = false
startup_timeout_sec = 10
tool_timeout_sec = 60

その MCP がなければ作業できない場合だけ required = true にしてください。初期化失敗が 新規 thread や再開を停止させるためです。

Profile で速度と安全性を切り替える

# ~/.codex/quick.config.toml
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

codex --profile quick

# ~/.codex/readonly.config.toml
approval_policy = "never"
sandbox_mode = "read-only"
web_search = "cached"

codex --profile readonly

Provider ID のようなセッション互換性に関係する値は、基本のユーザー設定に残してください。

/status、Token、Context Window

Model:              gpt-5.6-sol (reasoning xhigh, summaries auto)
Model provider:     I Code Easy - https://api.icodeeasy.cc
Permissions:        Custom (danger-full-access, Ask for approval)
Account:            API key configured
Token usage:        708K total (679K input + 28.9K output)
Context window:     51% left (132K used / 258K)
Limits:             not available for this account

実際の送信先は Provider の表示名ではなく URL で判断します。Limits: not available は 現在の認証で ChatGPT の制限情報を取得できないという意味で、無制限ではありません。

長いセッションでは毎回有効な履歴を送るため、累積入力は Context Window より大きくなります。 Codex 0.146.0 の表示式は次のとおりです。

displayed input = input_tokens - cached_input_tokens
displayed total = displayed input + output_tokens

reasoning token は output に含まれるため、もう一度加算しません。キャッシュ済み入力も入力 Token であり、料金は利用中のサービス規則に従います。

132K used / 258K が 51% left になるのは、このバージョンが使用量と総容量の両方から 約 12K の固定ベースラインを差し引き、ユーザーが制御できる残量を推定するためです。

作業段階の境界やコンテキスト不足が近いときは /compact、無関係な新しい作業には /new を使用してください。

セッションの再開

codex resume <session-id>
codex resume --last
codex resume --all

通常の選択画面と --last は現在のディレクトリを考慮し、--all はディレクトリをまたいで 検索します。再開できるのはメッセージとセッションメタデータです。終了済みプロセスは復元されず、 ファイル、Git、外部サービスは現在の実状態が使われます。

無効なフィールドと厳密な検証

Codex 0.146.0 では次の古いフィールドを設定しないでください。

disable_response_storage = true
preferred_auth_method = "apikey"

通常起動では不明なフィールドが無視される場合があります。非 Azure の Responses リクエストは このバージョンですでに store = false であり、disable_response_storage では制御されません。

Linux / macOS：

codex --strict-config mcp-server </dev/null
codex doctor --summary --ascii

PowerShell：

"" | codex --strict-config mcp-server
codex doctor --summary --ascii

最初のコマンドは不明なキーを拒否して EOF 後に終了し、次のコマンドはインストール、認証、 MCP、ローカル状態、Provider 接続を診断します。TUI では /status と /debug-config で 実効設定を確認してください。

参考資料

• Codex Authentication
• Codex Configuration Reference
• Codex Advanced Configuration
• Codex CLI command reference

このページは 2026-08-03 に Codex CLI 0.146.0 と OpenAI 公式資料で確認しました。