Claude CodeのCLAUDE_CODE_MODEL_CATALOG — モデル設定の署名付きファイルを止める手順

CLAUDE_CODE_MODEL_CATALOG=off は、Bedrock・Mantle・Vertex・Foundryで動かすClaude Codeが、モデル設定を downloads.claude.ai の署名付きファイルから読む挙動を止める環境変数です。v2.1.311のchangelogに1行だけ載っています。環境変数の一覧にも、モデル設定のページにも、この変数の記載はありません。

changelogの1行を起点に、止め方、閉域網での確かめ方、モデル固定との関係を順に書きます。閉域網や管理設定でモデル周りを固定している組織が、この変更をどう扱うかを決める材料にしてください。

v2.1.311で変わったこと

changelogの該当行は次のとおりです。

Changed Claude Code on Bedrock, Mantle, Vertex, and Foundry to load model settings from a signed file on downloads.claude.ai; set CLAUDE_CODE_MODEL_CATALOG=off to turn this off

読み取れる事実は4つです。

Mantleは、Amazon Bedrockが用意するもう1つのエンドポイントです。Invoke APIではなくAnthropic APIと同じ形式でClaudeを呼び、AWSの認証情報をそのまま使います。CLAUDE_CODE_USE_MANTLE=1 で切り替えます。

Anthropic APIに直接つなぐ構成は、この1行の対象に入っていません。同じv2.1.311では ultrathink の動作変更や、[1m] サフィックスを持たないモデル名の表示変更も入りました。全体はClaude Code v2.1.311のリリースノートにまとめています。

名前の揺れにも注意が要ります。changelogは「Vertex」と書きますが、ネットワーク設定やモデル設定のページは同じ経路を「Google Cloud's Agent Platform」と呼びます。社内の手順書を探すときは、どちらの名前でも検索してください。

公式ページに書かれていないこと

変数名は、環境変数の一覧、モデル設定のページ、ネットワーク設定のページのいずれにも載っていません。次の項目は、changelogの1行にも周辺ページにも書かれていません。

前提: v2.1.311以上か確かめる

この変数が載ったのはv2.1.311です。それより前のバージョンでは、変数を設定しても何も起きません。先にバージョンを確かめます。

claude --version

v2.1.311未満なら、この記事の変数を入れる前に更新が先です。

止め方: settings.jsonのenvに書く

環境変数の公式手順では、settings.json の env キーに書けば、claude の起動方法によらず読まれます。この変数も同じ書き方で止められます。

{
  "env": {
    "CLAUDE_CODE_MODEL_CATALOG": "off"
  }
}

置き場所で効く範囲が変わります。

• ~/.claude/settings.json: 自分の全プロジェクト
• .claude/settings.json: リポジトリを共有する全員
• 管理設定: 組織の全員

組織で一括して止めるなら管理設定の env に入れます。

複数の場所に書いたときの優先順位

設定ファイル同士の env は、設定の優先順位に従います。高い順に、管理設定、コマンドライン、プロジェクトのローカル設定、共有のプロジェクト設定、ユーザー設定です。管理設定の env で off にした値は、自分の settings.json では上書きできません。

シェルで export した値と、settings.json の env に同じ変数があるときは、ほとんどのセッションで settings.json の値が使われます。env の各項目が、シェルから引き継いだ値を置き換えるためです。置き換えが起きない例外は、公式のsettingsリファレンスにある「How env values interact with your shell」に載っています。

一時的に試すだけなら、シェルで直接渡せます。

CLAUDE_CODE_MODEL_CATALOG=off claude

WindowsのPowerShellでは $env:CLAUDE_CODE_MODEL_CATALOG = "off" を実行してから claude を起動します。

値は off だけがchangelogに載っています。0 や false を使いたいときは、ログで通信が消えるかを確かめてからにします。

閉域網で見るべき点

