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で切り替えるのではなく、ターミナルごとに--modelかANTHROPIC_MODELを指定して起動するのが確実です。設定を永続化したい場合は、設定ファイルのmodelフィールドに書きます。詳しい優先順位とANTHROPIC_DEFAULT_*_MODEL系(エイリアスの解決先を変える変数)との役割の違いはANTHROPIC_DEFAULT_FABLE_MODELとはにまとめてあり、ANTHROPIC_MODELはそちらで説明する4段階の優先順位のうち上から3番目にあたります。

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

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

Anthropic APIに直接つないでいる場合、/modelでの切り替えは文字列のチェックを受けます。エイリアス・/modelピッカーの候補・claude-で始まる名前・カスタムモデルオプション・modelOverridesのいずれにも当てはまらない文字列は、切り替えそのものが拒否されます。ところがこのチェックは--modelフラグ、ANTHROPIC_MODEL環境変数、設定ファイルのmodelフィールドには及びません。この3つの経路で誤った値を渡した場合、起動時点ではエラーにならず、最初のリクエストでThere's an issue with the selected modelというエラーになります。タイプミスに心当たりがあるなら、まず/modelを開いて正しい名前を選び直すのが早道です。似た文言のエラーで原因が異なるケースは「is not a recognized model id」の意味と対処で扱っています。

Amazon Bedrock・Google Cloud's Agent Platform・Microsoft Foundry経由の場合や、ANTHROPIC_BASE_URLでLLMゲートウェイにつないでいる場合は、モデル名の形式そのものを提供元が決めるため、Claude Code側はチェックせずそのまま渡します。この経路では、提供元が認識できない文字列を渡した時点でエラーになります。

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

availableModelsでモデルを絞っている組織では、ANTHROPIC_MODELで許可リスト外のモデルを指定しても、そのモデルではセッションが始まりません。--modelフラグや設定ファイルのmodelフィールドと同じ扱いで、Claude Codeは起動時に許可された既定モデルへ値を差し替え、要求したモデル名と差し替え後のモデル名の両方を含む通知を表示します。/model <name>でセッション中に切り替えようとした場合も同じ許可リストで弾かれる一方、ANTHROPIC_MODEL側は差し替えたうえで起動を続ける、という扱いの違いがあります。opusのようなファミリーエイリアスを指定した場合は、Anthropic APIとClaude Platform on AWSでは許可リストが許す範囲でそのファミリーの最新版に解決されます。この許可リストをANTHROPIC_MODELで迂回する経路は用意されていません。

サードパーティ配布ではセッション単位のピン留めとして働く

Amazon Bedrock・Google Cloud's Agent Platform経由でClaude Codeを配布している場合、opusやsonnetといったエイリアスは提供元ごとの組み込みの既定モデルIDに解決されます。この既定は最新のAnthropicリリースに追いついていないことがあり、既定が示すモデルが利用者のアカウントでまだ有効になっていないこともあります。既定モデルが利用できないとき、Amazon BedrockとGoogle Cloud's Agent Platformでは通知とともに1つ古いバージョンへ、あるいはOpus系の既定でOpusが1つも使えない場合はSonnet系の既定へ自動的に切り替わります。Microsoft Foundryにはこの起動時チェックが無いため、エラーとして表れます。

ここで--model・ANTHROPIC_MODEL・設定ファイルのmodelフィールドのいずれかで特定のSonnet・Opusバージョンを指定してセッションを始めると、その版が対応するエイリアスのそのセッションの既定として扱われ、組み込みの既定を置き換えていたはずの起動時チェック自体がスキップされます。つまりANTHROPIC_MODELは、その場でモデルを選ぶだけでなく、提供元側の既定ドリフトを回避する手段にもなります。ただし効果は起動したセッション限りで、恒久的にバージョンを固定したいチーム配布では、ANTHROPIC_DEFAULT_OPUS_MODELのような系統別の変数を使うほうが向いています。

サブエージェントには別の変数が要る

ANTHROPIC_MODELが固定するのはメインセッションのモデルだけです。Claude Codeが呼び出すサブエージェント・agent teamのメンバー・workflow内のエージェントは、この変数の影響を受けません。サブエージェントのモデルをまとめて変えたいときは、代わりにCLAUDE_CODE_SUBAGENT_MODELを使います。こちらはエイリアスかフルネームを受け取り、サブエージェント呼び出し時のmodelパラメーターやサブエージェント定義側のmodelfrontmatterより優先されます。通常の解決順に戻したい場合は値をinheritにします。「モデルを固定したのにサブエージェントだけ違うモデルで動いている」という状態は、たいていこの変数の指定漏れが原因です。

よくあるつまずき

セッションを再開したのにANTHROPIC_MODELの値が使われない。claude --resumeなどで再開したセッションは、記録された時点で使っていたモデルを保つのが基本です。ただし新しい起動で--modelやANTHROPIC_MODELを指定した場合は、この復元されたモデルより優先されます。提供元固有のデプロイIDを使うBedrock・Google Cloud's Agent Platform・Microsoft Foundryでは、そもそも復元時にモデルを保持する仕組みがなく、毎回通常の優先順位で解決される点も異なります。

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

シェルの値と/modelの表示が食い違う。/modelは現在有効なモデルを表示しますが、ANTHROPIC_MODELはそのセッションを起動した瞬間にしか読まれません。セッション中にシェル側の環境変数を書き換えても、次に新しく起動するまで反映されません。

まとめ

ANTHROPIC_MODELは、設定ファイルを触らずにそのセッションだけモデルを固定する変数です。優先順位では/modelと--modelの下、設定ファイルのmodelフィールドの上に位置し、Anthropic APIへ直接つなぐ場合だけ/modelと同じ文字列チェックの対象外になる点、組織の許可リストに掛かると通知付きで置き換わる点、サードパーティ配布では起動時チェックを回避するピン留めとして働く点を押さえておくと、意図しないモデルで動くトラブルを避けられます。恒久的にチームへ配布したい場合はANTHROPIC_DEFAULT_*_MODEL系の変数を、環境変数全体を見渡したい場合はClaude Code環境変数リファレンスを参照してください。

よくある質問

ANTHROPIC_MODELとsettings.jsonのmodelフィールドはどちらが向いていますか

一時的に別モデルを試すだけならANTHROPIC_MODEL、チーム全員に同じモデルを使わせ続けたいなら設定ファイルのmodelフィールドが向いています。ANTHROPIC_MODELを設定した状態で起動すると、その回だけmodelフィールドの値を上書きします。

ANTHROPIC_MODELにdefaultという文字列は使えますか

ANTHROPIC_MODEL自体にdefaultという特別な値の扱いはありません。この文字列が意味を持つのはfallbackModelのチェーンを設定するときで、"default"と書くとアカウントの既定モデルに展開されます。

CIでANTHROPIC_MODELを使うときの注意点はありますか

非対話モード(-pフラグ)でもセッション単位の優先順位はそのまま適用されます。CIのジョブ定義に環境変数を直接書くと誤って別のジョブへ引き継がれることがあるため、ジョブごとにスコープを絞って設定するか、--modelフラグで明示的にコマンドへ渡すほうが取り違えを避けやすくなります。