ClawRouter

ClawRouter надає OpenClaw один ключ з обмеженою політикою для кількох висхідних постачальників моделей. Вбудований Plugin clawrouter виявляє лише моделі, дозволені для цього ключа, спрямовує кожну модель через заявлений для неї протокол і відображає бюджет ключа та сукупне використання в інтерфейсах використання OpenClaw.

Облікові дані висхідних систем і переспрямування, специфічне для постачальника, залишаються в ClawRouter, тому вам не потрібно встановлювати чи автентифікувати Plugin кожного висхідного постачальника на хості OpenClaw. Plugin постачається разом з 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 уже включено до кореневого середовища виконання. Виберіть лише Plugin каналу, який потребує окремого пакування, наприклад OPENCLAW_EXTENSIONS=clickclack, slack або msteams; див. образи, зібрані з вихідного коду з вибраними Plugins. Архівні розгортання та розгортання у вигляді програмно-апаратного комплексу мають пакувати той самий інтегрований вихідний код через власний конвеєр артефактів, а не використовувати образ 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 "Reply exactly: CLAWROUTER_CANARY_OK" \  --json

Використовуйте модель, повернену каталогом з обмеженою областю дії, замість сліпого копіювання моделі з прикладу. Успішна відповідь /readyz означає, що Gateway може обслуговувати запити; вона не підтверджує готовність ClawRouter, його облікових даних або висхідного постачальника. Перевірка моделі та канаркова перевірка агента є підтвердженнями виведення.

Для діагностики в робочому середовищі виконайте канаркову перевірку та перегляньте стандартні журнали Gateway. Наявні діагностичні повідомлення транспорту моделей, що містять лише метадані, мають такий вигляд:

[model-fetch] start provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] response provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

Plugin надсилає обмежені за довжиною заголовки 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 секунд для кожної області дії облікових даних) виявить її. Модель, яка потребує нового мережевого протоколу, спочатку потребує підтримки з боку Plugin.

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

ClawRouter керує обліковими даними висхідних систем; його каталог повідомляє OpenClaw, який транспорт використовувати, тому вам не потрібно встановлювати Plugin автентифікації кожної висхідної компанії.

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

Пов’язане