Claude Codeプロキシ設定 — 社内CA証明書と許可ドメインの手順

Claude Codeのプロキシ設定は、HTTPS_PROXYなどの環境変数と社内CA証明書の登録さえ揃えれば、多くの企業ネットワークでそのまま疎通します。ただし証明書を登録する場所やmTLS、バックグラウンドエージェントへの設定の届け方など、通しで読まないと拾いにくい分岐点がいくつかあります。環境変数の優先順位から証明書・mTLSの設定、ファイアウォールで許可すべきドメイン一覧、症状別のトラブルシューティングまでを扱います。

Claude Codeが企業プロキシ配下でつながらないときに出る症状

企業ネットワーク配下でClaude Codeが動かないとき、症状は大きく3つに分かれます。1つ目は起動直後に落ちる「プロキシURLのパースエラー」、2つ目はしばらく動いてから出る「接続エラー(ECONNREFUSED・ETIMEDOUT等)」、3つ目は「SSL証明書エラー」です。この切り分けが最初の一歩になります。

Claude Codeは起動時にほとんどの設定値を検証しません。プロキシURLのパースだけは例外で、http://のようなスキームが欠けた値を渡すと起動時点でエラーを出して停止します。それ以外の設定ミス(証明書パスの誤りなど)は、後続のリクエストが実際に失敗するまで表面化しません。つまり「起動はするのに途中で落ちる」場合は証明書かネットワーク到達性、「起動すらしない」場合はプロキシURLの書式を疑う、という切り分けが成り立ちます。

前提として、この記事はスタンドアロンCLI(ターミナルから実行するclaudeコマンド)とターミナル起動セッションを対象にします。VS Code拡張やJetBrainsプラグインもCLI本体を内部で使うため、同じ環境変数が効きます。ただし拡張機能側の起動プロセスがどの環境を継承するかは別問題です。共有設定を確実に効かせたい場合は、後述のsettings.json経由を優先してください。

なお、Claude Desktopがプロバイダー接続を管理するセッション(サードパーティプロバイダーのCodeタブ・Coworkセッション)は対象外です。こうしたセッションでは、プロキシ変数(HTTP_PROXY・HTTPS_PROXY・NO_PROXY)とCA・mTLS関連の変数を、管理設定と~/.claude/settings.jsonからのみ読み込みます。リポジトリ側の設定ファイルは無視します(v2.1.217以降)。それより前のバージョンでは、アプリが接続を管理しているあいだ、これらの変数(プロキシ変数とCA・mTLS関連変数)がどの設定ファイルからも読み込まれませんでした。ただし、claude.aiでサインインしたローカル・SSH・WSLのCodeタブでは、アプリが接続自体を管理しないため、通常のターミナルセッションと同じくすべての設定スコープを読み込みます。

プロキシ環境変数の設定(HTTPS_PROXY・HTTP_PROXY・NO_PROXY)

プロキシ経由でAPIに到達させる最初の一手は、標準的な環境変数を設定することです。Claude CodeはHTTPS_PROXY(推奨)、HTTP_PROXY、NO_PROXYに従い、小文字のhttps_proxy等でも動作します。複数が設定されている場合、https_proxy → HTTPS_PROXY → http_proxy → HTTP_PROXYの順で最初に見つかった値を使います。

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

