setup-tokenとRemote Controlが両立しない理由とトークンの外し方

claude setup-tokenで作った長期トークンをCLAUDE_CODE_OAUTH_TOKENに置いたまま、Remote Controlを使うことはできません。トークンはモデルへのリクエストしか認証できず、Remote Controlのセッションを確立できないためです。Remote Controlを使うなら、環境変数を外してclaude auth loginでログインし直します。

つまり「無人で長く動かすための長期トークン」と「外から操作するためのRemote Control」は、同じセッションで同時には成り立ちません。この記事では、止まったときの見分け方、仕様上の理由、常駐サーバーでどちらを選ぶかを順に扱います。

症状は「full-scope login token」の一行で出る

Remote Controlを起動したときに、次のエラーが出る場合が該当します。

Remote Control requires a full-scope login token

claude doctorでは、同じ状況が「Sign-in is missing the user:profile scope」と表示されたという報告があります。これは後述のGitHub issueに書かれた内容です。

エラーリファレンスの該当節は、原因を次のように説明しています。claude setup-tokenで作った長期トークン、またはCLAUDE_CODE_OAUTH_TOKEN環境変数で認証している状態で、これらはモデルへのリクエストしかできません。対処はclaude auth loginでフルスコープのセッショントークンに切り替えることです。

なぜ長期トークンではRemote Controlが成立しないのか

公式の認証ドキュメントは、claude setup-tokenのトークンを「Claude subscriptionで認証する、1年有効のOAuthトークン」と位置づけています。そのうえで、できないことを明記しています。

• Remote Controlのセッションを確立できない
• claude.aiコネクタを取得できない
• ローカルで設定したMCPサーバーは、そのまま動く

認証の優先順位も効いてきます。CLAUDE_CODE_OAUTH_TOKENは優先順位の5番目で、/loginで得たサブスクリプションの資格情報(7番目)より上です。変数がある限り、保存済みのログインよりも長期トークンのほうが選ばれます。

環境変数の置き場所にも注意が要ります。シェルの設定ファイルだけでなく、設定ファイルのenvブロックに入れている場合も同じです。ドキュメントによれば、変数が設定されたまま/loginを実行すると、そのセッションだけは新しいログインに切り替わります。ただし新しいセッションを始めるたびに、変数が再び読まれます。変数を消さない限り、症状は繰り返します。

手元の認証方式を確かめる

claude auth statusは認証状態をJSONで返し、authMethodはnone、claude.ai、oauth_token、api_key、api_key_helper、third_partyのいずれかです。長期トークンが効いているならoauth_tokenになる想定です。

claude auth status --text
env | grep CLAUDE_CODE_OAUTH_TOKEN
grep -n CLAUDE_CODE_OAUTH_TOKEN ~/.claude/settings.json

2行目はシェル環境、3行目はユーザー設定のenvブロックを調べます。プロジェクトの設定ファイルや管理設定に入っている場合もあるので、見つからなければ他の設定ファイルも探します。

常駐サーバーでの二択と、それぞれの代償

GitHub issueで報告されているのは、Dockerコンテナ内で動くHome Assistantのアドオンのような、ヘッドレスの常駐セッションです。報告者は、現実的な選択肢を次のように整理しています。

「約28日で更新が切れる」という数字は報告者の観測で、認証ドキュメントの期限の節には日数の記載がありません。ドキュメント側で確かなのは、期限切れの扱いです。認証ドキュメントによれば、バックグラウンドセッションやRemote Controlセッションがログインの期限を越えて動き続けると、処理が進まなくなり、再ログインするまで回復しません。期限が近づくと起動時に「Your login expires in 3 days」と警告が出るので、無人運用ではこれを見逃さない仕組みが前提になります。

使い分けの目安

用途で分けると判断が早くなります。

• CIやバッチ処理のように、人が外から触らない: 長期トークン。Remote Controlは不要です。手順はsetup-tokenの発行と運用にまとめています
• 手元のマシンで長く動かし、スマホからも見たい: /login。期限の警告が出たら更新します
• 無人で長期間動かし、外からも操作したい: 現状は両立する方法がありません。どちらかを諦めるか、定期的に人がclaude auth loginをやり直す運用になります

三つ目が、issueの報告者が困っている領域です。

issueで求められていること

報告はanthropics/claude-codeのissue #96076として、2026年9月22日にbugとarea:authラベルで起票されました。起票後のコメントはなく、openのままです。報告者の環境はv2.1.207で、CHANGELOGの先頭(v2.1.278)までを調べても対応の記載がなかったとされています。

求めている対応は3つです。

1. setup-tokenのトークンにもuser:profileスコープを持たせる(明示的なオプトインでもよい)
2. 通常ログインのリフレッシュトークンをバックグラウンドで更新し続ける仕組み
3. 少なくとも、このトレードオフをclaude setup-token --helpとRemote Controlのドキュメントに書く

issueは3つ目を「文書化がなく、claude doctorのエラーで初めて分かる」と述べています。現在の公式ドキュメントには、Remote Controlのトラブルシューティングと認証ドキュメントの両方に、長期トークンではRemote Controlを確立できないという記述があります。文書化の要望は、少なくとも文面上は満たされています。残る1つ目と2つ目は、仕様の変更を求める内容です。

「環境変数が常に勝つ」という主張の位置づけ

報告者は、フルログインを済ませても環境変数のトークンが常に優先される、と書いています。公式ドキュメントの優先順位表とは整合しますが、「/loginで現在のセッションだけは切り替わる」という記述とは、見かけ上ずれがあります。優先順位表と「現在のセッションだけ切り替わる」の記述を合わせると、切り替わるのは現在のセッションに限られ、次のセッションで変数が再び読まれるためと説明がつきます。

Remote Controlに戻す手順

長期トークンを外してRemote Controlへ戻すときは、次の順に進めます。

トークン自体はsetup-tokenが保存しない仕様です。CI側で使うトークンは、発行時にコピーした値がそのまま残ります。

状況に応じた対処のまとめ

Remote Controlが必要なら、CLAUDE_CODE_OAUTH_TOKENをシェルと設定ファイルの両方から消し、claude auth loginでclaude.aiのサブスクリプションログインに戻します。そのうえでclaude auth statusのauthMethodがclaude.aiになっているかを確認します。

長期トークンが必要なら、Remote Controlとコネクタを使わない前提で設計します。無人で長く動かしながら外からも操作したい場合は、issueが解決されるまで、期限警告を見て人が再ログインする運用が実質の選択肢です。接続の失敗が別の文言で出たときは、Remote Controlの接続トラブル一覧とログイン更新の失敗を引くと原因を絞れます。Remote Control自体の使い方はRemote Controlの使い方を参照してください。

よくある質問

setup-tokenを使ったまま、別のマシンでRemote Controlだけ使えますか

トークンを設定していないマシンでclaude auth loginすれば、そのマシンのRemote Controlは使えます。変数は環境ごとの設定なので、設定していない環境には影響しません。

再ログインが頻繁に求められるのは長期トークンで解決しますか

Remote Controlが不要なら選択肢になります。頻繁な再ログインの原因の切り分けは、再ログインを求められる原因に別途まとめています。