Codex for Biz
2026/11/17Codex
導入・運用初心者向け

Codexのconfig.tomlの場所と書き方|おすすめ設定

Codexのconfig.tomlの場所と書き方|おすすめ設定

「Codex の config.toml はどこにあるのか」「何を書けばいいのか、おすすめの設定が知りたい」——Codex を毎日使うようになると、起動のたびに同じ指定を打つのが面倒になり、設定ファイルを探し始めます。

結論から言うと、Codex の config.toml は ~/.codex/config.toml(ホームフォルダの下の .codex フォルダ)にあり、CLI と IDE 拡張で共通です。最初に入れる設定は「model」「model_reasoning_effort」「approval_policy」「sandbox_mode」の4つで十分で、あとは用途ごとにプロファイルの別ファイルへ分けます。ただし、古い解説に載っている書き方の中には、今の Codex では起動しないもの、何も言わずに効いていないものがあります。

株式会社Fyveは、社内の Mac mini で Codex を毎日自動で動かしています(画像の生成など)。この記事では、公式ドキュメント(2026年11月17日時点)を正にして config.toml の場所と書き方をまとめ、私たちが Codex CLI 0.167.0 で実際に書いて確かめた「止まる書き方」「黙って効かない書き方」と、自分の設定を見直して見つかったことをお伝えします。

Codex の config.toml の場所

Codex の設定ファイルは、置く場所で役割が変わります。ふだん書くのは1つ目の「自分の設定」だけで、ほかは必要になってから使えば足ります。

種類

場所

使いどころ

自分の設定

~/.codex/config.toml

すべてのフォルダで使う既定値。ふだん書くのはここ

プロジェクトの設定

リポジトリの中の .codex/config.toml

そのリポジトリだけの設定。信頼したフォルダでだけ読まれる

プロファイル

~/.codex/名前.config.toml

「調べもの用」「自動実行用」など、起動時に選んで重ねる設定

マシン全体の設定

/etc/codex/config.toml(Mac・Linux)

1台を複数人で使うときの共通の既定値

~ はホームフォルダのことです。Mac なら /Users/ユーザー名、Windows なら C:\Users\ユーザー名 の下に .codex フォルダがあります。先頭にドットが付くフォルダは、Finder やエクスプローラーでは初期設定で隠れて見えません。Mac の Finder では Command+Shift+. で表示が切り替わります。

このフォルダは、環境変数 CODEX_HOME で別の場所に変えられます。公式ドキュメントでは「Codex はローカルの状態を CODEX_HOME(既定は ~/.codex)の下に保存する」と書かれていて、config.toml のほか、ログイン情報(auth.json)や会話の履歴もここに入ります。

config.toml が見つからないとき

Codex を入れただけでは、config.toml が無いこともあります。その場合は自分で作って構いません。何も書かなければ、組み込みの既定値で動きます。

mkdir -p ~/.codex
touch ~/.codex/config.toml
open -e ~/.codex/config.toml   # Mac のテキストエディットで開く

VS Code などの IDE 拡張を使っている場合は、Codex の画面の歯車のアイコンから「Codex Settings」→「Open config.toml」で同じファイルが開きます。CLI と IDE 拡張は同じ config.toml を読むので、どちらで書いても両方に効きます。

Codex が config.toml を読み込む順番

同じ項目が複数の場所に書かれていると、どれが使われるかで迷います。公式ドキュメントが示す順番は次のとおりで、上にあるものほど強く、下の値を上書きします。

Codexがconfig.tomlを読み込む順番。コマンドの指定、プロジェクトの設定、プロファイル、自分の設定、組織の既定値、マシン全体、組み込みの既定値の7段
  1. コマンドの指定:--model や -s、-c key=value などの、その回だけの指定
  2. プロジェクトの設定:リポジトリの .codex/config.toml。リポジトリの一番上から今いるフォルダまで順に読み、近いほうが勝つ(信頼したプロジェクトだけ)
  3. プロファイル:--profile 名前 で選んだ ~/.codex/名前.config.toml
  4. 自分の設定:~/.codex/config.toml
  5. 組織が配る既定値:ChatGPT のワークスペースの管理者が配っている場合
  6. マシン全体の設定:/etc/codex/config.toml
  7. 組み込みの既定値

これとは別に、管理者が requirements.toml で決めた制限は、上の全部をしばります。会社の ChatGPT のアカウントで Codex を使っていて「config.toml に書いたのに効かない」ときは、管理者側の制限を疑ってください。

