Claude Media
ANTHROPIC_BASE_URLでAPIエンドポイントを切り替える
Claude CodeTips

ANTHROPIC_BASE_URLでAPIエンドポイントを切り替える

Claude CodeのANTHROPIC_BASE_URLはAPIの接続先を変える環境変数です。設定方法と優先順位、ゲートウェイ経由で自動的に変わる挙動、モデル情報の合わせ込み方をまとめます。

読了目安 約9分

ANTHROPIC_BASE_URLは、Claude CodeのAPIリクエスト先をapi.anthropic.comから別のホストへ切り替える環境変数です。LiteLLMやKongのようなAnthropic互換のLLMゲートウェイ、社内プロキシを間に挟む構成で使います。設定自体は1行ですが、ゲートウェイへ向けた瞬間にMCPツール検索やRemote Controlなど複数の機能が既定値から変わります。設定方法と優先順位、自動で変わる挙動、モデル情報の合わせ込み方までをまとめます。90種を超えるClaude Codeの環境変数を用途別に見渡したい場合はClaude Code環境変数リファレンスを参照してください。

ANTHROPIC_BASE_URLが変えるもの

ANTHROPIC_BASE_URLを設定すると、Claude Codeはモデルへのリクエスト全体をこのURL宛てに送ります。同じAPI形式でレスポンスを返せるゲートウェイやプロキシを挟む構成が主な用途です。

認証情報とは別レイヤーです。ログインで管理する.credentials.jsonはこの変数の対象外で、ANTHROPIC_BASE_URLが動かすのは接続先だけです。認証方式を変えたいときはANTHROPIC_AUTH_TOKENかANTHROPIC_API_KEYを使います。この2つの違いはANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYの違いで扱っています。

設定のしかたと優先順位

シェルの環境変数として渡すか、設定ファイルのenvキーに書きます。

export ANTHROPIC_BASE_URL="https://gateway.example.com"
claude

チームや端末をまたいで揃えたいときは、~/.claude/settings.json(自分専用・全プロジェクト)や.claude/settings.json(プロジェクト共有)のenvキーに書きます。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com"
  }
}

同じ変数をシェルと設定ファイルの両方に書いた場合、設定ファイル側が勝ちます。Claude Codeは起動時と設定ファイル変更時にenvブロックの値をプロセス環境へ書き込み、シェルから引き継いだ値を上書きするからです。複数の設定ファイルが同じ変数を持つときは、管理者が配布するmanaged設定がユーザー設定・プロジェクト設定より優先されます。

ANTHROPIC_MODELのように、環境変数と同じ役割を持つ設定ファイル専用キー(model)がある変数もあります。その場合は環境変数側が優先され、設定ファイルのキーは環境変数が未設定のときだけ使われます。ANTHROPIC_BASE_URLにはこれに相当する専用キーがありません。設定ファイルでこの変数を書く手段はenvブロックだけです。

ゲートウェイに向けると自動で変わる挙動

api.anthropic.com以外のホストを指定すると、Claude Codeはいくつかの機能を既定値から切り替えます。プロキシ側がすべてのAPI機能をそのまま中継できるとは限らないためです。

挙動既定の変化戻す・強制する変数
MCPツール検索既定の変化無効化される戻す・強制する変数プロキシがtool_referenceブロックを転送できるならENABLE_TOOL_SEARCH=true
Remote Control既定の変化v2.1.196以降、無効化される戻す・強制する変数変数側では戻せない
ツール呼び出しの逐次ストリーミング既定の変化無効(Microsoft Foundry・ゲートウェイ接続と同じ扱い)戻す・強制する変数CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1で強制有効化
通信断の検知しきい値(バイト単位のwatchdog)既定の変化有効のまま、300秒に伸びる戻す・強制する変数直接APIは180秒、ゲートウェイ経由は300秒
W3Cトレースコンテキストの伝播既定の変化既定で無効戻す・強制する変数CLAUDE_CODE_PROPAGATE_TRACEPARENT=1で有効化

MCPツール検索が既定で切れるのは、ToolSearchが使うtool_referenceという特殊なブロック形式を、すべてのプロキシが転送できるとは限らないためです。転送できると確認済みのゲートウェイならENABLE_TOOL_SEARCH=trueで戻せます。未対応のプロキシで有効化すると、リクエストそのものが失敗します。

Remote Controlは、ANTHROPIC_BASE_URLがapi.anthropic.com以外を指す構成そのものがブロック対象です。原因の切り分けと解除手順はRemote Controlが使えない「requires the Anthropic API」の意味で詳しく扱っています。

一方、ゲートウェイ経由でも直接api.anthropic.comを呼び続ける処理が2つあります。

fast modeのチェック自体は設定したHTTPプロキシには従うため、ブロックされている場合はプロキシ側でapi.anthropic.comを許可するのが対処です。ゲートウェイが発行した認証情報をAnthropicが拒否している場合はこの許可では直らず、fast modeは接続エラーとして報告します。

ツール呼び出しの逐次ストリーミングが無効だと、長いファイル書き込みのような大きなツール入力は、Claudeが生成し終えてから初めて画面に届きます。生成中は何も表示されないため、セッションが固まっているように見えます。ゲートウェイ経由でこの現象が気になる場合はCLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1で強制的に有効化できますが、プロキシ側がストリーミング応答に対応している必要があります。

