Claude Code は Anthropic が提供するコマンドラインのコーディングツールで、既定では Anthropic の公式インターフェースに接続します。国内のチームが実際に使う場合、アクセスの安定性、請求の統一、割当量管理のために、自前または第三者のゲートウェイへ向けることがよくあります。いわゆる「カスタム API への接続」は、本質的には 3 つだけを変える作業です。リクエストの送り先（Base URL）、認証方法（Key）、呼び出すモデル（モデル名）です。

本記事では、インストール、環境変数、設定ファイル、モデル選択、接続確認、チームへの展開、セキュリティの順に、再利用できる接続手順を説明します。コマンドは主に macOS と Linux を想定し、Windows については個別に注記します。

注記：Claude、Anthropic は各権利者の商標です。本記事は技術的な接続説明のみを目的としており、関連ベンダーとの提携関係はありません。Claude Code は更新が速く、環境変数、設定項目、メニュー名がバージョンによって変わる可能性があります。claude --help、公式ドキュメント、サイト内の接続説明を基準にしてください。

一、接続前に確認する 3 つのこと

Claude Code は Anthropic Messages プロトコルを使用し、OpenAI の Chat Completions プロトコルではありません。そのため、カスタム API は少なくとも 2 点を満たす必要があります。Anthropic 互換の /v1/messages 入口を提供していること。モデル名がゲートウェイで実際に提供されている名称と一致していることです。OpenAI 互換入口しか持たないゲートウェイは、Anthropic 互換ルートを併設していない限り、そのまま Claude Code に設定できません。

開始前に 3 つを用意します。

  • Base URL：ゲートウェイのルートアドレスです。例として https://ai.zhongshangqihang.com があります。/v1 を付けるかはゲートウェイの実装によります。サイト内の接続説明に従ってください。
  • API Key：コンソールで作成し、割当上限と有効期限を設定します。長期間無制限の Key をテストに使わないでください。
  • モデル名：コンソールまたは料金ページからコピーします。記憶で手書きしないでください。大文字小文字やハイフンが 1 文字違うだけでも「モデルが存在しない」エラーになります。

まだアカウントがない場合は、登録入口から始め、まず低い割当のテスト用 Key を作成してください。

二、Claude Code をインストールする

Claude Code は通常 npm で配布され、他のインストール方法も提供されています。以下は最も一般的な流れです。

  1. Node.js がインストールされていることを確認します。保守中の LTS バージョンを推奨します。最低バージョンは公式ドキュメントを基準にしてください。
  2. npm install -g @anthropic-ai/claude-code を実行してグローバルにインストールします。
  3. claude --version を実行し、コマンドが使えることを確認してバージョン番号を記録します。
  4. テスト用プロジェクトのディレクトリに移動して claude を実行し、案内に従ってテーマ、ディレクトリの信頼などの初回設定を完了します。
  5. チームにバージョン管理の要件がある場合は、バージョンを固定して導入ドキュメントに記載します。アップグレード前にテストプロジェクトで検証してください。
node --version
npm install -g @anthropic-ai/claude-code
claude --version
cd /path/to/your-project
claude

カスタム API を使う場合、通常は Anthropic アカウントへのログインは不要ですが、ログインを省略できるかはバージョンと設定方法によります。起動後にログインを求められる場合は、まず環境変数が Claude Code を起動した同じシェルで有効になっているか確認してください。

三、環境変数：BASE_URL と AUTH_TOKEN

Claude Code は主に次の認証変数を読み取ります。

  • ANTHROPIC_BASE_URL：リクエストのルートアドレス。
  • ANTHROPIC_AUTH_TOKEN：Authorization: Bearer 形式で送信され、ゲートウェイ接続でよく使われます。
  • ANTHROPIC_API_KEY：x-api-key 形式で送信され、Anthropic のネイティブな認証方式に近いものです。

どちらか一方を選べば十分です。ゲートウェイが Bearer 認証なら ANTHROPIC_AUTH_TOKEN、ネイティブ方式なら ANTHROPIC_API_KEY を使います。両方を同時に設定すると、バージョンによって優先順位が異なり、「正しく設定したはずなのに 401 になる」ことが起きます。1 つだけ残すことを推奨します。

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-あなたのキー"
claude

