Содержание
Пытаетесь использовать Claude Code на рабочем компьютере или через VPN, а соединение не устанавливается с ошибками вроде этих?
Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API: SSL certificate verification failed.
Check your proxy or corporate SSL certificates
fetch failedЭто сетевые ошибки, означающие «Claude Code не может достучаться до сервера Anthropic (api.anthropic.com)». Это не аутентификация (401/403), не перегрузка сервера (529/500) и не лимит запросов (429) — запрос вообще не дошёл до сервера. Обычные причины — корпоративные прокси, TLS-инспекция (сертификаты) и файрволы, поэтому такое особенно часто встречается в корпоративных сетях. В этой статье разбираются настройка прокси, корпоративные CA-сертификаты, домены для белого списка и шаги диагностики — на основе официальной информации.
Главное сразу. (1) За прокси задайте HTTPS_PROXY. (2) При ошибке сертификата из-за TLS-инспекции (Zscaler и т. п.) укажите корпоративный CA в NODE_EXTRA_CA_CERTS — и никогда не отключайте проверку через NODE_TLS_REJECT_UNAUTHORIZED=0 (это открывает весь трафик для перехвата). (3) Начните с запуска curl -I https://api.anthropic.com, чтобы проверить «доходит ли вообще?» — это отправная точка диагностики.
Запрос не доходит до сервера
— где остановился, тем и определяется решение
HTTPS_PROXYNODE_EXTRA_CA_CERTS
Сначала запустите curl -I https://api.anthropic.com, чтобы проверить, доходит ли соединение.
Как только понятно, где оно останавливается (прокси / TLS / файрвол), нужная настройка определена.
1. О чём говорит эта ошибка
Unable to connect to API, fetch failed, ECONNREFUSED / ETIMEDOUT означают «запрос не дошёл до сервера Anthropic» = сбой где-то на уровне TCP/TLS/DNS. Это решающее отличие от других ошибок: аутентификация (401/403), сервер (529/500) и лимит (429) — это ответы уже после того, как запрос дошёл до сервера, тогда как сетевые ошибки означают, что он туда вообще не добрался.
В корпоративных сетях типичные препятствия делятся на три уровня. (1) Прокси — напрямую выйти нельзя, нужно идти через корпоративный прокси, который не настроен. (2) TLS-инспекция (сертификаты) — инспектирующий прокси вроде Zscaler подменяет сертификаты, поэтому нужно доверять корпоративному корневому CA. (3) Файрвол — нужные домены не разрешены. Первое, что нужно сделать, — подтвердить «доходит ли?» командой curl -I https://api.anthropic.com — эта единственная проверка отделяет «проблему сети» от «всего остального».
Где остановилось = какую настройку применить
ECONNREFUSED/ETIMEDOUT/fetch failed. Нужно идти через корпоративный прокси → задайте HTTPS_PROXY.SSL certificate verification failed/self-signed → поместите корпоративный CA в NODE_EXTRA_CA_CERTS. Никогда не отключайте проверку.Could not resolve host/ENOTFOUND. DNS не работает, остатки VPN или Docker перехватывает трафик.
Если curl -I https://api.anthropic.com проходит, проблема сужается до уровня между Claude Code и сетью.
2. Настройка прокси (HTTPS_PROXY)
Когда нужно идти через корпоративный прокси, задайте стандартные переменные окружения прокси. Claude Code их учитывает.
# Рекомендуется: HTTPS-прокси
export HTTPS_PROXY=http://proxy.example.com:8080
# Если HTTPS недоступен, HTTP_PROXY
export HTTP_PROXY=http://proxy.example.com:8080
# Адреса в обход прокси (через пробел или запятую)
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"
# Прокси с аутентификацией (не хардкодьте пароли)
export HTTPS_PROXY=http://username:password@proxy.example.com:8080Замечания: SOCKS-прокси не поддерживаются. Для прокси с NTLM / Kerberos официальная рекомендация — поднять между ними LLM gateway и направить на него ANTHROPIC_BASE_URL. Кроме того, если вы используете серверы MCP, нужно явно задать HTTPS_PROXY и NODE_EXTRA_CA_CERTS в блоке env каждого сервера (они не наследуются от родителя). Эти переменные можно также прописать в блоке env файла settings.json.
3. TLS и корпоративные CA-сертификаты (самое важное, безопасно)
Самое частое корпоративное препятствие — ошибка сертификата из-за того, что инспектирующий TLS-прокси (Zscaler, Netskope, Palo Alto и т. п.) подменяет сертификаты. Типичные сообщения — unable to get local issuer certificate и SELF_SIGNED_CERT_IN_CHAIN.
Для контекста: современный Claude Code доверяет КАК встроенному набору CA, ТАК И хранилищу доверия ОС. Поэтому если корпоративный корневой CA уже в хранилище сертификатов ОС, часто всё работает без дополнительной настройки (поведение зависит от версии, так что уточняйте актуальное). Если же его нет в хранилище ОС, укажите в NODE_EXTRA_CA_CERTS бандл CA (PEM), полученный от ИТ-отдела:
# Правильный, безопасный способ: доверять корпоративному CA
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
# Если прокси требует клиентский сертификат (mTLS)
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem⚠️ НЕ делайте этого: отключать проверку TLS
Отключение проверки сертификата через NODE_TLS_REJECT_UNAUTHORIZED=0 вроде бы «чинит» проблему, но так делать нельзя ни в коем случае. Это отключает проверку TLS для всего процесса, поэтому весь трафик — включая к api.anthropic.com — оказывается открыт для атак «человек посередине» (перехват/подмена). Это грозит утечкой учётных данных и кода. Правильный ответ всегда — «корректно доверять корпоративному CA через NODE_EXTRA_CA_CERTS».
Если ошибка сертификата возникает уже на этапе установки (когда бинарника ещё нет), передайте CA в curl: curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash.
4. Домены для белого списка файрвола
Если файрвол ограничивает адреса назначения, разрешите эти домены по HTTPS (443) (согласно официальным сетевым требованиям).
| Домен | Назначение |
|---|---|
api.anthropic.com | Запросы к Claude API (обязательно) |
claude.ai | Аутентификация аккаунта claude.ai |
platform.claude.com | Аутентификация аккаунта Console |
downloads.claude.ai | Установщик, автообновление, плагины |
raw.githubusercontent.com | Примечания к релизам, маркетплейс |
Телеметрия (statsig.anthropic.com) и отчёты об ошибках (*.sentry.io) необязательны и могут быть отключены (включать их в обязательный белый список не нужно). Если вы управляете установкой самостоятельно через npm, downloads.claude.ai может не понадобиться. Точные домены и диапазоны IP могут пересматриваться, поэтому уточняйте актуальные данные на официальной странице настройки сети.
5. Порядок диагностики
Когда соединение не устанавливается, идите сверху вниз. Первый curl задаёт направление.
Локализуйте сверху вниз
curl -I https://api.anthropic.com (Windows: curl.exe), чтобы проверить достижимость. Если проходит, проблема на вашей стороне./doctor (или claude doctor, если не запускается) и проверьте переменные окружения прокси.NODE_EXTRA_CA_CERTS; прокси не задан → примените HTTPS_PROXY.curl проходит, а Claude Code нет, подозревайте DNS (WSL resolv.conf), остатки VPN или Docker, перехватывающий трафик.
Правило: «сначала проверь достижимость (curl), затем примени настройку для того уровня, где остановилось».
Сертификаты — через NODE_EXTRA_CA_CERTS. Никогда не отключайте проверку.
6. Отличие от похожих ошибок
«Остановилось» может быть и не сетевой проблемой. Главное разделение — «дошёл ли запрос до сервера?»
| Симптом | Что это на самом деле | Основное решение |
|---|---|---|
| Unable to connect / fetch failed / ошибка сертификата | Эта статья = сеть (запрос не дошёл до сервера) | HTTPS_PROXY / NODE_EXTRA_CA_CERTS / белый список файрвола |
| 401 / 403 / Invalid API key | Аутентификация (дошёл, но проблема с учётными данными) | ошибки аутентификации / входа |
| 529 / 500 | Сторона сервера (дошёл, но перегрузка / внутренняя ошибка) | ошибки 529/500 |
| 429 Request rejected | Лимит запросов (дошёл, но слишком много трафика) | Снизьте темп, подождите |
Памятка: сетевые ошибки означают «запрос не дошёл до сервера» (TCP/TLS/DNS), и HTTPS_PROXY или NODE_EXTRA_CA_CERTS помогают только на этом уровне. Напротив, 401/403, 529/500 и 429 — это «ответы уже после того, как запрос дошёл», поэтому правка прокси или CA их не исправит. Проходит ли curl — лучший единственный признак, разделяющий эти две группы. О других частых ошибках см. сводку ошибок.
Итоги
Сетевые/прокси-ошибки Claude Code (Unable to connect / fetch failed / SSL certificate verification failed и т. п.) означают, что запрос так и не дошёл до сервера = сбой TCP/TLS/DNS. Они отличаются от аутентификации (401/403), сервера (529/500) и лимита (429), а обычные виновники — корпоративные прокси, TLS-инспекция и файрвол.
Решения: (1) за прокси задайте HTTPS_PROXY (SOCKS не поддерживается; NTLM/Kerberos — через gateway), (2) при ошибках сертификата поместите корпоративный CA в NODE_EXTRA_CA_CERTS — никогда NODE_TLS_REJECT_UNAUTHORIZED=0, (3) добавьте api.anthropic.com и др. в белый список файрвола. Диагностируйте так: сначала проверьте достижимость командой curl -I https://api.anthropic.com -> /doctor и проверка прокси -> настройки сертификата/прокси -> прямое соединение для подтверждения -> DNS/VPN/Docker. Главное — отделить сеть от аутентификации/сервера/лимита по принципу «дошёл ли запрос до сервера?» Связанное: ошибки аутентификации / входа, ошибки 529/500, сводка ошибок Claude Code.
FAQ
Q. На рабочем ПК получаю «Unable to connect to API» и не могу подключиться.
A. Обычно нужно идти через корпоративный прокси, который не настроен. Сначала проверьте достижимость командой curl -I https://api.anthropic.com; если не проходит, задайте прокси вроде export HTTPS_PROXY=http://proxy.example.com:8080 (добавьте user:password@ для прокси с аутентификацией). Учтите, что SOCKS не поддерживается, а для прокси с NTLM/Kerberos официальная рекомендация — идти через LLM gateway.
Q. Получаю «SSL certificate verification failed».
A. Обычно это корпоративный инспектирующий TLS-прокси (например, Zscaler), подменяющий сертификаты. Получите корпоративный корневой CA (PEM) от ИТ-отдела и задайте export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem. Если корпоративный CA уже в хранилище сертификатов ОС, может работать и без настройки. Никогда не отключайте проверку через NODE_TLS_REJECT_UNAUTHORIZED=0 — это открывает весь трафик для перехвата.
Q. Установил NODE_TLS_REJECT_UNAUTHORIZED=0, и заработало. Так нормально?
A. Нет — верните это сейчас же. Это отключает проверку TLS-сертификатов для всего процесса, оставляя весь трафик — включая к api.anthropic.com — беззащитным перед атаками «человек посередине» (перехват/подмена). Это серьёзный риск безопасности, способный привести к утечке учётных данных и исходного кода. Единственное правильное решение — корректно доверять корпоративному CA через NODE_EXTRA_CA_CERTS.
Q. Какие домены нужно разрешить в файрволе?
A. По HTTPS (443) как минимум разрешите api.anthropic.com (API), claude.ai и platform.claude.com (аутентификация), downloads.claude.ai (установщик/обновления) и raw.githubusercontent.com. Телеметрия (statsig) и отчёты об ошибках (sentry) необязательны. Точные домены/IP могут пересматриваться, поэтому уточняйте актуальные данные на официальной странице настройки сети.
Q. curl работает, но именно Claude Code не подключается.
A. Причина часто между Claude Code и ОС. Частые случаи: WSL /etc/resolv.conf, указывающий на нерабочий DNS, остатки VPN (например, старые интерфейсы utun в macOS) или резидентный инструмент вроде Docker, перехватывающий трафик. Попробуйте прямое соединение без VPN, остановите резидентные инструменты и проверьте DNS — именно в таком порядке. Учтите, что временные ошибки 5xx автоматически повторяются до 10 раз, поэтому если вы видите ошибку при том, что curl проходит, повторы уже исчерпаны.
