К содержимому
Блог

OpenClaw: установка и подключение к API Relay

OpenClaw: установка и подключение к API Relay

Установка OpenClaw и подключение модели требуют двух отдельных действий. Сначала установите клиент по официальному руководству для своей системы, затем добавьте провайдера Relay с адресом https://relay-llm.ru/v1, ключом и ID модели. После настройки проверьте простой текстовый запрос, прежде чем подключать каналы сообщений и автоматические действия.

Как установить OpenClaw и проверить запуск

Откройте руководство OpenClaw в документации Relay. На странице есть ссылки на официальный сайт и инструкцию установки. Возьмите способ для вашей ОС и проверьте требования к среде выполнения. Не подставляйте случайную команду из выдачи по запросу OpenClaw install: пакет с похожим именем может относиться к другому проекту.

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

Определите, как будет работать Gateway: в вашем терминале или фоновой службой. От этого зависит передача секрета. Переменная, заданная в интерактивной оболочке, не обязана попадать в уже установленную службу. Запишите способ запуска до того, как начнёте искать ошибку ключа.

Как добавить провайдера Relay

Выберите в каталоге модель с Chat Completions. Для примера ниже подходит gpt-5.6-luna. Базовый текстовый запрос всё равно проверьте отдельно от агентного сценария.

Для новой настройки используйте структуру ниже в ~/.openclaw/openclaw.json. Если файл уже существует, добавьте соответствующие поля в него, не заменяя остальные настройки. Пример не включает каналы и внешние инструменты.

json
{
  "models": {
    "providers": {
      "custom-gateway": {
        "baseUrl": "https://relay-llm.ru/v1",
        "apiKey": "${RELAY_API_KEY}",
        "api": "openai-completions",
        "models": [{ "id": "gpt-5.6-luna", "name": "GPT-5.6 Luna" }]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "custom-gateway/gpt-5.6-luna" }
    }
  }
}

custom-gateway обозначает локальное имя провайдера в OpenClaw. Префикс нужен в выборе модели клиента, а в запрос Relay уходит ID gpt-5.6-luna. Не ищите полную строку с локальным префиксом в каталоге Relay.

Значение openai-completions выбирает адаптер Chat Completions в OpenClaw. Это не предложение использовать старый текстовый Completions API. Если выберете модель только с Responses, такой адаптер для неё не подойдёт.

Как передать ключ процессу Gateway

Создайте отдельный ключ Relay, ограничьте его расход и разрешённые модели по задаче. Для проверки из терминала формат окружения выглядит так:

bash
export RELAY_API_KEY="sk-demo-not-a-real-key"

Строка в примере вымышлена. Настоящий секрет передавайте способом, который предусмотрен вашей средой запуска. Для службы используйте её механизм переменных или описанный в руководстве OpenClaw локальный файл секретов. Проверьте права доступа и исключите файл из Git. Читать или печатать секрет ради диагностики не нужно.

Запускайте Gateway в той же среде, куда передали переменную. Если проверка из оболочки работает, а служба получает 401, сравните источник окружения и способ перезапуска службы. Пересоздание ключа не поможет процессу, который по-прежнему не получает его значение.

Как проверить API отдельно от OpenClaw

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

bash
curl --fail-with-body --max-time 30 https://relay-llm.ru/v1/key \
  -H "Authorization: Bearer $RELAY_API_KEY"

Метод возвращает сведения о текущем ключе, разрешённых моделях, лимитах и доступном балансе. Успех подтверждает авторизацию, но ещё не доказывает, что денег хватит на выбранную генерацию. Публичный список моделей без ключа для такой проверки не подходит: каталог доступен и без авторизации.

После этого выберите custom-gateway/gpt-5.6-luna в OpenClaw и отправьте короткое сообщение без инструментов. Найдите вызов в журнале Relay. Затем проверьте одну нужную операцию агента в тестовом каталоге: успешный текстовый ответ не доказывает работу файловых или сетевых инструментов.

Как найти причину ошибки

При отказе запуска после изменения JSON проверьте синтаксис и поля по руководству клиента. При 401 проверьте передачу секрета процессу. При ошибке модели сопоставьте локальный префикс OpenClaw, ID Relay и протокол адаптера.

При 402 прочитайте код: баланс и лимит ключа требуют разных действий. При 429 уменьшите темп запросов по правилам лимитов Relay. Если ломается только вызов инструмента, сохраните обезличенный запрос и проверьте поддержку tools выбранной моделью.

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

OpenClaw: как установить и подключить Relay?

Установите клиент по официальной инструкции для вашей ОС, пройдите первичную настройку и добавьте провайдера с URL, ключом и моделью Relay по примеру выше.

Почему ключ работает в curl, но не в OpenClaw?

Проверьте, получил ли процесс Gateway переменную окружения. Фоновая служба может запускаться с другим окружением, чем ваш терминал.

Почему ID с custom-gateway не находится в Relay?

Это локальное имя провайдера OpenClaw. В каталоге Relay ищите часть после префикса, например gpt-5.6-luna.

Подходит ли любая модель из каталога?

Для показанной настройки нужен Chat Completions. Для агентных задач дополнительно проверьте инструменты и другие возможности, которыми пользуется ваш сценарий.

Создать аккаунт

Модели из статьи

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.