Claude Codeのプロキシ設定 — settings.jsonのenv・CA証明書・許可ドメイン

Claude Codeのプロキシ設定は、HTTPS_PROXYを設定し、社内CA証明書をNODE_EXTRA_CA_CERTSで登録すれば、多くの企業ネットワークで疎通します。設定は~/.claude/settings.jsonのenvブロックに書くと、シェルを選ばずバックグラウンドにも届きます。ただし証明書を登録する場所やmTLS、バックグラウンドエージェントへの設定の届け方など、通しで読まないと拾いにくい分岐点がいくつかあります。環境変数の優先順位から証明書・mTLSの設定、ファイアウォールで許可すべきドメイン一覧、症状別のトラブルシューティングまでを扱います。なお、通信を完全に遮断したオフライン・エアギャップ環境ではプロキシ設定に関わらず動作しません。可否の判定基準はClaude Codeはオフライン環境で使えるかにまとめています。

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

企業ネットワーク配下でClaude Codeが動かないとき、症状は大きく3つに分かれます。この切り分けが最初の一歩です。

Claude Codeは起動時にほとんどの設定値を検証しません。プロキシURLのパースだけは例外で、http://のようなスキームが欠けた値を渡すと起動時点でエラーを出して停止します。それ以外の設定ミス(証明書パスの誤りなど)は、後続のリクエストが実際に失敗するまで表面化しません。HIPAA構成の組織で許可するホストはHIPAA対応Enterpriseの端末準備にあります。

前提として、この記事はスタンドアロン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サービスを間に挟む構成を使う方法があります。Claude Desktopで同じ環境の症状が出るときの切り分けは、Claude DesktopでAuthentication failedが繰り返される原因にあります。

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

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

TLSを検査する企業プロキシやセキュリティアプライアンスを挟んだ環境では、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自身がプロキシに対して身元を証明する」ための設定です。両方が必要な環境では、どちらか一方だけ設定しても疎通しません。サンドボックス内通信のTLS終端はsandbox.network.tlsTerminateが別途あります。証明書ローテーション時の再読み込みルールはClaude CodeのmTLSクライアント証明書認証にまとめています。検査プロキシ配下で圧縮済みの本文だけが失敗するときは、gzip圧縮を止める変数の解説が手がかりになります。

証明書と鍵は起動時だけでなく、設定を適用するたび(セッション中の設定変更を含む)に再読み込みされます。同じパスにファイルを置き換えるだけでローテーションでき、証明書更新のたびに再起動する必要はありません。ファイルの変更を監視しているわけではなく、接続エラーの後の再試行か、設定の適用後の次のリクエストで新しい組を提示します。v2.1.232より前は、接続エラーでは再読み込みしませんでした。

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

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

npmまたはbunでインストールする場合は、上記に加えてパッケージレジストリのregistry.npmjs.org(または社内ミラー)も必要です。ネイティブインストールでも、npm配布のプラグインやnpxで起動するMCPサーバーを使うならregistry.npmjs.orgに届く必要があります。

表に載せていない用途別のホストもあります。github.comはGitHub上のプラグインマーケットプレイスをcloneするときに使います。*.frame.claudeusercontent.comはArtifactツールが使える場合にファイルを読む宛先です。enableArtifactをfalseにするかCLAUDE_CODE_DISABLE_ARTIFACT=1で外せます。

Gerritの変更情報の照会も用途別のホストの一つです。HEADのChange-Idに対応するopenな変更があるかを調べるもので、宛先は*-review.googlesource.com、匿名で呼びます。発生するのは、Claude DesktopのCodeタブでoriginがgooglesource.comの信頼済みチェックアウトを開いたときだけです。他のセッション種別では起きず、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICで止められます。

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 Desktopでプロキシを設定するときの注意

セッション種別ごとにどの設定ファイルが読まれるかは、冒頭の前提の段落にまとめています。ここでは、そこに載せていないDesktop固有の2点を補います。

