httpProxyPortとsocksProxyPortで社内検査プロキシを通す設定
sandbox.network.httpProxyPort/socksProxyPortは、サンドボックスの通信を社内の検査プロキシへ差し替える設定です。組み込みプロキシやtlsTerminateとの使い分けをまとめます。
Claude Codeのサンドボックスは、既定では組み込みのプロキシがサンドボックス化したコマンドの通信を仲介します。sandbox.network.httpProxyPortとsandbox.network.socksProxyPortを設定すると、この仲介役を社内で運用する独自プロキシに置き換えられます。HTTPS通信を復号して検査する、独自のフィルタリングルールを通す、通信をすべてログに残す、といった用途で使う設定です。似た名前のsandbox.network.tlsTerminateとは役割が異なり、両者の使い分けはsandbox.network.tlsTerminateの記事にまとめています。
httpProxyPort・socksProxyPortとは
sandbox.network.httpProxyPortとsandbox.network.socksProxyPortは、サンドボックス化したコマンドの通信を、社内独自のプロキシへ丸ごと差し替える設定です。サンドボックス化されたBashコマンドの通信は、サンドボックスの外で動く1つのプロキシサーバーを必ず経由します。設定を何もしなければ、このプロキシはClaude Code自身が起動したものです。ホスト名だけを見てドメイン許可リストと突き合わせ、許可・拒否を判定します。
高度なネットワークセキュリティを求める組織向けに、公式ドキュメントは独自プロキシの実装によって次の4つができるとしています。
- HTTPS通信を復号して中身を検査する
- 組織独自のフィルタリングルールを適用する
- すべてのネットワークリクエストをログに残す
- 既存のセキュリティ基盤と統合する
社内ネットワークの出口にすでにTLS検査型のプロキシ製品を置いている組織であれば、Claude Codeのサンドボックスだけを例外にせず、同じ監査経路に載せられます。
設定方法
設定はsettings.jsonのsandbox.networkブロックに2つのポート番号を書くだけです。
{
"sandbox": {
"network": {
"httpProxyPort": 8080,
"socksProxyPort": 8081
}
}
}2つのキーは独立しています。httpProxyPortだけを設定すると、HTTPトラフィックは指定したポートの独自プロキシに向きますが、SOCKSトラフィックはClaude Code自身のプロキシが引き続き処理します。両方のプロトコルを独自プロキシに寄せたい場合は、2つとも設定してください。
どちらのキーも設定値の型は数値で、公式リファレンスは「ローカルのTCPポート」と説明しています。待ち受けるプロキシのホスト名やIPアドレスを直接指定するキーはありません。社内ネットワークの出口にある検査プロキシをここに使いたい場合は、そのプロキシへ転送するプロキシやフォワーダーを手元で立て、httpProxyPort・socksProxyPortにはそのローカルの待受ポートを書きます。socksProxyPortが受け付けるのはSOCKS5プロトコルで、独自プロキシ側もSOCKS5に対応している必要があります。
設定が実際に効いているかどうかは、指定したポートで待ち受ける独自プロキシ側のアクセスログを見ると確認しやすくなります。サンドボックス化したコマンドが動くたびに、そのプロキシへの接続が記録されているかを見る方法です。
スコープは「Any file」、つまりユーザー設定・プロジェクト設定・ローカル設定・管理設定のどこに書いても読み込まれます。mask資格情報置換に使うtlsTerminateがUser設定かManaged設定からしか読まれず、リポジトリの.claude/settings.jsonでは無視されるのとは対照的です。プロジェクト単位の設定でも検査プロキシへ切り替えられる分、社内標準として配りたい場合は管理設定に置くほうが、開発者ごとの設定ばらつきを避けられます。
組み込みプロキシ・tlsTerminateとの違い
サンドボックスのネットワーク関連キーは名前が似ていて役割を混同しがちです。スコープも設定によって異なるため、目的とあわせて並べると次のようになります。
| 設定 | 何をするか | スコープ |
|---|---|---|
| 既定(未設定) | 何をするかClaude Code自身のプロキシがホスト名だけを見て許可・拒否を判定 | スコープ― |
httpProxyPort / socksProxyPort | 何をするか通信の中継先を組織独自のプロキシに丸ごと差し替える | スコープAny file |
tlsTerminate | 何をするか組み込みプロキシ自身にTLSを終端させmask置換を動かす | スコープUser or managed |
企業プロキシ配下でClaude Code自身のAPIリクエスト(api.anthropic.com宛の通信など)を通す設定は、この記事の対象と別軸です。HTTPS_PROXY・HTTP_PROXY・NO_PROXYという環境変数を使う経路で、ドメイン許可リストの判定を済ませたうえで上流プロキシへトンネリングします。手順はClaude Codeプロキシ設定にまとめています。httpProxyPortが差し替えるのは、あくまでサンドボックス化したコマンドの出口プロキシで、Claude Code自身のAPI通信の経路には影響しません。
社内の検査プロキシがすでにHTTPS_PROXY経由の通信を受けている場合でも、httpProxyPortは別に設定する必要があります。両方を同じ検査プロキシに向けるには2つとも書きます。片方だけだと、もう一方の経路が検査から漏れます。
TLS検査を実際に機能させるための前提
ポートを差し替えただけでは、通信内容の検査は自動的には始まりません。既定の組み込みプロキシは、TLSを終端も検査もせずホスト名だけで許可・拒否を判定します。github.comのような広いドメインを許可リストに入れている場合、サンドボックス内のコードがドメインフロンティングのような手法で許可リスト外のホストに到達する余地が理論上残ります。
公式ドキュメントは、より強い保証が必要な脅威モデルでは「カスタムプロキシ」構成のほうが妥当だとしています。TLSを終端して中身を検査し、そのCA証明書をサンドボックス内にインストールする構成です。httpProxyPort・socksProxyPortは、この構成の入り口にあたる設定です。ポートを向けた先の独自プロキシ自身がTLSを終端し、発行したCA証明書をサンドボックス内の各ツールに信頼させて初めて、検査が機能します。ポートを差し替えるだけでCA証明書のインストールを済ませていない場合、検査プロキシを経由しているという安心感だけが先に立つ状態になります。独自プロキシがどれだけ精密にTLSを検査していても、許可するドメインの選び方自体は運用側の責任です。公式ドキュメントも、ポリシーに許可するドメインが信頼できるものだけになっているかを確認する責任は利用者側にあると明記しています。
公式ドキュメントは、TLSを意識したより強いネットワーク分離を「活発に開発が進んでいる領域」と位置付けています。ドメインの許可判定が依然としてクライアントが名乗ったホスト名ベースで行われるという前提を踏まえたうえで、検査プロキシの導入を検討する必要があります。
よくあるつまずき
- Go製CLI: MITMプロキシと独自CAの組み合わせで
httpProxyPortを使うと、macOSではgh・gcloud・terraformのようなGo製CLIがSeatbelt配下のTLS検証に失敗することがあります。対処はsandbox.enableWeakerNetworkIsolationをtrueにすることで、macOSのシステムTLS信頼サービスへの到達を許可します。この設定はv2.1.69で追加されましたが、システム信頼サービス経由の新しいデータ持ち出し経路を開くトレードオフを伴います。MITMプロキシを使わない既定の組み込みプロキシ環境でも同じくGo製CLIがTLS検証に失敗することがありますが、その場合の対処は該当コマンドをexcludedCommandsに加えることです。httpProxyPortと独自CAを組み合わせているときに限り、enableWeakerNetworkIsolation側の対処に切り替えます。 - ポートの片方だけの設定:
httpProxyPortだけ設定してSOCKSトラフィックの差し替えを忘れると、その分の通信だけがClaude Code自身のプロキシに残ります。検査対象を漏らさないよう、社内プロキシがHTTP・SOCKS両方を受けられるか事前に確認してください。 - socatPathとの混同: LinuxとWSL2では、サンドボックスは
bubblewrapでファイルシステムを分離し、通信をプロキシへ中継する役目にsocatを使います。socatバイナリの場所を管理設定で固定するsandbox.socatPathは、httpProxyPortとは別の設定です。前者は中継の実装、後者は中継先の差し替えを扱います。socatPathはスコープがManagedで、PATHの外に置いたsocatバイナリを使わせたい場合に設定します。詳しくはsandbox.socatPathの記事にまとめています。 - 分離範囲の思い込み: サンドボックスが分離するのはBashサブプロセスの通信だけです。Read・Edit・Writeといった組み込みファイルツールは権限システムを直接使い、サンドボックスのプロキシを経由しません。検査プロキシへ切り替えても、これらのツールの通信までは検査対象になりません。全体の権限モデルはClaude Codeセキュリティ・権限ガイドにまとめています。
- サブエージェントへの適用漏れの心配は不要: サブエージェントは親セッションと同じプロセスで動き、同じサンドボックス設定を使います。親セッションで
httpProxyPort・socksProxyPortを設定していれば、サブエージェント内で実行されるBashコマンドの通信も同じ独自プロキシへ差し替わります。サブエージェントだけ検査対象から漏れるという心配は要りません。 - ドメイン許可リストは別枠で管理ロックできる:
httpProxyPort・socksProxyPort自体はAny fileスコープで、どの設定ファイルに書いても読み込まれます。開発者側の設定でドメイン許可リストが広がってしまうのを防ぎたい場合は、httpProxyPortとは別にsandbox.network.allowManagedDomainsOnlyを管理設定で有効にします。許可ドメインの判定を管理設定の値だけに固定する設定で、通信の中継先を差し替えるhttpProxyPortとは役割が異なります。両方を組み合わせれば、通信の中身はカスタムプロキシで検査しつつ、宛先ドメインの範囲は管理設定だけが決められる状態にできます。
まとめ
sandbox.network.httpProxyPortとsandbox.network.socksProxyPortは、サンドボックス化したコマンドの通信を社内の検査プロキシへ丸ごと差し替えるための設定です。導入の順番は3段階が目安です。まずHTTPS_PROXYで外側の疎通を確認し、次にhttpProxyPort・socksProxyPortでサンドボックス内部の通信を同じ検査プロキシへ寄せます。mask資格情報置換が必要になった段階でtlsTerminateを足します。実際にTLSを検査できるかどうかは、差し替えた先の独自プロキシがTLSを終端しCA証明書をサンドボックス内へ配布しているかにかかっており、ポートの差し替えだけでは検査は始まりません。