ClawRouter

ClawRouter предоставляет OpenClaw один ключ с областью действия, заданной политикой, для нескольких вышестоящих провайдеров моделей. Встроенный плагин clawrouter обнаруживает только модели, разрешённые для этого ключа, направляет каждую модель через заявленный для неё протокол и отображает бюджет ключа и совокупное использование в интерфейсах использования OpenClaw. Вышестоящие учётные данные и перенаправление с учётом особенностей провайдера остаются в ClawRouter, поэтому не требуется устанавливать или аутентифицировать плагин каждого вышестоящего провайдера на хосте OpenClaw. Плагин поставляется вместе с OpenClaw (enabledByDefault: true); нужны только выданные учётные данные ClawRouter.

Свойство	Значение
Провайдер	`clawrouter`
Плагин	встроенный (включён в OpenClaw)
Аутентификация	`CLAWROUTER_API_KEY`
URL по умолчанию	`https://clawrouter.openclaw.ai`
Каталог моделей	Ограничен областью учётных данных через `/v1/catalog`
Квоты	Ежемесячный бюджет и использование через `/v1/usage`

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

Получение учётных данных с ограниченной областью действия

Запросите у администратора ClawRouter учётные данные, политика которых включает провайдеров, модели и ежемесячный бюджет, которые следует использовать. Учётные данные отображаются один раз при выдаче.

Настройка OpenClaw

export CLAWROUTER_API_KEY="..."
openclaw onboard --auth-choice clawrouter-api-key
openclaw plugins enable clawrouter

clawrouter встроен и включён по умолчанию. Если в конфигурации задан plugins.allow, добавьте clawrouter в этот список перед включением. Для нестандартного развёртывания задайте models.providers.clawrouter.baseUrl как источник ClawRouter; значение по умолчанию — https://clawrouter.openclaw.ai.

Просмотр предоставленных моделей

openclaw models list --all --provider clawrouter

Используйте возвращённые ссылки на модели точно в указанном виде. Они сохраняют вышестоящее пространство имён, например clawrouter/openai/gpt-5.5, clawrouter/anthropic/claude-sonnet-4-6 или clawrouter/google/gemini-3.5-flash. Если agents.defaults.models используется в конфигурации как список разрешений, добавьте в него каждую выбранную ссылку ClawRouter.

Выбор модели

openclaw models set clawrouter/<provider>/<model>

Возвращённую модель также можно выбрать для одного запуска с помощью openclaw agent --model clawrouter/<provider>/<model> --message "...".

Управляемое неинтерактивное развёртывание

Храните ключ прокси в системе внедрения секретов рабочей нагрузки, а в openclaw.json сохраняйте только SecretRef. Канонические управляемые поля:

Назначение	Поле конфигурации или окружения
Источник маршрутизатора	`models.providers.clawrouter.baseUrl`
Учётные данные	`models.providers.clawrouter.apiKey` -> SecretRef окружения
Значение секрета	`CLAWROUTER_API_KEY` в окружении процесса Gateway
Модель по умолчанию	`agents.defaults.model.primary` -> `clawrouter/<provider>/<model>`
Метка рабочей нагрузки	`models.providers.clawrouter.headers.X-ClawRouter-Project-Id` (необязательно)

Например, контроллер развёртывания может управлять этой заплатой JSON5:

{
  plugins: {
    entries: { clawrouter: { enabled: true } },
  },
  models: {
    providers: {
      clawrouter: {
        baseUrl: "https://clawrouter.internal.example",
        apiKey: {
          source: "env",
          provider: "default",
          id: "CLAWROUTER_API_KEY",
        },
        headers: {
          "X-ClawRouter-Project-Id": "fakeco",
        },
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "clawrouter/openai/gpt-5.5" },
    },
  },
}

Если при развёртывании задаётся plugins.allow, сохраните существующие записи и добавьте clawrouter. Проверьте и примените без интерактивного мастера:

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --json
openclaw config patch --file ./clawrouter.patch.json5

Пробный запуск разрешает SecretRef, но никогда не выводит его значение. Чтобы сменить учётные данные, обновите внешний Secret, предоставляющий CLAWROUTER_API_KEY, и перезапустите рабочую нагрузку Gateway, чтобы загрузилось окружение нового процесса. Файл конфигурации и ссылка на модель не изменяются. Для автономного Docker-шлюза, собранного из исходного кода, ClawRouter уже включён в корневую среду выполнения. Выберите только плагин канала, требующий отдельной упаковки, например OPENCLAW_EXTENSIONS=clickclack, slack или msteams; см. образы, собранные из исходного кода с выбранными плагинами. Архивные развёртывания и развёртывания в виде программно-аппаратного комплекса должны упаковывать тот же принятый исходный код через собственный конвейер артефактов, а не использовать образ OCI.