バイト単位のwatchdogは、SSEのkeep-aliveも含めて配線上に何もバイトが届かない状態を検知する仕組みです。ゲートウェイ経由でもこの監視自体は有効なままで、しきい値だけ直接APIより長い300秒になります。v2.1.222より前は、keep-alive pingが届いていてもパース済みのイベントだけを数えていたため、ゲートウェイ経由の接続で本来なら健全な通信を誤ってタイムアウト扱いにすることがありました。現在のバージョンではこの誤検知は解消されています。

モデル一覧とコンテキスト長を合わせ込む

ゲートウェイ経由の構成では、Claude Codeがモデルの実体を直接把握できません。2つの変数がそこを補います。

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERYを1にすると、/modelピッカーの候補をゲートウェイの/v1/modelsエンドポイントから取得します。既定で無効なのは、共有のAPIキーを使うゲートウェイだと、鍵がアクセスできる全モデルが全ユーザーに見えてしまうからです。有効化しても、実際に選べるモデルはavailableModelsの許可リストでさらに絞り込まれます。この許可リストはMDMか管理設定ファイルで配る必要があります。ゲートウェイ構成ではサーバー管理設定による配布に対応していないためです。

CLAUDE_CODE_MAX_CONTEXT_TOKENSは、Claude Codeがそのモデルに想定するコンテキストウィンドウのサイズを上書きします。ゲートウェイ越しのモデルIDが指すコンテキスト長が、Claude Codeの認識するサイズと食い違うときに使う変数です。適用のされ方はモデルIDの解決結果によって変わります。claude-で始まらない独自エイリアスならこの変数がそのまま効き、claude-を含みClaudeモデルに解決されるIDではDISABLE_COMPACTも併用しないと効きません。設定前に、想定と実際のどちらのIDでリクエストが届いているかを確認しておくと迷いません。

/modelピッカーから選べるモデルを絞り込みたい場合は、managed設定にavailableModelsの許可リストを配布します。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "availableModels": ["claude-opus-5", "claude-sonnet-5"]
}

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERYでゲートウェイの全モデルが候補に上がっても、availableModelsに無いモデルは選択肢に出ません。共有キーのゲートウェイでモデル発見だけ有効化し、選べる範囲は許可リストで絞る、という2段構成が既定の安全側です。

ホスト側のプラットフォームがClaude Codeを組み込んで提供元の経路を自分で管理している場合は事情が変わります。そうしたホストがCLAUDE_CODE_PROVIDER_MANAGED_BY_HOSTを設定していると、Claude CodeはANTHROPIC_BASE_URLを含む接続先・認証系の変数を設定ファイル内で無視します。ユーザー側の設定でホストの経路を上書きできないようにするための仕組みで、こうした組み込み環境でANTHROPIC_BASE_URLを設定しても効かないのは既定の挙動です。

「別のAPI」ではなく「同じAPIの入り口」を変える設計

ANTHROPIC_BASE_URLが触るのは接続先だけです。認証はANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEY、モデル選択はANTHROPIC_MODEL系、コンテキスト管理はCLAUDE_CODE_MAX_CONTEXT_TOKENSと、役割ごとに変数が分かれています。1つの変数に機能を詰め込んでいないのは、ゲートウェイ運用では特定の機能だけを個別に確認しながら戻したい場面が多いからです。MCPツール検索やRemote Controlを既定で止めるのも、同じ発想の延長線上にあります。ゲートウェイ側の対応状況をひとつずつ確かめてから、対応済みのものだけ明示的に戻す運用のほうが壊れにくくなります。

よくある質問

ANTHROPIC_BASE_URLとANTHROPIC_VERTEX_BASE_URLは何が違いますか

ANTHROPIC_VERTEX_BASE_URLとANTHROPIC_BEDROCK_BASE_URLは、それぞれGoogle Cloud's Agent PlatformとAmazon Bedrock向けの専用変数です。ANTHROPIC_BASE_URLはそれ以外の、Anthropic互換APIを話す汎用ゲートウェイ・プロキシ向けに使います。

設定してもClaude Codeが接続先を使ってくれません

値が実際に届いているかを、同じシェルでecho $ANTHROPIC_BASE_URLを実行して確認します。設定ファイルのenvブロックに書いた場合、機能によっては起動時にしか読まれないため、保存後は新しいセッションを開始してから確認します。

プロキシ経由にしたらMCPサーバーが使えなくなりました

MCPツール検索が既定で無効化されているためです。プロキシがtool_referenceブロックを転送できるかを先に確認し、対応しているならENABLE_TOOL_SEARCH=trueを試します。未対応のプロキシで設定するとリクエストが失敗するので、確認が先です。

unsetすればすぐに直接APIへ戻りますか

unset ANTHROPIC_BASE_URLのあとにclaudeを再起動すれば直接APIへ戻ります。設定ファイルのenvブロックに書いている場合は、そちらも削除しないと次回起動時に再び適用されます。

値を空文字にするのとunsetするのは同じですか

設定ファイルのenvブロックでは変数を削除できないため、シェルから引き継いだ値を打ち消したいときは空文字を設定します。Claude Codeはプロバイダー選択において空文字を未設定として扱いますが、子プロセスには空文字のまま渡ります。

トレースを取りたいのですが何を設定すればいいですか

分散トレーシングでゲートウェイをまたいだリクエストを追跡したい場合はCLAUDE_CODE_PROPAGATE_TRACEPARENT=1を設定します。モデルリクエストとHTTP MCPリクエストのtraceparentヘッダー、Bash・PowerShell・hookのサブプロセスに渡すTRACEPARENT環境変数の両方に、W3Cのトレースコンテキストが伝播するようになります。既定では直接Anthropic APIに接続している場合だけ有効です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →