OpenClaw

OpenClaw — self-hosted ассистент, который живёт в ваших каналах: локальный gateway принимает сообщения из Telegram, Slack, Discord и других, отдаёт их модели и возвращает ответ в тот же канал. Модели OpenClaw не привязывает к одному провайдеру: это локальный gateway, а не облачный API, поэтому адрес шлюза и ключ задаются в его конфигурации. Указав SpeShu.AI как OpenAI-совместимый провайдер, вы получаете весь каталог моделей с оплатой в рублях и без зарубежной карты.

От OpenClaw нужны ровно две вещи: адрес шлюза https://speshu.ai/api/v1 и API-ключ в заголовке Authorization: Bearer. Эндпоинт /api/v1/chat/completions совместим с OpenAI Chat Completions, поэтому код и промпты трогать не нужно. Ключ создаётся на speshu.ai/profile, подробности — в разделе Аутентификация.

Ключ и идентификатор модели

Положите ключ в переменную окружения

cURL

export SPESHU_API_KEY="sk-ваш-ключ"

Проверьте ключ запросом баланса

Запрос баланса бесплатный и не обращается к моделям:

cURL

curl -s https://speshu.ai/api/v1/balance \
  -H "Authorization: Bearer $SPESHU_API_KEY"

{ "RUB": "1250.00", "USD": "3.75" }

Ответ 401 invalid_api_key означает, что ключ недействителен или отозван, — разбираться нужно в профиле, а не в конфиге OpenClaw.

Возьмите идентификаторы моделей из каталога

Идентификаторы текстовых моделей не зашивайте ни в конфиг, ни в чат: состав каталога меняется, и зашитый в конфиг идентификатор начинает падать с 404 model_not_found без предупреждения. Заберите список один раз и используйте его целиком:

cURL

curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[] | "\(.id)\t\(.title)"' | head

Сохраните каталог в файл — из него ниже собирается конфигурация:

cURL

curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq '[.data[] | {id: .id, name: .title}]' > /tmp/speshu-models.json

jq -r 'length' /tmp/speshu-models.json

Формат ответа и параметры выбора — в разделе Модели и цены.

Конфигурация

OpenClaw читает конфигурацию из JSON-файла в своём каталоге данных: ~/.openclaw/openclaw.json в Linux и macOS, %USERPROFILE%\.openclaw\openclaw.json в Windows. Провайдеры моделей описаны в секции models.providers — каждый записью с адресом шлюза, ключом, типом API и списком моделей.

Имена ключей конфигурации зависят от версии OpenClaw. Проверьте их на своей версии: свежие релизы печатают фактическую схему, а ряд команд диагностики (openclaw doctor) проверяет конфигурацию и указывает на неизвестные поля. Если у вас более старый релиз и раздел провайдеров назван иначе, правьте его по той же схеме: адрес, ключ, тип API, список моделей.

Добавьте блок в models.providers:

{
  "models": {
    "providers": {
      "speshu": {
        "baseUrl": "https://speshu.ai/api/v1",
        "apiKey": "${SPESHU_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "<идентификатор из GET /api/v1/models>",
            "name": "<название из поля title>"
          }
        ]
      }
    }
  }
}

Поле	Что задаёт
`baseUrl`	Адрес шлюза. Без потерянного `/v1` и без завершающего слэша — иначе `404`
`apiKey`	Ключ либо строка `${SPESHU_API_KEY}` для подстановки из переменной окружения
`api`	Тип протокола. Для OpenAI-совместимых шлюзов — `openai-completions`
`models`	Список моделей провайдера: `id` — то, что уходит в поле `model`, `name` — подпись в интерфейсе

Секция models.providers — это allowlist. Модель, которой нет в списке, gateway не предложит, даже если она есть в GET /api/v1/models. Пересобирайте список при обновлении каталога.

Собрать конфигурацию из каталога

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

cURL

CONFIG=~/.openclaw/openclaw.json

jq --slurpfile m /tmp/speshu-models.json '
  .models.providers.speshu = {
    baseUrl: "https://speshu.ai/api/v1",
    apiKey: "${SPESHU_API_KEY}",
    api: "openai-completions",
    models: $m[0]
  }
' "$CONFIG" > /tmp/openclaw.json \
  && cp /tmp/openclaw.json "$CONFIG" \
  && chmod 600 "$CONFIG"

jq '.models.providers.speshu | {baseUrl, api, models: (.models | length)}' "$CONFIG"

Строка ${SPESHU_API_KEY} остаётся в файле как есть — gateway подставит значение при запуске. Если ваша версия не подставляет переменные окружения, замените её на значение ключа и обязательно ограничьте права на файл командой chmod 600.

Модель по умолчанию

В секции agents.defaults.model укажите модель, которой gateway будет отвечать по умолчанию. Ссылка строится как <имя-провайдера>/<идентификатор модели> — с идентификатором из каталога как есть, вместе со слэшем в группе:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "speshu/<идентификатор из GET /api/v1/models>"
      }
    }
  }
}

В чате переключайте модель командой /model с полной ссылкой в кавычках — идентификаторы содержат слэш, и без кавычек команда разберётся неверно:

/model "speshu/<идентификатор из GET /api/v1/models>"

Алиасы для коротких ссылок задайте в той же секции agents.defaults.models, где ключ — полная ссылка на модель:

