Claude Codeのgzip圧縮がプロキシで壊れるときの対処法

Claude Codeは api.anthropic.com に送るリクエスト本文を、条件が合えばgzipで圧縮します。TLS検査プロキシがこの圧縮済みの本文を正しく扱えない環境では、CLAUDE_CODE_GZIP_REQUEST_BODIES=0 で圧縮だけを止められます。証明書を信頼させる設定とは別の、もう一段手前のスイッチです。

CLAUDE_CODE_GZIP_REQUEST_BODIESとは何を切り替える変数か

CLAUDE_CODE_GZIP_REQUEST_BODIES は、Claude Codeがリクエスト本文をgzip圧縮して送るかどうかを決める環境変数です。値に 0 を入れると圧縮をやめます。

対象になる通信は3種類です。

• Claude APIへのリクエスト
• テレメトリー
• Artifactの公開リクエスト

宛先はいずれも api.anthropic.com です。圧縮の対象は「大きなリクエスト本文」で、短いやり取りは対象外のようです。どこからが「大きい」のかという閾値は、env-varsの説明にも載っていません。

圧縮が自動で外れる条件と、外れない条件

既定では、Claude Codeが自分で圧縮の要否を判定します。判定は次のとおりです。

つまり、プロキシを環境変数で指定していれば、この変数を触る必要はほぼありません。問題になるのは、Claude Codeが「プロキシ配下にいる」と検出できない構成です。

該当する例は、Claude Codeが検出できないTLS検査プロキシです。Claude Code側には直接接続に見えるのに、経路の途中の機器が暗号化を解いて中身を検査している構成です。

この条件を並べると、どの環境が危ないかが見えてきます。以下は上の判定表からの推論です。

• HTTPS_PROXY を設定していない
• クライアント証明書を設定していない
• NODE_EXTRA_CA_CERTS も設定していない
• それでも途中にTLS検査機器がある

たとえば、検査機器のルート証明書がOSの信頼ストアに配布済みの端末です。ネットワークの設定ファイルや証明書を追加で触らなくても通信できてしまうため、Claude Codeからはプロキシの存在が見えません。ネットワーク設定のページも、ルート証明書がOSの信頼ストアにあれば検査プロキシは追加設定なしで動くと説明しています(OSストアを読むには、ネイティブインストーラー版か、npm版ならNode 22.15以降が必要です)。

そのうえで、検査機器が圧縮済みの本文を正しく処理できないと、リクエストだけが失敗します。

圧縮を止める設定

シェルで一度だけ試すなら、起動時に変数を付けます。

CLAUDE_CODE_GZIP_REQUEST_BODIES=0 claude

常用するなら、~/.claude/settings.json の env ブロックに書く方法があります。ネットワーク設定のページは、専用のスキーマキーを持たない CLAUDE_CODE_CERT_STORE をこの env ブロックで指定できると案内しています。同じ書き方が使える、という見立てです。

{
  "env": {
    "CLAUDE_CODE_GZIP_REQUEST_BODIES": "0"
  }
}

設定できる値は 0 だけで、圧縮を強制的に有効にする値はありません。自動判定に戻すには、変数を外します。

組織全体に配るときの置き場所と、設定ファイルごとの優先順位は、Claude Codeプロキシ設定で扱っています。

証明書エラーとは別の問題として切り分ける

TLS検査まわりの不具合は、大きく2系統あります。症状が違うので、先にどちらかを見分けます。

証明書側のエラーは、UNABLE_TO_GET_ISSUER_CERT_LOCALLY や SELF_SIGNED_CERT_IN_CHAIN といったコード付きで表示されます。メッセージ自体が NODE_EXTRA_CA_CERTS の設定を促します。この系統なら圧縮の変数は関係ありません。

一方、圧縮の問題にはエラーメッセージの例がありません。切り分けは、症状と試行結果から組み立てることになります。

切り分けの手順

次の順で進めると、原因を絞れます。

手順2は、圧縮の対象が大きな本文であることから立てた仮説です。決め手は手順3の再現です。

設定が読み込まれているかは、claude --debug のログで確認できます。NODE_EXTRA_CA_CERTS やmTLSの読み込みはログで追えます。圧縮の有効・無効は、ログの例にありません。

圧縮を止める前後で変わること

圧縮を止めると、送信するバイト数は増えます。帯域が細い回線や、従量課金の閉域網では、この点が効く可能性があります。影響の大きさを示す数値はないので、環境ごとに測るほかありません。

変更履歴のv2.1.281には、Artifact公開が絡む項目があります。低速な回線でのArtifact公開を改善し、大きなページのアップロードを圧縮して送る、というものです。圧縮対象にArtifactの公開が含まれるため、検査プロキシ配下でArtifactの公開だけが失敗する場合も、疑う対象に入ります。

