Claude CodeをLiteLLM経由で使う設定と2つの認証方式

Claude CodeをLLMゲートウェイであるLiteLLMのプロキシ経由で動かすには、プロキシ側のconfig.yamlと、Claude Code側の環境変数の2か所を合わせます。つなぎ方は2通りあります。LiteLLMの仮想キーをそのままAPIキーとして使う方式と、Claudeサブスクリプション（Maxなど）のOAuthトークンをLiteLLMの裏のAnthropicまで素通しする方式です。どちらを選ぶかで、課金先とヘッダーの置き場所が変わります。

LiteLLMはClaude Code側からは「Anthropic形式のゲートウェイ」に見えるだけで、特別な連携機能はありません。汎用の接続手順はLLMゲートウェイへの接続方法にあります。この記事はLiteLLMに固有の部分、つまりconfig.yamlの書き方、仮想キー、OAuth転送の設定に絞ります。

2つの方式は何が違うのか

くらべる

LiteLLM経由の2方式

API課金

仮想キー方式

Claude CodeのANTHROPIC_AUTH_TOKENにLiteLLMのキーを入れます。LiteLLMが保持するAnthropic（またはBedrockなど）のキーで課金され、サブスクの利用枠は使いません。

Maxサブスク

OAuth転送方式

Claude Codeにはサブスクでログインしたままにします。LiteLLMのキーはANTHROPIC_CUSTOM_HEADERSで別ヘッダーに載せ、OAuthトークンはLiteLLMが上流へ転送します。

分かれ目は、Claude Codeが認証情報をどこに載せるかです。ゲートウェイ用の認証情報の変数（ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY）かapiKeyHelperが有効な間、リクエストにはその認証情報が載り、保存済みのclaude.aiログインは送られません。この通信はトークン単位で、ゲートウェイが転送する認証情報の持ち主に課金されます。

一方、ANTHROPIC_BASE_URLだけを設定して認証情報の変数を置かない場合は、リクエストはゲートウェイを通っても、有効な認証情報はclaude.aiのログインのままです。サブスクの利用上限と課金がそのまま適用されます。LiteLLMのMaxサブスク向け手順が、LiteLLMのキーをAuthorizationではなく専用ヘッダーに載せているのは、この仕様に合わせた形です。

仮想キー方式の設定手順

LiteLLMのconfig.yamlを書く

まずプロキシ側です。LiteLLMの手順ではuv tool install 'litellm[proxy]'で入れます。model_listにClaude Codeから呼ばせたいモデルを並べ、master_keyを環境変数から読ませます。

model_list:
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
 
  - model_name: claude-opus-5
    litellm_params:
      model: anthropic/claude-opus-5
      api_key: os.environ/ANTHROPIC_API_KEY
 
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

model_nameがClaude Code側から見えるモデル名で、litellm_params.modelが上流に渡る実際のモデルです。モデル名の組み合わせは、LiteLLMのドキュメントに載っている例に沿った形です。手元で使うモデルIDは、自分のLiteLLMのバージョンが対応しているものに置き換えてください。

環境変数を用意してプロキシを起動します。待ち受けは既定で4000番ポートです。

export ANTHROPIC_API_KEY="（上流のAnthropicキー）"
export LITELLM_MASTER_KEY="sk-（十分に長いランダム文字列）"
litellm --config /path/to/config.yaml
# RUNNING on http://0.0.0.0:4000

Claude Codeにつなぐ前に、curlで確かめる

Claude Codeを開く前に、/v1/messagesへ直接リクエストを送ります。失敗したときに、原因がプロキシ側かClaude Code側かを分けられます。

curl -X POST http://0.0.0.0:4000/v1/messages \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 100,
       "messages": [{"role": "user", "content": "ping"}]}'

{"id":"msg_で始まるJSONが返れば、URLと認証情報は通っています。モデル名が見つからないというエラーでも、認証は通過している証拠です。

環境変数を設定する

Claude Code側は、ベースURLと認証情報の2つを渡します。LiteLLMのキーはANTHROPIC_AUTH_TOKENに入れ、Authorization: Bearerで送らせます。

export ANTHROPIC_BASE_URL="http://0.0.0.0:4000"
export ANTHROPIC_AUTH_TOKEN="$LITELLM_KEY"
claude

$LITELLM_KEYにはマスターキーか仮想キーを入れます。マスターキーはプロキシのすべてのモデルを呼べるので、個人や端末ごとには配らず、モデルを絞った仮想キーを発行するのが運用上の基本です。仮想キーの作成は後述の予算設定の節で扱います。

シェルのexportは、そのターミナルから起動したプロセスにしか届きません。常に同じ設定で動かしたいときは、~/.claude/settings.jsonのenvブロックに書きます。プロジェクトの.claude/settings.jsonは共有されるので、認証情報は書かないでください。

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://0.0.0.0:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-（LiteLLMの仮想キー）"
  }
}

