「OAuth scope requirement」エラーの意味と対処 — Claude Code

Claude Codeで「OAuth token does not meet scope requirement」と出たら、ログイン自体は有効なままです。保存済みトークンが古く、新しい機能が必要とする権限範囲(スコープ)を持っていないだけで、認証が壊れているわけではありません。他のOAuthエラーと違い、ログアウトは不要で/loginを一度実行すれば直ります。

エラーメッセージの読み方

実際の表示は次のような形です。

OAuth token does not meet scope requirement: user:profile

スコープ(scope)とは、OAuth認証においてトークンが実行できる操作の範囲を細かく区切る仕組みです。user:profileの部分はスコープ名で、そのリクエストが要求する権限範囲を示します。メッセージの意味は「トークンは有効だが、このリクエストが必要とする権限が足りない」ということです。ログインが失効した状態(Login expired)や、APIがトークンそのものを拒否した状態(OAuth token revoked)とは根本的に別の状態で、認証は通っているのに認可(何ができるか)が足りていないケースにあたります。

なぜ有効なトークンでスコープ不足が起きるのか

/loginでサインインした時点のトークンには、その時点でClaude Codeが要求していたスコープの集合が埋め込まれます。その後のアップデートで新しい機能が追加され、その機能が新しいスコープを必要とするようになっても、すでに発行済みのトークンは自動では更新されません。古いトークンを使い続けている限り、新しいスコープを要求する機能を呼び出した瞬間にこのエラーが出ます。

このため、Claude Code本体を最新版に更新した直後や、しばらく/loginをやり直していないアカウントで起きやすい傾向があります。トークンの有効期限が切れているわけではないので、通常の使用では気づかず、特定の機能を使ったときだけ表面化します。

スコープは「そのトークンで何ができるか」を積み増す方式の許可リストです。新しいスコープが追加されても、それは新機能が使う権限が1つ増えるだけで、既存のトークンが持つ権限が減ったり無効になったりするわけではありません。会話やツール実行そのものは、トークンが発行された時点のスコープで問題なく動き続けます。エラーが出るのは、そのスコープをまだ持っていないトークンで、新しいスコープを要求する機能(/usageやステータスラインの使用量表示)を呼び出したときに限られます。

/usageとステータスラインで出やすい理由

このエラーが最も出やすいのは/usageコマンドと、ステータスラインの使用量インジケーターです。どちらもアカウントのプラン利用状況を読み取る必要があり、user:profileのようなプロファイル関連のスコープを要求します。

/usageはPro・Max・Team・Enterpriseプランで、直近24時間または7日間のプラン上限に対する使用率を表示します。あわせてスキル・サブエージェント・プラグイン・個々のMCPサーバーへの使用量の内訳も表示され、dキーとwキーで期間を切り替えられます。これらはいずれもアカウントのプラン利用状況を読みに行く機能で、この内訳を取得するリクエストが、古いトークンのスコープでは足りずに失敗する形でエラーが表面化します。

ステータスラインをカスタマイズしている場合は、rate_limitsフィールドを使って5時間・週次のレート上限使用率を表示できます。このフィールドはClaude.aiサブスクリプション(Pro/Max)ユーザーで、セッション開始後の最初のAPI応答が返った時点から利用可能になります。API課金アカウント(Console経由)ではこのフィールド自体が存在しないため、スコープ不足以前にレート上限の表示対象外です。プラン利用状況を取得する点で/usageと同じ権限を必要とするため、同じスコープ不足エラーの対象になります。

/loginで解決する

対処は/loginの再実行だけです。ログアウトの手順は不要です。

/login

/loginを実行すると、その時点でClaude Codeが要求する全スコープを含む新しいトークンが発行され、既存の保存済みトークンと置き換わって保存されます。再度ブラウザーでの認証フローを通るだけで、既存のセッションやプロジェクト設定に影響はありません。作業中の会話を/clearする必要もなく、/loginを挟んだ直後から/usageやステータスラインの表示が正常に戻ります。ログイン方式そのものの違い(claude.aiアカウント・APIキー・OAuthトークン)を確認したい場合はClaude Codeログイン方法3種の使い分けを参照してください。

CI・長期トークンでの注意点

claude setup-tokenで発行した長期OAuthトークンをCLAUDE_CODE_OAUTH_TOKEN環境変数に設定してCI環境で使っている場合も、同じ理由でスコープ不足が起きます。ブラウザーでの対話的な/loginができない環境では、claude setup-tokenを実行できる端末で新しいトークンを発行し直し、CI側の環境変数を更新します。

claude setup-token

