Claude CodeのSSL証明書エラーの原因と対処法

SSL証明書エラーは、プロキシやセキュリティアプライアンスがTLS通信を自前の証明書で代行し、Claude Codeがその証明書を信頼していないときに出ます。接続そのものは確立できているのに、証明書の身元確認だけで止まっている状態です。対処は社内CAバンドルをNODE_EXTRA_CA_CERTSに登録することで、TLS検証そのものを無効化する設定は使いません。v2.1.199でリトライの扱いも変わり、以前より早くエラーに気づけるようになりました。企業ネットワーク配下でClaude Codeを導入するときに最初につまずきやすい症状の1つで、原因の見た目に反して対処自体は難しくありません。

SSL証明書エラーが出る仕組み

Claude Codeは既定で、Mozillaのバンドル証明書とOSの証明書ストアの両方を信頼します。企業ネットワークでTLSを検査するプロキシ(CrowdStrike FalconやZscalerなど)は、通信をいったん復号して検査するために自前の証明書を発行し直します。この証明書がOSのトラストストアに登録されていなければ、Claude Codeは接続先の身元を確認できず、SSL証明書エラーとして接続を止めます。

OSの証明書ストアを読むにはtls.getCACertificatesというランタイム機能が必要です。ネイティブインストーラ経由なら常に対応していますが、npmでインストールした場合はNode.js 22.15以降が必要です。それより古いNodeでは、バンドル証明書とNODE_EXTRA_CA_CERTSで追加した証明書だけが使われ、OSストアに社内CAを入れていても効きません。

つまり同じ「社内CAをOSに登録しているのに直らない」という相談でも、原因はTLS検査プロキシの証明書が信頼されていないケースと、ランタイム側がOSストアを読めていないケースの2種類に分かれます。前者は証明書そのものの登録先、後者はNode.jsのバージョンという、まったく別の切り分けが必要です。どちらのケースかを最初に見極めておくと、遠回りな試行錯誤を避けられます。

エラー文言の違いを見分ける

同じ原因でも、発生するタイミングによってメッセージの形が変わります。

3つ目のパターンは、メッセージ自体に「NODE_EXTRA_CA_CERTSを設定するか、ITに*.anthropic.comの許可を依頼してください。詳細はclaude doctorで確認できます」という案内が埋め込まれています。/loginや起動直後の接続チェックは、通常のAPIリクエストとは別の経路でエラーを報告しているため、文言の形が変わります。

どのパターンでも根本原因は同じで、Claude Codeが接続先の証明書チェーンをたどれないことに変わりありません。文言の違いは、失敗を検知した箇所がAPIリクエストの途中か、ログイン・起動チェックの専用フローかという実装上の都合によるものです。原因の特定に文言の違い自体が影響することはなく、いずれのメッセージでも対処は共通です。

v2.1.199でリトライの扱いが変わった

バージョンによって、証明書エラーが表示されるまでの待ち時間が違います。

証明書の検証失敗は、何度リクエストを送り直しても同じ理由で失敗し続けます。v2.1.199以降はこれを見越して、無駄なリトライをせず一発目でエラーを出すようになりました。ただしTLSハンドシェイクのタイムアウトのような一時的なTLS事象は区別されており、そちらは引き続き自動リトライの対象です。証明書そのものが信頼できないケースだけが、即座にエラーとして扱われます。

v2.1.199より前のバージョンでは、フルのリトライ予算を使い切るまで数分待たされたうえで同じエラーが出ていたため、「一時的な不調かもしれない」と誤解して繰り返し実行してしまうことがありました。バージョンを更新するだけでこの無駄な待ち時間は解消しますが、証明書自体を信頼させる作業は避けて通れません。手元のバージョンが古い場合はClaude Codeアップデートの方法に沿って先に更新しておくと、以降の切り分けが速くなります。

対処 — 社内CAバンドルを登録する

正しい対処は、組織のCAバンドルをエクスポートし、NODE_EXTRA_CA_CERTSでそのパスを指定することです。

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

信頼元の組み合わせ自体を制御したい場合は、CLAUDE_CODE_CERT_STOREにカンマ区切りでbundled・systemを指定します。既定値はbundled,systemで、このキーには専用のsettings.jsonスキーマ項目がないため、envブロックか環境変数で設定します。企業プロキシ配下でClaude Codeを一から動かす手順はClaude Codeプロキシ設定ガイドにまとめてあります。本記事はそのうちSSL証明書エラーの原因切り分けとバージョンごとの挙動差だけを深掘りする位置づけです。すでに接続自体はできていて証明書エラーだけが出ている場合は、このページの手順で足ります。

