Claude CodeでConnection refusedが出る原因と切り分け

Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)は、Claude Codeが「接続を拒否された」と報告するエラーです。文面はファイアウォールかプロキシを疑わせますが、GitHubのissueに集まった報告では、原因が宛先の取り違えだった例が目立ちます。ANTHROPIC_BASE_URLが、すでに止まったローカルのプロキシやゲートウェイを指したままになっているケースです。

この記事は、ネットワークを疑う前に1分で終わる確認を先に置き、それでも直らないときに本物のファイアウォール・プロキシ問題へ進む順で切り分けます。

このエラーは何を意味するか

Claude Codeのエラー一覧では、この文言は「Unable to connect to API」の仲間として扱われています。APIへのTCP接続が失敗した、または完了しなかったときに出るもので、接続エラーの種類ごとに文言が変わります。

Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL)
Connection dropped (ECONNRESET)

括弧の中のコードは環境で揺れます。Connection refusedはConnectionRefusedにもECONNREFUSEDにもなります。v2.1.227より前は、同じ状況がUnable to connect to API (ECONNREFUSED)の形で表示されていました。検索で古い文言の記事に当たったときは、同じ現象として読んで構いません。

「Connection refused」の意味は、接続先のホストには届いたのに、そのポートで待ち受けているものが無かった、というものです。ファイアウォールが黙って捨てた場合はタイムアウトになりやすく、即座に拒否される場合は宛先が間違っているか、プロキシが明示的に断っています。メッセージが出るまでの早さも手がかりになります。

最初の1分: curlと環境変数で宛先を確かめる

切り分けの軸は2つです。同じシェルからapi.anthropic.comへ届くか。そして、Claude Codeの宛先が本当にapi.anthropic.comか。

curl -I https://api.anthropic.com
echo $ANTHROPIC_BASE_URL
env | grep -i -E 'anthropic|proxy'

Windows PowerShellではcurlがInvoke-WebRequestの別名になるため、curl.exe -I https://api.anthropic.comと書きます。環境変数はecho $env:ANTHROPIC_BASE_URLで見ます。

結果の読み方は次のとおりです。

3行目が、このエラーで最も見落とされる組み合わせです。curlも、Node.jsの素のfetchもANTHROPIC_BASE_URLを読みません。ネットワークの診断が全部成功しても、Claude Codeだけが別の場所へ送っているため、診断が「問題なし」を返し続けます。

宛先がずれる4つの経路

issueのコメントに挙がった例を、混入経路で分けると4つあります。どれもANTHROPIC_BASE_URLを指す先が、すでに動いていないことが共通点です。

Ollama接続そのものを意図して設定する手順はClaude CodeをOllamaのローカルLLMに接続する手順と制約にまとめています。意図して設定した変数を、別の用途の端末にまで持ち込まないことが、この症状の予防になります。

症状から経路を当てる手がかり

issueの報告には、宛先の取り違えを疑える付随症状がいくつか書かれています。ここでの記述は報告者の観察であり、すべての環境で再現するとは限りません。

• /loginは成功するのに状況が変わらない。認証の通信先と、推論リクエストの宛先が別のため
• デスクトップアプリでは動くのに、VS Codeの統合ターミナルでは失敗する。アプリが子プロセスに渡す環境変数を上書きしているため
• claude -p "hi" --debugのログに、ANTHROPIC_BASE_URLがAnthropic公式のホストではないという趣旨の行が出る
• claude doctorがANTHROPIC_BASE_URLの設定を警告する

最後の2つは、報告者が自分の環境で見た出力です。表示の文言はバージョンで変わることがあるので、手元の出力で確かめてください。claude doctorは、セッションを開始せずに、インストールと設定の診断を読み取り専用で出力します。切り分けの初手として軽いので、手作業の診断を長く続ける前に1回走らせておくと時間を節約できます。

直し方: 消す場所を3か所当たる

宛先がずれていると分かったら、変数の出どころを順に当たります。見つけた場所で消し、新しい端末から起動します。

シェルの設定ファイルから該当行を消すコマンドは、次のとおりです。実行前にgrepで行を確認してください。

grep -n ANTHROPIC_BASE_URL ~/.bashrc ~/.zshrc ~/.profile
sed -i '/ANTHROPIC_BASE_URL/d' ~/.bashrc ~/.zshrc ~/.profile
unset ANTHROPIC_BASE_URL

macOSのsed -iは引数の形が違い、sed -i ''と空文字を渡す必要があります。迷うときは、エディタで該当行を手で消すほうが安全です。

VS Codeの統合ターミナルだけ外す

マシン全体に変数が入っていて、自分では消せない環境では、VS Codeの統合ターミナルに限って外せます。ユーザー設定のsettings.jsonに次のように書きます。報告者が使った形で、Windowsの例です。

"terminal.integrated.env.windows": {
    "ANTHROPIC_API_KEY": null,
    "ANTHROPIC_BASE_URL": null
}

nullは変数を取り除く指定です。設定後は、新しい統合ターミナルを開いてください。この方法が効くのはVS Codeの端末だけで、他のシェルの変数はそのまま残ります。根本的に直すには、配布元の管理者に依頼して変数を外してもらう必要があります。

変数を1回だけ外して起動する

