Codexでチーム設定を統一し、優先順位を検証する

Codexでチーム設定を統一し、優先順位を検証する

約40分で、プロジェクト共通のCodex設定を作り、設定の優先順位を試し、チームメンバーが結果を再現する方法を記録できます。必要なのはCodex CLI、検証用リポジトリ、そこでファイルを編集する権限です。成果物は短い設定ファイル、2台の端末または2つのアカウントでの検証記録、個人設定が共通設定を上書きした場合の対処方法です。

複数人でCodexを使うと、モデルや検索モードが人によって異なることがあります。OpenAIのConfig basicsによると、Codexは複数の場所から設定を読み込みます。プロジェクトの設定が有効になるのは、そのプロジェクトが信頼されている場合だけです。また、管理者のポリシーはユーザーが選べる値を制限することがあります。この記事では設定の再現性に焦点を当てます。ファイルやネットワークへのアクセス、コマンド実行時の承認については、Codexの権限を検証するガイドを参照してください。

🧰 準備

Codex CLIを開いてサインインし、ボタンの文言変更など、小さな作業がある検証用リポジトリを選びます。2台の端末を比較できるよう、Codexのバージョン、OS、作業ディレクトリ、workspace、検証日を記録してください。

編集する前に、次の4つの場所を区別します。

  1. ~/.codex/config.tomlには個人の既定値が入ります。CODEX_HOMEを設定すると基点は指定したディレクトリに変わります。そのディレクトリは事前に存在している必要があります。
  2. リポジトリ内の.codex/config.tomlにはプロジェクトの設定が入ります。プロジェクトのルートから作業ディレクトリまで、複数の設定層が適用される場合があります。現在のディレクトリに近いものが優先されます。
  3. $CODEX_HOME/[name].config.tomlはprofileファイルです。--profile [name]で選択します。
  4. -cや--configを含むCLI引数は、その実行に適用され、設定値の中で最も高い優先順位を持ちます。

新しいキーを追加する前にConfiguration Referenceを確認してください。プロジェクトの設定では、model_provider、model_providers、notify、profile、profiles、otelなどを上書きできません。自然言語で書く作業ルールはAGENTS.mdに置き、実行時の設定はconfig.tomlに置きます。

🪜 手順

1. 共通化する値を最小限に絞る

Codexを日常的に使う人と安全性の担当者に、どの設定を端末間でそろえる必要があるか確認します。リポジトリには、本当に共通の値だけを入れます。使えるモデルが各自のプランで異なるなら、ファイルをそろえるためだけにmodelを固定しないでください。

検証用リポジトリに.codex/config.tomlを作り、まずは最小限の例を入れます。

web_search = "cached"
model_reasoning_effort = "medium"

これは検証用の例であり、どの会社にも適する標準設定ではありません。Config basicsによると、cachedは検索インデックスを利用します。推論の強さは、選択したモデルが対応する場合にだけ意味があります。レビュー担当者が各変更の理由を理解できるよう、設定ファイルは短く保ちます。

モデルも共通化する場合は、関係する全アカウントで使えることを先に確認します。Sample Configurationは参照資料であり、そのままリポジトリにコピーするファイルではありません。

2. チーム用の優先順位表を作る

「キー、設定した場所、期待する値」の3列で表を作ります。OpenAIが示す優先順位は、高い順にCLI引数、信頼済みプロジェクトのルートから現在のディレクトリまでの設定、選択したprofile、ユーザー設定、クラウド管理のconfig.tomlの既定値、システム設定、組み込みの既定値です。プロジェクト内では、作業ディレクトリに近い設定層が優先されます。

たとえば、リポジトリにweb_search = "cached"と書いても、メンバーが-c web_search=liveを指定して起動すれば、そのセッションではliveが使われます。CLI引数の優先順位が高いためです。profileがdisabled、信頼済みリポジトリがcachedなら、リポジトリが優先されます。これは公開された優先順位からの推論なので、実際のセッションで確かめてください。

管理者が適用するrequirements.tomlは制約です。-cで上書きできる既定値の一層ではありません。管理ポリシーは、ユーザーが選んだ値を禁止できます。会社がMDM、Agent Security、Work Cloudを使う場合は、実際の環境に適用されるポリシーを管理者に確認してもらいます。

3. 信頼済みと未信頼のプロジェクトで試す

2人のメンバーに、同じ検証用リポジトリで新しいセッションを始めてもらいます。使用中の画面で/statusに設定が表示されるなら記録します。表示されない場合は、観察できる検証結果を記録します。APIキー、token、ログインファイルをスクリーンショットに含めないでください。次の依頼をコピーできます。

現在の作業ディレクトリと、画面に表示されているセッション設定を要約してください。まだファイルは編集しないでください。

この検証作業にWeb検索が必要かどうか、理由とともに簡潔に説明してください。ファイル編集やインストールコマンドの実行はしないでください。

プロジェクトがuntrustedとされている場合、Codexはそのプロジェクトの.codex/層を読み飛ばします。設定、hooks、rulesも対象です。一方、ユーザー設定とシステム設定は読み込まれます。リポジトリのファイルが誤っていると判断する前に、信頼状態を確認してください。内容を確認していないリポジトリを安易に信頼しないことも大切です。

