Claude Code

Claude Code — CLI-агент Anthropic для работы с кодом в терминале: читает и правит файлы, запускает команды, работает с git и выполняет многошаговые задачи сам. Он обращается к Anthropic Messages API, а SpeShu.AI отдаёт этот же контракт на POST /api/v1/messages, поэтому вся настройка сводится к двум значениям: адресу шлюза и ключу.

Два значения задают всё остальное. Ключ создаётся в личном кабинете и кладётся в ANTHROPIC_AUTH_TOKEN. Адрес — ANTHROPIC_BASE_URL. Значение адреса — https://speshu.ai/api, без /v1: Claude Code сам дописывает к нему /v1/messages и в итоге обращается к https://speshu.ai/api/v1/messages — это и есть нужный эндпоинт. Ключ уходит в заголовке Authorization: Bearer, который API принимает наравне с X-Api-Key.

Установка

npm install -g @anthropic-ai/claude-code

Либо официальным установщиком на macOS, Linux и WSL:

curl -fsSL https://claude.ai/install.sh | bash

На нативном Windows установщик не работает — используйте WSL.

Ключ и идентификатор модели

Ключ показывается один раз — сохраните его сразу:

export SPESHU_API_KEY="sk-ваш-ключ"

Идентификатор текстовой модели не зашивайте в код: состав каталога меняется, и зашитый в конфиг идентификатор начинает падать с 404 not_found_error без предупреждения. Возьмите его из каталога:

cURL

export SPESHU_MODEL=$(curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[0].id')
echo "$SPESHU_MODEL"

.data[0] — первый элемент, чтобы пример был запускаемым; выбирайте по cost_completion, context_length и наличию зрения. Формат ответа — в разделе Каталог моделей, подбор под задачу — в Модели и цены.

Конфигурация

Переменные окружения

export ANTHROPIC_BASE_URL="https://speshu.ai/api"
export ANTHROPIC_AUTH_TOKEN="$SPESHU_API_KEY"

export ANTHROPIC_DEFAULT_SONNET_MODEL="$SPESHU_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$SPESHU_MODEL"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$SPESHU_MODEL"
export CLAUDE_CODE_SUBAGENT_MODEL="$SPESHU_MODEL"

Переменная	На что влияет
`ANTHROPIC_BASE_URL`	Адрес шлюза. Claude Code дописывает `/v1/messages`
`ANTHROPIC_AUTH_TOKEN`	Ключ в `Authorization: Bearer`
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Роль «основная модель» — код, анализ, правки
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Роль «сложная модель» — тяжёлые рассуждения
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Роль «быстрая модель» — фоновая работа, заголовки
`CLAUDE_CODE_SUBAGENT_MODEL`	Модель субагентов, запускаемых из сессии
`ANTHROPIC_MODEL`	Полное переопределение модели вместо ролей выше

Если в окружении остался ключ Anthropic в ANTHROPIC_API_KEY, Claude Code может уйти на api.anthropic.com. Либо уберите переменную, либо положите в неё тот же ключ SpeShu.AI — эндпоинт принимает и X-Api-Key, и Authorization: Bearer. Проверка: env | grep -i anthropic.

settings.json

Тот же набор в файле — он перекрывает окружение и не требует правки профиля оболочки.

Уровень	Путь
Пользовательский	`~/.claude/settings.json` (macOS, Linux, WSL)
Пользовательский	`%USERPROFILE%\.claude\settings.json` (Windows)
Проектный	`.claude/settings.json` в корне репозитория

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://speshu.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-ваш-ключ",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "<идентификатор из GET /api/v1/models>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "<идентификатор из GET /api/v1/models>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<идентификатор из GET /api/v1/models>",
    "CLAUDE_CODE_SUBAGENT_MODEL": "<идентификатор из GET /api/v1/models>"
  }
}

Не коммитьте settings.json с ключом в репозиторий: добавьте его в .gitignore или держите ключ только в переменных окружения. Файл пользовательских настроек лежит вне проекта и в git не попадает — безопаснее именно он.

Проверьте, что всё работает

Сначала убедитесь, что адрес и ключ дают рабочий ответ по тому пути, который собирает Claude Code:

cURL

curl -s https://speshu.ai/api/v1/messages \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$SPESHU_MODEL\",
    \"max_tokens\": 64,
    \"messages\": [{\"role\": \"user\", \"content\": \"Ответь одним словом: работает?\"}]
  }" | jq -r '.content[0].text, .stop_reason'

Правильный ответ — текст и stop_reason: "end_turn". Если здесь ошибка, Claude Code упадёт на том же месте. Затем запустите агента в проекте:

cd /path/to/your/project
claude