claude setup-tokenが発行するトークンは有効期間1年で、Claude Pro・Max・Team・Enterpriseいずれかのサブスクリプションと紐づきます。このトークンはモデルへのリクエストしか行えない設計で、Remote Controlセッションの確立やclaude.aiコネクタの取得はできません(ローカルに設定したMCPサーバーは通常どおり動作します)。この制約と、/usageやステータスラインが必要とするプロファイル関連のスコープは別の話で、claude setup-tokenで再発行すれば発行時点の最新スコープが付与されます。

古いトークンをそのまま使い続けているCIパイプラインでは、Claude Codeを更新したタイミングで初めてこのエラーが出ることがあります。CIのビルドログにscope requirementという文字列が出たら、対話的な再ログインではなくトークンの再発行が必要なサインなので、まずclaude setup-tokenの再実行を検討します。なお--bareフラグを付けたベアモードのスクリプトはCLAUDE_CODE_OAUTH_TOKEN自体を読み込まないため、この経路のスコープ不足エラーは発生しません。ベアモードではANTHROPIC_API_KEYまたはapiKeyHelperで認証します。

どのトークンが実際に使われているか分からない場合は、/statusを実行してAuth tokenの行を確認します。CLAUDE_CODE_OAUTH_TOKENと表示されていれば、この環境変数の値が使われている状態です。

/status

似た文言の別エラーと混同しない

「認証まわりのエラー」はいくつかありますが、状態がまったく違います。

3つとも表示は似ていますが、scope requirementだけは「トークンは生きているのに機能が足りない」という点で性質が異なります。ログアウトしてから入り直す必要はなく、/loginを一度実行するだけで解決します。会話やコード編集そのものが止まることはなく、影響は/usageやステータスラインの表示に限られる点も他の2つとの違いです。

見分ける際は、エラーメッセージ全文をコピーしてscope requirementという文字列が含まれているかどうかを確認するのが手早い方法です。含まれていれば対処は/login一択で、/logoutを先に挟むかどうかを迷う必要もありません。表示された文言だけで判断に迷う場合は、/statusでAuth tokenの行を見て、現在どのトークンが使われているかを合わせて確認しておくと切り分けがさらに確実になります。

よくある質問

user:profile以外のスコープでも同じエラーは出ますか

はい。user:profileはメッセージによく現れるスコープ名ですが、メッセージの末尾に表示されるスコープ名は機能によって変わります。今後Claude Codeに新しいアカウント連携機能が追加されれば、別のスコープ名でも同じ形式のエラーが出る可能性があります。対処はどのスコープ名であっても/loginの再実行で共通です。

/logoutしてから/loginする必要はありますか

不要です。トークン自体は無効になっていないため、/loginだけで現在の全スコープを含む新しいトークンに置き換わります。/logoutを挟むと保存済みの設定が一部リセットされるため、このエラーに限っては不要な手順です。

このエラーは課金や使用量のカウントに影響しますか

影響しません。スコープ不足はプラン利用状況を取得するリクエストが失敗するだけで、Claude Code本体の会話やツール実行には影響しません。/usageやステータスラインの表示が更新されないだけの状態です。

APIキーやANTHROPIC_API_KEYで認証している場合も起きますか

起きません。このエラーはOAuthトークン(/loginまたはCLAUDE_CODE_OAUTH_TOKEN)を使った認証に固有です。ANTHROPIC_API_KEYはスコープの概念を持たない別方式の認証情報のため対象外で、キー自体が無効な場合はAPI Error: 401 Invalid authentication credentialsのような別のエラーとして表示されます。両者は文言も対処もまったく異なります。

/login後もまだ/usageが動きません

/loginを実行しても/usageのプラン利用状況が読み込まれない場合、原因はスコープ不足とは別のことがあります。/usageは利用状況エンドポイントがレート制限されているときも一時的に取得へ失敗し、この場合は直近60分以内に読み込んだ最後のデータをShowing last-known usageとして表示します。rキーで再取得できます。この失敗はスコープの問題ではないため、/loginをやり直しても解決しません。しばらく待ってからrキーで再試行します。

何度も同じエラーが出る場合は何を疑いますか

/loginを実行しても直後に再発する場合は、まずCLAUDE_CODE_OAUTH_TOKEN環境変数が設定されたままになっていないか確認します。この変数が設定されていると、/loginで新しいトークンを保存しても、Claude Codeは次のセッションで環境変数の古いトークンを再び読み込みます。環境変数側もclaude setup-tokenで更新するか、unsetして/loginのトークンに一本化します。シェルの設定ファイル(~/.zshrcや~/.bashrc)に古い値をエクスポートする行が残っていないかも、あわせて確認しておくと再発を防げます。原因が特定できないまま繰り返す場合は、/statusのAuth token表示と実際に使っている認証方式が一致しているかを、上から順にひとつずつ照合していくのが確実です。