Claude CodeのOpus 4.1自動読み替えを止める環境変数

CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAPが止めるもの

CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAPは、Anthropic API上でOpus 4.0とOpus 4.1が現行のOpusへ自動で読み替えられる処理を止める環境変数です。1に設定すると読み替えが走らなくなり、指定した旧モデルのまま扱われます。説明文には「意図的に古いモデルへ固定したいときに使う」とあります。

効く範囲は狭く、Anthropic API以外では何も起きません。Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundryでは、そもそも読み替え自体が走らないからです。

読み替えが起きていたかどうかは、--model claude-opus-4-1のように旧モデルを名指しした場合に表れます。Claude Codeは、要求したモデルが読み替えられるとき、そのモデル名を挙げた警告を出します。つまり「旧モデルを指定したのに、別のモデルで動いていた」という状況を自分で気づけるようになっています。

旧Opusは引退済みなので、固定の前に生死を確かめる

この変数を使う前に確認したいのが、固定したい旧モデルが今も動くかどうかです。モデル廃止の一覧では、claude-opus-4-20250514が2026年6月15日に、claude-opus-4-1-20250805が同年8月5日に引退しています。

通知から引退までは、Opus 4もOpus 4.1も約2か月でした。引退したモデルへのリクエストは失敗する、とモデル廃止のページは説明しています。ここから読み取れる帰結は一つです。Anthropic APIでCLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP=1を立てて旧Opusを名指しすると、読み替えという逃げ道を自分で塞いだうえで、引退済みのモデルへリクエストを送ることになります。この場合にClaude Code側へ出るエラーの文言は、環境変数の説明にもモデル設定のページにも載っていません。

逆に言えば、読み替えが働いているうちは、古いIDを書いたまま放置されたスクリプトでも動き続けていたことになります。

読み替えが走る環境、走らない環境

読み替えの有無は、どのプロバイダー経由で使っているかで決まります。

Claude Platform on AWSについては、環境変数の説明に記載がありません。この経路で旧Opusを使う予定がある場合は、claude --modelで指定したときの警告の有無で挙動を確かめるのが確実です。

ここで一つ注意したいのは、「読み替えが走らない」と「そのモデルがまだ使える」は別の話だという点です。引退日の一覧は、Anthropic API、Claude Platform on AWS、Foundryの3つに適用されます。BedrockとGoogle Cloudは各社が自前の引退日程を持つため、日付が食い違うことがあります。Foundryは読み替えがなく、引退日はAnthropic側の日程に従う、という組み合わせになります。

状況別に見た、1を立てる意味

どの経路で何を使っているかで、変数の意味が変わります。

opusのようなエイリアスは、読み替えの対象ではなく、解決先がそのときの最新に更新される仕組みです。この2つは混同しやすいので、変数が関わるのは「旧モデルのIDを直接書いたとき」だけと覚えておくと整理がつきます。

設定のしかた

シェルで設定する方法と、settings.jsonのenvに書く方法があります。シェルの値は起動時に読まれ、変えた後は次のclaude起動から効きます。

export CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP=1
claude --model claude-opus-4-1

チーム全体や特定プロジェクトに揃えるなら、envブロックに書きます。次は公式の書式に沿った例です。

{
  "env": {
    "CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP": "1"
  }
}

書き込み先で適用範囲が変わります。~/.claude/settings.jsonは自分の全プロジェクト、.claude/settings.jsonはリポジトリの全員、.claude/settings.local.jsonは自分のそのプロジェクトだけ、管理設定は組織全員です。同じ変数をシェルとenvの両方で設定した場合は、多くのセッションで設定ファイルの値が使われます。ファイル同士では、管理設定がユーザー設定やプロジェクト設定の同名の値を上書きします。

読み替えが起きたかを確かめる

読み替えの有無は、警告と出力で追えます。

• 対話セッション: 起動時の通知に、要求したモデル名が出る
• 非対話モード: v2.1.182から、既定のテキスト出力のとき同じ警告が標準エラーに書かれる
• subagentのfrontmatter: modelを指定していても、同じ確認の対象になる

