---
read_when:
- Вам потрібен один керований ключ для кількох постачальників моделей
- Вам потрібне виявлення моделей ClawRouter або звітування про квоти в OpenClaw
summary: Спрямовуйте моделі з обліковими даними через ClawRouter і відображайте керовані квоти
title: ClawRouter
x-i18n:
generated_at: "2026-07-16T18:26:35Z"
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 Gateway, зібраного з вихідного коду, ClawRouter уже включено до
кореневого середовища виконання. Виберіть лише плагін каналу, який потребує окремого пакування,
наприклад `OPENCLAW_EXTENSIONS=clickclack`, `slack` або `msteams`; див.
[образи, зібрані з вихідного коду з вибраними плагінами](/uk/install/docker#source-built-images-with-selected-plugins).
Архівні розгортання та розгортання у вигляді програмно-апаратного комплексу мають пакувати той самий інтегрований вихідний код через власний
конвеєр артефактів, а не використовувати образ OCI.
## Готовність і перевірка в реальному середовищі
Ці перевірки підтверджують різні межі; не замінюйте одну іншою:
```bash
# Лише працездатність процесу 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.
Наявна діагностика транспорту моделей лише з метаданими виводить рядки такого вигляду:
```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 для перегляду використання та стану.