4. 一度だけ上書きし、元に戻す

チームリーダーは、元に戻せるテストで優先順位表を確かめます。検証用リポジトリで1つのキーだけ値を変えたCLIセッションを開始し、通常のセッションと比較してください。

codex -c web_search=disabled

コマンド、作業ディレクトリ、期待値、観察した結果を記録します。検証セッションを閉じ、-cを付けずに新しいセッションを始めます。動作の変化しか観察できなかった場合は、そのように記録してください。それだけでは全設定層の読み込み経路を証明できません。

同じ人が簡単な確認と深い検討など、二つの作業方法を使い分けるならprofileが役立ちます。profileファイルはユーザー設定の隣に置き、リポジトリ内で定義されたものと決めつけないでください。CLI引数で選択します。

codex --profile [profile-name]

[profile-name]を実際の名前に置き換え、代表的な端末で試します。信頼済みリポジトリでは、プロジェクト設定はprofileより優先されます。profileには共通の既定値と異なる設定だけを入れます。

5. 環境変数と永続的な設定を分ける

OpenAIのEnvironment variablesによると、config.tomlは永続的な設定に使います。環境変数はshellのセッション、自動化で使う秘密情報、診断に適しています。CODEX_HOMEは設定、認証情報、ログ、セッションの保存場所を変えます。メンバーがこの変数を設定しているなら、~/.codex/config.tomlを編集する前に実際のパスを確認してください。

CODEX_API_KEYやCODEX_ACCESS_TOKENをリポジトリに入れないでください。OpenAIは、非対話のプロセスや信頼された自動化での利用を説明しています。CIの秘密情報ストアを使い、値をログに出さないようにします。RUST_LOGは診断情報の絞り込みに使うものです。

[shell_environment_policy]は、子プロセスに渡す環境変数を制限します。Config basicsでは、ignore_default_excludes = falseにすると、名前にKEY、SECRET、TOKENを含む変数の既定フィルタリングが有効になると説明しています。実際の秘密情報ではなくダミーの変数で試してください。これは子プロセスの環境を制御する仕組みであり、Codexがどの設定ファイルを読むかとは別の話です。

6. 設定変更をチームのレビューに組み込む

.codex/config.tomlを変更するpull requestには、理由、変更したキー、変更前後の検証結果を記載します。別のディレクトリからもメンバーに試してもらい、より近い設定層が適用されるか確認します。チームが-cやprofileを使うなら、その経路も試します。作業手順はAGENTS.mdに置き、共有skillには別の配布手順を用意します。

✅ 結果の例

3人のチームがリポジトリにweb_searchとmodel_reasoning_effortを追加します。2人は同じ期待値を記録します。3人目は-c web_search=disabledで異なるセッションを観察し、新しいセッションを開いて既定値に戻します。記録には、誰が別のCODEX_HOMEを使うか、Work Cloudのポリシーについて管理者の確認が残っていることも記します。良い結果とは、値が有効になった理由を説明できることです。

💡 精度を上げるコツ

  • 実際に試せるキーを二つか三つ選ぶところから始めます。
  • 作業ディレクトリを記録します。近い設定層が結果を変えることがあります。
  • 秘密情報と個人設定をリポジトリに入れません。
  • Codexの更新後は再検証し、Configuration Referenceを確認します。
  • 初めて使う人はTOMLの前にAIエージェントの基礎を読んでもよいでしょう。

⚠️ 知っておきたい制約

config.tomlは既定値を選ぶためのものです。管理者ポリシーの代わりにはならず、OSのアクセス権が付与された証拠にもなりません。リポジトリのファイルだけで外部アプリへのアクセス権を与えたり、権限が異なるアカウントに同じモデルを使わせたりすることはできません。広く展開する前に、実際の環境で検証してください。

OpenAIによると、CLIとIDEは設定層を共有します。Codex Cloud、Work Cloud、管理対象端末には別のポリシーが適用される場合があるため、管理者に確認してください。検証結果が予想と違うときは、証拠を残して原因を調べます。

❓ よくある質問

config-sampleを丸ごとリポジトリにコピーすべきですか？ いいえ。サンプルには多くのキーが載っています。チームに必要で、担当者とテストケースがあるキーだけを選びます。

.codex/config.tomlが反映されないのはなぜですか？ リポジトリが信頼済みか、現在のディレクトリに近い設定層があるか、CLI引数で上書きしていないかを確認します。そのキーがプロジェクト設定では無視されるかも確認してください。

Profileはリポジトリの設定より優先されますか？ 信頼済みリポジトリではプロジェクト設定が優先されます。CLI引数は両方より優先されます。

CODEX_HOMEを設定すると全員で同じ設定を共有しますか？ いいえ。その端末または実行環境にあるプロセスの基点が変わるだけです。各自が自分のパスと権限を確かめる必要があります。

-cで会社のポリシーを回避できますか？ そのように考えないでください。-cは設定の既定値より優先されますが、管理者の要件は別の制約です。値が拒否されたら管理者に確認します。

公式資料：Config basics、Configuration Reference、Environment variables、Sample Configuration。OpenAI Learn、2026年10月5日確認。

#Codex #ChatGPT #AIAgent #VibeCoding

他の記事