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 Gateway, зібраного з вихідного коду, ClawRouter уже включено до кореневого середовища виконання. Виберіть лише плагін каналу, який потребує окремого пакування, наприклад OPENCLAW_EXTENSIONS=clickclack, slack або msteams; див. образи, зібрані з вихідного коду з вибраними плагінами. Архівні розгортання та розгортання у вигляді програмно-апаратного комплексу мають пакувати той самий інтегрований вихідний код через власний конвеєр артефактів, а не використовувати образ OCI.

Готовність і перевірка в реальному середовищі

Ці перевірки підтверджують різні межі; не замінюйте одну іншою:

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

# Лише готовність запуску OpenClaw Gateway; виклик моделі не виконується.
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

Початок роботи

Кероване неінтерактивне розгортання

Готовність і перевірка в реальному середовищі

Виявлення моделей

Протоколи та плагіни постачальників

Квоти та використання

Усунення несправностей

Поведінка безпеки

Пов’язані матеріали

Постачальники моделей

Відстеження використання

​Початок роботи

​Кероване неінтерактивне розгортання

​Готовність і перевірка в реальному середовищі

​Виявлення моделей

​Протоколи та плагіни постачальників

​Квоти та використання

​Усунення несправностей

​Поведінка безпеки

​Пов’язані матеріали

Постачальники моделей

Відстеження використання

Початок роботи

Кероване неінтерактивне розгортання

Готовність і перевірка в реальному середовищі

Виявлення моделей

Протоколи та плагіни постачальників

Квоти та використання

Усунення несправностей

Поведінка безпеки

Пов’язані матеріали