CursorとClaude Codeの企業ネットワークにおけるHTTPS_PROXYの設定方法

もしあなたの会社が企業プロキシを通じてアウトバウンドトラフィックを遮断している場合、Cursor や Claude Code のような AI アシスタントは ただ応答しなくなります: オートコンプリートがフリーズし、CLI が ETIMEDOUT または SSL certificate problem を返します。 環境変数 HTTPS_PROXY を正しく設定し、 認証を設定し、開発者がコードの代わりにネットワーク設定のデバッグに何時間も費やす原因となる一般的なエラーを回避する方法を見ていきましょう。

企業ネットワークにおける AI アシスタントのためのプロキシの必要性

Cursor と Claude Code はローカルモデルではありません。彼らは外部 API に常にアクセスしています: Cursor は自分の コードインデクシングサーバーやモデルの API（選択したプロバイダーに応じて OpenAI、Anthropic、Google など）にアクセスし、Claude Code は HTTPS を介して直接 Anthropic API にアクセスします。企業ネットワークでは、インターネットへの直接アクセスはファイアウォールによって 通常遮断されており、すべてのアウトバウンドトラフィックはプロキシサーバー（Squid、Zscaler、Blue Coat、Fortinet FortiProxy または内部の 企業ゲートウェイ）を通過する必要があります。正しく設定された環境変数がないと、アプリケーションはトラフィックをプロキシを通じて ルーティングする必要があることを知らず、直接インターネットにアクセスしようとしてタイムアウトが発生します。

別の難しさは、Cursor が Electron（本質的には Chromium + Node.js）上に構築されているのに対し、Claude Code は Node.js CLI アプリケーションであることです。各々がプロキシ設定を読み取るロジックは異なります: Electron は部分的に OS のシステム設定を継承し、Node.js プロセスは環境変数 HTTP_PROXY/HTTPS_PROXY を直接または undici や node-fetch のようなライブラリを介して読み取ります。 これが混乱を引き起こします: 設定はされているのに、ツールがそれを「見えない」状態になります。

HTTP_PROXY、HTTPS_PROXY、および NO_PROXY 環境変数: その仕組み

コンソールの Node.js、Python、および Go アプリケーションのためにプロキシを指定する一般的な方法は、環境変数を介して行います。 HTTP_PROXY と HTTPS_PROXY の違いは重要です: 前者は HTTP プロトコルのリクエストに使用され、 後者は HTTPS リクエストに使用されます（ほとんどの AI アシスタントのトラフィックは実際には HTTPS です）。実際のトラフィックが HTTPS のみであっても、両方を指定するべきです — 一部のライブラリは起動時にサービス用の HTTP リクエストを行います。

export HTTP_PROXY="http://proxy.company.local:8080"
export HTTPS_PROXY="http://proxy.company.local:8080"
export NO_PROXY="localhost,127.0.0.1,.company.local"

注意: HTTPS トラフィックの場合でも、プロキシのアドレスは http:// として指定されます。https:// ではありません — これはプロキシサーバー自体のアドレスであり、ターゲットリソースのアドレスではありません。HTTP 経由でプロキシに接続するのは正常であり、 最終サーバーへの暗号化は CONNECT トンネリングメカニズムを介して機能します。

NO_PROXY 環境変数は、企業の内部アドレスをプロキシから除外するために必要です — さもなければ、内部の git リポジトリ、Jira、またはローカル開発サービスへのリクエストも外部プロキシを通過し、見つからないか、遅くなる可能性があります。重要な 注意点: 一部のライブラリは変数の大文字と小文字に敏感です。信頼性のために、両方のバリエーションを指定してください — 大文字と小文字の両方で:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export no_proxy="$NO_PROXY"

Cursor のためのプロキシ設定

Cursor は部分的に OS のシステムプロキシ設定を使用します（特に macOS と Windows で）、しかし企業ネットワークでの安定した動作のためには 環境変数を介して明示的に設定し、必要に応じてアプリケーションの設定ファイルを介して設定する方が良いです。

macOS と Linux では、ターミナルを起動するたびに環境変数が読み込まれるように、 シェルプロファイルファイルにエクスポートを追加するのが最も簡単です。これにより、Cursor が起動されます:

# ~/.zshrc または ~/.bash_profile
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,*.company.local"

プロファイルファイルを変更した後は、source ~/.zshrc を実行し、Cursor を完全に再起動してください（ウィンドウを単に最小化するのではなく、Activity Monitor やタスクマネージャーを介してプロセスを終了させてください。Electron アプリケーションは起動時に環境をキャッシュします）。

Windows では、環境変数をシステム設定（コントロールパネル → システム → システムの詳細設定 → 環境変数）を介して設定する方が便利です。 または PowerShell を介して永続的に保存することもできます:

