Codex config.tomlの設定方法｜項目と書き方まとめ
Codexの動作を毎回コマンドラインフラグで指定するのは手間がかかります。config.tomlにモデルや承認モードなどの既定値をまとめておけば、起動コマンドを短くでき、チームでも同じ設定を共有できます。この記事では、config.tomlの保存場所と役割、主要な設定項目、サンプル設定、コマンドラインフラグとの優先関係までを整理します。
前提・動作環境
この記事はCodex CLIを導入済みであることを前提に解説します。導入やサインインの手順は「Codexの使い方完全ガイド」で解説しているので、未導入の方はあわせてご覧ください。設定項目は今後もアップデートされる可能性があるため、手元の挙動と異なる場合は公式サイト(developers.openai.com/codex)で最新情報を確認してください。
config.tomlとは何か・保存場所
config.tomlは、Codexの起動時の既定値をまとめて指定するための設定ファイルです。既定の保存場所は ~/.codex/config.tomlで、環境変数CODEX_HOMEを設定するとホームディレクトリの位置自体を変更できます。ファイルが存在しない場合は空の状態として扱われ、Codexはビルトインの既定値で動作します。
プロジェクト単位で上書きしたい場合は、リポジトリ直下に.codex/config.tomlを置くことも可能です。ただしこれはそのプロジェクトが「信頼済み」として扱われている場合のみ読み込まれ、モデルプロバイダーや認証情報、通知先といったキーはセキュリティ上の理由からプロジェクト側で上書きできません。機密性の高い設定は必ずユーザーレベルのconfig.toml側で管理しましょう。
主要な設定項目
config.tomlで指定できる項目は多岐にわたりますが、まず押さえておきたいのは次の4つです。
- model / model_provider: 使用するモデル名(例:
gpt-5.1-codex)と、そのモデルを提供するプロバイダーIDを指定します。プロバイダー自体を独自に定義したい場合はmodel_providers.<id>テーブルでベースURLや認証方法を設定できます。 - model_reasoning_effort: 推論の強度を
minimalからxhighまでの段階で指定します。値を上げるほど応答は丁寧になりますが、処理時間も長くなります。 - approval_policy / sandbox_mode: それぞれ承認モードとサンドボックスの既定値です。
approval_policyにはuntrusted(未知のコマンドは都度確認)、on-request(必要と判断したときだけ確認)、on-failure(失敗時のみ確認)、never(確認なし)などを指定します。sandbox_modeにはread-only・workspace-write・danger-full-accessがあり、/permissionsで切り替えられる読み取り専用・自動編集・フルアクセスの3段階に対応する値です。 - mcp_servers.<id>: 外部ツールと連携するMCPサーバーを登録するテーブルです。起動コマンド(
command)、引数(args)、環境変数(env)を指定します。
このほかにも、TUIのテーマを変えるtui.theme、セッション履歴の保存有無を決めるhistory.persistence、ログ出力先のlog_dirなど、細かなカスタマイズ項目が用意されています。
サンプルconfig.toml全文
実務でよく使う項目をまとめた例です。そのままコピーして、値を自分の環境に合わせて書き換えてください。
# 使用モデルとプロバイダー
model = "gpt-5.1-codex"
model_provider = "openai"
model_reasoning_effort = "medium"
# 承認モード・サンドボックスの既定値
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
# MCPサーバーの登録例
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { "GITHUB_PERSONAL_ACCESS_TOKEN" = "ghp_xxxxxxxxxxxx" }
# コードレビュー用プロファイル(読み取り専用・確認なし)
[profiles.review]
model = "gpt-5.1"
approval_policy = "never"
sandbox_mode = "read-only"[profiles.<name>]テーブルを使うと、用途ごとに設定を切り替えられます。上記の例ではcodex --profile reviewと実行すると、レビュー用の緩やかなモデルと読み取り専用サンドボックスで起動します。
コマンドラインフラグとの優先関係
設定の優先順位は「コマンドラインフラグ > config.toml」が基本です。たとえばconfig.tomlでapproval_policy = "on-request"と書いていても、起動時にcodex --full-autoのようなフラグを付ければ、そのセッションではフラグ側の指定が優先されます。日常的な既定値はconfig.tomlにまとめ、一時的に挙動を変えたいときだけフラグで上書きする、という使い分けが基本の運用です。プロファイルを使う場合も同様に、--profileで選んだプロファイルの値より、さらに個別に指定したフラグのほうが優先されます。
AGENTS.mdとの役割分担
config.tomlと混同されやすいファイルにAGENTS.mdがあります。両者は役割がまったく異なります。config.tomlは承認モードやサンドボックス、使用モデルといった「動作の設定」を担い、Codexというプログラム自体の挙動を制御します。一方のAGENTS.mdは、ビルドコマンドやコーディング規約といった「エージェントへの指示・文脈情報」を書く場所で、強制力はありません。禁止したい操作を確実に止めたい場合はAGENTS.mdに書くだけでなく、config.toml側のサンドボックス設定と組み合わせる必要があります。AGENTS.mdの書き方は「AGENTS.mdの書き方」で詳しく解説しています。
つまずきポイント/よくあるエラー
- 設定を書いたのに反映されない: TOMLの構文エラーで読み込み自体に失敗している可能性があります。インデントやクォートの対応、テーブル名の綴りを確認してください。
- プロジェクト側の設定が効かない:
.codex/config.tomlはプロジェクトが信頼済みとして扱われていないと読み込まれません。またプロバイダーや認証系のキーはプロジェクト側では上書きできない仕様です。 - フラグを付けているのに古い設定のまま: フラグの優先順位を誤解しているケースです。実行したコマンド全体を見直し、フラグの綴りと値を再確認しましょう。
CODEX_HOMEを変更したら設定が消えたように見える: 参照先のホームディレクトリごと変わるため、旧~/.codex/config.tomlは読まれなくなります。移行する際は新しいパスにファイルをコピーしてください。
よくある質問
config.tomlはどこに作ればいいですか?
既定では~/.codex/config.tomlです。ファイルが存在しない場合は自分で新規作成してかまいません。CODEX_HOME環境変数でホームディレクトリの位置を変更している場合は、そのディレクトリ直下に作成します。
プロファイルは何個まで作れますか?
明確な上限は設けられていません。用途別(通常作業用・レビュー用・フルオート用など)に複数の[profiles.<name>]を用意し、--profileで使い分けるのが一般的な運用です。
GUIやVS Code拡張でもconfig.tomlは使われますか?
はい、CLIとVS Code拡張機能は同じ~/.codex/config.tomlを参照します。CLIでの基本操作は「Codex CLIの使い方」でまとめているので、あわせて確認してください。
まとめ
config.tomlは~/.codex/config.tomlに置く、Codexの動作全体を制御する設定ファイルです。モデルの指定、承認モードとサンドボックスの既定値、MCPサーバーの登録、用途別のプロファイルという4点を押さえておけば、日々の起動コマンドを大幅に簡略化できます。優先順位は常に「コマンドラインフラグが最優先」であることを忘れず、動作設定はconfig.toml、指示や文脈情報はAGENTS.mdという役割分担を意識して運用しましょう。Codex全体の使い方は「Codexの使い方完全ガイド」もあわせてご覧ください。