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 # Лише готовність запуску 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, який транспорт використовувати, тому не потрібно встановлювати плагін автентифікації кожної висхідної компанії.

Плагін також застосовує відповідні політики повторного відтворення та схем інструментів для цих сімейств (сумісність схем інструментів 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 замінюються на їхні ідентифікатори у вхідних системах лише під час надсилання.
• Непідтримувані рядки каталогу або рядки, до яких не надано доступ, блокуються за принципом безпечної відмови й недоступні для вибору.

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