Codex YAML設定とTOMLの違い・使い分け確認ポイント集

Codex YAMLと公式設定の違い

「codex yaml」という検索語には、Codexの設定をYAMLで記述できるか知りたい意図と、CodexにYAMLファイルを作らせたい意図が混ざっています。前者への答えは、公式のCodexクライアント設定として案内されている拡張子は.tomlだということです。後者なら、YAMLはリポジトリの中で扱うデータや設定ファイルの一つとして編集できます。この二つを同じものだと考えると、ファイルを置いたのにモデルや承認方法が変わらない、という事態になります。

Codexの公式設定ページでは、個人用の~/.codex/config.tomlと、プロジェクトやサブフォルダーに置く.codex/config.tomlが説明されています。設定の読み込みは拡張子の似たファイルを探す方式ではないため、.codex/config.yamlや.codex/settings.ymlを作っても、そのファイルだけで同じ効果になるとは考えないでください。まず公式ページで現在のキー名と配置を確認し、必要な値をTOMLへ書き換えます。出典 URL: https://developers.openai.com/codex/config-basic

ここで大切なのは、YAMLの優劣を決めることではありません。YAMLは人が読みやすいデータ交換形式として多くの開発現場で使われますが、Codexのクライアント設定の読み込み契約とは別です。YAMLの文法に慣れている人ほど、コロンで値を並べる感覚をそのままTOMLへ持ち込まず、文字列の引用、配列、テーブルの書き方を分けて考える必要があります。

config.tomlはCodexの動作を決める

config.tomlは、Codex CLIやIDE拡張で利用するモデル、提供元、確認方法、サンドボックスの範囲などを指定するファイルです。公式ドキュメントでは、CLIとIDE拡張が同じ設定の層を共有すると説明されています。そのため、画面側だけの設定と思って変更した値がCLIにも影響することがあります。設定を編集したら、どの入口で確認したかと、どのファイルへ書いたかを記録しておくと、別の作業で意図せず値が変わったように見える問題を追いやすくなります。出典 URL: https://developers.openai.com/codex/config-basic

AGENTS.mdは作業方針を伝える

AGENTS.mdは、コードの読み方、テストの方針、説明の言語、変更時の注意などをCodexへ伝えるMarkdownファイルです。モデルやサンドボックスの値を置く場所ではありません。公式説明では、ホームディレクトリからプロジェクトの階層へ進み、近い場所の指示が後から加わる形で読み込まれます。YAMLの編集方法を指示したい場合も、方針はAGENTS.md、YAMLそのものはリポジトリ内の編集対象、クライアント設定はconfig.tomlという分担にします。出典 URL: https://developers.openai.com/codex/guides/agents-md

YAMLを使う場面と使わない場面を分ける

YAMLを使っているプロジェクトでは、Codexにそのファイルを読み書きさせること自体は自然です。たとえば画面の文言、環境ごとの非機密な設定、テスト用の入力、サービスの一覧などをsettings.yamlへ保存し、Codexに値の追加や形式の確認を頼めます。ただし、それはプロジェクトのコードがYAMLを読む設計である場合の話で、Codexのクライアントがsettings.yamlを自身の設定として読むという意味ではありません。

作業を始める前に「このファイルは誰が読むのか」を一文で説明すると混乱しません。Codexが読むのは、クライアントの設定ならconfig.toml、作業方針ならAGENTS.mdです。アプリケーションが読むのは、リポジトリにあるYAMLやJSONなどのデータファイルです。利用者が読むのは、設定値の意味を記した説明書です。同じフォルダーに複数の形式が並んでいても、読み手が違えば役割も違います。

また、既存のプロジェクトにYAML設定があるからといって、Codexの設定をそこへ統合する必要はありません。アプリ側の設定と作業支援側の設定を混ぜると、アプリの起動時に必要な値を変更したつもりがCodexの動作まで変わる、またはその逆の問題が起きます。運用を揃えたいときは、共有する値を別の説明で参照し、実際に読み込むファイルはそれぞれの形式と場所に置きます。

YAMLを編集対象にする場合

YAMLファイルを編集対象にする場合は、まずそのファイルを読むアプリケーション、キーの型、許される値、確認方法をCodexへ伝えます。Codexの設定をYAMLに寄せるのではなく、Codexへ「このファイルはアプリが読むので、既存のインデントとキー名を保つ」と依頼する考え方です。変更後は差分を見て、文字列が数値へ変わっていないか、インデントが崩れていないか、参照先の名前が一致しているかを確かめます。

