ピン留めモデルの表示名と対応能力を環境変数で上書きする — Claude Code

ピン留めモデルの表示名と能力は環境変数で決められる

ANTHROPIC_DEFAULT_OPUS_MODEL などでモデルをピン留めすると、/modelピッカーの行は「Claude Codeが認識できるIDならモデル名、そうでなければ生のID」で表示されます。Amazon Bedrockの推論プロファイルARNのような長い文字列がそのまま並ぶ状況は、この既定から生まれます。

表示を直すのが _NAME と _DESCRIPTION、機能の可否を宣言するのが _SUPPORTED_CAPABILITIES です。3つの接尾辞は、ピン留め用の4変数とカスタム行用の変数のどちらにも付きます。

親が5種、接尾辞が3種なので、上書き用の変数は合計15個です。個別に覚える必要はありません。「親の変数名 + _NAME / _DESCRIPTION / _SUPPORTED_CAPABILITIES」という規則だけで足ります。

表示名が生のIDになる条件

公式の説明では、行の表示は次の2通りに分かれます。

• 認識される場合: Anthropic APIのID、またはプロバイダーやゲートウェイ形式のIDが、Claude Codeの知っているモデルと完全一致するとき。[1m] サフィックスの有無は問いません。us.anthropic.claude-sonnet-4-5-20250929-v1:0 をピン留めすると、行は Sonnet 4.5 と読めます
• 認識されない場合: 上記以外のID。アプリケーション推論プロファイルのARNや、Claude Codeがまだ知らないバージョンのIDが該当します。ただし modelOverrides がそのIDの文字列に対応づけていれば別です

Microsoft Foundryは特殊です。デプロイ名がユーザー定義のため、Claude Codeはピン留めされたIDを一切認識せず、既定の表示はデプロイ名になります。

モデル名が表示される行では、既定の説明文にピン留めされたIDが含まれます。名前だけ見ても、どのIDが動いているかは追えます。

_NAMEと_DESCRIPTIONで行の見た目を直す

_NAME は行の名前、_DESCRIPTION は説明文です。未設定のときの既定は変数によって違います。

Sonnetをゲートウェイ経由で使っている場合を例にします。名前と説明だけを足す最小構成は次のとおりです。

export ANTHROPIC_DEFAULT_SONNET_MODEL='my-gateway/sonnet-prod'
export ANTHROPIC_DEFAULT_SONNET_MODEL_NAME='Sonnet (社内ゲートウェイ)'
export ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION='本番用の固定バージョン'
claude

シェルでエクスポートした環境変数は、Claude Codeの起動時に読まれます。既存のセッションでは反映されないため、エクスポートしてから起動するか、再起動します。settings.json の env に書く方法は後半で扱います。

どの接続経路で効くか

効く範囲は変数によって異なります。ここを外すと、設定したのにピッカーが変わらない状態になります。

ゲートウェイでの _SUPPORTED_CAPABILITIES の扱いは、公式が「サードパーティープロバイダーで有効」「_NAME と _DESCRIPTION はゲートウェイでも有効」と分けて書いている部分です。ゲートウェイ経由で能力を宣言したい場合は、実際に /effort などが変わるかを手元で確かめてください。

_SUPPORTED_CAPABILITIESで能力を宣言する

Claude Codeは、モデルIDを既知のパターンと照合して、effortレベルや拡張思考を有効にします。BedrockのARNやカスタムのデプロイ名はパターンに合わないことが多く、対応しているはずの機能が無効のままになります。

_SUPPORTED_CAPABILITIES には、対応する機能をカンマ区切りで並べます。使える値は6つです。

挙動のルールは2つです。変数を設定すると、列挙した能力が有効になり、列挙しなかった能力は無効になります。設定しなければ、従来どおりモデルIDに基づく組み込みの判定に戻ります。

つまり、一部だけ書くと残りは無効化されます。effort だけを書けば xhigh も max も使えません。Opusの全機能を使いたいなら、公式の例のように6つすべてを並べます。

export ANTHROPIC_DEFAULT_OPUS_MODEL=\
'arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'
export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME='Opus via Bedrock'
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES=\
'effort,xhigh_effort,max_effort,thinking,adaptive_thinking,interleaved_thinking'

上の例は、公式の設定例に沿った形です。_DESCRIPTION も加えると、行の説明文まで揃います。

宣言する値をどう決めるか

宣言はモデルの実際の対応と一致させる必要があります。公式のeffort表では、Fable 5.1とFable 5、Opus 5.5・Sonnet 5.5・Opus 5・Sonnet 5・Opus 4.8・Opus 4.7が low から max の5段階(low・medium・high・xhigh・max)、Opus 4.6とSonnet 4.6が xhigh を除く4段階です。表に載らないモデルはeffort非対応なので、Fableは非対応ではなく、Opusの新しい版と同じ5段階に入ります。

ARNの背後にいるモデルが何かを確認してから、この表に沿って xhigh_effort や max_effort を足すかを決めます。Fableをピン留めするなら、ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES に同じ5段階分の値を並べる形です。

effortの段階を宣言に入れても、既定値はモデル側で決まります。公式によると、既定は多くのモデルで high、Opus 5.5とSonnet 5.5は medium、Opus 4.7は xhigh です。宣言はどの段階を選べるかだけを決め、初期値には触れません。

拡張思考にも注意点があります。Opus 5.5・Sonnet 5.5・Fable系のモデルでは思考をオフにできません。背後のモデルがこれらに当たるなら、thinking を宣言に入れる前提で考えるのが自然です。宣言の根拠はモデル側の仕様に置きます。

ネーミングとカスタム行を組み合わせる

