Windsurf: подключение к Claude и GPT

Сразу оговорка: на момент написания Windsurf не даёт указать свой base URL для всех моделей; проверьте актуальные настройки BYOK (свой ключ) в вашей версии. Если в вашей сборке есть поле Base URL для OpenAI-совместимого провайдера или для Anthropic, оба варианта работают через шлюз с одним и тем же ключом fetch_... — разница только в base URL и заголовках. Если такого поля нет, надёжная альтернатива — расширения Cline, Roo Code или Kilo Code в VS Code, где свой base URL задаётся штатно (см. https://zukko.pro/docs/ide-integrations/vscode-extensions↗).

Где искать настройки

В Windsurf это раздел управления моделями (Settings → Models / Cascade → Manage Models). Ищите там поля Base URL и API Key — для OpenAI-совместимого провайдера и/или для Anthropic. Ключ fetch_... вставляется без изменений, но без поля Base URL запросы не пойдут в шлюз, и ключ работать не будет; в этом случае используйте альтернативы из начала статьи.

OpenAI-совместимый вход: GPT и GLM

В поле Base URL нужно указать ровно:

Ключ — в поле API Key, как есть, вместе с префиксом fetch_. Windsurf сам добавит Authorization: Bearer и путь /chat/completions. Дальше в списке моделей или в поле произвольного названия модели вписываете точный id из каталога: gpt-5.6-sol, gpt-5.6-luna, glm-5.3, glm-5.3-flash (актуальный список — GET https://api.zukko.pro/v1/models).

Если Windsurf ограничивает выбор моделей выпадающим списком под конкретного провайдера и не даёт вписать своё имя — используйте поле "custom model" или аналогичное текстовое поле, которое есть у большинства сборок Windsurf для нестандартных провайдеров.

Anthropic-вход: Claude без лишнего /v1

Для Claude base URL — без /v1:

Это самое частое место ошибки: если скопировать тот же адрес, что и для OpenAI-совместимого поля, и дописать к нему /v1, все запросы к Claude через это поле начнут падать с 404, при этом ключ будет выглядеть принятым. Anthropic-клиенты сами достраивают путь до /v1/messages, поэтому суффикс лишний.

Модели для этого поля: claude-opus-5-5 и claude-sonnet-5.

Проверка вне IDE

Когда Windsurf молчит или не показывает внятный текст ошибки, быстрее проверить ключ напрямую curl'ом, в обход интерфейса:

curl https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-5","max_tokens":64,"messages":[{"role":"user","content":"тест"}]}'

Для OpenAI-совместимого пути:

curl https://api.zukko.pro/v1/chat/completions \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"тест"}]}'

Если оба ответа приходят нормально, а Windsurf всё равно не работает — проблема в самом IDE (кэш настроек, старая версия конфига, неправильное поле), а не в ключе или шлюзе. Помогает полный перезапуск Windsurf после смены Base URL — часть сборок кэширует список провайдеров при старте.

Типичные коды ошибок

Если curl вернул не ответ модели, а JSON с error, дальше разбираться проще:

• 401 — ключ не дошёл или искажён (лишний пробел при вставке — частая причина).
• 402, код insufficient_balance — баланс закончился, до модели запрос не доходил, повторный запрос после пополнения ничего не стоит сверх обычного.
• 404 c model_not_found — опечатка в id модели, сверьте с curl https://api.zukko.pro/v1/models (ключ не нужен).
• 400 c model_retired — модель сняли с каталога, в тексте ошибки указана замена.
• 503 c model_disabled — модель выключена в каталоге; выберите другую из /v1/models.
• 403 c model_not_allowed_for_key — на этом ключе в кабинете настроен список разрешённых моделей, и запрошенной в нём нет.

Веб-поиск для моделей без встроенного

GLM и часть моделей GPT в этом каталоге не имеют собственного веб-поиска, в отличие от некоторых режимов Claude. Если в Windsurf нужен ответ со свежими данными, а модель встроенного поиска не имеет, можно дернуть отдельный эндпоинт до основного запроса и подставить результат в промпт вручную:

curl https://api.zukko.pro/v1/web-search \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"query":"последние изменения в Windsurf changelog"}'

Сам Windsurf это не делает автоматически — это ручной приём для случаев, когда через API нужен более свежий контекст, чем знает модель.

Сколько всего потрачено на ключ

Историю списаний удобно смотреть отдельно от общего баланса — эндпоинт /v1/usage отдаёт историю с курсорной пагинацией. Учтите, что она общая на весь аккаунт: все ключи вместе, фильтра по ключу нет:

curl "https://api.zukko.pro/v1/usage?limit=20" \
  -H "Authorization: Bearer fetch_ваш_ключ"

Это удобно, когда в Windsurf одновременно работают несколько человек — по /v1/usage видно, на какие модели и запросы ушли деньги, а не только итоговый остаток. Актуальные лимиты и цены по каждой модели — в GET /v1/models/info, тоже без ключа.

Лимиты, стоимость и что смотреть в кабинете

Каждый ключ можно ограничить дневным или месячным лимитом расхода в долларах прямо со страницы ключа в кабинете (https://zukko.pro/app/api-keys) — полезно завести отдельный ключ под Windsurf с собственным лимитом, чтобы эксперименты в IDE не съедали общий баланс. В обычных (не потоковых) ответах есть заголовки X-Zukko-Cost-Micros (стоимость именно этого запроса в микродолларах) и X-Fetch-Balance-Cents (остаток после списания, тоже в микродолларах, несмотря на название) — через curl их видно с флагом -i. У потоковых ответов, которые получает IDE, этих заголовков нет — там расход смотрите в кабинете или /v1/usage.

Если это первое подключение и баланс нулевой, получить $0.50 на тесты можно один раз: привязать Telegram в кабинете, подписаться на канал @zukkopro↗ и нажать «Проверить». Стартового баланса нет. Пополнение картой, через СБП или крипту (от $1) доступно на странице /app/payments.