実際によく起きるのは、2と4の食い違いです。自分の設定では model_reasoning_effort = "high" にしているのに、あるリポジトリだけ考える量が少ない、というときは、そのリポジトリの .codex/config.toml に別の値が書かれていないかを先に見ます。

プロジェクトの設定が読まれる条件

リポジトリの .codex/config.toml は、そのフォルダを「信頼する」と決めたときだけ読まれます。信頼していないフォルダでは、プロジェクトの設定・フック・ルールがまとめて読まれず、自分の設定とマシン全体の設定だけで動きます。

信頼したかどうかは、自分の config.toml に次の形で書き込まれます。初めてのフォルダで Codex を起動したときに出る確認に答えると、この行が自動で増えます。

[projects."/path/to/your-repo"]
trust_level = "trusted"

また、プロジェクトの設定には書けない項目があります。公式ドキュメントでは、model_provider・model_providers・notify・profile・profiles・openai_base_url などはプロジェクトの設定に書いても無視され、起動時に警告が出るとされています。接続先や通知のように、人のリポジトリを開いただけで変わると困る項目は、自分の設定にしか書けない作りです。

この記事を読んでいるあなたへ無料プレゼントCodexを使い始める前に、「絶対に」見直してほしい5つのこと学習の設定・確認なしの操作・戻せる状態など。Codexにそのまま貼れる頼み方つき(全9ページ)
仕事の画面や資料を、AIの学習に使わせない設定取り返しのつかない操作が確認なしになっていないか、Codexに調べさせる頼み方AGENTS.mdのいちばん上に書く「絶対にしないこと」の例
中身のプレビューを見る ↓登録すると、過去の特典もまとめて受け取れます(PDF 23点・合計550ページ + すぐ使えるzip素材 3点)

最初に入れるおすすめ設定

最初から多くの項目を書く必要はありません。私たちがすすめるのは、次の4行から始めて、困ったときに1項目ずつ足す形です。値は公式ドキュメントの例に合わせています。

# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

項目

意味

選べる値(公式)

model

既定で使うモデル

モデル名の文字列

model_reasoning_effort

考える量

low・medium・high・xhigh など(モデルとクライアントによって違う)

approval_policy

コマンドを実行する前に確認を求めるか

on-request・never・granular

sandbox_mode

ファイルとネットワークにどこまで触れてよいか

read-only・workspace-write・danger-full-access

モデル名は入れ替わりが速いので、model を書かずに既定のままにしておくのも1つの手です。書かなければ、Codex 側の既定のモデルが使われます。特定のモデルに固定したい理由があるときだけ書く、と決めておくと、世代が変わったときに古い名前が残る事故を防げます。

approval_policy と sandbox_mode の組み合わせ

2つは役割が違います。sandbox_mode は「技術的に何ができるか」、approval_policy は「いつ人に確認するか」を決めます。公式ドキュメントが挙げている組み合わせは次の3つです。

使い方

sandbox_mode

approval_policy

ふだんの対話(おすすめ)

workspace-write

on-request

読むだけで、書き換えさせたくない

read-only

on-request

CI などで読むだけの自動実行

read-only

never

workspace-write では、初期設定でネットワークに出られません。パッケージの取得などでネットワークが要るときは、次のように足します。

[sandbox_workspace_write]
network_access = true

作業フォルダの外に書き込ませたいときは、同じ表に writable_roots = ["/path/to/other-dir"] のように足せます。danger-full-access はサンドボックスを丸ごと切る設定で、公式も外側で隔離された環境向けとしています。それぞれのモードで何が起きるかは、別の記事で詳しくまとめています。

Codexの承認モードとサンドボックス|安全運用
CodexCodexの承認モードとサンドボックス|安全運用

web_search と features

Web 検索は web_search で決めます。公式の値は "cached"(既定)・"indexed"・"live"・"disabled" の4つです。最新の情報を調べさせたいなら "live"、外に出したくない作業なら "disabled" にします。[features] の中の web_search は古い書き方で、公式は一番上の web_search を使うよう案内しています。

開発中の機能は [features] の表で入れたり切ったりします。たとえば記憶の機能(memories)は初期設定で切れているので、使うなら次のように書きます。

[features]
memories = true

どの機能が入っているかは codex features list で一覧が出ます。0.167.0 の手元では、名前・段階(stable・experimental・under development・removed)・入っているかどうかの3列で表示されました。

そのほか、あとで足すと便利な項目

項目

何ができるか

[mcp_servers.名前]

MCP サーバーをつなぐ(command・args・env・enabled)

