Claude Media
Couldn't start the local listenerの2つの挙動と対処 — Claude Code
Claude CodeTips

Couldn't start the local listenerの2つの挙動と対処 — Claude Code

「Couldn't start the local listener」と「The browser can't return the sign-in」は原因が同じでも進み方が違います。コードを貼って続ける手順と、止まったときの代替認証です。

読了目安 約10分

Couldn't start the local listener that receives the browser sign-in. Try again. と出たら、サインインは止まっています。一方、The browser can't return the sign-in to Claude Code automatically という通知なら、同じ原因でも続行できます。表示されたURLをブラウザーで開き、出てきたコードを貼るだけです。

どちらも、ブラウザーがサインイン結果を返す 127.0.0.1 のポートを、Claude Codeが開けなかったことを示します。違うのは、そのあとの進み方です。

2つのメッセージは何が違うのか

/login、claude auth login、claude setup-token のどれかで、このポートを開けないと次のどちらかになります。

表示サインインの状態ブラウザー
The browser can't return the sign-in to Claude Code automatically. After you sign in, paste the code shown.サインインの状態続行できるブラウザー自動では開かない
Couldn't start the local listener that receives the browser sign-in. Try again.サインインの状態止まるブラウザー開かない

前者は、URLの上に通知が出る形で進みます。後者はそこで終わります。

会話

どちらが出ても、手を止める必要はあるのか

  1. 後輩

    「The browser can't return…」が出ました。何か壊れたのでしょうか。

  2. 先輩

    先に直す必要はありません。ポートなしで進む経路に切り替わっただけです。出ているURLを開いてください。

  3. 後輩

    「Couldn't start the local listener」のほうは、URLが出ません。

  4. 先輩

    そちらは止まった側です。もう一度同じコマンドを実行し、同じ結果なら別の認証手段に切り替えます。

通知が出たとき: URLを開いてコードを貼る

The browser can't return the sign-in to Claude Code automatically の場合、手順は3つです。

手順

コード貼り付けでサインインを続ける

  1. 1

    URLを開く

    通知の下に表示されたURLを、ブラウザーで開いてサインインします。ブラウザーは自動では開きません。

  2. 2

    コードを控える

    サインインが済むと、ブラウザーに「コード」が表示されます。

  3. 3

    コードを貼る

    Claude Codeの Paste code here > プロンプトに、そのコードを貼ります。ここからサインインが続きます。

WSL2、SSH接続、コンテナーのようにブラウザーが別のホストで開く環境では、これは珍しい場面ではありません。ブラウザーのリダイレクトがClaude Codeのローカルのコールバックサーバーに届かず、リダイレクトの代わりにログインコードが表示されるからです。トラブルシューティングのページでは、この環境でコードを Paste code here if prompted のプロンプトに貼る手順が案内されています。

貼り付けが効かないときは、端末の貼り付けキーが入力欄に届いていない可能性があります。Windows Terminalなら右クリックやShift+Insertを試します。それでも通らなければ、標準入力から貼り付けコードを読む claude auth login を使う手もあります。

claude auth login

「Couldn't start the local listener」で止まったとき

この文言を含むメッセージが出たら、サインインはそこで止まっています。たとえば claude auth login に入力をパイプで流し込んだときに起こります。

Couldn't start the local listener that receives the browser sign-in. Try again.

対処は、軽いものから順に3段階です。

  1. 同じコマンドをもう一度実行する
  2. 同じ止まり方が続くなら、ブラウザーを使わない認証に切り替える
  3. パイプで入力を渡していたなら、端末でそのまま実行し、貼り付けコードを受け取れる状態にする

3番目は、パイプで入力を流し込む実行が止まる例として挙がっているためです。端末で実行すれば、貼り付けコードを受け取れます。

ブラウザーを使わずに認証する

2番目の切り替え先は、契約形態で分かれます。

契約設定するもの取得元
claude.aiのサブスクリプション設定するもの環境変数 CLAUDE_CODE_OAUTH_TOKEN取得元サインインが通る別のマシンの claude setup-token
Claude Consoleの契約設定するもの環境変数 ANTHROPIC_API_KEY取得元Claude Consoleで発行したキー

サブスクリプションの場合は、サインインできるマシンでトークンを発行します。

claude setup-token

承認すると、有効期間1年のOAuthトークンが端末に表示されます。トークンはどこにも保存されません。値をコピーして、困っているマシンの環境変数に設定します。

export CLAUDE_CODE_OAUTH_TOKEN=your-token

どちらの変数も、設定したあとに /status でどの認証が使われているかを見ておけます。複数の認証手段が同居するときの優先順位は、Claude Codeのチーム認証の設定手順と認証情報の優先順位にあります。ログイン方法の違いはClaude Codeログイン方法3種の使い分けが扱っています。

