Настройка Claude Code через API-шлюз
Инструкция для macOS, Linux и Windows PowerShell: как подключить Claude Code к любому Anthropic-совместимому API-провайдеру, выбрать модель, проверить соединение и разобраться с типичными ошибками.
Содержание
1. Установите Claude Code
macOS, Linux и WSL:
curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell:
irm https://claude.ai/install.ps1 | iex
Альтернатива — глобальный пакет npm (нужен Node.js 22 или новее, без sudo):
npm install -g @anthropic-ai/claude-code@latest
Откройте новое окно терминала и проверьте установку. Команда должна вывести номер версии; если терминал не
находит claude, каталог установки ещё не добавлен в PATH.
claude --version2. Получите Base URL и отдельный ключ у провайдера
- Отдельный ключ. Создайте ключ только для Claude Code и задайте ему лимит расходов — его проще отозвать, если он попадёт в чужие руки.
-
Base URL без суффикса. Нужен адрес вида
https://api.provider.example. Путь/v1/messagesClaude Code добавляет сам. - Точное название модели. У провайдеров оно может отличаться от официального — например, содержать префикс. Скопируйте его из кабинета провайдера.
3. Задайте переменные окружения
Введите Base URL и модель — генератор соберёт команды для вашей системы. Ключ сюда вводить не нужно: замените
заглушку sk-ваш-ключ уже в терминале.
Настройка Claude Code за 2 минуты
Работает с любым Anthropic-совместимым API-шлюзом. Подставьте свой Base URL.
# Переменные окружения для Claude Code (текущая сессия терминала) export ANTHROPIC_BASE_URL='https://your-api-gateway.example' export ANTHROPIC_AUTH_TOKEN='sk-ваш-ключ' export ANTHROPIC_MODEL='claude-opus-5-5' # Проверка подключения: один короткий запрос claude -p "Ответь одним словом: работает"
| Переменная | Заголовок запроса | Когда использовать |
|---|---|---|
ANTHROPIC_AUTH_TOKEN |
Authorization: Bearer |
Провайдер говорит о «bearer-токене» или не уточняет тип ключа |
ANTHROPIC_API_KEY |
x-api-key |
Провайдер говорит об «API-ключе» или заголовке x-api-key |
Переменные из export и $env: действуют только в текущем окне терминала и в
программах, запущенных из него.
4. Проверьте подключение
Сначала проверьте адрес и ключ напрямую — одним запросом на один токен. Bash или Zsh:
curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-opus-5-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'PowerShell:
Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
-Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
-ContentType "application/json" `
-Body '{"model": "claude-opus-5-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
Подставьте вместо claude-opus-5-5 название модели вашего провайдера. JSON-ответ, который
начинается с {"id":"msg_, означает, что адрес и ключ работают. Ошибка о неизвестной модели
тоже подтверждает, что авторизация пройдена. Код 401 — ключ отклонён: попробуйте вторую
переменную из таблицы выше.
Затем запустите Claude Code из того же терминала и отправьте короткий запрос:
claude -p "Ответь одним словом: работает"
В интерактивной сессии выполните /status: строка Anthropic base URL должна
показывать адрес провайдера, а строка Auth token или API key — заданную переменную.
5. Сохраните настройки
Чтобы настройки действовали во всех сессиях, перенесите их в блок env файла
~/.claude/settings.json (в Windows — %USERPROFILE%\.claude\settings.json):
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.provider.example",
"ANTHROPIC_AUTH_TOKEN": "sk-ваш-ключ",
"ANTHROPIC_MODEL": "claude-opus-5-5"
}
}.claude/settings.json внутри
репозитория попадает в коммиты и доступен всем, кто клонирует проект. Для одного проекта используйте
.claude/settings.local.json и убедитесь, что он добавлен в .gitignore.
Выбор и сопоставление моделей
Если названия моделей у провайдера отличаются от официальных, задайте их явно — иначе Claude Code запросит модель, которой у провайдера нет, и получит ошибку 404.
| Переменная | Что задаёт |
|---|---|
ANTHROPIC_MODEL |
Модель для запускаемой сессии |
ANTHROPIC_DEFAULT_SONNET_MODEL |
Во что раскрывается псевдоним sonnet |
ANTHROPIC_DEFAULT_OPUS_MODEL |
Во что раскрывается псевдоним opus |
ANTHROPIC_DEFAULT_HAIKU_MODEL |
Во что раскрывается псевдоним haiku; эта же модель обслуживает фоновые задачи, например заголовки сессий |
Приоритет выбора модели: команда /model, затем флаг --model, затем
ANTHROPIC_MODEL, затем параметр model в настройках.
Типичные ошибки и что с ними делать
| Симптом | Причина | Решение |
|---|---|---|
Ошибка 401 |
Ключ не принят или передан в заголовке, который провайдер не читает |
Проверьте ключ; замените ANTHROPIC_AUTH_TOKEN на ANTHROPIC_API_KEY или
наоборот
|
Ошибка 403 с HTML-страницей |
Запрос заблокировал межсетевой экран перед шлюзом: короткий curl проходит, а реальная сессия — нет | Сообщите провайдеру: путь /v1/messages нужно исключить из проверки тела запроса |
Ошибка 404 |
Лишний /v1 в Base URL или неверное название модели |
Уберите суффикс из адреса и задайте точное название модели через переменные из раздела выше |
Ошибка 429 |
Сработал лимит запросов у провайдера или закончился баланс | Проверьте баланс и лимиты ключа в кабинете провайдера |
| Ответ обрывается или «зависает» | Шлюз накапливает ответ вместо потоковой передачи либо вырезает служебные события SSE | Проверьте поток в форме проверки API; если TTFT не измеряется — обратитесь к провайдеру |
Ошибка 400 о неизвестных полях (Extra inputs are not permitted) |
Провайдер не принимает экспериментальные поля, которые отправляет Claude Code | Задайте CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 |
API returned an empty or malformed response (HTTP 200) |
По адресу отвечает не API, а, например, HTML-страница сайта или входа | Проверьте Base URL: он должен вести на API-эндпоинт, а не на сайт провайдера |
| Предупреждение о двух источниках авторизации | Одновременно активны ключ шлюза и сохранённый вход в аккаунт claude.ai | Выполните /logout, чтобы использовать ключ шлюза, или уберите переменную |
ANTHROPIC_API_KEY задан, но не используется |
Ключ требует разового подтверждения в интерактивной сессии; ранее отклонённый ключ игнорируется | Включите его в /config, пункт Use custom API key |
| Ошибки TLS-сертификата при успешном curl | Claude Code не доверяет центру сертификации, которому доверяет curl (часто из-за корпоративного прокси) | Укажите путь к набору сертификатов в NODE_EXTRA_CA_CERTS |
Вопросы о подключении Claude Code
Нужно ли добавлять /v1 в ANTHROPIC_BASE_URL?
Нет. Claude Code сам добавляет путь /v1/messages к Base URL. Если указать адрес с /v1 на конце, запросы уйдут на /v1/v1/messages и провайдер ответит ошибкой 404.
Чем отличаются ANTHROPIC_AUTH_TOKEN и ANTHROPIC_API_KEY?
ANTHROPIC_AUTH_TOKEN передаётся в заголовке Authorization: Bearer, а ANTHROPIC_API_KEY — в заголовке x-api-key. Если провайдер не уточнил, начните с ANTHROPIC_AUTH_TOKEN; при ошибке 401 попробуйте вторую переменную.
Почему Claude Code просит войти в аккаунт, хотя переменные заданы?
Скорее всего, переменные не дошли до процесса: они заданы в другом окне терминала или в настройках проекта, которые применяются только после подтверждения доверия к папке. Задайте их в том же терминале или в ~/.claude/settings.json и проверьте командой /status.
Можно ли использовать через шлюз модели не из семейства Claude?
Технически провайдер может сопоставить название модели с любой моделью, но Anthropic не поддерживает такую работу Claude Code, и часть функций может не работать. Совместимость конкретного эндпоинта проверяйте тестом и коротким запросом claude -p.
Безопасно ли вводить ключ на этой странице?
Генератор команд на этой странице не запрашивает ключ: в команду подставляется заглушка, которую вы заменяете сами в терминале. Ключ нужен только в форме проверки API, где он используется для одного запроса и не сохраняется.