中小DXラボ のツール

Claude Code をプロキシ・社内証明書の環境で使う設定(環境変数と確認方法)

公開: ・ 中小DXラボ ・ 内容は執筆時点(2026年10月)の公式ドキュメントなどの出典にもとづきます(各節の末尾に出典を記載)

結論

  • Claude Code(Anthropic 社が提供する、ターミナルで動く AI コーディングエージェント)は、公式ドキュメントによると、プロキシ・独自の認証局(CA)・mTLS を環境変数で設定します。起動前に設定し、settings.json でも指定できます。
  • 証明書は既定で、同梱の Mozilla CA と OS の証明書ストアの両方を信頼します。TLS 検査プロキシは、ルート証明書が OS に入っていて実行環境が読めれば、追加設定なしで動くとされています。
  • SOCKS プロキシは非対応です。設定の誤りは後から接続エラーで気づくことが多いため、claude --debug と /status で読み込みを確認します。

何ができるか:環境変数で3つの設定を行う

この記事は公式ドキュメントの「Enterprise network configuration」を整理したもので、執筆時点(2026年10月)の記載に基づきます。自分で試した結果ではありません。

公式ドキュメントでは、社内プロキシ経由の通信、独自 CA(社内で証明書を発行する認証局)の信頼、クライアント証明書で認証する mTLS(相互 TLS 認証)を、環境変数で設定すると説明しています。

環境変数は起動前に設定します。シェルで export した値は起動時に一度だけ読まれるため、動いているセッションは後からの変更を拾いません。

出典: Enterprise network configuration

プロキシの設定

標準的なプロキシ環境変数に対応しています。HTTPS プロキシが推奨で、HTTPS が使えない場合に HTTP プロキシを指定します。

# HTTPS proxy (recommended)
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP proxy (if HTTPS not available)
export HTTP_PROXY=http://proxy.example.com:8080

プロキシを通さない宛先は NO_PROXY で指定します。スペース区切りとカンマ区切りのどちらも使えます。

# Bypass proxy for specific requests - comma-separated format
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"

小文字の変数も使え、https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY の順で、最初に設定されているものが使われます。

認証が必要なプロキシ

Basic 認証が必要な場合は、プロキシの URL に認証情報を含めます。

export HTTPS_PROXY=http://username:password@proxy.example.com:8080

公式ドキュメントは、スクリプトにパスワードを直接書かず、環境変数や安全な資格情報の保管を使うよう注意しています。NTLM や Kerberos など高度な認証が必要なプロキシについては、その認証方式に対応した LLM Gateway サービスの利用を検討するとしています。

出典: Enterprise network configuration

証明書の設定:OS ストア、独自 CA、mTLS

公式ドキュメントによると、既定では同梱の Mozilla CA 証明書と OS の証明書ストアの両方を信頼します。OS ストアの読み取りには tls.getCACertificates を持つ実行環境が必要です。ネイティブインストーラー版は常に対応し、npm インストールでは Node 22.15 以上が条件です。それより古い Node では、同梱セットと NODE_EXTRA_CA_CERTS だけが使われます。

TLS 検査プロキシは、ルート証明書が OS の信頼ストアに入っていて実行環境が読めれば、追加設定なしで動きます。そのプロキシが gzip 圧縮されたリクエストボディを正しく扱えない場合は、CLAUDE_CODE_GZIP_REQUEST_BODIES=0 で圧縮を止められます。

独自 CA を直接指定する

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

信頼元は CLAUDE_CODE_CERT_STORE でも絞れます。カンマ区切りで bundled(同梱の Mozilla CA)と system(OS)を指定し、既定は bundled,system です。この変数には settings.json 専用のキーがないため、~/.claude/settings.json の env ブロックか、プロセスの環境で設定します。

mTLS(クライアント証明書)

# Client certificate for authentication
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem

# Client private key
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

# Optional: Passphrase for encrypted private key
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

