Документация

Быстрый старт

Базовый URL — https://api.modelproxy.org/v1. Получите ключ в личном кабинете и отправьте первый запрос:

curl https://api.modelproxy.org/v1/chat/completions \
  -H "Authorization: Bearer mp-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Привет"}]}'

Тот же базовый URL работает со стандартным SDK openai: достаточно задать base_url. Настраиваете агента — начните с раздела «Общие настройки», дальше идут пошаговые инструкции для каждого инструмента.

Ключи и авторизация

Ключи создаются и отзываются в разделе API-ключи. Полный ключ показывается один раз — сразу после создания; в списке остаётся только префикс. Отозванный ключ перестаёт работать немедленно.

Оба заголовка авторизации равнозначны, выбирайте тот, который использует ваш клиент:

Если переданы оба заголовка, приоритет у Authorization. Расход по каждому ключу виден в разделе Использование.

Доступ из России

При подключении из России можно использовать https://ru.api.modelproxy.org: тот же ключ, те же пути и форматы ответов — меняется только адрес. Для всех остальных канонический адрес остаётся https://api.modelproxy.org. Адрес выбираете вы: по региону запросы не перенаправляются.

Правило про /v1 сохраняется: у OpenAI-совместимого базового URL он остаётся, у Anthropic-совместимого его нет.

export OPENAI_BASE_URL="https://ru.api.modelproxy.org/v1"
export ANTHROPIC_BASE_URL="https://ru.api.modelproxy.org"

OpenAI-совместимый endpoint

curl https://api.modelproxy.org/v1/chat/completions \
  -H "Authorization: Bearer mp-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Привет"}],"stream":true}'

Что важно знать:

• Для Codex-моделей max_tokens удаляется перед upstream-запросом; расход ограничивается серверным kill switch.
• Prompt caching выполняется провайдером автоматически: параметры управления кэшем (например prompt_cache_retention) удаляются, cache-read токены учитываются в usage и тарифицируются по каталогу.
• response_format с json_schema поддерживается; режим json_object не транслируется — используйте json_schema.
• Если модель не принимает принудительный tool_choice, значения required и указание конкретной функции транслируются в auto, а требование вызвать инструмент передаётся модели текстом. Запрос выполняется, а не отклоняется; поддержку можно проверить в capabilities.forced_tool_choice ответа /v1/models.

Anthropic-совместимый endpoint

curl https://api.modelproxy.org/v1/messages \
  -H "x-api-key: mp-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-fable-5","max_tokens":1024,"messages":[{"role":"user","content":"Привет"}]}'

Что важно знать:

• Extended thinking поддерживается, но при принудительном tool_choice (тип any или tool) параметр thinking отключается — upstream отклоняет эту комбинацию.
• cache_control передаётся нативно.
• При cross-provider запросе (модель другого провайдера на этом endpoint) параметры транслируются через общий внутренний формат: streaming, tools, изображения, system-сообщения и reasoning сохраняются; json_object эквивалента не имеет.

Общие настройки

Инструкции проверены по официальным источникам: 27 августа 2026. Установка и формат настроек у сторонних инструментов меняются между релизами: если команда не совпадает, сверьтесь с документацией инструмента.

Всем агентам нужны два значения: базовый URL и ключ. Ключ создаётся в разделе API-ключи и показывается один раз — сохраните его сразу.

Держите ключ в переменной окружения, чтобы он не попал в конфигурационные файлы репозитория:

export MODELPROXY_API_KEY="mp-your-key"

Проверить ключ можно одним запросом — он вернёт список доступных моделей:

curl -s https://api.modelproxy.org/v1/models \
  -H "Authorization: Bearer $MODELPROXY_API_KEY"

401 — неверный или отозванный ключ, 402 — недостаточно баланса; остальные коды в разделе «Лимиты и ошибки». Значения для поля model — в разделе «Модели и цены».

Claude Code

Терминальный агент Anthropic. С внешним провайдером говорит только в формате Anthropic Messages, поэтому базовый URL указывается без /v1.

1. Установка

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

2. Настройка

export ANTHROPIC_BASE_URL="https://api.modelproxy.org"
export ANTHROPIC_AUTH_TOKEN="mp-your-key"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"
claude

ANTHROPIC_DEFAULT_HAIKU_MODEL переводит фоновые запросы Claude Code — генерацию заголовка сессии и обработку страниц, полученных через WebFetch, — на недорогую Claude Haiku 4.5. Без неё клиент через сторонний адрес выполняет их основной моделью сессии и по её цене. Проверку действий в режиме auto клиент в любом случае выполняет моделью Claude Sonnet 5. Модель самой сессии переменная не меняет: её по-прежнему выбирают /model или --model.

Ограничение на длину ответа берётся из каталога: у текущих моделей Anthropic это 128000 токенов вывода, поэтому значение Claude Code по умолчанию (64000) проходит без настройки. На модели с меньшим лимитом сервис ответит 400 и назовёт её точный предел — уменьшите CLAUDE_CODE_MAX_OUTPUT_TOKENS до этого значения.