~/.zshrc や ~/.bashrc に書くと設定が恒久的に有効になります。変更後は source ~/.zshrc を実行してください。Windows PowerShell では $env:ANTHROPIC_BASE_URL="..." を使いますが、現在のウィンドウにしか効きません。永続化する場合はシステムの環境変数画面か setx を使い、変更後にターミナルを開き直してください。

export をプロジェクトのスクリプトに書いてコミットしないでください。キーが Git の履歴に入ると、ファイルを削除しても記録は消えません。

四、settings.json：設定をファイルに固定する

環境変数は一時的な切り替えに向いています。長期的に使う場合は Claude Code の settings ファイルに書くことを推奨します。一般的な場所は 3 層あります。

  • ユーザーレベル：~/.claude/settings.json。本機のすべてのプロジェクトに適用されます。
  • プロジェクトレベル：.claude/settings.json。リポジトリにコミットでき、機密でない設定のチーム共有に向いています。
  • ローカルプロジェクトレベル：.claude/settings.local.json。コミットせず、個人の上書きに適しています。

例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.zhongshangqihang.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-あなたのキー"
  },
  "model": "claude-sonnet-4-5"
}

注意：settings.json 内の Key は平文です。個人の PC では許容できますが、共有マシン、CI、コードリポジトリでは行わないでください。プロジェクトレベルのファイルには Base URL とモデル名だけを置き、Key は環境変数やシークレット管理ツールに任せます。設定の優先順位は概ね、企業管理設定、コマンドライン引数、ローカルプロジェクト、プロジェクト、ユーザーの順に上書きされます。詳細は現在のバージョンのドキュメントを基準にしてください。

五、モデル選択：タスク別に階層を分ける

Claude モデルは通常 3 つの階層に分かれ、適したタスクが異なります。

階層 典型的な用途 トレードオフ
Opus 複雑なリファクタリング、ファイル横断分析、長い Agent 処理 能力は高いがコストも高く、速度が遅い場合がある
Sonnet 日常的なコーディング、バグ修正、コードレビュー 能力とコストのバランスが良く、既定の階層に適する
Haiku 単純な補完、整形、小規模なバッチ処理 高速で低コストだが、複雑なタスクには力不足になりやすい

Claude Code では ANTHROPIC_MODEL でメインモデルを指定できます。また ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL で各階層のマッピングを個別に上書きできます。対応する変数はバージョンによって異なるため、設定前に claude --help または公式ドキュメントを確認してください。

モデル名はゲートウェイのモデル一覧と一致している必要があります。ゲートウェイは上流モデルに独自の命名を使うことがあり、公式ドキュメントの名前をそのまま書いても一致するとは限りません。利用可能なモデルと課金方式はモデル価格を参照してください。価格はモデルのバージョンや上流の方針によって調整されます。

六、接続確認：まず curl、次に Claude Code

まず Claude Code を経由せず、curl でゲートウェイ自体が通るか確認します。

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "OK とだけ返してください"}]
  }'

ゲートウェイが Bearer 認証を使う場合は、x-api-key を Authorization: Bearer $ANTHROPIC_AUTH_TOKEN に置き換えます。200 が返り内容が正常なら、Base URL、Key、モデルの 3 項目のうち少なくとも 1 組は利用可能です。

次に Claude Code に戻り、順番に確認します。

  1. claude --version でクライアントが実行可能か確認します。
  2. プロジェクトディレクトリで claude doctor を実行します（現在のバージョンがこのコマンドを提供している場合）。インストールと設定を確認できます。
  3. claude を起動し、/status で現在のモデルとアカウント情報を確認します。
  4. リスクの低いタスクを入力します。例えば「このディレクトリの構造を説明してください。ファイルは変更しないでください」です。
  5. 正常に返るか、401、404、モデル不存在などのエラーが出ないかを確認します。

よくある現象と対処：

現象 優先して確認する項目 対処
401 Key、変数名、リクエストヘッダー Key をコピーし直す。認証変数を 1 つだけ残す
404 Base URL の /v1 が多すぎる、または足りない ゲートウェイのドキュメントに従い、ルートアドレスか互換入口に変更する
model not found モデル名がゲートウェイの一覧と不一致 コンソールまたは料金ページからコピーする
リクエストタイムアウト ネットワーク、DNS、プロキシ 別のネットワークで試す。プロキシがヘッダーを書き換えていないか確認する
429 同時実行数または割当制限 同時実行数を下げる。Key の上限を確認する