プロキシ側でBasic認証が必要な場合は、URLにusername:password@を埋め込みます(https://user:pass@proxy.example.com:8080)。パスワードをスクリプトに直書きするのは避け、環境変数か安全な資格情報ストアから読み込む運用にしてください。

SOCKSプロキシは非対応です。NTLMやKerberosのような高度な認証方式も同様に公式サポート外で、この場合はLLM Gatewayサービスを間に挟む構成を使う方法があります。

NO_PROXYはスペース区切り・カンマ区切りのどちらでも書け、"*"を指定すると全リクエストがプロキシを迂回します。ホスト名の名前解決を呼び出し元でなくプロキシ側に任せたい環境では、CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1を設定します。既定は無効なオプトイン項目で、社内DNSでしか名前解決できない構成のときに使います。

社内CA証明書を信頼させる

TLSを検査するプロキシ(CrowdStrike FalconやZscalerなど)を挟んだ環境では、Claude Codeがプロキシ自身の証明書を信頼していないことが接続失敗の主因になります。既定では、Mozillaのバンドル証明書(bundled)とOSの証明書ストア(system)の両方を信頼する設定になっており、多くの環境では追加設定なしでOSトラストストアにルート証明書さえ入っていれば通ります。

OSの証明書ストアを読むにはtls.getCACertificatesというランタイム機能が必要です。ネイティブインストーラ経由なら常に対応しますが、npmでインストールした場合はNode.js 22.15以降が必要です。それより古いNodeでは、バンドル証明書(bundled)とNODE_EXTRA_CA_CERTSで追加した証明書だけが使われます。つまりNODE_EXTRA_CA_CERTS自体は古いNodeでも有効で、後述の社内CA登録は影響を受けません。Claude Codeのインストール手順でNodeのバージョンを合わせて確認しておくと、証明書エラーの原因切り分けが早くなります。

社内CAを個別に追加登録したい場合はNODE_EXTRA_CA_CERTSにPEMファイルのパスを指定します。信頼元の組み合わせ自体を制御したいならCLAUDE_CODE_CERT_STOREにカンマ区切りでbundled・systemを指定します(このキーには専用のsettings.jsonスキーマ項目がなく、envブロックか環境変数で設定します)。

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-ca.pem
export CLAUDE_CODE_CERT_STORE=bundled,system

プロキシ経由でヘッダーやボディを差し込んで通す認証構成を組む場合は、環境変数リファレンスにあるCLAUDE_CODE_EXTRA_BODYの挙動もあわせて確認してください。この変数に限り、v2.1.206以降はシェルでexportした値もバックグラウンドセッションに届きます。プロキシ・CA・mTLSの各変数はこの例外に含まれず、後述のとおりsettings.json側で配る必要があります。v2.1.206より前のバージョンでは、CLAUDE_CODE_EXTRA_BODYをシェルでexportしてもバックグラウンドセッションに届かず、スーパーバイザープロセスが引き継いだコピーの値が使われていました。

mTLS(クライアント証明書認証)が必要な環境

プロキシ側がクライアント証明書での相互TLS認証を要求する環境では、CLAUDE_CODE_CLIENT_CERTとCLAUDE_CODE_CLIENT_KEYの2変数で証明書と秘密鍵のパスを指定します。秘密鍵にパスフレーズが設定されている場合はCLAUDE_CODE_CLIENT_KEY_PASSPHRASEも追加します。

export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

mTLSとCA証明書の設定は別軸です。NODE_EXTRA_CA_CERTSは「プロキシの証明書をClaude Codeが信頼する」ための設定、CLAUDE_CODE_CLIENT_CERT系は「Claude Code自身がプロキシに対して身元を証明する」ための設定です。両方が必要な環境では、どちらか一方だけ設定しても疎通しません。

証明書と鍵は起動時だけでなく、設定を適用するたび(セッション中の設定変更を含む)に再読み込みされます。同じパスにファイルを置き換えるだけでローテーションでき、証明書更新のたびに再起動する必要はありません。

ファイアウォールで許可すべきドメイン一覧

スタンドアロンCLIが到達する必要のあるホストは次のとおりです。ファイアウォール担当者への申請時は、この一覧をそのまま渡せる形にしておくと、個別機能だけが断続的に失敗するような原因特定の難しい不具合を避けられます。中核APIリクエストが止まるものと、個別機能だけが欠けるものを区別してください。

npmまたはbunでインストールする場合は、上記に加えてパッケージレジストリのregistry.npmjs.org(または社内ミラー)も必要です。2つのDatadogホストは運用テレメトリのみを運ぶオプション項目で、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICを設定すると両方まとめて無効化できます。個別に絞りたい場合はDISABLE_TELEMETRY・DO_NOT_TRACK・DISABLE_ERROR_REPORTINGの3変数も使えます。

Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundry、またはサインイン済みのゲートウェイセッションを使う場合は勝手が変わります。モデルへの通信と認証は、この表のホストではなくプロバイダーやゲートウェイ側に向かいます。

ただし例外が2つあります。WebFetchツールのドメイン安全性チェックは、skipWebFetchPreflight: trueを設定しない限りapi.anthropic.comを呼び続けます。ANTHROPIC_BASE_URLでLLM Gatewayを使う場合も、fast modeの利用可否チェックだけはゲートウェイでなくapi.anthropic.comを呼びます。この呼び出し自体は設定したHTTPプロキシに従うため、ここがブロックされて失敗しているなら、プロキシ側でapi.anthropic.comを許可することが対処になります。

なお、ここまでの表はスタンドアロンCLIが対象です。Claude Desktopアプリやブラウザのclaude.aiは、assets-proxy.anthropic.comや*.claudeusercontent.comのような追加のAnthropic CDNホストからアプリコードやアーティファクトを読み込みます。claude.aiだけ許可してこれらのホストをブロックすると、エラーではなく白紙のページが表示されます。

CLIが到達できるネットワーク上のホストを決めるこの一覧と、Claude Code自身がツール実行時にどのドメインへのアクセスを許可するかを決める権限モデルは役割が違います。後者のnetwork.allowedDomains・network.deniedDomains(権限ドキュメント側の表記ではsandbox.network.*)は、サンドボックス化されたコマンドの送信先を制御する仕組みです。Claude Codeセキュリティ・権限ガイドにまとめています。

設定が反映されているかを確認する方法

設定を変えたら、claude --debugで読み込まれた値を確認できます。デバッグ出力はターミナルではなく~/.claude/debug/<session-id>.txt(または--debug-fileで指定したパス)に書かれます。

claude --debug

出力にはCA証明書の追加読み込みやmTLS証明書・鍵の読み込みが行を分けて記録されます。

CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (/etc/ssl/certs/corp-ca.pem)
mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT
mTLS: Loaded client key from CLAUDE_CODE_CLIENT_KEY

対話セッション中であれば/statusでも確認できます。行ごとの意味は次のとおりです。

• Proxy: 有効なプロキシURLを表示する。パースできない値は無効として無視した旨を示す
• mTLS client cert / mTLS client key: ファイルを読み込めたときだけ表示される
• Additional CA cert(s): NODE_EXTRA_CA_CERTSのパスを表示するが、そのファイルが実際に読み込めたかまでは検査しない

パスを指定したのにエラーが解消しない場合は、まずファイルが存在してPEM形式で正しく書けているかを見直す必要があります。

シェルでexportした変数は起動時に一度だけ読み込まれます。実行中のセッションは、後からシェル環境を変更しても反映しません。「設定を変えたのに効かない」ときは、まずセッションを再起動して読み直させてから/statusで確認します。

バックグラウンドエージェントにプロキシ設定を届ける

対話セッションではプロキシが通るのに、バックグラウンドで動くエージェントだけ接続に失敗する場合、原因は環境変数の設定場所にあることが多いです。バックグラウンドエージェントを動かすスーパーバイザープロセスは全ターミナルで共有される単一のプロセスで、どのシェルが最初にそれをコールドスタートさせたかに応じてその環境を引き継ぎます。OSインストール型のスーパーバイザーに至っては、シェルの環境をまったく受け取りません。

つまりシェルのexportだけでプロキシ変数を設定していると、たまたま自分のシェルがスーパーバイザーを起動したときは効き、別のシェルやマシンで起動された場合はエラーも出さずに効かなくなります。対策は一つです。同じ変数を~/.claude/settings.jsonのenvブロックか管理設定に書きます。この記事で扱った変数はすべてこのブロックで設定できます。スタンドアロンCLIとターミナル起動セッションの範囲では、あらゆるマシン・あらゆるバックグラウンドセッションに確実に届く設定はこれだけです(Claude Desktopがプロバイダー接続を管理するセッションでの例外は前述のとおりです)。

settings.jsonのenvブロックを書き換えると、次に新しく起動するバックグラウンドセッションから設定が適用されます。スーパーバイザーは待機中のワーカープロセスを常に1つ用意しておき、ディスパッチのたびにそのワーカーへセッションの作業ディレクトリ・設定・資格情報を割り当てます。この割り当ての時点で最新の設定を読むため、既に動いているセッションをわざわざ終了させて起動し直す必要はありません。

ただし、稼働中のスーパーバイザー自体は起動したときの設定を保持し続けます。書き換えを確実に反映させたい場合は、次のコマンドでスーパーバイザーをいったん終了させます。

claude daemon stop --any

次にclaude agentsまたは--bgを実行すると、新しい設定を引き継いだスーパーバイザーが立ち上がります。OSインストール型のサービスとして動かしている場合は、--anyを付けないclaude daemon stopを使います。

{
  "env": {
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-ca.pem",
    "CLAUDE_CODE_CERT_STORE": "bundled,system",
    "CLAUDE_CODE_CLIENT_CERT": "/path/to/client-cert.pem",
    "CLAUDE_CODE_CLIENT_KEY": "/path/to/client-key.pem"
  }
}

症状別トラブルシューティング早見表

症状ごとの原因と対処は次のとおりです。

curl -I https://api.anthropic.comは通るのにClaude Codeだけ接続に失敗する場合、curlとClaude Codeが同じネットワークスタックを通っているとは限りません。OS固有の原因は次の「よくあるつまずき」にまとめました。

v2.1.199以降、証明書検証の失敗はリトライされなくなり、フルのリトライ回数を待たずに1回目の試行でこのエラーが出るようになりました。エラーが出るタイミングが早くなっただけで、原因そのものは以前と変わりません。

GitHub Issueには、ANTHROPIC_BASE_URL利用時にNO_PROXYが無視される、起動時のポリシー取得がプロキシ設定の適用より先に走る、といった報告も上がっています。いずれも未解決のIssueで、公式ドキュメントが保証している挙動ではありません。ここまでの設定を一通り見直しても解決しない場合は、同様の報告がないかIssueを検索する価値はあります。

よくあるつまずき

• Linux/WSLでは、/etc/resolv.confが到達不能なnameserverを指していないか確認します。WSLはホスト側の壊れたリゾルバをそのまま引き継ぐことがあります
• macOSでは、VPNクライアントの切断やアンインストール後に残留したutunインターフェースやルーティング規則が無いか確認します
• Docker Desktopなどのコンテナランタイムが、Claude Codeの送信トラフィックを横取りしていないか確認します
• WindowsのPowerShellで疎通確認する場合は、組み込みエイリアスのInvoke-WebRequestではなくcurl.exe -I https://api.anthropic.comのように明示します

よくある質問

SOCKSプロキシやNTLM/Kerberos認証は使えますか

どちらも公式サポート外です。Claude CodeのHTTPS_PROXY・HTTP_PROXYはHTTP(S)プロキシを前提にしており、プロキシ認証はURLにusername:password@を埋め込むBasic認証のみに対応します。SOCKSプロキシやNTLM/Kerberosのような高度な認証方式が必要な環境では、LLM Gatewayサービスを間に挟む構成が代替になります。

VS Code拡張でも同じ環境変数が使えますか

VS Code拡張はClaude CodeのCLI本体を内部で使うため、同じ環境変数に従います。ただし拡張機能の起動プロセスがどのシェル環境を継承するかは環境によって変わるため、確実に効かせたいなら~/.claude/settings.jsonのenvブロックに書く方法が安定します。

クラウドセッション(Claude Code on the webやRoutine)にも同じプロキシ設定が必要ですか

いいえ。クラウドセッションはサンドボックスVM内で動き、その出力ネットワークはセッション側の許可リストで制御されます。このためHTTP 403・x-deny-reason: host_not_allowedのようなエラーが出た場合、ローカルCLI側のプロキシ設定を直しても解決しません。さらにクラウドセッションは、設定ファイルのenvブロック由来の6キーを無視します。対象はCLAUDE_CODE_CLIENT_CERT・CLAUDE_CODE_CLIENT_KEY・CLAUDE_CODE_CLIENT_KEY_PASSPHRASE・NODE_EXTRA_CA_CERTS・NODE_TLS_REJECT_UNAUTHORIZED・CLAUDE_CODE_OAUTH_SCOPESです。無視した各キーはセッションのデバッグログに記録されます。この記事で紹介したsettings.jsonのenvブロックは、クラウドセッションのmTLS・証明書設定には効かないということです。

強制ランチャー経由での起動と何が違いますか

CLAUDE_CODE_PROCESS_WRAPPERやprocessWrapper設定は、バックグラウンドサービスや再起動を特定のランチャー経由に強制する仕組みで、目的はこの記事で扱ったプロキシ・証明書の疎通設定と異なります。ただし設定の届け方の規則は同じです。シェルのexportではバックグラウンドサービスに届かず、管理設定か~/.claude/settings.jsonで配ります。サンドボックスや資格情報の注入までネットワーク統制を厳格化したい場合の隣接トピックとして押さえておくとよいものです。

まとめ

企業プロキシ配下でClaude Codeを動かすうえで最初に揃えるべきはHTTPS_PROXYとNODE_EXTRA_CA_CERTSの2つです。ここまでで多くの環境は疎通します。mTLSやカスタムの証明書ストア制御が必要な環境ではさらに数変数を足すだけで足り、設定自体は難しくありません。

見落としやすいのはむしろ設定の置き場所です。シェルのexportはそのシェルが起動したプロセスにしか効かず、バックグラウンドエージェントには届かないことがあります。チーム展開や恒常運用を前提にするなら、最初から~/.claude/settings.jsonのenvブロックに書く方が、後からの原因調査を減らせます。

ネットワーク周りの疎通が済んだら、モデル選びや権限設計まで含めたClaude Code全体の使い方はClaude Code完全ガイドにまとめています。