クライアント設定を変更する場合

モデルや確認方法を変える場合は、YAMLを編集する前にconfig.tomlを開きます。公式設定ページで紹介されているmodel、approval_policy、sandbox_modeなどを、現在のCodexが対応する名前として記述します。見つけた記事の古いキーをそのまま追加するのではなく、設定リファレンスと利用中の版を照合し、不要なキーを増やさないことが大切です。出典 URL: https://developers.openai.com/codex/config-basic

指示書を変更する場合

「説明は日本語にする」「テストを先に読む」「変更範囲を広げない」といった希望は、YAMLの値ではなくAGENTS.mdの文章にします。指示書はコードの一部を直接動かす設定ではないため、目的と確認方法を短い段落で書きます。公式ドキュメントでは、プロジェクトの階層に沿って複数の指示書が結合される仕組みが説明されています。共通方針とフォルダー固有の方針を分けると、YAMLのファイル自体へ余計な情報を埋め込まずに済みます。出典 URL: https://developers.openai.com/codex/guides/agents-md

config.tomlの基本的な書き方

YAMLに慣れている人が最初に戸惑うのは、キーと値の区切りです。YAMLではmodel: gpt-5.6のようにコロンを使いますが、TOMLではmodel = "gpt-5.6"のように等号を使い、文字列を引用符で囲みます。値の意味が同じでも記法は同じではありません。公式の設定ページにあるキーを少数だけ選び、ひとつ保存するたびに読み込みを確認すると、誤記の範囲を小さくできます。

基本形は次のようになります。これは設定の考え方を示す最小例であり、モデル名やWindowsの利用条件は、利用中のCodexと公式ドキュメントで確認してください。

model = "gpt-5.6"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[windows]
sandbox = "elevated"

公式ページでは、利用者設定、プロジェクト設定、プロファイル、システム設定などが優先順位を持つことも説明されています。正しい書式でも、より優先度の高いCLI引数や近いプロジェクト設定があれば、画面に見える結果は変わります。したがって、文法エラーがないことと、期待した値が採用されたことは別に確認します。出典 URL: https://developers.openai.com/codex/config-basic

Step 1: 変更する範囲を決める

まず、その設定を自分のすべてのプロジェクトで使うのか、ひとつのリポジトリだけで使うのかを決めます。共通のモデルや確認方法なら~/.codex/config.toml、プロジェクト固有の前提ならプロジェクト内の.codex/config.tomlが候補です。範囲を決めずにホーム側へ書くと、別の作業にも同じ値が効きます。逆にプロジェクト側へ書いた値は、信頼されていないプロジェクトでは読み込まれない場合があるため、場所と信頼状態を一緒に確認します。

Step 2: TOMLの値を小さく追加する

一度に多くの項目を追加せず、まずモデル、次に確認方法、その後にサンドボックスのように一つずつ変えます。文字列は引用し、真偽値はtrueまたはfalse、配列は角括弧、まとまりのある設定は角括弧のテーブルで表します。YAMLから写すときに、コロン、インデント、引用符を機械的に残さないことが重要です。未知のキーを足しても目的の機能が有効になるとは限らないので、公式リファレンスで対応状況を確認します。

Step 3: Windowsの値は実行環境と合わせる

WindowsでネイティブにCodexを使う場合、公式設定ページは[windows]テーブルのsandboxにelevatedを指定する例を示しています。管理者権限や導入状態によっては別の値が必要になるため、例をそのまま固定せず、実際の端末で起動できるかを確認します。Windows用の値を一般設定の階層へ混ぜず、対応するテーブルへ置くことで、他の環境で読みにくい設定になることを避けられます。出典 URL: https://developers.openai.com/codex/config-basic

Step 4: 一回だけの変更と保存設定を分ける

試しに一度だけ設定を変えたい場合は、公式が案内する-cまたは--configの上書きを使い、恒久的な変更と区別します。期待した結果が得られたら、必要な値だけをconfig.tomlへ移します。設定ファイルに残す値は、次の作業でも必要なものだけに絞ると、どの設定が効いているかを追いやすくなります。保存した値と一回だけの値が混ざると、同じ依頼をしても結果が変わった理由を見つけにくくなります。

YAMLからTOMLへ置き換える手順