シェルのexportと設定ファイルのenvが同じ変数を指すと、設定ファイルの値が使われます。起動後に/statusを開き、Anthropic base URLの行にプロキシのアドレスが出ているか、Auth tokenの行があるかを確認します。この行が出ていなければ、変数がセッションに届いていません。

エンドポイントはどちらを選ぶか

LiteLLMには、統合エンドポイント（http://0.0.0.0:4000）と、Anthropicのパススルーエンドポイント（http://0.0.0.0:4000/anthropic）があります。LiteLLMのクイックスタートは統合エンドポイントを推奨しています。複数プロバイダーのモデルをmodel_nameで切り替えたいなら、統合エンドポイントを選びます。

キーが定期的に変わる環境では

JWTなど、一定時間で失効する認証情報を使うなら、静的なANTHROPIC_AUTH_TOKENの代わりにapiKeyHelperを使います。認証情報を標準出力に書くだけのスクリプトを作り、settings.jsonに指定します。

{
  "apiKeyHelper": "~/bin/get-litellm-key.sh"
}

スクリプトの出力は既定で5分間キャッシュされます。間隔を変えるにはCLAUDE_CODE_API_KEY_HELPER_TTL_MSにミリ秒を入れます。出力はAuthorizationとx-api-keyの両方のヘッダーで送られます。ANTHROPIC_AUTH_TOKENやANTHROPIC_API_KEYが設定されていれば、そちらが優先されます。スクリプトが認証情報以外のバナーやログを出力すると、v2.1.227以降では失敗扱いになります。

モデルの指定と1Mコンテキスト

LiteLLMのmodel_nameに付けた名前を、そのままClaude Codeのモデル指定に使います。

claude --model claude-opus-5
# セッション中は /model claude-opus-5

既定のモデルを環境変数で固定する場合は、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODELにmodel_nameを入れます。

1Mトークンのコンテキストを使うときの注意が1つあります。Claude Codeはモデル名の[1m]サフィックスを取り除いてからLiteLLMに送り、代わりにanthropic-betaヘッダーでコンテキスト拡張を要求します。LiteLLMのconfig.yamlのモデル名には[1m]を含めません。シェルから渡すときは、角括弧がシェルに解釈されないよう--model 'claude-opus-5[1m]'のように引用符で囲みます。

プロキシが用意するモデル一覧を/modelピッカーに出したい場合は、CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1を設定します。仕組みはモデルディスカバリの解説にあります。

MaxサブスクのOAuthをLiteLLM経由で通す設定

サブスクの利用枠を使いつつ、LiteLLMで利用状況の記録・予算・レート制限をかけたい場合の構成です。LiteLLMのチュートリアルでは、前提がClaude Codeのインストール、Claude Maxの契約、動作中のLiteLLMの3つになっています。

プロキシ側はforward_client_headers_to_llm_apiが要

general_settingsにforward_client_headers_to_llm_api: trueを入れます。これがクライアントのAuthorizationヘッダー、つまりOAuthトークンを上流のAnthropic APIへ転送する設定です。

model_list:
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
 
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  forward_client_headers_to_llm_api: true

転送するモデルを絞りたいときは、litellm_settings.model_group_settings.forward_client_headers_to_llm_apiにモデル名を列挙する書き方もあります。

litellm_settings:
  model_group_settings:
    forward_client_headers_to_llm_api:
      - claude-sonnet-5

クライアント側はキーを別ヘッダーに載せる

LiteLLMの仮想キーをANTHROPIC_CUSTOM_HEADERSでx-litellm-api-keyとして送ります。AuthorizationにはClaude Code自身のOAuthトークンが載ったままになります。

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_MODEL="claude-sonnet-5"
export ANTHROPIC_CUSTOM_HEADERS="x-litellm-api-key: Bearer sk-（LiteLLMの仮想キー）"
claude

初回の起動で、ログイン方法の選択肢から「Claude account with subscription」を選びます。ブラウザーで承認すると、以降のリクエストはLiteLLMを通り、LiteLLMのダッシュボードのLogsに記録されます。