Готовность и проверка в рабочей среде

Эти проверки подтверждают разные границы; не заменяйте одну другой:

# Только работоспособность процесса ClawRouter; учётные данные и вышестоящая модель не проверяются.
curl -fsS https://clawrouter.internal.example/v1/health

# Только готовность запуска Gateway OpenClaw; вызов модели не выполняется.
curl -fsS http://127.0.0.1:18789/readyz

# Обнаружение каталога в области действия учётных данных.
openclaw models list --all --provider clawrouter --json

# Минимальная реальная проба вывода через настроенного провайдера ClawRouter.
openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json

# Проверка рабочей нагрузки с использованием точной предоставленной ссылки на модель.
openclaw agent --agent main \
  --model clawrouter/openai/gpt-5.5 \
  --message "Ответьте в точности: CLAWROUTER_CANARY_OK" \
  --json

Используйте модель, возвращённую каталогом с ограниченной областью действия, вместо бездумного копирования модели из примера. Успешный ответ /readyz означает, что Gateway может обслуживать запросы; это не означает, что ClawRouter, его учётные данные или вышестоящий провайдер готовы. Проба модели и контрольная проверка агента подтверждают выполнение вывода. Для диагностики в рабочей среде выполните контрольную проверку и изучите стандартные журналы Gateway. Существующая диагностика транспорта модели, содержащая только метаданные, выводит строки следующего вида:

[model-fetch] запуск provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses
[model-fetch] ответ provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

Плагин отправляет ограниченные по длине заголовки X-ClawRouter-Client, X-ClawRouter-Agent-Id и X-ClawRouter-Session-Id, когда эти идентификаторы доступны. Он также сопоставляет диагностический callId (<run-id>:model:<n>) вызова модели с X-Request-ID, благодаря чему событие вызова модели OpenClaw можно связать с журналом аудита ClawRouter, содержащим только метаданные. Значения, укладывающиеся в ограничение идентификатора запроса в 128 символов, идентичны. Более длинные значения сохраняют суффикс :model:<n> и детерминированный хеш, поэтому разные вызовы остаются ограниченными по длине и доступными для связывания. Статические метаданные развёртывания, такие как X-ClawRouter-Project-Id, можно задать в карте headers провайдера. Заголовки атрибуции агента и сеанса сохраняют отдельное ограничение в 256 символов. Автоматические идентификаторы запросов, содержащие символы вне набора ASCII-идентификаторов ClawRouter, используют ту же детерминированную ограниченную форму. Явно настроенные заголовки, включая любой вариант регистра X-Request-ID, имеют приоритет над автоматическими значениями. Диагностика транспорта записывает метаданные маршрутизации и ответа; она не записывает учётные данные, идентификаторы запросов, запросы к модели или завершения. Собственное событие аудита ClawRouter содержит выбранного вышестоящего провайдера и состояние хранения содержимого.

Обнаружение моделей

GET /v1/catalog возвращает { providers: [...] }, где запись каждого провайдера содержит собственный список models[] (с вышестоящим идентификатором, возможностями и ценами) и поддерживаемые маршруты запросов. OpenClaw не поставляет второй фиксированный список моделей ClawRouter. Модель из каталога объявляется моделью OpenClaw, когда:

политика учётных данных предоставляет доступ к её провайдеру;
модель каталога заявляет поддерживаемую возможность LLM (llm.responses, llm.chat, llm.messages или llm.stream с соответствующим маршрутом потоковой передачи); и
провайдер предоставляет соответствующий маршрут для одного из приведённых ниже транспортов.

Добавление модели к поддерживаемому провайдеру ClawRouter не требует выпуска новой версии OpenClaw: следующее обновление каталога (кешируется на 60 секунд для каждой области учётных данных) обнаружит её. Для модели, которой требуется новый протокол передачи, сначала необходимо добавить поддержку в плагин.

Плагины протоколов и провайдеров

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

Возможность/маршрут каталога	Транспорт OpenClaw
`llm.responses` (OpenAI-совместимый провайдер)	`openai-responses`
`llm.chat` (OpenAI-совместимый провайдер)	`openai-completions`
`llm.messages` + маршрут `anthropic.messages`	`anthropic-messages`
`llm.stream` + потоковый маршрут `google.generate_content`	`google-generative-ai`

