DEV Community

Seven
Seven

Posted on

Claude Code с внешним Anthropic-совместимым API: воспроизводимый порядок отладки

#api #ai #webdev #russian

Раскрытие и доступность: DaoXE — мультимодельный мультипротокольный API-шлюз, который мы эксплуатируем. Он поддерживает OpenAI Chat Completions, OpenAI Responses, Anthropic Messages (протокол Claude) и OpenAI-совместимую генерацию изображений там, где она доступна. Сервис недоступен в материковом Китае. Статья — для разработчиков в регионах, разрешённых условиями сервиса. Порядок отладки ниже подходит для любого шлюза, совместимого с Anthropic Messages, не только для DaoXE.

CLI Claude Code работает по протоколу Anthropic Messages. Если шлюз отдаёт протокол Claude по адресу /v1/messages, направить Claude Code на него можно двумя переменными окружения — без прокси, без роутера, без правок кода.

Проблема почти никогда не в модели и не в промпте. Она в форме base URL, в оболочке или в имени переменной токена. Этот порядок за полминуты разделяет «проблема шлюза/ключа» и «проблема конфигурации Claude Code», чтобы вы перестали гадать.

Сначала — две переменные 

export ANTHROPIC_BASE_URL="https://your-gateway.example"   # КОРЕНЬ хоста, не .../v1
export ANTHROPIC_AUTH_TOKEN="ваш_API_KEY"
Enter fullscreen mode Exit fullscreen mode

Claude Code сам добавит /v1/messages. Самая частая ошибка — задать ANTHROPIC_BASE_URL как https://your-gateway.example/v1; тогда Claude Code запрашивает /v1/v1/messages, и всё возвращает 404.

Шаг 1 — сначала докажите протокол через curl

Не запускайте claude сразу. Если curl не работает, CLI не заработает тоже. Узнайте реальный ID модели, затем отправьте один крошечный запрос Messages (max_tokens держите маленьким; может тарифицироваться):

export API_KEY="ваш_API_KEY"

# 1. Что этот аккаунт реально может вызвать?
curl -H "Authorization: Bearer $API_KEY" https://your-gateway.example/v1/models

# 2. Один крошечный запрос Messages
export MODEL="точный_id_из_шага_1"
curl --fail-with-body --show-error --silent \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$MODEL\",\"max_tokens\":8,\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK.\"}]}" \
  https://your-gateway.example/v1/messages
Enter fullscreen mode Exit fullscreen mode
  • 200 + короткий ответ → протокол в порядке, переходите к шагу 2.
  • 401 → неверный ключ / не активирован / не тот заголовок. Чините здесь, не в Claude Code.
  • 404 / HTML → неверный путь или форма base URL. Запишите точный рабочий URL.
  • model-not-found → этого ID нет в каталоге вашего аккаунта. Возьмите ID из шага 1.

Шаг 2 — только теперь запускайте Claude Code 

export ANTHROPIC_BASE_URL="https://your-gateway.example"   # корень хоста
export ANTHROPIC_AUTH_TOKEN="$API_KEY"
claude
Enter fullscreen mode Exit fullscreen mode

Если curl работает, а Claude Code всё равно падает — проверяйте по порядку:

  1. /v1 в base URL. Должен быть корень хоста. Причина №1.
  2. Не та оболочка. export должны быть в том же терминале, где запускается claude; в новой вкладке их нет.
  3. Имя переменной токена. Некоторые версии Claude Code читают ANTHROPIC_API_KEY, а не ANTHROPIC_AUTH_TOKEN. Задайте обе на одно значение.
  4. Псевдоним модели vs реальный ID. Если задан ANTHROPIC_MODEL, это должен быть точный ID из шага 1, а не удобный алиас Anthropic, который шлюз может не отображать.
  5. Устаревший файл настроек перекрывает окружение. Проверьте ~/.claude/settings.json и .claude/settings.json в проекте.

Шаг 3 — закрепите (по желанию)

Чтобы не экспортировать каждый раз, добавьте переменные в профиль оболочки:

# ~/.zshrc или ~/.bashrc
export ANTHROPIC_BASE_URL="https://your-gateway.example"
export ANTHROPIC_AUTH_TOKEN="ваш_API_KEY"
# опционально, зафиксировать точные ID из каталога:
export ANTHROPIC_MODEL="точный_id_модели"
export ANTHROPIC_SMALL_FAST_MODEL="точный_id_лёгкой_модели"
Enter fullscreen mode Exit fullscreen mode

Ключ не должен попадать в git и на скриншоты. Если утёк — ротация в кабинете.

Почему важен именно этот порядок

Комбинация «curl проходит, а клиент красный» очень частая. Обычно это не значит, что шлюз лежит — это значит, что «диалект клиента» и «путь, который вы только что проверили» — не одно и то же. Доказав сам протокол Messages на шаге 1, вы локализуете проблему до конфигурации клиента, а не тратите время на модели и промпты.

Клиент и протокол

  • Cline / Continue / Roo и многие ассистенты кода → обычно OpenAI-совместимый Chat Completions с кастомным base URL
  • Новые agent-стеки → может понадобиться Responses
  • Claude Code / Anthropic SDK / инструменты только на Messages → Anthropic Messages
  • Инструменты изображений → OpenAI-совместимая генерация изображений, если в каталоге аккаунта есть image-модели

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

Ссылки

  • Нативная настройка Claude Code (ANTHROPIC_BASE_URL): CLAUDE_CODE.md
  • Настройка клиентов (Cline / Roo / Continue + пути протоколов): CLIENT_SETUP.md
  • Примеры и недорогой бенчмарк: DaoXE-AI
  • Главная (с трекингом): daoxe.com

Имена переменных окружения и приоритеты меняются между релизами Claude Code; при странном поведении сверяйтесь с текущей документацией по настройкам Claude Code и с curl из шага 1. DaoXE — мультимодельный мультипротокольный шлюз: не только протокол OpenAI и не только модели OpenAI/Claude.

Top comments (0)