すでにYAML形式で設定案を持っている場合は、ファイルをそのまま改名するのではなく、意味を確認しながらTOMLへ移します。拡張子だけを.yamlから.tomlへ変えても、コロン区切りの文法はTOMLとして正しく解釈されません。さらに、Codexが対応していないキーや、別のツール専用のキーを持ち込むと、読み込まれない値が増えます。移行では、設定の目的、公式キー、適用範囲、確認方法を一項目ずつ対応させます。

たとえば、YAMLで次のような案を作っていたとします。

model: gpt-5.6
approval_policy: on-request
sandbox_mode: workspace-write

Codexの公式設定へ移すときは、文字列を引用して等号へ置き換えます。

model = "gpt-5.6"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

ここで重要なのは、YAMLをTOMLへ変換する作業と、Codexがそのキーを採用するか確認する作業を分けることです。形式変換ツールが文法を整えてくれても、Codexの版に存在しないキーまで正しい設定になるわけではありません。変換後は公式の設定リファレンスを開き、キー名、値の種類、既定値、必要な範囲を照合します。出典 URL: https://developers.openai.com/codex/config-basic

Step 1: キーの意味を一つずつ確認する

YAMLの各行を見て、それがモデル、確認方法、サンドボックス、表示、外部接続など何を変える値なのかを説明します。説明できない行は一度保留にし、似た名前のキーを推測で追加しません。特に、古い記事の設定例では現在の版で廃止された名前や、別の入口だけで使う値が混ざることがあります。公式リファレンスに対応する説明がある行だけを、TOMLの候補として残します。

Step 2: 型と階層をTOMLへ合わせる

YAMLで文字列に見える値が、TOMLでは引用が必要な文字列なのか、真偽値なのか、数値なのかを決めます。複数の値は配列にし、まとまりは[table]で分けます。Windowsのような環境別の項目は、一般のトップレベルに長い名前を並べず、公式例に合わせたテーブルを使います。インデントだけで階層を表す感覚をいったん捨て、等号とテーブル名で読み手に構造を示すことが移行のコツです。

Step 3: 反映を確認してから整理する

変換したファイルを置いたら、まず小さな読み取り作業で起動と設定の読み込みを確認します。モデル名、確認が出る場面、ファイルへ書ける範囲を別々に見て、期待と違う項目だけを戻します。すべてを一度に試すと、TOMLの記述ミス、優先順位、プロジェクトの信頼状態、版による違いのどれが原因か分かりません。成功した値だけを残し、採用されなかったキーは説明書に控える程度にします。

Step 4: 役割ごとにファイルを戻す

アプリが読むYAMLはリポジトリに残し、Codexの動作を決める値はconfig.tomlへ置き、作業上の約束はAGENTS.mdへ書きます。ひとつのYAMLにすべてを集めようとせず、読み手に合わせてファイルを分けます。こうすると、アプリの設定を変更したレビューと、Codexの利用者設定を変更したレビューを別々に確認でき、意図しない影響範囲を見つけやすくなります。AGENTS.mdの探索と結合の規則は公式ドキュメントで確認できます。出典 URL: https://developers.openai.com/codex/guides/agents-md

0.154.0更新後に確認するCodex設定

2026年9月9日に公開されたCodex 0.154.0では、GPT-6-Astraをモデル選択へ追加する変更、作業を分けて扱う機能、作業中に質問へ答える機能、Windowsセッションで背景のCodexサーバーを共有する変更が案内されました。これらはCodexの使い方や選べる機能に関係しますが、公式のクライアント設定がYAMLへ移行したという告知ではありません。リリース情報と設定ファイルの文法を同じものとして読まないことが重要です。出典 URL: https://github.com/openai/codex/releases/tag/rust-v0.154.0

更新直後に「YAMLが効かない」と感じたときは、まずファイル形式ではなく三つの差を分けます。第一は、更新前から存在した設定値です。第二は、版の更新で変わった機能や既定値です。第三は、CLI引数やプロジェクト側の設定による上書きです。公式設定ページの優先順位に沿って上から確認すれば、YAMLを置けば解決する問題なのか、別の設定が採用されているのかを切り分けられます。出典 URL: https://developers.openai.com/codex/config-basic

新しいモデルが選択欄に現れても、すべてのプラン、地域、入口で同じ条件になるとは限りません。設定ファイルのモデル名だけを見て利用可能だと決めず、実際のモデル選択欄と起動結果を確認します。選択できない値をTOMLへ固定すると、起動時の警告や既定モデルへの切り替えを見落とすことがあります。モデルの提供状況はリリースページと利用中の画面を別々に確認するのが安全です。