[shell_environment_policy]

Codex が実行するコマンドに、どの環境変数を渡すか。AWS_* などを外せる

notify

1回の返答が終わったときに、自分のスクリプトを呼ぶ

[history]

会話の履歴を残すか(persistence = "none" で残さない)

file_opener

出力の中のファイルをどのエディタで開くか(vscode・cursor など)

MCP サーバーの書き方は長くなるので、別の記事にまとめています。

Codex×MCP連携の設定|外部ツール接続の実践
CodexCodex×MCP連携の設定|外部ツール接続の実践

用途ごとに分ける:プロファイルと -c

「ふだんは medium で、レビューのときだけ high にしたい」のように、用途で設定を変えたいときはプロファイルを使います。ここは最近の版で書き方が変わったところなので、古い解説を写すと動きません。

プロファイルは別ファイルにする(0.134.0 から)

公式ドキュメントによると、Codex 0.134.0 以降では、config.toml の中の [profiles.名前] の表を --profile が読まなくなり、profile = "名前" で既定のプロファイルを選ぶ書き方も使えなくなりました。今は、プロファイルごとに別のファイルを作ります。

# ~/.codex/deep-review.config.toml(表に入れず、一番上に書く)
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "read-only"
codex --profile deep-review
codex exec --profile deep-review "この変更をレビューして"

ファイル名の「deep-review」の部分がプロファイルの名前で、英数字・ハイフン・アンダースコアが使えます。中身は [profiles.deep-review] のような表に入れず、一番上にそのまま書きます。プロファイルは自分の設定の上に重なるので、書いた項目だけが変わり、書いていない項目は自分の設定の値のままです。

手元の 0.167.0 で確かめると、--profile を付けられるのは codex・codex exec・codex review・codex resume など実際に動かすコマンドで、codex doctor や codex features に付けるとエラーになりました。

その回だけ変えるなら -c

1回だけ変えたいなら、ファイルを書き換えずに -c(--config)で上書きします。値は TOML として読まれ、読めなければ文字列として扱われます。表の中の項目は、ドットでつないで指定します。

codex -c model_reasoning_effort='"high"'
codex -c sandbox_workspace_write.network_access=true
codex -c 'shell_environment_policy.include_only=["PATH","HOME"]'

専用のオプションがある項目(--model・-s・-a など)は、そちらを使うほうが打ち間違いが減ります。公式も「専用のフラグがあるならそれを使い、無ければ -c」と案内しています。

古い書き方で「起動しない」「黙って効かない」例

config.toml の書き方は、Codex の版が上がるたびに変わることがあります。Web で見つかる解説記事の中には、今の Codex では使えない書き方がそのまま残っているものがあります。私たちは Codex CLI 0.167.0 で、空の設定フォルダ(CODEX_HOME を一時的なフォルダに向けたもの)に1行ずつ書いて起動し、どう扱われるかを確かめました。

古い書き方と打ち間違いの扱い。untrustedなど3つは起動しない、打ち間違いやpersonalityなど3つは何も言わずに動く

起動しない書き方(エラーが出るので気づける)

書いた行

出たエラー(0.167.0)

直し方

approval_policy = "untrusted"

approval_policy = "untrusted" is no longer supported; remove this setting

この行を消す。厳しく確認させたいなら下の方法へ

profile = "fast"

legacy `profile = "fast"` config is no longer supported; use `--profile fast` with `fast.config.toml` instead

中身を fast.config.toml に移し、この行を消す

model = gpt(引用符なし)

string values must be quoted, expected literal string(行と列の番号つき)

文字列を " で囲む

このうち untrusted は、少し前まで多くの解説で「慎重に使う設定」としてすすめられていた値です。公式ドキュメントでは「Codex と ChatGPT Work は approval_policy = "untrusted" をもうサポートしない」「どちらのクライアントも起動しなくなることがある」とされています。厳しく確認させたいときの代わりとして公式が挙げているのは、approval_policy を書かずに、そのプロジェクトを trust_level = "untrusted" にする方法です。こうすると、許可のルールに当たらないコマンドは毎回確認を求められ、プロジェクトの設定も読まれなくなります。

黙って効かない書き方(エラーが出ないので気づけない)