Те же значения можно записать в ~/.claude/settings.json, в блок env. Файл с ключом не коммитьте: для проектных настроек есть .claude/settings.local.json.

3. Модель

Имя модели клиент не проверяет — оно передаётся как есть. Выберите модель командой /model или при запуске:

claude --model claude-fable-5

4. Проверка

Команда /status внутри claude покажет базовый URL и переменную, из которой взят ключ. Разовый неинтерактивный запуск:

claude --bare -p "Ответь одним словом: OK"

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

Codex / Codex CLI

Codex — семейство продуктов OpenAI: агент в приложении ChatGPT, расширение для IDE, облачный Codex и терминальный Codex CLI. Свой провайдер читают только CLI и расширение для IDE, из общего файла настроек; облачный Codex работает исключительно через инфраструктуру OpenAI.

С внешним провайдером Codex говорит единственным протоколом — OpenAI Responses API; значение wire_api = "chat" из клиента удалено. ModelProxy отдаёт Responses на https://api.modelproxy.org/v1 рядом с Chat Completions и Anthropic Messages.

1. Установка

npm install -g @openai/codex
codex --version

2. Настройка

Ключ берётся из переменной окружения, названной в env_key — в самом файле его писать не нужно:

model = "gpt-5.5"
model_provider = "modelproxy"

[model_providers.modelproxy]
name = "ModelProxy"
base_url = "https://api.modelproxy.org/v1"
env_key = "MODELPROXY_API_KEY"
wire_api = "responses"

Имя провайдера выбирается свободно, кроме зарезервированных openai, ollama и lmstudio. Блок model_providers читается только из пользовательского ~/.codex/config.toml: в проектном файле он игнорируется.

3. Модель

Значение model из файла переопределяется для одного запуска; полный список — в разделе «Модели и цены».

codex --model gpt-5.5

4. Проверка

export MODELPROXY_API_KEY="mp-your-key"
codex exec --skip-git-repo-check "Ответь одним словом: OK"

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

Проверено: 28 августа 2026, codex-cli 0.150.1: клиент выполнил задание с правкой файла через /v1/responses.

Cursor

Редактор (Cursor IDE)

Свой ключ задаётся только в интерфейсе: Cursor Settings → Models. Официально принимаются ключи OpenAI, Anthropic, Google, Azure OpenAI и AWS Bedrock — ключ уходит своему провайдеру.

Чтобы запросы шли в ModelProxy, нужен ещё и переопределённый базовый URL. Такой настройки нет в официальной документации Cursor: она известна по сообщениям пользователей, и по ним же ломает встроенные Anthropic-модели.

Официальные ограничения:

• Свой ключ работает только с чат-моделями. Автодополнение (Tab) остаётся на моделях Cursor.
• Запросы идут через облако Cursor, поэтому адрес должен быть публично доступен: api.modelproxy.org подходит, локальный прокси — нет.
• Отдельного поля для Anthropic-совместимого адреса нет.
• Политика Zero Data Retention со своим ключом не действует.

Проверки соединения Cursor не показывает: с неверным ключом запросы перестают выполняться. Живой ли ключ — проверьте запросом из «Общих настроек».

Cursor CLI — подключить нельзя

Установщик curl https://cursor.com/install -fsS | bash ставит agent и cursor-agent — это одна программа, и ни одна её настройка не ведёт в ModelProxy.

Ловушка — флаг -e, --endpoint и переменная CURSOR_API_ENDPOINT: это адрес бэкенда Cursor, не провайдера моделей. Первым же запросом клиент идёт в POST /auth/exchange_user_api_key — обменять ключ аккаунта Cursor.

• В ~/.cursor/cli-config.json нет полей провайдера и базового URL — только интерфейс и разрешения.
• Единственная сторонняя интеграция — AWS Bedrock (agent bedrock), а не произвольный OpenAI-совместимый адрес.
• Сотрудники Cursor подтверждали на форуме (17.01.2026): CLI авторизуется только через аккаунт Cursor.

Проверено: 27 августа 2026, cursor-agent 2026.08.25-3e8eec8. Симптом при попытке подключения: 404 на POST /auth/exchange_user_api_key.

Kilo Code

Расширение для VS Code и терминальный клиент с общим файлом настроек. Работает по OpenAI-совместимому протоколу.

1. Установка

npm install -g @kilocode/cli

2. Настройка

В расширении: Settings → Providers → Custom provider, тип API — «OpenAI Compatible», базовый URL https://api.modelproxy.org/v1, ключ — ваш mp-…. То же самое файлом, ~/.config/kilo/kilo.jsonc:

