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

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

Claude Codeで「OAuth token does not meet scope requirement」と出たときの意味と対処。/loginだけで直る理由と、直らないときの切り分けをまとめます。

読了目安 約10分

Claude Codeで「OAuth token does not meet scope requirement」と出たら、保存済みのトークンが、新しい機能の必要とする権限範囲(スコープ)より前に発行されたものです。対処は/loginを一度実行するだけで、先に/logoutでログアウトする必要はありません。

エラー文の読み方

実際の表示は次のとおりです。

OAuth token does not meet scope requirement: user:profile

スコープ(scope)とは、OAuthのトークンが実行できる操作を細かく区切った権限の単位です。末尾のuser:profileが、そのときの機能が要求したスコープ名にあたります。

公式のエラー一覧では、同じエラーが2通りの形で載っています。一覧表の行はdoes not meet scope requirement user:profileで、コロンも先頭のOAuth tokenもありません。詳細の節には、上の全文が載っています。ログやチャットから過去の発生を探すなら、両方に含まれるscope requirementで検索すると取りこぼしません(v2.1.287時点の公式ページの表記です)。

なぜ有効なトークンでスコープが足りなくなるのか

公式の説明は一文です。保存済みのトークンが、新しい機能の必要とするスコープより前のものだ、というものです。/loginは、その時点のスコープを持つ新しいトークンを取り直す操作にあたります。

つまり、トークンを取った時点のスコープが固定され、後からClaude Codeに追加された機能が別のスコープを要求すると、その機能を呼んだ瞬間に不足が表面化します。ログインが切れたわけではないので、普段の作業では気づかず、特定の機能だけが失敗する形で現れます。

どの機能がどのスコープを要求するかは、エラーのページに一覧がありません。手がかりは、メッセージ末尾のスコープ名だけです。エラーのページが示す対処は/loginです。

/usageやステータスラインが動かないとき、原因はスコープとは限らない

使用量まわりの表示が出ないときに、まずスコープ不足を疑いたくなります。しかし、表示されない理由はほかにも公式に書かれています。分かれ目は、画面にscope requirementの文言が出ているかどうかです。

/usageの利用状況バーが読み込めないとき、とくに使用量の取得先がレート制限されているときは、直近60分以内に読み込んだ最後のバーをShowing last-known usageの注記つきで出します。rキーで再取得できます。60分以内のスナップショットがなければ、取得先がレート制限されていると表示します。この場合は/loginで解決しません。

なお、スキル・サブエージェント・プラグイン・MCPサーバー別の内訳は、手元のセッション履歴から計算される値です。別の端末やclaude.aiの使用量は含まれません。内訳が少なく見えても、スコープとは無関係です。詳しい読み方は/usageコマンドの解説にあります。

ステータスラインのrate_limitsフィールドも同様です。表示対象はclaude.aiのProとMaxの契約者(またはClaude appsゲートウェイで支出上限が設定された環境)に限られます。セッション最初のAPI応答の後に現れ、5時間と7日の枠はそれぞれ単独で欠けることがあります。つまり、API課金の環境で何も出ないのは正常な状態です。

似た認証エラーとの見分け方

認証のエラーは文面が似ていても、トークンの状態が別です。

くらべる

3つの認証エラーの違い

権限が足りない

scope requirement

保存済みのトークンが、機能の必要とするスコープより前のものです。対処は/loginで、ログアウトは不要です。

APIが拒否した

OAuth token revoked / expired

APIが返した拒否で、全端末でのサインアウトや管理者による権限の取り消し、更新の失敗が原因です。詳しくはOAuth tokenが失効したときの記事にあります。/loginで入り直します。

Claude Codeが自分で止めた

Login expired

保存済みログインの更新が拒否され、Claude Codeが資格情報を消した状態です。モデルへのリクエストはAPIに届く前に止まります。/statusのLogin行にExpired — log in againと出ます。

Anthropicのプロファイル経由で認証しているときは、別のAnthropic profile login expiredが出ます。このときは/loginで直る条件が限られるので、プロファイルのログイン失効の記事で条件を確かめてください。

claude.aiコネクタの呼び出しでclaude.ai rejected the session tokenと出る場合も、直すのはClaude Codeのログインです。拒否されているのはコネクタ自体の認可でなく、Claude Codeのログインのトークンなので、コネクタを認可し直しても解決しません。/loginで入り直してから、/mcpでコネクタを再接続します。順序が逆だと同じ状態のままです。詳しくはsession token rejectedの記事にあります。

MCPサーバーの権限不足は、さらに紛らわしい例です。次の文面はスコープに関係しますが、対処が違います。

MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate

サーバーがHTTP 403のinsufficient_scopeを返したときの表示で、直すのは/loginでなく/mcpです。/mcpでそのサーバーを選び、メニューから認証し直します。サーバー設定でoauth.scopesを固定している場合は、足りないスコープをその一覧に足してから認証し直します。

