chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
0e640f977e
commit
906cfabd8f
@ -2,27 +2,27 @@
|
||||
read_when:
|
||||
- Робота над визначенням профілю автентифікації або маршрутизацією облікових даних
|
||||
- Налагодження збоїв автентифікації моделі або порядку профілів
|
||||
summary: Канонічна придатність облікових даних і семантика визначення для профілів автентифікації
|
||||
summary: Семантика придатності та визначення канонічних облікових даних для профілів автентифікації
|
||||
title: Семантика облікових даних автентифікації
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T07:07:52Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-29T11:03:50Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: a1172a87053986567ac6051afe99946a9d36e1e838ce693cd56d56e71242d679
|
||||
source_hash: 1f235d0c43a6cb38edf76762d530c2316ff62dfa16204875b80704b58324c176
|
||||
source_path: auth-credential-semantics.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Цей документ визначає канонічну придатність облікових даних і семантику визначення, що використовуються в таких компонентах:
|
||||
Цей документ визначає канонічні семантики придатності та розв’язання облікових даних, що використовуються в:
|
||||
|
||||
- `resolveAuthProfileOrder`
|
||||
- `resolveApiKeyForProfile`
|
||||
- `models status --probe`
|
||||
- `doctor-auth`
|
||||
|
||||
Мета — забезпечити узгодженість поведінки під час вибору та під час виконання.
|
||||
Мета — узгодити поведінку під час вибору та під час виконання.
|
||||
|
||||
## Стабільні коди причин probe
|
||||
## Стабільні коди причин зондування
|
||||
|
||||
- `ok`
|
||||
- `excluded_by_auth_order`
|
||||
@ -38,48 +38,58 @@ x-i18n:
|
||||
|
||||
### Правила придатності
|
||||
|
||||
1. Профіль токена є непридатним, якщо відсутні і `token`, і `tokenRef`.
|
||||
1. Профіль токена є непридатним, коли відсутні і `token`, і `tokenRef`.
|
||||
2. `expires` є необов’язковим.
|
||||
3. Якщо `expires` указано, це має бути скінченне число, більше за `0`.
|
||||
4. Якщо `expires` є недійсним (`NaN`, `0`, від’ємне значення, нескінченне значення або неправильний тип), профіль є непридатним із `invalid_expires`.
|
||||
5. Якщо `expires` уже минув, профіль є непридатним із `expired`.
|
||||
3. Якщо `expires` присутній, це має бути скінченне число, більше за `0`.
|
||||
4. Якщо `expires` недійсний (`NaN`, `0`, від’ємне значення, нескінченне значення або неправильний тип), профіль є непридатним із `invalid_expires`.
|
||||
5. Якщо `expires` у минулому, профіль є непридатним із `expired`.
|
||||
6. `tokenRef` не обходить перевірку `expires`.
|
||||
|
||||
### Правила визначення
|
||||
### Правила розв’язання
|
||||
|
||||
1. Семантика визначення відповідає семантиці придатності для `expires`.
|
||||
2. Для придатних профілів матеріал токена може визначатися з вбудованого значення або `tokenRef`.
|
||||
3. Посилання, які неможливо визначити, дають `unresolved_ref` у виводі `models status --probe`.
|
||||
1. Семантики розв’язувача відповідають семантикам придатності для `expires`.
|
||||
2. Для придатних профілів матеріал токена може бути розв’язано з вбудованого значення або `tokenRef`.
|
||||
3. Посилання, які неможливо розв’язати, створюють `unresolved_ref` у виводі `models status --probe`.
|
||||
|
||||
## Явна фільтрація порядку автентифікації
|
||||
## Портативність копіювання агента
|
||||
|
||||
- Коли для провайдера задано `auth.order.<provider>` або перевизначення порядку зі сховища автентифікації, `models status --probe` перевіряє лише ідентифікатори профілів, які залишаються у визначеному порядку автентифікації для цього провайдера.
|
||||
- Збережений профіль для цього провайдера, пропущений у явному порядку, не перевіряється потім неявно. У виводі probe для нього вказується
|
||||
`reasonCode: excluded_by_auth_order` і деталь
|
||||
`Excluded by auth.order for this provider.`
|
||||
Успадкування автентифікації агента працює наскрізним читанням. Коли агент не має локального профілю, він може розв’язувати профілі зі сховища стандартного/головного агента під час виконання без копіювання секретного матеріалу у власний `auth-profiles.json`.
|
||||
|
||||
## Визначення цілі probe
|
||||
Явні потоки копіювання, як-от `openclaw agents add`, використовують таку політику портативності:
|
||||
|
||||
- Цілі probe можуть надходити з профілів автентифікації, облікових даних середовища або `models.json`.
|
||||
- Якщо провайдер має облікові дані, але OpenClaw не може визначити для нього придатну до probe модель-кандидат, `models status --probe` повідомляє `status: no_model` з
|
||||
`reasonCode: no_model`.
|
||||
- Профілі `api_key` є портативними, якщо не вказано `copyToAgents: false`.
|
||||
- Профілі `token` є портативними, якщо не вказано `copyToAgents: false`.
|
||||
- Профілі `oauth` за замовчуванням не є портативними, оскільки токени оновлення можуть бути одноразовими або чутливими до ротації.
|
||||
- OAuth-потоки, якими володіє провайдер, можуть увімкнути це за допомогою `copyToAgents: true` лише тоді, коли відомо, що копіювання матеріалу оновлення між агентами є безпечним.
|
||||
|
||||
## Захисне правило політики OAuth SecretRef
|
||||
Непортативні профілі залишаються доступними через наскрізне успадкування, якщо цільовий агент не ввійде окремо та не створить власний локальний профіль.
|
||||
|
||||
- Вхід SecretRef призначено лише для статичних облікових даних.
|
||||
## Явне фільтрування порядку автентифікації
|
||||
|
||||
- Коли для провайдера задано `auth.order.<provider>` або перевизначення порядку сховища автентифікації, `models status --probe` зондує лише ідентифікатори профілів, що залишаються в розв’язаному порядку автентифікації для цього провайдера.
|
||||
- Збережений профіль для цього провайдера, пропущений у явному порядку, не буде непомітно випробуваний пізніше. Вивід зондування повідомляє про нього з `reasonCode: excluded_by_auth_order` і деталлю `Excluded by auth.order for this provider.`
|
||||
|
||||
## Розв’язання цілі зондування
|
||||
|
||||
- Цілі зондування можуть походити з профілів автентифікації, облікових даних середовища або `models.json`.
|
||||
- Якщо провайдер має облікові дані, але OpenClaw не може розв’язати кандидата моделі, придатного для зондування, `models status --probe` повідомляє `status: no_model` із `reasonCode: no_model`.
|
||||
|
||||
## Запобіжник політики SecretRef для OAuth
|
||||
|
||||
- Ввід SecretRef призначений лише для статичних облікових даних.
|
||||
- Якщо облікові дані профілю мають `type: "oauth"`, об’єкти SecretRef не підтримуються для матеріалу облікових даних цього профілю.
|
||||
- Якщо `auth.profiles.<id>.mode` має значення `"oauth"`, вхід `keyRef`/`tokenRef` на основі SecretRef для цього профілю відхиляється.
|
||||
- Порушення є жорсткими помилками в шляхах визначення автентифікації під час запуску/перезавантаження.
|
||||
- Якщо `auth.profiles.<id>.mode` дорівнює `"oauth"`, ввід `keyRef`/`tokenRef` на основі SecretRef для цього профілю відхиляється.
|
||||
- Порушення є жорсткими збоями в шляхах розв’язання автентифікації під час запуску/перезавантаження.
|
||||
|
||||
## Повідомлення зі збереженням сумісності зі спадщиною
|
||||
## Повідомлення, сумісні зі спадщиною
|
||||
|
||||
Для сумісності зі скриптами перший рядок помилок probe залишається без змін:
|
||||
Для сумісності зі скриптами перший рядок помилок зондування залишається незмінним:
|
||||
|
||||
`Auth profile credentials are missing or expired.`
|
||||
|
||||
Зрозуміла для людини деталізація та стабільні коди причин можуть додаватися в наступних рядках.
|
||||
Зручні для людини подробиці та стабільні коди причин можуть додаватися в наступних рядках.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Керування секретами](/uk/gateway/secrets)
|
||||
- [Сховище автентифікації](/uk/concepts/oauth)
|
||||
- [Зберігання автентифікації](/uk/concepts/oauth)
|
||||
|
||||
@ -1,45 +1,45 @@
|
||||
---
|
||||
read_when:
|
||||
- Робота над поведінкою каналу WhatsApp/веб або маршрутизацією вхідних повідомлень
|
||||
- Робота з поведінкою WhatsApp/вебканалу або маршрутизацією вхідних повідомлень
|
||||
summary: Підтримка каналу WhatsApp, контроль доступу, поведінка доставки та експлуатація
|
||||
title: WhatsApp
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T05:37:25Z"
|
||||
generated_at: "2026-04-29T11:03:42Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 9057208c69d125aea8d063f7c16c98babbf70ded7f693bdb15cde159c4920019
|
||||
source_hash: f5acfebb37e16c4a3602ead7c9a4f2e16315d07612dc1e929f30fb7b1bc37761
|
||||
source_path: channels/whatsapp.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Стан: готовий до production через WhatsApp Web (Baileys). Gateway володіє пов’язаними сеансами.
|
||||
Status: готово до production через WhatsApp Web (Baileys). Gateway володіє пов’язаними сеансами.
|
||||
|
||||
## Встановлення (на вимогу)
|
||||
|
||||
- Onboarding (`openclaw onboard`) і `openclaw channels add --channel whatsapp`
|
||||
пропонують встановити Plugin WhatsApp під час першого вибору.
|
||||
- `openclaw channels login --channel whatsapp` також пропонує потік встановлення, коли
|
||||
Plugin ще не наявний.
|
||||
- Канал розробки + git checkout: за замовчуванням використовує локальний шлях Plugin.
|
||||
пропонують установити WhatsApp plugin під час першого вибору.
|
||||
- `openclaw channels login --channel whatsapp` також пропонує потік установлення, коли
|
||||
plugin ще відсутній.
|
||||
- Dev channel + git checkout: за замовчуванням використовує локальний шлях plugin.
|
||||
- Stable/Beta: використовує npm-пакет `@openclaw/whatsapp`, коли поточний пакет
|
||||
опубліковано.
|
||||
|
||||
Ручне встановлення лишається доступним:
|
||||
Ручне встановлення залишається доступним:
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/whatsapp
|
||||
```
|
||||
|
||||
Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий або відсутній, використайте
|
||||
поточну пакетовану збірку OpenClaw або локальний checkout, доки ланцюжок npm-пакетів
|
||||
Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий або відсутній, використовуйте
|
||||
поточну пакетовану збірку OpenClaw або локальний checkout, доки npm-пакетний потік
|
||||
не наздожене.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pairing" icon="link" href="/uk/channels/pairing">
|
||||
Стандартна політика DM — pairing для невідомих відправників.
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Типова політика DM для невідомих відправників — сполучення.
|
||||
</Card>
|
||||
<Card title="Усунення несправностей каналу" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та інструкції з відновлення.
|
||||
Міжканальна діагностика та playbook-и відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони й приклади конфігурації каналів.
|
||||
@ -66,7 +66,7 @@ openclaw plugins install @openclaw/whatsapp
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Зв’яжіть WhatsApp (QR)">
|
||||
<Step title="Під’єднайте WhatsApp (QR)">
|
||||
|
||||
```bash
|
||||
openclaw channels login --channel whatsapp
|
||||
@ -78,7 +78,7 @@ openclaw channels login --channel whatsapp
|
||||
openclaw channels login --channel whatsapp --account work
|
||||
```
|
||||
|
||||
Щоб під’єднати наявний/власний каталог автентифікації WhatsApp Web перед входом:
|
||||
Щоб підключити наявний/власний каталог автентифікації WhatsApp Web перед входом:
|
||||
|
||||
```bash
|
||||
openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
|
||||
@ -87,7 +87,7 @@ openclaw channels login --channel whatsapp --account work
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Запустіть Gateway">
|
||||
<Step title="Запустіть gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -95,14 +95,14 @@ openclaw gateway
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Підтвердьте перший запит pairing (якщо використовується режим pairing)">
|
||||
<Step title="Схваліть перший запит на сполучення (якщо використовується режим сполучення)">
|
||||
|
||||
```bash
|
||||
openclaw pairing list whatsapp
|
||||
openclaw pairing approve whatsapp <CODE>
|
||||
```
|
||||
|
||||
Запити pairing спливають через 1 годину. Очікувані запити обмежені 3 на канал.
|
||||
Запити на сполучення спливають через 1 годину. Кількість очікуваних запитів обмежена 3 на канал.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -114,11 +114,11 @@ OpenClaw рекомендує за можливості запускати Whats
|
||||
## Шаблони розгортання
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Виділений номер (рекомендовано)">
|
||||
<Accordion title="Окремий номер (рекомендовано)">
|
||||
Це найчистіший операційний режим:
|
||||
|
||||
- окрема ідентичність WhatsApp для OpenClaw
|
||||
- чіткіші allowlist DM і межі маршрутизації
|
||||
- чіткіші allowlist-и DM і межі маршрутизації
|
||||
- нижча ймовірність плутанини із self-chat
|
||||
|
||||
Мінімальний шаблон політики:
|
||||
@ -137,20 +137,20 @@ OpenClaw рекомендує за можливості запускати Whats
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Резервний варіант з особистим номером">
|
||||
Onboarding підтримує режим особистого номера й записує базову конфігурацію, зручну для self-chat:
|
||||
Onboarding підтримує режим особистого номера й записує базовий варіант, дружній до self-chat:
|
||||
|
||||
- `dmPolicy: "allowlist"`
|
||||
- `allowFrom` містить ваш особистий номер
|
||||
- `selfChatMode: true`
|
||||
|
||||
Під час виконання захисти self-chat спираються на пов’язаний власний номер і `allowFrom`.
|
||||
Під час виконання захист self-chat базується на пов’язаному власному номері та `allowFrom`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Обсяг каналу лише WhatsApp Web">
|
||||
<Accordion title="Область каналу лише WhatsApp Web">
|
||||
Канал платформи обміну повідомленнями базується на WhatsApp Web (`Baileys`) у поточній архітектурі каналів OpenClaw.
|
||||
|
||||
У вбудованому реєстрі чат-каналів немає окремого каналу повідомлень Twilio WhatsApp.
|
||||
У вбудованому реєстрі чат-каналів немає окремого каналу обміну повідомленнями Twilio WhatsApp.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -158,21 +158,21 @@ OpenClaw рекомендує за можливості запускати Whats
|
||||
## Модель виконання
|
||||
|
||||
- Gateway володіє сокетом WhatsApp і циклом повторного підключення.
|
||||
- Сторож повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку, тому тихий сеанс пов’язаного пристрою не перезапускається тільки через те, що останнім часом ніхто не надсилав повідомлень. Довший ліміт тиші застосунку все одно примусово виконує повторне підключення, якщо транспортні кадри продовжують надходити, але повідомлення застосунку не обробляються протягом вікна сторожа.
|
||||
- Часові параметри сокета Baileys явно задані в `web.whatsapp.*`: `keepAliveIntervalMs` керує пінгами застосунку WhatsApp Web, `connectTimeoutMs` керує таймаутом початкового handshake, а `defaultQueryTimeoutMs` керує таймаутами запитів Baileys.
|
||||
- Watchdog повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку, тому тихий сеанс пов’язаного пристрою не перезапускається лише через те, що останнім часом ніхто не надсилав повідомлення. Довший ліміт тиші застосунку все одно примусово виконує повторне підключення, якщо транспортні кадри продовжують надходити, але протягом вікна watchdog не обробляються повідомлення застосунку; після тимчасового повторного підключення для нещодавно активного сеансу ця перевірка тиші застосунку використовує звичайний тайм-аут повідомлень для першого вікна відновлення.
|
||||
- Таймінги сокета Baileys явно задані в `web.whatsapp.*`: `keepAliveIntervalMs` керує ping-ами застосунку WhatsApp Web, `connectTimeoutMs` керує тайм-аутом початкового handshake, а `defaultQueryTimeoutMs` керує тайм-аутами запитів Baileys.
|
||||
- Вихідні надсилання потребують активного слухача WhatsApp для цільового облікового запису.
|
||||
- Чати статусів і трансляцій ігноруються (`@status`, `@broadcast`).
|
||||
- Сторож повторного підключення відстежує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку: тихі сеанси пов’язаних пристроїв залишаються активними, доки транспортні кадри продовжуються, але зависання транспорту примушує повторне підключення значно раніше за пізніший шлях віддаленого відключення.
|
||||
- Прямі чати використовують правила сеансів DM (`session.dmScope`; стандартне `main` згортає DM до головного сеансу агента).
|
||||
- Чати статусів і розсилок ігноруються (`@status`, `@broadcast`).
|
||||
- Watchdog повторного підключення відстежує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку: тихі сеанси пов’язаних пристроїв залишаються активними, доки транспортні кадри продовжують надходити, але зупинка транспорту примушує повторне підключення значно раніше за пізніший шлях віддаленого від’єднання.
|
||||
- Прямі чати використовують правила сеансів DM (`session.dmScope`; стандартне `main` зводить DM до головного сеансу агента).
|
||||
- Групові сеанси ізольовані (`agent:<agentId>:whatsapp:group:<jid>`).
|
||||
- Транспорт WhatsApp Web поважає стандартні змінні середовища proxy на хості Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу конфігурації proxy на рівні хоста замість налаштувань proxy WhatsApp для конкретного каналу.
|
||||
- Коли `messages.removeAckAfterReply` увімкнено, OpenClaw очищає реакцію підтвердження WhatsApp після доставки видимої відповіді.
|
||||
- Транспорт WhatsApp Web поважає стандартні змінні середовища proxy на хості gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу proxy-конфігурації на рівні хоста над специфічними для каналу налаштуваннями proxy WhatsApp.
|
||||
- Коли `messages.removeAckAfterReply` увімкнено, OpenClaw очищає ack-реакцію WhatsApp після доставлення видимої відповіді.
|
||||
|
||||
## Хуки Plugin і конфіденційність
|
||||
## Hook-и plugin і приватність
|
||||
|
||||
Вхідні повідомлення WhatsApp можуть містити особистий вміст повідомлень, номери телефонів,
|
||||
ідентифікатори груп, імена відправників і поля кореляції сеансів. З цієї причини
|
||||
WhatsApp не транслює вхідні payload хуків `message_received` до plugins,
|
||||
WhatsApp не транслює вхідні payload-и hook `message_received` до plugins,
|
||||
якщо ви явно не ввімкнете це:
|
||||
|
||||
```json5
|
||||
@ -187,7 +187,7 @@ WhatsApp не транслює вхідні payload хуків `message_received
|
||||
}
|
||||
```
|
||||
|
||||
Можна обмежити це ввімкнення одним обліковим записом:
|
||||
Можна обмежити opt-in одним обліковим записом:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -205,8 +205,8 @@ WhatsApp не транслює вхідні payload хуків `message_received
|
||||
}
|
||||
```
|
||||
|
||||
Вмикайте це лише для plugins, яким ви довіряєте отримувати вміст та ідентифікатори
|
||||
вхідних повідомлень WhatsApp.
|
||||
Увімкніть це лише для plugins, яким ви довіряєте отримувати вміст вхідних повідомлень
|
||||
WhatsApp та ідентифікатори.
|
||||
|
||||
## Контроль доступу й активація
|
||||
|
||||
@ -214,60 +214,60 @@ WhatsApp не транслює вхідні payload хуків `message_received
|
||||
<Tab title="Політика DM">
|
||||
`channels.whatsapp.dmPolicy` керує доступом до прямих чатів:
|
||||
|
||||
- `pairing` (стандартно)
|
||||
- `pairing` (за замовчуванням)
|
||||
- `allowlist`
|
||||
- `open` (потребує, щоб `allowFrom` містив `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`allowFrom` приймає номери в стилі E.164 (нормалізуються внутрішньо).
|
||||
`allowFrom` приймає номери у стилі E.164 (нормалізуються внутрішньо).
|
||||
|
||||
Перевизначення для кількох облікових записів: `channels.whatsapp.accounts.<id>.dmPolicy` (і `allowFrom`) мають пріоритет над стандартними значеннями рівня каналу для цього облікового запису.
|
||||
Перевизначення для кількох облікових записів: `channels.whatsapp.accounts.<id>.dmPolicy` (і `allowFrom`) мають пріоритет над типовими значеннями рівня каналу для цього облікового запису.
|
||||
|
||||
Деталі поведінки під час виконання:
|
||||
Подробиці поведінки під час виконання:
|
||||
|
||||
- pairings зберігаються в channel allow-store і об’єднуються з налаштованим `allowFrom`
|
||||
- сполучення зберігаються в allow-store каналу та об’єднуються з налаштованим `allowFrom`
|
||||
- якщо allowlist не налаштовано, пов’язаний власний номер дозволено за замовчуванням
|
||||
- OpenClaw ніколи автоматично не створює pairing для вихідних DM `fromMe` (повідомлень, які ви надсилаєте собі з пов’язаного пристрою)
|
||||
- OpenClaw ніколи автоматично не сполучає вихідні DM `fromMe` (повідомлення, які ви надсилаєте собі з пов’язаного пристрою)
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Політика груп + allowlists">
|
||||
<Tab title="Політика груп + allowlist-и">
|
||||
Доступ до груп має два рівні:
|
||||
|
||||
1. **Allowlist членства в групах** (`channels.whatsapp.groups`)
|
||||
- якщо `groups` пропущено, усі групи придатні
|
||||
- якщо `groups` наявний, він діє як груповий allowlist (`"*"` дозволено)
|
||||
- якщо `groups` наявний, він діє як allowlist груп (`"*"` дозволено)
|
||||
|
||||
2. **Політика відправників групи** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
|
||||
- `open`: allowlist відправників обходиться
|
||||
- `allowlist`: відправник має відповідати `groupAllowFrom` (або `*`)
|
||||
- `disabled`: блокувати всі вхідні повідомлення груп
|
||||
- `allowlist`: відправник має збігатися з `groupAllowFrom` (або `*`)
|
||||
- `disabled`: блокувати всі групові вхідні повідомлення
|
||||
|
||||
Резервна логіка allowlist відправників:
|
||||
Резервний варіант allowlist відправників:
|
||||
|
||||
- якщо `groupAllowFrom` не задано, під час виконання використовується `allowFrom`, коли він доступний
|
||||
- allowlists відправників оцінюються перед активацією за згадкою/відповіддю
|
||||
- якщо `groupAllowFrom` не задано, runtime повертається до `allowFrom`, коли він доступний
|
||||
- allowlist-и відправників оцінюються до активації за згадкою/відповіддю
|
||||
|
||||
Примітка: якщо блок `channels.whatsapp` взагалі відсутній, резервна групова політика під час виконання — `allowlist` (із попереджувальним логом), навіть якщо задано `channels.defaults.groupPolicy`.
|
||||
Примітка: якщо блок `channels.whatsapp` взагалі відсутній, резервна групова політика runtime — `allowlist` (із попередженням у журналі), навіть якщо задано `channels.defaults.groupPolicy`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Згадки + /activation">
|
||||
Відповіді в групах за замовчуванням потребують згадки.
|
||||
Групові відповіді за замовчуванням потребують згадки.
|
||||
|
||||
Виявлення згадок охоплює:
|
||||
|
||||
- явні згадки WhatsApp ідентичності бота
|
||||
- налаштовані regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервний варіант `messages.groupChat.mentionPatterns`)
|
||||
- налаштовані шаблони regex згадок (`agents.list[].groupChat.mentionPatterns`, резервний варіант `messages.groupChat.mentionPatterns`)
|
||||
- транскрипти вхідних голосових нотаток для авторизованих групових повідомлень
|
||||
- неявне виявлення відповіді боту (відправник відповіді збігається з ідентичністю бота)
|
||||
|
||||
Примітка з безпеки:
|
||||
Примітка щодо безпеки:
|
||||
|
||||
- цитата/відповідь лише задовольняє перевірку згадки; вона **не** надає авторизацію відправнику
|
||||
- з `groupPolicy: "allowlist"` відправники поза allowlist все одно блокуються, навіть якщо вони відповідають на повідомлення користувача з allowlist
|
||||
- з `groupPolicy: "allowlist"` відправники поза allowlist усе одно блокуються, навіть якщо відповідають на повідомлення користувача з allowlist
|
||||
|
||||
Команда активації рівня сеансу:
|
||||
Команда активації на рівні сеансу:
|
||||
|
||||
- `/activation mention`
|
||||
- `/activation always`
|
||||
@ -279,10 +279,10 @@ WhatsApp не транслює вхідні payload хуків `message_received
|
||||
|
||||
## Поведінка особистого номера й self-chat
|
||||
|
||||
Коли пов’язаний власний номер також наявний у `allowFrom`, активуються захисти self-chat WhatsApp:
|
||||
Коли пов’язаний власний номер також присутній у `allowFrom`, активуються запобіжники WhatsApp self-chat:
|
||||
|
||||
- пропускати підтвердження прочитання для ходів self-chat
|
||||
- ігнорувати поведінку автоматичного спрацювання mention-JID, яка інакше пінгувала б вас
|
||||
- пропускати прочитані квитанції для self-chat ходів
|
||||
- ігнорувати поведінку автозапуску mention-JID, яка інакше ping-увала б вас
|
||||
- якщо `messages.responsePrefix` не задано, відповіді self-chat за замовчуванням мають вигляд `[{identity.name}]` або `[openclaw]`
|
||||
|
||||
## Нормалізація повідомлень і контекст
|
||||
@ -291,7 +291,7 @@ WhatsApp не транслює вхідні payload хуків `message_received
|
||||
<Accordion title="Вхідний envelope + контекст відповіді">
|
||||
Вхідні повідомлення WhatsApp обгортаються у спільний вхідний envelope.
|
||||
|
||||
Якщо існує цитована відповідь, контекст додається в такій формі:
|
||||
Якщо існує процитована відповідь, контекст додається в такій формі:
|
||||
|
||||
```text
|
||||
[Replying to <sender> id:<stanzaId>]
|
||||
@ -303,8 +303,8 @@ WhatsApp не транслює вхідні payload хуків `message_received
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Плейсхолдери медіа й витягування локації/контакту">
|
||||
Вхідні повідомлення лише з медіа нормалізуються з плейсхолдерами, такими як:
|
||||
<Accordion title="Media placeholders і видобування локації/контакту">
|
||||
Вхідні повідомлення лише з медіа нормалізуються з placeholder-ами, такими як:
|
||||
|
||||
- `<media:image>`
|
||||
- `<media:video>`
|
||||
@ -313,31 +313,31 @@ WhatsApp не транслює вхідні payload хуків `message_received
|
||||
- `<media:sticker>`
|
||||
|
||||
Авторизовані групові голосові нотатки транскрибуються перед перевіркою згадки, коли
|
||||
тіло містить лише `<media:audio>`, тож промовляння згадки бота в голосовій нотатці може
|
||||
викликати відповідь. Якщо транскрипт усе одно не згадує бота,
|
||||
транскрипт зберігається в очікуваній історії групи замість сирого плейсхолдера.
|
||||
body — лише `<media:audio>`, тож промовляння згадки бота в голосовій нотатці може
|
||||
викликати відповідь. Якщо транскрипт усе ще не згадує бота, його
|
||||
зберігають в очікуваній історії групи замість raw placeholder.
|
||||
|
||||
Тіла локацій використовують стислий текст координат. Мітки/коментарі локацій і дані контактів/vCard відображаються як відгороджені недовірені метадані, а не як вбудований текст prompt.
|
||||
Тіла локацій використовують стислий координатний текст. Позначки/коментарі локацій і подробиці контактів/vCard рендеряться як fenced недовірені метадані, а не inline prompt text.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вставлення очікуваної історії групи">
|
||||
Для груп необроблені повідомлення можуть буферизуватися й вставлятися як контекст, коли бот нарешті спрацьовує.
|
||||
<Accordion title="Ін’єкція очікуваної історії групи">
|
||||
Для груп необроблені повідомлення можуть буферизуватися й ін’єктуватися як контекст, коли бот нарешті запускається.
|
||||
|
||||
- стандартний ліміт: `50`
|
||||
- конфігурація: `channels.whatsapp.historyLimit`
|
||||
- резервний варіант: `messages.groupChat.historyLimit`
|
||||
- `0` вимикає
|
||||
|
||||
Маркери вставлення:
|
||||
Маркери ін’єкції:
|
||||
|
||||
- `[Chat messages since your last reply - for context]`
|
||||
- `[Current message - respond to this]`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підтвердження прочитання">
|
||||
Підтвердження прочитання за замовчуванням увімкнені для прийнятих вхідних повідомлень WhatsApp.
|
||||
<Accordion title="Прочитані квитанції">
|
||||
Прочитані квитанції ввімкнено за замовчуванням для прийнятих вхідних повідомлень WhatsApp.
|
||||
|
||||
Вимкнути глобально:
|
||||
|
||||
@ -367,47 +367,47 @@ WhatsApp не транслює вхідні payload хуків `message_received
|
||||
}
|
||||
```
|
||||
|
||||
Ходи self-chat пропускають підтвердження прочитання, навіть коли вони глобально ввімкнені.
|
||||
Ходи self-chat пропускають прочитані квитанції, навіть коли їх увімкнено глобально.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Доставка, фрагментація й медіа
|
||||
## Доставлення, розбиття на частини та медіа
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Фрагментація тексту">
|
||||
- стандартний ліміт фрагмента: `channels.whatsapp.textChunkLimit = 4000`
|
||||
<Accordion title="Розбиття тексту на частини">
|
||||
- стандартний ліміт частини: `channels.whatsapp.textChunkLimit = 4000`
|
||||
- `channels.whatsapp.chunkMode = "length" | "newline"`
|
||||
- режим `newline` віддає перевагу межам абзаців (порожнім рядкам), а потім переходить до безпечної за довжиною фрагментації
|
||||
- режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім повертається до безпечного за довжиною розбиття
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поведінка вихідних медіа">
|
||||
- підтримує зображення, відео, аудіо (голосову нотатку PTT) і document payloads
|
||||
- аудіомедіа надсилається через Baileys `audio` payload з `ptt: true`, тому клієнти WhatsApp відображають його як голосову нотатку push-to-talk
|
||||
- reply payloads зберігають `audioAsVoice`; вихідна голосова нотатка TTS для WhatsApp залишається на цьому шляху PTT, навіть коли провайдер повертає MP3 або WebM
|
||||
- підтримує зображення, відео, аудіо (голосову нотатку PTT) і документні payloads
|
||||
- аудіомедіа надсилається через payload Baileys `audio` з `ptt: true`, тому клієнти WhatsApp відображають його як голосову нотатку push-to-talk
|
||||
- payloads відповідей зберігають `audioAsVoice`; вивід голосових нотаток TTS для WhatsApp залишається на цьому шляху PTT, навіть коли provider повертає MP3 або WebM
|
||||
- нативне аудіо Ogg/Opus надсилається як `audio/ogg; codecs=opus` для сумісності з голосовими нотатками
|
||||
- аудіо не у форматі Ogg, зокрема вихід MP3/WebM Microsoft Edge TTS, перекодовується за допомогою `ffmpeg` у моно Ogg/Opus 48 кГц перед доставкою PTT
|
||||
- `/tts latest` надсилає останню відповідь асистента як одну голосову нотатку та пригнічує повторне надсилання тієї самої відповіді; `/tts chat on|off|default` керує авто-TTS для поточного чату WhatsApp
|
||||
- аудіо не у форматі Ogg, зокрема вивід Microsoft Edge TTS MP3/WebM, перекодовується за допомогою `ffmpeg` у моно Ogg/Opus 48 кГц перед доставкою PTT
|
||||
- `/tts latest` надсилає останню відповідь асистента як одну голосову нотатку й пригнічує повторні надсилання для тієї самої відповіді; `/tts chat on|off|default` керує авто-TTS для поточного чату WhatsApp
|
||||
- відтворення анімованих GIF підтримується через `gifPlayback: true` під час надсилання відео
|
||||
- підписи застосовуються до першого медіаелемента під час надсилання multi-media reply payloads, крім голосових нотаток PTT: для них спершу надсилається аудіо, а видимий текст окремо, оскільки клієнти WhatsApp не завжди стабільно відображають підписи до голосових нотаток
|
||||
- підписи застосовуються до першого медіаелемента під час надсилання payloads відповіді з кількома медіа, крім голосових нотаток PTT: для них аудіо надсилається першим, а видимий текст окремо, бо клієнти WhatsApp не завжди узгоджено відображають підписи голосових нотаток
|
||||
- джерелом медіа може бути HTTP(S), `file://` або локальні шляхи
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Обмеження розміру медіа та поведінка резервного варіанта">
|
||||
<Accordion title="Обмеження розміру медіа та поведінка fallback">
|
||||
- ліміт збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`)
|
||||
- ліміт надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`)
|
||||
- перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
|
||||
- зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб уміститися в ліміти
|
||||
- у разі помилки надсилання медіа резервний варіант для першого елемента надсилає текстове попередження замість мовчазного відкидання відповіді
|
||||
- перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
|
||||
- зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб вписатися в ліміти
|
||||
- у разі помилки надсилання медіа fallback для першого елемента надсилає текстове попередження замість беззвучного відкидання відповіді
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Видимість помилок
|
||||
|
||||
`channels.whatsapp.exposeErrorText` керує тим, чи доставляється текст помилки агента/провайдера назад у WhatsApp. Типове значення — `true`. Установіть `false`, щоб помилки у WhatsApp не показувалися, зберігаючи поведінку інших каналів.
|
||||
`channels.whatsapp.exposeErrorText` керує тим, чи текст помилки агента/provider доставляється назад у WhatsApp. Типове значення — `true`. Установіть його в `false`, щоб помилки в WhatsApp лишалися тихими, зберігаючи поведінку інших каналів.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -419,20 +419,20 @@ WhatsApp не транслює вхідні payload хуків `message_received
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts.<id>.exposeErrorText`.
|
||||
Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts.<id>.exposeErrorText`.
|
||||
|
||||
## Цитування відповідей
|
||||
|
||||
WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Керуйте цим через `channels.whatsapp.replyToMode`.
|
||||
WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Керуйте цим за допомогою `channels.whatsapp.replyToMode`.
|
||||
|
||||
| Значення | Поведінка |
|
||||
| Значення | Поведінка |
|
||||
| ----------- | --------------------------------------------------------------------- |
|
||||
| `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення |
|
||||
| `"first"` | Цитувати лише перший фрагмент вихідної відповіді |
|
||||
| `"all"` | Цитувати кожен фрагмент вихідної відповіді |
|
||||
| `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення |
|
||||
| `"first"` | Цитувати лише перший фрагмент вихідної відповіді |
|
||||
| `"all"` | Цитувати кожен фрагмент вихідної відповіді |
|
||||
| `"batched"` | Цитувати поставлені в чергу пакетні відповіді, залишаючи негайні відповіді без цитування |
|
||||
|
||||
Типово — `"off"`. Перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts.<id>.replyToMode`.
|
||||
Типово — `"off"`. Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts.<id>.replyToMode`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -450,14 +450,14 @@ WhatsApp підтримує нативне цитування відповіде
|
||||
|
||||
| Рівень | Ack-реакції | Реакції, ініційовані агентом | Опис |
|
||||
| ------------- | ----------- | ---------------------------- | ------------------------------------------------ |
|
||||
| `"off"` | Ні | Ні | Жодних реакцій |
|
||||
| `"off"` | Ні | Ні | Реакцій немає взагалі |
|
||||
| `"ack"` | Так | Ні | Лише Ack-реакції (підтвердження перед відповіддю) |
|
||||
| `"minimal"` | Так | Так (консервативно) | Ack + реакції агента з консервативними настановами |
|
||||
| `"minimal"` | Так | Так (обережно) | Ack + реакції агента з обережними настановами |
|
||||
| `"extensive"` | Так | Так (заохочується) | Ack + реакції агента із заохочувальними настановами |
|
||||
|
||||
Типово: `"minimal"`.
|
||||
|
||||
Перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts.<id>.reactionLevel`.
|
||||
Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts.<id>.reactionLevel`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -472,7 +472,7 @@ WhatsApp підтримує нативне цитування відповіде
|
||||
## Реакції підтвердження
|
||||
|
||||
WhatsApp підтримує негайні Ack-реакції після отримання вхідного повідомлення через `channels.whatsapp.ackReaction`.
|
||||
Ack-реакції обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` дорівнює `"off"`.
|
||||
Ack-реакції обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` має значення `"off"`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -490,8 +490,8 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
|
||||
Нотатки щодо поведінки:
|
||||
|
||||
- надсилається негайно після прийняття вхідного повідомлення (до відповіді)
|
||||
- помилки журналюються, але не блокують нормальну доставку відповіді
|
||||
- надсилається негайно після прийняття вхідного повідомлення (перед відповіддю)
|
||||
- помилки журналюються, але не блокують звичайну доставку відповіді
|
||||
- режим групи `mentions` реагує на ходи, спричинені згадкою; активація групи `always` діє як обхід цієї перевірки
|
||||
- WhatsApp використовує `channels.whatsapp.ackReaction` (застаріле `messages.ackReaction` тут не використовується)
|
||||
|
||||
@ -499,23 +499,23 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Вибір облікового запису та типові значення">
|
||||
- ідентифікатори облікових записів беруться з `channels.whatsapp.accounts`
|
||||
- типовий вибір облікового запису: `default`, якщо він є, інакше перший налаштований ідентифікатор облікового запису (відсортовано)
|
||||
- ідентифікатори облікових записів походять із `channels.whatsapp.accounts`
|
||||
- типовий вибір облікового запису: `default`, якщо наявний, інакше перший налаштований ідентифікатор облікового запису (відсортований)
|
||||
- ідентифікатори облікових записів внутрішньо нормалізуються для пошуку
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Шляхи облікових даних і сумісність зі старими версіями">
|
||||
<Accordion title="Шляхи облікових даних і сумісність зі спадковою схемою">
|
||||
- поточний шлях автентифікації: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
|
||||
- файл резервної копії: `creds.json.bak`
|
||||
- застаріла типова автентифікація в `~/.openclaw/credentials/` усе ще розпізнається/мігрується для потоків типового облікового запису
|
||||
- спадкова типова автентифікація в `~/.openclaw/credentials/` досі розпізнається/мігрується для потоків типового облікового запису
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поведінка виходу">
|
||||
`openclaw channels logout --channel whatsapp [--account <id>]` очищує стан автентифікації WhatsApp для цього облікового запису.
|
||||
`openclaw channels logout --channel whatsapp [--account <id>]` очищає стан автентифікації WhatsApp для цього облікового запису.
|
||||
|
||||
У застарілих каталогах автентифікації `oauth.json` зберігається, а файли автентифікації Baileys видаляються.
|
||||
У спадкових каталогах автентифікації `oauth.json` зберігається, а файли автентифікації Baileys видаляються.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -523,16 +523,16 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
## Інструменти, дії та записи конфігурації
|
||||
|
||||
- Підтримка інструментів агента включає дію реакції WhatsApp (`react`).
|
||||
- Обмеження дій:
|
||||
- Шлюзи дій:
|
||||
- `channels.whatsapp.actions.reactions`
|
||||
- `channels.whatsapp.actions.polls`
|
||||
- Записи конфігурації, ініційовані каналом, увімкнені типово (вимкнути через `channels.whatsapp.configWrites=false`).
|
||||
- Записи конфігурації, ініційовані каналом, увімкнено типово (вимикайте через `channels.whatsapp.configWrites=false`).
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Не прив’язано (потрібен QR)">
|
||||
Симптом: статус каналу повідомляє, що його не прив’язано.
|
||||
<Accordion title="Не пов’язано (потрібен QR)">
|
||||
Симптом: стан каналу повідомляє, що його не пов’язано.
|
||||
|
||||
Виправлення:
|
||||
|
||||
@ -543,12 +543,12 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Прив’язано, але від’єднано / цикл повторного підключення">
|
||||
Симптом: прив’язаний обліковий запис із повторюваними від’єднаннями або спробами повторного підключення.
|
||||
<Accordion title="Пов’язано, але відключено / цикл перепідключення">
|
||||
Симптом: пов’язаний обліковий запис із повторними відключеннями або спробами перепідключення.
|
||||
|
||||
Тихі облікові записи можуть залишатися підключеними після звичайного тайм-ауту повідомлень; watchdog
|
||||
перезапускається, коли активність транспорту WhatsApp Web зупиняється, сокет закривається або
|
||||
активність на рівні застосунку залишається тихою довше за розширене захисне вікно.
|
||||
перезапускається, коли транспортна активність WhatsApp Web зупиняється, сокет закривається або
|
||||
активність на рівні застосунку залишається беззвучною довше за розширене безпечне вікно.
|
||||
|
||||
Якщо журнали показують повторюване `status=408 Request Time-out Connection was lost`, налаштуйте
|
||||
таймінги сокета Baileys у `web.whatsapp`. Почніть зі скорочення
|
||||
@ -574,21 +574,21 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
За потреби повторно прив’яжіть через `channels login`.
|
||||
За потреби повторно пов’яжіть через `channels login`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вхід за QR завершується тайм-аутом за proxy">
|
||||
Симптом: `openclaw channels login --channel whatsapp` завершується помилкою до показу придатного QR-коду з `status=408 Request Time-out` або від’єднанням TLS-сокета.
|
||||
Симптом: `openclaw channels login --channel whatsapp` завершується помилкою до показу придатного QR-коду з `status=408 Request Time-out` або відключенням TLS-сокета.
|
||||
|
||||
Вхід у WhatsApp Web використовує стандартне proxy-середовище хоста Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, варіанти в нижньому регістрі та `NO_PROXY`). Перевірте, що процес Gateway успадковує proxy env і що `NO_PROXY` не відповідає `mmg.whatsapp.net`.
|
||||
Вхід у WhatsApp Web використовує стандартне proxy-середовище хоста Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, варіанти в нижньому регістрі та `NO_PROXY`). Переконайтеся, що процес Gateway успадковує proxy env і що `NO_PROXY` не відповідає `mmg.whatsapp.net`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Немає активного слухача під час надсилання">
|
||||
Вихідні надсилання швидко завершуються помилкою, коли для цільового облікового запису немає активного слухача Gateway.
|
||||
Вихідні надсилання швидко завершуються помилкою, коли для цільового облікового запису немає активного слухача gateway.
|
||||
|
||||
Переконайтеся, що Gateway запущено, а обліковий запис прив’язано.
|
||||
Переконайтеся, що gateway запущено, а обліковий запис пов’язано.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -598,46 +598,46 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
- `groupPolicy`
|
||||
- `groupAllowFrom` / `allowFrom`
|
||||
- записи allowlist у `groups`
|
||||
- обмеження за згадками (`requireMention` + шаблони згадок)
|
||||
- дубльовані ключі в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому тримайте один `groupPolicy` на кожну область
|
||||
- gating згадок (`requireMention` + шаблони згадок)
|
||||
- дублікати ключів у `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому тримайте один `groupPolicy` на scope
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Попередження runtime Bun">
|
||||
Runtime WhatsApp Gateway має використовувати Node. Bun позначено як несумісний для стабільної роботи WhatsApp/Telegram Gateway.
|
||||
Runtime Gateway для WhatsApp має використовувати Node. Bun позначено як несумісний для стабільної роботи gateway WhatsApp/Telegram.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Системні промпти
|
||||
## Системні prompts
|
||||
|
||||
WhatsApp підтримує системні промпти в стилі Telegram для груп і прямих чатів через мапи `groups` і `direct`.
|
||||
WhatsApp підтримує системні prompts у стилі Telegram для груп і прямих чатів через мапи `groups` і `direct`.
|
||||
|
||||
Ієрархія розв’язання для групових повідомлень:
|
||||
|
||||
Ефективна мапа `groups` визначається спочатку: якщо обліковий запис визначає власні `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук промпта виконується в отриманій єдиній мапі:
|
||||
Ефективна мапа `groups` визначається першою: якщо обліковий запис визначає власні `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук prompt виконується в отриманій єдиній мапі:
|
||||
|
||||
1. **Системний промпт конкретної групи** (`groups["<groupId>"].systemPrompt`): використовується, коли запис конкретної групи існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний промпт не застосовується.
|
||||
2. **Системний промпт wildcard для груп** (`groups["*"].systemPrompt`): використовується, коли запис конкретної групи повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
|
||||
1. **Системний prompt для конкретної групи** (`groups["<groupId>"].systemPrompt`): використовується, коли конкретний запис групи існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується й системний prompt не застосовується.
|
||||
2. **Системний prompt wildcard для груп** (`groups["*"].systemPrompt`): використовується, коли конкретний запис групи повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
|
||||
|
||||
Ієрархія розв’язання для прямих повідомлень:
|
||||
|
||||
Ефективна мапа `direct` визначається спочатку: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук промпта виконується в отриманій єдиній мапі:
|
||||
Ефективна мапа `direct` визначається першою: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук prompt виконується в отриманій єдиній мапі:
|
||||
|
||||
1. **Системний промпт конкретного прямого чату** (`direct["<peerId>"].systemPrompt`): використовується, коли запис конкретного peer існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний промпт не застосовується.
|
||||
2. **Системний промпт wildcard для прямих чатів** (`direct["*"].systemPrompt`): використовується, коли запис конкретного peer повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
|
||||
1. **Системний prompt для конкретного прямого чату** (`direct["<peerId>"].systemPrompt`): використовується, коли конкретний запис peer існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується й системний prompt не застосовується.
|
||||
2. **Системний prompt wildcard для прямих чатів** (`direct["*"].systemPrompt`): використовується, коли конкретний запис peer повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
|
||||
|
||||
<Note>
|
||||
`dms` залишається легким bucket перевизначень історії для окремих DM (`dms.<id>.historyLimit`). Перевизначення промптів розміщуються в `direct`.
|
||||
`dms` залишається легким bucket перевизначення історії для окремих DM (`dms.<id>.historyLimit`). Перевизначення prompt розміщуються в `direct`.
|
||||
</Note>
|
||||
|
||||
**Відмінність від поведінки Telegram із кількома обліковими записами:** У Telegram кореневий `groups` навмисно пригнічується для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для тих, що не визначають власні `groups`, — щоб запобігти отриманню ботом групових повідомлень для груп, до яких він не належить. WhatsApp не застосовує цей захист: кореневі `groups` і коренева `direct` завжди успадковуються обліковими записами, які не визначають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У конфігурації WhatsApp із кількома обліковими записами, якщо вам потрібні групові або прямі промпти для окремих облікових записів, явно визначайте повну мапу в кожному обліковому записі, а не покладайтеся на типові значення кореневого рівня.
|
||||
**Відмінність від поведінки Telegram із кількома обліковими записами:** У Telegram кореневі `groups` навмисно пригнічуються для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для облікових записів, які не визначають власних `groups`, — щоб запобігти отриманню ботом групових повідомлень із груп, до яких він не належить. WhatsApp не застосовує цей захист: кореневі `groups` і коренева `direct` завжди успадковуються обліковими записами, які не визначають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У конфігурації WhatsApp із кількома обліковими записами, якщо вам потрібні групові або прямі prompts для окремих облікових записів, визначайте повну мапу під кожним обліковим записом явно, а не покладайтеся на типові значення кореневого рівня.
|
||||
|
||||
Важлива поведінка:
|
||||
|
||||
- `channels.whatsapp.groups` є одночасно мапою конфігурації для окремих груп і allowlist груп на рівні чату. У кореневій області або області облікового запису `groups["*"]` означає «усі групи допускаються» для цієї області.
|
||||
- Додавайте wildcard group `systemPrompt` лише тоді, коли ви вже хочете, щоб ця область допускала всі групи. Якщо ви все ще хочете, щоб придатним був лише фіксований набір ідентифікаторів груп, не використовуйте `groups["*"]` як типове значення промпта. Натомість повторіть промпт у кожному явно доданому до allowlist записі групи.
|
||||
- Допуск групи та авторизація відправника — це окремі перевірки. `groups["*"]` розширює набір груп, які можуть потрапити до обробки груп, але сам по собі не авторизує кожного відправника в цих групах. Доступ відправника все ще окремо керується через `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`.
|
||||
- `channels.whatsapp.direct` не має такого самого побічного ефекту для DM. `direct["*"]` лише надає типову конфігурацію прямого чату після того, як DM уже допущено через `dmPolicy` плюс `allowFrom` або правила pairing-store.
|
||||
- `channels.whatsapp.groups` є і мапою конфігурації для окремих груп, і allowlist груп на рівні чату. У кореневому scope або scope облікового запису `groups["*"]` означає "допущено всі групи" для цього scope.
|
||||
- Додавайте wildcard-групу `systemPrompt` лише тоді, коли ви вже хочете, щоб цей scope допускав усі групи. Якщо ви все ще хочете, щоб придатним був лише фіксований набір group IDs, не використовуйте `groups["*"]` для типового prompt. Натомість повторіть prompt у кожному явно внесеному до allowlist записі групи.
|
||||
- Допуск групи та авторизація відправника є окремими перевірками. `groups["*"]` розширює набір груп, які можуть дійти до обробки груп, але саме по собі не авторизує кожного відправника в цих групах. Доступ відправника й далі окремо контролюється `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`.
|
||||
- `channels.whatsapp.direct` не має такого самого побічного ефекту для DM. `direct["*"]` лише надає типову конфігурацію прямого чату після того, як DM уже допущено правилами `dmPolicy` плюс `allowFrom` або pairing-store.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -679,20 +679,20 @@ WhatsApp підтримує системні промпти в стилі Telegr
|
||||
}
|
||||
```
|
||||
|
||||
## Вказівники до довідника конфігурації
|
||||
## Посилання на довідник конфігурації
|
||||
|
||||
Основний довідник:
|
||||
|
||||
- [Довідник конфігурації - WhatsApp](/uk/gateway/config-channels#whatsapp)
|
||||
|
||||
Ключові поля WhatsApp:
|
||||
Найважливіші поля WhatsApp:
|
||||
|
||||
- доступ: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`
|
||||
- доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel`, `exposeErrorText`
|
||||
- доставлення: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel`, `exposeErrorText`
|
||||
- кілька облікових записів: `accounts.<id>.enabled`, `accounts.<id>.authDir`, перевизначення на рівні облікового запису
|
||||
- операції: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`, `web.whatsapp.*`
|
||||
- поведінка сеансу: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms.<id>.historyLimit`
|
||||
- підказки: `groups.<id>.systemPrompt`, `groups["*"].systemPrompt`, `direct.<id>.systemPrompt`, `direct["*"].systemPrompt`
|
||||
- промпти: `groups.<id>.systemPrompt`, `groups["*"].systemPrompt`, `direct.<id>.systemPrompt`, `direct["*"].systemPrompt`
|
||||
|
||||
## Пов’язане
|
||||
|
||||
|
||||
@ -1,26 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібні кілька ізольованих агентів (робочі простори + маршрутизація + автентифікація)
|
||||
summary: Довідка CLI для `openclaw agents` (список/додавання/видалення/прив’язки/прив’язати/відв’язати/встановити ідентичність)
|
||||
summary: Довідник CLI для `openclaw agents` (list/add/delete/bindings/bind/unbind/set identity)
|
||||
title: Агенти
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T06:23:29Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-29T11:03:52Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 41683d8684eba61421124bc3977690ad40b01d63a109d931854638a5d2c372a2
|
||||
source_hash: 46742a890a57cb1035a053f14fe574044e4a3d7dcc04812cd11c633bd808819b
|
||||
source_path: cli/agents.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw agents`
|
||||
|
||||
Керуйте ізольованими агентами (робочі простори + автентифікація + маршрутизація).
|
||||
|
||||
Пов’язане:
|
||||
Пов’язано:
|
||||
|
||||
- [Маршрутизація між кількома агентами](/uk/concepts/multi-agent)
|
||||
- [Багатоагентна маршрутизація](/uk/concepts/multi-agent)
|
||||
- [Робочий простір агента](/uk/concepts/agent-workspace)
|
||||
- [Конфігурація Skills](/uk/tools/skills-config): конфігурація видимості навичок.
|
||||
- [Конфігурація Skills](/uk/tools/skills-config): конфігурація видимості skills.
|
||||
|
||||
## Приклади
|
||||
|
||||
@ -39,11 +39,11 @@ openclaw agents delete work
|
||||
|
||||
## Прив’язки маршрутизації
|
||||
|
||||
Використовуйте прив’язки маршрутизації, щоб закріпити вхідний трафік каналу за певним агентом.
|
||||
Використовуйте прив’язки маршрутизації, щоб закріпити вхідний трафік каналу за конкретним агентом.
|
||||
|
||||
Якщо ви також хочете різні видимі Skills для кожного агента, налаштуйте `agents.defaults.skills` і `agents.list[].skills` у `openclaw.json`. Див. [Конфігурація Skills](/uk/tools/skills-config) і [Довідка з конфігурації](/uk/gateway/config-agents#agents-defaults-skills).
|
||||
Якщо ви також хочете різні видимі skills для кожного агента, налаштуйте `agents.defaults.skills` і `agents.list[].skills` в `openclaw.json`. Див. [Конфігурація Skills](/uk/tools/skills-config) і [Довідник конфігурації](/uk/gateway/config-agents#agents-defaults-skills).
|
||||
|
||||
Перегляд прив’язок:
|
||||
Список прив’язок:
|
||||
|
||||
```bash
|
||||
openclaw agents bindings
|
||||
@ -51,21 +51,21 @@ openclaw agents bindings --agent work
|
||||
openclaw agents bindings --json
|
||||
```
|
||||
|
||||
Додавання прив’язок:
|
||||
Додати прив’язки:
|
||||
|
||||
```bash
|
||||
openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a
|
||||
```
|
||||
|
||||
Якщо ви не вказуєте `accountId` (`--bind <channel>`), OpenClaw визначає його з типових значень каналу та хуків налаштування Plugin, якщо вони доступні.
|
||||
Якщо ви пропустите `accountId` (`--bind <channel>`), OpenClaw визначить його з типових параметрів каналу та хуків налаштування Plugin, коли вони доступні.
|
||||
|
||||
Якщо ви не вказуєте `--agent` для `bind` або `unbind`, OpenClaw використовує поточний типовий агент.
|
||||
Якщо ви пропустите `--agent` для `bind` або `unbind`, OpenClaw націлиться на поточного типового агента.
|
||||
|
||||
### Поведінка області дії прив’язки
|
||||
|
||||
- Прив’язка без `accountId` відповідає лише типовому обліковому запису каналу.
|
||||
- `accountId: "*"` — це загальноканальний запасний варіант (усі облікові записи) і він менш специфічний, ніж явна прив’язка облікового запису.
|
||||
- Якщо той самий агент уже має відповідну прив’язку каналу без `accountId`, а ви пізніше додаєте прив’язку з явним або визначеним `accountId`, OpenClaw оновлює цю наявну прив’язку на місці замість додавання дубліката.
|
||||
- `accountId: "*"` є резервним варіантом для всього каналу (усі облікові записи) і менш специфічний, ніж явна прив’язка облікового запису.
|
||||
- Якщо той самий агент уже має відповідну прив’язку каналу без `accountId`, а згодом ви прив’язуєте з явним або визначеним `accountId`, OpenClaw оновлює цю наявну прив’язку на місці замість додавання дубліката.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -77,16 +77,16 @@ openclaw agents bind --agent work --bind telegram
|
||||
openclaw agents bind --agent work --bind telegram:ops
|
||||
```
|
||||
|
||||
Після такого оновлення маршрутизація для цієї прив’язки обмежується `telegram:ops`. Якщо вам також потрібна маршрутизація для типового облікового запису, додайте її явно (наприклад, `--bind telegram:default`).
|
||||
Після оновлення маршрутизація для цієї прив’язки обмежується `telegram:ops`. Якщо вам також потрібна маршрутизація для типового облікового запису, додайте її явно (наприклад, `--bind telegram:default`).
|
||||
|
||||
Видалення прив’язок:
|
||||
Видалити прив’язки:
|
||||
|
||||
```bash
|
||||
openclaw agents unbind --agent work --bind telegram:ops
|
||||
openclaw agents unbind --agent work --all
|
||||
```
|
||||
|
||||
`unbind` приймає або `--all`, або одне чи кілька значень `--bind`, але не обидва варіанти одночасно.
|
||||
`unbind` приймає або `--all`, або одне чи більше значень `--bind`, але не обидва варіанти одночасно.
|
||||
|
||||
## Поверхня команд
|
||||
|
||||
@ -99,7 +99,7 @@ openclaw agents unbind --agent work --all
|
||||
Параметри:
|
||||
|
||||
- `--json`
|
||||
- `--bindings`: включити повні правила маршрутизації, а не лише кількість/зведення по агентах
|
||||
- `--bindings`: включати повні правила маршрутизації, а не лише підрахунки/зведення за агентами
|
||||
|
||||
### `agents add [name]`
|
||||
|
||||
@ -114,9 +114,14 @@ openclaw agents unbind --agent work --all
|
||||
|
||||
Примітки:
|
||||
|
||||
- Передавання будь-яких явних прапорців додавання перемикає команду в неінтерактивний режим.
|
||||
- Неінтерактивний режим вимагає імені агента та `--workspace`.
|
||||
- `main` зарезервовано й не може використовуватися як ідентифікатор нового агента.
|
||||
- Передавання будь-яких явних прапорців додавання переводить команду в неінтерактивний шлях.
|
||||
- Неінтерактивний режим вимагає і назви агента, і `--workspace`.
|
||||
- `main` зарезервовано, і його не можна використовувати як id нового агента.
|
||||
- В інтерактивному режимі початкове заповнення автентифікації копіює лише переносні статичні профілі
|
||||
(`api_key` і статичний `token` за замовчуванням). Профілі OAuth refresh-token залишаються
|
||||
доступними лише через успадкування з читанням із реального сховища агента `main`.
|
||||
Якщо налаштований типовий агент не є `main`, увійдіть окремо для профілів OAuth
|
||||
у новому агенті.
|
||||
|
||||
### `agents bindings`
|
||||
|
||||
@ -129,7 +134,7 @@ openclaw agents unbind --agent work --all
|
||||
|
||||
Параметри:
|
||||
|
||||
- `--agent <id>` (типово використовується поточний типовий агент)
|
||||
- `--agent <id>` (за замовчуванням поточний типовий агент)
|
||||
- `--bind <channel[:accountId]>` (можна повторювати)
|
||||
- `--json`
|
||||
|
||||
@ -137,7 +142,7 @@ openclaw agents unbind --agent work --all
|
||||
|
||||
Параметри:
|
||||
|
||||
- `--agent <id>` (типово використовується поточний типовий агент)
|
||||
- `--agent <id>` (за замовчуванням поточний типовий агент)
|
||||
- `--bind <channel[:accountId]>` (можна повторювати)
|
||||
- `--all`
|
||||
- `--json`
|
||||
@ -153,7 +158,7 @@ openclaw agents unbind --agent work --all
|
||||
|
||||
- `main` не можна видалити.
|
||||
- Без `--force` потрібне інтерактивне підтвердження.
|
||||
- Каталоги робочого простору, стану агента та стенограм сеансів переміщуються до кошика, а не видаляються остаточно.
|
||||
- Робочий простір, стан агента та каталоги транскриптів сесій переміщуються до Кошика, а не видаляються остаточно.
|
||||
- Якщо робочий простір іншого агента має той самий шлях, розташований всередині цього робочого простору або містить цей робочий простір,
|
||||
робочий простір зберігається, а `--json` повідомляє `workspaceRetained`,
|
||||
`workspaceRetainedReason` і `workspaceSharedWith`.
|
||||
@ -163,18 +168,18 @@ openclaw agents unbind --agent work --all
|
||||
Кожен робочий простір агента може містити `IDENTITY.md` у корені робочого простору:
|
||||
|
||||
- Приклад шляху: `~/.openclaw/workspace/IDENTITY.md`
|
||||
- `set-identity --from-identity` читає дані з кореня робочого простору (або з явно вказаного `--identity-file`)
|
||||
- `set-identity --from-identity` читає з кореня робочого простору (або з явного `--identity-file`)
|
||||
|
||||
Шляхи до аватарів визначаються відносно кореня робочого простору.
|
||||
Шляхи аватарів визначаються відносно кореня робочого простору.
|
||||
|
||||
## Установлення ідентичності
|
||||
## Налаштування ідентичності
|
||||
|
||||
`set-identity` записує поля в `agents.list[].identity`:
|
||||
|
||||
- `name`
|
||||
- `theme`
|
||||
- `emoji`
|
||||
- `avatar` (шлях відносно робочого простору, URL `http(s)` або data URI)
|
||||
- `avatar` (шлях відносно робочого простору, URL http(s) або data URI)
|
||||
|
||||
Параметри:
|
||||
|
||||
@ -190,23 +195,23 @@ openclaw agents unbind --agent work --all
|
||||
|
||||
Примітки:
|
||||
|
||||
- Для вибору цільового агента можна використовувати `--agent` або `--workspace`.
|
||||
- Якщо ви покладаєтеся на `--workspace`, а кілька агентів використовують той самий робочий простір, команда завершиться з помилкою й попросить передати `--agent`.
|
||||
- Якщо явні поля ідентичності не задано, команда читає дані ідентичності з `IDENTITY.md`.
|
||||
- `--agent` або `--workspace` можна використовувати для вибору цільового агента.
|
||||
- Якщо ви покладаєтеся на `--workspace`, а кілька агентів спільно використовують цей робочий простір, команда завершується помилкою й просить передати `--agent`.
|
||||
- Коли явні поля ідентичності не надано, команда читає дані ідентичності з `IDENTITY.md`.
|
||||
|
||||
Завантаження з `IDENTITY.md`:
|
||||
Завантажити з `IDENTITY.md`:
|
||||
|
||||
```bash
|
||||
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
|
||||
```
|
||||
|
||||
Явне перевизначення полів:
|
||||
Явно перевизначити поля:
|
||||
|
||||
```bash
|
||||
openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png
|
||||
```
|
||||
|
||||
Приклад конфігурації:
|
||||
Зразок конфігурації:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -226,8 +231,8 @@ openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --ava
|
||||
}
|
||||
```
|
||||
|
||||
## Пов’язане
|
||||
## Пов’язано
|
||||
|
||||
- [Довідка CLI](/uk/cli)
|
||||
- [Маршрутизація між кількома агентами](/uk/concepts/multi-agent)
|
||||
- [Довідник CLI](/uk/cli)
|
||||
- [Багатоагентна маршрутизація](/uk/concepts/multi-agent)
|
||||
- [Робочий простір агента](/uk/concepts/agent-workspace)
|
||||
|
||||
@ -2,27 +2,27 @@
|
||||
read_when: You want multiple isolated agents (workspaces + auth) in one gateway process.
|
||||
sidebarTitle: Multi-agent routing
|
||||
status: active
|
||||
summary: 'Маршрутизація з кількома агентами: ізольовані агенти, облікові записи каналів і прив’язки'
|
||||
title: Багатоагентна маршрутизація
|
||||
summary: 'Багатоагентна маршрутизація: ізольовані агенти, облікові записи каналів і прив’язки'
|
||||
title: Маршрутизація між кількома агентами
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:09:04Z"
|
||||
generated_at: "2026-04-29T11:03:35Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 75770f058453345ef2de281d5fffb20ccfda5e73815e27b1643909a624007b86
|
||||
source_hash: 67adea74d5f97feff3f816cc4c34c9429e7659289013e5a7c7623bd185a50a31
|
||||
source_path: concepts/multi-agent.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Запускайте кілька _ізольованих_ агентів — кожен із власним робочим простором, каталогом стану (`agentDir`) та історією сеансів — плюс кілька облікових записів каналів (наприклад, два WhatsApp) в одному запущеному Gateway. Вхідні повідомлення маршрутизуються до правильного агента через прив’язки.
|
||||
Запускайте кілька _ізольованих_ агентів — кожен із власним робочим простором, каталогом стану (`agentDir`) та історією сеансів — а також кілька облікових записів каналів (наприклад, два WhatsApp) в одному запущеному Gateway. Вхідні повідомлення маршрутизуються до правильного агента через прив’язки.
|
||||
|
||||
**Агент** тут — це повна область для окремої персони: файли робочого простору, профілі автентифікації, реєстр моделей і сховище сеансів. `agentDir` — це каталог стану на диску, який містить цю конфігурацію для окремого агента в `~/.openclaw/agents/<agentId>/`. **Прив’язка** зіставляє обліковий запис каналу (наприклад, робочий простір Slack або номер WhatsApp) з одним із цих агентів.
|
||||
Тут **агент** — це повна область для окремої персони: файли робочого простору, профілі автентифікації, реєстр моделей і сховище сеансів. `agentDir` — це каталог стану на диску, який містить цю конфігурацію для окремого агента за шляхом `~/.openclaw/agents/<agentId>/`. **Прив’язка** зіставляє обліковий запис каналу (наприклад, робочий простір Slack або номер WhatsApp) з одним із цих агентів.
|
||||
|
||||
## Що таке "один агент"?
|
||||
## Що таке «один агент»?
|
||||
|
||||
**Агент** — це повністю обмежений за областю "мозок" із власними:
|
||||
**Агент** — це повністю окремий «мозок» із власними:
|
||||
|
||||
- **Робочим простором** (файли, AGENTS.md/SOUL.md/USER.md, локальні нотатки, правила персони).
|
||||
- **Каталогом стану** (`agentDir`) для профілів автентифікації, реєстру моделей і конфігурації для окремого агента.
|
||||
- **Каталогом стану** (`agentDir`) для профілів автентифікації, реєстру моделей і конфігурації окремого агента.
|
||||
- **Сховищем сеансів** (історія чату + стан маршрутизації) у `~/.openclaw/agents/<agentId>/sessions`.
|
||||
|
||||
Профілі автентифікації є **окремими для кожного агента**. Кожен агент читає зі свого власного:
|
||||
@ -32,19 +32,24 @@ x-i18n:
|
||||
```
|
||||
|
||||
<Note>
|
||||
`sessions_history` також є безпечнішим шляхом пригадування між сеансами тут: він повертає обмежене, очищене подання, а не сирий дамп стенограми. Пригадування асистента видаляє теги мислення, каркас `<relevant-memories>`, XML-навантаження викликів інструментів у звичайному тексті (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів), понижений каркас викликів інструментів, витеклі ASCII/повноширинні токени керування моделлю та некоректний XML викликів інструментів MiniMax перед редагуванням/обрізанням.
|
||||
`sessions_history` тут також є безпечнішим шляхом пригадування між сеансами: він повертає обмежене, очищене подання, а не сирий дамп транскрипту. Пригадування асистента прибирає теги міркувань, каркас `<relevant-memories>`, XML-навантаження викликів інструментів у звичайному тексті (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів), понижений каркас викликів інструментів, витеклі ASCII/повноширинні керівні токени моделі та некоректний MiniMax XML викликів інструментів перед редагуванням/обрізанням.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
Облікові дані головного агента **не** поширюються автоматично. Ніколи не використовуйте `agentDir` повторно для кількох агентів (це спричиняє конфлікти автентифікації/сеансів). Якщо хочете поширити облікові дані, скопіюйте `auth-profiles.json` в `agentDir` іншого агента.
|
||||
Ніколи не використовуйте той самий `agentDir` для кількох агентів (це спричиняє конфлікти автентифікації/сеансів). Агенти
|
||||
можуть читати профілі автентифікації типового/головного агента, коли не мають
|
||||
локального профілю, але OpenClaw не клонує OAuth refresh tokens у
|
||||
сховище вторинного агента. Якщо вам потрібен незалежний обліковий запис OAuth, увійдіть із
|
||||
цього агента; якщо копіюєте облікові дані вручну, копіюйте лише переносні статичні
|
||||
профілі `api_key` або `token`.
|
||||
</Warning>
|
||||
|
||||
Skills завантажуються з робочого простору кожного агента плюс спільних коренів, таких як `~/.openclaw/skills`, а потім фільтруються за ефективним списком дозволених Skills агента, якщо він налаштований. Використовуйте `agents.defaults.skills` для спільної бази та `agents.list[].skills` для заміни на рівні агента. Див. [Skills: для окремого агента й спільні](/uk/tools/skills#per-agent-vs-shared-skills) і [Skills: списки дозволених Skills агента](/uk/tools/skills#agent-skill-allowlists).
|
||||
Skills завантажуються з робочого простору кожного агента, а також зі спільних коренів, як-от `~/.openclaw/skills`, після чого фільтруються за ефективним списком дозволених Skills агента, якщо його налаштовано. Використовуйте `agents.defaults.skills` для спільної бази та `agents.list[].skills` для заміни на рівні окремого агента. Див. [Skills: для окремого агента чи спільні](/uk/tools/skills#per-agent-vs-shared-skills) і [Skills: списки дозволених Skills агента](/uk/tools/skills#agent-skill-allowlists).
|
||||
|
||||
Gateway може розміщувати **одного агента** (типово) або **багато агентів** поруч.
|
||||
Gateway може розміщувати **одного агента** (типово) або **багатьох агентів** поруч.
|
||||
|
||||
<Note>
|
||||
**Примітка щодо робочого простору:** робочий простір кожного агента є **типовим cwd**, а не жорсткою пісочницею. Відносні шляхи розв’язуються всередині робочого простору, але абсолютні шляхи можуть діставатися інших розташувань хоста, якщо пісочницю не ввімкнено. Див. [Пісочниця](/uk/gateway/sandboxing).
|
||||
**Примітка щодо робочого простору:** робочий простір кожного агента є **типовим cwd**, а не жорсткою пісочницею. Відносні шляхи розв’язуються всередині робочого простору, але абсолютні шляхи можуть досягати інших розташувань хоста, якщо пісочницю не ввімкнено. Див. [Пісочниця](/uk/gateway/sandboxing).
|
||||
</Note>
|
||||
|
||||
## Шляхи (коротка мапа)
|
||||
@ -59,14 +64,14 @@ Gateway може розміщувати **одного агента** (типо
|
||||
|
||||
Якщо нічого не робити, OpenClaw запускає одного агента:
|
||||
|
||||
- `agentId` типово дорівнює **`main`**.
|
||||
- `agentId` типово має значення **`main`**.
|
||||
- Сеанси мають ключі у форматі `agent:main:<mainKey>`.
|
||||
- Робочий простір типово `~/.openclaw/workspace` (або `~/.openclaw/workspace-<profile>`, коли встановлено `OPENCLAW_PROFILE`).
|
||||
- Стан типово `~/.openclaw/agents/main/agent`.
|
||||
- Робочий простір типово дорівнює `~/.openclaw/workspace` (або `~/.openclaw/workspace-<profile>`, коли встановлено `OPENCLAW_PROFILE`).
|
||||
- Стан типово зберігається в `~/.openclaw/agents/main/agent`.
|
||||
|
||||
## Помічник агента
|
||||
|
||||
Використовуйте майстер агентів, щоб додати нового ізольованого агента:
|
||||
Скористайтеся майстром агентів, щоб додати нового ізольованого агента:
|
||||
|
||||
```bash
|
||||
openclaw agents add work
|
||||
@ -84,18 +89,18 @@ openclaw agents list --bindings
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть робочий простір кожного агента">
|
||||
Використайте майстер або створіть робочі простори вручну:
|
||||
Скористайтеся майстром або створіть робочі простори вручну:
|
||||
|
||||
```bash
|
||||
openclaw agents add coding
|
||||
openclaw agents add social
|
||||
```
|
||||
|
||||
Кожен агент отримує власний робочий простір із `SOUL.md`, `AGENTS.md` і необов’язковим `USER.md`, а також окремий `agentDir` і сховище сеансів у `~/.openclaw/agents/<agentId>`.
|
||||
Кожен агент отримує власний робочий простір із `SOUL.md`, `AGENTS.md` і необов’язковим `USER.md`, а також виділений `agentDir` і сховище сеансів у `~/.openclaw/agents/<agentId>`.
|
||||
|
||||
</Step>
|
||||
<Step title="Створіть облікові записи каналів">
|
||||
Створіть один обліковий запис на агента у бажаних каналах:
|
||||
Створіть по одному обліковому запису для кожного агента у вибраних каналах:
|
||||
|
||||
- Discord: один бот на агента, увімкніть Message Content Intent, скопіюйте кожен токен.
|
||||
- Telegram: один бот на агента через BotFather, скопіюйте кожен токен.
|
||||
@ -109,7 +114,7 @@ openclaw agents list --bindings
|
||||
|
||||
</Step>
|
||||
<Step title="Додайте агентів, облікові записи та прив’язки">
|
||||
Додайте агентів у `agents.list`, облікові записи каналів у `channels.<channel>.accounts` і з’єднайте їх через `bindings` (приклади нижче).
|
||||
Додайте агентів у `agents.list`, облікові записи каналів у `channels.<channel>.accounts` і з’єднайте їх за допомогою `bindings` (приклади нижче).
|
||||
</Step>
|
||||
<Step title="Перезапустіть і перевірте">
|
||||
```bash
|
||||
@ -124,15 +129,15 @@ openclaw agents list --bindings
|
||||
|
||||
З **кількома агентами** кожен `agentId` стає **повністю ізольованою персоною**:
|
||||
|
||||
- **Різні номери телефонів/облікові записи** (на `accountId` каналу).
|
||||
- **Різні номери телефонів/облікові записи** (окремий `accountId` для кожного каналу).
|
||||
- **Різні особистості** (файли робочого простору окремого агента, як-от `AGENTS.md` і `SOUL.md`).
|
||||
- **Окрема автентифікація + сеанси** (без взаємного впливу, якщо це явно не ввімкнено).
|
||||
- **Окрема автентифікація + сеанси** (без перетинів, якщо це явно не ввімкнено).
|
||||
|
||||
Це дає змогу **кільком людям** спільно використовувати один сервер Gateway, зберігаючи їхні AI-"мізки" й дані ізольованими.
|
||||
Це дає змогу **кільком людям** спільно використовувати один сервер Gateway, зберігаючи їхні AI-«мізки» та дані ізольованими.
|
||||
|
||||
## Пошук QMD-пам’яті між агентами
|
||||
|
||||
Якщо один агент має шукати в QMD-стенограмах сеансів іншого агента, додайте додаткові колекції в `agents.list[].memorySearch.qmd.extraCollections`. Використовуйте `agents.defaults.memorySearch.qmd.extraCollections` лише тоді, коли кожен агент має успадкувати ті самі спільні колекції стенограм.
|
||||
Якщо один агент має шукати транскрипти QMD-сеансів іншого агента, додайте додаткові колекції в `agents.list[].memorySearch.qmd.extraCollections`. Використовуйте `agents.defaults.memorySearch.qmd.extraCollections` лише тоді, коли кожен агент має успадковувати ті самі спільні колекції транскриптів.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -165,14 +170,14 @@ openclaw agents list --bindings
|
||||
}
|
||||
```
|
||||
|
||||
Шлях додаткової колекції може бути спільним для агентів, але назва колекції залишається явною, коли шлях розташований поза робочим простором агента. Шляхи всередині робочого простору залишаються обмеженими агентом, тож кожен агент зберігає власний набір пошуку стенограм.
|
||||
Шлях додаткової колекції може бути спільним для кількох агентів, але назва колекції лишається явною, коли шлях розташований поза робочим простором агента. Шляхи всередині робочого простору лишаються прив’язаними до агента, тож кожен агент зберігає власний набір пошуку транскриптів.
|
||||
|
||||
## Один номер WhatsApp, кілька людей (розділення DM)
|
||||
|
||||
Можна маршрутизувати **різні DM WhatsApp** до різних агентів, залишаючись на **одному обліковому записі WhatsApp**. Зіставляйте за E.164 відправника (наприклад, `+15551234567`) з `peer.kind: "direct"`. Відповіді все одно надходять з того самого номера WhatsApp (без ідентичності відправника для окремого агента).
|
||||
Ви можете маршрутизувати **різні WhatsApp DM** до різних агентів, залишаючись в **одному обліковому записі WhatsApp**. Зіставляйте за E.164 відправника (наприклад, `+15551234567`) з `peer.kind: "direct"`. Відповіді все одно надходитимуть із того самого номера WhatsApp (без окремої ідентичності відправника для кожного агента).
|
||||
|
||||
<Note>
|
||||
Прямі чати згортаються до **головного ключа сеансу** агента, тому справжня ізоляція вимагає **одного агента на людину**.
|
||||
Прямі чати згортаються до **головного ключа сеансу** агента, тому справжня ізоляція потребує **одного агента на людину**.
|
||||
</Note>
|
||||
|
||||
Приклад:
|
||||
@ -206,7 +211,7 @@ openclaw agents list --bindings
|
||||
|
||||
Примітки:
|
||||
|
||||
- Керування доступом до DM є **глобальним для облікового запису WhatsApp** (спарювання/allowlist), а не окремим для агента.
|
||||
- Контроль доступу DM є **глобальним для облікового запису WhatsApp** (спарювання/список дозволених), а не окремим для кожного агента.
|
||||
- Для спільних груп прив’яжіть групу до одного агента або використовуйте [Групи трансляції](/uk/channels/broadcast-groups).
|
||||
|
||||
## Правила маршрутизації (як повідомлення вибирають агента)
|
||||
@ -218,10 +223,10 @@ openclaw agents list --bindings
|
||||
Точний id DM/групи/каналу.
|
||||
</Step>
|
||||
<Step title="збіг parentPeer">
|
||||
Успадкування потоку.
|
||||
Успадкування гілки.
|
||||
</Step>
|
||||
<Step title="guildId + ролі">
|
||||
Маршрутизація ролей Discord.
|
||||
Маршрутизація за ролями Discord.
|
||||
</Step>
|
||||
<Step title="guildId">
|
||||
Discord.
|
||||
@ -230,7 +235,7 @@ openclaw agents list --bindings
|
||||
Slack.
|
||||
</Step>
|
||||
<Step title="збіг accountId для каналу">
|
||||
Резервний варіант для облікового запису.
|
||||
Резервний варіант для окремого облікового запису.
|
||||
</Step>
|
||||
<Step title="Збіг на рівні каналу">
|
||||
`accountId: "*"`.
|
||||
@ -241,24 +246,24 @@ openclaw agents list --bindings
|
||||
</Steps>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Розв’язання збігів і семантика AND">
|
||||
- Якщо кілька прив’язок збігаються на одному рівні, перемагає перша в порядку конфігурації.
|
||||
- Якщо прив’язка задає кілька полів зіставлення (наприклад, `peer` + `guildId`), потрібні всі указані поля (семантика `AND`).
|
||||
<Accordion title="Розв’язання нічиїх і семантика AND">
|
||||
- Якщо в одному рівні збігається кілька прив’язок, перемагає перша в порядку конфігурації.
|
||||
- Якщо прив’язка задає кілька полів збігу (наприклад, `peer` + `guildId`), потрібні всі зазначені поля (семантика `AND`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Деталі області облікового запису">
|
||||
- Прив’язка, яка пропускає `accountId`, збігається лише з типовим обліковим записом.
|
||||
- Використовуйте `accountId: "*"` для резервного варіанта на весь канал у всіх облікових записах.
|
||||
- Якщо згодом додати ту саму прив’язку для того самого агента з явним id облікового запису, OpenClaw оновить наявну прив’язку лише до каналу до прив’язки з областю облікового запису замість дублювання.
|
||||
- Прив’язка, яка пропускає `accountId`, відповідає лише типовому обліковому запису.
|
||||
- Використовуйте `accountId: "*"` для резервного варіанта на весь канал для всіх облікових записів.
|
||||
- Якщо згодом додати ту саму прив’язку для того самого агента з явним id облікового запису, OpenClaw оновить наявну прив’язку лише каналу до області облікового запису замість її дублювання.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Кілька облікових записів / номерів телефонів
|
||||
|
||||
Канали, які підтримують **кілька облікових записів** (наприклад, WhatsApp), використовують `accountId` для ідентифікації кожного входу. Кожен `accountId` можна маршрутизувати до іншого агента, тож один сервер може розміщувати кілька номерів телефонів без змішування сеансів.
|
||||
Канали, які підтримують **кілька облікових записів** (наприклад, WhatsApp), використовують `accountId` для ідентифікації кожного входу. Кожен `accountId` можна маршрутизувати до іншого агента, тому один сервер може розміщувати кілька номерів телефонів без змішування сеансів.
|
||||
|
||||
Якщо потрібен типовий обліковий запис на весь канал, коли `accountId` пропущено, установіть `channels.<channel>.defaultAccount` (необов’язково). Якщо не встановлено, OpenClaw повертається до `default`, якщо він є, інакше до першого налаштованого id облікового запису (відсортовано).
|
||||
Якщо потрібен типовий обліковий запис для всього каналу, коли `accountId` пропущено, задайте `channels.<channel>.defaultAccount` (необов’язково). Якщо не задано, OpenClaw повертається до `default`, якщо він є, інакше до першого налаштованого id облікового запису (у відсортованому порядку).
|
||||
|
||||
Поширені канали, що підтримують цей шаблон:
|
||||
|
||||
@ -266,18 +271,18 @@ openclaw agents list --bindings
|
||||
- `irc`, `line`, `googlechat`, `mattermost`, `matrix`, `nextcloud-talk`
|
||||
- `bluebubbles`, `zalo`, `zalouser`, `nostr`, `feishu`
|
||||
|
||||
## Концепції
|
||||
## Поняття
|
||||
|
||||
- `agentId`: один "мозок" (робочий простір, автентифікація для окремого агента, сховище сеансів для окремого агента).
|
||||
- `agentId`: один «мозок» (робочий простір, автентифікація окремого агента, сховище сеансів окремого агента).
|
||||
- `accountId`: один екземпляр облікового запису каналу (наприклад, обліковий запис WhatsApp `"personal"` проти `"biz"`).
|
||||
- `binding`: маршрутизує вхідні повідомлення до `agentId` за `(channel, accountId, peer)` і необов’язково id гільдії/команди.
|
||||
- Прямі чати згортаються до `agent:<agentId>:<mainKey>` ("main" для окремого агента; `session.mainKey`).
|
||||
- `binding`: маршрутизує вхідні повідомлення до `agentId` за `(channel, accountId, peer)` і, за потреби, id гільдії/команди.
|
||||
- Прямі чати згортаються до `agent:<agentId>:<mainKey>` («головний» для окремого агента; `session.mainKey`).
|
||||
|
||||
## Приклади платформ
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Боти Discord для кожного агента">
|
||||
Кожен обліковий запис бота Discord зіставляється з унікальним `accountId`. Прив’яжіть кожен обліковий запис до агента й зберігайте allowlist для кожного бота.
|
||||
Кожен обліковий запис бота Discord зіставляється з унікальним `accountId`. Прив’яжіть кожен обліковий запис до агента й підтримуйте списки дозволених окремо для кожного бота.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -322,10 +327,10 @@ openclaw agents list --bindings
|
||||
```
|
||||
|
||||
- Запросіть кожного бота до гільдії та ввімкніть Message Content Intent.
|
||||
- Токени зберігаються в `channels.discord.accounts.<id>.token` (типовий обліковий запис може використовувати `DISCORD_BOT_TOKEN`).
|
||||
- Токени зберігаються в `channels.discord.accounts.<id>.token` (обліковий запис за замовчуванням може використовувати `DISCORD_BOT_TOKEN`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Telegram bots per agent">
|
||||
<Accordion title="Боти Telegram для кожного агента">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -356,12 +361,12 @@ openclaw agents list --bindings
|
||||
}
|
||||
```
|
||||
|
||||
- Створіть одного бота для кожного агента через BotFather і скопіюйте кожен токен.
|
||||
- Створіть по одному боту для кожного агента за допомогою BotFather і скопіюйте кожен токен.
|
||||
- Токени зберігаються в `channels.telegram.accounts.<id>.botToken` (обліковий запис за замовчуванням може використовувати `TELEGRAM_BOT_TOKEN`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="WhatsApp numbers per agent">
|
||||
Прив’яжіть кожен обліковий запис перед запуском Gateway:
|
||||
<Accordion title="Номери WhatsApp для кожного агента">
|
||||
Зв’яжіть кожен обліковий запис перед запуском Gateway:
|
||||
|
||||
```bash
|
||||
openclaw channels login --channel whatsapp --account personal
|
||||
@ -437,8 +442,8 @@ openclaw agents list --bindings
|
||||
## Поширені шаблони
|
||||
|
||||
<Tabs>
|
||||
<Tab title="WhatsApp daily + Telegram deep work">
|
||||
Розділіть за каналом: маршрутизуйте WhatsApp до швидкого повсякденного агента, а Telegram — до агента Opus.
|
||||
<Tab title="WhatsApp щодня + Telegram для глибокої роботи">
|
||||
Розділіть за каналом: спрямовуйте WhatsApp до швидкого повсякденного агента, а Telegram до агента Opus.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -467,12 +472,12 @@ openclaw agents list --bindings
|
||||
|
||||
Примітки:
|
||||
|
||||
- Якщо у вас є кілька облікових записів для каналу, додайте `accountId` до прив’язки (наприклад `{ channel: "whatsapp", accountId: "personal" }`).
|
||||
- Щоб маршрутизувати один DM/групу до Opus, залишаючи решту в чаті, додайте прив’язку `match.peer` для цього співрозмовника; збіги співрозмовника завжди мають перевагу над правилами для всього каналу.
|
||||
- Якщо у вас є кілька облікових записів для каналу, додайте `accountId` до прив’язки (наприклад, `{ channel: "whatsapp", accountId: "personal" }`).
|
||||
- Щоб спрямувати один особистий чат/групу до Opus, залишивши решту в чаті, додайте прив’язку `match.peer` для цього співрозмовника; відповідності співрозмовника завжди мають перевагу над правилами для всього каналу.
|
||||
|
||||
</Tab>
|
||||
<Tab title="Same channel, one peer to Opus">
|
||||
Залиште WhatsApp на швидкому агенті, але маршрутизуйте один DM до Opus:
|
||||
<Tab title="Той самий канал, один співрозмовник до Opus">
|
||||
Залиште WhatsApp на швидкому агенті, але спрямуйте один особистий чат до Opus:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -502,11 +507,11 @@ openclaw agents list --bindings
|
||||
}
|
||||
```
|
||||
|
||||
Прив’язки співрозмовника завжди мають перевагу, тому тримайте їх над правилом для всього каналу.
|
||||
Прив’язки peer завжди мають перевагу, тому тримайте їх вище за правило для всього каналу.
|
||||
|
||||
</Tab>
|
||||
<Tab title="Family agent bound to a WhatsApp group">
|
||||
Прив’яжіть окремого сімейного агента до однієї групи WhatsApp, із фільтрацією за згадками та суворішою політикою інструментів:
|
||||
Прив’яжіть спеціального сімейного агента до однієї групи WhatsApp із gating за згадками та суворішою політикою інструментів:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -553,13 +558,13 @@ openclaw agents list --bindings
|
||||
|
||||
Примітки:
|
||||
|
||||
- Списки дозволених/заборонених інструментів стосуються **інструментів**, а не Skills. Якщо Skills потрібно запустити бінарний файл, переконайтеся, що `exec` дозволено, а бінарний файл існує в пісочниці.
|
||||
- Для суворішої фільтрації задайте `agents.list[].groupChat.mentionPatterns` і залиште ввімкненими списки дозволених груп для каналу.
|
||||
- Списки дозволу/заборони інструментів стосуються **інструментів**, а не skills. Якщо skill має запускати бінарний файл, переконайтеся, що `exec` дозволено, а бінарний файл існує в пісочниці.
|
||||
- Для суворішого gating задайте `agents.list[].groupChat.mentionPatterns` і залиште ввімкненими allowlist груп для каналу.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Налаштування пісочниці та інструментів для кожного агента
|
||||
## Конфігурація пісочниці й інструментів для кожного агента
|
||||
|
||||
Кожен агент може мати власну пісочницю та обмеження інструментів:
|
||||
|
||||
@ -597,25 +602,25 @@ openclaw agents list --bindings
|
||||
```
|
||||
|
||||
<Note>
|
||||
`setupCommand` розташований у `sandbox.docker` і виконується один раз під час створення контейнера. Перевизначення `sandbox.docker.*` для окремого агента ігноруються, коли визначена область дії дорівнює `"shared"`.
|
||||
`setupCommand` розташовується в `sandbox.docker` і виконується один раз під час створення контейнера. Перевизначення `sandbox.docker.*` для окремого агента ігноруються, коли визначена область дії дорівнює `"shared"`.
|
||||
</Note>
|
||||
|
||||
**Переваги:**
|
||||
|
||||
- **Ізоляція безпеки**: обмежуйте інструменти для ненадійних агентів.
|
||||
- **Контроль ресурсів**: ізолюйте конкретних агентів у пісочниці, залишаючи інших на хості.
|
||||
- **Ізоляція безпеки**: обмежуйте інструменти для недовірених агентів.
|
||||
- **Контроль ресурсів**: запускайте конкретних агентів у пісочниці, залишаючи інших на хості.
|
||||
- **Гнучкі політики**: різні дозволи для кожного агента.
|
||||
|
||||
<Note>
|
||||
`tools.elevated` є **глобальним** і залежить від відправника; його не можна налаштувати для окремого агента. Якщо вам потрібні межі для кожного агента, використовуйте `agents.list[].tools`, щоб заборонити `exec`. Для націлювання на групи використовуйте `agents.list[].groupChat.mentionPatterns`, щоб @згадки чітко відповідали потрібному агенту.
|
||||
`tools.elevated` є **глобальним** і базується на відправнику; його не можна налаштувати для окремого агента. Якщо потрібні межі для кожного агента, використовуйте `agents.list[].tools`, щоб заборонити `exec`. Для націлювання на групу використовуйте `agents.list[].groupChat.mentionPatterns`, щоб @згадки коректно зіставлялися з потрібним агентом.
|
||||
</Note>
|
||||
|
||||
Див. [пісочницю та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools) для докладних прикладів.
|
||||
Див. [Пісочниця та інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools), щоб переглянути докладні приклади.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [агенти ACP](/uk/tools/acp-agents) — запуск зовнішніх середовищ для програмування
|
||||
- [Агенти ACP](/uk/tools/acp-agents) — запуск зовнішніх середовищ для кодування
|
||||
- [Маршрутизація каналів](/uk/channels/channel-routing) — як повідомлення маршрутизуються до агентів
|
||||
- [Присутність](/uk/concepts/presence) — присутність і доступність агента
|
||||
- [Сесія](/uk/concepts/session) — ізоляція та маршрутизація сесії
|
||||
- [Субагенти](/uk/tools/subagents) — запуск фонових виконань агента
|
||||
- [Сесія](/uk/concepts/session) — ізоляція та маршрутизація сесій
|
||||
- [Субагенти](/uk/tools/subagents) — запуск фонових виконань агентів
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете зрозуміти OAuth в OpenClaw від початку до кінця
|
||||
- Ви хочете зрозуміти OpenClaw OAuth від початку до кінця
|
||||
- Ви зіткнулися з проблемами анулювання токена / виходу з облікового запису
|
||||
- Вам потрібні потоки автентифікації Claude CLI або OAuth
|
||||
- Вам потрібні кілька облікових записів або маршрутизація профілів
|
||||
summary: 'OAuth в OpenClaw: обмін токенами, зберігання та шаблони роботи з кількома обліковими записами'
|
||||
title: OAuth
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T06:56:13Z"
|
||||
generated_at: "2026-04-29T11:04:03Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 493251e4341489e5fba9ab561d71200245d26888e10f153239d2ac8fc8fe1830
|
||||
source_hash: b4b228c83a79afa4018e9572f790ddfef016a73d2383d2847facdc5bb61ed004
|
||||
source_path: concepts/oauth.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -23,14 +23,14 @@ OpenClaw підтримує “автентифікацію за підписк
|
||||
- **Anthropic Claude CLI / автентифікація за підпискою всередині OpenClaw**: співробітники Anthropic
|
||||
повідомили нам, що таке використання знову дозволене
|
||||
|
||||
OpenAI Codex OAuth явно підтримується для використання в зовнішніх інструментах, як-от
|
||||
OpenAI Codex OAuth явно підтримується для використання у зовнішніх інструментах, як-от
|
||||
OpenClaw. На цій сторінці пояснюється:
|
||||
|
||||
Для Anthropic у продакшені автентифікація за API-ключем є безпечнішим рекомендованим шляхом.
|
||||
Для Anthropic у production безпечнішим рекомендованим шляхом є автентифікація через API-ключ.
|
||||
|
||||
- як працює **обмін токенів** OAuth (PKCE)
|
||||
- як працює **обмін токена** OAuth (PKCE)
|
||||
- де **зберігаються** токени (і чому)
|
||||
- як працювати з **кількома обліковими записами** (профілі + перевизначення для окремих сеансів)
|
||||
- як працювати з **кількома обліковими записами** (профілі + перевизначення для окремих сесій)
|
||||
|
||||
OpenClaw також підтримує **плагіни провайдерів**, які постачають власні потоки OAuth або API‑ключів.
|
||||
Запускайте їх через:
|
||||
@ -39,111 +39,121 @@ OpenClaw також підтримує **плагіни провайдерів**
|
||||
openclaw models auth login --provider <id>
|
||||
```
|
||||
|
||||
## Приймач токенів (чому він існує)
|
||||
## Приймач токенів (навіщо він потрібен)
|
||||
|
||||
Провайдери OAuth часто створюють **новий refresh-токен** під час потоків входу/оновлення. Деякі провайдери (або клієнти OAuth) можуть робити старі refresh-токени недійсними, коли для того самого користувача/застосунку видано новий.
|
||||
OAuth-провайдери часто створюють **новий refresh token** під час потоків входу/оновлення. Деякі провайдери (або OAuth-клієнти) можуть робити старіші refresh tokens недійсними, коли для того самого користувача/застосунку видано новий.
|
||||
|
||||
Практичний симптом:
|
||||
|
||||
- ви входите через OpenClaw _і_ через Claude Code / Codex CLI → один із них згодом випадково “виходить з акаунта”
|
||||
- ви входите через OpenClaw _і_ через Claude Code / Codex CLI → один із них згодом випадково “виходить з облікового запису”
|
||||
|
||||
Щоб зменшити це, OpenClaw розглядає `auth-profiles.json` як **приймач токенів**:
|
||||
|
||||
- середовище виконання читає облікові дані з **одного місця**
|
||||
- runtime читає облікові дані з **одного місця**
|
||||
- ми можемо зберігати кілька профілів і маршрутизувати їх детерміновано
|
||||
- повторне використання зовнішнього CLI залежить від провайдера: Codex CLI може ініціалізувати порожній
|
||||
профіль `openai-codex:default`, але щойно OpenClaw має локальний профіль OAuth,
|
||||
локальний refresh-токен є канонічним; інші інтеграції можуть залишатися
|
||||
керованими зовні та повторно читати своє сховище автентифікації CLI
|
||||
профіль `openai-codex:default`, але щойно OpenClaw має локальний OAuth-профіль,
|
||||
локальний refresh token стає канонічним; інші інтеграції можуть залишатися
|
||||
керованими зовні й повторно читати сховище автентифікації свого CLI
|
||||
- шляхи статусу й запуску, які вже знають налаштований набір провайдерів, обмежують
|
||||
виявлення зовнішнього CLI цим набором, тому непов’язане сховище входу CLI не
|
||||
пошук зовнішніх CLI цим набором, тому сховище входу непов’язаного CLI не
|
||||
перевіряється для конфігурації з одним провайдером
|
||||
|
||||
## Сховище (де зберігаються токени)
|
||||
## Зберігання (де живуть токени)
|
||||
|
||||
Секрети зберігаються **для кожного агента**:
|
||||
Секрети зберігаються у сховищах автентифікації агента:
|
||||
|
||||
- Профілі автентифікації (OAuth + API-ключі + необов’язкові посилання рівня значення): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- Файл сумісності зі старими версіями: `~/.openclaw/agents/<agentId>/agent/auth.json`
|
||||
(статичні записи `api_key` очищуються, коли їх виявлено)
|
||||
(статичні записи `api_key` очищаються після виявлення)
|
||||
|
||||
Застарілий файл лише для імпорту (досі підтримується, але не є основним сховищем):
|
||||
Старий файл лише для імпорту (досі підтримується, але не є основним сховищем):
|
||||
|
||||
- `~/.openclaw/credentials/oauth.json` (імпортується в `auth-profiles.json` під час першого використання)
|
||||
|
||||
Усе вищезазначене також враховує `$OPENCLAW_STATE_DIR` (перевизначення каталогу стану). Повний довідник: [/gateway/configuration](/uk/gateway/configuration-reference#auth-storage)
|
||||
Усе наведене вище також враховує `$OPENCLAW_STATE_DIR` (перевизначення каталогу стану). Повна довідка: [/gateway/configuration](/uk/gateway/configuration-reference#auth-storage)
|
||||
|
||||
Про статичні посилання на секрети та поведінку активації знімка середовища виконання див. [Керування секретами](/uk/gateway/secrets).
|
||||
Для статичних посилань на секрети та поведінки активації runtime-знімка див. [Керування секретами](/uk/gateway/secrets).
|
||||
|
||||
## Сумісність із застарілими токенами Anthropic
|
||||
Коли вторинний агент не має локального профілю автентифікації, OpenClaw використовує read-through
|
||||
успадкування зі сховища стандартного/головного агента. Він не клонує
|
||||
`auth-profiles.json` головного агента під час читання. OAuth refresh tokens є особливо
|
||||
чутливими: звичайні потоки копіювання пропускають їх за замовчуванням, бо деякі провайдери обертають
|
||||
або роблять refresh tokens недійсними після використання. Налаштуйте окремий OAuth-вхід для
|
||||
агента, коли йому потрібен незалежний обліковий запис.
|
||||
|
||||
## Сумісність зі старими токенами Anthropic
|
||||
|
||||
<Warning>
|
||||
Публічна документація Claude Code від Anthropic каже, що безпосереднє використання Claude Code залишається в межах
|
||||
Публічна документація Claude Code від Anthropic каже, що пряме використання Claude Code залишається в межах
|
||||
лімітів підписки Claude, а співробітники Anthropic повідомили нам, що використання Claude
|
||||
CLI у стилі OpenClaw знову дозволене. Тому OpenClaw розглядає повторне використання Claude CLI і
|
||||
використання `claude -p` як санкціоновані для цієї інтеграції, якщо Anthropic
|
||||
не опублікує нову політику.
|
||||
CLI у стилі OpenClaw знову дозволене. Тому OpenClaw розглядає повторне використання Claude CLI та
|
||||
використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не
|
||||
опублікує нову політику.
|
||||
|
||||
Актуальну документацію Anthropic щодо планів для прямого використання Claude Code див. у [Використання Claude Code
|
||||
Поточну документацію Anthropic щодо планів прямого використання Claude Code див. у [Використання Claude Code
|
||||
з вашим планом Pro або Max](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
|
||||
і [Використання Claude Code з вашим планом Team або Enterprise](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/).
|
||||
|
||||
Якщо вам потрібні інші варіанти у стилі підписки в OpenClaw, див. [OpenAI
|
||||
Codex](/uk/providers/openai), [Qwen Cloud Coding
|
||||
Plan](/uk/providers/qwen), [MiniMax Coding Plan](/uk/providers/minimax)
|
||||
Plan](/uk/providers/qwen), [MiniMax Coding Plan](/uk/providers/minimax),
|
||||
і [Z.AI / GLM Coding Plan](/uk/providers/glm).
|
||||
</Warning>
|
||||
|
||||
OpenClaw також надає setup-token Anthropic як підтримуваний шлях автентифікації токеном, але тепер віддає перевагу повторному використанню Claude CLI і `claude -p`, коли вони доступні.
|
||||
OpenClaw також надає setup-token Anthropic як підтримуваний шлях token-auth, але тепер віддає перевагу повторному використанню Claude CLI і `claude -p`, коли вони доступні.
|
||||
|
||||
## Міграція Anthropic Claude CLI
|
||||
|
||||
OpenClaw знову підтримує повторне використання Anthropic Claude CLI. Якщо на хості вже є локальний
|
||||
вхід Claude, onboarding/configure може повторно використати його напряму.
|
||||
вхід Claude, onboarding/configure може використати його напряму.
|
||||
|
||||
## Обмін OAuth (як працює вхід)
|
||||
|
||||
Інтерактивні потоки входу OpenClaw реалізовані в `@mariozechner/pi-ai` і підключені до майстрів/команд.
|
||||
Інтерактивні потоки входу OpenClaw реалізовані в `@mariozechner/pi-ai` і під’єднані до майстрів/команд.
|
||||
|
||||
### Setup-token Anthropic
|
||||
### setup-token Anthropic
|
||||
|
||||
Форма потоку:
|
||||
|
||||
1. запустіть setup-token Anthropic або paste-token з OpenClaw
|
||||
2. OpenClaw зберігає отримані облікові дані Anthropic у профілі автентифікації
|
||||
3. вибір моделі залишається на `anthropic/...`
|
||||
4. наявні профілі автентифікації Anthropic залишаються доступними для відкоту/керування порядком
|
||||
3. вибір моделі лишається на `anthropic/...`
|
||||
4. наявні профілі автентифікації Anthropic лишаються доступними для rollback/керування порядком
|
||||
|
||||
### OpenAI Codex (ChatGPT OAuth)
|
||||
|
||||
OpenAI Codex OAuth явно підтримується для використання поза Codex CLI, включно з робочими процесами OpenClaw.
|
||||
OpenAI Codex OAuth явно підтримується для використання поза Codex CLI, зокрема в робочих процесах OpenClaw.
|
||||
|
||||
Форма потоку (PKCE):
|
||||
|
||||
1. згенерувати verifier/challenge PKCE + випадковий `state`
|
||||
2. відкрити `https://auth.openai.com/oauth/authorize?...`
|
||||
3. спробувати перехопити callback на `http://127.0.0.1:1455/auth/callback`
|
||||
4. якщо callback не може прив’язатися (або ви працюєте віддалено/без графічного середовища), вставити URL/код перенаправлення
|
||||
5. виконати обмін на `https://auth.openai.com/oauth/token`
|
||||
6. витягти `accountId` з access-токена і зберегти `{ access, refresh, expires, accountId }`
|
||||
1. згенеруйте PKCE verifier/challenge + випадковий `state`
|
||||
2. відкрийте `https://auth.openai.com/oauth/authorize?...`
|
||||
3. спробуйте перехопити callback на `http://127.0.0.1:1455/auth/callback`
|
||||
4. якщо callback не може прив’язатися (або ви працюєте віддалено/без headless), вставте URL/code перенаправлення
|
||||
5. виконайте обмін на `https://auth.openai.com/oauth/token`
|
||||
6. витягніть `accountId` з access token і збережіть `{ access, refresh, expires, accountId }`
|
||||
|
||||
Шлях у майстрі: `openclaw onboard` → вибір автентифікації `openai-codex`.
|
||||
Шлях майстра: `openclaw onboard` → вибір автентифікації `openai-codex`.
|
||||
|
||||
## Оновлення + строк дії
|
||||
## Оновлення + завершення строку дії
|
||||
|
||||
Профілі зберігають мітку часу `expires`.
|
||||
Профілі зберігають timestamp `expires`.
|
||||
|
||||
Під час виконання:
|
||||
Під час runtime:
|
||||
|
||||
- якщо `expires` у майбутньому → використати збережений access-токен
|
||||
- якщо строк дії минув → оновити (під файловим блокуванням) і перезаписати збережені облікові дані
|
||||
- виняток: деякі облікові дані зовнішнього CLI залишаються керованими зовні; OpenClaw
|
||||
повторно читає ці сховища автентифікації CLI замість витрачання скопійованих refresh-токенів.
|
||||
Ініціалізація Codex CLI навмисно вужча: вона створює порожній профіль
|
||||
`openai-codex:default`, після чого оновлення, що належать OpenClaw, зберігають локальний
|
||||
- якщо `expires` у майбутньому → використовується збережений access token
|
||||
- якщо строк дії минув → виконується refresh (під файловим блокуванням) і збережені облікові дані перезаписуються
|
||||
- якщо вторинний агент читає успадкований OAuth-профіль головного агента, refresh
|
||||
записує назад у сховище головного агента замість копіювання refresh token у
|
||||
сховище вторинного агента
|
||||
- виняток: деякі облікові дані зовнішніх CLI залишаються керованими зовні; OpenClaw
|
||||
повторно читає ці сховища автентифікації CLI замість витрачання скопійованих refresh tokens.
|
||||
Ініціалізація Codex CLI навмисно вужча: вона засіває порожній
|
||||
профіль `openai-codex:default`, після чого оновлення, якими володіє OpenClaw, зберігають локальний
|
||||
профіль канонічним.
|
||||
|
||||
Потік оновлення автоматичний; зазвичай вам не потрібно керувати токенами вручну.
|
||||
Потік refresh автоматичний; зазвичай вам не потрібно керувати токенами вручну.
|
||||
|
||||
## Кілька облікових записів (профілі) + маршрутизація
|
||||
|
||||
@ -151,39 +161,39 @@ OpenAI Codex OAuth явно підтримується для використа
|
||||
|
||||
### 1) Рекомендовано: окремі агенти
|
||||
|
||||
Якщо ви хочете, щоб “особисте” і “робоче” ніколи не взаємодіяли, використовуйте ізольованих агентів (окремі сеанси + облікові дані + робоча область):
|
||||
Якщо ви хочете, щоб “особисте” і “робоче” ніколи не взаємодіяли, використовуйте ізольованих агентів (окремі сесії + облікові дані + workspace):
|
||||
|
||||
```bash
|
||||
openclaw agents add work
|
||||
openclaw agents add personal
|
||||
```
|
||||
|
||||
Потім налаштуйте автентифікацію для кожного агента (майстер) і маршрутизуйте чати до потрібного агента.
|
||||
Потім налаштуйте автентифікацію для кожного агента (майстер) і маршрутизуйте чати до правильного агента.
|
||||
|
||||
### 2) Розширено: кілька профілів в одному агенті
|
||||
|
||||
`auth-profiles.json` підтримує кілька ID профілів для того самого провайдера.
|
||||
|
||||
Виберіть, який профіль використовується:
|
||||
Вибір профілю, який використовується:
|
||||
|
||||
- глобально через порядок у конфігурації (`auth.order`)
|
||||
- для окремого сеансу через `/model ...@<profileId>`
|
||||
- для окремої сесії через `/model ...@<profileId>`
|
||||
|
||||
Приклад (перевизначення сеансу):
|
||||
Приклад (перевизначення сесії):
|
||||
|
||||
- `/model Opus@anthropic:work`
|
||||
|
||||
Як побачити, які ID профілів існують:
|
||||
Як переглянути наявні ID профілів:
|
||||
|
||||
- `openclaw channels list --json` (показує `auth[]`)
|
||||
|
||||
Пов’язані документи:
|
||||
Пов’язана документація:
|
||||
|
||||
- [Відмовостійке перемикання моделей](/uk/concepts/model-failover) (правила ротації + cooldown)
|
||||
- [Slash-команди](/uk/tools/slash-commands) (поверхня команд)
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Автентифікація](/uk/gateway/authentication) — огляд автентифікації провайдера моделей
|
||||
- [Секрети](/uk/gateway/secrets) — сховище облікових даних і SecretRef
|
||||
- [Автентифікація](/uk/gateway/authentication) — огляд автентифікації провайдерів моделей
|
||||
- [Секрети](/uk/gateway/secrets) — зберігання облікових даних і SecretRef
|
||||
- [Довідник конфігурації](/uk/gateway/configuration-reference#auth-storage) — ключі конфігурації автентифікації
|
||||
|
||||
@ -1,51 +1,51 @@
|
||||
---
|
||||
read_when:
|
||||
- Вибір або перемикання моделей, налаштування псевдонімів
|
||||
- Налагодження резервного перемикання моделей / «Усі моделі зазнали збою»
|
||||
- Налагодження резервного перемикання моделей / "Усі моделі завершилися помилкою"
|
||||
- Розуміння профілів автентифікації та керування ними
|
||||
sidebarTitle: Models FAQ
|
||||
summary: 'Поширені запитання: типові налаштування моделей, вибір, псевдоніми, перемикання, резервне перемикання та профілі автентифікації'
|
||||
summary: 'Поширені запитання: типові налаштування моделей, вибір, псевдоніми, перемикання, аварійне перемикання та профілі автентифікації'
|
||||
title: 'Поширені запитання: моделі та автентифікація'
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:15:41Z"
|
||||
generated_at: "2026-04-29T11:04:02Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f80163d645a31b07220c7a4c5bbfe79ed431facbd7232968c12095b7cd9ac4a9
|
||||
source_hash: eaa72bf66d3f1528f95762e2a2763bc2f6bfddbc1d4c24a9ec2df7f943ebc14b
|
||||
source_path: help/faq-models.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Запитання й відповіді щодо моделей і профілів автентифікації. Про налаштування, сеанси, Gateway, канали та
|
||||
Модельні та автентифікаційно-профільні запитання й відповіді. Щодо налаштування, сеансів, Gateway, каналів і
|
||||
усунення несправностей див. основний [FAQ](/uk/help/faq).
|
||||
|
||||
## Моделі: типові значення, вибір, псевдоніми, перемикання
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title='Що таке "типова модель"?'>
|
||||
Типова модель OpenClaw — це те, що ви задали як:
|
||||
Типова модель OpenClaw — це те, що ви встановили як:
|
||||
|
||||
```
|
||||
agents.defaults.model.primary
|
||||
```
|
||||
|
||||
Моделі вказуються як `provider/model` (приклад: `openai/gpt-5.5` або `openai-codex/gpt-5.5`). Якщо ви не вкажете провайдера, OpenClaw спершу спробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього як застарілий шлях сумісності повернеться до налаштованого типового провайдера. Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повернеться до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. Вам усе одно слід **явно** задавати `provider/model`.
|
||||
Моделі вказуються як `provider/model` (приклад: `openai/gpt-5.5` або `openai-codex/gpt-5.5`). Якщо ви не вкажете провайдера, OpenClaw спочатку спробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього повернеться до налаштованого типового провайдера як застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повернеться до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. Вам усе одно слід **явно** задавати `provider/model`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Яку модель ви рекомендуєте?">
|
||||
**Рекомендована типова модель:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів.
|
||||
**Для агентів з інструментами або ненадійним введенням:** віддавайте пріоритет потужності моделі, а не вартості.
|
||||
**Для звичайного/низькоризикового чату:** використовуйте дешевші резервні моделі та маршрутизуйте за роллю агента.
|
||||
**Рекомендоване типове значення:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів.
|
||||
**Для агентів із підтримкою інструментів або недовіреним введенням:** віддавайте перевагу потужності моделі, а не вартості.
|
||||
**Для звичайного/низькоризикового чату:** використовуйте дешевші резервні моделі й маршрутизуйте за роллю агента.
|
||||
|
||||
MiniMax має власну документацію: [MiniMax](/uk/providers/minimax) і
|
||||
[Локальні моделі](/uk/gateway/local-models).
|
||||
|
||||
Загальне правило: використовуйте **найкращу модель, яку можете собі дозволити** для важливої роботи, і дешевшу
|
||||
модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі для кожного агента та використовувати субагентів для
|
||||
паралельного виконання довгих завдань (кожен субагент споживає токени). Див. [Моделі](/uk/concepts/models) і
|
||||
Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити**, для роботи з високими ставками, і дешевшу
|
||||
модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі для кожного агента й використовувати субагентів, щоб
|
||||
паралелізувати довгі завдання (кожен субагент споживає токени). Див. [Моделі](/uk/concepts/models) і
|
||||
[Субагенти](/uk/tools/subagents).
|
||||
|
||||
Важливе попередження: слабші/надмірно квантизовані моделі більш вразливі до prompt
|
||||
Серйозне попередження: слабші/надмірно квантовані моделі вразливіші до prompt
|
||||
injection і небезпечної поведінки. Див. [Безпека](/uk/gateway/security).
|
||||
|
||||
Більше контексту: [Моделі](/uk/concepts/models).
|
||||
@ -60,10 +60,10 @@ x-i18n:
|
||||
- `/model` у чаті (швидко, для окремого сеансу)
|
||||
- `openclaw models set ...` (оновлює лише конфігурацію моделі)
|
||||
- `openclaw configure --section model` (інтерактивно)
|
||||
- редагувати `agents.defaults.model` у `~/.openclaw/openclaw.json`
|
||||
- редагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json`
|
||||
|
||||
Уникайте `config.apply` з частковим об'єктом, якщо не маєте наміру замінити всю конфігурацію.
|
||||
Для редагувань через RPC спершу перевірте через `config.schema.lookup` і надавайте перевагу `config.patch`. Корисне навантаження lookup дає нормалізований шлях, коротку документацію/обмеження схеми та підсумки безпосередніх дочірніх елементів
|
||||
Уникайте `config.apply` із частковим об'єктом, якщо не маєте наміру замінити всю конфігурацію.
|
||||
Для RPC-редагувань спочатку перевірте через `config.schema.lookup` і надавайте перевагу `config.patch`. Корисне навантаження lookup дає нормалізований шлях, поверхневу документацію/обмеження схеми й короткі описи безпосередніх дочірніх елементів.
|
||||
для часткових оновлень.
|
||||
Якщо ви перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення.
|
||||
|
||||
@ -71,37 +71,37 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можу я використовувати самостійно розміщені моделі (llama.cpp, vLLM, Ollama)?">
|
||||
<Accordion title="Чи можна використовувати самостійно розгорнуті моделі (llama.cpp, vLLM, Ollama)?">
|
||||
Так. Ollama — найпростіший шлях для локальних моделей.
|
||||
|
||||
Найшвидше налаштування:
|
||||
|
||||
1. Установіть Ollama з `https://ollama.com/download`
|
||||
2. Завантажте локальну модель, наприклад `ollama pull gemma4`
|
||||
3. Якщо вам також потрібні хмарні моделі, запустіть `ollama signin`
|
||||
3. Якщо також потрібні хмарні моделі, запустіть `ollama signin`
|
||||
4. Запустіть `openclaw onboard` і виберіть `Ollama`
|
||||
5. Виберіть `Local` або `Cloud + Local`
|
||||
|
||||
Примітки:
|
||||
|
||||
- `Cloud + Local` дає хмарні моделі плюс ваші локальні моделі Ollama
|
||||
- `Cloud + Local` дає вам хмарні моделі плюс ваші локальні моделі Ollama
|
||||
- хмарні моделі, як-от `kimi-k2.5:cloud`, не потребують локального завантаження
|
||||
- для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/<model>`
|
||||
|
||||
Примітка щодо безпеки: менші або сильно квантизовані моделі більш вразливі до prompt
|
||||
injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти.
|
||||
Якщо ви все ж хочете малі моделі, увімкніть ізоляцію та суворі списки дозволених інструментів.
|
||||
Примітка щодо безпеки: менші або сильно квантовані моделі вразливіші до prompt
|
||||
injection. Ми настійно рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти.
|
||||
Якщо ви все ж хочете малі моделі, увімкніть sandboxing і суворі списки дозволених інструментів.
|
||||
|
||||
Документація: [Ollama](/uk/providers/ollama), [Локальні моделі](/uk/gateway/local-models),
|
||||
[Провайдери моделей](/uk/concepts/model-providers), [Безпека](/uk/gateway/security),
|
||||
[Ізоляція](/uk/gateway/sandboxing).
|
||||
[Sandboxing](/uk/gateway/sandboxing).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Які моделі використовують OpenClaw, Flawd і Krill?">
|
||||
- Ці розгортання можуть відрізнятися й змінюватися з часом; фіксованої рекомендації щодо провайдера немає.
|
||||
- Перевірте поточне налаштування середовища виконання на кожному Gateway за допомогою `openclaw models status`.
|
||||
- Для агентів, чутливих до безпеки або з інструментами, використовуйте найсильнішу модель останнього покоління з доступних.
|
||||
- Ці розгортання можуть відрізнятися й змінюватися з часом; сталої рекомендації щодо провайдера немає.
|
||||
- Перевірте поточне runtime-налаштування на кожному gateway за допомогою `openclaw models status`.
|
||||
- Для чутливих до безпеки агентів або агентів із підтримкою інструментів використовуйте найсильнішу модель останнього покоління, доступну вам.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -118,9 +118,9 @@ x-i18n:
|
||||
/model gemini-flash-lite
|
||||
```
|
||||
|
||||
Це вбудовані псевдоніми. Власні псевдоніми можна додати через `agents.defaults.models`.
|
||||
Це вбудовані псевдоніми. Користувацькі псевдоніми можна додати через `agents.defaults.models`.
|
||||
|
||||
Доступні моделі можна переглянути за допомогою `/model`, `/model list` або `/model status`.
|
||||
Ви можете переглянути доступні моделі за допомогою `/model`, `/model list` або `/model status`.
|
||||
|
||||
`/model` (і `/model list`) показує компактний нумерований вибір. Виберіть за номером:
|
||||
|
||||
@ -128,17 +128,17 @@ x-i18n:
|
||||
/model 3
|
||||
```
|
||||
|
||||
Також можна примусово задати певний профіль автентифікації для провайдера (для сеансу):
|
||||
Ви також можете примусово задати конкретний профіль автентифікації для провайдера (для окремого сеансу):
|
||||
|
||||
```
|
||||
/model opus@anthropic:default
|
||||
/model opus@anthropic:work
|
||||
```
|
||||
|
||||
Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується та який профіль автентифікації буде спробувано наступним.
|
||||
Він також показує налаштовану кінцеву точку провайдера (`baseUrl`) і режим API (`api`), якщо вони доступні.
|
||||
Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробовано далі.
|
||||
Він також показує налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли вони доступні.
|
||||
|
||||
**Як скасувати закріплення профілю, заданого через @profile?**
|
||||
**Як відкріпити профіль, який я встановив через @profile?**
|
||||
|
||||
Повторно запустіть `/model` **без** суфікса `@profile`:
|
||||
|
||||
@ -151,12 +151,12 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можу я використовувати GPT 5.5 для щоденних завдань і Codex 5.5 для програмування?">
|
||||
Так. Задайте одну модель типовою та перемикайтеся за потреби:
|
||||
<Accordion title="Чи можна використовувати GPT 5.5 для щоденних завдань і Codex 5.5 для кодування?">
|
||||
Так. Встановіть одну модель типовою й перемикайтеся за потреби:
|
||||
|
||||
- **Швидке перемикання (для сеансу):** `/model openai/gpt-5.5` для поточних завдань із прямим API-ключем OpenAI або `/model openai-codex/gpt-5.5` для завдань GPT-5.5 Codex OAuth.
|
||||
- **Типове значення:** задайте `agents.defaults.model.primary` як `openai/gpt-5.5` для використання API-ключа або `openai-codex/gpt-5.5` для використання GPT-5.5 Codex OAuth.
|
||||
- **Субагенти:** маршрутизуйте завдання з програмування до субагентів з іншою типовою моделлю.
|
||||
- **Швидке перемикання (для окремого сеансу):** `/model openai/gpt-5.5` для поточних завдань із прямим ключем OpenAI API або `/model openai-codex/gpt-5.5` для завдань GPT-5.5 Codex OAuth.
|
||||
- **Типове значення:** встановіть `agents.defaults.model.primary` на `openai/gpt-5.5` для використання API-ключа або `openai-codex/gpt-5.5` для використання GPT-5.5 Codex OAuth.
|
||||
- **Субагенти:** маршрутизуйте завдання кодування до субагентів з іншою типовою моделлю.
|
||||
|
||||
Див. [Моделі](/uk/concepts/models) і [Slash-команди](/uk/tools/slash-commands).
|
||||
|
||||
@ -165,8 +165,8 @@ x-i18n:
|
||||
<Accordion title="Як налаштувати швидкий режим для GPT 5.5?">
|
||||
Використовуйте перемикач сеансу або типове значення конфігурації:
|
||||
|
||||
- **Для сеансу:** надішліть `/fast on`, коли сеанс використовує `openai/gpt-5.5` або `openai-codex/gpt-5.5`.
|
||||
- **Типове значення для моделі:** задайте `agents.defaults.models["openai/gpt-5.5"].params.fastMode` або `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` як `true`.
|
||||
- **Для окремого сеансу:** надішліть `/fast on`, поки сеанс використовує `openai/gpt-5.5` або `openai-codex/gpt-5.5`.
|
||||
- **Типове значення для моделі:** встановіть `agents.defaults.models["openai/gpt-5.5"].params.fastMode` або `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` у `true`.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -186,14 +186,14 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Для OpenAI швидкий режим відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Перевизначення сеансу `/fast` мають перевагу над типовими значеннями конфігурації.
|
||||
Для OpenAI швидкий режим відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Перевизначення сеансу `/fast` мають пріоритет над типовими значеннями конфігурації.
|
||||
|
||||
Див. [Мислення і швидкий режим](/uk/tools/thinking) та [Швидкий режим OpenAI](/uk/providers/openai#fast-mode).
|
||||
Див. [Мислення і швидкий режим](/uk/tools/thinking) і [Швидкий режим OpenAI](/uk/providers/openai#fast-mode).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Чому я бачу "Model ... is not allowed", а потім немає відповіді?'>
|
||||
Якщо задано `agents.defaults.models`, це стає **списком дозволених** для `/model` і будь-яких
|
||||
Якщо `agents.defaults.models` встановлено, це стає **списком дозволених** для `/model` і будь-яких
|
||||
перевизначень сеансу. Вибір моделі, якої немає в цьому списку, повертає:
|
||||
|
||||
```
|
||||
@ -201,23 +201,24 @@ x-i18n:
|
||||
```
|
||||
|
||||
Ця помилка повертається **замість** звичайної відповіді. Виправлення: додайте модель до
|
||||
`agents.defaults.models`, видаліть список дозволених або виберіть модель з `/model list`.
|
||||
`agents.defaults.models`, видаліть список дозволених або виберіть модель із `/model list`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Чому я бачу "Unknown model: minimax/MiniMax-M2.7"?'>
|
||||
Це означає, що **провайдера не налаштовано** (не знайдено конфігурацію провайдера MiniMax або профіль автентифікації), тому модель не можна розпізнати.
|
||||
Це означає, що **провайдера не налаштовано** (не знайдено конфігурації провайдера MiniMax або профілю
|
||||
автентифікації), тому модель неможливо розв'язати.
|
||||
|
||||
Контрольний список виправлення:
|
||||
|
||||
1. Оновіть OpenClaw до поточного випуску (або запустіть із вихідного коду `main`), потім перезапустіть Gateway.
|
||||
1. Оновіться до поточного випуску OpenClaw (або запустіть із вихідного коду `main`), потім перезапустіть gateway.
|
||||
2. Переконайтеся, що MiniMax налаштовано (майстер або JSON), або що автентифікація MiniMax
|
||||
існує в env/профілях автентифікації, щоб відповідний провайдер міг бути впроваджений
|
||||
існує в env/профілях автентифікації, щоб відповідний провайдер можна було ін'єктувати
|
||||
(`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений MiniMax
|
||||
OAuth для `minimax-portal`).
|
||||
3. Використовуйте точний ідентифікатор моделі (з урахуванням регістру) для вашого шляху автентифікації:
|
||||
`minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування
|
||||
з API-ключем, або `minimax-portal/MiniMax-M2.7` /
|
||||
`minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування з API-ключем,
|
||||
або `minimax-portal/MiniMax-M2.7` /
|
||||
`minimax-portal/MiniMax-M2.7-highspeed` для налаштування OAuth.
|
||||
4. Запустіть:
|
||||
|
||||
@ -231,11 +232,11 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можу я використовувати MiniMax як типову модель, а OpenAI — для складних завдань?">
|
||||
Так. Використовуйте **MiniMax як типову модель** і перемикайте моделі **для сеансу**, коли потрібно.
|
||||
<Accordion title="Чи можна використовувати MiniMax як типову модель, а OpenAI — для складних завдань?">
|
||||
Так. Використовуйте **MiniMax як типову модель** і перемикайте моделі **для окремого сеансу**, коли потрібно.
|
||||
Резервні варіанти призначені для **помилок**, а не для "складних завдань", тому використовуйте `/model` або окремого агента.
|
||||
|
||||
**Варіант A: перемикання для сеансу**
|
||||
**Варіант A: перемикання для окремого сеансу**
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,7 +270,7 @@ x-i18n:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи є opus / sonnet / gpt вбудованими скороченнями?">
|
||||
Так. OpenClaw постачається з кількома типовими скороченнями (застосовуються лише коли модель існує в `agents.defaults.models`):
|
||||
Так. OpenClaw постачається з кількома типовими скороченнями (застосовуються лише тоді, коли модель існує в `agents.defaults.models`):
|
||||
|
||||
- `opus` → `anthropic/claude-opus-4-6`
|
||||
- `sonnet` → `anthropic/claude-sonnet-4-6`
|
||||
@ -280,11 +281,11 @@ x-i18n:
|
||||
- `gemini-flash` → `google/gemini-3-flash-preview`
|
||||
- `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
|
||||
|
||||
Якщо ви задасте власний псевдонім із такою самою назвою, ваше значення матиме перевагу.
|
||||
Якщо ви задасте власний псевдонім із такою самою назвою, ваше значення матиме пріоритет.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як визначати/перевизначати скорочення моделей (псевдоніми)?">
|
||||
<Accordion title="Як визначити/перевизначити скорочення моделей (псевдоніми)?">
|
||||
Псевдоніми беруться з `agents.defaults.models.<modelId>.alias`. Приклад:
|
||||
|
||||
```json5
|
||||
@ -302,11 +303,11 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Потім `/model sonnet` (або `/<alias>`, коли підтримується) розпізнається як цей ідентифікатор моделі.
|
||||
Тоді `/model sonnet` (або `/<alias>`, коли підтримується) розв'язується в цей ідентифікатор моделі.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як додати моделі від інших провайдерів, як-от OpenRouter або Z.AI?">
|
||||
<Accordion title="Як додати моделі від інших провайдерів, наприклад OpenRouter або Z.AI?">
|
||||
OpenRouter (оплата за токени; багато моделей):
|
||||
|
||||
```json5
|
||||
@ -335,11 +336,11 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Якщо ви посилаєтеся на провайдера/модель, але потрібний ключ провайдера відсутній, ви отримаєте помилку авторизації під час виконання (наприклад, `No API key found for provider "zai"`).
|
||||
Якщо ви посилаєтеся на постачальника/модель, але потрібний ключ постачальника відсутній, ви отримаєте помилку автентифікації під час виконання (наприклад, `No API key found for provider "zai"`).
|
||||
|
||||
**Не знайдено API-ключ провайдера після додавання нового агента**
|
||||
**Ключ API для постачальника не знайдено після додавання нового агента**
|
||||
|
||||
Зазвичай це означає, що **новий агент** має порожнє сховище авторизації. Авторизація є окремою для кожного агента й
|
||||
Зазвичай це означає, що **новий агент** має порожнє сховище автентифікації. Автентифікація прив’язана до агента й
|
||||
зберігається в:
|
||||
|
||||
```
|
||||
@ -348,120 +349,121 @@ x-i18n:
|
||||
|
||||
Варіанти виправлення:
|
||||
|
||||
- Запустіть `openclaw agents add <id>` і налаштуйте авторизацію під час роботи майстра.
|
||||
- Або скопіюйте `auth-profiles.json` з `agentDir` основного агента в `agentDir` нового агента.
|
||||
- Запустіть `openclaw agents add <id>` і налаштуйте автентифікацію під час роботи майстра.
|
||||
- Або скопіюйте лише переносні статичні профілі `api_key` / `token` зі сховища автентифікації основного агента до сховища автентифікації нового агента.
|
||||
- Для профілів OAuth увійдіть із нового агента, коли йому потрібен власний обліковий запис; інакше OpenClaw може читати через стандартного/основного агента без клонування токенів оновлення.
|
||||
|
||||
**Не** використовуйте той самий `agentDir` для кількох агентів; це спричиняє конфлікти авторизації/сесій.
|
||||
**Не** використовуйте повторно `agentDir` для різних агентів; це спричиняє конфлікти автентифікації/сеансів.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Перемикання моделей у разі збою та "All models failed"
|
||||
## Резервне перемикання моделей і "All models failed"
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Як працює перемикання у разі збою?">
|
||||
Перемикання у разі збою відбувається у два етапи:
|
||||
<Accordion title="Як працює резервне перемикання?">
|
||||
Резервне перемикання відбувається у два етапи:
|
||||
|
||||
1. **Ротація профілів авторизації** в межах того самого провайдера.
|
||||
2. **Резервний вибір моделі** до наступної моделі в `agents.defaults.model.fallbacks`.
|
||||
1. **Ротація профілів автентифікації** у межах того самого постачальника.
|
||||
2. **Резервний перехід моделі** до наступної моделі в `agents.defaults.model.fallbacks`.
|
||||
|
||||
До профілів зі збоями застосовуються періоди охолодження (експоненційне відкладення), тож OpenClaw може продовжувати відповідати, навіть коли провайдер обмежує частоту запитів або тимчасово не працює.
|
||||
Періоди охолодження застосовуються до профілів, що зазнають помилок (експоненційне відтермінування), тому OpenClaw може продовжувати відповідати, навіть коли постачальник обмежує частоту запитів або тимчасово не працює.
|
||||
|
||||
Бакет обмеження частоти містить більше, ніж прості відповіді `429`. OpenClaw
|
||||
Сегмент обмеження частоти містить більше, ніж звичайні відповіді `429`. OpenClaw
|
||||
також розглядає повідомлення на кшталт `Too many concurrent requests`,
|
||||
`ThrottlingException`, `concurrency limit reached`,
|
||||
`workers_ai ... quota limit exceeded`, `resource exhausted` і періодичні
|
||||
обмеження вікна використання (`weekly/monthly limit reached`) як обмеження
|
||||
частоти, що мають спричиняти перемикання у разі збою.
|
||||
обмеження вікна використання (`weekly/monthly limit reached`) як обмеження частоти,
|
||||
достатні для резервного перемикання.
|
||||
|
||||
Деякі відповіді, схожі на проблеми з оплатою, не є `402`, а деякі HTTP-відповіді `402`
|
||||
також залишаються в цьому тимчасовому бакеті. Якщо провайдер повертає
|
||||
явний текст про оплату на `401` або `403`, OpenClaw усе одно може залишити це в
|
||||
напрямі оплати, але специфічні для провайдера зіставники тексту залишаються обмеженими
|
||||
провайдером, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402`
|
||||
натомість схоже на повторюване обмеження вікна використання або
|
||||
Деякі відповіді, схожі на білінгові, не є `402`, а деякі HTTP-відповіді `402`
|
||||
також залишаються в цьому тимчасовому сегменті. Якщо постачальник повертає
|
||||
явний білінговий текст для `401` або `403`, OpenClaw усе ще може залишити це
|
||||
в білінговій гілці, але специфічні для постачальника зіставлення тексту залишаються обмеженими
|
||||
постачальником, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402`
|
||||
натомість виглядає як придатне до повтору вікно використання або
|
||||
ліміт витрат організації/робочого простору (`daily limit reached, resets tomorrow`,
|
||||
`organization spending limit exceeded`), OpenClaw розглядає його як
|
||||
`rate_limit`, а не як тривале вимкнення через оплату.
|
||||
`rate_limit`, а не як тривале вимкнення через білінг.
|
||||
|
||||
Помилки переповнення контексту відрізняються: сигнатури на кшталт
|
||||
`request_too_large`, `input exceeds the maximum number of tokens`,
|
||||
`input token count exceeds the maximum number of input tokens`,
|
||||
`input is too long for the model` або `ollama error: context length
|
||||
exceeded` залишаються на шляху Compaction/повторної спроби замість переходу до
|
||||
резервної моделі.
|
||||
exceeded` залишаються на шляху Compaction/повторної спроби, а не просувають
|
||||
резервний перехід моделі.
|
||||
|
||||
Узагальнений текст серверної помилки навмисно вужчий, ніж "усе, що містить
|
||||
unknown/error". OpenClaw справді розглядає тимчасові форми, прив’язані до провайдера,
|
||||
як-от Anthropic із самим лише `An unknown error occurred`, OpenRouter із самим лише
|
||||
`Provider returned error`, помилки причин зупинки на кшталт `Unhandled stop reason:
|
||||
error`, JSON-навантаження `api_error` із тимчасовим серверним текстом
|
||||
Загальний текст помилки сервера навмисно вужчий, ніж "будь-що з
|
||||
unknown/error у ньому". OpenClaw справді розглядає тимчасові форми, обмежені постачальником,
|
||||
як-от Anthropic bare `An unknown error occurred`, OpenRouter bare
|
||||
`Provider returned error`, помилки причини зупинки на кшталт `Unhandled stop reason:
|
||||
error`, корисні навантаження JSON `api_error` із тимчасовим серверним текстом
|
||||
(`internal server error`, `unknown error, 520`, `upstream error`, `backend
|
||||
error`) і помилки зайнятості провайдера, як-от `ModelNotReadyException`, як
|
||||
сигнали тайм-ауту/перевантаження, що мають спричиняти перемикання у разі збою, коли контекст провайдера
|
||||
error`) і помилки зайнятості постачальника, як-от `ModelNotReadyException`, як
|
||||
сигнали таймауту/перевантаження, достатні для резервного перемикання, коли контекст постачальника
|
||||
збігається.
|
||||
Узагальнений внутрішній текст резервного збою, як-от `LLM request failed with an unknown
|
||||
error.`, залишається консервативним і сам по собі не запускає резервний вибір моделі.
|
||||
Загальний внутрішній текст резервної помилки на кшталт `LLM request failed with an unknown
|
||||
error.` залишається консервативним і сам по собі не запускає резервний перехід моделі.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Що означає "No credentials found for profile anthropic:default"?'>
|
||||
Це означає, що система спробувала використати ID профілю авторизації `anthropic:default`, але не змогла знайти облікові дані для нього в очікуваному сховищі авторизації.
|
||||
Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації.
|
||||
|
||||
**Контрольний список виправлення:**
|
||||
|
||||
- **Підтвердьте, де зберігаються профілі авторизації** (нові та застарілі шляхи)
|
||||
- **Підтвердьте, де зберігаються профілі автентифікації** (нові та застарілі шляхи)
|
||||
- Поточний: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- Застарілий: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`)
|
||||
- **Підтвердьте, що вашу змінну середовища завантажено Gateway**
|
||||
- Якщо ви встановили `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або увімкніть `env.shellEnv`.
|
||||
- **Підтвердьте, що ваша змінна середовища завантажується Gateway**
|
||||
- Якщо ви задали `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або ввімкніть `env.shellEnv`.
|
||||
- **Переконайтеся, що редагуєте правильного агента**
|
||||
- У конфігураціях із кількома агентами може бути кілька файлів `auth-profiles.json`.
|
||||
- **Перевірте стан моделі/авторизації**
|
||||
- Використайте `openclaw models status`, щоб побачити налаштовані моделі та чи автентифіковані провайдери.
|
||||
- **Перевірте стан моделі/автентифікації**
|
||||
- Використайте `openclaw models status`, щоб побачити налаштовані моделі та чи автентифіковані постачальники.
|
||||
|
||||
**Контрольний список виправлення для "No credentials found for profile anthropic"**
|
||||
|
||||
Це означає, що запуск прив’язано до профілю авторизації Anthropic, але Gateway
|
||||
не може знайти його у своєму сховищі авторизації.
|
||||
Це означає, що запуск прив’язано до профілю автентифікації Anthropic, але Gateway
|
||||
не може знайти його у своєму сховищі автентифікації.
|
||||
|
||||
- **Використайте Claude CLI**
|
||||
- Запустіть `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway.
|
||||
- **Якщо натомість хочете використовувати API-ключ**
|
||||
- Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**.
|
||||
- Очистьте будь-який закріплений порядок, який примусово використовує відсутній профіль:
|
||||
- Запустіть `openclaw models auth login --provider anthropic --method cli --set-default` на хості Gateway.
|
||||
- **Якщо натомість хочете використати ключ API**
|
||||
- Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості Gateway**.
|
||||
- Очистьте будь-який закріплений порядок, який примусово вимагає відсутній профіль:
|
||||
|
||||
```bash
|
||||
openclaw models auth order clear --provider anthropic
|
||||
```
|
||||
|
||||
- **Підтвердьте, що виконуєте команди на хості gateway**
|
||||
- У віддаленому режимі профілі авторизації зберігаються на машині gateway, а не на вашому ноутбуці.
|
||||
- **Підтвердьте, що виконуєте команди на хості Gateway**
|
||||
- У віддаленому режимі профілі автентифікації зберігаються на машині Gateway, а не на вашому ноутбуці.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чому він також спробував Google Gemini і зазнав збою?">
|
||||
Якщо ваша конфігурація моделі містить Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного вибору моделі. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`.
|
||||
<Accordion title="Чому він також спробував Google Gemini і зазнав помилки?">
|
||||
Якщо ваша конфігурація моделі містить Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного переходу моделі. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`.
|
||||
|
||||
Виправлення: або надайте авторизацію Google, або видаліть/уникайте моделей Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервний маршрут не спрямовував туди.
|
||||
Виправлення: або надайте автентифікацію Google, або вилучіть/уникайте моделей Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервний перехід не маршрутизував туди.
|
||||
|
||||
**Запит LLM відхилено: потрібна thinking signature (Google Antigravity)**
|
||||
**Запит LLM відхилено: потрібна сигнатура thinking (Google Antigravity)**
|
||||
|
||||
Причина: історія сесії містить **блоки thinking без signatures** (часто з
|
||||
перерваного/часткового потоку). Google Antigravity вимагає signatures для блоків thinking.
|
||||
Причина: історія сеансу містить **блоки thinking без сигнатур** (часто з
|
||||
перерваного/часткового потоку). Google Antigravity вимагає сигнатури для блоків thinking.
|
||||
|
||||
Виправлення: OpenClaw тепер видаляє непідписані блоки thinking для Google Antigravity Claude. Якщо це все ще з’являється, почніть **нову сесію** або встановіть `/thinking off` для цього агента.
|
||||
Виправлення: OpenClaw тепер вилучає непідписані блоки thinking для Google Antigravity Claude. Якщо це все ще з’являється, почніть **новий сеанс** або встановіть `/thinking off` для цього агента.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Профілі авторизації: що це таке і як ними керувати
|
||||
## Профілі автентифікації: що це таке і як ними керувати
|
||||
|
||||
Пов’язано: [/concepts/oauth](/uk/concepts/oauth) (потоки OAuth, зберігання токенів, шаблони для кількох облікових записів)
|
||||
Пов’язано: [/concepts/oauth](/uk/concepts/oauth) (потоки OAuth, зберігання токенів, шаблони кількох облікових записів)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Що таке профіль авторизації?">
|
||||
Профіль авторизації — це іменований запис облікових даних (OAuth або API-ключ), прив’язаний до провайдера. Профілі зберігаються в:
|
||||
<Accordion title="Що таке профіль автентифікації?">
|
||||
Профіль автентифікації — це іменований запис облікових даних (OAuth або ключ API), прив’язаний до постачальника. Профілі зберігаються в:
|
||||
|
||||
```
|
||||
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
|
||||
@ -469,25 +471,25 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Якими є типові ID профілів?">
|
||||
OpenClaw використовує ID з префіксом провайдера, наприклад:
|
||||
<Accordion title="Які типові ID профілів?">
|
||||
OpenClaw використовує ID із префіксом постачальника, як-от:
|
||||
|
||||
- `anthropic:default` (поширено, коли немає email-ідентичності)
|
||||
- `anthropic:default` (поширено, коли немає ідентичності електронної пошти)
|
||||
- `anthropic:<email>` для ідентичностей OAuth
|
||||
- власні ID, які ви обираєте (наприклад, `anthropic:work`)
|
||||
- власні ID, які ви вибираєте (наприклад, `anthropic:work`)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можу я керувати тим, який профіль авторизації пробується першим?">
|
||||
Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного провайдера (`auth.order.<provider>`). Це **не** зберігає секрети; це зіставляє ID із провайдером/режимом і задає порядок ротації.
|
||||
<Accordion title="Чи можу я керувати тим, який профіль автентифікації пробується першим?">
|
||||
Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного постачальника (`auth.order.<provider>`). Це **не** зберігає секрети; це зіставляє ID з постачальником/режимом і задає порядок ротації.
|
||||
|
||||
OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **періоді охолодження** (обмеження частоти/тайм-аути/збої авторизації) або в довшому стані **вимкнено** (оплата/недостатньо кредитів). Щоб перевірити це, запустіть `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`.
|
||||
OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **періоді охолодження** (обмеження частоти/таймаути/помилки автентифікації) або в тривалішому **вимкненому** стані (білінг/недостатньо кредитів). Щоб це перевірити, запустіть `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`.
|
||||
|
||||
Періоди охолодження через обмеження частоти можуть бути прив’язані до моделі. Профіль, який охолоджується
|
||||
для однієї моделі, усе ще може бути придатним для спорідненої моделі в того самого провайдера,
|
||||
тоді як вікна оплати/вимкнення все одно блокують увесь профіль.
|
||||
Періоди охолодження через обмеження частоти можуть бути обмежені моделлю. Профіль, який охолоджується
|
||||
для однієї моделі, усе ще може бути придатним для спорідненої моделі в того самого постачальника,
|
||||
тоді як білінгові/вимкнені вікна все одно блокують увесь профіль.
|
||||
|
||||
Також можна задати перевизначення порядку **для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI:
|
||||
Ви також можете задати перевизначення порядку **для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI:
|
||||
|
||||
```bash
|
||||
# Defaults to the configured default agent (omit --agent)
|
||||
@ -503,30 +505,30 @@ x-i18n:
|
||||
openclaw models auth order clear --provider anthropic
|
||||
```
|
||||
|
||||
Щоб вибрати конкретного агента:
|
||||
Щоб націлитися на конкретного агента:
|
||||
|
||||
```bash
|
||||
openclaw models auth order set --provider anthropic --agent main anthropic:default
|
||||
```
|
||||
|
||||
Щоб перевірити, що фактично буде спробовано, використайте:
|
||||
Щоб перевірити, що фактично пробуватиметься, використайте:
|
||||
|
||||
```bash
|
||||
openclaw models status --probe
|
||||
```
|
||||
|
||||
Якщо збережений профіль пропущено в явному порядку, probe повідомляє
|
||||
`excluded_by_auth_order` для цього профілю замість того, щоб тихо пробувати його.
|
||||
`excluded_by_auth_order` для цього профілю замість того, щоб мовчки пробувати його.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="OAuth проти API-ключа - у чому різниця?">
|
||||
<Accordion title="OAuth чи ключ API — у чому різниця?">
|
||||
OpenClaw підтримує обидва варіанти:
|
||||
|
||||
- **OAuth** часто використовує доступ за підпискою (де це застосовно).
|
||||
- **API-ключі** використовують оплату за токени.
|
||||
- **Ключі API** використовують оплату за токени.
|
||||
|
||||
Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API-ключі.
|
||||
Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і ключі API.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -534,6 +536,6 @@ x-i18n:
|
||||
## Пов’язано
|
||||
|
||||
- [FAQ](/uk/help/faq) — основний FAQ
|
||||
- [FAQ — швидкий старт і налаштування першого запуску](/uk/help/faq-first-run)
|
||||
- [FAQ — швидкий старт і початкове налаштування](/uk/help/faq-first-run)
|
||||
- [Вибір моделі](/uk/concepts/model-providers)
|
||||
- [Перемикання моделей у разі збою](/uk/concepts/model-failover)
|
||||
- [Резервне перемикання моделей](/uk/concepts/model-failover)
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен багаторівневий захист від SSRF і атак повторного прив’язування DNS
|
||||
- Налаштування зовнішнього прямого проксі-сервера для трафіку середовища виконання OpenClaw
|
||||
summary: Як спрямовувати HTTP- і WebSocket-трафік середовища виконання OpenClaw через фільтрувальний проксі, керований оператором
|
||||
- Вам потрібен багаторівневий захист від SSRF та атак повторного прив’язування DNS
|
||||
- Налаштування зовнішнього прямого проксі для трафіку середовища виконання OpenClaw
|
||||
summary: Як маршрутизувати HTTP- і WebSocket-трафік середовища виконання OpenClaw через фільтрувальний проксі, керований оператором
|
||||
title: Мережевий проксі
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:25:46Z"
|
||||
generated_at: "2026-04-29T11:03:53Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 571e08a36c53dc7a6527d73860ecd885d0a43622aaac2de08cae30d6981563cc
|
||||
source_hash: b653991b31793a7ac0a8c45ff9bb2fa24288acc8835aefe0031eb218453380ec
|
||||
source_path: security/network-proxy.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Мережевий проксі
|
||||
|
||||
OpenClaw може спрямовувати HTTP- і WebSocket-трафік середовища виконання через керований оператором прямий проксі. Це необов’язковий додатковий рівень захисту для розгортань, яким потрібні централізований контроль вихідного трафіку, сильніший захист від SSRF і краща аудитованість мережі.
|
||||
OpenClaw може спрямовувати runtime-трафік HTTP і WebSocket через прямий проксі, керований оператором. Це додатковий необов’язковий захист для розгортань, яким потрібні централізований контроль вихідного трафіку, сильніший захист від SSRF і краща аудитованість мережі.
|
||||
|
||||
OpenClaw не постачає, не завантажує, не запускає, не налаштовує й не сертифікує проксі. Ви запускаєте технологію проксі, яка підходить для вашого середовища, а OpenClaw спрямовує через нього звичайні локальні для процесу HTTP- і WebSocket-клієнти.
|
||||
OpenClaw не постачає, не завантажує, не запускає, не налаштовує й не сертифікує проксі. Ви запускаєте проксі-технологію, яка підходить вашому середовищу, а OpenClaw спрямовує через неї звичайні локальні для процесу клієнти HTTP і WebSocket.
|
||||
|
||||
## Навіщо використовувати проксі?
|
||||
|
||||
Проксі дає операторам одну точку мережевого контролю для вихідного HTTP- і WebSocket-трафіку. Це може бути корисно навіть поза посиленням захисту від SSRF:
|
||||
Проксі дає операторам одну точку мережевого контролю для вихідного трафіку HTTP і WebSocket. Це може бути корисно навіть поза посиленням захисту від SSRF:
|
||||
|
||||
- Центральна політика: підтримуйте одну політику вихідного трафіку замість того, щоб покладатися на правильність мережевих правил у кожному місці HTTP-виклику застосунку.
|
||||
- Перевірки під час підключення: оцінюйте призначення після DNS-розв’язання й безпосередньо перед тим, як проксі відкриє висхідне з’єднання.
|
||||
- Захист від DNS rebinding: зменшіть розрив між DNS-перевіркою на рівні застосунку та фактичним вихідним з’єднанням.
|
||||
- Ширше покриття JavaScript: спрямовуйте звичайні `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch і подібні клієнти тим самим шляхом.
|
||||
- Централізована політика: підтримуйте одну політику вихідного трафіку замість того, щоб покладатися на те, що кожне місце виклику HTTP в застосунку правильно застосує мережеві правила.
|
||||
- Перевірки під час з’єднання: оцінюйте призначення після DNS-резолюції та безпосередньо перед тим, як проксі відкриє upstream-з’єднання.
|
||||
- Захист від DNS rebinding: зменшуйте проміжок між DNS-перевіркою на рівні застосунку та фактичним вихідним з’єднанням.
|
||||
- Ширше покриття JavaScript: спрямовуйте звичайні `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch і подібні клієнти через той самий шлях.
|
||||
- Аудитованість: журналюйте дозволені й заборонені призначення на межі вихідного трафіку.
|
||||
- Операційний контроль: застосовуйте правила призначень, сегментацію мережі, обмеження швидкості або дозволені списки вихідного трафіку без перебудови OpenClaw.
|
||||
- Операційний контроль: застосовуйте правила призначень, сегментацію мережі, обмеження швидкості або allowlist для вихідного трафіку без повторної збірки OpenClaw.
|
||||
|
||||
OpenClaw і далі зберігає захисні механізми SSRF на рівні застосунку, як-от `fetchWithSsrFGuard`. Маршрутизація через проксі є додатковим захисним обмежувачем на рівні процесу для звичайного вихідного HTTP- і WebSocket-трафіку, а не заміною захищених fetch-запитів чи мережевої пісочниці на рівні ОС.
|
||||
OpenClaw і далі зберігає захист від SSRF на рівні застосунку, зокрема `fetchWithSsrFGuard`. Маршрутизація через проксі є додатковим захисним обмеженням на рівні процесу для звичайного вихідного трафіку HTTP і WebSocket, а не заміною захищених fetch-викликів або мережевої пісочниці на рівні ОС.
|
||||
|
||||
## Як OpenClaw маршрутизує трафік
|
||||
## Як OpenClaw спрямовує трафік
|
||||
|
||||
Коли `proxy.enabled=true` і налаштовано URL проксі, захищені процеси середовища виконання, як-от `openclaw gateway run`, `openclaw node run` і `openclaw agent --local`, спрямовують звичайний вихідний HTTP- і WebSocket-трафік через налаштований проксі:
|
||||
Коли `proxy.enabled=true` і налаштовано URL проксі, захищені runtime-процеси, як-от `openclaw gateway run`, `openclaw node run` і `openclaw agent --local`, спрямовують звичайний вихідний трафік HTTP і WebSocket через налаштований проксі:
|
||||
|
||||
```text
|
||||
OpenClaw process
|
||||
@ -43,13 +43,13 @@ OpenClaw process
|
||||
WebSocket clients -> operator-managed filtering proxy -> public internet
|
||||
```
|
||||
|
||||
Публічний контракт — це поведінка маршрутизації, а не внутрішні хуки Node, використані для її реалізації. WebSocket-клієнти площини керування OpenClaw Gateway використовують вузький прямий шлях для RPC-трафіку локального Gateway через local loopback, коли URL Gateway використовує буквальну IP-адресу loopback, як-от `127.0.0.1` або `[::1]`. Цей шлях площини керування має мати змогу досягати loopback Gateway навіть тоді, коли операторський проксі блокує призначення loopback. Звичайні HTTP- і WebSocket-запити середовища виконання все одно використовують налаштований проксі.
|
||||
Публічним контрактом є поведінка маршрутизації, а не внутрішні хуки Node, використані для її реалізації. Клієнти WebSocket площини керування OpenClaw Gateway використовують вузький прямий шлях для local loopback Gateway RPC-трафіку, коли URL Gateway використовує `localhost` або літеральну loopback IP-адресу, як-от `127.0.0.1` чи `[::1]`. Цей шлях площини керування має мати змогу досягати loopback Gateway навіть тоді, коли операторський проксі блокує loopback-призначення. Звичайні runtime-запити HTTP і WebSocket і далі використовують налаштований проксі.
|
||||
|
||||
Сам URL проксі має використовувати `http://`. HTTPS-призначення все одно підтримуються через проксі за допомогою HTTP `CONNECT`; це лише означає, що OpenClaw очікує звичайний HTTP-слухач прямого проксі, як-от `http://127.0.0.1:3128`.
|
||||
|
||||
Поки проксі активний, OpenClaw очищає `no_proxy`, `NO_PROXY` і `GLOBAL_AGENT_NO_PROXY`. Ці списки обходу залежать від призначення, тому залишення там `localhost` або `127.0.0.1` дозволило б високоризиковим SSRF-цілям пропускати фільтрувальний проксі.
|
||||
Поки проксі активний, OpenClaw очищає `no_proxy`, `NO_PROXY` і `GLOBAL_AGENT_NO_PROXY`. Ці списки обходу базуються на призначенні, тому залишення там `localhost` або `127.0.0.1` дозволило б високоризиковим SSRF-цілям оминути фільтрувальний проксі.
|
||||
|
||||
Під час завершення роботи OpenClaw відновлює попереднє проксі-середовище й скидає кешований стан маршрутизації процесу.
|
||||
Під час завершення роботи OpenClaw відновлює попереднє проксі-середовище та скидає кешований стан маршрутизації процесу.
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -59,7 +59,7 @@ proxy:
|
||||
proxyUrl: http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
Ви також можете передати URL через середовище, зберігши `proxy.enabled=true` у конфігурації:
|
||||
Ви також можете передати URL через середовище, залишивши `proxy.enabled=true` у конфігурації:
|
||||
|
||||
```bash
|
||||
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
|
||||
@ -67,9 +67,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
|
||||
|
||||
`proxy.proxyUrl` має пріоритет над `OPENCLAW_PROXY_URL`.
|
||||
|
||||
Якщо `enabled=true`, але не налаштовано жодного дійсного URL проксі, захищені команди завершують запуск із помилкою замість того, щоб повертатися до прямого мережевого доступу.
|
||||
Якщо `enabled=true`, але не налаштовано дійсний URL проксі, захищені команди не запускаються замість того, щоб повертатися до прямого мережевого доступу.
|
||||
|
||||
Для керованих сервісів Gateway, запущених через `openclaw gateway start`, бажано зберігати URL у конфігурації:
|
||||
Для керованих служб Gateway, запущених через `openclaw gateway start`, краще зберігати URL у конфігурації:
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
@ -78,9 +78,9 @@ openclaw gateway install --force
|
||||
openclaw gateway start
|
||||
```
|
||||
|
||||
Резервний варіант через середовище найкраще підходить для запусків на передньому плані. Якщо ви використовуєте його з установленим сервісом, помістіть `OPENCLAW_PROXY_URL` у довговічне середовище сервісу, як-от `$OPENCLAW_STATE_DIR/.env` або `~/.openclaw/.env`, а потім перевстановіть сервіс, щоб launchd, systemd або Scheduled Tasks запускали gateway із цим значенням.
|
||||
Резервний варіант через середовище найкраще підходить для запусків у передньому плані. Якщо ви використовуєте його з установленою службою, помістіть `OPENCLAW_PROXY_URL` у тривале середовище служби, наприклад `$OPENCLAW_STATE_DIR/.env` або `~/.openclaw/.env`, а потім перевстановіть службу, щоб launchd, systemd або Scheduled Tasks запускали gateway із цим значенням.
|
||||
|
||||
Для команд `openclaw --container ...` OpenClaw пересилає `OPENCLAW_PROXY_URL` у дочірній CLI, націлений на контейнер, коли його встановлено. URL має бути доступний зсередини контейнера; `127.0.0.1` посилається на сам контейнер, а не на хост. OpenClaw відхиляє URL проксі loopback для команд, націлених на контейнер, якщо ви явно не перевизначите цю перевірку безпеки.
|
||||
Для команд `openclaw --container ...` OpenClaw передає `OPENCLAW_PROXY_URL` у дочірній CLI, націлений на контейнер, коли це значення встановлено. URL має бути доступним ізсередини контейнера; `127.0.0.1` вказує на сам контейнер, а не на хост. OpenClaw відхиляє loopback URL проксі для команд, націлених на контейнер, якщо ви явно не перевизначите цю перевірку безпеки.
|
||||
|
||||
## Вимоги до проксі
|
||||
|
||||
@ -89,44 +89,44 @@ openclaw gateway start
|
||||
Налаштуйте проксі так, щоб він:
|
||||
|
||||
- Прив’язувався лише до loopback або приватного довіреного інтерфейсу.
|
||||
- Обмежував доступ так, щоб ним міг користуватися лише процес, хост, контейнер або сервісний обліковий запис OpenClaw.
|
||||
- Самостійно розв’язував призначення й блокував IP-адреси призначення після DNS-розв’язання.
|
||||
- Застосовував політику під час підключення як для звичайних HTTP-запитів, так і для HTTPS-тунелів `CONNECT`.
|
||||
- Відхиляв обходи на основі призначення для loopback, приватних, link-local, metadata, multicast, зарезервованих діапазонів або діапазонів документації.
|
||||
- Уникав дозволених списків імен хостів, якщо ви повністю не довіряєте шляху DNS-розв’язання.
|
||||
- Журналював призначення, рішення, статус і причину без журналювання тіл запитів, заголовків авторизації, cookies або інших секретів.
|
||||
- Тримав політику проксі під контролем версій і переглядав зміни як чутливу до безпеки конфігурацію.
|
||||
- Обмежував доступ так, щоб ним могли користуватися лише процес OpenClaw, хост, контейнер або службовий обліковий запис.
|
||||
- Самостійно резолвив призначення та блокував IP-адреси призначення після DNS-резолюції.
|
||||
- Застосовував політику під час з’єднання як для звичайних HTTP-запитів, так і для HTTPS-тунелів `CONNECT`.
|
||||
- Відхиляв обходи на основі призначення для loopback, приватних, link-local, metadata, multicast, зарезервованих або документаційних діапазонів.
|
||||
- Уникав allowlist імен хостів, якщо ви не повністю довіряєте шляху DNS-резолюції.
|
||||
- Журналював призначення, рішення, статус і причину без журналювання тіл запитів, заголовків авторизації, cookie або інших секретів.
|
||||
- Тримав політику проксі під контролем версій і перевіряв зміни як чутливу до безпеки конфігурацію.
|
||||
|
||||
## Рекомендовані заблоковані призначення
|
||||
|
||||
Використовуйте цей список заборони як початкову точку для будь-якого прямого проксі, брандмауера або політики вихідного трафіку.
|
||||
Використовуйте цей denylist як відправну точку для будь-якого прямого проксі, firewall або політики вихідного трафіку.
|
||||
|
||||
Логіка класифікатора на рівні застосунку OpenClaw розташована в `src/infra/net/ssrf.ts` і `src/shared/net/ip.ts`. Відповідні хуки паритету — це `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` і вбудована обробка IPv4 sentinel для NAT64, 6to4, Teredo, ISATAP і IPv4-mapped форм. Ці файли є корисними довідковими матеріалами під час підтримки зовнішньої політики проксі, але OpenClaw не експортує й не застосовує ці правила автоматично у вашому проксі.
|
||||
Логіка класифікатора на рівні застосунку OpenClaw розташована в `src/infra/net/ssrf.ts` і `src/shared/net/ip.ts`. Відповідні хуки паритету: `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` і вбудована обробка sentinel для IPv4 для NAT64, 6to4, Teredo, ISATAP і IPv4-mapped форм. Ці файли є корисними довідковими матеріалами під час підтримки зовнішньої політики проксі, але OpenClaw не експортує й не застосовує ці правила у вашому проксі автоматично.
|
||||
|
||||
| Діапазон або хост | Навіщо блокувати |
|
||||
| ------------------------------------------------------------------------------------ | -------------------------------------------------- |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback |
|
||||
| `::1/128` | IPv6 loopback |
|
||||
| `0.0.0.0/8`, `::/128` | Невизначені адреси й адреси цієї мережі |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Приватні мережі RFC1918 |
|
||||
| `169.254.0.0/16`, `fe80::/10` | Link-local адреси та поширені шляхи cloud metadata |
|
||||
| `169.254.169.254`, `metadata.google.internal` | Сервіси cloud metadata |
|
||||
| `100.64.0.0/10` | Спільний адресний простір carrier-grade NAT |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | Діапазони benchmarking |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Діапазони спеціального використання й документації |
|
||||
| `224.0.0.0/4`, `ff00::/8` | Multicast |
|
||||
| `240.0.0.0/4` | Зарезервований IPv4 |
|
||||
| `fc00::/7`, `fec0::/10` | Локальні/приватні діапазони IPv6 |
|
||||
| `100::/64`, `2001:20::/28` | Діапазони IPv6 discard і ORCHIDv2 |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | Префікси NAT64 із вбудованим IPv4 |
|
||||
| `2002::/16`, `2001::/32` | 6to4 і Teredo із вбудованим IPv4 |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv4-compatible і IPv4-mapped IPv6 |
|
||||
| Діапазон або хост | Чому блокувати |
|
||||
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback |
|
||||
| `::1/128` | IPv6 loopback |
|
||||
| `0.0.0.0/8`, `::/128` | Невизначені адреси та адреси цієї мережі |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Приватні мережі RFC1918 |
|
||||
| `169.254.0.0/16`, `fe80::/10` | Link-local адреси та поширені шляхи cloud metadata |
|
||||
| `169.254.169.254`, `metadata.google.internal` | Служби cloud metadata |
|
||||
| `100.64.0.0/10` | Спільний адресний простір carrier-grade NAT |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | Діапазони для бенчмаркінгу |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Діапазони special-use і документаційні діапазони |
|
||||
| `224.0.0.0/4`, `ff00::/8` | Multicast |
|
||||
| `240.0.0.0/4` | Зарезервований IPv4 |
|
||||
| `fc00::/7`, `fec0::/10` | Локальні/приватні діапазони IPv6 |
|
||||
| `100::/64`, `2001:20::/28` | Діапазони IPv6 discard і ORCHIDv2 |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | Префікси NAT64 із вбудованим IPv4 |
|
||||
| `2002::/16`, `2001::/32` | 6to4 і Teredo із вбудованим IPv4 |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv4-compatible і IPv4-mapped IPv6 |
|
||||
|
||||
Якщо ваш хмарний провайдер або мережева платформа документує додаткові хости metadata чи зарезервовані діапазони, додайте і їх.
|
||||
Якщо ваш cloud provider або мережева платформа документує додаткові metadata хости чи зарезервовані діапазони, додайте і їх.
|
||||
|
||||
## Валідація
|
||||
|
||||
Перевірте проксі з того самого хоста, контейнера або сервісного облікового запису, який запускає OpenClaw:
|
||||
Перевіряйте проксі з того самого хоста, контейнера або службового облікового запису, де працює OpenClaw:
|
||||
|
||||
```bash
|
||||
curl -x http://127.0.0.1:3128 https://example.com/
|
||||
@ -136,7 +136,7 @@ curl -x http://127.0.0.1:3128 http://169.254.169.254/
|
||||
|
||||
Публічний запит має успішно виконатися. Запити до loopback і metadata мають завершитися помилкою на проксі.
|
||||
|
||||
Потім увімкніть маршрутизацію проксі OpenClaw:
|
||||
Потім увімкніть маршрутизацію OpenClaw через проксі:
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
@ -154,9 +154,9 @@ proxy:
|
||||
|
||||
## Обмеження
|
||||
|
||||
- Проксі покращує покриття для локальних для процесу JavaScript HTTP- і WebSocket-клієнтів, але не замінює `fetchWithSsrFGuard` на рівні застосунку.
|
||||
- Сирі сокети `net`, `tls` і `http2`, нативні додатки та дочірні процеси можуть обходити маршрутизацію проксі на рівні Node, якщо вони не успадковують і не дотримуються змінних середовища проксі.
|
||||
- Локальні WebUI користувача та локальні сервери моделей слід додавати до дозволеного списку в операторській політиці проксі, коли це потрібно; OpenClaw не надає для них загальний обхід локальної мережі.
|
||||
- Обхід проксі для площини керування Gateway навмисно обмежений URL із буквальними IP-адресами loopback. Використовуйте `ws://127.0.0.1:18789` або `ws://[::1]:18789` для локальних прямих підключень площини керування Gateway; імена хостів `localhost` маршрутизуються як звичайний трафік на основі імені хоста.
|
||||
- OpenClaw не перевіряє, не тестує й не сертифікує вашу політику проксі.
|
||||
- Проксі покращує покриття для локальних для процесу JavaScript-клієнтів HTTP і WebSocket, але не замінює `fetchWithSsrFGuard` на рівні застосунку.
|
||||
- Сирі сокети `net`, `tls` і `http2`, native addons і дочірні процеси можуть обходити маршрутизацію проксі на рівні Node, якщо вони не успадковують і не поважають змінні середовища проксі.
|
||||
- Локальні WebUI користувача та локальні сервери моделей слід додавати до allowlist у політиці операторського проксі, коли це потрібно; OpenClaw не надає для них загального обходу локальної мережі.
|
||||
- Обхід проксі площини керування Gateway навмисно обмежений `localhost` і літеральними loopback IP URL. Використовуйте `ws://127.0.0.1:18789`, `ws://[::1]:18789` або `ws://localhost:18789` для локальних прямих з’єднань площини керування Gateway; інші імена хостів маршрутизуються як звичайний трафік на основі імені хоста.
|
||||
- OpenClaw не інспектує, не тестує й не сертифікує вашу політику проксі.
|
||||
- Розглядайте зміни політики проксі як чутливі до безпеки операційні зміни.
|
||||
|
||||
@ -5,30 +5,30 @@ status: active
|
||||
summary: Пісочниця й обмеження інструментів для кожного агента, пріоритетність і приклади
|
||||
title: Багатоагентна пісочниця та інструменти
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:27:22Z"
|
||||
generated_at: "2026-04-29T11:03:40Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d6c43b9ff881d05c49f3e9d93859dd620e7b8e9febfddb16b7a9fd8b8e331e65
|
||||
source_hash: eedb36301f670bcd8956dbeb81788acfc96627e39401e34434c2348fcb10f155
|
||||
source_path: tools/multi-agent-sandbox-tools.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Кожен агент у багатоагентному налаштуванні може перевизначати глобальну політику пісочниці та інструментів. На цій сторінці описано конфігурацію для окремих агентів, правила пріоритету та приклади.
|
||||
Кожен агент у багатоагентному налаштуванні може перевизначати глобальну пісочницю та політику інструментів. Ця сторінка описує конфігурацію для окремого агента, правила пріоритету та приклади.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Пісочниця" href="/uk/gateway/sandboxing">
|
||||
Бекенди та режими — повна довідка з пісочниці.
|
||||
Бекенди та режими — повний довідник із пісочниці.
|
||||
</Card>
|
||||
<Card title="Пісочниця, політика інструментів і підвищений режим" href="/uk/gateway/sandbox-vs-tool-policy-vs-elevated">
|
||||
Налагодження питання «чому це заблоковано?»
|
||||
Налагодження "чому це заблоковано?"
|
||||
</Card>
|
||||
<Card title="Підвищений режим" href="/uk/tools/elevated">
|
||||
Підвищений exec для довірених відправників.
|
||||
<Card title="Режим із підвищеними правами" href="/uk/tools/elevated">
|
||||
Виконання з підвищеними правами для довірених відправників.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Warning>
|
||||
Автентифікація налаштовується для кожного агента: кожен агент читає зі свого сховища автентифікації `agentDir` у `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`. Облікові дані **не** спільні між агентами. Ніколи не використовуйте той самий `agentDir` для кількох агентів. Якщо потрібно поділитися обліковими даними, скопіюйте `auth-profiles.json` до `agentDir` іншого агента.
|
||||
Автентифікація прив’язана до агента: кожен агент має власне сховище автентифікації `agentDir` у `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`. Ніколи не використовуйте той самий `agentDir` для кількох агентів. Агенти можуть звертатися до профілів автентифікації типового/основного агента, коли не мають локального профілю, але токени оновлення OAuth не клонуються до сховищ вторинних агентів. Якщо ви копіюєте облікові дані вручну, копіюйте лише переносні статичні профілі `api_key` або `token`.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
@ -36,7 +36,7 @@ x-i18n:
|
||||
## Приклади конфігурації
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Приклад 1: особистий + обмежений сімейний агент">
|
||||
<Accordion title="Приклад 1: Особистий агент + обмежений сімейний агент">
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
@ -81,11 +81,11 @@ x-i18n:
|
||||
|
||||
**Результат:**
|
||||
|
||||
- агент `main`: працює на хості, повний доступ до інструментів.
|
||||
- агент `family`: працює в Docker (один контейнер на агента), лише інструмент `read`.
|
||||
- Агент `main`: працює на хості, має повний доступ до інструментів.
|
||||
- Агент `family`: працює в Docker (один контейнер на агента), лише інструмент `read`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Приклад 2: робочий агент зі спільною пісочницею">
|
||||
<Accordion title="Приклад 2: Робочий агент зі спільною пісочницею">
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
@ -113,7 +113,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Приклад 2b: глобальний профіль кодування + агент лише для повідомлень">
|
||||
<Accordion title="Приклад 2b: Глобальний профіль кодування + агент лише для повідомлень">
|
||||
```json
|
||||
{
|
||||
"tools": { "profile": "coding" },
|
||||
@ -130,11 +130,11 @@ x-i18n:
|
||||
|
||||
**Результат:**
|
||||
|
||||
- агенти за замовчуванням отримують інструменти кодування.
|
||||
- типові агенти отримують інструменти для кодування.
|
||||
- агент `support` призначений лише для повідомлень (+ інструмент Slack).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Приклад 3: різні режими пісочниці для кожного агента">
|
||||
<Accordion title="Приклад 3: Різні режими пісочниці для кожного агента">
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
@ -175,11 +175,11 @@ x-i18n:
|
||||
|
||||
## Пріоритет конфігурації
|
||||
|
||||
Коли існують і глобальні (`agents.defaults.*`), і специфічні для агента (`agents.list[].*`) конфігурації:
|
||||
Коли існують і глобальні (`agents.defaults.*`), і агент-специфічні (`agents.list[].*`) конфігурації:
|
||||
|
||||
### Конфігурація пісочниці
|
||||
|
||||
Налаштування для конкретного агента перевизначають глобальні:
|
||||
Налаштування конкретного агента перевизначають глобальні:
|
||||
|
||||
```
|
||||
agents.list[].sandbox.mode > agents.defaults.sandbox.mode
|
||||
@ -192,7 +192,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
```
|
||||
|
||||
<Note>
|
||||
`agents.list[].sandbox.{docker,browser,prune}.*` перевизначає `agents.defaults.sandbox.{docker,browser,prune}.*` для цього агента (ігнорується, коли область пісочниці визначається як `"shared"`).
|
||||
`agents.list[].sandbox.{docker,browser,prune}.*` перевизначає `agents.defaults.sandbox.{docker,browser,prune}.*` для цього агента (ігнорується, коли область пісочниці розв’язується як `"shared"`).
|
||||
</Note>
|
||||
|
||||
### Обмеження інструментів
|
||||
@ -212,7 +212,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
<Step title="Політика інструментів провайдера">
|
||||
`tools.byProvider[provider].allow/deny`.
|
||||
</Step>
|
||||
<Step title="Політика інструментів для конкретного агента">
|
||||
<Step title="Агент-специфічна політика інструментів">
|
||||
`agents.list[].tools.allow/deny`.
|
||||
</Step>
|
||||
<Step title="Політика провайдера агента">
|
||||
@ -221,27 +221,27 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
<Step title="Політика інструментів пісочниці">
|
||||
`tools.sandbox.tools` або `agents.list[].tools.sandbox.tools`.
|
||||
</Step>
|
||||
<Step title="Політика інструментів підагента">
|
||||
<Step title="Політика інструментів субагента">
|
||||
`tools.subagents.tools`, якщо застосовно.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Правила пріоритету">
|
||||
- Кожен рівень може додатково обмежувати інструменти, але не може знову дозволити інструменти, заборонені на попередніх рівнях.
|
||||
- Якщо задано `agents.list[].tools.sandbox.tools`, воно замінює `tools.sandbox.tools` для цього агента.
|
||||
- Якщо задано `agents.list[].tools.profile`, воно перевизначає `tools.profile` для цього агента.
|
||||
- Кожен рівень може додатково обмежувати інструменти, але не може знову дозволяти інструменти, заборонені на попередніх рівнях.
|
||||
- Якщо задано `agents.list[].tools.sandbox.tools`, це замінює `tools.sandbox.tools` для цього агента.
|
||||
- Якщо задано `agents.list[].tools.profile`, це перевизначає `tools.profile` для цього агента.
|
||||
- Ключі інструментів провайдера приймають або `provider` (наприклад, `google-antigravity`), або `provider/model` (наприклад, `openai/gpt-5.4`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Поведінка порожнього списку дозволів">
|
||||
Якщо будь-який явний список дозволів у цьому ланцюжку залишає запуск без доступних для виклику інструментів, OpenClaw зупиняється до надсилання промпта моделі. Це навмисно: агент, налаштований із відсутнім інструментом, наприклад `agents.list[].tools.allow: ["query_db"]`, має явно завершитися помилкою, доки Plugin, який реєструє `query_db`, не буде ввімкнено, а не продовжувати як агент лише з текстом.
|
||||
Якщо будь-який явний список дозволів у цьому ланцюжку залишає запуск без доступних для виклику інструментів, OpenClaw зупиняється до надсилання промпта моделі. Це навмисно: агент, налаштований із відсутнім інструментом, таким як `agents.list[].tools.allow: ["query_db"]`, має явно завершуватися помилкою, доки Plugin, який реєструє `query_db`, не буде ввімкнено, а не продовжувати роботу як текстовий агент.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Політики інструментів підтримують скорочення `group:*`, які розгортаються в кілька інструментів. Повний список див. у [Групи інструментів](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands).
|
||||
Політики інструментів підтримують скорочення `group:*`, які розгортаються в кілька інструментів. Повний список див. у [групах інструментів](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands).
|
||||
|
||||
Перевизначення підвищеного режиму для окремих агентів (`agents.list[].tools.elevated`) можуть додатково обмежувати підвищений exec для конкретних агентів. Докладніше див. у [Підвищений режим](/uk/tools/elevated).
|
||||
Перевизначення підвищених прав для окремого агента (`agents.list[].tools.elevated`) можуть додатково обмежувати виконання з підвищеними правами для конкретних агентів. Докладніше див. у [режимі з підвищеними правами](/uk/tools/elevated).
|
||||
|
||||
---
|
||||
|
||||
@ -328,17 +328,17 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
}
|
||||
```
|
||||
|
||||
`sessions_history` у цьому профілі все одно повертає обмежене й очищене представлення пригадування, а не сирий дамп стенограми. Пригадування асистента прибирає теги мислення, службову структуру `<relevant-memories>`, plain-text XML-навантаження викликів інструментів (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів), понижену службову структуру викликів інструментів, витіклі ASCII/повноширинні керівні токени моделі та некоректний XML викликів інструментів MiniMax перед редагуванням/обрізанням.
|
||||
`sessions_history` у цьому профілі все одно повертає обмежене, санітизоване подання згадування, а не сирий дамп транскрипту. Згадування асистента видаляє теги мислення, каркас `<relevant-memories>`, XML-навантаження викликів інструментів у звичайному тексті (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів), понижений каркас викликів інструментів, витеклі ASCII/повноширинні керівні токени моделі та некоректний XML викликів інструментів MiniMax перед редагуванням/обрізанням.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## Поширена пастка: "non-main"
|
||||
## Типова пастка: "non-main"
|
||||
|
||||
<Warning>
|
||||
`agents.defaults.sandbox.mode: "non-main"` базується на `session.mainKey` (за замовчуванням `"main"`), а не на ідентифікаторі агента. Сеанси груп/каналів завжди отримують власні ключі, тому вони вважаються non-main і будуть поміщені в пісочницю. Якщо ви хочете, щоб агент ніколи не використовував пісочницю, задайте `agents.list[].sandbox.mode: "off"`.
|
||||
`agents.defaults.sandbox.mode: "non-main"` базується на `session.mainKey` (типово `"main"`), а не на ідентифікаторі агента. Сесії груп/каналів завжди отримують власні ключі, тому вони вважаються неосновними та будуть ізольовані в пісочниці. Якщо ви хочете, щоб агент ніколи не використовував пісочницю, задайте `agents.list[].sandbox.mode: "off"`.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
@ -348,7 +348,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
Після налаштування багатоагентної пісочниці та інструментів:
|
||||
|
||||
<Steps>
|
||||
<Step title="Перевірте визначення агента">
|
||||
<Step title="Перевірте розв’язання агента">
|
||||
```bash
|
||||
openclaw agents list --bindings
|
||||
```
|
||||
@ -377,18 +377,18 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
<AccordionGroup>
|
||||
<Accordion title="Агент не в пісочниці, попри `mode: 'all'`">
|
||||
- Перевірте, чи немає глобального `agents.defaults.sandbox.mode`, який це перевизначає.
|
||||
- Конфігурація для конкретного агента має пріоритет, тому задайте `agents.list[].sandbox.mode: "all"`.
|
||||
- Агент-специфічна конфігурація має пріоритет, тому задайте `agents.list[].sandbox.mode: "all"`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Інструменти все ще доступні, попри список заборон">
|
||||
- Перевірте порядок фільтрації інструментів: глобальний → агент → пісочниця → підагент.
|
||||
- Перевірте порядок фільтрації інструментів: глобальний → агент → пісочниця → субагент.
|
||||
- Кожен рівень може лише додатково обмежувати, а не знову дозволяти.
|
||||
- Перевірте за журналами: `[tools] filtering tools for agent:${agentId}`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Контейнер не ізольований для кожного агента">
|
||||
- Задайте `scope: "agent"` у конфігурації пісочниці для конкретного агента.
|
||||
- За замовчуванням використовується `"session"`, що створює один контейнер на сеанс.
|
||||
- Задайте `scope: "agent"` в агент-специфічній конфігурації пісочниці.
|
||||
- Типове значення — `"session"`, що створює один контейнер на сесію.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -397,9 +397,9 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Підвищений режим](/uk/tools/elevated)
|
||||
- [Режим із підвищеними правами](/uk/tools/elevated)
|
||||
- [Багатоагентна маршрутизація](/uk/concepts/multi-agent)
|
||||
- [Конфігурація пісочниці](/uk/gateway/config-agents#agentsdefaultssandbox)
|
||||
- [Пісочниця, політика інструментів і підвищений режим](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) — налагодження питання «чому це заблоковано?»
|
||||
- [Пісочниця](/uk/gateway/sandboxing) — повна довідка з пісочниці (режими, області, бекенди, образи)
|
||||
- [Керування сеансами](/uk/concepts/session)
|
||||
- [Пісочниця, політика інструментів і підвищений режим](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) — налагодження "чому це заблоковано?"
|
||||
- [Пісочниця](/uk/gateway/sandboxing) — повний довідник із пісочниці (режими, області, бекенди, образи)
|
||||
- [Керування сесіями](/uk/concepts/session)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user