Ollamaの変数をユーザー環境全体に置いていて、一時的に本家のAPIへ戻したいときは、起動コマンドの側で外す方法があります。fishでの例が報告されています。

env -u ANTHROPIC_API_KEY -u ANTHROPIC_BASE_URL claude

恒久的に直すなら、変数をユーザー環境へ置くのをやめ、使うアプリやコマンドの範囲に限定します。

設定が戻ったかを/statusで確かめる

直したら、短いメッセージを送る前に/statusを開きます。Anthropic base URLの行は、ベースURLが設定されているときだけ表示されます。行が出なければ、変数はセッションに届いていません。つまり、直っています。ゲートウェイを意図して使っている場合は、行のアドレスが想定と合っているかを見ます。この確認の詳しい手順と、設定の優先順位はANTHROPIC_BASE_URLでAPIエンドポイントを切り替えるにあります。

意図してゲートウェイを使っている環境で同じエラーが出るときは、ゲートウェイ側に届いていない可能性が高くなります。ゲートウェイ接続のトラブルシューティング表にも、同じ文言の行があります。原因は「ベースURLのアドレスが違う、またはVPNやファイアウォールがゲートウェイへの経路を塞いでいる」で、確認はcurlでゲートウェイへ届くかを試す形です。

本当にファイアウォールやプロキシのとき

curl -I https://api.anthropic.comが失敗し、ANTHROPIC_BASE_URLも空なら、ネットワークの問題です。順に当たります。

プロキシ変数を設定する

社内にプロキシがあるなら、Claude Codeを起動する前にHTTPS_PROXYを設定します。

export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY="localhost,127.0.0.1"
claude

Claude Codeは標準のプロキシ変数に従い、大文字小文字の別を許容します。優先順はhttps_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXYです。SOCKSプロキシには対応していません。プロキシのURLをhttp://といったスキーム抜きで書くと、起動時に変数名つきのエラーで止まります。

どの設定が読み込まれたかは、/statusのProxy行で確かめられます。解釈できない値は、無効で無視されたと表示されます。

プロキシが接続を拒否した場合は、文言が変わります。Couldn't connect through your proxy (ERR_PROXY_TUNNEL)が出たときは、プロキシのトンネル要求が断られています。認証情報と、プロキシが対象ホストを許可しているかを確かめる場面です。

許可するホストを確認する

ファイアウォールとプロキシには、少なくとも次のホストの許可が必要です。

プラグインやネイティブインストーラー、MCPコネクタなど、使う機能ごとに追加のホストがあります。完全な一覧はネットワーク設定のドキュメントにあり、コンテナや制限の厳しい環境ほど漏れやすい部分です。コンテナ内で外向き通信を絞る参照構成はdevcontainerのinit-firewall.shで扱っています。

サンドボックス内のコマンドの通信を検査プロキシへ通す設定は、Claude Code本体の通信とは別のレイヤーです。httpProxyPortとsocksProxyPortで社内検査プロキシを通す設定を参照してください。

curlが成功してもClaude Codeが失敗するとき

curlは成功するのにConnection refusedが続く場合、ANTHROPIC_BASE_URL以外にも、ランタイムとネットワークの間にあるものを疑います。

• LinuxとWSLでは、/etc/resolv.confの名前解決先が到達不能になっていないか。WSLはホストから壊れた設定を引き継ぐことがあります
• macOSでは、切断またはアンインストールしたVPNが、トンネルインターフェースやルーティングの規則を残していないか。ifconfigで古いutunを探します
• Docker Desktopなど、コンテナのランタイムが外向き通信を横取りしていないか。終了して再試行すると切り分けられます

接続エラー全般の切り分けとAPIキー側の確認は、Claude API connection errorが出たときの切り分けと疎通確認が扱っています。

見落としやすいつまずき

• 新しい端末を開き忘れる: 設定ファイルを直しても、起動済みの端末は古い環境変数を持ち続けます
• curlの成功を安心材料にする: curlはANTHROPIC_BASE_URLを読まないので、成功しても宛先の正しさは何も保証されません
• 自動再試行の沈黙を故障と見なす: 一時的な失敗は自動で再試行されるため、エラーが出るまで間が空くことがあります。持続する失敗はローカルのネットワーク問題を指します
• 設定を書いたツールを忘れる: settings.jsonのenvは他のツールが書き込んでいる場合があります。自分で書いた覚えがなくても、値が残っていないか見ます

メッセージが宛先を示さないという弱点

issueでは、メッセージに実際に接続を試みたホストが含まれていれば、ConnectionRefused (http://127.0.0.1:8045)のように一目で原因が分かったはずだという提案が出ています。現状の文言例には宛先のホストが含まれず、ファイアウォールかプロキシを疑う文面になっています。この記事の切り分けは、その欠けを手作業で補う手順です。

エラーが出たら、まず「どこへ送ろうとして断られたのか」を確かめる。echo $ANTHROPIC_BASE_URLの1行は、ネットワークの調査より先に打つ価値があります。このissueはドキュメントの不足として起票されています。

よくある質問

claude updateやインストールし直しで直りますか

報告では、更新もネイティブインストーラーとnpmの入れ直しも効きませんでした。原因が環境変数にあるため、バイナリを入れ替えても宛先は変わりません。