ClawRouter

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

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

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

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

openclaw models list --all --provider clawrouter

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

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

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

Например, контроллер развёртывания может управлять этой заплатой 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 --jsonopenclaw 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, какой транспорт использовать, поэтому устанавливать плагин аутентификации каждой вышестоящей компании не требуется.

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

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

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

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

Проверьте актуальный снимок с помощью:

openclaw status --usageopenclaw models status

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

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

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

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

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