こちらのほうが厄介です。Codex は普通に起動するのに、書いたつもりの設定が効いていません。

  • 項目名の打ち間違い:model_reasoning_efort = "high"(f が1つ足りない)と書いても、ふだんの起動ではエラーにならず、そのまま無視されます。考える量は既定のままです
  • personality = "pragmatic":公式のリファレンスでは「非推奨の互換用の設定で、friendly と pragmatic はもう文体を選ばない」とされています。書いても文句は言われませんが、何も変わりません。今も意味があるのは "none"(組み込みの性格の指示を外す)だけです
  • [profiles.名前] の表だけを残す:--profile を付けずに起動するかぎり、表は何も言わずに残ります。--profile 名前 を付けた時だけ「その表を 名前.config.toml に移して消せ」というエラーになりました

私たちの config.toml でも見つかった

この記事を書くにあたって、社内の Mac mini の ~/.codex/config.toml を開いたところ、1行目に personality = "pragmatic" が残っていました。ほかは、信頼したフォルダの trust_level = "trusted" の行が3つあるだけです。

Codex は毎日問題なく動いていたので、この行が効いていないことにはまったく気づいていませんでした。後で説明する codex doctor でも、この設定の行は ✓(問題なし)と出ます。名前が正しい項目なので、打ち間違いを見つける仕組みにも引っかかりません。古い設定が効かなくなったことは、公式のリファレンスを読まないかぎり分からない、というのが今回の実感です。

私たちのように、自動で回すジョブでは大事な指定を config.toml に頼らず、毎回コマンドに書いています。画像を作るジョブでは codex exec --sandbox workspace-write --skip-git-repo-check -m モデル名 のように、サンドボックスとモデルをその場で決めています。--skip-git-repo-check を付けているのは、信頼していないフォルダや git の管理下にないフォルダで codex exec を動かすと「Not inside a trusted directory and --skip-git-repo-check was not specified.」と出て止まるためです。config.toml が古いままでも、ジョブの動きは変わりません。この分け方が、今回は結果として効いていました。

書いた後の確かめ方

config.toml を書き換えたら、Codex を起動して様子を見る前に、次の3つで確かめると早く済みます。

1. codex doctor で読み込みを見る

codex doctor は、インストール・設定・ログイン・ネットワークの状態をまとめて点検するコマンドです。設定は「Configuration」の欄に出ます。手元の 0.167.0 では次のように表示されました(一部)。

Configuration
  ✓ config       loaded
      model                    <default> · openai
      config.toml              ~/.codex/config.toml
      config.toml parse        ok
      MCP servers              0
  ✓ sandbox      restricted fs + restricted network · approval OnRequest

見るのは3か所です。「config.toml」の行で、どのファイルを読んだかが分かります(CODEX_HOME を変えているときの確認になります)。「parse」が ok なら、TOML の文法は通っています。「sandbox」の行で、実際に効いているサンドボックスと確認の設定が分かります。

打ち間違いの項目があると、「config」の行が ✓ ではなく ⚠ に変わり、冒頭の「Notes」にも ⚠ config が出ました。どの項目が悪いかまでは出ないので、⚠ が出たら次の方法で探します。

2. --strict-config で知らない項目を探す

--strict-config を付けて起動すると、今の Codex が知らない項目を見つけた時点でエラーにして止まります。打ち間違いを試したときは、次のように行番号と項目名が出ました。

$ codex --strict-config exec "say ok"
Error loading config.toml:
config.toml:1:1: unknown configuration field `model_reasoning_efort`

ただし、0.167.0 では codex features や codex doctor と組み合わせると「--strict-config is not supported」と出ました。対話の codex か codex exec に付けて使います。また、personality のように「名前は正しいが、もう効かない」項目は、この方法でも見つかりません。

3. 版を上げるときに、公式のリファレンスと突き合わせる

効かなくなった項目を見つけるには、結局、公式の Configuration Reference と自分の config.toml を並べて読むしかありません。私たちは今回、Codex の版を上げるときに config.toml を開いて、1行ずつリファレンスで探すことにしました。項目が少ないほど見直しは楽なので、ここでも「4行から始めて、要るものだけ足す」が効いてきます。版の確かめ方と上げ方は、次の記事にまとめています。

Codexのバージョン確認と更新方法|最新化と戻し方
CodexCodexのバージョン確認と更新方法|最新化と戻し方

よくある質問

config.toml と AGENTS.md はどう違いますか

config.toml は Codex という道具の動き方(モデル・サンドボックス・確認・接続先)を決めるファイルで、AGENTS.md は Codex に読ませる作業の指示(このリポジトリの決まり・テストの回し方など)を書くファイルです。モデルを変えたいなら config.toml、「コミットの前にテストを回して」と伝えたいなら AGENTS.md に書きます。