{
  "agents": {
    "defaults": {
      "models": {
        "speshu/<идентификатор из GET /api/v1/models>": { "alias": "Основная" }
      }
    }
  }
}

Проверьте, что всё работает

Проверьте ключ и модель напрямую, минуя gateway:

cURL

export TEXT_MODEL=$(jq -r '.[0].id' /tmp/speshu-models.json)

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$TEXT_MODEL\",
    \"messages\": [{\"role\": \"user\", \"content\": \"Ответь одним словом: работает?\"}]
  }" | jq -r '.choices[0].message.content, .usage.cost.total_cost'

Если этот запрос отвечает, а gateway — нет, проблема в конфигурации: перезапустите его и проверьте, что файл прошёл валидацию. Дальше отправьте сообщение в подключённый канал — ответ придёт от gateway, и модель будет та, что указана в agents.defaults.model.primary.

usage.cost.total_cost — сумма, списанная с кошелька в рублях. Это единственное поле, по которому стоит считать расход. Подробности — в разделе Тарификация и оплата.

Что ещё доступно

Потоковая передача

Gateway читает /chat/completions как OpenAI-совместимый поток, поэтому сообщения в канале печатаются по мере генерации. Формат кадров SSE, маркер [DONE] и кадр со списанием разобраны в гайде Потоковая передача.

Инструменты

Описание инструментов уходит в поле tools запроса, а выбранный инструмент возвращается в choices[0].message.tool_calls — тот же протокол, что и в обычном чате. Полный цикл вызова, разбор аргументов и обработка параллельных вызовов — в гайде Вызов функций.

Изображения во входе

Чтобы отдать модели скриншот или фото из переписки, передайте его публичной ссылкой в блоке image_url. Требования к ссылке и все четыре типа блоков контента — в гайде Медиаввод.

Генерация медиа

Медиа-API не OpenAI-совместимый, поэтому генерация изображений, видео и музыки не идёт через провайдера моделей. Задачи создаются отдельным вызовом POST /api/v1/async/media/tasks и опрашиваются до state: "success". Идентификаторы медиа-моделей, в отличие от текстовых, стабильны — берите их из GET /api/v1/media/models. Формат конверта, Idempotency-Key и скачивание файла — в разделе Создать задачу.

Эндпоинта эмбеддингов у SpeShu.AI нет: /embeddings в /api/v1 не существует. Если вы включили в OpenClaw функцию памяти или поиска по векторам, она пойдёт по адресу провайдера и получит 404. Выводите такой шаг на отдельного провайдера эмбеддингов со своим адресом и своим ключом, а генерацию оставьте здесь.

Типичные проблемы

404 на запросе, хотя ключ и модель верны

Проверьте baseUrl: должно быть ровно https://speshu.ai/api/v1 — без потерянного /v1 и без завершающего слэша. Обе ошибки дают одинаковый 404 при верном ключе. Подробнее — в разделе Введение в API.

401 invalid_api_key в gateway, но не в curl

Ключ не подставился: строка ${SPESHU_API_KEY} осталась в файле как есть, а переменная окружения не экспортирована в процесс gateway. Gateway запускают как демон или systemd-юнит — у него своё окружение. Проверьте командой curl https://speshu.ai/api/v1/balance -H "Authorization: Bearer $SPESHU_API_KEY".

404 model_not_found

Идентификатор в models.providers.speshu.models устарел или скопирован с ошибкой. Пересоберите список из GET /api/v1/models скриптом выше: вручную скопированный каталог устаревает молча, и список в чате продолжает показывать пропавшие модели.

Модели нет в списке, хотя она есть в каталоге

models.providers — allowlist: модель вне списка не предлагается в интерфейсе и не принимается по ссылке speshu/<идентификатор>. Добавьте её в список и перезапустите gateway.

Ответ приходит целиком, а не по частям

Проверьте, что в конфигурации не отключён поток для канала. Формат кадров SSE и [DONE] — в гайде Потоковая передача.

Всё остальное

Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки, таймауты и квоты — в разделе Лимиты.

Что дальше

Начало работы

Полный маршрут от ключа до медиа-задачи

Модели и цены

Как выбрать идентификатор и на что смотреть

Вызов функций

Полный цикл вызова инструмента

Запрос чату

Поля запроса и формат ответа

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Ключ и идентификатор модели

Конфигурация

Собрать конфигурацию из каталога

Модель по умолчанию

Проверьте, что всё работает

Что ещё доступно

Потоковая передача

Инструменты

Изображения во входе

Генерация медиа

Типичные проблемы

Что дальше

Начало работы

Модели и цены

Вызов функций

Запрос чату

​Ключ и идентификатор модели

​Конфигурация

​Собрать конфигурацию из каталога

​Модель по умолчанию

​Проверьте, что всё работает

​Что ещё доступно

​Потоковая передача

​Инструменты

​Изображения во входе

​Генерация медиа

​Типичные проблемы

​Что дальше

Начало работы

Модели и цены

Вызов функций

Запрос чату

Ключ и идентификатор модели

Конфигурация

Собрать конфигурацию из каталога

Модель по умолчанию

Проверьте, что всё работает

Что ещё доступно

Потоковая передача

Инструменты

Изображения во входе

Генерация медиа

Типичные проблемы

Что дальше