Как настроить Cursor, Claude Code и Codex на пользовательский API endpoint
Пошаговая настройка маршрутизации запросов Cursor, Claude Code, OpenAI Codex и Zed через пользовательский OpenAI-совместимый API endpoint. Охватывает настройку base URL, маппинг model ID, заголовки авторизации, проблемы streaming и продакшн-чеклист для команд, использующих LLM-шлюз или router.
Все основные AI-инструменты для кодинга в 2026 году поддерживают пользовательские API endpoint. Это означает, что вы можете направить Cursor, Claude Code, OpenAI Codex и Zed на собственный шлюз — будь то self-hosted proxy, коммерческий LLM router или unified API layer — и маршрутизировать каждый запрос через один base URL. Это даёт provider fallback, отслеживание расходов, контроль доступа на уровне моделей и один API key для управления всей командой.
Это руководство описывает точные шаги настройки для каждого инструмента, типичные ловушки при первой настройке и продакшн-чеклист для команд, разворачивающих пользовательские endpoint в масштабе.
OpenAI-совместимость означает, что провайдер предоставляет endpoint chat-completions, чей контракт запроса и ответа достаточно близок к API OpenAI, чтобы немодифицированный вызов OpenAI SDK работал после замены трёх значений: API key, base URL, название модели. Минимальная поверхность на практике —POST /v1/chat/completions с messages, model и потоковым ответом в форме OpenAI.
Зачем использовать пользовательский API endpoint
Прежде чем перейти к настройке, вот причины, по которым команды заменяют URL провайдеров по умолчанию на пользовательский endpoint:
- Fallback между провайдерами. Если OpenAI вернёт 429 или 503, ваш router автоматически повторит запрос через Anthropic, DeepSeek или DashScope — без изменения кода. Подробнее — в нашем руководстве по fallback-маршрутизации.
- Единый биллинг. Один счёт вместо пяти. Один набор API key вместо отдельного для каждого провайдера.
- Контроль доступа на уровне моделей. Определяйте, какие модели может использовать каждая команда или проект, устанавливайте бюджетные лимиты, проводите аудит каждого запроса.
- Оптимизация затрат. Маршрутизируйте простые задачи на дешёвые модели, сложные — на frontier-модели — через один
base_url. Наше руководство по оптимизации затрат раскрывает тему подробно. - Observability. Видьте каждый запрос, latency, количество токенов и ошибки в одном dashboard вместо пяти консолей провайдеров.
Если вы используете только одного провайдера и не нуждаетесь в маршрутизации, пользовательский endpoint лишь добавит сложность. Но как только вы используете двух и более провайдеров — или вам нужен контроль на уровне команды — шлюз быстро себя окупает.
Шаг 1: Настройка пользовательского API endpoint в Cursor
Cursor поддерживает пользовательские OpenAI-совместимые endpoint через встроенный UI настроек. Настройка находится в Cursor Settings → Models.
Шаги настройки
- Откройте Cursor и нажмите
Cmd+Shift+J(macOS) илиCtrl+Shift+J(Windows/Linux) для открытия Cursor Settings. - Перейдите в раздел Models.
- Включите OpenAI API Key и введите ключ вашего шлюза.
- Включите Override OpenAI Base URL.
- Введите URL вашего endpoint — например,
https://your-gateway.example.com/v1. - Добавьте пользовательские имена моделей в список. Нажмите + Add Model и введите model ID, который ожидает ваш шлюз (например,
gpt-5.6-terra,claude-opus-4,deepseek-v4-flash). - Нажмите Verify для проверки соединения.
Подводные камни Cursor
Совместимость с HTTP/2. Если после установки base URL появляются ошибки соединения, перейдите в Cursor Settings → Network → HTTP Compatibility Mode и переключитесь на HTTP/1.1. Многие reverse proxy и шлюзы не поддерживают HTTP/2, а Cursor использует его по умолчанию. Это самый частый источник проблем, о котором сообщают на форуме Cursor.
Не все функции используют ваш ключ. Даже с включённым пользовательским API key некоторые функции Cursor — включая Tab Completion и Apply from Chat — по-прежнему используют собственные модели Cursor. Ваш endpoint обрабатывает только chat- и agent-запросы для моделей, которые вы явно добавили.
Маппинг model ID. Cursor отправляет ровно тот model ID, который вы ввели в списке моделей. Если шлюз ожидает openai/gpt-5.6-terra, а вы ввели gpt-5.6-terra, запрос не пройдёт. Убедитесь, что ID совпадает с форматом шлюза.
Ограничение subagent. Пользовательские модели, настроенные через Override Base URL, могут быть недоступны в subagent-потоках Cursor. Если фоновые агенты молча откатываются на модели Cursor, это известное ограничение по состоянию на середину 2026 года.
Шаг 2: Настройка пользовательского endpoint в Claude Code
Claude Code поддерживает пользовательские endpoint через переменные окружения. Два ключевых параметра:
| Переменная | Назначение |
|---|---|
ANTHROPIC_BASE_URL | Переопределить endpoint Anthropic API по умолчанию |
ANTHROPIC_API_KEY | Ваш API key (или ключ шлюза) |
Шаги настройки
Вариант A: Переменные окружения shell (быстрый старт)
export ANTHROPIC_BASE_URL="https://your-gateway.example.com/v1"
export ANTHROPIC_API_KEY="your-gateway-key"
claude
Вариант B: Файл настроек Claude Code (постоянно)
Добавьте переменные в ~/.claude/settings.json:
{
"env": {
"ANTHROPIC_BASE_URL": "https://your-gateway.example.com/v1",
"ANTHROPIC_API_KEY": "your-gateway-key"
}
}
Вариант C: Управляемые настройки для команд
Для корпоративных развёртываний распространяйте управляемый файл настроек с предустановленным URL шлюза. Документация Claude Code по LLM-шлюзам описывает, как передать конфигурацию через систему управления, чтобы каждый разработчик автоматически получил одинаковый endpoint.
Подводные камни Claude Code
Нативный формат Anthropic vs OpenAI-совместимый. Claude Code по умолчанию использует Anthropic Messages API, а не формат chat completions от OpenAI. Если ваш шлюз обрабатывает только OpenAI-совместимые запросы, нужен шлюз, умеющий транслировать между двумя форматами — или используйте Anthropic напрямую.
OPENAI_BASE_URL для моделей OpenAI. Если вы хотите, чтобы Claude Code вызывал модели OpenAI (через флаг --model с OpenAI model ID), установите OPENAI_BASE_URL. Claude Code использует правильную переменную base URL в зависимости от провайдера модели.
AWS Bedrock и Google Vertex. Claude Code также поддерживает переменные окружения CLAUDE_CODE_USE_BEDROCK=1 и CLAUDE_CODE_USE_VERTEX=1 для облачного Claude. Если вы маршрутизируете через AWS или Google, используйте их вместо ANTHROPIC_BASE_URL.
Шаг 3: Настройка пользовательского endpoint в OpenAI Codex CLI
OpenAI Codex CLI читает конфигурацию из ~/.codex/config.toml. Пользовательские endpoint настраиваются как именованные model provider.
Шаги настройки
- Установите Codex CLI:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
- Создайте или отредактируйте
~/.codex/config.toml:
model = "gpt-5.6-terra"
model_provider = "my-gateway"
[model_providers.my-gateway]
name = "my-gateway"
base_url = "https://your-gateway.example.com/v1"
env_key = "MY_GATEWAY_API_KEY"
wire_api = "responses"
[projects."/path/to/your/project"]
trust_level = "trusted"
- Установите API key:
export MY_GATEWAY_API_KEY="your-gateway-key"
- Запустите Codex:
codex
Подводные камни Codex
Настройка wire_api. Codex поддерживает два формата: "responses" (новый Responses API от OpenAI) и "chat_completions" (стандартный /v1/chat/completions). Если ваш шлюз поддерживает только chat completions, установите wire_api = "chat_completions". Неправильная настройка приводит к непонятным 404-ошибкам, потому что Codex пытается отправить POST на /v1/responses.
Profiles для нескольких endpoint. Codex поддерживает именованные profiles в config.toml. Вы можете определить несколько блоков [model_providers.*] и переключаться между ними командой codex --profile <name>. Это удобно, когда для dev и production используются разные шлюзы.
Stream idle timeout. Для длительных запросов на рассуждение увеличьте stream_idle_timeout_ms в конфигурации провайдера. Значение по умолчанию может быть слишком маленьким для моделей, которые думают 30+ секунд:
[model_providers.my-gateway]
stream_idle_timeout_ms = 120000
stream_max_retries = 5
Шаг 4: Настройка пользовательского endpoint в Zed
Zed поддерживает пользовательские OpenAI-совместимые провайдеры через JSON-настройки.
Шаги настройки
- Откройте настройки Zed (
Cmd+,на macOS). - Перейдите в Agent Settings и добавьте пользовательского OpenAI-совместимого провайдера.
- Или отредактируйте
~/.config/zed/settings.jsonнапрямую:
{
"language_models": {
"openai": {
"api_url": "https://your-gateway.example.com/v1",
"available_models": [
{
"name": "gpt-5.6-terra",
"display_name": "GPT-5.6 Terra (via Gateway)",
"max_tokens": 128000
}
]
}
}
}
- Установите API key через переменную окружения
OPENAI_API_KEYили хранилище учётных данных Zed.
Подводные камни Zed
Блоки конфигурации провайдеров. У Zed отдельные блоки конфигурации для разных провайдеров (openai, anthropic, google). Если ваш шлюз обрабатывает несколько провайдеров через один base URL, настраивайте его в блоке openai — он поддерживает пользовательский api_url.
Доступность моделей. Вы должны явно перечислить доступные модели в массиве available_models. Zed не обнаруживает модели автоматически через шлюз.
Общие проблемы для всех инструментов
Формат заголовка авторизации
Большинство инструментов для кодинга отправляют API key как Bearer token в заголовке Authorization:
Authorization: Bearer sk-your-key-here
Если ваш шлюз ожидает другую схему авторизации (например, заголовок X-Api-Key), потребуется тонкий слой proxy для трансляции заголовков. Большинство коммерческих шлюзов и router принимают стандартные Bearer-токены.
Маппинг model ID
Model ID, отправляемый инструментом, должен точно совпадать с тем, что ожидает шлюз. Типичные несовпадения:
| Инструмент отправляет | Шлюз ожидает | Решение |
|---|---|---|
gpt-5.6-terra | openai/gpt-5.6-terra | Добавьте префикс провайдера в конфигурации инструмента |
claude-opus-4 | anthropic/claude-opus-4 | Добавьте префикс или настройте шлюз принимать оба формата |
deepseek-v4-flash | deepseek/deepseek-v4-flash | Аналогично — добавьте namespace провайдера |
Совместимость streaming
Все четыре инструмента по умолчанию используют streaming-ответы (stream: true). Ваш шлюз должен поддерживать Server-Sent Events (SSE) streaming. Если он поддерживает только non-streaming, вы увидите ошибки timeout или пустые ответы. Проверьте документацию шлюза на предмет поддержки streaming.
Rate limit и повторные попытки
При маршрутизации через шлюз действуют его rate limit, а не провайдера. Если ваш шлюз ограничивает 60 RPM, а Cursor agent отправляет 80 запросов в минуту, вы получите 429-ошибки, даже если провайдер бы их пропустил. Настройте rate limit шлюза под ожидаемую нагрузку. Подробнее — в нашем сравнении rate limit.
Продакшн-чеклист для команд
Перед развёртыванием пользовательских endpoint для команды проверьте каждый пункт:
- Шлюз доступен со всех машин разработчиков (VPN, правила firewall, DNS).
- SSL-сертификат валиден и доверен. Самоподписанные сертификаты вызывают тихие сбои в большинстве инструментов.
- Ротация API key возможна без обновления локальной конфигурации каждого разработчика. Используйте переменные окружения или менеджер секретов.
- Model ID задокументированы. Опубликуйте список доступных model ID и какой провайдер стоит за каждым.
- Fallback-поведение протестировано. Симулируйте сбой провайдера и убедитесь, что шлюз маршрутизирует на резерв.
- Streaming работает end-to-end. Отправьте длинный prompt и убедитесь, что токены приходят инкрементально.
- Режим HTTP/1.1 включён в Cursor, если шлюз не поддерживает HTTP/2.
- Мониторинг затрат настроен. Убедитесь, что dashboard шлюза показывает использование токенов по моделям и пользователям.
- Rate limit настроены под размер команды и паттерны использования.
- Значения timeout подходят для reasoning-моделей, которые могут думать 60+ секунд.
Интеграция с TheRouter
TheRouter маршрутизирует OpenAI-совместимые запросы через настроенных провайдеров и поддерживает provider/model routing и fallback. Чтобы направить любой из вышеперечисленных инструментов на TheRouter:
- Используйте base URL TheRouter как пользовательский endpoint (например,
https://api.therouter.ai/v1). - Используйте API key TheRouter как API key.
- Используйте model ID из каталога моделей TheRouter — они автоматически маппятся на соответствующих провайдеров.
TheRouter берёт на себя разрешение model-to-provider, поэтому не нужно беспокоиться о префиксах провайдеров. Один base_url даёт доступ к OpenAI, Anthropic, DeepSeek, DashScope и другим провайдерам через один endpoint. Полное руководство по миграции — в нашем гайде по миграции с OpenAI на TheRouter.
FAQ
Можно ли использовать один endpoint для всех четырёх инструментов?
Да, если ваш шлюз поддерживает OpenAI-совместимый формат chat completions. Cursor, Codex и Zed используют формат OpenAI. Claude Code по умолчанию использует формат Anthropic, поэтому шлюзу нужно уметь обрабатывать оба — или вы настраиваете Claude Code на использование OpenAI-совместимых моделей через OPENAI_BASE_URL.
Шлюз будет видеть весь мой код?
Да. Каждый prompt, который отправляет инструмент — включая содержимое файлов, инструкции и контекст — проходит через ваш шлюз. Выбирайте шлюз, которому вы доверяете свою кодовую базу. По вопросам безопасности — наше руководство по governance для coding agent.
Что произойдёт, если шлюз упадёт?
Большинство инструментов покажут ошибку соединения и перестанут работать до восстановления шлюза. Они не откатываются автоматически на прямой endpoint провайдера. Некоторые шлюзы поддерживают health check и автоматический failover на резервные endpoint — настраивайте это на уровне шлюза, а не в инструменте.
Это работает с локальными моделями (Ollama, vLLM)?
Да. Любой endpoint, поддерживающий формат OpenAI chat completions, подойдёт. Укажите base URL на http://localhost:11434/v1 для Ollama или URL вашего vLLM-сервера. Model ID должны совпадать с тем, что предоставляет локальный сервер.
Источники: Cursor Settings & Custom API Keys (получено 2026-07-29), Claude Code environment variables (получено 2026-07-29), Claude Code LLM gateway docs (получено 2026-07-29), OpenAI Codex CLI advanced configuration (получено 2026-07-29), LiteLLM Codex tutorial (получено 2026-07-29), Zed API access docs (получено 2026-07-29), Cursor forum: Override Base URL issues (получено 2026-07-29), Cursor forum: Subagent limitation (получено 2026-07-29)