--- read_when: - Вам нужен один управляемый ключ для нескольких поставщиков моделей - Вам требуется обнаружение моделей ClawRouter или отчётность по квотам в OpenClaw summary: Маршрутизируйте модели с привязкой к учётным данным через ClawRouter и отображайте управляемые квоты title: ClawRouter x-i18n: generated_at: "2026-07-16T16:49:12Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 684405818b701448b37431302b0c2cc66e106c2c6d482545569d9dfc7f7fe8e5 source_path: providers/clawrouter.md workflow: 16 --- 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 учётные данные, политика которых включает провайдеров, модели и ежемесячный бюджет, которые следует использовать. Учётные данные отображаются один раз при выдаче. ```bash 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`. ```bash 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. ```bash openclaw models set clawrouter// ``` Возвращённую модель также можно выбрать для одного запуска с помощью `openclaw agent --model clawrouter// --message "..."`. ## Управляемое неинтерактивное развёртывание Храните ключ прокси в системе внедрения секретов рабочей нагрузки, а в `openclaw.json` сохраняйте только SecretRef. Канонические управляемые поля: | Назначение | Поле конфигурации или окружения | | ------------- | ------------------------------------------------------------------------ | | Источник маршрутизатора | `models.providers.clawrouter.baseUrl` | | Учётные данные | `models.providers.clawrouter.apiKey` -> SecretRef окружения | | Значение секрета | `CLAWROUTER_API_KEY` в окружении процесса Gateway | | Модель по умолчанию | `agents.defaults.model.primary` -> `clawrouter//` | | Метка рабочей нагрузки | `models.providers.clawrouter.headers.X-ClawRouter-Project-Id` (необязательно) | Например, контроллер развёртывания может управлять этой заплатой JSON5: ```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`. Проверьте и примените без интерактивного мастера: ```bash 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`; см. [образы, собранные из исходного кода с выбранными плагинами](/ru/install/docker#source-built-images-with-selected-plugins). Архивные развёртывания и развёртывания в виде программно-аппаратного комплекса должны упаковывать тот же принятый исходный код через собственный конвейер артефактов, а не использовать образ OCI. ## Готовность и проверка в рабочей среде Эти проверки подтверждают разные границы; не заменяйте одну другой: ```bash # Только работоспособность процесса 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. Существующая диагностика транспорта модели, содержащая только метаданные, выводит строки следующего вида: ```text [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` (`:model:`) вызова модели с `X-Request-ID`, благодаря чему событие вызова модели OpenClaw можно связать с журналом аудита ClawRouter, содержащим только метаданные. Значения, укладывающиеся в ограничение идентификатора запроса в 128 символов, идентичны. Более длинные значения сохраняют суффикс `:model:` и детерминированный хеш, поэтому разные вызовы остаются ограниченными по длине и доступными для связывания. Статические метаданные развёртывания, такие как `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: итоговые значения запросов, токенов и расходов, а также окно ежемесячного бюджета, если для ключа задан лимит. Для ключей без лимита по-прежнему отображается совокупное использование без процентного окна. Для получения квоты используется тот же ключ с ограниченной областью действия, что и для обнаружения моделей. Ошибка получения квоты не блокирует выполнение модели. Проверьте актуальный снимок с помощью: ```bash 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 для просмотра использования и состояния.