--output-format jsonとstream-jsonでは、標準エラーの警告が出ません。この形式でCIに組み込んでいる場合は、結果メッセージのmodelUsageフィールドから実際に使われたモデルを読みます。

claude -p "ok と返して" \
  --model claude-opus-4-1 \
  --output-format json | jq '.modelUsage | keys'

この出力に旧モデルのIDが残っていれば固定が効いており、現行Opusのモデル名が並んでいれば読み替えが働いています。上のコマンドは、結果のmodelUsageに並ぶ項目名を取り出します。

旧モデルのIDが残っている場所を洗い出す

読み替えに頼って動いている自動化は、IDを探せば見つかります。リポジトリ全体とエージェント定義を一度検索してみてください。

grep -rnE "claude-opus-4(-0|-1)?(-2025|[^-0-9]|$)" \
  --include="*.md" --include="*.json" \
  --include="*.yml" --include="*.sh" .

見つかりやすいのは、次の4か所です。

• .claude/agents/のsubagent定義にあるmodel:行
• CIのワークフローやシェルスクリプトの--model引数
• settings.jsonのmodelとANTHROPIC_DEFAULT_OPUS_MODEL
• 個人の~/.claude/settings.jsonに残った古い値

見つかったら、変数で読み替えを止める前に、IDを現行のものへ書き換えるほうが筋のよい直し方です。

固定したいなら、変数以外の手段のほうが向いている

この変数の説明は、旧モデルへ固定したい場面に使うよう案内しています。ただ、現行世代の中でバージョンを固定したいだけなら、別の仕組みが用意されています。

• エイリアスの解決先を決める: ANTHROPIC_DEFAULT_OPUS_MODELに具体的なモデルIDを入れると、opusとopusplanのプラン段階がそのモデルを指す
• フルモデル名で指定する: claude-opus-5-5のような名前を直接書けば、エイリアスの更新に巻き込まれない
• 組織でモデルを絞る: 管理設定のavailableModelsで使えるモデルを決め、deniedModelsで新しいリリースを止める(deniedModelsとavailableModelsMatchはv2.1.283以降が要件)

エイリアスの解決先は更新で変わります。opusは、v2.1.280からAnthropic APIでOpus 5.5を指します。この変更はClaude Codeを更新した時点で入るので、動作を固定したいチームは、エイリアスに頼らずIDで書くか、環境変数で解決先を決めておく必要があります。固定とエイリアスのどちらが向くかという設計判断は、Claudeモデルの引退で自動化が止まる日で整理しています。

旧Opusの指定は、v2.1.69から現行Opusへ解決されている

v2.1.69では、--model claude-opus-4-0と--model claude-opus-4-1が、廃止済みのOpusではなく現行のOpusに解決される修正が入っています。

古いIDを書いたまま現行モデルで動いている状況は、最近始まった話ではありません。意図しないまま現行のOpusで動いている自動化があっても不思議ではないので、先ほどのmodelUsageの確認を一度やっておくと、手元の実態がはっきりします。現行のOpusでの使いこなしは、Opus 5.5をClaude Codeで使いこなすにまとめました。

DISABLEの名前ほど影響は大きくない — 止まるのは旧Opus 2種の読み替えだけ

名前はDISABLEで始まりますが、効果は「止める」という言葉から連想するほど大きくありません。止まるのは旧Opus 2種の読み替えだけで、引退した事実は覆りません。

同じDISABLE_で始まる変数には、モデル別にキャッシュを止めるDISABLE_PROMPT_CACHING_OPUS/SONNETがあります。設定項目全体の一覧はClaude Code settings完全ガイドにあります。

まとめ

この変数は、Anthropic APIでOpus 4.0と4.1を現行のOpusへ読み替える処理を止めるスイッチです。両モデルはすでに引退しているので、固定して得られるものは限られます。まずはmodelUsageと警告で手元の自動化が実際にどのモデルで動いているかを確かめ、旧IDが残っていれば現行のIDに書き換える。それが済んでから、固定の要否を判断する順番が現実的です。