OSごとの設定コマンド

export はmacOS、Linux、WSLの書き方です。Windowsでは端末ごとに書き方が変わります。

$env:CLAUDE_CODE_OAUTH_TOKEN = "your-token"
set CLAUDE_CODE_OAUTH_TOKEN=your-token

このトークンはサブスクリプションの認証に使われ、Pro、Max、Team、Enterpriseのいずれかのプランが必要です。モデルへのリクエストしか送れないため、Remote Controlのセッションを開始したり、claude.aiのコネクターを取得したりはできません。ローカルで設定したMCPサーバーは引き続き使えます。スクリプトに --bare を付けると CLAUDE_CODE_OAUTH_TOKEN は読まれないので、その場合は ANTHROPIC_API_KEY か apiKeyHelper で認証します。

変数を入れっぱなしにしたときの副作用

CLAUDE_CODE_OAUTH_TOKEN を設定した状態で /login を実行すると、そのセッションは新しいログインに切り替わります。ただ、変数は新しいセッションのたびにまた読まれます。シェルのプロファイルや設定ファイルの env から消さない限り、変数の値が使われ続けます。

Remote Controlが使えない点は、上のとおりトークンの仕様です。理由と外し方はsetup-tokenとRemote Controlが両立しない理由にあります。

貼り付けで詰まる3つの場面

コードを貼る経路に入ってからの失敗は、次の3つが中心です。

  • URLが開けない。ブラウザーが自動で開かない、または狭い端末やSSHでURLが折り返してクリックできないときは、c キーでURLをクリップボードにコピーして手動で開く
  • OAuth error: Invalid code. Please make sure the full code was copied。コードの期限切れか、コピー中の欠けが原因。Enterで再試行し、ブラウザーが開いたらすぐ済ませる
  • 貼り付けても反応しない。端末の貼り付けキーが入力欄に届いていない。別の貼り付けショートカットか、先に挙げた claude auth login を使う

WSL2でブラウザーが全く開かないときは、環境変数 BROWSER にWindows側のブラウザーのパスを指定する方法もあります。

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

ブラウザーの自動返しを取り戻すには

通知が出るたびにURLとコードを手で扱うのが面倒なら、根本は「Claude Codeが 127.0.0.1 で待ち受けられる環境にする」ことです。

  • サンドボックスの中で動かしているなら、そのポリシーがローカルポートでの待ち受けを許しているかを確かめ、直してからサインインし直す
  • 待ち受けが許されているはずなのに通知が出るなら、/feedback を実行して環境の詳細をレポートに含める

注意したいのは、コマンド実行用のサンドボックスにある network.allowLocalBinding です。これは、サンドボックス内で動くコマンドがポートで待ち受けるための設定で、macOSの手順として書かれています。LinuxとWSL2では、サンドボックス内のコマンドから見た localhost はそのコマンド専用で、この設定は効きません。サインイン用リスナーの対処としては挙がっていないので、同じものと考えないほうが安全です。

v2.1.305より前の表示との関係

v2.1.305より前は、ポートを開けないとサインインがその場で止まり、サインイン先のURLも出ませんでした。メッセージは、たとえば次のような形でした。

Failed to start OAuth callback server: Failed to start server. Is port 0 in use?

この古い表示に当たったなら、Claude Codeを更新してサインインし直すか、ブラウザーを使わずにトークンかAPIキーで認証します。旧メッセージの読み方と回避手順はFailed to start OAuth callback serverの原因と回避にまとめています。

つまり、v2.1.305以降は「通知が出てURL経由で続行」と「止まる」の2通りに分かれます。バージョンを確認してから読み分けるのが早道です。

近い症状との見分け方

認証まわりのメッセージは似ています。今どの表示が出ているかで、行き先が変わります。

出ている表示状況読むべき内容
The browser can't return the sign-in…状況ポートなしで続行できる読むべき内容本記事の貼り付け手順
Couldn't start the local listener…状況サインインが止まった読むべき内容本記事の代替認証
Failed to start OAuth callback server…状況v2.1.305より前の表示読むべき内容旧メッセージの記事
保存に失敗したという表示状況認証は通ったが資格情報を保存できない読むべき内容Couldn't save your loginの記事

ポート自体を別プロセスが握っている場合や、OAuthのstateが消えてログインが循環する場合は、別の原因です。ループの症状ならClaude Codeのログインがループする原因が合います。

まとめ

2つのメッセージは同じ原因から来ますが、進み方が逆です。通知なら、URLを開いてコードを貼れば続けられます。Couldn't start the local listener なら、まず再実行し、続くなら claude setup-token と CLAUDE_CODE_OAUTH_TOKEN、もしくは ANTHROPIC_API_KEY に切り替えます。

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

関連する記事

Claude Code をもっと見る →