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 Gateway, собранного из исходного кода, 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; собственные политики повторного воспроизведения Anthropic и Google Gemini). Поставщик каталога, предоставляющий только неподдерживаемый формат запроса, намеренно не объявляется текстовой моделью OpenClaw. Нормализуйте таких поставщиков в ClawRouter до одного из поддерживаемых контрактов, а не отправляйте несовместимую полезную нагрузку.

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

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

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

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

openclaw status --usageopenclaw models status

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

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

Поведение безопасности

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

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