/loginで解決する

Claude Code本体の/loginを実行します。再度ブラウザーの認証フローを通ると、現在のスコープを持つ新しいトークンが保存されます。

/login

claude.aiアカウント・Consoleアカウント・APIキーのどれで入るかは、契約と課金の形で決まります。違いはログイン方法3種の使い分けにあります。

/loginしても同じ表示が出るとき

環境変数にトークンを入れている環境では、/loginで保存し直しても効果が見えないことがあります。次の順に見ます。

手順

`/login`後も直らないときの確認順

  1. 1

    使われている認証を`/status`で見る

    Auth tokenの行にCLAUDE_CODE_OAUTH_TOKENと出ていれば、環境変数の値が使われています。API keyの行があり、使用外の印が付いていなければ、承認済みのANTHROPIC_API_KEYが優先されており、/loginでは置き換わりません。

  2. 2

    環境変数のトークンを取り除く

    変数が設定されたまま/loginすると、いまのセッションは新しいログインに切り替わります。ただし新しいセッションでは、変数が再び読み込まれます。シェルのプロファイル(~/.zshrcなど)や、設定ファイルのenvブロックから行を外します。

  3. 3

    新しいセッションで確かめる

    行を外したシェルからclaudeを起動し直し、/loginで入った状態で/statusを見ます。Auth tokenの行が消えて、ログインの行が見えれば、保存したトークンが使われています。

/loginで得るサブスクリプションのOAuth認証は、複数の認証が同居するときの優先順で最後の7番目です。CLAUDE_CODE_OAUTH_TOKENは5番目で、その上にはクラウドプロバイダーの認証、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY、apiKeyHelperがあります。環境に上位の認証が有効なまま残っていれば、/loginで保存したトークンは使われません。

APIキーが無効な場合は、スコープ不足とは別にAPI Error: 401 Invalid authentication credentialsが出ます。このときも先に/statusで、どの認証が有効かを確かめます。

CIとスクリプトではclaude setup-token

ブラウザーでの/loginができないCIでは、claude setup-tokenで長期のトークンを発行します。有効期間は1年で、ProかMax、TeamかEnterpriseの契約が必要です。v2.1.287で--helpを見ると、次のように出ます。

claude setup-token --help
Usage: claude setup-token [options]
 
Set up a long-lived authentication token (requires Claude subscription)
 
Options:
  -h, --help  Display help for command

発行したトークンは、端末に表示されるだけで、どこにも保存されません。表示された値を、使いたい環境のCLAUDE_CODE_OAUTH_TOKENに設定します。

このトークンはモデルへのリクエストだけを行えます。Remote Controlのセッションは作れず、claude.aiコネクタも取得できません。ローカルに設定したMCPサーバーは、そのまま動きます。

--bareを付けたスクリプトはCLAUDE_CODE_OAUTH_TOKENを読みません。ベアモードではANTHROPIC_API_KEYかapiKeyHelperで認証します。

古いトークンが期限切れになったCIの扱いも、公式が書いています。環境変数でトークンを渡している場合、401が出ても、Claude Codeは設定した値を送り続けます。保存済みログインのトークンに切り替わりません(v2.1.225より前は、保存済みログインの短命なアクセストークンに途中で置き換わり、それが切れると再び401になっていました)。対処は、claude setup-tokenで作り直して再起動するか、変数をunsetして/loginすることです。

エラーのページがスコープ不足の対処として挙げるのは、/loginだけです。claude setup-tokenが効くかどうかは、そのページには書かれていません。/loginが使えない環境では、失効や取り消しの対処として案内されている再発行を試し、それでも同じ文言が出るかを見ることになります。

手元の認証状態を見るコマンド

セッションの外から、現在のログイン方法を確かめるコマンドもあります。

claude auth status --text

v2.1.287では、次の3行が出力されます(メールアドレスは置き換えています)。

Login method: Claude Max account
Organization: you@example.com's Organization
Email: you@example.com

出力にはスコープの行がありません。このコマンドで分かるのは、どのアカウントの種別でログインしているかまでです。トークンがどのスコープを持っているかは、ここからは読み取れません。--textを付けない場合の既定の出力はJSONです。

セッションの中では/statusが、Auth tokenやLoginの行で認証の出どころを示します。スクリプトから呼ぶならclaude auth status、対話中に見るなら/statusという使い分けになります。

ログインし直しそのものを、シェルから始めるコマンドはclaude auth loginです。--consoleでAPI課金のConsoleアカウント、--ssoでSSO、--email <email>でメールアドレスの入力済みの状態にできます。--claudeaiが既定で、Claudeのサブスクリプションで入ります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →