Поддерживает ли OpenCode пользовательский базовый URL?

Да. Вы указываете пользовательский провайдер в opencode.json, задав базовый URL, ключ и список моделей. Проверьте текущую документацию OpenCode для точных имён полей, так как они могут меняться между версиями.

Какой идентификатор модели следует ввести?

Введите uncensored точно так, как написано. Он должен совпадать с ключом в блоке models и ID, возвращаемым GET /v1/models.

Есть ли бесплатный способ протестировать настройку?

Новые пользователи могут получить $0.50 бесплатного пробного баланса одним нажатием на странице API-ключа после регистрации. Он действует 7 дней, не требует привязки карты и предоставляется один раз на человека.

Почему возникают ошибки 429 во время работы агента?

Агенты часто отправляют несколько запросов одновременно. Полный ключ позволяет 8 параллельных запросов и 300 в минуту, а пробный ключ — 2 и 60 соответственно. Уменьшите параллелизм или повторите запрос после задержки Retry-After.

OpenCode с API, совместимым с OpenAI: настройка

Что вам нужно перед началом

OpenCode — это кодовый агент с открытым исходным кодом, работающий в вашем терминале. Он может взаимодействовать со многими провайдерами моделей и позволяет добавить своего провайдера, если эндпоинт соответствует формату чата OpenAI. Этот API соответствует формату, поэтому настройка сводится к заполнению нескольких полей.

Сначала соберите эти три значения:

Базовый URL: https://api.kimicode.top/v1
Идентификатор модели: uncensored
API-ключ: создайте его на странице API-ключ. Новые аккаунты могут получить $0.50 бесплатного пробного баланса одним нажатием — этого достаточно для тестов ниже. Пробный ключ позволяет выполнять 2 одновременных запроса и 60 запросов в минуту.

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

export KIMICODE_API_KEY="your-key-here"

Шаг 1: тестирование эндпоинта через curl

Сделайте это до настройки любого инструмента. Если curl работает, а OpenCode нет, вы знаете, что проблема в конфигурации. Если curl не работает, вы исправляете ключ или URL один раз, а не в двух местах.

curl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Say hello in five words."}],
    "max_tokens": 40
  }'

Вы должны получить объект JSON с массивом choices и блоком usage. Ошибка 401 означает, что ключ неверен или отсутствует префикс Bearer. Ошибка 404 обычно означает, что URL введён неверно или уже содержит /chat/completions.

Кодовый агент использует потоковую передачу ответов и вызывает инструменты, поэтому проверьте и эти два параметра:

curl -N https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to five."}]
  }'

Вы должны увидеть серию строк data:, каждая из которых содержит небольшой дельта-объект JSON, завершающийся данными об использовании и финальным маркером. Флаг -N отключает буферизацию curl, чтобы фрагменты появлялись по мере поступления.

Шаг 2: добавление пользовательского провайдера в OpenCode

