Codex CLIの「Background server has incompatible feature settings」は、そのセッションに必要な設定について、CLIと共有バックグラウンドサーバーの状態が一致していないことを示します。フラグを書き換える前に、両方のバージョンを比べてください。同じバージョンでも、サーバーに保存された上書き設定が残っている場合があります。再起動の成功表示だけでは、次のセッションが正常に開くとは確認できません。
この記事はOfox運営チームの英語診断ガイドを、AI支援で全文翻訳・編集したものです。対象はapi_key_model_discoveryなどを含むターミナルCLIの互換性ダイアログです。デスクトップアプリのワークスペース読み込みエラーや、Windowsで実行ファイルが見つからない問題とは分けて扱います。以下の起動段階の確認には、有料のモデル呼び出しは必要ありません。
元記事は2026年10月16日に公開報告と、リポジトリのコントリビューターによる限定的な修正説明（「response from codex」と明記された返信）を確認しています。当時のローカル確認はCLI 0.154.0でのコマンドの利用可否だけで、報告された0.161.0の障害を再現したものではありません。今回も稼働中のdaemonを停止・再起動しておらず、修復を実測したとは主張しません。OfoxはAPIサービスを提供していますが、プロバイダーの変更がこの起動時の設定交渉を直すことは示されていません。
2026年10月26日に出典を再確認しました。後述のIssueは現在closedですが、終了したこと自体は、すべてのビルドや明示的な上書き設定に対する修復保証ではありません。現在の公式CLIリファレンスでも、--no-daemonは対話CLIを共有サーバーなしで実行する指定であり、--remoteやcodex agentsとは併用できないとされています。インストール済みバージョンのヘルプと実際の選択肢を優先してください。
1. どの設定が、どちら向きに食い違っているか
ダイアログは、api_key_model_discoveryを有効にする必要がある場合と、無効にする必要がある場合の両方があります。この違いを読み落とさないでください。他人のスクリーンショットからフラグをコピーする前に、自分のメッセージを確認します。
まず次の4点を書き留めます。
| 記録する項目 | 必要な理由 |
|---|---|
| CLIのバージョンと実行ファイルのパス | 更新したものとは別のインストールをターミナルが呼び出している場合がある |
| 動作中のdaemonのバージョン | 共有サービスとクライアントのバージョンが異なる場合がある |
| 要求された機能と有効・無効の方向 | 有効化の要求と無効化の要求は逆の変更になる |
| 共有サービスに実行中・待機中の作業があるか | 再起動がほかのセッションへ影響する場合がある |
#51758には、CLIが古くdaemonが新しい場合と、CLIが新しくdaemonが古い場合の両方が報告されています。リポジトリのコントリビューターは、「response from codex」と明記した返信で、通常起動時にデフォルト機能の違いだけで再起動を求められる動作について、0.162.1で修正したと説明し、各自のインストール経路からCLIを0.162.1以降へ更新するよう案内しています。これは記載された動作に対する修正であり、すべての明示的な上書き設定やdaemonエラーが消えるという約束ではありません。
2. サービスを変更せずにバージョンを集める
問題が起きるターミナルで、まず次を確認します。
codex --version
codex app-server daemon version
codex features list
daemonのversionコマンドは、クライアントとサーバーのバージョン情報を確認するためのものです。daemonが動作しているかも含め、そのビルドが実際に返したフィールドを記録します。欠けている値をCLIのバージョンで補わないでください。
サブコマンドが不明と表示された場合は、そのバージョンのヘルプを確認します。診断コマンドが未対応であることを、別のdaemon障害として数えないでください。
codex app-server daemon --help
codex features --help
macOSやLinuxでは、シェルが選んでいる実行ファイルを確認します。
command -v codex
PowerShellでは次を使います。
Get-Command codex | Select-Object Source
これらが示すのは現在のシェルが解決するコマンドです。デスクトップアプリに同梱されたすべての実行ファイルを列挙するものではありません。
npmで更新しても、別のパッケージマネージャー由来のバイナリが選ばれていれば、そのCLIは変わらないことがあります。実際に起動しているインストールに対応するアップデーターを使い、更新後は新しいターミナルでバージョンを確認します。すべてのパッケージマネージャーのコピーを一度に入れ直さないでください。
3. 結果に応じて次の確認を決める
| 分かったこと | 次に行うこと | 確認する結果 |
|---|---|---|
| CLIとdaemonのバージョンが異なり、意図した上書き設定はない | 修正説明を確認し、該当クライアントを通常のインストール経路で更新する | 両方の報告バージョンと、新規起動の結果 |
| バージョンは同じだが、要求されたフラグが一致しない | CLIのfeature listとdaemonに保存された該当設定を比べる | 明示的な上書き設定が残っているか |
| daemonが報告されない | 起動エラーを保存し、その版のdaemonヘルプを読む | 設定交渉ではなくサービス起動の問題か |
| メッセージがファイル欠落やWindowsのパスを示す | app-serverの起動診断へ進む | バックエンドプロセスが実際に起動できるか |
バージョンの一致は有用な情報ですが、正常性の完全な確認ではありません。#52085には、同じバージョンでも起動時に設定が一致しなかった報告があります。
この事例では、サーバーがCodexによる管理下にないため、再起動の選択肢も無効でした。自分のダイアログに同じ説明が出る場合は、表示された一時的な経路を使うか、サーバーの管理者と調整します。独立して管理されているサービスをCLIが再起動できるとは限りません。
4. 影響範囲を見て復旧方法を選ぶ
対象バージョンのダイアログには、その呼び出しだけdaemonなしで動かす、表示された設定で再起動する、キャンセルする、という選択肢がありました。名称や対応フラグは変わり得るので、自分のクライアントに実際に表示された選択肢を使ってください。
| 選択肢 | 何を選ぶことになるか | 止まるべき条件 |
|---|---|---|
| Run without daemon this time | 共有サーバー設定を変更せず、提示された一時的な経路を使う | 必要なセッションやワークフローがその経路で使えない |
| Restart with these settings | 共有サーバーに永続的な設定変更を適用し、再起動する | 実行中・待機中の作業や、ほかのクライアントの要件が分からない |
| Cancel | 現在の状態を保ったまま証拠を集める | バージョンと管理主体の確認後に戻る |
急ぎの作業なら、一時的な経路で共有サービスをすぐに変更せず続けられる場合があります。ただし恒久的な修復ではなく、リモートやバックグラウンドのすべての機能がdaemonなしでも動く証拠にもなりません。既存タスクのresumeやforkが目的なら、その意図と引数を保ち、誤って無関係な新規作業を始めないようにします。前述のとおり、現在の公式リファレンスでは--no-daemonと--remote、codex agentsの併用はできません。
永続的な再起動を選ぶ場合は、先に作業を保存し、同じサービスを使うほかのクライアントへの影響を確認します。最初の行のフラグだけでなく、ダイアログに提案された設定一式を読みます。変更後は有効な設定を確認し、新しいセッションで起動を試します。通常のCLIコマンドだからといって、共有サービスの再起動を無害とは扱わないでください。
5. 再起動が成功しても不一致が残る理由
#51787は、0.161.0で、enableフラグ付きの再起動が成功扱いになっても、競合する保存済み上書き設定が残った事例です。報告者の対話式の復旧経路では保存状態が変わり、続くセッションが起動できたとされています。このIssueは確認時点でclosedですが、それだけで自分のインストールにおける各バージョンの動作は保証されません。
区別すべきなのは、プロセスの再起動と、実際に有効になった設定です。同じ永続設定を読み直したままでも、プロセス自体は正常に再起動できます。したがって、同じ再起動を繰り返すだけでは診断になりません。
報告されたファイルは、有効なCodexホーム配下のapp-server-daemon/settings.jsonです。CODEX_HOMEをカスタマイズしているなら、~/.codexと決めつけず、そのホームを確認します。名前付きの設定プロファイルがあることだけでは、別のホームディレクトリが使われるとは判断できません。
読むのは該当する機能の上書き設定だけにし、設定ファイル全体を公開しないでください。codex features listの値と、ダイアログが求める有効・無効の方向を比べます。
たとえば、保存値がfalseでセッションがtrueを必要としているなら、意味のある差異です。ただし、差が見つかったことはファイル全体を削除してよい理由にはなりません。ほかの設定がリモート管理や別の利用者に関係している可能性があります。意図して変更する前に非公開のバックアップを取り、対応している復旧操作を使い、戻せるよう元の値を保管します。管理主体が分からないなら、サービスの管理者に確認するまで変更を止めます。
6. 最初の対応として変更しないもの
- API認証情報。 この不一致はモデル要求より前に発生し得ます。認証状態を消しても、サーバーの機能設定が変わったことにはなりません。
-
モデル名。 設定の不一致は
model_not_foundとは別です。モデル設定を編集する前に、どの段階のエラーかを確認します。 - Codexの全データ。 ホーム全体を削除すると無関係な状態も失い、変更前後の診断が難しくなります。
- セキュリティ設定。 サンドボックスやファイルアクセスを広げても、CLIとdaemonの互換性が成立したことは示せません。
設定全体の理解、Windowsのパス・ランタイム欠落、デスクトップのワークスペース読み込みは、それぞれ対応する診断に分けます。記事末尾の原文から関連ガイドを参照できますが、症状が異なるのに同じ修復を当てはめないことが先です。
7. 新しいセッションで修復を確認する
受け入れ確認は、次の3段階に分けます。
- バージョンと該当機能の状態を取り直す。 変わったものと変わっていないものを記録します。CLIだけが更新されても、動作中サーバーが変わった証拠にはなりません。
- 元の失敗した経路で、新しいセッションを起動する。 互換性ダイアログなしで通常の入力画面に到達すれば、起動時の設定交渉を確認できます。この段階の確認に有料モデル要求を送る必要はありません。
- 元のワークフローを別途確認する。 既存タスクの再開が目的なら、そのタスクを選び、新たな作業を依頼する前に状態を確認します。バックグラウンドやリモートの動作は、必要なワークフローに含まれる場合に確認します。
一時的なdaemonなしの経路だけが動くなら、「回避策は利用中、共有サーバーの不一致は未解決」と記録します。通常の新規起動は成功しても別のクライアントが失敗するなら、その回帰を記録し、修復完了とはしません。
サポートへの引き継ぎには、次の記録を使えます。
観測日時とタイムゾーン：
OSとインストール方法：
CLIバージョン／シェルが選ぶ実行ファイル：
daemonバージョン／動作中または利用不可：
要求された正確な機能名と、有効化・無効化の方向：
CLIの機能値／サーバーに保存された該当の上書き設定：
意図的な上書き設定：あり／なし／不明
共有サービスの実行中・待機中の作業：あり／なし／不明
試した操作と、その後の有効な設定：
通常の新規起動／一時的な経路／元のワークフローの結果：
共有前に認証情報や非公開のパスが含まれていないか確認します。必要なのは設定の食い違いと確認した結果であり、設定一式のダンプではありません。修復の成功は、意図した状態を保って新たに起動できることです。再起動コマンドの終了コードが0だったことだけでは足りません。
英語原文と関連する症状別ガイド：Codex Background Server Has Incompatible Feature Settings: What to Check