Windows でも場所は同じですか

同じく、ホームフォルダの下の .codex\config.toml です。Windows では、サンドボックスの方式を [windows] の表の sandbox で選ぶ項目が加わります(公式の例は sandbox = "elevated")。方式ごとの違いは「CodexのWindows sandbox設定|3方式の違い」で詳しく扱っています。

チームで同じ設定を使いたいときは

リポジトリに .codex/config.toml を入れて共有するのが基本です。ただし、メンバーがそのフォルダを信頼しないと読まれないこと、接続先や通知など一部の項目はプロジェクトの設定に書けないことに注意してください。組織として強制したい制限は、ChatGPT のワークスペースの管理者が配る設定(requirements.toml)で決めます。

APIキーは config.toml に書きますか

書きません。ChatGPT のアカウントでログインしている場合、ログイン情報は auth.json か OS のキーチェーンに保存されます。自分で別の接続先を足す [model_providers.名前] でも、キーそのものではなく、キーを入れた環境変数の名前を env_key に書く形です。

まとめ

  • Codex の config.toml は ~/.codex/config.toml。CLI と IDE 拡張で共通で、無ければ自分で作ってよい
  • 読み込む順番は「コマンドの指定 → プロジェクトの .codex/config.toml(信頼したフォルダだけ)→ プロファイル → 自分の設定 → 組織 → マシン全体 → 既定値」
  • 最初は model・model_reasoning_effort・approval_policy・sandbox_mode の4行で十分。ネットワークは [sandbox_workspace_write] の network_access で足す
  • プロファイルは 0.134.0 から別ファイル(~/.codex/名前.config.toml)。[profiles.名前] と profile = は使えない
  • approval_policy = "untrusted" は起動しなくなる。打ち間違いと personality = "pragmatic" はエラーにならず、黙って効かない
  • 書いた後は codex doctor の Configuration 欄と、codex --strict-config exec で確かめる

config.toml は一度書くと開かなくなるファイルですが、Codex の版が上がるたびに、書いた設定の意味が変わることがあります。株式会社Fyveでは、こうした道具の設定や運用の決まりを、実際に動かして確かめたうえでお伝えしています。

この記事を読んでいるあなたへ無料プレゼント

Codexを使い始める前に、「絶対に」見直してほしい5つのこと

学習の設定・確認なしの操作・戻せる状態など。Codexにそのまま貼れる頼み方つき(全9ページ)

Codexは便利な一方で、設定ひとつで「聞かずに動く」ようになります。この資料を作るために自分の設定を開いたら、本番のデータベースを書き換える操作が、覚えのないうちに確認なしで動く状態になっていました。使い始める前に見直してほしい5つを、Codexにそのまま貼れる頼み方と一緒にまとめました。

  • 仕事の画面や資料を、AIの学習に使わせない設定
  • 取り返しのつかない操作が確認なしになっていないか、Codexに調べさせる頼み方
  • AGENTS.mdのいちばん上に書く「絶対にしないこと」の例
  • 失敗しても戻せる状態で始める方法と、使えなくなったAIの指定の直し方

メールアドレス登録で他にも様々な資料を閲覧できます

Claudeのプランを「上げる」前に読む本AIっぽくない画像を生成するためのプロンプトギャラリー10選「Muse」の便利な使い方 TOP30「Fable 5.2」vs「Opus 5.5」徹底比較「GPT-6.1 Terra」を、実務で比べてみた。仕事でAIを使う人が「絶対に」知っておくべき Claude Codeスキル TOP10「Sonnet 5.5」を、実務で比べてみた。「Opus 5.5」を、実務で比べてみた。Jevで得する仕事、損する仕事+14

PDF 23点・合計550ページ + すぐ使えるzip素材 3点

どれも登録後の受け取りページから、まとめてダウンロードできます。

毎週配信の無料ニュースレター「AIネイティブ超研究」の購読特典です。メール登録後すぐ、受け取りページのご案内が届きます。そこにはこの資料に加えて、過去の特典もすべてまとめて置いてあります。あわせて、AI活用に関するお知らせやお役に立てそうなご案内をお送りすることがあります。解除はいつでも1クリック。

← 記事一覧に戻る

御社の業務に合わせたCodex導入支援

「AIツールを導入したが、現場で使われない」を終わらせる。
業務課題のヒアリングから設計、ハンズオン実践、運用定着まで一貫して支援します。

初回無料相談を申し込む相談プランと料金を見る →
© 2025 Fyve Inc. All rights reserved.