証明書を更新するときは、同じパスのファイルを置き換えます。接続リセットや TLS ハンドシェイクエラーでリクエストが失敗すると、両ファイルを再読込して再試行するため、実行中のセッションでも再起動なしで反映されます。v2.1.232 より前は、接続エラーでは再読込されませんでした。ゲートウェイが HTTP エラーで応答する場合は再読込されず、設定の適用時か再起動で反映されます。期限が切れる前に置き換えてください。

出典: Enterprise network configuration

設定が読み込まれたかを確認する

公式ドキュメントによると、Claude Code は設定の多くを読み込み時に検証しないため、プロキシのアドレスや証明書のパスの誤りは、後続のリクエストで接続エラーや証明書エラーとして表れます。起動時に検査するのはプロキシ URL だけで、http:// が抜けているなど解釈できない値は、修正すべき変数名を示すエラーで起動を止めます。

リクエストを送る前に確認するには、デバッグログ付きで起動します。

claude --debug

出力先はターミナルではなく ~/.claude/debug/<session-id>.txt で、--debug-file <path> で変更できます。ログに次のような行があれば、各ファイルを読み込めています。読み込めない場合は、理由つきの Failed to read か Failed to load の行が出ます。

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 でも確認できます。mTLS の行は、ファイルを読み込めたときだけ表示されます。Additional CA cert(s) の行はパスを表示するだけで読み込みは確認しないため、こちらはデバッグログで確かめます。

出典: Enterprise network configuration

配る前の注意:バックグラウンドエージェントと許可リスト

claude agents、--bg、/background のバックグラウンドエージェントは、ユーザーごとのスーパーバイザープロセスが動かします。このプロセスは、最初に起動したシェルの環境を引き継ぎます。プロキシや CA の変数をシェルだけで export すると、届くかどうかが起動したシェル次第になります。公式ドキュメントは、~/.claude/settings.json か managed settings の env ブロックに書くよう勧めています。すべてのバックグラウンドセッションに届くのは、設定ファイルだけだとしています。

プロキシやファイアウォールの許可リストには、公式ドキュメントの一覧にあるホストを登録します。たとえば api.anthropic.com は Claude API のリクエスト用、claude.ai は claude.ai アカウントの認証用、platform.claude.com は Console アカウントの認証用です。Amazon Bedrock などのプロバイダー経由では、モデル通信と認証の宛先がプロバイダー側になります。ただし WebFetch は、skipWebFetchPreflight: true を設定しない限り api.anthropic.com を呼びます。ホストの全一覧は、公式ドキュメントで確認してください。

出典: Enterprise network configuration

よくある質問

SOCKS プロキシ経由で使えますか。

公式ドキュメントでは、Claude Code は SOCKS プロキシに対応していないとされています。HTTPS プロキシ(推奨)か HTTP プロキシを使います。

出典: Enterprise network configuration

社内の TLS 検査プロキシの証明書は、どう信頼させますか。

公式ドキュメントによると、プロキシのルート証明書が OS の信頼ストアに入っていて、実行環境が読める場合は追加設定が不要です。npm インストールでは Node 22.15 以上が条件です。直接指定する場合は NODE_EXTRA_CA_CERTS に証明書ファイルのパスを設定します。

出典: Enterprise network configuration

プロキシや証明書の設定が効いているかは、どう確認しますか。

claude --debug で起動してログに読み込みの行が出ているかを見るか、対話セッションで /status を実行します。CA のパスは /status では読み込みまで確認できないため、デバッグログで確かめます。

出典: Enterprise network configuration

関連する無料ツール

Claude Code つまずき早見表: Windows で Claude Code を使うときに起きやすい症状を、原因と対処で引ける早見表です。

参考(執筆時点)

この記事は、上の出典の内容を中小DXラボが要約・再構成したものです。仕様は変わることがあります。社内で使う・配る前に、公式ドキュメントで最新の情報を確認してください。