Codex CLIが起動できない：unknown variant xhigh を最短で直す¶

この記事の対象者

Codex CLI 0.50.0 を使用している開発者
unknown variant xhigh エラーで起動できなくなった方
最短で復旧したい方

Codex CLI 実行時、設定読み込みで即座に落ちるケースがあります。

Error loading configuration: unknown variant `xhigh`, expected one of `minimal`, `low`, `medium`, `high`
in `model_reasoning_effort`

この記事では 最短手順でコピペ復旧 し、チーム運用での 再発防止 まで整理します。

何が起きているか¶

重要ポイント

これはAPIやネットワーク以前の問題です。設定ファイルのスキーマチェックで落ちています。

Codex CLI は起動時に設定ファイル（ユーザー設定やプロジェクト設定）を読み込みます。model_reasoning_effort は列挙値（enum）として厳格に検証され、CLI が認識しない値（今回なら xhigh）があると 起動直後に fail-fast します。

つまり「モデル問い合わせに行く前に設定のスキーマチェックで落ちている」ため、APIキーや回線を疑っても解決しません。

最短解決（コピペで復旧）¶

xhigh を high に置換することで復旧します。対象は以下の2系統です。

ユーザー設定: ~/.codex
リポジトリ配下の Team Config: .codex

# xhigh を high に一括置換
grep -RIl --exclude-dir .git -E 'model_reasoning_effort *= *"xhigh"' ~/.codex .codex 2>/dev/null \
| while read -r f; do sed -i 's/model_reasoning_effort *= *"xhigh"/model_reasoning_effort = "high"/g' "$f"; done

# 再実行
codex /model

確認

codex /model が正常に動けば復旧完了です。

直らない場合の切り分け¶

環境変数が上書きしている¶

設定ファイルではなく環境変数で xhigh を注入している場合があります。

env | grep -i -E 'codex|reason|effort|openai'

xhigh を含む値が見つかったら unset して再実行します。

unset CODEX_MODEL_REASONING_EFFORT
codex /model

設定場所が別にある¶

次のコマンドで "犯人ファイル" を炙り出せます。

grep -RIn --exclude-dir .git --exclude-dir .venv --exclude-dir node_modules \
  -E 'model_reasoning_effort|xhigh' ~ 2>/dev/null | head -50

再発防止¶

CIで弾く¶

xhigh 混入はテンプレ差し替えやコピペで起きがちです。CIで弾くのが安いです。

grep -RIn -E 'model_reasoning_effort *= *"xhigh"' .codex ~/.codex 2>/dev/null && exit 1 || true

CLIバージョンを固定する¶

「テンプレが新しく、CLIが古い」だけで全員の起動が壊れます。npm/パッケージマネージャで codex-cli を固定 し、更新は計画的に行うのが安全です。

まとめ¶

ポイント

unknown variant xhigh は設定読み込み時の enum バリデーション で落ちている
xhigh を high に置換して最短復旧
再発防止にはCIチェックとCLIバージョン固定が有効