ネットワーク設定のページには、downloads.claude.ai の用途が「プラグインの実行ファイル、ネイティブ版のインストーラーと自動更新、更新バージョンの確認」と列挙されています。モデル設定の取得は、この行に含まれていません。

同じページには、npm経由のインストールや自前のバイナリ配布なら、ネイティブ版のインストーラーと自動更新のための downloads.claude.ai は不要だという説明があります。ただし、その他の用途は導入方法によらず当てはまるとも書かれています。署名付きファイルの取得が「その他の用途」に入るかは、次の節の方法で確かめられます。

もう1点、Bedrock・Vertex・Foundryでは、モデルの通信と認証が api.anthropic.com ではなくプロバイダー側へ向かうと明記されています。つまり、許可リストが「導入と更新のときだけ downloads.claude.ai を開け、実行時はプロバイダーのエンドポイントだけを通す」形になっている組織では、v2.1.311以降、その前提を見直す理由が1つ増えます。

閉域網の通信先を全体像で確認したいときは、Claude Codeはオフラインで使えるかの許可リストと並べて読むと整理しやすくなります。

手元で確かめる方法

公式ページに失敗時の挙動がない以上、自社の環境で確かめるのが確実です。次の2つを比べます。

# ホスト単位で到達できるか(ファイルのパスは指さない)
curl -sI https://downloads.claude.ai/claude-code-releases/stable | head -1

1. プロキシやファイアウォールのログで、起動時に downloads.claude.ai への通信が出るかを見る
2. CLAUDE_CODE_MODEL_CATALOG=off を付けて起動し、同じ通信が消えるかを見る

通信が消えれば、その通信がこの機能由来だと切り分けられます。逆に、遮断したまま起動してモデル選択に違いが出ないかも、同じログと /model の一覧で見比べられます。

切り分けフロー

起動後にモデル周りで違和感が出たときの順番です。

モデル固定の運用との関係

third-partyプロバイダーでは、モデルバージョンを固定してから展開するのが公式の案内です。固定しない場合、opus や sonnet のエイリアスは組み込みの既定モデルIDに解決され、その既定値が最新リリースに遅れたり、アカウントで有効化されていなかったりします。

固定は ANTHROPIC_DEFAULT_OPUS_MODEL のようなバージョン指定の環境変数で行います。BedrockとVertexでは、起動時の確認がアカウントで使えないモデルを検出し、通知を出して前のバージョンへ落とします。Foundryにはこの起動時の確認がなく、使えないモデルはエラーとして表に出ます。

固定済みの環境で署名付きファイルが何を変えるかは、前節の手順で off の有無を比べ、/model の一覧に違いが出るかで確かめられます。固定の手順そのものはBedrockのIAMとクロスリージョン推論プロファイルの記事と、modelPickerで /modelの一覧を構成する記事が詳しいです。

起動時のモデル確認と混同しない

Bedrockで起動直後に出る「ピンの更新を促す表示」や「フォールバックの通知」は、署名付きファイルの話ではありません。これは公式のAmazon Bedrockページにある起動時のモデル確認で、アカウントでモデルを呼べるかを調べる仕組みです。

この確認は、拒否されたモデルを手元に最大1日記憶します。記憶を止めるのは CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1 で、今回の変数とは別物です。通知が出たからといって CLAUDE_CODE_MODEL_CATALOG を疑う理由にはなりません。

変数を入れる前の判断材料

止める側と止めない側の材料を並べます。どちらが正解という話ではなく、構成によって比重が変わります。

まとめ

CLAUDE_CODE_MODEL_CATALOG=off は、v2.1.311で追加された、モデル設定の署名付きファイル取得を止める変数です。changelogが示すのは、対象の4経路、取得元のホスト、止める値の off までです。失敗時の挙動と中身は、手元のログで確かめます。

閉域網では、downloads.claude.ai の許可を「インストーラー用」とだけ見ていた設定が、実行時の通信にも関わる可能性があります。まず通信ログで有無を確かめ、そのうえで止めるか許可するかを決めると、後から理由を説明しやすくなります。