Claude Code ガイド

Appearance

原文（日本語訳） ​

クライアント証明書の無停止（in-place）ローテーション中に設定が再適用された際、一時的に発生していたmTLSハンドシェイクの失敗を修正しました。

原文（英語） ​

Fixed transient mTLS handshake failures when settings were re-applied during an in-place client certificate rotation

概要 ​

本アップデートは、Claude Codeの通信基盤に対するバグ修正です。mTLS（mutual TLS、相互TLS）は、企業のセキュリティポリシーにおいてサーバー側だけでなくクライアント側も証明書を提示して認証を行う仕組みで、Claude Codeではプロキシやゲートウェイ経由の通信を保護するために利用されています。今回の修正により、運用中のクライアント証明書を停止せずに入れ替える「無停止ローテーション」の最中にsettings.jsonが再読み込みされたタイミングで発生していた、一時的なハンドシェイク失敗が解消されました。

基本的な使い方 ​

Claude Codeでは、mTLSによるクライアント証明書認証を以下の環境変数で設定します。これらは~/.claude/settings.jsonのenvブロックに記載することも、プロセス環境変数として直接設定することも可能です。

bash
# クライアント証明書
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"

settings.jsonで管理する場合は以下のように記述します。

json
{
  "env": {
    "CLAUDE_CODE_CLIENT_CERT": "/etc/claude-code/certs/client-cert.pem",
    "CLAUDE_CODE_CLIENT_KEY": "/etc/claude-code/certs/client-key.pem",
    "CLAUDE_CODE_CLIENT_KEY_PASSPHRASE": "your-passphrase"
  }
}

証明書や鍵のパスを変更して設定を再適用すると、Claude Codeは新しい証明書を使ってTLSハンドシェイクを行います。今回の修正前は、この再適用のタイミングが証明書ローテーションの切り替え処理と重なると、まれにハンドシェイクが一時的に失敗するケースがありました。

実践例 ​

企業のPKI基盤での定期的な証明書ローテーション ​

多くの企業では、セキュリティポリシーに基づきクライアント証明書を数か月〜1年ごとに自動更新しています。証明書管理システム（例: HashiCorp VaultのPKIエンジンや社内CA）が新しい証明書・秘密鍵を発行し、管理者向け設定配布の仕組み（MDMや構成管理ツール、managed settings.json）経由でファイルを差し替え、続けてCLAUDE_CODE_CLIENT_CERT・CLAUDE_CODE_CLIENT_KEYの参照先を更新します。今回の修正により、この差し替えと同時にClaude Codeが設定を再読み込みしても、ハンドシェイクが不安定になることなく新しい証明書へスムーズに切り替わるようになりました。

json
{
  "env": {
    "CLAUDE_CODE_CLIENT_CERT": "/etc/claude-code/certs/client-cert-2026-07.pem",
    "CLAUDE_CODE_CLIENT_KEY": "/etc/claude-code/certs/client-key-2026-07.pem"
  }
}

CI/CDパイプラインでの緊急ローテーション対応 ​

証明書の漏えいや失効が疑われた場合、CI/CDパイプラインやオーケストレーションツールから緊急でクライアント証明書を差し替えることがあります。この際、稼働中のClaude Codeセッションやエージェントプロセスを止めずに設定ファイルだけを更新（無停止ローテーション）したいという要件が出てきます。以前は、このような緊急ローテーション中に設定の再適用タイミングが重なると通信が一時的に不安定になるリスクがありましたが、本修正によりローテーション処理と設定再適用が競合してもハンドシェイクが安定して完了するようになり、緊急時の運用がより安全になりました。

注意点 ​

  • 本修正は一時的（transient）なハンドシェイク失敗に対するものであり、証明書自体の期限切れや無効な証明書によるエラーは別問題として引き続き調査が必要です。
  • CLAUDE_CODE_CLIENT_CERT・CLAUDE_CODE_CLIENT_KEYのパスを変更した場合は、ファイルのパーミッションやパスの正当性を確認してください。
  • CLAUDE_CODE_CERT_STOREなど関連するTLS設定と組み合わせて利用している場合は、ローテーション後に一度接続確認を行うことを推奨します。
  • 子プロセス（MCPサーバーなど）は親プロセスの環境変数を必ずしも引き継がないため、ローテーション後にサブプロセス側でも証明書設定が反映されているか確認してください。

関連情報 ​