Claude Code のカスタムベース URL で 401:Invalid API key と AUTH_TOKEN を順に確認
2026年11月20日時点で、Claude Code の接続先をカスタム API アドレスに向けたあとに 401 が出る原因は四つに絞られます。キーとエンドポイントが別サービス、ANTHROPIC_API_KEY と ANTHROPIC_AUTH_TOKEN の取り違え、設定ファイルの env ブロックに古い値が残っている、アドレスに余分な /v1 が付いている、のいずれかです。まず /status を実行して Anthropic base URL と Auth token の行を読み、それらに一致する認証情報の変数を一つだけ残してください。
更新日 2026-11-20
1 つのキーで Claude、GPT、主要な中国系モデルを利用でき、トークン単位の課金で、数分で使い始められます。
- トークン単位の課金・最新単価は /models
- カード(Visa / Mastercard)・Apple Pay・Google Pay・暗号資産で支払い可能
- チャージ後すぐにセルフサービスで開通
まず覚える四つの値
拒否されたのは認証情報で、ネットワークではない
Anthropic の API エラーリファレンスは 401 を authentication_error と定義しています。キー自体に問題がある(形式が不正、失効、期限切れ)という意味です。アドレスがゲートウェイを指す場合、401 のあとの文言は Anthropic ではなくそのゲートウェイが書いたものです。
ANTHROPIC_API_KEY はこのヘッダーで送られる
認証リファレンスによると、Anthropic API へ直接アクセスする場合は X-Api-Key ヘッダーとして送信されます。サブスクリプションのログインも併用している場合、承認済みの API キーがログインより優先されます。ログイン中なのに認証情報で失敗するのはこのためです。
ANTHROPIC_AUTH_TOKEN はこのヘッダーで送られる
値には Bearer が前置され、Authorization ヘッダーとして送信されます。bearer トークンで認証するゲートウェイやプロキシ向けです。公式の助言は、どちらを使うべきか指示がない場合はまずこちらを使うというものです。
実際に有効なアドレスと認証情報を確認
ゲートウェイガイドでは、ゲートウェイのアドレスを設定したときだけ Anthropic base URL の行が表示されます。Auth token または API key の行があればゲートウェイの認証情報が有効、Login method の行があればログインが有効です。
カスタムアドレスでの 401 の正体
カスタム API アドレスでの 401 は、ネットワークの問題であることはほとんどありません。リクエストに付けた認証情報が相手側で受け入れられていないのです。公式のエラーページでは、Invalid API key は ANTHROPIC_API_KEY 変数、または apiKeyHelper スクリプトが返したキーを API が拒否した場合、あるいは Claude Code が送信前にそのキーを止めた場合だと説明されています。
もう一つの API Error: 401 Invalid authentication credentials はより具体的で、API は認証情報の形式を認識したものの、その背後のアカウントまたは組織を拒否したという意味です。したがって期限切れトークンが原因ではありません。三つ目のケースもあります。アドレスがゲートウェイを指す場合、401 のあとの文言はゲートウェイ自身のエラーであり、/login では変えられません。ゲートウェイが別の認証情報を求めているからです。三つとも最初の手順は同じです。/status を実行し、どのアドレスとどの認証情報が有効かを見ます。
2026年11月20日時点で、この 401 に関係する二つの変更
1. ゲートウェイ側にもう一つ 401 の発生源があります。公式のエラーページによると、ゲートウェイが想定する認証情報をすでに持っているのにすべてのリクエストが 401 で失敗する場合は、そのゲートウェイが tool search のフィールドを受け付けるか確認してください。v2.1.304 より前は、ENABLE_TOOL_SEARCH で有効にしない限り、ゲートウェイの背後では tool search はオフでした。
2. apiKeyHelper の失敗の見え方が変わりました。スクリプトがキーを返さないと、リクエストはプレースホルダーの認証情報を付けて API に届き、401 で拒否されます。v2.1.208 より前は、Claude Code が再試行の予算をすべてそのプレースホルダー認証情報での再送に使い、最後にスクリプトの失敗ではなく一般的な 401 authentication error を報告していました。
v2.1.208 以降は、スクリプトがエラー、タイムアウト、または何も出力しない場合、三回の試行以内に Your apiKeyHelper script is failing と表示されます。
三つの日付:どの変数をどこに置くか、設定ファイルでの書き方、ゲートウェイ側の 401
コミュニティのトラブルシューティングでよく見られる経験則では、カスタムエンドポイントには ANTHROPIC_AUTH_TOKEN、api.anthropic.com への直接接続には ANTHROPIC_API_KEY を使います。この分担では、ゲートウェイのアドレスに Anthropic のキーを組み合わせる、あるいは直接接続のアドレスにゲートウェイのキーを組み合わせると、リクエストヘッダーが一致せず、相手側は 401 しか返せません。
コミュニティのトラブルシューティングでよく見られる経験則では、アドレスとゲートウェイのキーはターミナルで export するだけでなく、~/.claude/settings.json の env ブロックに書きます。繰り返し出てくる二つのルールは、アドレスはホストまでを埋めて /v1 を付けないこと、同じ変数が二か所にある場合は設定ファイルが優先されることです。
ゲートウェイがすでに正しい認証情報を持っているのに、すべてのリクエストが 401 を返す場合は、ゲートウェイが tool search のフィールドを受け付けるか確認してください。v2.1.304 より前は、この機能はゲートウェイの背後ではオフで、ENABLE_TOOL_SEARCH で有効にする必要がありました。同じドキュメントは、/status の Anthropic base URL の行がゲートウェイのアドレスを設定したときだけ表示されることも記しています。
公式ドキュメントで確認できること vs コミュニティの主張と未公開の詳細
Claude Code のエラー、認証、環境変数、ゲートウェイ、設定の各ドキュメントと Anthropic の API エラーリファレンスで確認済み
1. 二つのメッセージ:Invalid API key · Fix external API key は、ANTHROPIC_API_KEY または apiKeyHelper スクリプトが API に拒否されたキーを渡した、あるいは Claude Code が送信前にそれを止めたという意味です。API Error: 401 Invalid authentication credentials は、形式は認識されたもののアカウントまたは組織が拒否されたという意味で、期限切れトークンが原因ではありません。
2. ヘッダー:AUTH_TOKEN の値は Bearer を前置して Authorization として送信され、API_KEY は X-Api-Key として送信されます。3. 優先順位:AUTH_TOKEN は API_KEY より上位で、ログインはその両方より下位です。対話モードでは API キーに一度承認が必要で、-p モードでは存在すれば常に使われます。
4. ゲートウェイのケース:アドレスがゲートウェイを指す場合、401 のあとの文言はゲートウェイのメッセージで、/login では変わりません。認証情報は、ゲートウェイが求めるものに応じて AUTH_TOKEN、API_KEY、apiKeyHelper のいずれかに置きます。5. 設定ファイル:env ブロックは Claude Code が動作するすべての場所に適用され、ユーザーレベルの ~/.claude/settings.json はすべてのプロジェクト、プロジェクト内の .claude/settings.local.json は一つのプロジェクトを対象にします。
プロジェクトの .claude/settings.json はコミットされるため、認証情報を置いてはいけません。6. 関連するコード:403 は権限不足、429 はレートまたは支出の上限、529 は API の過負荷で、いずれも認証情報の問題ではありません。
コミュニティの主張と公式ドキュメントが述べていないこと
1. アドレスの末尾に /v1 を付けるほうが安全: コミュニティの議論では、アドレスの末尾に /v1 を付けないよう述べられています。なぜなら /v1/messages は自動で追加されるためです。公式の検証リクエストは $ANTHROPIC_BASE_URL/v1/messages と記載されており、/v1 が変数に含まれないことが分かります。
QCode では値は https://api.qcode.cc/api で、末尾に /v1 を余分に付けても /v1/v1/messages という重複した形になります。2. ターミナルでの export は常に有効: 公式ドキュメントは、direnv、dotenv 系のシェルプラグイン、IDE のターミナルがプロジェクトの .env ファイルから古いキーを読み込む可能性があると警告しています。
コミュニティの投稿では、同じ変数を両方で設定した場合は設定ファイルが優先されると報告されています。そのため、シェルを編集する前に /status を確認してください。3. 新しく /login すると API キーが置き換わる: そうはなりません。ドキュメントには、承認済みの API キーがログインより優先され、/login では置き換わらないと記載されています。unset するか、キーをローテーションしてください。
二つの経路:API_KEY で Anthropic へ直接 vs AUTH_TOKEN でゲートウェイ経由
ANTHROPIC_API_KEY:Anthropic API へ直接アクセスするための Console キー
X-Api-Key ヘッダーとして送信され、発行元は Claude Console です。対話モードでは初回に承認を求められ、その選択は記憶されます。-p モードでは存在すれば使われます。サブスクリプションのログインより優先されるため、プランが有効なのに 401 が返り続けることがあります。Console でキーをローテーションするか、unset してサブスクリプションに戻してください。
ANTHROPIC_AUTH_TOKEN:ゲートウェイが求める bearer 認証情報
値には Bearer が付与され、Authorization として送信されます。bearer token で認証するゲートウェイ向けです。QCode の場合、アドレスは https://api.qcode.cc/api で /v1 は付きません。認証情報は cr_ で始まる key です。ANTHROPIC_API_KEY は unset にして、2 つの認証情報が併存しないようにします。公式の推奨: ゲートウェイがどちらの種類を求めるか明示していない場合は、AUTH_TOKEN から始め、検証リクエストで確認します。
六つの手順: エラー原文の行から再起動と検証まで
1. エラー行をそのまま読み、三つのどれかに分類します。Invalid API key · Fix external API key は key が拒否された、または送信前にブロックされたことを意味します。API Error: 401 Invalid authentication credentials は形式は正しく、アカウントまたは組織が拒否されたことを意味します。
アドレスがゲートウェイを指している場合、401 の後のテキストはゲートウェイのものなので、/login を実行するのではなく、ゲートウェイが求める認証情報に変更します。2. /status を実行し、Anthropic base URL の行があるか、どのアドレスを示しているかを確認し、次に Auth token または API key の行を読んで、どちらの認証情報が有効かを確認します。
3. ~/.claude/settings.json を開き、env ブロックに古い ANTHROPIC_BASE_URL や古い key が残っていないか調べます。同じ変数が設定ファイルにも書かれている場合、ターミナルで編集した値が反映されないことがあります。認証情報をプロジェクトの .claude/settings.json に置かないでください。
コミット対象になります。4. 認証情報の変数は一つだけにします。ゲートウェイなら ANTHROPIC_AUTH_TOKEN を設定して unset ANTHROPIC_API_KEY を実行し、Anthropic への直接アクセスなら逆にして ANTHROPIC_API_KEY を残し AUTH_TOKEN を消します。
5. アドレスを確認します。QCode の Claude Code 用アドレスは https://api.qcode.cc/api で /v1 は付きません。Codex は https://api.qcode.cc/openai を使うので、両者を混在させないでください。6. claude を再起動し、curl で最小のリクエストを一つ送ります。
POST $ANTHROPIC_BASE_URL/v1/messages に Authorization: Bearer $ANTHROPIC_AUTH_TOKEN と anthropic-version: 2023-06-01 を付けます。401 が返ればもう一方の変数に切り替えて再試行し、JSON ボディが返ればアドレスと認証情報の両方が正しいということです。
QCode 側: 一つのアドレス、一つの変数
QCode は独立した API アクセスサービスで、Anthropic、OpenAI などのベンダーとは提携関係にありません。Claude モデルは Anthropic Messages エンドポイントのみを通ります。ANTHROPIC_BASE_URL には https://api.qcode.cc/api を /v1 なしで設定し、ANTHROPIC_AUTH_TOKEN には cr_ で始まる key を設定し、ANTHROPIC_API_KEY は unset にして 2 つの認証情報が併存しないようにします。
両方の行を ~/.claude/settings.json の env ブロックに書き、claude を再起動してから /status で Anthropic base URL と Auth token の行を確認します。Codex は別のアドレス https://api.qcode.cc/openai を使うので、Claude Code と混在させないでください。
課金はトークン単位で、各モデルの現在の料金は /models にあります。月額プランの準備がまだですか。クォータパックは $4 から、7 日以内に使う一度限りのクォータを購入できます。個人プランをすでにご利用の場合は、クォータが足りないときにブースターパックを追加してください。
よくある質問
ターミナルで ANTHROPIC_AUTH_TOKEN を export したのに、Claude Code が依然として 401 を返すのはなぜですか。
まず /status を実行し、Auth token または API key の行がどの認証情報を示しているか、Anthropic base URL の行がどのアドレスを示しているかを読みます。これが公式に、有効な認証情報の出所を確認する方法です。よくある原因は三つです。一つ目は設定ファイルに古い値が残っていることです。~/.claude/settings.json の env ブロックに書かれた値は Claude Code が動作するすべての場所に適用され、ターミナルの新しい値で必ずしも上書きされません。二つ目は別の場所から読み込まれた key です。ドキュメントは、direnv、dotenv 系のシェルプラグイン、IDE のターミナルが、明示的に設定していない key をプロジェクトの .env ファイルから読み込む可能性があると警告しています。同じシェルで env | grep ANTHROPIC を実行して確認してください。三つ目はエンドポイントと異なるサービスの key です。カスタムエンドポイントに Anthropic の key を組み合わせる、あるいは直接アドレスにゲートウェイの key を組み合わせるケースです。
ANTHROPIC_AUTH_TOKEN と ANTHROPIC_API_KEY の違いは何ですか。
ヘッダーと用途の違いです。AUTH_TOKEN の値には Bearer が付与され、Authorization として送信され、bearer token で認証するゲートウェイやプロキシで使われます。ANTHROPIC_API_KEY は X-Api-Key として送信され、Anthropic API への直接アクセスで Claude Console の key に使うものです。公式の優先順位リストでは AUTH_TOKEN が API_KEY より先なので、両方ある場合は AUTH_TOKEN が使われます。ゲートウェイの背後ではこれを残してもう一方を unset し、直接アクセスでは逆にします。ゲートウェイがどちらを求めるかわからない場合、ドキュメントは AUTH_TOKEN から始め、検証リクエストで確認することを推奨しています。
ANTHROPIC_BASE_URL に /v1 を含めるべきですか。
いいえ。/v1 をアドレスの末尾に追加しないでください。/v1/messages は Claude Code 自身が追加します。公式の検証リクエストは $ANTHROPIC_BASE_URL/v1/messages と記載されており、/v1 が値に含まれないことが分かります。末尾に余分なセグメントを付けると /v1/v1/messages になり、ゲートウェイはそのパスをルーティングできず、応答は認証情報の問題のように見えることがよくあります。QCode では値は https://api.qcode.cc/api で、/api はアドレス自体の一部であり、重複した /v1 ではありません。同じルールがすべてのクライアントに当てはまるわけではありません。OpenAI 互換の SDK と Codex は /openai または /openai/v1 を含むアドレスを使用します。
401 と 403 の違いは何ですか。
401 は認証情報そのものに関するものです。API リファレンスはこれを authentication_error と定義しており、key が不正な形式、失効、または期限切れであることを意味します。403 は permission_error で、key は有効だが要求したリソースへの権限がないことを意味するため、Console の組織およびワークスペースのアクセス設定を確認してください。例外を一つ覚えておく価値があります。401 のテキストが CORS requests are not allowed for this Organization で始まる場合、key は問題ではありません。リクエストがブラウザからの Origin ヘッダーを伴っていたためで、代わりに自前のバックエンドから送る必要があります。key を変更しても何も変わりません。
429 と 529 は key の問題ですか。
いいえ。どちらの番号も認証情報に関するものではなく、新しい key でも解決しません。429 は rate_limit_error です。組織がレート制限、利用層の月間支出上限、または Claude Code ワークスペースの支出上限に達した状態です。この種の 429 はアクセスが回復するまで失敗し続けることがあり、retry-after ヘッダーなしで届くこともあります。529 は overloaded_error です。API が一時的に過負荷の状態で、ドキュメントでは全ユーザーのトラフィックが多いときに起こり得るとされています。公式 SDK はこうした一時的な失敗を自動的に再試行し、既定では 2 回、retry-after を尊重します。
apiKeyHelper が失敗する、またはリクエストが 401 を返し続ける場合はどうすればよいですか。
まずスクリプトを単独で実行し、有効な key を stdout に出力することを確認してください。これが公式の最初の切り分け手順です。スクリプトが key を返さない場合、リクエストはプレースホルダーの認証情報で API に届き、401 で拒否されます。v2.1.208 より前は、Claude Code が再試行の予算をすべてそのプレースホルダー認証情報での再送に費やし、最後にスクリプトの失敗ではなく一般的な 401 authentication error を報告しました。v2.1.208 以降は、エラー、タイムアウト、または何も出力しないスクリプトは 3 回の試行以内に Your apiKeyHelper script is failing として表面化します。key の返却に 10 秒を超える場合、経過時間を含む警告がプロンプトバーに表示されます。スクリプトが正常なのに 401 が続く場合は、/status でその出力が有効な認証情報かどうかを確認してください。AUTH_TOKEN と API_KEY は apiKeyHelper より優先され、変数が残っているとスクリプトの key は使われません。Claude Desktop とクラウドセッションは apiKeyHelper を呼び出さず、これらの環境変数も読みません。
出典
Claude Code エラーリファレンス code.claude.com/docs/en/errors(2026-11-20 に確認)、認証と優先順位 code.claude.com/docs/en/authentication(2026-11-20 に確認)、環境変数 code.claude.com/docs/en/env-vars(2026-11-20 に確認)、LLM ゲートウェイ接続 code.claude.com/docs/en/llm-gateway-connect(2026-11-20 に確認)、設定ファイル code.claude.com/docs/en/settings(2026-11-20 に確認)、Anthropic API エラー platform.claude.com/docs/en/api/errors(2026-11-20 に確認)、コミュニティの主張は公開ディスカッション投稿に由来し、本文でそのように明示されています。すべて 2026-11-20 に確認。
関連記事
クォータパック: 月額プランなし、7 日間有効
7 日間有効の一度限りのクォータを購入するか、個人プランにブースターパックを追加できます。モデルごとの料金は /models にあります。
Claude Code の ANTHROPIC_BASE_URL: カスタム API エンドポイントを設定する
ANTHROPIC_BASE_URL と ANTHROPIC_AUTH_TOKEN を環境変数または settings.json で設定し、Claude Code をカスタムエンドポイントに向けます。1M コンテキストと /autocompact についても扱います。
Claude Code サブエージェント・デフォルトモデル環境変数設定ガイド(2026-11)
2026-11-22 時点:ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_*_MODEL、および CLAUDE_CODE_SUBAGENT_MODEL の優先順位、エイリアス固定、v2.1.330 の修正、~/.claude/settings.json ゲートウェイテンプレートを解説します。
暗号資産チャージガイド
9 通貨・56 ネットワーク、手数料 0 で AI コーディング API クレジットを購入。
Anthropic の Claude Code ドキュメントと API エラーリファレンスは 2026-11-20 に確認し、code.claude.com と platform.claude.com が正式な情報源です。QCode.cc は独立した API アクセスサービスであり、Anthropic や OpenAI との提携関係も承認もなく、ベンダーがアカウントや key をどう判断するかを変更することはできません。QCode のモデル提供状況と最新料金は qcode.cc/models に従います。