また、この変数が触るのはリクエスト本文の圧縮だけです。許可ドメインの設定や、ファイアウォールの開放は別の話です。通信自体がブロックされている場合は、devcontainerの外向き通信を絞る構成のように、許可リストの側を見直します。

自動判定に効くプロキシ変数の指定

「プロキシ経由なら圧縮しない」という判定は、プロキシ変数が指定されているかに左右されます。Claude Codeが読むのは HTTPS_PROXY と HTTP_PROXY で、小文字の変数も使えます。https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY の順で、最初に設定されたものが採用されます。

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

NO_PROXY は空白区切りでもカンマ区切りでも書け、* を入れると全リクエストがプロキシを迂回します。ここに載せた宛先はプロキシを通りません。また、localhost や 127.0.0.0/8 宛てのWebSocket接続は、NO_PROXY に書かなくてもプロキシへ送られません。NO_PROXY に api.anthropic.com を入れたときの圧縮の扱いは、claude --debug で有効なプロキシURLを見ながら実機で確かめます。プロキシURLが解釈できない値だと、起動時にエラーで止まります。

対象はapi.anthropic.com宛ての通信だけ

この変数が触るのは、api.anthropic.com に送るリクエスト本文です。ANTHROPIC_BASE_URL でLLMゲートウェイへ向けている構成や、Bedrock・Vertexのエンドポイントを ANTHROPIC_BEDROCK_BASE_URL、ANTHROPIC_VERTEX_BASE_URL で差し替えている構成では、モデルへのリクエストの宛先が api.anthropic.com ではありません。モデルへのリクエストがゲートウェイ経由でも、api.anthropic.com に直接送られるテレメトリーやArtifact公開のリクエストは圧縮の対象に残るため、モデルの応答が通っていてもこの2つだけが失敗することがあります。ゲートウェイ配下で圧縮を疑うときは、ゲートウェイ側のログとあわせて確かめます。

ゲートウェイ構成でも、api.anthropic.com への通信は残ります。たとえば高速モードの可用性チェックは、ゲートウェイを設定していても api.anthropic.com を呼び、設定済みのHTTPプロキシを通ります。ネットワーク設定のページは、ブロックが原因ならプロキシ側で api.anthropic.com を許可するのが解決策だと案内しています。ただし、ゲートウェイ発行の資格情報をAnthropicが拒否した場合も同じ接続エラーになり、こちらは許可リストを足しても直りません。検査機器の側でできる対処も、同じ方向です。api.anthropic.com 宛てを検査の対象から外すか、圧縮された本文を許可するかを、機器の管理者に相談できます。

変数を足す前に確認したいこと

圧縮を切る前に、次の点を確認すると遠回りを避けられます。

• 検査機器のルート証明書が、OSの信頼ストアまたは NODE_EXTRA_CA_CERTS で渡されているか。CLAUDE_CODE_CERT_STORE の既定は bundled,system(同梱のMozilla CA群とOSの信頼ストアの両方)で、bundled だけに絞っていると、OSに配布済みのルート証明書は読まれません
• プロキシの指定が必要な環境なら、HTTPS_PROXY を明示しているか。明示すれば、自動判定で圧縮が外れる
• mTLSが必要な環境なら、クライアント証明書も設定済みか。設定すれば圧縮は外れる。詳しくはmTLSクライアント証明書の設定にまとめています
• 検査機器の側で、圧縮された本文を許可する設定にできないか

プロキシを明示するのは、検査機器の側から変更できない端末でも実行できる対策です。ただ、明示するとサンドボックスなど他の経路の設定にも影響します。サンドボックス側のポート指定はhttpProxyPortとsocksProxyPortの記事に分けてあります。

いずれも決め手にならないときに、CLAUDE_CODE_GZIP_REQUEST_BODIES=0 が最終手段として残ります。

よくある質問

全員に 0 を配ってよいか

直接接続の端末では、圧縮のほうが送信量を減らせます。検査機器の配下にある端末にだけ、チーム設定やユーザー設定で 0 を入れる運用が現実的です。

0 を入れたら証明書エラーも消えるか

消えません。証明書エラーは信頼の問題で、圧縮とは別の層で起きます。

まとめ

CLAUDE_CODE_GZIP_REQUEST_BODIES=0 が効くのは、Claude Codeが検出できないTLS検査機器が、圧縮済みの本文だけを正しく扱えない構成です。証明書エラーが出ているなら、先に信頼の設定を直します。次に 0 を付けて再現し、その1行で通るかどうかを判断の決め手にします。