Claude CodeのmTLSクライアント証明書認証 — 設定とローテーションの落とし穴

クライアント証明書での相互認証(mTLS)を要求するプロキシ配下では、HTTPS_PROXYとCA証明書の設定だけでは疎通しません。Claude Code自身がプロキシに対して身元を証明する必要があり、これを担うのがCLAUDE_CODE_CLIENT_CERT・CLAUDE_CODE_CLIENT_KEY(秘密鍵が暗号化されている場合はCLAUDE_CODE_CLIENT_KEY_PASSPHRASEも)です。この記事はmTLS認証にフォーカスし、証明書をローテーションしたときにClaude Codeがいつ新しい証明書を読み直すか、その再読み込みを止めるCLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTIONの使いどころを中心に扱います。プロキシ環境変数や許可すべきドメイン一覧など、社内ネットワーク全体の設定はClaude Codeプロキシ設定にまとまっています。

Claude CodeのmTLSクライアント証明書認証とは

mTLS(相互TLS)は、サーバーだけでなくクライアント側も証明書で身元を証明する認証方式です。Claude Codeがプロキシ配下で動く社内網の一部では、プロキシがこのクライアント証明書を要求し、証明書を提示できない接続をそもそも受け付けません。この場合に必要なのが、証明書ファイルと秘密鍵ファイルのパスをClaude Codeに渡す設定です。

これはサーバー証明書の検証とは別の話です。プロキシ自身が発行した証明書をClaude Codeが信頼できずに起きるSSL証明書エラーはNODE_EXTRA_CA_CERTSで対処しますが、mTLSはその逆方向、つまりClaude Code側が身元を証明する設定です。両方を要求する環境では、どちらか一方だけ設定しても疎通しません。

3つの環境変数でクライアント証明書を設定する

必須の2変数はCLAUDE_CODE_CLIENT_CERT(証明書ファイルのパス)とCLAUDE_CODE_CLIENT_KEY(秘密鍵ファイルのパス)です。秘密鍵が暗号化されている場合は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"

ここまでの3変数とは別に、信頼するCA証明書の組み合わせ(サーバー証明書の検証側)を制御したい場合はCLAUDE_CODE_CERT_STOREにカンマ区切りで指定します。クライアント証明書の身元証明には関わりません。認識される値はbundled(Claude Codeに同梱されたMozillaのCA証明書セット)とsystem(OSの証明書ストア)で、既定はbundled,systemです。バンドル証明書だけを信頼させたい場合は次のように設定します。

export CLAUDE_CODE_CERT_STORE=bundled

CLAUDE_CODE_CERT_STOREには専用のsettings.jsonスキーマ項目がなく、envブロックか環境変数で設定します。OSの証明書ストアを読むにはtls.getCACertificatesというランタイム機能が必要で、ネイティブインストーラなら常に対応しますが、npmインストールではNode.js 22.15以降が必要です。

どこで設定するかでセッションごとの効き方が変わる

同じ変数でも、どのセッション種別で・どこに書いたかによって適用されるかが変わります。

バックグラウンドエージェントを動かすスーパーバイザープロセスは全ターミナルで共有される単一のプロセスで、どのシェルが最初にそれをコールドスタートさせたかに応じて環境を引き継ぎます。OSインストール型のスーパーバイザーはシェルの環境をまったく受け取りません。恒常運用を前提にするなら、CLAUDE_CODE_CLIENT_CERT系の3変数は最初から~/.claude/settings.jsonのenvブロックかmanaged settingsに書く方が、原因不明の接続失敗を避けられます。

クラウドセッションでは、ホスティング環境がAPIへの接続自体を管理するため、設定ファイルのenvブロック由来の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の6キーが無視されます。無視した各キーはセッションのデバッグログに記録されます。

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

Claude Codeは起動時にほとんどの設定値を検証しません。証明書パスの誤りのような設定ミスは、後続のリクエストが実際に失敗するまで表面化しないため、--debugで事前に確認しておくのが確実です。

claude --debug

デバッグ出力は~/.claude/debug/<session-id>.txt(または--debug-fileで指定したパス)に書かれ、証明書と鍵の読み込みが行ごとに記録されます。

mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT
mTLS: Loaded client key from CLAUDE_CODE_CLIENT_KEY

読み込みに失敗した場合はFailed to readまたはFailed to loadという行が理由付きで出ます。対話セッション中であれば/statusでも確認でき、mTLS client certとmTLS client keyの行はファイルを読み込めたときだけ表示されます。行が無いこと自体が読み込み失敗のサインで、詳しい理由はデバッグログ側で確認します。

証明書をローテーションすると何が起きるか