Плагин также применяет соответствующие политики повторного воспроизведения и схем инструментов для этих семейств (совместимость схем инструментов OpenAI/DeepSeek/Gemini/Perplexity; собственные политики повторного воспроизведения Anthropic и Google Gemini). Для моделей Perplexity применяется строгое переписывание схемы: patternProperties и additionalProperties удаляются, а в каждой объектной схеме объявляется properties, поскольку Perplexity отклоняет схемы инструментов без них. Провайдер каталога, предоставляющий только неподдерживаемый формат запроса, намеренно не объявляется текстовой моделью OpenClaw. Нормализуйте таких провайдеров в ClawRouter до одного из поддерживаемых контрактов, а не отправляйте несовместимую полезную нагрузку.

Квоты и использование

Ответ /v1/usage ClawRouter поступает в стандартные интерфейсы использования провайдера OpenClaw: итоговые значения запросов, токенов и расходов, а также окно ежемесячного бюджета, если для ключа задан лимит. Для ключей без лимита по-прежнему отображается совокупное использование без процентного окна. Для получения квоты используется тот же ключ с ограниченной областью действия, что и для обнаружения моделей. Ошибка получения квоты не блокирует выполнение модели. Проверьте актуальный снимок с помощью:

openclaw status --usage
openclaw models status

Тот же снимок провайдера доступен для /status в чате и в интерфейсе использования OpenClaw. Бюджет действует для всей политики, поэтому запросы другого клиента, использующего ту же политику ClawRouter, могут изменить оставшийся процент.

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

Симптом	Что проверить
Нет моделей ClawRouter	Убедитесь, что плагин включён и разрешён параметром `plugins.allow`, затем проверьте, что учётные данные активны и предоставляют доступ хотя бы к одному готовому провайдеру.
Настроенная модель ClawRouter отсутствует	Проверьте её возможность `/v1/catalog` и поддержку маршрута. Неподдерживаемые транспортные контракты намеренно отфильтровываются.
`Unknown model: clawrouter/...`	Добавьте точную ссылку из каталога в `agents.defaults.models`, если эта карта конфигурации используется как список разрешений.
`401` или `403` от каталога или интерфейса использования	Повторно выдайте учётные данные ClawRouter или измените их область действия; OpenClaw не переключается на ключи вышестоящих провайдеров.
Вызов модели завершается ошибкой после обнаружения	Проверьте подключение провайдера и состояние вышестоящего сервиса в ClawRouter, затем повторите попытку после восстановления его готовности.
В использовании есть итоговые значения, но нет процентов	Политика не имеет лимита; добавьте ежемесячный бюджет в ClawRouter, чтобы отображалось процентное окно.

Безопасность

Обнаружение каталога ограничено областью настроенного ключа прокси, а результаты кэшируются отдельно для каждой области учётных данных (каталог агента, каталог рабочей области, идентификатор профиля аутентификации и базовый URL-адрес).
Ключ прокси добавляется только при отправке запроса; он не сохраняется в метаданных модели.
Перед отправкой значения автоматической атрибуции и корреляции запросов обрезаются по краям, а значения с управляющими символами отклоняются. Значения атрибуции ограничены 256 символами, а идентификаторы запросов — 128.
Диагностические данные транспорта модели содержат только метаданные и никогда не включают ключ прокси или содержимое модели.
Идентификаторы нативных моделей Anthropic и Gemini заменяются их вышестоящими идентификаторами только при отправке.
Строки каталога, которые не поддерживаются или на которые не предоставлены права, отклоняются по принципу запрета по умолчанию и недоступны для выбора.

Связанные материалы

Провайдеры моделей

Настройка провайдеров и выбор модели.

Отслеживание использования

Интерфейсы OpenClaw для просмотра использования и состояния.

Overview

Concepts and configuration

Providers

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

Управляемое неинтерактивное развёртывание

Готовность и проверка в рабочей среде

Обнаружение моделей

Плагины протоколов и провайдеров

Квоты и использование

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

Безопасность

Связанные материалы

Провайдеры моделей

Отслеживание использования

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

​Управляемое неинтерактивное развёртывание

​Готовность и проверка в рабочей среде

​Обнаружение моделей

​Плагины протоколов и провайдеров

​Квоты и использование

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

​Безопасность

​Связанные материалы

Провайдеры моделей

Отслеживание использования

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

Управляемое неинтерактивное развёртывание

Готовность и проверка в рабочей среде

Обнаружение моделей

Плагины протоколов и провайдеров

Квоты и использование

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

Безопасность

Связанные материалы