ANTHROPIC_CUSTOM_MODEL_OPTION は、組み込みのエイリアスを置き換えずに、ピッカーへ1行だけ足します。テスト中のモデルIDや、ゲートウェイ固有のモデルを選べるようにする用途です。IDの検証はスキップされるため、APIエンドポイントが受け付ける文字列ならそのまま使えます。

export ANTHROPIC_CUSTOM_MODEL_OPTION='my-gateway/claude-opus-5-5'
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME='Opus via Gateway'
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION='社内ゲートウェイ経由'
export ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES='effort,thinking'

3つの補助変数はいずれも任意です。名前を省くと、IDが認識できればモデル名、できなければIDが出ます。説明を省くと Custom model (<model-id>) になります。カスタム行は組み込み行の後ろに並び、modelPicker で追加した行はさらにその後ろです。

availableModels を設定している組織では、カスタムモデルのIDも許可リストに入れる必要があります。入れないと、ピッカーから行が消え、--model での指定も他の除外モデルと同様に拒否されます。

注意が必要なのは、IDにファミリー名が含まれるケースです。my-gateway/claude-opus-5-5 のようなIDは、そのファミリーの個別エントリとして数えられ、ファミリーのワイルドカードを無効にします。選べるようにしたいバージョンは、許可リストにも並べます。許可リストの構造はenforceAvailableModelsでDefaultモデルの抜け穴を塞ぐで扱っています。

隣り合う設定との使い分け

同じピッカーに関わる設定は複数あり、役割が重なりません。

modelOverrides は、ピン留め用の変数が1ファミリーに1IDしか結べないときの逃げ道です。認識されないIDでも、modelOverrides がそのIDの文字列に対応づけていれば、モデル名の表示が復活します。

キーはAnthropicのモデルID、値がプロバイダー側の文字列です。設定ファイルには次のように書きます。

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
    "claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
  }
}

日付つきのモデルIDをキーにするときは、モデル一覧にある表記どおり日付の接尾辞まで書きます。知らないキーは無視されます。/model ピッカーの各行を支えるIDがこの値に差し替わり、--model や ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_*_MODEL にAnthropicのモデルIDを直接渡したときも同じ対応表が使われます。--model と環境変数への適用は、v2.1.200より前は対象外でした。

availableModels との併用では、許可リストの判定がオーバーライド後の値ではなくAnthropicのモデルIDに対して行われます。"opus" を許可リストに入れておけば、Opusの各版をARNに対応づけたあとも一致し続けます。管理設定で availableModels を置いている場合、--model や環境変数で渡したAnthropicのモデルIDに効くのは管理設定側の modelOverrides だけで、ユーザー設定やプロジェクト設定の分は無視されます。この制限はv2.1.200以降です。

ゲートウェイのエイリアスのように、認識されないIDの診断行([claude-code:unrecognized_model])を止めたいときは、そのIDを値に持つエントリを足します。

effortをモデルごとに細かく決めたいときは、modelSettingsのeffortをモデル別に直接編集するも選択肢です。こちらは設定ファイル側の操作で、環境変数による能力宣言とは入口が異なります。

つまずきやすい点

• 直接接続では何も変わらない: api.anthropic.com へ直接つないでいる環境では、3種類の接尾辞のどれも効きません。動作確認は、Bedrock・Google Cloud Agent Platform・Foundry・ゲートウェイのいずれかで行います
• 能力を書きすぎ・書き漏らす: 宣言は上書きです。列挙しない能力は無効になるため、既存の表示が変わったときはまず宣言の抜けを疑います
• 説明の既定が読みづらい: 未設定のときは Custom Sonnet model から始まる文が出ます。チームで共有するなら、_DESCRIPTION で用途を書いておくと、ピッカーの行が読み手に伝わります
• シェルで設定した値はそのシェルにだけ効く: エクスポートした環境変数は、そのシェルから起動した claude にしか届きません。全員に同じ表示を出すには、設定ファイルの env キーを使う方法があります

settings.jsonのenvでチーム全員に配る

settings.json の env キーに書いた変数は、claude の起動方法を問わず読み込まれます。.claude/settings.json はプロジェクトの全員に効き、ソース管理にも入れられます。~/.claude/settings.json は自分の全プロジェクトに効きます。前のセクションのSonnetの例は、次のように書き直せます。

{
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "my-gateway/sonnet-prod",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "Sonnet (社内ゲートウェイ)",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION": "本番用の固定バージョン"
  }
}

シェルと設定ファイルの env の両方に同じ変数があるときは、設定ファイルの値が使われます。設定ファイル同士では、管理設定がユーザー設定やプロジェクト設定より優先されます。

シェルで設定する場合と違い、稼働中のセッションに対しても、ファイルを保存すると新しい値や変更が反映されます。値を消したときの解除は、次に claude を起動したときです。組織で固定したい表示名は、管理設定の env に置く選択肢もあります。ただしホストプラットフォームがモデルの経路を管理している環境(CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST が設定されている場合)では、管理設定の env にある ANTHROPIC_DEFAULT_*_MODEL 系の変数は無視されます。

_NAME と _DESCRIPTION が変えるのは行の見た目です。ピン留めしたIDそのものは、親の ANTHROPIC_DEFAULT_*_MODEL が決めます。

まとめ

ピン留めしたモデルの行が生のIDのまま、あるいはeffortが使えないままなら、原因はClaude CodeがそのIDを認識できていないことです。_NAME と _DESCRIPTION で表示を、_SUPPORTED_CAPABILITIES で機能を、モデルの実際の仕様に合わせて宣言します。効果があるのはサードパーティープロバイダーとゲートウェイの経路で、api.anthropic.com への直接接続は対象外です。