七、チームへの展開：1 人 1 Key、入口を統一

チームで使う場合、1 つの Key を共用することは推奨しません。より安全な方法は次のとおりです。

  • 1 人 1 Key とし、名前に氏名や用途を含め、退職時にそのまま無効化する。
  • プロジェクトや環境ごとに割当上限を設定し、本番とテストを分ける。
  • 統一ゲートウェイで使用量、モデル分布、異常な呼び出しを集中的に確認する。
  • 企業管理設定で Base URL と許可するモデルを配布し、メンバーの手作業による設定ミスを減らす。
  • 接続手順を導入ドキュメントにまとめ、検証コマンドとよくあるエラーを含める。
  • 毎週または毎月、使用量をレビューし、異常な Key を速やかに処理する。

会社に調達やコンプライアンスのプロセスがある場合は、データの流れを先に確認してください。コードの断片はゲートウェイとその上流のモデルサービスへ送信されます。保存の有無、保存期間、学習への利用の有無は利用規約を確認し、自己判断で仮定しないでください。

八、セキュリティの境界：Key、コード、データ

最後にいくつかの原則です。

  • Key を Git、コンテナイメージ、フロントエンドコード、スクリーンショット、チャット履歴に入れない。
  • プロジェクトに .gitignore を追加し、少なくとも .env、.env.*、.claude/settings.local.json を含める。
  • 漏洩を疑ったら、まず古い Key を失効させ、その後に使用量を調査する。パスワード変更だけでは不十分です。
  • Key に有効期限を設定し、人員の変更時にローテーションする。
  • 共有マシンではシークレット管理ツールや apiKeyHelper を使い、settings.json に平文を書かない。
  • Claude Code は信頼できる配布元からのみインストールし、アップグレード前に変更履歴を確認する。

よくある質問

Claude Code は必ず Anthropic アカウントにログインする必要がありますか？

必ずしもそうではありません。有効な Base URL と認証変数を設定すれば、クライアントはカスタム API を直接利用できます。ただし初回起動時のテーマ、ディレクトリ信頼などの案内は表示される場合があります。ログインが必要かはバージョンと設定によります。問題が起きたら、まず環境変数が起動シェルで有効か確認してください。

ANTHROPIC_API_KEY と ANTHROPIC_AUTH_TOKEN の違いは何ですか？

前者は通常 x-api-key リクエストヘッダーで送信され、後者は Authorization: Bearer で送信されます。どちらを選ぶかはゲートウェイの認証方式によります。リクエストヘッダーの衝突を避けるため、1 つだけ設定することを推奨します。

Base URL にはルートアドレスを書きますか、それとも /v1 を付けますか？

Claude Code では通常ルートアドレスを書き、クライアントが /v1/messages を結合します。一部のゲートウェイは互換入口を直接書くよう求めます。判断は簡単です。curl でルートアドレスに /v1/messages を付けてリクエストし、通ればルートアドレスを使います。通らなければゲートウェイのドキュメントに従って調整してください。

curl は通るのに Claude Code でエラーになるのはなぜですか？

よくある原因は、シェル変数が GUI や IDE 内蔵ターミナルに渡っていないこと、または 2 つの認証変数を同時に設定して衝突していることです。まず Claude Code を起動する同じターミナルで echo $ANTHROPIC_BASE_URL を実行して確認してください。

チームで 1 つの Key を共用できますか？

技術的には可能ですが、推奨しません。Key を共用するとメンバーごとの使用量を区別できず、漏洩時に責任者を特定しにくくなります。1 人 1 Key に割当と有効期限を組み合わせる方が、管理コストは低くなります。

次のステップ

利用可能なゲートウェイアカウントがない場合は、登録入口から始め、まず低い割当のテスト用 Key を作成し、本記事の curl と Claude Code の 2 段階で検証してください。モデルと課金はモデル価格を参照してください。価格は調整されるため、ページのリアルタイム情報を基準にしてください。

関連記事：