Unable to connect to API (ConnectionRefused) в Claude: причины и решение

Сообщение «Unable to connect to API (ConnectionRefused)» в Claude Code означает, что программа не смогла даже открыть соединение с адресом, который ей указан. Это не ошибка ключа (тогда пришёл бы код 401) и не ошибка баланса (402): до сервера запрос просто не дошёл. Ниже список причин от самых частых и порядок диагностики через curl, который за пять минут показывает, где обрыв.

Что значит ConnectionRefused

«Connection refused» это отказ на уровне соединения: по указанному адресу и порту никто не принимает подключение, либо между вами и сервером стоит прокси, который отказывает. Если бы сервер получил запрос и отклонил его, вы увидели бы HTTP-код с телом ответа. Поэтому первое правило диагностики: выяснить, получаете ли вы вообще какой-либо HTTP-ответ. Если да, сеть работает, и проблема в ключе, модели или балансе. Если нет, ищем проблему в адресе, прокси, DNS или сети.

Причины по частоте

1. Неверный ANTHROPIC_BASE_URL. Опечатка в домене, http:// вместо https://, лишний порт, адрес локального прокси, который когда-то настраивали и больше не запускают (например, http://localhost:3456).
2. Переменная не доходит до Claude Code. Вы записали её в ~/.zshrc, но запускаете редактор или терминал из графической оболочки, которая её не читает. Или переменная задана в другом окне терминала.
3. Мёртвый или неверный прокси. Заданы HTTPS_PROXY или HTTP_PROXY, указывающие на адрес, где ничего не слушает.
4. DNS не резолвит домен. Проблема с резолвером, корпоративным DNS или файлом hosts.
5. Сеть режет исходящие подключения. Корпоративный фаервол, ограничения сети организации. Здесь помогает администратор сети.
6. Адрес с /v1 или без него. Для Claude Code он обычно даёт 404, а не refused, но лишние пути в адресе тоже стоит убрать.

Диагностика за пять минут

Шаг 1. Что реально задано

В том же терминале, где запускаете claude:

echo "$ANTHROPIC_BASE_URL"
echo "${ANTHROPIC_AUTH_TOKEN:0:9}"   # первые символы ключа, должно быть fetch_...
env | grep -i proxy

Для Zukko правильно так: ANTHROPIC_BASE_URL=https://api.zukko.pro (без /v1, с https) и ANTHROPIC_AUTH_TOKEN=fetch_.... Пустой вывод значит, что переменная в этой сессии не задана. В PowerShell используйте $env:ANTHROPIC_BASE_URL и Get-ChildItem Env:*proxy*. Если вы задавали переменные в файле настроек Claude Code (блок env в settings.json), сверьтесь с документацией по Claude Code↗ и проверьте этот файл тоже: он может переопределять переменные окружения. В сессии также можно посмотреть команду /status, если она есть в вашей версии.

Шаг 2. Достижим ли сервер

curl -sS -o /dev/null -w "%{http_code}\n" https://api.zukko.pro/v1/models

Список моделей открыт и ключ не проверяет, поэтому эта команда отвечает только на вопрос о сети. Ключ проверим на шаге 3. В PowerShell вызывайте curl.exe, потому что curl там псевдоним другой команды. Читаем результат:

Шаг 3. Проверка ключа и формата сообщений

Если GET /v1/models отвечает, проверьте тот же путь, который использует Claude Code. Этот запрос уже проверяет ключ:

curl -sS https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":20,"messages":[{"role":"user","content":"ping"}]}'

Ответ с текстом модели означает, что ключ и API работают, а ошибка кроется в окружении Claude Code. 401 значит неверный ключ, 402 — не хватает баланса, model_not_found — неверное имя модели (список доступных даёт GET /v1/models). Остальные коды описаны в документации по авторизации↗.

Решения по причинам

Неверный адрес. Исправьте на https://api.zukko.pro, без /v1 и без завершающего пути. Если сомневаетесь, где /v1 нужен, а где нет, прочитайте статью Base URL с /v1 или без↗.

Остался адрес локального прокси. Сделайте unset ANTHROPIC_BASE_URL (или удалите строку из ~/.zshrc, из системных переменных в Windows), откройте новый терминал и задайте правильный адрес. Проверьте, не лежит ли старое значение в файле настроек Claude Code.

Переменные не видны. Задайте их в профиле оболочки (~/.zshrc, ~/.bashrc) и запускайте Claude Code из нового терминала. Если запускаете из редактора, откройте его из терминала или задайте переменные в его настройках терминала. На Windows после изменения системных переменных нужно перезапустить терминал.

Неверный прокси. Если прокси вам нужен (например, в организации), исправьте его адрес. Если не нужен, уберите HTTPS_PROXY и HTTP_PROXY для этой сессии: unset HTTPS_PROXY HTTP_PROXY. Если сеть корпоративная и исходящие подключения ограничены, обратитесь к администратору: он знает, какие адреса разрешены.

DNS. Проверьте nslookup api.zukko.pro. Если домен не находится, смените DNS-сервер в системе на другой доступный вам или проверьте файл hosts на устаревшие записи.

Сертификаты и время. Ошибки TLS часто вызывает неверное системное время или прокси организации, подставляющий свой сертификат. В организации корневой сертификат прокси добавляют в доверенные по правилам вашего ИТ-отдела.

Если после правок всё равно ошибка

1. Повторите шаг 2 с другой сети (например, с мобильной точки доступа): если там 200, причина в вашей основной сети.
2. Попробуйте запрос с другого компьютера. Так вы отделите проблему вашей машины от проблемы сети.
3. Если в curl приходит 503, это уже ответ сервера, а не отказ соединения: провайдер модели недоступен или модель выключена (model_disabled), возьмите другую модель из GET /v1/models.
4. Если Claude Code вместо этого просит войти в аккаунт Anthropic, это отдельная ситуация: Claude Code просит войти в Anthropic↗.

Частые вопросы

Unable to connect to API: это проблема ключа?

Нет. Неверный ключ приводит к ответу 401 от сервера, а здесь соединение не установлено вовсе. Но ключ всё же проверьте запросом из шага 3: если он вернёт 401, сеть в порядке, а ключ нужно заменить.

Работает ли Claude Code из России?

Доступ из России организуется через шлюз: в ANTHROPIC_BASE_URL указывается https://api.zukko.pro, ключ создаётся в кабинете, оплата СБП, картой MasterCard или криптой. Если после настройки возникает ConnectionRefused, диагностика выше покажет, где обрыв.

Нужно ли добавлять /v1 в ANTHROPIC_BASE_URL?

Нет. Claude Code сам дописывает /v1/messages, поэтому для него адрес без /v1. Ошибочное добавление обычно приводит к 404.

Как быстро проверить, что ключ и баланс в порядке?

Выполните запрос из шага 3: ответ модели означает, что ключ действителен и баланса хватает (иначе пришли бы 401 или 402). Остаток баланса и расход видны в кабинете в разделе «Использование».

Ключ и настройки для Claude Code находятся в кабинете↗: создайте ключ, задайте две переменные окружения и повторите проверку.