Claude Codeは証明書と鍵のファイルを起動時に読み込み、設定を適用するたび(組織がmanaged settingsのenvブロックをセッション中に変更した場合を含む)にも読み直します。ローテーションの手順自体は単純で、同じパスにファイルを置き換えるだけです。稼働中のセッションを再起動する必要はありません。

ただし、Claude Codeはファイルの変更を監視しているわけではありません。ファイルを置き換えた瞬間には何も起きず、次のいずれかのタイミングで新しい証明書を読みにいきます。

• 接続レベルのエラー(接続のリセットやTLSハンドシェイクの失敗など)を伴うAPIリクエストの再試行時
• 設定を次に適用したとき、またはセッションを再起動したとき

このどちらが先に来るかで決まります。ゲートウェイが古い証明書ペアを拒否して接続をリセットしたりTLSハンドシェイクを拒否したりした場合は前者が働きますが、ゲートウェイがハンドシェイクを完了させたうえでHTTPエラーを返す場合は再読み込みが起きず、後者を待つことになります。証明書と鍵が一致しないような書き換え途中の状態を読んでしまった場合は、古いペアを保持したまま次の失敗時まで再読み込みを待ちます。

ローテーションが反映されたかどうかは、デバッグログのStale connection — reloaded rotated mTLS client materialという行で確認できます。設定の適用時に反映された場合はこの行が出ないため、この行が無いことだけをもってローテーション失敗と判断はできません。

なお、HTTPベースのOTLPテレメトリエクスポーター向けのmTLS対応はv1.0.126で追加された別系統の仕組みで、こちらは初回使用時に読み込んだ証明書を保持し続けます。テレメトリ収集先にローテーション後の証明書を反映させるにはClaude Code自体の再起動が必要です。証明書は現在のペアが失効する前に置き換え、失効済みのペアを次回起動時に読み込ませないようにします。

CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTIONの使いどころ

CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION=1を設定すると、接続レベルのエラーをきっかけにした再読み込みを止められます。Claude Code v2.1.232以降で使える設定です。

export CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION=1

無効化すると、Claude Codeは次に設定を適用したときか次回起動時にしかローテーション後のファイルを読み込みません。既定の動作(接続エラーで即座に再読み込みする)は多くの環境でそのまま有効にしておいて問題ありませんが、証明書のローテーションと設定の再適用を同じタイミングに揃える運用にしていて、接続エラー起点の非同期な再読み込みを増やしたくない場合はオフにする選択肢があります。

mTLS対応の変遷

mTLSクライアント証明書の設定自体は以前から存在し、Claude Code v2.1.23(2026年1月29日)の時点で企業プロキシ・クライアント証明書利用時の接続問題を修正した記録が残っています。その後の版で対応範囲が広がりました。

v2.1.232より前のバージョンでは、接続エラーが起きても再読み込みをせず、次に設定を適用するか再起動するまで古いペアを使い続けていました。恒常的に運用する環境では、この版以降を使っているかどうかでローテーション時の挙動が大きく変わります。

よくあるつまずき

• CLAUDE_CODE_CLIENT_CERTとCLAUDE_CODE_CLIENT_KEYはどちらか一方だけでは機能しません。証明書と秘密鍵はペアで指定します
• シェルでexportした値は起動時に一度だけ読み込まれます。実行中のセッションは、後からシェル環境を変更しても反映されません。設定を変えたのに効かないときは、まずセッションを再起動してから確認します
• バックグラウンドエージェントだけ接続に失敗する場合、シェルのexportに頼っていないか疑います。対策は~/.claude/settings.jsonのenvブロックに同じ変数を書くことです
• ローテーション後に接続エラーが出ないままいつまでも古い証明書が使われている場合、ゲートウェイがハンドシェイクを完了させてHTTPエラーを返す構成になっていないか確認します。この場合は接続エラー起点の再読み込みが働かないため、設定の再適用かセッションの再起動が必要です
• OTLPエクスポーター経由のテレメトリ収集だけ証明書ローテーションが反映されない場合は、Claude Code自体の再起動を試します
• MCPサーバーとのOAuthフローだけmTLSが効いていないように見える場合は、v2.1.133より前のバージョンを使っていないか確認します

まとめ

mTLSクライアント証明書認証の設定自体はCLAUDE_CODE_CLIENT_CERT・CLAUDE_CODE_CLIENT_KEYの2変数で完結し、難しくありません。見落としやすいのは設定を書く場所と、ローテーション時の再読み込みタイミングです。バックグラウンドエージェントやClaude Desktop管理下のセッションまで確実に届けるには~/.claude/settings.jsonのenvブロックを使い、証明書を定期的に入れ替える運用では、v2.1.232以降の自動再読み込みとデバッグログでの確認方法を押さえておくと、原因調査に時間をかけずに済みます。