更新後にモデル名を確認する

まず現在のモデル選択欄に表示される名前と、config.tomlへ書いた値を比較します。大文字と小文字、ハイフン、世代番号が異なる場合は、記事の表記を写さず公式画面に出る値を基準にします。モデルの変更は出力の傾向や利用量にも影響するため、いきなり大きな変更を任せず、小さい読み取り作業で応答を確かめてから通常の作業へ戻ります。リリース番号とモデル名は同じものではないため、別の欄へ記録します。

Windowsのセッション共有を確認する

Windows版で複数のセッションを扱う場合は、0.154.0のリリースノートにある背景サーバー共有の説明を読み、現在の版が対象かを確かめます。これはセッションの起動や終了に関する更新であり、YAMLを設定ファイルとして読む機能ではありません。起動が不安定なときは、まずCodexの版、設定ファイルの場所、Windows側のサンドボックス値を記録し、設定を一度に複数変更しないようにします。出典 URL: https://github.com/openai/codex/releases/tag/rust-v0.154.0

更新情報とローカル設定を記録する

更新日、Codexの版、読み込ませた設定ファイル、選んだモデル、作業の結果を短く残します。公式リリースの説明は製品全体の変更を示し、手元の設定画面は自分の条件で採用された値を示します。両方を同じメモに置くと、一般的な更新と自分の環境の差を比較しやすくなります。YAMLを編集した場合は、アプリ側の変更として別に記録し、Codexの設定変更と一緒に扱わないことがポイントです。

Codex YAMLが反映されないときの切り分け

「YAMLに書いたのにモデルが変わらない」「YAMLで指定した確認方法が出ない」という場合、最初にファイル名を見直します。config.yamlを作っているなら、Codex公式の設定ファイル名であるconfig.tomlへ内容を移します。YAMLの内容がアプリ用で、Codexへ渡したい作業方針ならAGENTS.mdへ文章を移します。まず読み手の違いを決めると、文法の問題を設定の問題と取り違えにくくなります。

次に、正しい場所へ置いたTOMLが別の値で上書きされていないかを確認します。公式の優先順位では、CLIフラグと--configの上書き、プロジェクト設定、プロファイル、利用者設定などが順番に解決されます。ホーム側のファイルを直しても、現在の作業場所に近いプロジェクト設定が同じキーを持っていれば、そちらが採用されます。設定を見つけた順ではなく、優先度の高い順に並べると、原因を説明しやすくなります。出典 URL: https://developers.openai.com/codex/config-basic

プロジェクト設定が読まれない場合は、プロジェクトが信頼されているかも見ます。公式設定ページは、信頼されていないプロジェクトでは.codex/層を読み込まず、利用者側やシステム側の設定は残ると説明しています。ファイルの内容が正しくても、対象プロジェクトの信頼状態によって効果が変わるため、ファイルの存在だけで成功と判断しません。特に新しく取得したリポジトリで初めて試すときは、場所、信頼状態、起動し直したかを順番に確認します。

Step 1: ファイル名と場所を確認する

エクスプローラーやターミナルで、利用者側の.codex/config.tomlとプロジェクト側の.codex/config.tomlを確認します。似た名前のconfig.yml、config.yaml、settings.tomlが並んでいる場合は、それぞれを誰が読むファイルか説明できるようにします。ファイルの拡張子を変えただけなら、まずTOMLの構文へ直し、Codex公式の配置に合わせます。作業場所が想定したプロジェクトの中かも同時に確認します。

Step 2: 値の書式を確認する

等号の前後、文字列の引用、真偽値、配列、テーブル名を確認します。YAMLのインデントやコロンを残したまま拡張子だけを変更すると、TOMLとして解釈できません。キーを一行ずつ戻して、どの行を追加したあとに起動できなくなったかを調べます。複雑な値を最初から書かず、公式の最小例に近い形から増やすと、構文上の誤りを早く見つけられます。

Step 3: 優先順位とプロファイルを確認する

CLI起動時に-cや--configを渡していないか、別のプロファイルを選んでいないか、現在のフォルダーに近い位置へ同じキーがないかを確認します。複数のファイルを見つけたら、ファイル名だけでなく、どの設定層にあるかを表にして比較します。ホーム側を編集したのに変化がないとき、別の設定を消すのではなく、どの値が優先されているかを特定してから必要な場所を直します。出典 URL: https://developers.openai.com/codex/config-basic

Step 4: 起動し直して小さく試す