Внутри сессии выполните /status — он показывает, какой адрес и какая модель сейчас используются. Дайте агенту простую задачу, не требующую правок файлов: «Прочитай README.md в этом каталоге и перескажи его в двух предложениях». Если ответ пришёл, интеграция работает.

Разбор ответа /messages: обязательное поле max_tokens, отдельное поле system вместо роли system, формат ошибок в стиле Anthropic — в разделе Anthropic Messages.

Что Claude Code умеет через этот эндпоинт

Потоковая передача. Включена всегда и включать нечего: Claude Code сам просит stream: true и рисует ответ по мере поступления. Формат кадров, счётчики токенов и кадр со списанием — в гайде Потоковая передача. Инструменты. Файлы, shell-команды, поиск и правки Claude Code описывает как tools с input_schema, а ответ разбирает по блокам tool_use и stop_reason: "tool_use". Всё это нативный формат /messages, менять ничего не нужно. Полный цикл — в гайде Вызов функций. Изображения. Скриншот или картинку из проекта можно попросить описать: Claude Code отдаст её как блок image в content. Модель должна поддерживать зрение — иначе придёт 400 invalid_request на весь запрос, а не частичное игнорирование. Требования к входным данным — в гайде Медиаввод. Генерация изображений, видео и музыки. Встроенного инструмента для этого нет: медиа-API асинхронный, с оплатой при создании задачи и отдельным опросом статуса. Вариант — подключить его как MCP-сервер, тогда агент сможет вызывать POST /api/v1/async/media/tasks сам. Формат задачи — в разделе Создание задачи, подключение серверов — в гайде MCP.

Частые проблемы

404 на первом же сообщении

Проверьте ANTHROPIC_BASE_URL. Нужно https://speshu.ai/api — Claude Code сам дописывает /v1/messages. Значение https://speshu.ai/api/v1 даст путь /api/v1/v1/messages и тот же 404, как и адрес без /api вообще. Отладочная проверка: echo $ANTHROPIC_BASE_URL.

401 authentication_error

В ANTHROPIC_AUTH_TOKEN лежит не SpeShu-ключ, либо ключ отозван. Проверьте его отдельно от Claude Code: curl -s https://speshu.ai/api/v1/balance -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN". Пустой объект {} — корректный ответ для рабочего ключа, 401 — нет. Подробности — в разделе Аутентификация.

404 not_found_error: модель не найдена

Идентификатор устарел или скопирован с ошибкой. Возьмите его заново из GET /api/v1/models и подставьте как есть — без префикса и без обрезки. Удобно выбирать модель с поддержкой зрения и длинным контекстом, потому что Claude Code целиком загружает файлы в контекст.

400 invalid_request с текстом про деньги

Недостаток средств на /messages отдаётся как 400, а не 402 — так требует контракт Anthropic, чтобы SDK не перебрасывали код в другое исключение. Проверьте баланс через GET /api/v1/balance и пополните его в личном кабинете.

Агент отвечает, но не видит файлов проекта

Это не интеграция, а права: Claude Code ограничивает доступ к каталогам и запись в файлы. Проверьте, что вы запустили claude внутри проекта, а не в родительском каталоге, и при необходимости разрешите действия по подсказке в интерфейсе.

404 на запросе, которого не должно быть

Некоторые внутренние сценарии Claude Code (например, подсчёт токенов перед длинным запросом) обращаются к эндпоинтам вида count_tokens, которых в /api/v1 нет. Добавить эти эндпоинты мы не можем — ограничение на нашей стороне. Практический выход: держать сессии короче, а не искать обходной путь.

Всё остальное

Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки, таймауты и квоты — в разделе Лимиты.

Что дальше

Anthropic Messages

Контракт эндпоинта, к которому ходит Claude Code

Модели и цены

Как выбрать идентификатор под объём файлов

Вызов функций

Формат tool_use и tool_result

MCP

Медиа-задачи и ваши инструменты как серверы

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Установка

Ключ и идентификатор модели

Конфигурация

Переменные окружения

settings.json

Проверьте, что всё работает

Что Claude Code умеет через этот эндпоинт

Частые проблемы

Что дальше

Anthropic Messages

Модели и цены

Вызов функций

MCP

​Установка

​Ключ и идентификатор модели

​Конфигурация

​Переменные окружения

​settings.json

​Проверьте, что всё работает

​Что Claude Code умеет через этот эндпоинт

​Частые проблемы

​Что дальше

Anthropic Messages

Модели и цены

Вызов функций

MCP

Установка

Ключ и идентификатор модели

Конфигурация

Переменные окружения

settings.json

Проверьте, что всё работает

Что Claude Code умеет через этот эндпоинт

Частые проблемы

Что дальше