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

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

画面に出た文言から、原因の当たりをつける

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

通常のAPIリクエストで出る文言は、v2.1.285では次の2種類です。

Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config
Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). The certificate comes from an authority Claude Code doesn't trust, ...(以下同じ)

括弧内のOpenSSLコードが、証明書チェーンのどこで止まったかを示します。UNABLE_TO_GET_ISSUER_CERT_LOCALLYは発行元の証明書が手元に見つからない場合、SELF_SIGNED_CERT_IN_CHAINはチェーンの途中に自己署名の証明書がある場合です。どちらも文末の案内は同じで、対処は共通です。

一方、/loginの実行時と起動時の接続チェックでは、同じ失敗が別の文面になります。

SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

古いバージョンの文言で検索してきた場合は、末尾がCheck your proxy or corporate SSL certificatesで終わる短い形かもしれません。v2.1.273より前はOpenSSLコードもNODE_EXTRA_CA_CERTSの案内も付かず、上の2種類とも同じ一文で終わっていました。更新後は文面自体が対処のヒントを含みます。

「社内CAを入れたのに直らない」は原因が2通りある

同じ症状でも、切り分けの向きが違います。

npm版でNodeのバージョンが古い場合は、OSストアを直すよりNODE_EXTRA_CA_CERTSでファイルを直接渡すか、Nodeを更新する方が早く済みます。インストール方法そのものを見直すならClaude Codeインストールエラーの切り分けチェックリストが入口になります。

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

組織のCAバンドルをエクスポートし、NODE_EXTRA_CA_CERTSでそのパスを指定します。

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

初回セットアップでは、サインインの手順を出す前にapi.anthropic.comとplatform.claude.comへ届くかを確認します。どちらかが失敗すると理由を表示して終了するので、証明書の問題はログイン画面より前に表に出ることがあります。

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

設定が届いたかを確かめる

設定を変えただけでは、反映されたかどうかは分かりません。次の順で確認します。

claude doctorは、証明書エラーの文面が案内しているコマンドです。手元のv2.1.285でヘルプを確認すると、次のとおりです。

claude doctor --help

Usage: claude doctor [options]
 
Check the health of your Claude Code installation. Reads settings files in the
current directory without a trust prompt. For a full checkup that can also fix
issues, run /doctor in a session.
 
Options:
  -h, --help  Display help for command

ヘルプの説明はインストールの健全性チェックで、証明書に特化した診断とは書かれていません。証明書ファイルの読み込み結果は、上のデバッグログで確認します。

バックグラウンドセッションにはsettings.jsonで渡す

バックグラウンドセッション(claude agents・--bg・/background)は、シェルではなくスーパーバイザープロセスが起動します。このプロセスは全ターミナルで共有され、最初に起動したシェルの環境を引き継ぎます。OSのサービスとして入れた場合は、シェルの環境変数がまったく渡りません。シェルでだけexportした値は、たまたまそのシェルがスーパーバイザーを起動したときにしか届かないため、~/.claude/settings.jsonのenvブロックに書きます。

バージョンごとの挙動の変化

証明書まわりは最近のバージョンで何度か変わっています。手元のバージョンと突き合わせると、記事や社内メモの古い記述との食い違いが説明できます。

証明書エラーが「一時的な不調かも」と見えて何度も再実行していたのは、v2.1.199より前の待ち時間が原因です。古いバージョンを使っている場合はClaude Codeアップデートの方法に沿って更新すると、切り分けが速くなります。

よくあるつまずき

• NODE_EXTRA_CA_CERTSをシェルでexportしても、すでに起動しているセッションには反映されません。設定後は再起動します
• 証明書ファイルのパスが誤っていても、起動時にはエラーになりません。起動時に検証されるのはプロキシURLの書式だけで、パスの誤りは後続のAPIリクエストで初めて失敗として現れます
• Claude Desktopが接続を管理するセッションでは、リポジトリ直下の.claude/settings.jsonに書いても反映されません。管理者設定か~/.claude/settings.jsonからしか読まれないためです

よくある質問

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

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

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

効きません。クラウドセッションではホスティング環境がAPIへの接続を管理しており、設定ファイルのenvブロックに書いたNODE_EXTRA_CA_CERTSやNODE_TLS_REJECT_UNAUTHORIZEDは無視されます。無視されたキーはセッションのデバッグログに記録されます。また、クラウドセッションではネットワークポリシーを適用するプロキシが通信を終端するため、宛先の本物とは違う証明書が見えることがあります。この場合の証明書の不一致は、ローカルの設定ではなく環境側の挙動です。

Amazon Bedrockを使っていても同じ設定でいいですか

はい。Claude CodeがAWSへ送る認証情報の解決(STSやSSOのロール認証)、モデルの探索、セットアップウィザードの確認は、同じCA設定を使います。OSストアかNODE_EXTRA_CA_CERTSに社内ルート証明書があれば、Bedrock専用の設定は要りません。ただし適用の範囲が広がったのはv2.1.260からで、それより古いバージョンでは前節の年表にあるとおり、プロキシ経由の通信にしか効きません。ウィザードで「Use credentials already in my environment」を選んだときのモデル確認だけは、v2.1.261より前はOSストアの証明書を使いませんでした。