• Linuxのリモートマシンへ接続するSSHセッション: そのマシンの~/.claude/settings.jsonのenvに書きます。~/.profileなどでexport済みでも、settingsへの記載が要ります
• CA証明書の指定: SSL_CERT_FILEはsettings.jsonでは信頼されません。社内CAはNODE_EXTRA_CA_CERTSで指定します

claude.aiをブラウザで使う場合の許可ホストは、前述のドメイン一覧のうちDesktopとclaude.ai向けの段落にまとめました。

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

設定を変えたら、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がプロバイダー接続を管理するセッションでの例外は前述のとおりです)。

バックグラウンドセッションは、起動したディレクトリの設定を、そこでclaudeを起動したときと同じように読み込みます。

一方、稼働中のスーパーバイザー自体は、起動したときの構成を保持し続けます。スーパーバイザーが引き継ぐ環境を変えたときは、次の3ステップで読み直させます。

OSインストール型のサービスとして動かしている場合は、--anyを付けないclaude daemon stopを使うというのが公式ドキュメントの案内です。

手元のv2.1.286でclaude daemon --helpを実行すると、次の出力でした。ホームのパスは~の表記のままです。

Service lifecycle:
  run [json-path]   Run the supervisor in the foreground (default when piped)
  status            Show daemon pid, version, uptime
  logs              Tail the daemon log (Ctrl-C to stop)
  uninstall         Remove the background service (launchctl/systemd)
  stop              Shut down the supervisor and terminate background sessions
                      --any           also stop a transient (non-service) daemon
                      --keep-workers  leave detached sessions running
 
  Service install is disabled in this version — the daemon runs on demand
  and exits when the last client disconnects.

注目したいのは最後の2行です。v2.1.286ではサービスとしてのインストールが無効で、スーパーバイザーは必要なときに起動し、最後のクライアントが切れると終了すると書かれています。このバージョンで起動するのは、インストール済みサービスではなくオンデマンドのスーパーバイザーです。これを止めるときは--anyを付けて、その意思を示します。ログは~/.claude/daemon.logが既定です。claude daemon statusでpidとバージョン、稼働時間を確認でき、claude daemon logsでログを追えます。--keep-workersを付けると、切り離されたセッションを止めずに残せます。

{
  "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"
  }
}

プロキシが応答を止めたときのタイムアウトと調整変数

プロキシが応答の途中で無言になる環境では、Claude Code側の監視タイマーが先に切れることがあります。Claude Codeはストリーミング応答が静かになったとき、接続が死んだと判断して再試行するための監視を4種類持っています。

直接のAnthropic APIでは、最初のバイトが届くまでの期限と、バイト単位の無通信監視がどちらも既定180秒です。イベント単位の監視は全プロバイダーで300秒になります。HTTPSプロキシを通していても、直接のAnthropic APIと同じ扱いです。ANTHROPIC_BASE_URLでゲートウェイへ向けた場合は、最初のバイトの期限は動きません。

調整用の変数は次の4つです。

• CLAUDE_STREAM_IDLE_TIMEOUT_MS: イベント単位とバイト単位の両方の期限を決める。5分未満の値は5分に引き上げられ、バイト単位は上限30分
• CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS: バイト単位の期限だけを10秒〜30分の範囲で決める
• CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS: 最初のバイトまでの期限を直接決める
• CLAUDE_ENABLE_BYTE_WATCHDOG: 0でバイト単位の監視と最初のバイトの期限をまとめて切る

これらを伸ばす前に、プロキシ側のアイドル切断設定を確認するという順序もあります。

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

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

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のように明示します

よくある質問

クラウドセッション(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で配ります。サンドボックスや資格情報の注入までネットワーク統制を厳格化したい場合の隣接トピックとして押さえておくとよいものです。

まとめ

最初に揃える変数はHTTPS_PROXYとNODE_EXTRA_CA_CERTSの2つで、mTLSが必要な環境でだけ数変数が増えます。

見落としやすいのは設定の置き場所で、チーム展開や恒常運用なら最初から~/.claude/settings.jsonのenvブロックに書く選択肢があります。

ネットワーク周りの疎通が済んだら、モデル選びや権限設計まで含めたClaude Code全体についてはClaude Codeとは — できること・料金・使い方にまとめています。