CodexのTOML設定を点検する

Codexの設定に一行追加したら読み込みエラーになったり、エラーはないのに変わらなかったりすることがあります。TOMLでは、引用符だけでなく「どの表の中に書いたか」も意味を持ちます。

この記事では、設定のコピーを使い、構文・項目の所属・Codexでの意味を順番に確認します。元ファイルの保存場所は設定の基本を参照してください。

書式の問題と設定の意味を分ける

TOMLは、キーと値や、角括弧の見出しで設定を表す形式です。たとえば次は同じキーを同じ場所へ二回書いています。

personality = "friendly"
personality = "pragmatic"

後ろの値で上書きされるつもりでも、これはTOMLの構文エラーです。一方、別の表の中へ書いた項目は、構文として読めても意図した設定にならない場合があります。

各段階で確認してから、次の操作へ進みます。

1. 1構文を読む引用符・重複キーなどの書き方を確かめます。
2. 2所属する表を確認全体の項目か、表の中の項目かを見ます。
3. 3Codexでの意味を照合対応キーと適用される層を確認します。

具体的な依頼と、結果の確かめ方は本文にあります。

「ファイルを読めた」「項目の場所が合う」「Codexで使える」の三つを分けて確認します。

変更せず、エラーの位置を調べる

このconfig.tomlのコピーを点検してください。まだ修正は行いません。
構文エラーと、Codexの設定項目としての問題を分けて報告します。
引用符、重複キー、角括弧で始まる表、項目の所属を確認してください。
秘密の値は回答へ引用せず、エラーの周辺も必要最小限にします。
不明な項目を推測で削除しないでください。

キーを一つ消して構文が通っても、どちらの値を残すべきかは作業の意図で決めます。読み込みエラーの解消を理由に、モデルや権限の設定を別のものへ変えないようにします。

Pythonで小さな文字列を読む

Python 3.11以降には tomllib があります。次は固定した文字列を読む例で、ファイルを書き換えません。

import tomllib

sample = 'personality = "friendly"\n'
print(tomllib.loads(sample))

Python 3.12.14で {'personality': 'friendly'} になることを確認しました。上の重複キーの例は TOMLDecodeError になりました。Pythonがない場合は、この検査だけのために導入を急がず、Codexに利用可能な検査手段を確認します。

実ファイルをPythonで読む場合の tomllib.load() はバイナリモードを使います。tomllib は読み取り用で、元のコメントや配置を保って書き戻す機能ではありません。

角括弧の下に置いた項目を確認する

次はTOMLの構造を見るためだけの例です。example はCodexへ追加する設定名ではありません。

[example]
personality = "friendly"

Pythonで読むと {'example': {'personality': 'friendly'}} となり、全体の personality ではなく example の中の項目になります。この点も実際に確認しました。

実際の設定で [mcp_servers.名前] などの下へ全体用の項目を追記するときも、どの表に入るかを確かめます。構文が正しいだけでは、Codexがそのキーを認識する証拠になりません。

修正は一項目ずつ確かめる

確認した一項目の修正案と、変更前後の差分を示してください。
既存のコメントやほかの設定を保ちます。
修正後はTOML構文、キーの所属、公式資料の対応値を確認してください。
今回の確認だけでCodexへの反映成功とは報告しないでください。

内容を確認して保存した後、利用中のクライアントを再起動し、新しいタスクで目的の設定を確認します。反映されない場合は設定の優先順位へ戻ります。

やり直すときは今回の差分だけを戻します。途中でほかの変更が入ったファイルを、古いコピーで丸ごと上書きしないでください。この記事の実測はPythonの構文・表の構造で、Codexの実設定変更や起動後の動作ではありません。