ヘッダーの役割は次のとおりです。

ヘッダー	役割	処理する側
`x-litellm-api-key`	役割LiteLLMの認証、予算、レート制限	処理する側LiteLLM
`Authorization: Bearer {OAuthトークン}`	役割Claudeサブスクの認証	処理する側Anthropic API

ゲートウェイがOAuthの通信を上流のAnthropicに渡すなら、anthropic-betaヘッダーも変更せずに転送する必要があります。この値にはOAuth用の機能指定が含まれ、取り除くと401になります。LiteLLMで転送が足りない場合も、まずこの2つのヘッダーを疑います。

サブスクをLiteLLMのような中継に通してよいかは、契約しているプランの利用条件で決まります。ここで扱った設定は、技術的にどう通すかの手順です。組織で導入するなら、利用条件を先に確認してください。

予算を付けた仮想キーを配る

LiteLLMで開発者ごとの上限を管理するには、データベースを有効にして、/key/generateでキーを発行します。general_settingsにdatabase_urlを足します。

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  forward_client_headers_to_llm_api: true
  database_url: "postgresql://..."

curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key_alias": "developer-1", "max_budget": 100.00,
       "budget_duration": "monthly"}'

このキーを開発者に渡し、ANTHROPIC_AUTH_TOKEN（仮想キー方式）かx-litellm-api-keyヘッダー（OAuth転送方式）に入れてもらいます。端末の管理設定でベースURLと認証情報をまとめて配る方法は、ロールアウト手順に整理されています。

BedrockやAzureをLiteLLMの裏に置く場合

LiteLLMのmodel_listに、Bedrock、Azure Foundry、Vertex AIのモデルも並べられます。Claude Code側の接続は変えず、--modelでmodel_nameを切り替えるだけです。ただしBedrockの上流では、Claude Codeが付ける実験的なbetaヘッダーを受け付けず、400になることがあります。LiteLLMの手順は次の2点を挙げています。

モデル指定をbedrock/invoke/<モデルID>の形にする
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1を設定し、betaヘッダーを止める

後者は~/.claude/settings.jsonのenvに書きます。

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

LiteLLMのこの案内は暫定の回避策と位置づけられていて、LiteLLM側の対応が進めば不要になる見込みです。互換性はClaude Code・LiteLLMの双方の更新で変わるため、LiteLLMのClaude Code互換性マトリクスで機能ごとの対応状況を先に見ておきます。Claude Code側のドキュメントも、context_managementやExtra inputs are not permittedといった400は、このフラグで多くが止まるとしています。

なお、Claude Codeのドキュメントは、どのゲートウェイを使っても、Claude以外のモデルへClaude Codeを向けることはサポートしないと明記しています。LiteLLMが他社モデルを扱えることと、その構成がサポート対象かどうかは別の話です。

つながらないときの切り分け

LiteLLM側とClaude Code側のドキュメントで挙がっている症状を、原因の側ごとにまとめます。

症状	原因	対処
LiteLLMから401	原因`ANTHROPIC_AUTH_TOKEN`の値がLiteLLMのキーと違う、または`ANTHROPIC_CUSTOM_HEADERS`のキーが間違い	対処`curl http://localhost:4000/key/info`にキーを渡して有効性を確認
上流のAnthropicから認証エラー（OAuth転送方式）	原因`forward_client_headers_to_llm_api: true`が未設定	対処`general_settings`に追加
モデルが見つからない	原因`--model`か`ANTHROPIC_MODEL`が`model_name`と一致していない	対処`curl http://localhost:4000/v1/models`で一覧を確認
起動してもログイン画面が出る	原因プロジェクトの`.claude/settings.json`の`env`は、初回セットアップと信頼確認の後にしか効かない	対処シェルのexportか`~/.claude/settings.json`に認証情報を置く
400で`context_management`などのフィールド名が出る	原因上流がClaude Codeの送るフィールドを受け付けない	対処`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`
MCPツールが全部コンテキストに展開される	原因ベースURLが非ファーストパーティだとMCPツール検索が既定で無効	対処プロキシが`tool_reference`ブロックを転送するなら`ENABLE_TOOL_SEARCH=true`
証明書エラー	原因curlは通るがClaude Codeが同じ認証局を信頼していない	対処`NODE_EXTRA_CA_CERTS`にCAバンドルのパスを指定