OpenCode считывает файл конфигурации JSON opencode.json из папки вашего проекта или из глобального каталога конфигурации. Пользовательские провайдеры в стиле OpenAI объявляются через совместимый с OpenAI пакет AI SDK, базовый URL и список моделей. Структура ниже соответствует публичной документации OpenCode на момент написания. Имена полей могут меняться между релизами, поэтому, если что-то не принимается, сверяйтесь с разделом провайдеров в текущей документации OpenCode.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kimicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kimicode API",
      "options": {
        "baseURL": "https://api.kimicode.top/v1",
        "apiKey": "{env:KIMICODE_API_KEY}"
      },
      "models": {
        "uncensored": {
          "name": "Uncensored",
          "limit": {
            "context": 100000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "kimicode/uncensored"
}

Ключ под models — это точный идентификатор модели, отправляемый на сервер, поэтому он должен быть uncensored. Последняя строка выбирает провайдера и модель по умолчанию, записываются как имя провайдера, слэш и затем идентификатор модели.

Форма {env:KIMICODE_API_KEY} говорит OpenCode читать переменную из вашей оболочки. Если ваша версия обрабатывает данные аутентификации через собственную команду входа, используйте этот путь и не добавляйте ключ в файл. В любом случае не добавляйте настоящий ключ в репозиторий.

Проектная или глобальная конфигурация

Вы можете хранить блок провайдера в двух местах. Файл в корневом каталоге проекта действует только для этого репозитория, что подходит команде, использующей общую конфигурацию. Файл в каталоге пользовательской конфигурации действует везде, что подходит для личных настроек по умолчанию. Если оба файла существуют, файл проекта дополняет или переопределяет глобальный.

Предпочитайте глобальный файл для определения провайдера и переменную окружения для ключа. Тогда каждый репозиторий сможет использовать эндпоинт, а ничего секретного не окажется рядом с вашим исходным кодом. Если над проектом работает несколько человек, добавляйте в репозиторий только блок провайдера без ключа, а каждый участник должен задать свою переменную. Это также упрощает смену ключа: измените переменную, перезапустите терминал, и файл конфигурации останется нетронутым.

Шаг 3: выбор модели и запуск задачи

Запустите OpenCode в папке проекта и откройте список выбора модели. Ваш пользовательский провайдер должен появиться в списке с отображаемым именем, которое вы задали. Выберите его, затем дайте агенту небольшую проверяемую задачу, например объяснение функции или написание модульного теста для короткого файла.

Начинайте с малого по двум причинам. Во-первых, вы можете увидеть, работают ли вызовы инструментов: когда OpenCode просит модель прочитать или отредактировать файл, она делает это через интерфейс вызова инструментов. Во-вторых, кодовый агент отправляет много текста за один ход, включая содержимое файлов и историю, поэтому длинная сессия быстро расходует токены. В следующем разделе приведены расчёты.

Если модель не отображается, проверьте, является ли файл допустимым JSON, находится ли он там, где OpenCode ищет конфигурацию, и совпадает ли имя провайдера с тем, что вы ввели в поле model.

Тестирование вызова инструментов и JSON-режима напрямую

OpenCode полагается на вызовы инструментов для чтения файлов, выполнения команд и редактирования кода, поэтому стоит подтвердить, что эндпоинт обрабатывает определение инструмента, прежде чем обвинять агента в сбое. Этот запрос предлагает один инструмент и задаёт вопрос, требующий его использования.

curl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "read_file",
        "description": "Read a text file by path",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Хороший ответ содержит запись tool_calls с именем read_file и строкой аргументов JSON. Агент выполняет инструмент, затем отправляет результат обратно как сообщение с role, установленным в tool, и модель продолжает работу. Если вы видите только обычный текст, попробуйте более прямой промпт, так как решение модели вызвать инструмент является частью её поведения.

JSON-режим — это отдельный переключатель. Добавление "response_format": {"type": "json_object"} запрашивает вывод валидного JSON, что помогает, если другой скрипт должен распарсить возвращаемые данные. Также укажите JSON в промпте, чтобы модель знала, какую структуру вы ожидаете.

Размер контекста и стоимость сессии

Контекстное окно составляет 100 000 токенов, считая промпт и ответ вместе. Установка limit.context в 100000 позволяет агенту знать реальный предел, чтобы он мог обрезать или сокращать или резюмировать историю до того, как сервер отклонит запрос. Ответ может занимать любой оставшийся объём, а max_tokens является необязательным.

Тарификация составляет $0,15 за 1 млн входных токенов и $0,50 за 1 млн выходных токенов. Агенты потребляют много входных данных, так как каждый ход заново отправляет всю переписку. Вот пример расчёта для умеренной сессии:

40 ходов, каждый из которых отправляет около 30 000 входных токенов: 1 200 000 входных токенов, что составляет 1,2 x $0,15 = $0,18.
Каждый ход возвращает около 800 выходных токенов: 32 000 выходных токенов, что составляет 0,032 x $0,50 = $0,016.
Итого: $0,196, то есть примерно двадцать центов за всю сессию.

Ваши цифры будут отличаться. Считывайте значения usage в ответах или следите за заголовком X-Balance-USD, который сообщает о вашем оставшемся балансе в каждом ответе. Кредит предоплаченный и не сгорает, а неудачные или отклонённые запросы не тарифицируются. Подробности на странице тарифов.

Честные ожидания от кодового агента

Это общая текстовая модель, настроенная на ответы без отказов в контенте для законного использования взрослыми. Это не модель, специально созданная для кода, и на этой странице нет заявлений о бенчмарках. То, насколько надёжно она редактирует ваш репозиторий, вы должны протестировать на своих задачах с включённым контролем версий, прежде чем доверять ей что-то важное.

Она обрабатывает инфраструктуру, необходимую агенту: вызов инструментов с потоковой передачей tool_calls, отправка результатов инструментов обратно как сообщения role: "tool" и JSON-режим через response_format. Она работает только с текстом, без изображений, поэтому функции, прикрепляющие скриншоты, не будут работать.

Два ограничения важны для агентов. Полный ключ позволяет 8 параллельных запросов и 300 запросов в минуту. Вспомогательные агенты или параллельные запуски инструментов, отправляющие множество вызовов одновременно, могут достичь предела параллелизма, а потоковый запрос удерживает слот до завершения потока. В этом случае вы получаете HTTP 429 с кодом concurrency. Код rate_limited означает превышение лимита запросов в минуту. При временной перегрузке вы также можете увидеть 429 с Retry-After: 5. Уменьшите параллелизм или подождите и повторите запрос.

Устранение неполадок

Симптом	Вероятная причина	Исправление
401 Unauthorized	Пустой или неверный ключ; переменная окружения не установлена в оболочке, в которой запущен OpenCode	Выполните `echo $KIMICODE_API_KEY` в том же терминале, затем перезапустите OpenCode
404 Not Found	Базовый URL содержит `/chat/completions` или не содержит `/v1`	Используйте точно `https://api.kimicode.top/v1`
Модель не найдена	Ключ модели отличается от `uncensored`	Сопоставьте ключ в `models` с идентификатором, возвращаемым запросом `GET /v1/models`
429 с `concurrency`	Слишком много запросов одновременно	Уменьшите количество параллельных вызовов инструментов или дождитесь завершения потоковой передачи
Запрос слишком большой	Тело запроса превышает 8 МБ или история приближается к пределу контекстного окна	Начните новый сеанс или сократите или резюмируйте историю

Для всего, что не описано здесь, полная справочная информация по запросам доступна на странице документации, а в руководстве по интеграции этот эндпоинт рассмотрен с точки зрения других клиентов, совместимых с OpenAI.