[System.Environment]::SetEnvironmentVariable('HTTPS_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('HTTP_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('NO_PROXY','localhost,127.0.0.1','User')

それでも Cursor がモデル API に接続できない場合は、アプリケーション内のプロキシ設定を確認してください: 設定 → ネットワーク（または一般） — そこには システム変数をオーバーライドする Proxy URL の個別フィールドがあるかもしれません。Cursor の一部のビルドでは、「Use system proxy settings」オプションを明示的に有効にする必要があります。

Claude Code のためのプロキシ設定

Claude Code は Node.js 上の CLI ツールで、npm/npx を介して起動されるため、呼び出されたターミナルセッションから直接環境変数を読み取ります。 これにより設定が簡素化されます: 起動前に変数をエクスポートするだけで済みます。

export HTTPS_PROXY="http://user:[email protected]:8080"
export HTTP_PROXY="http://user:[email protected]:8080"
claude

CI パイプラインの一部としてまたはスクリプトから Claude Code を起動する場合は、グローバルなシェル環境への依存を避けるために、起動コマンドに明示的に変数を渡してください:

HTTPS_PROXY="http://proxy.company.local:8080" \
HTTP_PROXY="http://proxy.company.local:8080" \
claude --print "プロジェクトのテストを確認してください"

永続的な構成のためには、プロジェクトのルートにある .env ファイルに変数を固定し、 direnv またはシェルがサポートしている場合は dotenv の組み込みサポートを介して読み込むのが便利です。 これは、異なるプロジェクトが異なるプロキシ設定を必要とする場合（例えば、一つのプロジェクトが内部 API と連携し、別のプロジェクトが外部サービスと連携する場合）に特に便利です。

企業プロキシでの認証

ほとんどの企業プロキシは認証を要求します — Basic Auth、Digest、または NTLM。Basic Auth の場合、ログインとパスワードはプロキシの URL に直接埋め込むことができます。 上記のように: http://user:[email protected]:8080。 重要な注意点 — パスワードに特殊文字（@、#、%）が含まれている場合、 それらを URL エンコードする必要があります。さもなければ、プロキシ文字列のパーサーがログインとホストの境界で壊れてしまいます。

# パスワードが P@ssw0rd#2024 の場合、特殊文字をエンコードします:
# @ -> %40, # -> %23
export HTTPS_PROXY="http://user:P%40ssw0rd%[email protected]:8080"

NTLM 認証はより複雑です（Microsoft ISA Server、Forefront TMG または Fortinet と組み合わせて使用されることが多い） — Node.js とほとんどの HTTP クライアントは NTLM を「デフォルトで」サポートしていません。その場合の標準的な解決策は、 NTLM ハンドシェイクを処理し、その後アプリケーションに「クリーン」な HTTP プロキシを提供するローカルプロキシミドルウェアを立ち上げることです。 これには、cntlm や px（Python 上のローカル NTLM プロキシ）がよく使用されます。 スキームはシンプルです: Cursor/Claude Code → localhost:3128 (cntlm) → 企業 NTLM プロキシ → インターネット。

# cntlm の設定例 (/etc/cntlm.conf)
Username    your_login
Domain      COMPANY
Password    あなたのパスワードまたはハッシュ
Proxy       proxy.company.local:8080
Listen      3128

# cntlm を起動した後、ローカルアドレスを指定します:
export HTTPS_PROXY="http://127.0.0.1:3128"
export HTTP_PROXY="http://127.0.0.1:3128"

証明書と MITM: 企業ネットワークにおける SSL の問題

会社に Zscaler、Netskope、またはその他の SSL インスペクションを伴うウェブフィルタ製品が展開されている場合、 トラフィックはプロキシで復号化され、企業のルート CA 証明書で署名されます。Node.js（したがって Claude Code と Cursor の大部分の内部モジュール）は デフォルトで自分の組み込みのルート証明書セットのみを信頼し、UNABLE_TO_VERIFY_LEAF_SIGNATURE または self signed certificate in certificate chain のエラーを投げます。

解決策は、企業の CA 証明書をエクスポートすることです（通常、IT 部門から取得するか、ブラウザの証明書ストレージからエクスポートできます）、 そして Node.js にそのパスを NODE_EXTRA_CA_CERTS 環境変数を介して指定します:

export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/company-root-ca.pem"

NODE_TLS_REJECT_UNAUTHORIZED=0 を介して証明書の検証をグローバルに無効にすることは 極めて推奨されません — これはプロセス全体に対する MITM 攻撃からの保護を取り除き、正当な接続も含まれます。このフラグは一時的な診断のためにのみ使用し、 必ず保護を元に戻してください。

一般的なエラーとその解決策

エラー	原因	解決策
ETIMEDOUT / ECONNREFUSED	アプリケーションが実行されているセッションにプロキシ変数がエクスポートされていない	同じターミナルで echo $HTTPS_PROXY を確認し、アプリケーションを完全に再起動してください
407 Proxy Authentication Required	ログイン/パスワードが指定されていないか、古くなっている	プロキシの文字列で資格情報を更新し、パスワードの特殊文字を URL エンコードしてください
self signed certificate in certificate chain	企業の MITM プロキシが証明書を置き換えている	企業のルート CA を指定した NODE_EXTRA_CA_CERTS を指定してください
プロキシはターミナルで動作するが、Cursor では動作しない	Cursor が異なるターミナルから起動されているか、環境なしでショートカットから起動されている	エクスポートされた変数を持つターミナルからコマンドで Cursor を起動するか、システム全体で変数をグローバルに設定してください
NTLM authentication failed	クライアントが NTLM ハンドシェイクをサポートしていない	アプリケーションと企業プロキシの間に中間プロキシ cntlm または px を立ち上げてください

curl を使った接続確認

Cursor や Claude Code が動作しない理由を調査する前に、プロキシ自体が基本的にアクセス可能であり、HTTPS トラフィックを正しくプロキシしていることを確認してください。 そのためには curl を使用します — curl は同じ環境変数を読み取り、重いアプリケーションを起動せずに問題を迅速に特定することができます。

# プロキシと認証の可用性を確認
curl -v -x "http://user:[email protected]:8080" https://api.anthropic.com

# 企業証明書を考慮した確認
curl -v --cacert /etc/ssl/certs/company-root-ca.pem \
  -x "http://user:[email protected]:8080" \
  https://api.anthropic.com

curl が成功裏に応答を受け取る場合（401 や 403 でも問題ありません、TLS ハンドシェイクが成功したことを意味します）、それでも Claude Code が接続できない場合は、 問題はネットワークではなく、プロセスが環境変数を見ていないことです。もし curl も証明書エラーやタイムアウトで失敗する場合は、ネットワークまたはプロキシのレベルで問題があり、 ツールは関係ありません。

企業プロキシの代わりに外部プロキシが必要な場合

時には、タスクが企業ネットワークから外部へのアクセスに限定されないことがあります。地理的に依存する API との統合をテストしている開発者は、 異なる国からサービスの動作を確認したり、プロバイダーのモデルに対するレート制限ポリシーをデバッグしたりする際に、企業プロキシがすべてのリクエストに対して同じ企業 IP を返すことに直面します。 そのようなシナリオでは、テストトラフィックを外部プロキシを通じてメインの作業環境と並行して流すことが便利です。

安定した長期的なテストセッションで IP によるブロックのリスクを最小限に抑えるためには、 レジデンシャルプロキシ が適しています — これらは実際の家庭プロバイダーの IP アドレスを使用し、通常のユーザートラフィックのように見えるため、API の地理的に特異な応答を確認する際に重要です。 モバイルクライアントの動作を再現したり、ネットワークタイプに敏感なシナリオをテストしたりする必要がある場合は、モバイルプロキシを検討する価値があります。 公開 API に対する大量の並行リクエストをテストする場合は、速度とトラフィックコストが重要であり、通常のユーザーとしてのマスキングが重要でない場合は、通常 データセンタープロキシ で十分です。

重要: このような外部プロキシは、HTTPS_PROXY/HTTP_PROXY を介して同様に設定されますが、 テスト環境や個別のターミナルプロファイルのために、企業ゲートウェイを通じてのメインの作業トラフィックと混同しないようにします。企業のポリシーが、会社のすべてのトラフィックが内部プロキシを通過することを要求する場合、 外部プロキシの使用は IT/Security と合意する必要があります — 多くの企業は許可なしに企業ゲートウェイを回避することを明示的に禁止しています。

設定チェックリスト

結論

Cursor と Claude Code の企業プロキシでの問題のほとんどは、環境変数がプロセスに届かないこと、認証が不正確に設定されていること、または企業の MITM 証明書が 信頼されたものに追加されていないことに起因します。これらの三つのポイントを順に確認することで — curl を介して、 アプリケーションを直接使用するのではなく — 時間を節約し、迅速に原因を特定できます。

もしタスクが企業ネットワークの枠を超え、異なる地域や異なるタイプの IP から API の動作をテストする必要がある場合は、レジデンシャルプロキシを試してみることをお勧めします — これにより、通常のデータセンターのアドレスと比較して、外部サービスに対して安定した、より疑わしくないトラフィックを提供します。