プロキシが生きているかを見るだけなら、LiteLLMの手順どおりcurl http://0.0.0.0:4000/healthが早道です。

MCPツール検索の行は、/contextで全ツールのスキーマが展開されて見えるのが目印です。ベースURLを変えた直後にコンテキストの消費量が跳ね上がったときは、まずここを疑います。

設定が効かない面とモデルの制約

ゲートウェイ越しだと使えなくなる機能もあります。Remote Controlは、ANTHROPIC_BASE_URLがapi.anthropic.com以外を指していると無効になります。認証情報の変数やapiKeyHelperが有効な間は、音声入力も使えません。fast modeがゲートウェイ越しに使えない理由と回避策は、fast modeの記事にまとめています。

Claude Desktopは別の仕組みです。デスクトップアプリはANTHROPIC_BASE_URLやsettings.jsonではなく、サードパーティ推論の設定を読みます。管理者が配布した設定があればそれが優先され、無いときはHelp → Troubleshooting → Enable Developer Modeでアプリを再起動し、Developer → Configure Third-Party InferenceにゲートウェイのベースURLを入れます。LiteLLM側のconfig.yamlは同じでも、クライアントの設定の入口はCLIと別になる点に注意してください。配布の手順はdesktopブロックの記事が詳しいものの、あちらはAnthropic提供のゲートウェイが対象で、LiteLLMで同じ配布ができるとは限りません。

まとめ

LiteLLMへの接続は、課金先で2方式に割れます。API課金でよければ、仮想キーをANTHROPIC_AUTH_TOKENに入れる構成が単純です。サブスクの枠を使いたいなら、forward_client_headers_to_llm_api: trueとカスタムヘッダーの組み合わせになります。

どちらでも、curlで/v1/messagesを先に叩き、Claude Codeの/statusでベースURLと認証情報の行を確認する順序を守ると、切り分けが速くなります。モデル名のずれ、betaヘッダーの扱い、ベースURL変更で止まる機能は、いずれもベースURLを切り替える設定の記事で挙動の全体像を確認できます。

Claude CodeをLiteLLM経由で使う設定と2つの認証方式

2つの方式は何が違うのか

仮想キー方式の設定手順

LiteLLMのconfig.yamlを書く

Claude Codeにつなぐ前に、curlで確かめる

環境変数を設定する

エンドポイントはどちらを選ぶか

キーが定期的に変わる環境では

モデルの指定と1Mコンテキスト

MaxサブスクのOAuthをLiteLLM経由で通す設定

プロキシ側はforward_client_headers_to_llm_apiが要

クライアント側はキーを別ヘッダーに載せる

予算を付けた仮想キーを配る

BedrockやAzureをLiteLLMの裏に置く場合

つながらないときの切り分け

設定が効かない面とモデルの制約

まとめ

Claude Codeとは — できること・料金・始め方と使い方の全体像

Dynatrace MCPをClaudeにつなぐ手順 — ローカル版は終了、移行先で障害調査

ClaudeとEraserを連携してシステム構成図を生成・更新する

e-Gov法令APIとClaude Codeで法改正の施行日と条文差分を毎週追う

EDINET APIで有価証券報告書を同業他社と比較 — Claude Codeで回す手順

e-Gov法令APIでClaudeに条文を正確に引用させる手順

2つの方式は何が違うのか

仮想キー方式の設定手順

LiteLLMのconfig.yamlを書く

Claude Codeにつなぐ前に、curlで確かめる

環境変数を設定する

エンドポイントはどちらを選ぶか

キーが定期的に変わる環境では

モデルの指定と1Mコンテキスト

MaxサブスクのOAuthをLiteLLM経由で通す設定

プロキシ側はforward_client_headers_to_llm_apiが要

クライアント側はキーを別ヘッダーに載せる

予算を付けた仮想キーを配る

BedrockやAzureをLiteLLMの裏に置く場合

つながらないときの切り分け

設定が効かない面とモデルの制約

まとめ

関連する記事

Claude Codeとは — できること・料金・始め方と使い方の全体像

Dynatrace MCPをClaudeにつなぐ手順 — ローカル版は終了、移行先で障害調査

ClaudeとEraserを連携してシステム構成図を生成・更新する

e-Gov法令APIとClaude Codeで法改正の施行日と条文差分を毎週追う

EDINET APIで有価証券報告書を同業他社と比較 — Claude Codeで回す手順

e-Gov法令APIでClaudeに条文を正確に引用させる手順