設定を変えたあと、同じ画面を使い続けるのではなく、Codexを起動し直して新しい読み込みを確認します。公式のAGENTS.md説明でも、指示の探索は実行開始時に組み立て直されるとされています。設定変更後は、ファイルの読み取りや簡単な質問など、影響の小さい作業から始めます。モデル、承認、書き込み範囲を一度に試さず、結果を一項目ずつ記録すれば、戻すべき値を判断しやすくなります。出典 URL: https://developers.openai.com/codex/guides/agents-md

Codex CLIとIDEで同じ設定を確認する

Codex CLIとIDE拡張を併用していると、片方だけがYAMLを読んでいるように見えることがあります。しかし、公式設定ページでは両者が同じ設定の層を共有すると説明されています。違いがあるように見えるときは、入口ごとに別の形式があると決めつけず、起動場所、プロジェクトの信頼状態、指定したモデル、CLI上書きの有無を比べます。設定ファイルの場所が同じでも、起動したフォルダーが違えばプロジェクト設定の範囲が変わるため、確認条件を揃えることが必要です。

IDE拡張から設定を開く場合、公式ドキュメントでは右上の歯車からCodex Settings、Open config.tomlの順に進む案内があります。ここでも開く対象はYAMLではなくconfig.tomlです。ファイルを編集したあと、CLIとIDEの両方で同じモデル選択欄や確認方法を確認し、片方の表示だけで全体に反映されたと判断しないようにします。出典 URL: https://developers.openai.com/codex/config-basic

Step 1: 同じプロジェクトから開く

CLIとIDEを同じリポジトリの同じフォルダーで起動し、対象のプロジェクト設定が一致している状態を作ります。IDEで開いているサブフォルダーと、CLIの現在位置が違うと、近い場所の.codex/config.tomlが変わることがあります。まず現在の場所とプロジェクトのルートを記録し、YAMLの編集場所ではなくCodex設定の場所を基準に比べます。これだけで、形式の違いではなく起動場所の違いだった問題を見つけられます。

Step 2: 共有設定と一回の指定を分ける

IDE側で開いたconfig.tomlへ保存した値と、CLIへその場だけ渡した値を別に記録します。CLIの一回限りの上書きは、ファイルを変更しなくても結果を変えられます。そのため、IDEの表示とCLIの結果が違うときは、CLI起動時の引数を確認してからファイルを編集します。YAMLを使った外部の設定があっても、Codexに渡る値を確認するまでは、同じ設定だと扱わないことが安全です。

Step 3: 反映結果を同じ作業で比べる

まずファイルの一覧や短い説明など、結果を比較しやすい依頼を両方の入口で行います。モデル、回答言語、ファイルへ書き込める範囲など、観察する項目を一つに絞ります。差が出たら、入口、版、起動場所、読み込んだファイル、上書き指定を記録します。大きな変更をいきなり行うと、入口の差と作業内容の差が混ざるので、設定確認では小さな作業を選びます。

まとめ：codex yamlで迷ったら読み手を確認する

codex yamlで調べたときの要点は、YAMLを使うかどうかを先に決めることではありません。そのファイルを読むのがCodexクライアントなのか、リポジトリのアプリケーションなのか、作業方針を読む仕組みなのかを分けることです。Codexの公式設定はconfig.toml、作業方針はAGENTS.md、アプリのデータはプロジェクトが定めたYAMLとして、それぞれの役割を保ちます。

具体的には、モデルやサンドボックスを変えるならconfig.toml、説明の言語や確認の方針を揃えるならAGENTS.md、アプリが読む値を編集するなら既存のYAMLを対象にします。拡張子だけを変えず、値の型と優先順位、信頼状態、起動場所を確認してください。2026年9月9日の0.154.0更新後も、リリースされた機能と設定ファイルの形式は別の論点です。公式情報を版と日付つきで確認し、まず小さい作業で反映を確かめるのが、設定を安全に整える近道です。出典 URL: https://developers.openai.com/codex/config-basic

公式情報の入口は、Codexの設定の基本（https://developers.openai.com/codex/config-basic）、AGENTS.mdの読み込み方（https://developers.openai.com/codex/guides/agents-md）、Codex 0.154.0のリリースページ（https://github.com/openai/codex/releases/tag/rust-v0.154.0）です。記事を更新するときは、検索結果の断片ではなく、これらの公式ページで現在のファイル名、キー、優先順位、提供条件を改めて確認します。