{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "openai-compatible/gpt-5.5",
  "provider": {
    "openai-compatible": {
      "options": {
        "apiKey": "{env:MODELPROXY_API_KEY}",
        "baseURL": "https://api.modelproxy.org/v1"
      },
      "models": {
        "gpt-5.5": {
          "name": "ModelProxy",
          "tool_call": true,
          "limit": { "context": 128000, "output": 16384 }
        }
      }
    }
  }
}

3. Проверка

kilo run --auto "Ответь одним словом: OK"

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

Pi

Минималистичный терминальный агент. Умеет и OpenAI-, и Anthropic-совместимые провайдеры.

1. Установка

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

2. Настройка

Файл ~/.pi/agent/models.json — строгий JSON, комментарии в нём недопустимы. Запись $MODELPROXY_API_KEY означает «взять из переменной окружения»:

{
  "providers": {
    "modelproxy": {
      "baseUrl": "https://api.modelproxy.org/v1",
      "api": "openai-completions",
      "apiKey": "$MODELPROXY_API_KEY",
      "models": [
        { "id": "gpt-5.5", "contextWindow": 128000, "maxTokens": 16384 }
      ]
    }
  }
}

Для Anthropic-совместимого канала укажите "api": "anthropic-messages" и базовый URL https://api.modelproxy.org.

3. Проверка

pi --model modelproxy/gpt-5.5 --no-session -p "Ответь одним словом: OK"

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

omp.sh

Терминальный агент omp («oh-my-pi») — ответвление Pi с собственным набором инструментов. Настраивается на OpenAI-совместимый провайдер.

1. Установка

curl -fsSL https://omp.sh/install | sh
omp --version

2. Настройка

Файл ~/.omp/agent/models.yml. В поле apiKey можно указать имя переменной окружения — тогда сам ключ в файл не попадает:

providers:
  modelproxy:
    baseUrl: https://api.modelproxy.org/v1
    api: openai-completions
    apiKey: MODELPROXY_API_KEY
    models:
      - id: gpt-5.5
        name: ModelProxy
        contextWindow: 128000
        maxTokens: 16384

3. Проверка

omp models
omp -p "Ответь одним словом: OK" --model modelproxy/gpt-5.5

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

Hermes Agent

Автономный агент Nous Research. Поддерживает оба протокола: chat_completions и anthropic_messages.

1. Установка

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

2. Настройка

Файл ~/.hermes/config.yaml; секреты Hermes хранит отдельно, в ~/.hermes/.env, поэтому в конфиге указывается только имя переменной:

providers:
  modelproxy:
    api: https://api.modelproxy.org/v1
    key_env: MODELPROXY_API_KEY
    transport: chat_completions
model:
  default: gpt-5.5
  provider: custom:modelproxy

3. Проверка

hermes doctor
hermes -z "Ответь одним словом: OK"

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

OpenClaw

Персональный ассистент, работающий как постоянный шлюз к мессенджерам. Модель подключается своим провайдером; поддерживаются оба протокола.

1. Установка

npm install -g openclaw@latest --allow-scripts=openclaw

2. Настройка

Файл ~/.openclaw/openclaw.json в формате JSON5 (допустимы комментарии). Каждая модель должна быть явно перечислена в models — иначе агент откажется её использовать:

{
  agents: { defaults: { model: { primary: "modelproxy/gpt-5.5" } } },
  models: {
    mode: "merge",
    providers: {
      modelproxy: {
        baseUrl: "https://api.modelproxy.org/v1",
        apiKey: "${MODELPROXY_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.5", name: "ModelProxy",
            contextWindow: 128000, maxTokens: 16384 }
        ]
      }
    }
  }
}

3. Проверка

openclaw agents list
openclaw agent --local --agent main --message "Ответь одним словом: OK" --json

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

Что не стоит делать с ключом

• Не коммитьте конфигурационные файлы с ключом: почти каждый агент умеет читать ключ из переменной окружения — используйте эту возможность.
• Ключ показывается один раз. Если он утёк, отзовите его в личном кабинете — отзыв действует немедленно — и создайте новый.

Модели и цены

Значения, которые принимает поле model, и их цены за 1 млн токенов — те же, что в таблице на главной. Таблица обновляется автоматически из каталога сервиса; здесь только модели, доступные для вызова прямо сейчас — тот же набор, что возвращает GET /v1/models. Любая модель из этой таблицы вызывается на любом из описанных выше endpoint'ов: провайдера выбирает модель, формат ответа — endpoint.

Цены публикуются отдельно от доступности: модель может быть доступна для вызова раньше, чем для неё опубликован тариф, — тогда в её строке вместо цены стоит «не опубликована». Списание идёт по фактическому расходу токенов, каждая составляющая округляется вверх до копейки.

Модель, которая ещё проходит проверку или отключена оператором, в таблице не появляется: неизвестный или отключённый идентификатор возвращает 404 model_not_found.

Лимиты и ошибки

Фиксированных лимитов запросов на ключ нет. Максимальный размер тела запроса — 10 МБ.

При сетевой ошибке до первого байта ответа запрос автоматически повторяется, до 3 попыток.