OpenAIのローカル実行型コーディングエージェントであるCodex CLIを導入したものの、いざカスタマイズしようとしたときに「config.toml」がどこにあるのか分からなくて困っていませんか？設定ファイルが見つからないと、モデルの変更やセキュリティの調整もできなくて焦っちゃいますよね。この記事では、各OSにおけるCodexのconfig.tomlの場所や、環境変数を使った応用的な管理方法について分かりやすく解説します。設定が反映されないときの落とし穴や、安全に使いこなすための実践的なテンプレートも用意したので、ぜひ最後まで読んでみてくださいね。
- OSごとに異なるconfig.tomlの正確な配置場所とアクセス手順
- 環境変数やプロファイル機能を使った高度な設定ファイルの管理手法
- プロジェクトの信頼設定やセキュリティポリシーによる挙動制御の仕組み
- Model Context Protocol（MCP）やカスタムコマンドを活用した自動化の構築
codexのconfig.tomlの場所はどこ？
Codex CLIの中核を支える設定ファイルである「config.toml」の配置場所について、初心者の方にも分かりやすく解説します。お使いのOSごとにデフォルトの保存先が異なっていたり、環境変数によって場所を移動できたりするので、まずは自分の環境の物理パスを確認してみましょう。設定ファイルは単なるテキストデータですが、Codex全体の挙動を決定づける羅針盤のような役割を持っています。どこにファイルが存在し、どのようにシステムに読み込まれているかを理解することが、快適な開発環境への第一歩になりますよ。
OS別のデフォルト物理パス
グローバルレベルで適用されるユーザーデフォルトの config.toml は、各OSのホームディレクトリ内にある「.codex」という隠しディレクトリの直下に作成されます。それぞれの具体的な物理パスと、コマンドラインやIDE（統合開発環境）の拡張機能からアクセスする方法を以下の表にまとめました。隠しフォルダ属性になっているため、エクスプローラーやFinderの標準設定では見落としがちですが、コマンドやエディタの機能を直接叩けば一発でアクセスできるので安心してくださいね。
| 項目 | Mac / Linux 環境 | Windows 環境 |
|---|---|---|
| 物理パス | /Users/<ユーザー名>/.codex/config.toml | C:\Users\<ユーザー名>\.codex\config.toml |
| 表記略称 | ~/.codex/config.toml | %USERPROFILE%\.codex\config.toml |
| コマンドによる新規作成 | mkdir -p ~/.codex && touch ~/.codex/config.toml | PowerShell等でフォルダと空ファイルを生成可能 |
| IDE拡張からのアクセス | 拡張機能の右上にある「ギア（歯車）アイコン」を選択し、Codex Settings > Open config.toml の順にクリックすることで、対象ファイルを直接エディタで開くことができます。 | |
上記の通り、OSごとにパスの構造が微妙に異なるものの、基本的にはユーザー個人のホーム領域に紐づく形で自動生成される仕組みになっています。もし万が一「.codex」フォルダ自体が見当たらない場合は、Codex CLIを一度も起動していないか、初期化処理が走っていない可能性が高いかなと思います。一度ターミナルから codex --version などの基本コマンドを実行してみるか、上記のコマンド例を使って手動でディレクトリとファイルを生成してあげると、Codexが起動時に自動でそれを認識してくれるようになりますよ。
状態ディレクトリの分離方法
Codexは、動作に必要な一時状態やキャッシュ、すべての設定ファイルを「CODEX_HOME」という環境変数で指定されたディレクトリに格納する仕組みになっています。この環境変数が設定されていない場合のデフォルト値が、先ほど紹介した「~/.codex」になりますね。しかし、特定の検証用プロジェクトを進める際や、仕事用とプライベート用でAIの行動ログ、トークンキャッシュを混ざらないようにしたいときなど、完全に環境を切り離したい場面も出てくるかなと思います。
例えば、APIキーの認証セッションを完全に独立させたいときなど、セキュリティ上の理由で環境を隔離したいケースがあるかもしれません。そういった場合は、以下のように環境変数を定義して別ディレクトリを指定するのがおすすめです。環境変数は .bashrc や .zshrc、あるいはWindowsのシステム環境設定に書き込んでおくことで、ターミナル起動時にいつでも自動でクリーンな隔離環境へとCodexを誘導できるようになります。
環境変数の指定例：CODEX_HOME="$HOME/.codex-api" と定義することで、通常のパーソナルな設定とAPI実行用の環境を物理的に完全に分離してCodexを動かすことができますよ。
このように設定場所を柔軟にずらせる特性を活かせば、CI/CDパイプラインの中だけで使い捨てるための一時的な状態ディレクトリを用意することも容易です。プロジェクト単位でのスクリプト自動化の際などにも、この CODEX_HOME の切り替えテクニックは非常に重宝するテクニックなので、ぜひ覚えておいて損はないかなと思います。
ファイルの役割と管理データ
状態ディレクトリ（$CODEX_HOME）の中には、config.toml 以外にも様々な重要なファイルやフォルダが自動的に保存されます。それぞれの役割を把握しておくと、トラブルが起きたときにも役立ちます。Codexは自律的なエージェントとして振る舞うため、ユーザーが入力したプロンプトだけでなく、過去の会話履歴や取得したプラグイン、セッションの状態なども、すべてこのフォルダの下で一元管理されるのが特徴ですね。
| ファイル / ディレクトリ | 役割と管理データ |
|---|---|
| config.toml | ユーザーレベルの主要構成およびモデル動作設定ファイル。 |
| auth.json | ファイルベースの認証トークンやログイン情報が格納されるキャッシュ。 |
| .credentials.json | OSキーリングを使用しない場合のMCP OAuthなどに関する認証格納ファイル。 |
| history.jsonl | 会話セッションや実行コマンド履歴が保存される履歴ファイル。 |
| sessions/ | ローカルCLIセッションの実行履歴とコンテキストを記録するディレクトリ。 |
| skills/ | ユーザーが追加した特定の作業手順や、拡張手順（Skills）を保存するフォルダ。 |
| plugins/ | 拡張用のプラグインバイナリおよび関連キャッシュを格納する場所。 |
| <プロファイル名>.config.toml | –profile 引数とともに呼び出される、特定プロファイル用の追加設定ファイル。 |
これらの中でも、特に auth.json や .credentials.json はセキュリティ的に最も保護されるべきファイル群です。ここにはOpenAIのプラットフォームや外部連携APIと通信するための生トークン、認証状態が一時的にそのままキャッシュされているケースがあるからです。これらがもし外部に漏れてしまうと、意図しないAPI利用料金の発生など深刻な問題に繋がることもあるため、次節で解説する権限のチェックは確実にやっておいたほうが良さそうですね。
権限変更によるセキュリティ対策
ローカル環境でAPIキーや重要な認証データを扱う以上、設定ファイルのパーミッション（権限）管理は基本中の基本であり、非常に重要な対策です。特に、他のユーザーもアクセスできるような共有マシンを使っている場合や、社内の共有サーバー内でCodexを稼働させる場合は、意図しない読み込み権限を排除しておかなければなりません。設定ファイル自体に他のユーザーへの読み取り権限（Read属性）が残ったままだと、システム上の脆弱性として攻撃対象にされてしまうリスクがあるからです。
Unix/Linux環境やMacにおいては、ファイル権限を所有者だけが読み書きできるように制限する、以下のコマンドを実行しておくのがベストプラクティスとされています。Windows環境の場合は、ファイルのプロパティから「セキュリティ」タブを開き、自分自身のアカウント以外のユーザーグループ（Everyoneなど）のアクセス権をすべて削除することで、同等のセキュリティ強度を確保することができますよ。
パーミッションを制限するコマンド：chmod 600 ~/.codex/config.toml
この設定を行っておくことで、他アカウントからの不正なファイル閲覧を防ぎ、安全性を高めることができます。
また、config.toml だけに限らず、先ほど紹介した .codex ディレクトリ全体の権限も chmod 700 ~/.codex で絞っておくとさらに強固になります。AIツールを導入する楽しさに気を取られて、こうしたセキュリティの足元がおろそかになってしまうのはよくある落とし穴なので、最初の段階でしっかりガードを固めておくのがエンジニアとしてスマートな立ち回りかなと思います。
設定の優先順位と競合の解決
Codexは複数の設定ファイルを論理的に重ね合わせる「レイヤード・アプローチ」を採用しています。ツールを起動したときにこれらのファイルが自動でスキャンされ、もし同じ項目が違う場所で定義されていた場合は、あらかじめ決まっている優先順位（プレシデンス・ルール）に従って衝突が解決されます。これにより、「普段はPC全体の共通設定を使いつつ、特定の開発リポジトリに入ったときだけ専用のカスタム設定を上書き適用する」といった、非常に柔軟な運用が可能になっています。
適用される優先順位は、数字が小さいほど優先度が高くなります（1が最優先）。
- CLIフラグおよび -c / –config： コマンド実行時に引数で直接指定するオーバーライド。現行のコマンドにのみ一時的に影響を与えたいときに使います。
- プロファイルファイル（–profile <プロファイル名>）： 特定のタスクに応じたテンプレート。~/.codex/<プロファイル名>.config.toml の内容がマージされます。
- プロジェクト個別設定（.codex/config.toml）： 各Gitリポジトリ内に配置される設定。作業ディレクトリに最も近い親ディレクトリのものが優先されます。
- ユーザー個別設定（~/.codex/config.toml）： PC全体で共通して適用されるデフォルト。個人の好みや共通のAPIベースURLなどを記述します。
- システム一括設定（/etc/codex/config.toml）： 管理者によってマシン全体に規定されているデフォルト値。
- 内蔵デフォルト値 (Built-in Defaults)： 設定ファイルが一切存在しない場合に適用される、Codex本体のフォールバック値。
このルールを頭に入れておかないと、「ユーザー設定の config.toml をいくら編集しても、プロジェクト側のリポジトリ内に置かれた .codex/config.toml の設定にブロックされて変更が反映されない！」なんていう、初心者ありがちな沼にハマってしまう原因になります。何か挙動がおかしいなと感じたときは、現在実行しているディレクトリの周辺に、上位の優先順位を持つ設定ファイルが隠れていないか確認してみるのが良さそうですね。
プロジェクトを信頼する要件
プロジェクトごとのローカル構成（.codex/config.toml）には、強力な実行制御オプションを含めることができます。そのため、悪意のあるリポジトリをクローンして実行した際に環境が汚染されないよう、特別な防御メカニズムが備わっています。例えば、オープンソースのコードをGitHubからクローンしてきたとき、その中に開発者を狙った不正な設定ファイルが仕込まれていたら、予期せぬローカルコマンドを実行させられてしまう危険性がありますよね。
Codexは、ユーザーが明示的に「信頼する」と宣言したプロジェクトディレクトリ（Trusted Project）においてのみ、プロジェクトレベルの .codex/config.toml やフック、ルールをロードします。もしプロジェクトが信頼されていない場合、そのリポジトリ内の個別設定はシステムによって完全に黙殺され、ユーザー自身のグローバル設定のみに基づいて挙動が制約されるので安心ですね。初めてそのディレクトリでCodexを動かす際に「このプロジェクトを信頼しますか？」というプロンプトが表示されるのは、この強固なセキュリティ盾が働いている証拠なのです。
強制的に無視される禁止キー
たとえ「信頼されたプロジェクト」であっても、環境依存やセキュリティリスクが極めて高い特定のキーがプロジェクト用の .codex/config.toml に含まれていた場合、システムはそれを強制的に無視し、起動時に警告を表示します。これは、プロジェクト設定によって開発者の認証トークン送信先を勝手に別のフィッシング用サーバーに変えられてしまうような、高度なサプライチェーン攻撃を防ぐための仕組みです。
プロジェクト設定内で禁止されているキーの代表例としては、openai_base_url、chatgpt_base_url、model_provider、model_providers、notify、profile、profiles などが挙げられます。これらは悪意のあるエンドポイントへのデータ転送を防ぐためのガードレールとなっています。これらの根幹に関わる通信周りのディレクティブは、どれほどプロジェクト側で上書きを試みようとも、必ず最上位のユーザー設定（~/.codex/config.toml）に記載された安全なルートが強制適用されるようになっているわけです。
なお、企業などの一括管理端末では、個人の設定を上書きして組織全体の最低限の安全基準を定める requirements.toml が配置されることもあります。これによって、承認を一切求めない設定（approval_policy = "never"）や、フルアクセスを許容する危険な設定（sandbox_mode = "danger-full-access"）の有効化を組織側で制限できるようになっています。個人開発であっても組織開発であっても、こうしたセキュリティの多層防御が張り巡らされている点は、さすがOpenAIの設計だなと感じさせてくれますね。
codexのconfig.tomlの場所を確認した後の設定
設定ファイルの場所が分かったら、次は中身をカスタマイズしてCodexをより安全に、そして便利に使えるように設定してみましょう。ここでは安全性を高めるためのサンドボックス設定や、外部ツールと連携するための具体的な記述方法について詳しく見ていきます。デフォルトのままでも動くことは動きますが、自分のワークフローや求めるセキュリティレベルに合わせてチューニングすることで、開発の快適性が驚くほど跳ね上がりますよ。
承認ポリシーと安全な運用
自律して動くAIエージェントを安全に運用するための鍵は、ファイルシステムへの書き込み可否を規定する「サンドボックスモード」と、実行前にユーザーの合意を得る「承認ポリシー」の組み合わせにあります。AIが提示したソースコードやコマンドを、人間のチェックを挟まずにそのままノーガードで実行させてしまうのは、開発環境の破損や予期せぬ挙動を招く原因になりかねないからです。
承認ポリシー（approval_policy）は、エージェントがアクションを起こす前にユーザーへ確認を求める基準です。「untrusted」ポリシーを設定しておくと、信頼されたコマンド以外の全操作で確認を求めてくるため、開発環境において最も安全な選択肢として推奨されます。完全に自動化されたCI/CD環境でもない限り、「never（確認なし）」は避けるのが無難ですね。毎回 Y/N を選ぶのが少し手間に感じるかもしれませんが、予期せぬ rm -rf のような事故を未然に防いでくれる防波堤になってくれますよ。
サンドボックスと接続の制限
サンドボックスモード（sandbox_mode）は、OSレベルの隔離技術（macOSならSeatbelt、LinuxならLandlock+seccomp）を活用し、ファイルアクセスをシステムコールレベルで遮断してくれます。これにより、万が一AIモデルがバグのある破壊的なスクリプトを生成して実行しようとしたとしても、OSのカーネルレベルでその動作を未然に封じ込めることができる仕組みになっています。
例えば workspace-write モードに設定すると、現在アクティブな作業ディレクトリ内だけでコードの生成や実行が許可され、パスの外にある重要なシステムファイルへの直接アクセスは完全にブロックされます。もしプロジェクト外でどうしても書き込みを許可したい特定のパス（一時ファイル用ディレクトリなど）がある場合は、writable_roots の設定を併用して追加指定することも可能です。これにより、自由度を保ちながらも、システムルートなどの聖域をガッチリ守ることができます。
また、インターネットへのアクセスも制御できます。Web検索機能（web_search）を "cached" モードにしておけば、ライブのインターネットに直接パケットを投げず、OpenAIがホストするインデックス化されたキャッシュデータベースへアクセスするため、機密情報の漏洩リスクを減らせます。さらに、シェルコマンド内での外部通信を禁止したいなら、[sandbox_workspace_write].network_access = false を指定して、curl などのプロセスレベルの通信を拒絶することができます。ローカルのソースコードを勝手に外部へ送信されるリスクをゼロにしたいエンタープライズ用途では、このネットワーク遮断は必須の設定項目かなと思います。
おすすめの設定テンプレート
安全性と開発効率を両立させるために、洗練されたグローバル向けの設定テンプレートを用意しました。場所を確認した config.toml にそのまま貼り付けてベースとしてお使いいただけます。ここから必要に応じて、モデル名や推論のパラメータを自分好みに微調整していくのが一番手っ取り早くて確実な方法かなと思います。
# ~/.codex/config.toml
#:schema https://developers.openai.com/codex/config-schema.json
model = "gpt-5-codex"
review_model = "gpt-5-codex"
model_provider = "openai"
# モデルの振る舞い・推論の設定
model_reasoning_effort = "medium"
model_reasoning_summary = "auto"
model_verbosity = "medium"
# 安全性と承認ポリシーの画定
approval_policy = "untrusted"
sandbox_mode = "workspace-write"
web_search = "cached"
# 詳細なサンドボックスの制約[sandbox_workspace_write]
network_access = false exclude_tmpdir_env_var = true exclude_slash_tmp = true # 環境変数経由でのセキュリティ資格情報漏洩の防止
[shell_environment_policy]
inherit = “core” ignore_default_excludes = false exclude = []
このテンプレートでは、推論時の思考プロセスの深さを調整する model_reasoning_effort を "medium" にし、レスポンスの冗長さを適度に抑える設定にしています。これによって、過剰に長い解説でトークンを浪費することなく、的確なコーディングの提案を受け取ることができるようになります。また、スキーマ（#:schema）の行を入れておくことで、VS Codeなどのエディタでこのファイルを開いた際に、設定項目の自動補完やタイポのリアルタイムバリデーションが効くようになるので、記述ミスを減らせてとっても快適ですよ。
MCPサーバーとの外部連携
Codexの可能性をさらに大きく広げてくれるのが、Model Context Protocol（MCP）を用いた外部機能のインテグレーションです。config.toml 内に [mcp_servers] の構成を正しく定義することで、エージェントは高度なタスクを外部プログラムを通じて処理できるようになります。MCPはAIモデルとローカルツール・外部APIをセキュアに繋ぐ世界標準の共通規格なので、これを使いこなせるとCodexがただの「コード生成器」から「自律型開発パートナー」へと進化します。
MCPサーバーは標準入出力（stdio）方式などで通信を行いますが、設定ファイル内では起動コマンド（command / args）のほか、GitHub連携に必要なトークンなどを渡すための環境変数（env）を指定できます。また、初期起動時のモジュール取得などで応答が遅い場合は、startup_timeout_ms の数値を引き延ばすことで接続エラーを回避できますよ。ローカルの環境依存でnpxの立ち上がりが遅いケースなどでは、タイムアウト値をデフォルトから少し長めに設定してあげるのが、連携を安定させるちょっとしたコツになります。
主要なMCPサーバーの設定例：
- GitHub連携: イシュー作成やコミット、PRの自動生成などを自律実行させます。
[mcp_servers.github]command = "npx"args = ["-y", "@modelcontextprotocol/server-github"]env = { "GITHUB_TOKEN" = "your_pat_here" } - Browser自動化: Playwrightを使い、生成したUIの表示テストや自動確認を行います。
[mcp_servers.playwright]command = "npx"args = ["@playwright/mcp@latest"]
また、独自の認証や異なる形式を利用したい場合は、以下のように [model_providers] を定義することで、Ollamaなどのローカルモデルと連動させるカスタム仕様の構築も可能です。完全にオフラインで動作するローカルLLMをCodexのバックエンドとして組み込めば、社外秘のソースコードを1バイトもインターネットに出したくない状況下でも、安全かつ高速なインライン補完やコード補修の自動化環境が手に入りますね。
model = "codestral"
model_provider = "ollama"[model_providers.ollama]
name = “Ollama” base_url = “http://localhost:11434/v1” env_key = “OLLAMA_API_KEY” wire_api = “responses”
Claude Codeとの構造比較
同じターミナルベースの自律型AIコーディングエージェントとして、Anthropicの「Claude Code」も人気を集めていますよね。両者の設計思想や構成管理にはいくつかの違いがあります。これからどちらをメインに据えるか悩んでいる方や、併用を考えている方にとっては、設定ファイルのフォーマットや思想の違いを理解しておくことは、非常に有意義な比較材料になるかなと思います。
Codexが config.toml という可読性の高いTOML形式を採用しているのに対し、Claude Codeは settings.json によるJSON形式での管理を行っています。また、プロジェクトごとのルール規約ファイルも、Codexが AGENTS.md を自動検出する仕組みである一方、Claude Codeは CLAUDE.md を参照します。TOMLはコメントアウトが容易に残せるため、設定の意図をメモしながら管理したい人にはCodexのスタイルが馴染みやすいかもしれませんね。
興味深いことに、Claude Codeはそれ自体がMCPクライアントとして動くため、Codexを背後のMCPサーバーとして登録し、同一のターミナル上で両者の強みを組み合わせて相互運用する、といった高度な共存技法も可能となっています。OpenAIモデルが得意な推論タスクと、Anthropicモデルが得意な長文コンテキストのコード解析タスクを、設定ファイルひとつでシームレスに切り替える環境を構築してみるのも、最高に面白い挑戦になるんじゃないでしょうか。
codexのconfig.tomlの場所まとめ
最後に、Codex CLIの設定の要となる「config.toml」についておさらいしておきましょう。この記事のポイントを簡単にまとめました。
- デフォルトの場所は、各OSのホームディレクトリにある ~/.codex/config.toml である
- 環境変数 CODEX_HOME を設定することで、格納場所を任意のディレクトリへ物理的に分離できる
- セキュリティを高めるために、ファイルの権限を chmod 600 などで所有者のみに制限するのがおすすめ
- プロジェクトごとの個別設定を反映させるには、対象リポジトリが「信頼されたプロジェクト」である必要がある
設定ファイルの場所さえ分かってしまえば、モデルの変更からセキュリティの強化、外部ツールとの連携まで、Codexの持つポテンシャルを最大限に引き出すことができます。最初は難しそうに見えるTOMLの記述も、一度テンプレートを貼ってしまえば後は直感的に直せるものばかりです。まずはご自身のPCのフォルダを開くか、コマンドを入力して、config.toml が正しく配置されているかチェックしてみてくださいね！