設定が届いているかを確認する方法

設定を変えただけでは、実際に反映されているかは分かりません。claude --debugで起動すると、証明書ファイルを読み込んだ行がデバッグログに記録されます。読み込みに失敗している場合は、理由付きのFailed to readやFailed to loadという行が出ます。

インタラクティブセッションでは/statusも確認材料になります。「Additional CA cert(s)」の行はNODE_EXTRA_CA_CERTSのパスを表示しますが、ファイルが実際に読み込めたかまでは確認していません。読み込みの成否は、必ずデバッグログ側で確認します。

バックグラウンドセッション(claude agents・--bg・/background)は、シェルではなくスーパーバイザープロセスが起動します。シェルでのみexportしたNODE_EXTRA_CA_CERTSは、そのシェルがたまたまスーパーバイザーを起動したときにしか届きません。バックグラウンドセッションにも確実に届けたいなら、~/.claude/settings.jsonのenvブロックに書きます。

よくあるつまずき

• NODE_EXTRA_CA_CERTSをシェルでexportしただけで満足しがちですが、その値は起動時に一度だけ読まれます。すでに起動しているセッションには反映されないため、設定後は必ず再起動します
• 証明書ファイルのパスが誤っていても、Claude Codeは起動時にファイルの中身までは検証しません。/statusのパス表示だけを信じず、デバッグログの読み込み結果まで確認します
• Claude Desktopが接続を管理するセッションでは、リポジトリ直下の.claude/settings.jsonに書いても反映されません。管理者設定か~/.claude/settings.jsonからしか読まれないためです
• 起動時にClaude Codeが検証するのはプロキシURLの書式だけです。証明書パスの誤りはこの時点では弾かれず、後続のAPIリクエストで初めて失敗として現れます

よくある質問

mTLSのクライアント証明書エラーと同じですか

違います。SSL証明書エラーはサーバー側(プロキシやAPI)の証明書をClaude Codeが信頼できるかという問題で、mTLSは逆にClaude Code側がクライアント証明書を提示してサーバーに身元を証明する仕組みです。原因も設定する変数も別で、CLAUDE_CODE_CLIENT_CERT・CLAUDE_CODE_CLIENT_KEYはmTLS専用です。この2つを混同して、SSL証明書エラーが出ているのにクライアント証明書だけを設定して解決しない、という遠回りは避けられます。

クラウドセッションでも同じ設定が効きますか

効きません。クラウドセッションではホスティング環境がAPIへの接続を管理しており、設定ファイルのenvブロックに書いたNODE_EXTRA_CA_CERTSやNODE_TLS_REJECT_UNAUTHORIZEDは無視されます。この場合の証明書エラーは、ローカル側の設定ではなくホスティング環境側の問題として扱います。

claude doctorは何を教えてくれますか

/login時や起動時の接続チェックで出るSSL証明書エラーには、claude doctorで詳細を確認するよう案内が含まれています。設定状況の診断情報をまとめて確認できるため、NODE_EXTRA_CA_CERTSのパスが正しく認識されているかを含めた切り分けに使います。

OSの証明書ストアに社内CAを入れているのに直りません

npmインストールでNode.js 22.15より前を使っている場合、OSの証明書ストアを読む機能自体が使えず、バンドル証明書とNODE_EXTRA_CA_CERTSしか有効になりません。Node.jsのバージョンを確認するか、ネイティブインストーラへの切り替えを検討します。インストール周りのエラー全般はClaude Codeインストールエラーの切り分けチェックリストも参照してください。

自己署名証明書とTLS検査プロキシの証明書は同じ扱いですか

はい、どちらもOSやバンドルのトラストストアに登録されていない証明書という点で同じ扱いです。表示されるメッセージの違いは、Claude Codeが失敗の理由をどこまで具体的に特定できたかにすぎません。対処はどちらもNODE_EXTRA_CA_CERTSへの登録で共通です。

まとめ

SSL証明書エラーの対処は、TLS検証を切ることではなく、社内CAバンドルを正しく登録することです。設定後はclaude --debugのログで読み込みを確認し、バックグラウンドセッションを使うならsettings.jsonのenvブロックに書いて確実に届けます。v2.1.199以降はエラーが早く出るようになっただけで、対処そのものは変わりません。設定を変えても症状が同じなら、証明書の登録先の間違いとNode.jsのバージョン不足という、2つの独立した原因を切り分け直すところから始めます。