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

ANTHROPIC_BASE_URLは、Claude CodeのAPIリクエスト先をapi.anthropic.comから別のホストへ切り替える環境変数です。LiteLLMやKongのようなAnthropic互換のLLMゲートウェイ、社内プロキシを間に挟む構成で使います。設定自体は1行ですが、ゲートウェイへ向けた瞬間にMCPツール検索やRemote Controlなど複数の機能が既定値から変わります。設定方法と優先順位、自動で変わる挙動、モデル情報の合わせ込み方までをまとめます。300種を超える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ブロックの値をプロセス環境へ書き込み、シェルから引き継いだ値を上書きするからです。例外はClaude Desktopアプリやセルフホスト環境のrunnerが起動したセッションで、こちらは組み立てた起動環境が優先されます。複数の設定ファイルが同じ変数を持つときは、管理者が配布するmanaged設定がユーザー設定・プロジェクト設定より優先されます。

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

ベースURLだけでは、サブスクの認証は置き換わらない

ゲートウェイに向けても、課金と認証の経路が自動で切り替わるわけではありません。何が有効な認証情報になるかは、ベースURLとは別に決まります。

ログイン自体は端末に残り、認証情報の変数を外せば元に戻ります。ANTHROPIC_AUTH_TOKENなら設定した時点で優先され、ANTHROPIC_API_KEYは対話モードで一度だけ承認を求められます。ログインを消してゲートウェイの認証情報だけにしたい場合は/logoutを使います。

設定が効いているかを/statusで確かめる

環境変数を書いたのに反映されているか不安なときは、/statusの表示が最短の確認手段です。管理者が管理設定で配布している場合も、同じ手順で届いているかを見分けられます。

シェルでexportしただけの値は、Dockから起動したエディタには渡りません。VS Code拡張はVS Code自身のユーザー設定にあるclaudeCode.environmentVariablesへ書くのが確実な場所で、~/.claude/settings.jsonの値は起動したプロセスには届いても、拡張のログイン確認には届きません。

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

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

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

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

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

WebFetchのチェックだけを止めるなら、設定ファイルにskipWebFetchPreflight: trueを書きます。

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が届いていてもパース済みのイベントだけを数えていたため、ゲートウェイ経由の接続で本来なら健全な通信を誤ってタイムアウト扱いにすることがありました。現在のバージョンではこの誤検知は解消されています。

ゲートウェイ構成では、リクエストが丸ごと400で拒否される回帰も過去に2回ありました。

• v2.1.265以降: Artifactツールの入力スキーマにある正規表現を、Anthropic互換のエンドポイントが拒否しました。v2.1.268で修正されています
• v2.1.275: ANTHROPIC_BASE_URLでゲートウェイを指す構成のリクエストが拒否されました。Claude Code v2.1.276で修正されています

面ごとに、設定の置き場所が違う

ANTHROPIC_BASE_URLはCLIの話です。ほかの面では読まれ方が変わります。

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

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

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERYを1にすると、/modelピッカーの候補をゲートウェイの/v1/modelsエンドポイントから取得します。既定で無効なのは、共有のAPIキーを使うゲートウェイだと、鍵がアクセスできる全モデルが全ユーザーに見えてしまうからです。

CLAUDE_CODE_MAX_CONTEXT_TOKENSは、Claude Codeがそのモデルに想定するコンテキストウィンドウのサイズを上書きします。ゲートウェイ越しのモデルIDが指すコンテキスト長が、Claude Codeの認識するサイズと食い違うときに使う変数です。適用のされ方はモデルIDの解決結果によって変わります。

Claude Codeが認識できない独自のIDなら、この変数がそのまま効きます。ただしIDに[1m]を含む場合は、CLAUDE_CODE_DISABLE_1M_CONTEXT=1も設定しないと効きません。認識できるモデルに解決されるIDや、接尾辞のない素のclaude-名では、DISABLE_COMPACTも併用したときだけ効きます。設定前に、想定と実際のどちらのIDでリクエストが届いているかを確認しておくと迷いません。

v2.1.285では、ANTHROPIC_BASE_URLを設定したセッションは、1Mコンテキストを持つモデル(Opus 4.7以降、Sonnet 5以降、Fable)でその1Mを使うようになりました。ゲートウェイが200Kで止まる場合は/autocompact 200kを実行します。

共有キーのゲートウェイでは、モデル発見を有効化しつつ、availableModelsの許可リストで選べる範囲を絞る構成が使えます。許可リストはMDMか管理設定ファイルで配ります。ゲートウェイ構成ではサーバー管理設定による配布に対応していないためです。

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

この設定では、ゲートウェイの全モデルが候補に上がっても、availableModelsに無いモデルは選択肢に出ません。

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

接続先・認証・モデルは別々の変数で決まる

ANTHROPIC_BASE_URLが触るのは接続先だけです。認証はANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEY、モデル選択はANTHROPIC_MODEL系、コンテキスト管理はCLAUDE_CODE_MAX_CONTEXT_TOKENSと、役割ごとに変数が分かれています。

ゲートウェイに向けたときに止まる機能には、それぞれ別の理由があります。MCPツール検索が止まるのは、tool_referenceブロックをすべてのプロキシが転送できるとは限らないためです。Remote Controlが止まるのは、claude.aiのアカウントとAnthropic APIへの直接接続が要件だからです。前者は転送できると確認したゲートウェイならENABLE_TOOL_SEARCH=trueで戻せますが、後者は変数では戻せません。

よくある質問

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を話す汎用ゲートウェイ・プロキシ向けに使います。

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に接続している場合だけ有効です。