ANTHROPIC_MODEL環境変数でモデルを固定する方法

ANTHROPIC_MODELはClaude Codeを起動するときに使うモデルを、その場で指定する環境変数です。設定ファイルを書き換えずに、CIジョブやDockerコンテナ、一時的な検証セッションだけ別モデルで動かしたいときに使います。値にはエイリアス(sonnetなど)も正式なモデル名も渡せます。

ただし、指定したのに別のモデルで動く、サブエージェントだけ違うモデルになる、誤った名前でも起動できてしまう、といった場面が実際にあります。この記事は基本の渡し方から、そうした食い違いの原因までを順に扱います。

ANTHROPIC_MODELの基本的な使い方

シェルでその場に渡すのが基本形です。

export ANTHROPIC_MODEL='claude-sonnet-5'
claude

1回だけ試したいなら、コマンドの前に置いて渡します。

ANTHROPIC_MODEL='claude-opus-4-8' claude -p "このPRをレビューして"

--modelフラグとANTHROPIC_MODELは、どちらもその値で起動したセッション限りの指定です。/modelで選ぶ場合と違い、次回起動時のデフォルトとしては保存されません。複数のターミナルで別々のモデルを同時に使うなら、ターミナルごとに--modelかANTHROPIC_MODELを付けて起動します。

恒久的に変えたいときは、設定ファイルのmodelフィールドに書きます。エイリアスの解決先そのものを変えるANTHROPIC_DEFAULT_*_MODEL系との違いはANTHROPIC_DEFAULT_FABLE_MODELとはにあります。

指定したのに別のモデルで動くとき

「ANTHROPIC_MODELを設定したのに/modelが違うモデルを示す」ときは、まずモデルが決まる順番を疑います。

この順番から、次の食い違いが起きます。

/modelで保存したのに次の起動で戻るのは、ANTHROPIC_MODELがシェルに残っているときです。保存したmodelより変数が優先されます。公式のトラブル解説にも、/modelの選択が上位の設定に負けて再適用されない原因の1つとして挙がっています。

設定ファイルのenvブロックに書いた値は、シェルの値を上書きします。settings.jsonのenvにANTHROPIC_MODELを書くと、シェルから継承した値が置き換わります。シェルのexportを直しても変わらないときは、envブロックを確認します。例外は、Claude Desktopアプリやセルフホスト環境のランナーが起動したセッションです。起動環境が既に設定している変数については、envの値が無視されます。

再開したセッションが、前回のモデルのままのこともあります。claude --resumeなどで再開すると、記録されたモデルを保つのが基本です。新しい起動で--modelかANTHROPIC_MODELを指定すれば、そちらが復元されたモデルより優先されます。Bedrock・Google Cloud's Agent Platform・Microsoft Foundryのように、AnthropicのモデルIDでなくデプロイ固有のIDを使う提供元では、そもそも復元されず、毎回通常の順番で決まります。

.zshrcに古い指定が残っていることもあります。過去の検証で書いたexport ANTHROPIC_MODEL=...が残っていると、意図しないモデルで動き続けます。env | grep ANTHROPIC_MODELで、実際に渡っている値を確認するのが最初の切り分けです。応答の質が落ちたように感じる場合の確認手順はClaude Codeの応答品質が落ちたときの確認手順にあります。

シェルの環境変数は、起動済みのセッションには届きません。セッション中にシェルで書き換えても、次に新しく起動するまで反映されません。

誤ったモデル名を指定するとどうなるか

指定した文字列が正しいか確認されるタイミングは、経路と接続先で変わります。

エラーの全文はThere's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.の形です(対話式CLIの場合)。v2.1.160以降は実行面によって末尾の案内が変わり、-pではRun --modelになります。/modelを開いて選び直すのが早道です。似た文言で原因が違うケースは「is not a recognized model id」の意味と対処で扱っています。

Amazon Bedrock・Google Cloud's Agent Platform・Microsoft Foundry経由の場合や、ANTHROPIC_BASE_URLでLLMゲートウェイにつないでいる場合は、モデル名の形式を提供元が決めます。Claude Codeは、提供元ネイティブのIDや未知の文字列を事前チェックせずそのまま渡し、提供元が認識できなければそこでエラーになります。AnthropicのモデルIDは、Bedrock・Google Cloud's Agent Platform・Mantleでは、提供元がそのバージョンに対応していればmodelOverridesが無くても提供元固有のIDに変換されます。

組織のモデル制限にかかったときの通知

管理者がavailableModelsでモデルを絞っている組織では、許可リスト外のモデルをANTHROPIC_MODELで指定してもそのモデルでは始まりません。--modelや設定ファイルのmodelと同じ扱いで、起動時に許可された既定モデルへ差し替えられ、要求したモデル名と差し替え後のモデル名の両方を含む警告が出ます。通知の文言はModel "<name>" is restricted by your organization's settings. Using <model> instead.です。

/model <name>でセッション中に許可外のモデルを選ぶと、こちらは差し替えではなく拒否されます。起動時は差し替えて続行、セッション中は拒否、という違いがあります。opusのようなファミリーエイリアスなら、Anthropic APIとClaude Platform on AWSでは、許可リストが許す範囲でそのファミリーの最新版に解決されます。

なおANTHROPIC_DEFAULT_MODELは、許可リストに合わないと差し替えではなく無視されます。

BedrockとAgent Platformではセッション単位のピン留めとして働く

Amazon Bedrock・Google Cloud's Agent Platform・Microsoft Foundry・Claude Platform on AWS経由でClaude Codeを配布している場合、opusやsonnetは提供元ごとの組み込みの既定モデルIDに解決されます。この既定は最新のAnthropicリリースに追いついていないことがあり、利用者のアカウントでまだ有効になっていないこともあります。

既定モデルが使えないとき、Amazon BedrockとGoogle Cloud's Agent Platformでは、通知とともに既定モデルより前のバージョンへ自動で切り替わります。Opus系の既定でOpusが1つも使えない場合は、Sonnet系の既定へ切り替わります。Microsoft Foundryにはこの起動時チェックが無く、エラーとして表れます。

ここから先はBedrockとAgent Platformの話です。--model・ANTHROPIC_MODEL・設定ファイルのmodelのいずれかで特定のSonnet・Opusバージョンを指定して始めると、そのバージョンが対応するエイリアスのセッションの既定として扱われます。置き換えるはずだった組み込みの既定への起動時チェックは行われず、フォールバックの通知も出ません。v2.1.211より前は、明示指定していてもチェックが走り、通知が出ることがありました。

BedrockとAgent Platformでは、ANTHROPIC_MODELはその場でモデルを選ぶだけでなく、提供元側の既定のずれを避ける手段にもなります。ただし効くのは起動したセッションだけです。チームへ恒久的に配るなら、ANTHROPIC_DEFAULT_OPUS_MODELのような系統別の変数が向いています。

サブエージェントのモデルは別の変数で決まる

ANTHROPIC_MODELが決めるのはメインセッションのモデルです。サブエージェント・agent teamのメンバー・workflow内のエージェントには、専用の変数があります。

CLAUDE_CODE_SUBAGENT_MODELを設定すると、Claude Codeはまずそのモデルを試します。許可リストで弾かれた値がopusのようなファミリーエイリアスなら、そのファミリーで許可された最新版に差し替わります。それ以外の値や、差し替えられない場合は、継承したモデルで動きます。

この変数は既定であって、強制ではありません。Claudeがサブエージェントを呼び出すときに渡すモデルと、サブエージェント定義のmodelfrontmatter(inheritを含む)のほうが優先されます。v2.1.251より前はこの変数が最優先で、両方を上書きしていました。古い解説を読んで「変数を置けば全部揃う」と思うと、今は食い違います。

全員を1つのモデルに揃えたいなら、CLAUDE_CODE_SUBAGENT_MODEL_FORCEを1にします(v2.1.257以降)。両方の変数を設定すると、サブエージェントはCLAUDE_CODE_SUBAGENT_MODELのモデルで動きます。FORCEだけを設定した場合は、メインの会話と同じモデルになります。

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

inheritを指定したCLAUDE_CODE_SUBAGENT_MODELは、未設定と同じ扱いです。組み込みのExploreとPlanのモデルは、この変数だけでは変わらず、FORCEが要ります。

手元のClaude Codeで確認できること

v2.1.285でclaude --helpを実行し、モデル指定に関わる部分を取り出しました(空の設定ディレクトリで実行し、モデルは呼び出していません)。

$ claude --version
2.1.285 (Claude Code)
 
  --model <model>          Model for the current session. Provide
                           an alias for the latest model (e.g.
                           'fable', 'opus', or 'sonnet') or a
                           model's full name.
  --fallback-model <model> Enable automatic fallback to specified
                           model(s) when the default model is
                           overloaded or not available. Accepts a
                           comma-separated list to try each in
                           order. Re-tries the primary at the start
                           of each user turn.

--modelの説明が「current session」限りと書かれているのは、ANTHROPIC_MODELと同じ性質です。ヘルプにはANTHROPIC_MODELという語は出ません。実際に効いている値は、env | grep ANTHROPIC_MODELで見るのが確実です。

--fallback-modelは別物で、既定モデルが過負荷や利用不可のときの切り替え先です。設定ファイルのfallbackModelに配列で書くこともでき、その中の"default"はアカウントの既定モデルに展開されます。ANTHROPIC_DEFAULT_MODEL側では、defaultは無視される値の1つです。

まとめ

1回だけ別モデルで動かすならANTHROPIC_MODEL、次回以降も変えたいなら/modelか設定ファイル、サブエージェントまで揃えるならCLAUDE_CODE_SUBAGENT_MODEL_FORCEと、目的で使い分けます。環境変数全体はClaude Code環境変数リファレンスにあります。