diff --git a/docs/uk/channels/pairing.md b/docs/uk/channels/pairing.md index 64e42f800..8b7528959 100644 --- a/docs/uk/channels/pairing.md +++ b/docs/uk/channels/pairing.md @@ -1,38 +1,38 @@ --- read_when: - - Налаштування контролю доступу до приватних повідомлень - - Сполучення нового Node iOS/Android - - Огляд стану безпеки OpenClaw -summary: 'Огляд сполучення: схваліть, хто може надсилати вам приватні повідомлення, і які Node можуть приєднуватися' + - Налаштування контролю доступу до особистих повідомлень + - Сполучення нового iOS/Android Node + - Перегляд стану безпеки OpenClaw +summary: 'Огляд сполучення: схваліть, хто може надсилати вам приватні повідомлення + які вузли можуть приєднуватися' title: Сполучення x-i18n: - generated_at: "2026-04-27T12:48:22Z" - model: gpt-5.4 + generated_at: "2026-04-28T22:44:27Z" + model: gpt-5.5 provider: openai - source_hash: e529167045272b0e34978aa94f6d2ba6e46afaafb08ad098575bf68737ff0925 + source_hash: 123d1dccfab0a2ed8a415934eb508e373c4fe85e3d07adb5eb8aa9f3cf8a3fc9 source_path: channels/pairing.md - workflow: 15 + workflow: 16 --- -«Сполучення» — це явний крок **схвалення власником** в OpenClaw. -Воно використовується у двох випадках: +«Спарювання» — це явний крок підтвердження доступу в OpenClaw. +Воно використовується у двох місцях: -1. **Сполучення DM** (кому дозволено спілкуватися з ботом) -2. **Сполучення Node** (яким пристроям/Node дозволено приєднуватися до мережі Gateway) +1. **Спарювання DM** (кому дозволено спілкуватися з ботом) +2. **Спарювання Node** (яким пристроям/Node дозволено приєднуватися до мережі Gateway) -Контекст безпеки: [Security](/uk/gateway/security) +Контекст безпеки: [Безпека](/uk/gateway/security) -## 1) Сполучення DM (доступ до вхідного чату) +## 1) Спарювання DM (вхідний доступ до чату) -Коли для каналу налаштовано політику DM `pairing`, невідомі відправники отримують короткий код, а їхнє повідомлення **не обробляється**, доки ви не дасте схвалення. +Коли канал налаштовано з політикою DM `pairing`, невідомі відправники отримують короткий код, а їхнє повідомлення **не обробляється**, доки ви його не підтвердите. -Стандартні політики DM задокументовано тут: [Security](/uk/gateway/security) +Типові політики DM задокументовано тут: [Безпека](/uk/gateway/security) -Коди сполучення: +Коди спарювання: - 8 символів, великі літери, без неоднозначних символів (`0O1I`). -- **Закінчують дію через 1 годину**. Бот надсилає повідомлення про сполучення лише тоді, коли створюється новий запит (приблизно раз на годину для кожного відправника). -- Кількість незавершених запитів на сполучення DM за замовчуванням обмежена до **3 на канал**; додаткові запити ігноруються, доки один із наявних не закінчить дію або не буде схвалений. +- **Спливають через 1 годину**. Бот надсилає повідомлення про спарювання лише тоді, коли створюється новий запит (приблизно раз на годину для кожного відправника). +- Очікувані запити на спарювання DM типово обмежені **3 на канал**; додаткові запити ігноруються, доки один не спливе або не буде схвалений. ### Схвалити відправника @@ -41,60 +41,71 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` +Якщо власника команд ще не налаштовано, схвалення коду спарювання DM також ініціалізує +`commands.ownerAllowFrom` схваленим відправником, наприклад `telegram:123456789`. +Це дає початковим налаштуванням явного власника для привілейованих команд і запитів +на схвалення exec. Після появи власника наступні схвалення спарювання надають лише +доступ до DM; вони не додають більше власників. + Підтримувані канали: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`. ### Де зберігається стан Зберігається в `~/.openclaw/credentials/`: -- Незавершені запити: `-pairing.json` -- Сховище списку дозволених схвалених записів: - - Стандартний обліковий запис: `-allowFrom.json` - - Нестандартний обліковий запис: `--allowFrom.json` +- Очікувані запити: `-pairing.json` +- Схвалене сховище allowlist: + - Типовий акаунт: `-allowFrom.json` + - Нетиповий акаунт: `--allowFrom.json` -Поведінка області дії облікових записів: +Поведінка області акаунта: -- Нестандартні облікові записи читають і записують лише у власний файл списку дозволених записів з відповідною областю дії. -- Стандартний обліковий запис використовує файл списку дозволених записів каналу без області дії. +- Нетипові акаунти читають/записують лише свій файл allowlist з областю. +- Типовий акаунт використовує каналовий файл allowlist без області. -Вважайте ці файли конфіденційними (вони контролюють доступ до вашого помічника). +Вважайте ці дані чутливими (вони контролюють доступ до вашого асистента). -Це сховище призначене для доступу до DM. Авторизація груп налаштовується окремо. Схвалення коду сполучення DM не дозволяє цьому відправнику автоматично виконувати групові команди або керувати ботом у групах. Для доступу до груп налаштуйте явні списки дозволених груп для каналу (наприклад, `groupAllowFrom`, `groups` або перевизначення для конкретних груп чи тем залежно від каналу). +Сховище allowlist для спарювання призначене для доступу до DM. Авторизація груп окрема. +Схвалення коду спарювання DM не дозволяє автоматично цьому відправнику запускати групові +команди або керувати ботом у групах. Початкова ініціалізація першого власника є окремим станом +конфігурації в `commands.ownerAllowFrom`, а доставка в групові чати й надалі підпорядковується +груповим allowlist каналу (наприклад `groupAllowFrom`, `groups` або перевизначенням для окремої групи +чи окремої теми залежно від каналу). -## 2) Сполучення пристроїв Node (Node iOS/Android/macOS/headless) +## 2) Спарювання пристрою Node (iOS/Android/macOS/headless Node) Node підключаються до Gateway як **пристрої** з `role: node`. Gateway -створює запит на сполучення пристрою, який потрібно схвалити. +створює запит на спарювання пристрою, який потрібно схвалити. -### Сполучення через Telegram (рекомендовано для iOS) +### Спарювання через Telegram (рекомендовано для iOS) -Якщо ви використовуєте Plugin `device-pair`, ви можете виконати початкове сполучення пристрою повністю через Telegram: +Якщо ви використовуєте Plugin `device-pair`, можна виконати перше спарювання пристрою повністю з Telegram: -1. У Telegram надішліть вашому боту: `/pair` -2. Бот відповість двома повідомленнями: повідомленням з інструкціями та окремим повідомленням із **кодом налаштування** (його зручно копіювати й вставляти в Telegram). +1. У Telegram напишіть своєму боту: `/pair` +2. Бот відповість двома повідомленнями: повідомленням з інструкціями та окремим повідомленням із **кодом налаштування** (його легко скопіювати/вставити в Telegram). 3. На телефоні відкрийте застосунок OpenClaw для iOS → Settings → Gateway. 4. Вставте код налаштування та підключіться. -5. Поверніться в Telegram: `/pair pending` (перегляньте ідентифікатори запитів, роль і області дії), а потім схваліть. +5. Поверніться в Telegram: `/pair pending` (перегляньте ID запитів, роль і області), потім схваліть. -Код налаштування — це JSON-дані у кодуванні base64, які містять: +Код налаштування — це base64-кодоване JSON-навантаження, яке містить: -- `url`: URL WebSocket Gateway (`ws://...` або `wss://...`) -- `bootstrapToken`: короткочасний bootstrap-токен для одного пристрою, який використовується для початкового рукостискання сполучення +- `url`: URL WebSocket для Gateway (`ws://...` або `wss://...`) +- `bootstrapToken`: короткоживучий bootstrap-токен для одного пристрою, що використовується для початкового handshake спарювання -Цей bootstrap-токен містить вбудований bootstrap-профіль сполучення: +Цей bootstrap-токен містить вбудований bootstrap-профіль спарювання: - основний переданий токен `node` залишається з `scopes: []` -- будь-який переданий токен `operator` залишається обмеженим bootstrap-списком дозволів: +- будь-який переданий токен `operator` залишається обмеженим bootstrap allowlist: `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write` -- перевірки bootstrap-областей дії мають префікс ролі, а не є єдиним плоским пулом областей дії: - записи областей дії operator задовольняють лише запити operator, а ролі, що не є operator, - однаково мають запитувати області дії під префіксом власної ролі -- подальша ротація/відкликання токенів надалі обмежується як схваленим - рольовим контрактом пристрою, так і областями дії operator у сеансі виклику +- перевірки bootstrap-областей мають префікс ролі, а не один плоский пул областей: + записи області operator задовольняють лише запити operator, а ролі не-operator + усе одно мають запитувати області під власним префіксом ролі +- подальша ротація/відкликання токенів залишається обмеженою як схваленим + контрактом ролі пристрою, так і областями operator сесії викликача -Ставтеся до коду налаштування як до пароля, поки він дійсний. +Ставтеся до коду налаштування як до пароля, поки він чинний. ### Схвалити пристрій Node @@ -104,17 +115,18 @@ openclaw devices approve openclaw devices reject ``` -Якщо той самий пристрій повторно спробує підключитися з іншими даними автентифікації (наприклад, з іншою роллю/областями дії/публічним ключем), попередній незавершений запит буде замінено, і буде створено новий +Якщо той самий пристрій повторює спробу з іншими даними автентифікації (наприклад з іншими +роллю/областями/публічним ключем), попередній очікуваний запит замінюється, і створюється новий `requestId`. -Пристрій, який уже пройшов сполучення, не отримує ширший доступ непомітно. Якщо він перепідключається із запитом на більші області дії або ширшу роль, OpenClaw залишає наявне схвалення без змін і створює новий незавершений запит на розширення доступу. Використовуйте `openclaw devices list`, щоб порівняти поточний схвалений доступ із новим запитаним доступом, перш ніж схвалювати. +Уже спарений пристрій не отримує ширший доступ непомітно. Якщо він перепідключається і просить більше областей або ширшу роль, OpenClaw залишає наявне схвалення без змін і створює новий очікуваний запит на підвищення доступу. Використовуйте `openclaw devices list`, щоб порівняти поточний схвалений доступ із новим запитаним доступом перед схваленням. -### Необов’язкове авто-схвалення Node за довіреними CIDR +### Необов’язкове автоматичне схвалення Node за довіреним CIDR -Сполучення пристроїв за замовчуванням і надалі виконується вручну. Для жорстко контрольованих мереж Node -можна ввімкнути автоматичне початкове схвалення Node за явними CIDR або точними IP-адресами: +Спарювання пристроїв типово залишається ручним. Для суворо контрольованих мереж Node +можна ввімкнути автоматичне схвалення першого підключення Node з явними CIDR або точними IP: ```json5 { @@ -128,35 +140,35 @@ openclaw devices reject } ``` -Це застосовується лише до нових запитів на сполучення `role: node` без запитаних -областей дії. Клієнти Operator, браузера, Control UI і WebChat однаково потребують ручного -схвалення. Зміни ролі, областей дії, метаданих і публічного ключа, як і раніше, потребують ручного +Це застосовується лише до нових запитів спарювання `role: node` без запитаних +областей. Клієнти operator, browser, Control UI і WebChat усе одно потребують ручного +схвалення. Зміни ролі, області, metadata та публічного ключа також потребують ручного схвалення. -### Зберігання стану сполучення Node +### Сховище стану спарювання Node Зберігається в `~/.openclaw/devices/`: -- `pending.json` (короткочасний; незавершені запити закінчують дію) -- `paired.json` (сполучені пристрої + токени) +- `pending.json` (короткоживучий; очікувані запити спливають) +- `paired.json` (спарені пристрої + токени) ### Примітки -- Застарілий API `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|remove|rename`) — це - окреме сховище сполучення, яким володіє Gateway. Node WS однаково потребують сполучення пристрою. -- Запис сполучення є довготривалим джерелом істини для схвалених ролей. Активні - токени пристрою залишаються обмеженими цим схваленим набором ролей; випадковий запис токена - поза межами схвалених ролей не створює нового доступу. +- Застарілий API `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|remove|rename`) є + окремим сховищем спарювання, яким володіє Gateway. WS Node усе одно потребують спарювання пристрою. +- Запис спарювання є довговічним джерелом істини для схвалених ролей. Активні + токени пристрою залишаються обмеженими цим набором схвалених ролей; випадковий запис токена + поза схваленими ролями не створює нового доступу. -## Пов’язана документація +## Пов’язані документи -- Модель безпеки + ін’єкція підказок: [Security](/uk/gateway/security) -- Безпечне оновлення (запустіть doctor): [Updating](/uk/install/updating) +- Модель безпеки + prompt injection: [Безпека](/uk/gateway/security) +- Безпечне оновлення (запустіть doctor): [Оновлення](/uk/install/updating) - Конфігурації каналів: - Telegram: [Telegram](/uk/channels/telegram) - WhatsApp: [WhatsApp](/uk/channels/whatsapp) - Signal: [Signal](/uk/channels/signal) - BlueBubbles (iMessage): [BlueBubbles](/uk/channels/bluebubbles) - - iMessage (застаріле): [iMessage](/uk/channels/imessage) + - iMessage (застарілий): [iMessage](/uk/channels/imessage) - Discord: [Discord](/uk/channels/discord) - Slack: [Slack](/uk/channels/slack) diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index edc8246a3..a9fd0fb80 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,28 +1,28 @@ --- read_when: - Робота над функціями Telegram або Webhook -summary: Стан підтримки бота Telegram, можливості та конфігурація +summary: Статус підтримки Telegram-бота, можливості та налаштування title: Telegram x-i18n: - generated_at: "2026-04-28T20:11:05Z" + generated_at: "2026-04-28T22:44:12Z" model: gpt-5.5 provider: openai - source_hash: 663fd2eecc7f2ff02622f5fde1a6ae3c97427f7aeda26f89a230529f3284df8b + source_hash: 2e334360bce47f1b90d1fad1fe08a13b1b976ec86e06c87647dc87f71852fc8a source_path: channels/telegram.md workflow: 16 --- -Готовий до production для DM бота та груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook необов’язковий. +Готово до production для приватних повідомлень бота та груп через grammY. Режим довгого опитування є режимом за замовчуванням; режим Webhook необов'язковий. - Політика DM за замовчуванням для Telegram — сполучення. + Політика приватних повідомлень за замовчуванням для Telegram — сполучення. Міжканальна діагностика та інструкції з відновлення. - Повні шаблони та приклади конфігурації каналів. + Повні шаблони й приклади конфігурації каналів. @@ -30,13 +30,13 @@ x-i18n: - Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle саме `@BotFather`). + Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що ім'я точно `@BotFather`). Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен. - + ```json5 { @@ -51,12 +51,12 @@ x-i18n: } ``` - Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). - Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway. + Резервний варіант через середовище: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). + Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у конфігурації або середовищі, а потім запустіть gateway. - + ```bash openclaw gateway @@ -64,7 +64,7 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Коди сполучення діють 1 годину. + Коди сполучення спливають через 1 годину. @@ -74,26 +74,26 @@ openclaw pairing approve telegram -Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. +Порядок визначення токена враховує обліковий запис. На практиці значення конфігурації мають пріоритет над резервним значенням із середовища, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. -## Налаштування на боці Telegram +## Налаштування на стороні Telegram - Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують. + Для ботів Telegram за замовчуванням увімкнено **режим приватності**, який обмежує, які групові повідомлення вони отримують. Якщо бот має бачити всі групові повідомлення, або: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. - Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну. + Після перемикання режиму приватності видаліть і знову додайте бота в кожну групу, щоб Telegram застосував зміну. - Статус адміністратора контролюється в налаштуваннях групи Telegram. + Статус адміністратора керується в налаштуваннях групи Telegram. Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі. @@ -101,42 +101,43 @@ openclaw pairing approve telegram - - `/setjoingroups`, щоб дозволити/заборонити додавання до груп + - `/setjoingroups`, щоб дозволити або заборонити додавання до груп - `/setprivacy` для поведінки видимості в групах -## Контроль доступу та активація +## Контроль доступу й активація - - `channels.telegram.dmPolicy` керує доступом до прямих повідомлень: + + `channels.telegram.dmPolicy` керує доступом через прямі повідомлення: - `pairing` (за замовчуванням) - - `allowlist` (потребує щонайменше одного ID відправника в `allowFrom`) - - `open` (потребує, щоб `allowFrom` містив `"*"`) + - `allowlist` (потрібен принаймні один ID відправника в `allowFrom`) + - `open` (потрібно, щоб `allowFrom` містив `"*"`) - `disabled` - `dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів. + `dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім'я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів. - `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються. - `dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється валідацією конфігурації. + `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються й нормалізуються. + `dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі приватні повідомлення й відхиляється перевіркою конфігурації. Налаштування запитує лише числові ID користувачів. - Якщо ви оновилися і ваша конфігурація містить записи allowlist з `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потрібен токен бота Telegram). - Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у сценаріях allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). + Якщо ви оновилися й ваша конфігурація містить записи списку дозволених `@username`, виконайте `openclaw doctor --fix`, щоб їх розв'язати (на основі найкращої спроби; потрібен токен бота Telegram). + Якщо раніше ви покладалися на файли списку дозволених зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках списку дозволених (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх схвалень сполучення). - Поширене непорозуміння: схвалення сполучення DM не означає «цей відправник авторизований усюди». - Сполучення надає доступ лише до DM. Авторизація відправника в групі все одно береться з явних allowlist у конфігурації. - Якщо ви хочете «я авторизований один раз, і працюють як DM, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`. + Поширена плутанина: схвалення сполучення для приватних повідомлень не означає "цей відправник авторизований всюди". + Сполучення надає доступ до приватних повідомлень. Якщо власника команд ще немає, перше схвалене сполучення також встановлює `commands.ownerAllowFrom`, щоб команди лише для власника й схвалення виконання мали явний обліковий запис оператора. + Авторизація відправників у групах усе одно береться з явних списків дозволених у конфігурації. + Якщо ви хочете "я авторизований один раз, і працюють як приватні повідомлення, так і групові команди", додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. ### Як знайти свій ID користувача Telegram Безпечніше (без стороннього бота): - 1. Напишіть своєму боту в DM. + 1. Надішліть приватне повідомлення своєму боту. 2. Виконайте `openclaw logs --follow`. 3. Прочитайте `from.id`. @@ -150,14 +151,14 @@ curl "https://api.telegram.org/bot/getUpdates" - - Два механізми застосовуються разом: + + Два елементи керування застосовуються разом: 1. **Які групи дозволені** (`channels.telegram.groups`) - немає конфігурації `groups`: - з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи - з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`) - - `groups` налаштовано: працює як allowlist (явні ID або `"*"`) + - `groups` налаштовано: працює як список дозволених (явні ID або `"*"`) 2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`) - `open` @@ -166,13 +167,13 @@ curl "https://api.telegram.org/bot/getUpdates" `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`. Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються). - Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Негативні ID чатів належать до `channels.telegram.groups`. + Не додавайте ID чатів груп або супергруп Telegram до `groupAllowFrom`. Від'ємні ID чатів належать до `channels.telegram.groups`. Нечислові записи ігноруються для авторизації відправника. - Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень DM. - Сполучення лишається тільки для DM. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи/теми. - Якщо `groupAllowFrom` не задано, Telegram повертається до `allowFrom` у конфігурації, а не до сховища сполучень. + Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища сполучень приватних повідомлень. + Сполучення залишається лише для приватних повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи чи теми. + Якщо `groupAllowFrom` не задано, Telegram повертається до конфігураційного `allowFrom`, а не до сховища сполучень. Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`. - Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed із `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. + Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням закриває доступ із `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. Приклад: дозволити будь-якого учасника в одній конкретній групі: @@ -209,18 +210,18 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram. + Поширена помилка: `groupAllowFrom` — це не список дозволених груп Telegram. - - Додавайте негативні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. - - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. - - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом. + - Додавайте від'ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, до `channels.telegram.groups`. + - Додавайте ID користувачів Telegram, як-от `8734062810`, до `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. + - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг звертатися до бота. - Відповіді в групах за замовчуванням потребують згадки. + Групові відповіді за замовчуванням потребують згадки. Згадка може надходити з: @@ -252,9 +253,9 @@ curl "https://api.telegram.org/bot/getUpdates" Отримання ID групового чату: - - переслати групове повідомлення до `@userinfobot` / `@getidsbot` - - або прочитати `chat.id` з `openclaw logs --follow` - - або перевірити `getUpdates` Bot API + - перешліть групове повідомлення до `@userinfobot` / `@getidsbot` + - або прочитайте `chat.id` з `openclaw logs --follow` + - або перевірте `getUpdates` у Bot API @@ -263,13 +264,13 @@ curl "https://api.telegram.org/bot/getUpdates" - Telegram належить процесу gateway. - Маршрутизація детермінована: вхідні повідомлення Telegram відповідають назад у Telegram (модель не вибирає канали). -- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та плейсхолдерами медіа. -- Групові сесії ізольовані за ID групи. Теми форумів додають `:topic:`, щоб ізолювати теми. -- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують thread, і зберігає ID thread для відповідей. -- Довге опитування використовує grammY runner із послідовністю на рівні чату/thread. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`. -- Довге опитування захищене всередині кожного процесу gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший gateway OpenClaw, скрипт або зовнішній poller використовує той самий токен. -- Перезапуски watchdog довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зупинку опитування під час тривалої роботи. Значення вказується в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. -- Telegram Bot API не підтримує сповіщення про прочитання (`sendReadReceipts` не застосовується). +- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та заповнювачами для медіа. +- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми залишалися ізольованими. +- Приватні повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують тему, і зберігає ID теми для відповідей. +- Довге опитування використовує runner grammY з послідовністю на рівні чату й теми. Загальна конкурентність приймача runner використовує `agents.defaults.maxConcurrent`. +- Довге опитування захищене всередині кожного процесу gateway, щоб лише один активний опитувач міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший gateway OpenClaw, скрипт або зовнішній опитувач використовує той самий токен. +- Перезапуски сторожового механізму довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної перевірки живості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зупинку опитування під час довготривалої роботи. Значення в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. +- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується). ## Довідник функцій @@ -283,11 +284,11 @@ curl "https://api.telegram.org/bot/getUpdates" Вимога: - `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`) - - `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням) - - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активний streaming попереднього перегляду) - - застарілі значення `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode` + - `progress` відображається на `partial` у Telegram (сумісність із міжканальним іменуванням) + - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активна потокова передача попереднього перегляду) + - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode` - Оновлення попереднього перегляду прогресу інструментів — це короткі рядки "Working...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram тримає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніше. Щоб зберегти редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: + Оновлення попереднього перегляду прогресу інструментів — це короткі рядки "Працюємо...", показані під час виконання інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки патчів. Telegram лишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { @@ -304,45 +305,45 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Використовуйте `streaming.mode: "off"` лише тоді, коли хочете доставку лише фінальної відповіді: редагування попереднього перегляду Telegram вимкнені, а загальний шум інструментів/прогресу пригнічується замість надсилання як окремі повідомлення "Working...". Запити схвалення, медіа payloads і помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете зберегти лише редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів. + Використовуйте `streaming.mode: "off"` лише тоді, коли хочете доставку тільки фінального повідомлення: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу пригнічуються замість надсилання окремими повідомленнями "Працюємо...". Запити схвалення, медіаконтент і помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете залишити лише редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів. - Для відповідей лише з текстом: + Для текстових відповідей: - - короткі попередні перегляди DM/груп/тем: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці - - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тож видима мітка часу Telegram відображає час завершення, а не час створення попереднього перегляду + - короткі попередні перегляди в приватних повідомленнях/групах/темах: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці + - попередні перегляди старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, щоб видима позначка часу Telegram відображала час завершення, а не час створення попереднього перегляду - Для складних відповідей (наприклад, media payloads) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. + Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. - Попередній streaming окремий від блокового streaming. Коли блоковий streaming явно ввімкнено для Telegram, OpenClaw пропускає попередній stream, щоб уникнути подвійного streaming. + Потоковий попередній перегляд відокремлений від потокової передачі блоків. Коли потокову передачу блоків явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної потокової передачі. Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`. - Stream reasoning лише для Telegram: + Потік міркувань лише для Telegram: - - `/reasoning stream` надсилає reasoning у живий попередній перегляд під час генерування - - фінальна відповідь надсилається без тексту reasoning + - `/reasoning stream` надсилає міркування в живий попередній перегляд під час генерації + - фінальна відповідь надсилається без тексту міркувань - + Вихідний текст використовує Telegram `parse_mode: "HTML"`. - - Markdown-подібний текст рендериться у безпечний для Telegram HTML. + - Markdown-подібний текст рендериться в HTML, безпечний для Telegram. - Сирий HTML від моделі екранується, щоб зменшити кількість помилок парсингу Telegram. - - Якщо Telegram відхиляє розпарсений HTML, OpenClaw повторює надсилання як звичайний текст. + - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст. Попередні перегляди посилань увімкнено за замовчуванням, і їх можна вимкнути за допомогою `channels.telegram.linkPreview: false`. - - Реєстрація меню команд Telegram обробляється під час запуску через `setMyCommands`. + + Реєстрація меню команд Telegram виконується під час запуску за допомогою `setMyCommands`. - Типові значення нативних команд: + Стандартні значення нативних команд: - `commands.native: "auto"` вмикає нативні команди для Telegram - Додайте власні записи меню команд: + Додайте користувацькі записи в меню команд: ```json5 { @@ -359,47 +360,47 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - імена нормалізуються (видаляється початковий `/`, переводяться в нижній регістр) - - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - - власні команди не можуть перевизначати нативні команди + - назви нормалізуються (прибирається початковий `/`, переводяться в нижній регістр) + - дійсний шаблон: `a-z`, `0-9`, `_`, довжина `1..32` + - користувацькі команди не можуть перевизначати нативні команди - конфлікти/дублікати пропускаються й логуються Примітки: - - власні команди є лише записами меню; вони не реалізують поведінку автоматично - - команди plugin/skill усе ще можуть працювати, якщо їх ввести, навіть якщо вони не показані в меню Telegram + - користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично + - команди Plugin/Skills можуть і далі працювати під час введення, навіть якщо їх не показано в меню Telegram - Якщо нативні команди вимкнено, вбудовані команди видаляються. Власні команди/команди Plugin усе ще можуть реєструватися, якщо налаштовані. + Якщо нативні команди вимкнено, вбудовані команди видаляються. Команди користувацьких Plugin можуть усе одно реєструватися, якщо це налаштовано. - Типові помилки налаштування: + Поширені помилки налаштування: - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість команд Plugin/skill/власних команд або вимкніть `channels.telegram.commands.native`. - - Помилка `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було задано як повний endpoint `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. - - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до polling, тому це не повідомляється як помилка очищення Webhook. - - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано. + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнилося після обрізання; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`. + - Збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було задано як повний кінцевий шлях `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. + - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до опитування, тому це не повідомляється як збій очищення Webhook. + - `setMyCommands failed` з мережевими помилками або помилками fetch зазвичай означає, що вихідні DNS/HTTPS до `api.telegram.org` заблоковано. - ### Команди сполучення пристрою (Plugin `device-pair`) + ### Команди сполучення пристрою (`device-pair` Plugin) - Коли Plugin `device-pair` встановлено: + Коли встановлено `device-pair` Plugin: 1. `/pair` генерує код налаштування 2. вставте код у застосунок iOS - 3. `/pair pending` перелічує запити, що очікують (зокрема role/scopes) + 3. `/pair pending` виводить список запитів, що очікують (включно з роллю/областями дії) 4. схваліть запит: - `/pair approve ` для явного схвалення - `/pair approve`, коли є лише один запит, що очікує - `/pair approve latest` для найновішого - Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен primary node на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролям, що не є операторськими, все ще потрібні scopes під власним префіксом ролі. + Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей дії bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; неоператорським ролям усе ще потрібні області дії під власним префіксом ролі. - Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, role/scopes/public key), попередній запит, що очікує, замінюється, а новий запит використовує інший `requestId`. Перед схваленням повторно запустіть `/pair pending`. + Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роллю/областями дії/публічним ключем), попередній запит, що очікує, замінюється, а новий запит використовує інший `requestId`. Повторно запустіть `/pair pending` перед схваленням. Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). - - Налаштуйте scope inline-клавіатури: + + Налаштуйте область дії вбудованої клавіатури: ```json5 { @@ -431,7 +432,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Scopes: + Області дії: - `off` - `dm` @@ -439,9 +440,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (за замовчуванням) - Застаріле `capabilities: ["inlineButtons"]` мапиться на `inlineButtons: "all"`. + Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`. - Приклад дії повідомлення: + Приклад дії з повідомленням: ```json5 { @@ -464,7 +465,7 @@ curl "https://api.telegram.org/bot/getUpdates" - + Дії інструментів Telegram включають: - `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`) @@ -475,24 +476,24 @@ curl "https://api.telegram.org/bot/getUpdates" Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Елементи керування доступом: + Засоби керування доступом: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (за замовчуванням: вимкнено) - Примітка: `edit` і `topic-create` зараз увімкнено за замовчуванням, і вони не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час виконання використовують активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання. + Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. + Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) - - Telegram підтримує явні теги reply threading у згенерованому виводі: + + Telegram підтримує явні теги потоків відповідей у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення, що спричинило запуск + - `[[reply_to_current]]` відповідає на повідомлення, що запустило обробку - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: @@ -501,29 +502,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Коли reply threading увімкнено й доступний початковий текст або підпис Telegram, OpenClaw автоматично включає нативний фрагмент цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. + Коли потоки відповідей увімкнено й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично включає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. - Примітка: `off` вимикає неявний reply threading. Явні теги `[[reply_to_*]]` усе ще враховуються. + Примітка: `off` вимикає неявні потоки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. - + Форумні супергрупи: - - ключі сесій тем додають `:topic:` - - відповіді й індикація набору тексту спрямовуються в thread теми + - ключі сесій теми додають `:topic:` + - відповіді та індикатор набору спрямовуються в потік теми - шлях конфігурації теми: `channels.telegram.groups..topics.` - Спеціальний випадок загальної теми (`threadId=1`): + Особливий випадок загальної теми (`threadId=1`): - - надсилання повідомлень не включають `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) + - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - дії набору тексту все одно включають `message_thread_id` - Наслідування тем: записи тем наслідують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` застосовується лише до теми й не наслідується з типових значень групи. + Успадкування теми: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` застосовується лише до теми й не успадковується зі стандартних налаштувань групи. - **Маршрутизація агентів за темами**: кожна тема може спрямовуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований workspace, пам’ять і сесію. Приклад: + **Маршрутизація агентів за темами**: кожна тема може маршрутизуватися до іншого агента через задання `agentId` у конфігурації теми. Це надає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: ```json5 { @@ -545,26 +546,26 @@ curl "https://api.telegram.org/bot/getUpdates" Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` - **Постійне прив’язування тем ACP**: форумні теми можуть закріплювати сесії ACP harness через типізовані ACP bindings верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та id з уточненням теми, як-от `-1001234567890:topic:42`). Наразі scoped до форумних тем у групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). + **Постійне прив’язування тем ACP**: теми форуму можуть закріплювати сесії ACP harness через типізовані ACP-прив’язки верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ID з уточненням теми, як-от `-1001234567890:topic:42`). Наразі область дії обмежена темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). - **Створення thread-bound ACP із чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової ACP-сесії; подальші повідомлення спрямовуються туди напряму. OpenClaw закріплює підтвердження створення в темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`. + **Прив’язаний до потоку запуск ACP із чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`. - Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають DM-маршрутизацію, але використовують ключі сесій, що враховують thread. + Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесій з урахуванням потоку. - + ### Аудіоповідомлення - Telegram розрізняє голосові нотатки та аудіофайли. + Telegram розрізняє голосові нотатки й аудіофайли. - - за замовчуванням: поведінка аудіофайла + - за замовчуванням: поведінка аудіофайлу - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає голосову нотатку - - транскрипти вхідних голосових нотаток оформлюються як машинно згенерований, - недовірений текст у контексті агента; виявлення згадок усе ще використовує сирий - транскрипт, тому voice-повідомлення з gate за згадкою продовжують працювати. + - транскрипти вхідних голосових нотаток оформлюються в контексті агента як машинно згенерований, + ненадійний текст; виявлення згадок усе одно використовує сирий + транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати. - Приклад дії повідомлення: + Приклад дії з повідомленням: ```json5 { @@ -580,7 +581,7 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram розрізняє відеофайли та відеонотатки. - Приклад дії повідомлення: + Приклад дії з повідомленням: ```json5 { @@ -598,7 +599,7 @@ curl "https://api.telegram.org/bot/getUpdates" Обробка вхідних стікерів: - - статичний WEBP: завантажується й обробляється (placeholder ``) + - статичний WEBP: завантажується й обробляється (заповнювач ``) - анімований TGS: пропускається - відео WEBM: пропускається @@ -614,7 +615,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних vision-викликів. + Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів vision. Увімкніть дії зі стікерами: @@ -654,8 +655,8 @@ curl "https://api.telegram.org/bot/getUpdates" - - Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлень). + + Реакції Telegram надходять як оновлення `message_reaction` (окремо від вмісту повідомлень). Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт: @@ -668,35 +669,35 @@ curl "https://api.telegram.org/bot/getUpdates" Примітки: - - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (за найкращих зусиль через кеш надісланих повідомлень). - - Події реакцій усе ще поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - - Telegram не надає ідентифікатори тем у оновленнях реакцій. - - групи без форуму маршрутизуються до сеансу групового чату - - групи-форуми маршрутизуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми + - `own` означає лише реакції користувача на повідомлення, надіслані ботом (за можливості через кеш надісланих повідомлень). + - Події реакцій і надалі дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. + - Telegram не надає ідентифікатори гілок у оновленнях реакцій. + - групи без форуму спрямовуються до сесії групового чату + - форумні групи спрямовуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми - `allowed_updates` для polling/webhook автоматично включає `message_reaction`. + `allowed_updates` для polling/webhook автоматично містить `message_reaction`. - - `ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення. + + `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. - Порядок визначення: + Порядок розв’язання: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Telegram очікує unicode emoji (наприклад, "👀"). - - Використайте `""`, щоб вимкнути реакцію для каналу або облікового запису. + - Telegram очікує Unicode-емодзі (наприклад "👀"). + - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - Записи конфігурації каналу ввімкнено за замовчуванням (`configWrites !== false`). + Записи конфігурації каналу ввімкнені за замовчуванням (`configWrites !== false`). Записи, ініційовані Telegram, включають: @@ -720,35 +721,35 @@ curl "https://api.telegram.org/bot/getUpdates" За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`). - Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або розмістіть reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. + Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. - Режим Webhook перевіряє захист запитів, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram. - Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота для кожного чату/кожної теми, що й у long polling, тож повільні ходи агента не утримують delivery ACK Telegram. + Режим webhook перевіряє захисти запиту, секретний токен Telegram і JSON-тіло перед поверненням `200` до Telegram. + Після цього OpenClaw обробляє оновлення асинхронно через ті самі бот-лінії для кожного чату/теми, які використовує long polling, тож повільні ходи агента не затримують delivery ACK Telegram. - + - `channels.telegram.textChunkLimit` за замовчуванням дорівнює 4000. - - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною. + - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. - `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіа Telegram. - - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується стандартне значення grammY). - - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зависання polling. - - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає. - - додатковий контекст відповіді/цитати/пересилання наразі передається як отриманий. - - allowlist Telegram передусім обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + - `channels.telegram.timeoutSeconds` перевизначає timeout клієнта Telegram API (якщо не задано, застосовується стандартне значення grammY). + - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зупинку polling. + - історія групового контексту використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає. + - додатковий контекст reply/quote/forward наразі передається як отриманий. + - allowlists Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. - Керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API. + - Конфігурація `channels.telegram.retry` застосовується до helper-ів надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. - Ціль надсилання CLI може бути числовим ID чату або іменем користувача: + Ціль надсилання CLI може бути числовим ідентифікатором чату або іменем користувача: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Опитування Telegram використовують `openclaw message poll` і підтримують теми форуму: + Опитування Telegram використовують `openclaw message poll` і підтримують форумні теми: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -763,50 +764,50 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` для тем форуму (або використайте ціль `:topic:`) + - `--thread-id` для форумних тем (або використовуйте ціль `:topic:`) Надсилання Telegram також підтримує: - - `--presentation` з блоками `buttons` для inline-клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє - - `--pin` або `--delivery '{"pin":true}'`, щоб запитати закріплену доставку, коли бот може закріплювати в цьому чаті - - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених завантажень фото або animated-media + - `--presentation` з блоками `buttons` для inline keyboards, коли `channels.telegram.capabilities.inlineButtons` це дозволяє + - `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, коли бот може закріплювати в цьому чаті + - `--force-document` для надсилання вихідних зображень і GIF як документів замість стиснених завантажень фото або анімованих медіа Обмеження дій: - - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, зокрема опитування + - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим - - Telegram підтримує підтвердження exec у DM затверджувачів і може додатково публікувати запити в початковому чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram. + + Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ідентифікаторами користувачів Telegram. Шлях конфігурації: - - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного затверджувача) - - `channels.telegram.execApprovals.approvers` (резервно використовує числові ID власників із `allowFrom` / `defaultTo`) + - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна розв’язати принаймні одного схвалювача) + - `channels.telegram.execApprovals.approvers` (fallback до числових ідентифікаторів власників з `commands.ownerAllowFrom`, `allowFrom` або `defaultTo`) - `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both` - `agentFilter`, `sessionFilter` - Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту підтвердження та наступного повідомлення. Підтвердження exec за замовчуванням спливають через 30 хвилин. + Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему для запиту схвалення і наступного повідомлення. Схвалення exec за замовчуванням спливають через 30 хвилин. - Кнопки inline-підтвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID підтверджень із префіксом `plugin:` визначаються через підтвердження plugin; інші спочатку визначаються через підтвердження exec. + Inline-кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). Ідентифікатори схвалень із префіксом `plugin:` розв’язуються через схвалення Plugin; інші спершу розв’язуються через схвалення exec. - Див. [Підтвердження exec](/uk/tools/exec-approvals). + Див. [Схвалення exec](/uk/tools/exec-approvals). ## Керування відповідями про помилки -Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити його. Цю поведінку контролюють два ключі конфігурації: +Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приглушити її. Цю поведінку контролюють два ключі конфігурації: -| Ключ | Значення | За замовчуванням | Опис | -| ----------------------------------- | ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. | +| Ключ | Значення | За замовчуванням | Опис | +| ----------------------------------- | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю приглушує відповіді про помилки. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. | -Підтримуються перевизначення для облікового запису, групи та теми (таке саме успадкування, як і для інших ключів конфігурації Telegram). +Підтримуються перевизначення для кожного облікового запису, групи й теми (таке саме успадкування, як і для інших ключів конфігурації Telegram). ```json5 { @@ -824,53 +825,53 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ } ``` -## Усунення несправностей +## Усунення неполадок - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - - потім видаліть і повторно додайте бота до групи + - потім видаліть і знову додайте бота до групи - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки. - - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство. - - швидкий тест сеансу: `/activation always`. + - `openclaw channels status --probe` може перевіряти явні числові ідентифікатори груп; wildcard `"*"` не можна перевірити на членство. + - швидкий тест сесії: `/activation always`. - - коли існує `channels.telegram.groups`, група має бути в списку (або включати `"*"`) + - коли існує `channels.telegram.groups`, група має бути вказана (або містити `"*"`) - перевірте членство бота в групі - перегляньте журнали: `openclaw logs --follow` для причин пропуску - + - - авторизуйте свою ідентичність відправника (сполучення та/або числовий `allowFrom`) - - авторизація команд усе ще застосовується, навіть коли політика групи — `open` - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато пунктів; зменште кількість команд plugin/skill/користувацьких команд або вимкніть нативні меню - - `setMyCommands failed` із помилками network/fetch зазвичай вказує на проблеми доступності DNS/HTTPS до `api.telegram.org` + - авторизуйте ідентичність відправника (pairing і/або числовий `allowFrom`) + - авторизація команд усе одно застосовується, навіть коли політика групи `open` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість команд Plugin/skill/custom або вимкніть нативні меню + - `setMyCommands failed` з помилками network/fetch зазвичай вказує на проблеми доступності DNS/HTTPS до `api.telegram.org` - + - - `getMe returned 401` — це збій автентифікації Telegram для налаштованого токена бота. - - Повторно скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для облікового запису за замовчуванням. - - `deleteWebhook 401 Unauthorized` під час запуску також є збоєм автентифікації; трактування цього як "webhook не існує" лише відклало б той самий збій через поганий токен до пізніших викликів API. + - `getMe returned 401` — це помилка автентифікації Telegram для налаштованого токена бота. + - Повторно скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для стандартного облікового запису. + - `deleteWebhook 401 Unauthorized` під час запуску також є помилкою автентифікації; трактування цього як "webhook не існує" лише відклало б ту саму помилку неправильного токена до наступних викликів API. - - Node 22+ + користувацький fetch/proxy може спричинити негайну поведінку abort, якщо типи AbortSignal не збігаються. - - Деякі хости спершу резолвлять `api.telegram.org` в IPv6; зламаний вихід IPv6 може спричиняти переривчасті збої Telegram API. + - Node 22+ + custom fetch/proxy може спричиняти негайну поведінку abort, якщо типи AbortSignal не збігаються. + - Деякі хости спершу розв’язують `api.telegram.org` в IPv6; зламаний вихідний IPv6 може спричиняти періодичні збої Telegram API. - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки. - - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зависання polling. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або виходу TLS між хостом і `api.telegram.org`. - - На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: + - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної liveness long-poll за замовчуванням. + - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе ще повідомляє про хибні перезапуски через зупинку polling. Постійні зупинки зазвичай вказують на проблеми proxy, DNS, IPv6 або вихідного TLS між хостом і `api.telegram.org`. + - На VPS-хостах із нестабільним прямим виходом/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: @@ -879,7 +880,7 @@ channels: ``` - Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`. - - Якщо ваш хост є WSL2 або явно працює краще з поведінкою лише IPv4, примусово задайте вибір сімейства: + - Якщо ваш хост є WSL2 або явно краще працює з поведінкою лише IPv4, примусово задайте вибір сімейства: ```yaml channels: @@ -890,9 +891,9 @@ channels: - Відповіді benchmark-діапазону RFC 2544 (`198.18.0.0/15`) уже дозволені для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або - прозорий proxy переписує `api.telegram.org` на іншу - приватну/внутрішню/спеціального призначення адресу під час завантажень медіа, ви можете увімкнути - обхід лише для Telegram: + transparent proxy переписує `api.telegram.org` на якусь іншу + приватну/внутрішню/спеціального використання адресу під час завантажень медіа, ви можете opt + in до обходу лише для Telegram: ```yaml channels: @@ -901,25 +902,25 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Такий самий opt-in доступний для кожного облікового запису за адресою + - Такий самий opt-in доступний для кожного облікового запису за `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Якщо ваш proxy резолвить хости медіа Telegram у `198.18.x.x`, спочатку залиште - небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє benchmark-діапазон - RFC 2544 за замовчуванням. + - Якщо ваш proxy розв’язує хости медіа Telegram у `198.18.x.x`, спершу залиште + небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє benchmark-діапазон RFC 2544 + за замовчуванням. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист медіа Telegram - від SSRF. Використовуйте це лише для довірених, контрольованих оператором proxy - середовищ, як-от маршрутизація fake-IP Clash, Mihomo або Surge, коли вони - синтезують приватні або спеціального призначення відповіді поза benchmark-діапазоном - RFC 2544. Залишайте вимкненим для звичайного публічного інтернет-доступу до Telegram. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захисти Telegram + media SSRF. Використовуйте це лише для довірених, контрольованих оператором proxy + середовищ, як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони + синтезують приватні або спеціального використання відповіді поза benchmark-діапазоном RFC 2544. + Залишайте вимкненим для звичайного публічного доступу Telegram через інтернет. - Перевизначення середовища (тимчасові): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - Перевірте відповіді DNS: + - Перевірте DNS-відповіді: ```bash dig +short api.telegram.org A @@ -929,24 +930,24 @@ dig +short api.telegram.org AAAA -Додаткова допомога: [Усунення проблем із каналами](/uk/channels/troubleshooting). +Додаткова довідка: [Усунення несправностей каналів](/uk/channels/troubleshooting). ## Довідник конфігурації Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). - + - запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символьні посилання відхиляються) - контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`) - підтвердження виконання: `execApprovals`, `accounts.*.execApprovals` - команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands` -- гілки/відповіді: `replyToMode` +- потоки обговорень/відповіді: `replyToMode` - потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- користувацький корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot`) -- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- користувацький корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot`) +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` - помилки: `errorPolicy`, `errorCooldownMs` @@ -955,7 +956,7 @@ dig +short api.telegram.org AAAA -Пріоритет кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб явно визначити маршрутизацію за замовчуванням. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає про це. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. +Пріоритетність кількох облікових записів: коли налаштовано два або більше ідентифікаторів облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб зробити маршрутизацію за замовчуванням явною. Інакше OpenClaw повертається до першого нормалізованого ідентифікатора облікового запису, а `openclaw doctor` видає попередження. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. ## Пов’язане @@ -968,7 +969,7 @@ dig +short api.telegram.org AAAA Поведінка списку дозволених груп і тем. - Маршрутизуйте вхідні повідомлення до агентів. + Маршрутизуйте вхідні повідомлення агентам. Модель загроз і посилення захисту. @@ -976,7 +977,7 @@ dig +short api.telegram.org AAAA Зіставляйте групи й теми з агентами. - - Міжканальна діагностика. + + Діагностика між каналами. diff --git a/docs/uk/cli/doctor.md b/docs/uk/cli/doctor.md index afeb0f052..4d49e0d77 100644 --- a/docs/uk/cli/doctor.md +++ b/docs/uk/cli/doctor.md @@ -1,14 +1,14 @@ --- read_when: - - У вас виникли проблеми з підключенням/автентифікацією, і ви хочете отримати покрокові вказівки з їх виправлення - - Ви оновили й хочете перевірити коректність + - У вас проблеми з підключенням або автентифікацією, і вам потрібні покрокові виправлення + - Ви оновилися й хочете базову перевірку summary: Довідник CLI для `openclaw doctor` (перевірки працездатності + керовані виправлення) title: Діагностика x-i18n: - generated_at: "2026-04-28T11:07:15Z" + generated_at: "2026-04-28T22:44:19Z" model: gpt-5.5 provider: openai - source_hash: 00110787b9320f84aa3b57ea8b85120d412a97779fbf1e3d8f11f78c87d37676 + source_hash: 9985c84d23861dd9468a4659ee00519573fe6d540c436548da0a68067dbabc4c source_path: cli/doctor.md workflow: 16 --- @@ -17,7 +17,7 @@ x-i18n: Перевірки стану + швидкі виправлення для Gateway і каналів. -Пов’язано: +Пов’язане: - Усунення несправностей: [Усунення несправностей](/uk/gateway/troubleshooting) - Аудит безпеки: [Безпека](/uk/gateway/security) @@ -34,38 +34,39 @@ openclaw doctor --generate-gateway-token ## Параметри -- `--no-workspace-suggestions`: вимкнути пропозиції пам’яті/пошуку робочого простору -- `--yes`: приймати значення за замовчуванням без запиту +- `--no-workspace-suggestions`: вимкнути пропозиції пам’яті/пошуку робочої області +- `--yes`: прийняти значення за замовчуванням без запиту - `--repair`: застосувати рекомендовані виправлення без запиту - `--fix`: псевдонім для `--repair` -- `--force`: застосувати агресивні виправлення, зокрема перезаписати власну конфігурацію служби за потреби +- `--force`: застосувати агресивні виправлення, зокрема перезапис користувацької конфігурації сервісу за потреби - `--non-interactive`: запуск без запитів; лише безпечні міграції - `--generate-gateway-token`: згенерувати й налаштувати токен Gateway -- `--deep`: сканувати системні служби на додаткові встановлення Gateway +- `--deep`: просканувати системні сервіси на наявність додаткових інсталяцій Gateway Примітки: -- Інтерактивні запити (наприклад, виправлення keychain/OAuth) виконуються лише тоді, коли stdin є TTY і `--non-interactive` **не** задано. Запуски без інтерфейсу (cron, Telegram, без термінала) пропускатимуть запити. -- Продуктивність: неінтерактивні запуски `doctor` пропускають завчасне завантаження plugin, щоб перевірки стану без інтерфейсу залишалися швидкими. Інтерактивні сеанси все одно повністю завантажують plugins, коли перевірці потрібен їхній внесок. -- `--fix` (псевдонім для `--repair`) записує резервну копію в `~/.openclaw/openclaw.json.bak` і видаляє невідомі ключі конфігурації, перелічуючи кожне видалення. -- Перевірки цілісності стану тепер виявляють осиротілі файли транскриптів у каталозі сеансів. Архівування їх як `.deleted.` потребує інтерактивного підтвердження; `--fix`, `--yes` і запуски без інтерфейсу залишають їх на місці. -- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на застарілі форми завдань cron і може переписати їх на місці до того, як планувальнику доведеться автоматично нормалізувати їх під час виконання. -- Doctor відновлює відсутні runtime-залежності вбудованих plugin, не записуючи їх у запаковані глобальні встановлення. Для root-owned npm-встановлень або посилених systemd units задайте `OPENCLAW_PLUGIN_STAGE_DIR` як каталог, доступний для запису, наприклад `/var/lib/openclaw/plugin-runtime-deps`; це також може бути список шляхів, наприклад `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`, де попередні корені є шарами пошуку лише для читання, а останній корінь є ціллю виправлення. -- Doctor відновлює застарілу конфігурацію plugin, видаляючи відсутні ідентифікатори plugin з `plugins.allow`/`plugins.entries`, а також відповідну осиротілу конфігурацію каналів, цілі heartbeat і перевизначення моделей каналів, коли виявлення plugin працює коректно. -- Doctor ізолює недійсну конфігурацію plugin, вимикаючи відповідний запис `plugins.entries.` і видаляючи його недійсне навантаження `config`. Запуск Gateway уже пропускає лише цей несправний plugin, тож інші plugins і канали можуть продовжувати роботу. -- Задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли життєвим циклом Gateway керує інший супервізор. Doctor і надалі повідомляє про стан Gateway/служби та застосовує виправлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби й очищення застарілих служб. -- У Linux doctor ігнорує неактивні додаткові systemd units, схожі на Gateway, і не переписує метадані команди/точки входу для запущеної systemd-служби Gateway під час виправлення. Спершу зупиніть службу або використайте `openclaw gateway install --force`, якщо ви навмисно хочете замінити активний launcher. -- Doctor автоматично мігрує застарілу плоску конфігурацію Talk (`talk.voiceId`, `talk.modelId` та пов’язані параметри) у `talk.provider` + `talk.providers.`. -- Повторні запуски `doctor --fix` більше не повідомляють і не застосовують нормалізацію Talk, коли єдина відмінність — порядок ключів об’єкта. -- Doctor включає перевірку готовності пошуку в пам’яті й може рекомендувати `openclaw configure --section model`, коли бракує облікових даних для embedding. -- Якщо режим sandbox увімкнено, але Docker недоступний, doctor повідомляє змістовне попередження зі способом усунення (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`). -- Якщо `gateway.auth.token`/`gateway.auth.password` керуються через SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання й не записує plaintext fallback credentials. -- Якщо перевірка SecretRef каналу не вдається на шляху виправлення, doctor продовжує роботу й повідомляє попередження замість дострокового завершення. -- Автоматичне розв’язання імен користувачів Telegram `allowFrom` (`doctor --fix`) потребує доступного для розв’язання токена Telegram у поточному шляху команди. Якщо перевірка токена недоступна, doctor повідомляє попередження й пропускає автоматичне розв’язання для цього проходу. +- Інтерактивні запити (наприклад, виправлення keychain/OAuth) запускаються лише тоді, коли stdin є TTY і `--non-interactive` **не** встановлено. Запуски без термінала (Cron, Telegram, без термінала) пропускатимуть запити. +- Продуктивність: неінтерактивні запуски `doctor` пропускають завчасне завантаження Plugin, щоб перевірки стану без термінала залишалися швидкими. Інтерактивні сеанси все одно повністю завантажують plugins, коли перевірці потрібній їхній внесок. +- `--fix` (псевдонім для `--repair`) записує резервну копію в `~/.openclaw/openclaw.json.bak` і відкидає невідомі ключі конфігурації, перелічуючи кожне видалення. +- Перевірки цілісності стану тепер виявляють осиротілі файли транскриптів у каталозі сеансів. Їх архівування як `.deleted.` потребує інтерактивного підтвердження; `--fix`, `--yes` і запуски без термінала залишають їх на місці. +- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на застарілі форми завдань Cron і може переписати їх на місці до того, як планувальнику доведеться автоматично нормалізувати їх під час виконання. +- Doctor виправляє відсутні runtime-залежності bundled plugin без запису в пакетні глобальні інсталяції. Для npm-інсталяцій, що належать root, або посилених systemd-юнітів встановіть `OPENCLAW_PLUGIN_STAGE_DIR` на доступний для запису каталог, як-от `/var/lib/openclaw/plugin-runtime-deps`; це також може бути список шляхів, наприклад `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`, де попередні корені є шарами пошуку лише для читання, а фінальний корінь є ціллю виправлення. +- Doctor виправляє застарілу конфігурацію plugin, видаляючи відсутні plugin ids з `plugins.allow`/`plugins.entries`, а також відповідну завислу конфігурацію каналів, цілі Heartbeat і перевизначення моделей каналів, коли виявлення plugin працює коректно. +- Doctor поміщає недійсну конфігурацію plugin у карантин, вимикаючи відповідний запис `plugins.entries.` і видаляючи його недійсний payload `config`. Запуск Gateway уже пропускає лише цей проблемний plugin, тож інші plugins і канали можуть продовжувати працювати. +- Встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли інший supervisor керує життєвим циклом Gateway. Doctor усе одно повідомляє про стан Gateway/сервісу й застосовує виправлення, не пов’язані із сервісом, але пропускає install/start/restart/bootstrap сервісу та очищення застарілих сервісів. +- У Linux doctor ігнорує неактивні додаткові systemd-юніти, схожі на Gateway, і не переписує метадані команди/entrypoint для запущеного systemd-сервісу Gateway під час виправлення. Спершу зупиніть сервіс або використайте `openclaw gateway install --force`, якщо навмисно хочете замінити активний launcher. +- Doctor автоматично мігрує застарілу плоску конфігурацію Talk (`talk.voiceId`, `talk.modelId` і пов’язані ключі) у `talk.provider` + `talk.providers.`. +- Повторні запуски `doctor --fix` більше не повідомляють/застосовують нормалізацію Talk, коли єдина відмінність — порядок ключів об’єкта. +- Doctor містить перевірку готовності пошуку в пам’яті та може рекомендувати `openclaw configure --section model`, коли відсутні облікові дані embeddings. +- Doctor попереджає, коли не налаштовано власника команд. Власник команд — це обліковий запис оператора-людини, якому дозволено запускати команди лише для власника й схвалювати небезпечні дії. Спарювання DM лише дозволяє комусь спілкуватися з ботом; якщо ви схвалили відправника до появи bootstrap першого власника, явно встановіть `commands.ownerAllowFrom`. +- Якщо режим пісочниці ввімкнено, але Docker недоступний, doctor повідомляє змістовне попередження з варіантом усунення (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`). +- Якщо `gateway.auth.token`/`gateway.auth.password` керуються SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання й не записує резервні облікові дані відкритим текстом. +- Якщо перевірка SecretRef каналу завершується невдало в шляху виправлення, doctor продовжує роботу й повідомляє попередження замість раннього завершення. +- Автоматичне визначення імен користувачів Telegram `allowFrom` (`doctor --fix`) потребує доступного для розв’язання токена Telegram у поточному шляху команди. Якщо перевірка токена недоступна, doctor повідомляє попередження й пропускає автоматичне визначення для цього проходу. -## macOS: перевизначення змінних середовища `launchctl` +## macOS: перевизначення env `launchctl` -Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш конфігураційний файл і може спричиняти постійні помилки “unauthorized”. +Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації та може спричиняти постійні помилки «unauthorized». ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN @@ -75,7 +76,7 @@ launchctl unsetenv OPENCLAW_GATEWAY_TOKEN launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ``` -## Пов’язано +## Пов’язане - [Довідник CLI](/uk/cli) -- [Gateway doctor](/uk/gateway/doctor) +- [Діагностика Gateway](/uk/gateway/doctor) diff --git a/docs/uk/cli/pairing.md b/docs/uk/cli/pairing.md index 7352031aa..b7afcd0b9 100644 --- a/docs/uk/cli/pairing.md +++ b/docs/uk/cli/pairing.md @@ -1,24 +1,24 @@ --- read_when: - - Ви використовуєте приватні повідомлення в режимі сполучення й вам потрібно підтверджувати відправників -summary: Довідник CLI для `openclaw pairing` (підтвердження/перегляд запитів на сполучення) + - Ви використовуєте приватні повідомлення в режимі сполучення й маєте схвалити відправників +summary: Довідник CLI для `openclaw pairing` (схвалення/перегляд списку запитів на сполучення) title: Сполучення x-i18n: - generated_at: "2026-04-24T03:15:51Z" - model: gpt-5.4 + generated_at: "2026-04-28T22:44:15Z" + model: gpt-5.5 provider: openai - source_hash: 9e81dc407138e958e41d565b0addb600ad1ba5187627bb219f0b85b92bd112d1 + source_hash: bffc70a8c08e298f42c8fbc2238fce06993572e72f333e87ad18dea3cf33fab5 source_path: cli/pairing.md - workflow: 15 + workflow: 16 --- # `openclaw pairing` -Підтверджуйте або переглядайте запити на сполучення в приватних повідомленнях (для каналів, які підтримують сполучення). +Схвалюйте або переглядайте запити на прив'язування в DM (для каналів, що підтримують прив'язування). -Пов’язано: +Пов'язане: -- Потік сполучення: [Сполучення](/uk/channels/pairing) +- Потік прив'язування: [Прив'язування](/uk/channels/pairing) ## Команди @@ -34,44 +34,51 @@ openclaw pairing approve --channel telegram --account work --notify ## `pairing list` -Показати список очікуваних запитів на сполучення для одного каналу. +Перелічує очікувані запити на прив'язування для одного каналу. Параметри: -- `[channel]`: позиційний id каналу -- `--channel `: явний id каналу -- `--account `: id облікового запису для каналів із кількома обліковими записами -- `--json`: машиночитний вивід +- `[channel]`: позиційний ідентифікатор каналу +- `--channel `: явний ідентифікатор каналу +- `--account `: ідентифікатор облікового запису для каналів із кількома обліковими записами +- `--json`: машинозчитуваний вивід Примітки: -- Якщо налаштовано кілька каналів, що підтримують сполучення, потрібно вказати канал або позиційно, або через `--channel`. -- Канали розширень дозволені, якщо id каналу є дійсним. +- Якщо налаштовано кілька каналів із підтримкою прив'язування, потрібно вказати канал позиційно або через `--channel`. +- Канали Plugin дозволені, якщо ідентифікатор каналу чинний. ## `pairing approve` -Підтвердити очікуваний код сполучення й дозволити цього відправника. +Схвалює очікуваний код прив'язування та дозволяє цього відправника. Використання: - `openclaw pairing approve ` - `openclaw pairing approve --channel ` -- `openclaw pairing approve `, якщо налаштовано рівно один канал, що підтримує сполучення +- `openclaw pairing approve `, коли налаштовано рівно один канал із підтримкою прив'язування Параметри: -- `--channel `: явний id каналу -- `--account `: id облікового запису для каналів із кількома обліковими записами -- `--notify`: надіслати підтвердження у відповідь запитувачу в тому самому каналі +- `--channel `: явний ідентифікатор каналу +- `--account `: ідентифікатор облікового запису для каналів із кількома обліковими записами +- `--notify`: надіслати підтвердження запитувачу в тому самому каналі + +Початкове налаштування власника: + +- Якщо `commands.ownerAllowFrom` порожній, коли ви схвалюєте код прив'язування, OpenClaw також записує схваленого відправника як власника команд, використовуючи запис у межах каналу, наприклад `telegram:123456789`. +- Це виконує початкове налаштування лише першого власника. Подальші схвалення прив'язування не замінюють і не розширюють `commands.ownerAllowFrom`. +- Власник команд — це обліковий запис людини-оператора, якій дозволено запускати команди лише для власника та схвалювати небезпечні дії, як-от `/diagnostics`, `/export-trajectory`, `/config` і схвалення exec. ## Примітки -- Вхідне значення каналу: передавайте його позиційно (`pairing list telegram`) або через `--channel `. +- Ввід каналу: передайте його позиційно (`pairing list telegram`) або через `--channel `. - `pairing list` підтримує `--account ` для каналів із кількома обліковими записами. - `pairing approve` підтримує `--account ` і `--notify`. -- Якщо налаштовано лише один канал, що підтримує сполучення, дозволено `pairing approve `. +- Якщо налаштовано лише один канал із підтримкою прив'язування, дозволено `pairing approve `. +- Якщо ви схвалили відправника до появи цього початкового налаштування, запустіть `openclaw doctor`; він попередить, коли власника команд не налаштовано, і покаже команду `openclaw config set commands.ownerAllowFrom ...`, щоб це виправити. -## Пов’язано +## Пов'язане - [Довідник CLI](/uk/cli) -- [Сполучення каналу](/uk/channels/pairing) +- [Прив'язування каналу](/uk/channels/pairing) diff --git a/docs/uk/cli/sessions.md b/docs/uk/cli/sessions.md index da3571f86..c8c8167d4 100644 --- a/docs/uk/cli/sessions.md +++ b/docs/uk/cli/sessions.md @@ -1,20 +1,20 @@ --- read_when: - - Ви хочете переглянути список збережених сеансів і недавню активність -summary: Довідка CLI для `openclaw sessions` (перелік збережених сеансів + використання) + - Ви хочете переглянути список збережених сеансів і побачити нещодавню активність +summary: Довідник CLI для `openclaw sessions` (список збережених сеансів + використання) title: Сеанси x-i18n: - generated_at: "2026-04-27T20:08:42Z" - model: gpt-5.4 + generated_at: "2026-04-28T22:44:10Z" + model: gpt-5.5 provider: openai - source_hash: 77bf1cdc5cb1688889ec5155241ed98a2c62204c56e727a1174c593a79c78ca8 + source_hash: 9fea2014f538b00a27fa0078391a421843052333c5bcfc8100fced515eed0004 source_path: cli/sessions.md - workflow: 15 + workflow: 16 --- # `openclaw sessions` -Перелічує збережені сеанси розмов. +Перелічує збережені сесії розмов. ```bash openclaw sessions @@ -27,18 +27,28 @@ openclaw sessions --json Вибір області: -- за замовчуванням: сховище агента, налаштоване за замовчуванням +- типово: налаштоване стандартне сховище агента - `--verbose`: докладне журналювання - `--agent `: одне налаштоване сховище агента -- `--all-agents`: агрегує всі налаштовані сховища агентів +- `--all-agents`: об'єднати всі налаштовані сховища агентів - `--store `: явний шлях до сховища (не можна поєднувати з `--agent` або `--all-agents`) -`openclaw sessions --all-agents` читає налаштовані сховища агентів. Виявлення -сеансів Gateway і ACP має ширше охоплення: воно також включає сховища, знайдені -лише на диску, у стандартному корені `agents/` або в корені `session.store`, -заданому шаблоном. Ці виявлені сховища мають відповідати звичайним файлам -`sessions.json` усередині кореня агента; символічні посилання та шляхи поза -коренем пропускаються. +Експортувати пакет траєкторії для збереженої сесії: + +```bash +openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace . +openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json +``` + +Це шлях команди, який використовується slash-командою `/export-trajectory` після того, +як власник схвалює запит на виконання. Вихідний каталог завжди визначається +всередині `.openclaw/trajectory-exports/` у вибраному робочому просторі. + +`openclaw sessions --all-agents` читає налаштовані сховища агентів. Виявлення сесій Gateway і ACP +ширше: воно також включає сховища лише на диску, знайдені під +стандартним коренем `agents/` або шаблонним коренем `session.store`. Ці +виявлені сховища мають визначатися як звичайні файли `sessions.json` всередині +кореня агента; символьні посилання та шляхи поза коренем пропускаються. Приклади JSON: @@ -63,7 +73,7 @@ openclaw sessions --json ## Обслуговування очищення -Запустіть обслуговування зараз (замість очікування наступного циклу запису): +Запустити обслуговування зараз (замість очікування наступного циклу запису): ```bash openclaw sessions cleanup --dry-run @@ -76,17 +86,17 @@ openclaw sessions cleanup --json `openclaw sessions cleanup` використовує налаштування `session.maintenance` з конфігурації: -- Примітка щодо області дії: `openclaw sessions cleanup` обслуговує сховища сеансів, стенограми та побічні файли траєкторій. Воно не обрізає журнали запусків Cron (`cron/runs/.jsonl`), якими керують `cron.runLog.maxBytes` і `cron.runLog.keepLines` у [конфігурації Cron](/uk/automation/cron-jobs#configuration), а також які описані в [обслуговуванні Cron](/uk/automation/cron-jobs#maintenance). +- Примітка щодо області: `openclaw sessions cleanup` обслуговує сховища сесій, транскрипти та супровідні файли траєкторій. Вона не обрізає журнали запусків Cron (`cron/runs/.jsonl`), якими керують `cron.runLog.maxBytes` і `cron.runLog.keepLines` у [конфігурації Cron](/uk/automation/cron-jobs#configuration) та які пояснено в [обслуговуванні Cron](/uk/automation/cron-jobs#maintenance). -- `--dry-run`: попередньо показує, скільки записів буде вилучено/обмежено без запису. - - У текстовому режимі dry-run виводить таблицю дій по сеансах (`Action`, `Key`, `Age`, `Model`, `Flags`), щоб ви могли побачити, що буде збережено, а що видалено. -- `--enforce`: застосовує обслуговування, навіть коли `session.maintenance.mode` має значення `warn`. -- `--fix-missing`: видаляє записи, у яких відсутні файли стенограм, навіть якщо вони зазвичай ще не підлягали б видаленню за віком/кількістю. -- `--active-key `: захищає конкретний активний ключ від витіснення через обмеження дискового бюджету. -- `--agent `: запускає очищення для одного налаштованого сховища агента. -- `--all-agents`: запускає очищення для всіх налаштованих сховищ агентів. -- `--store `: запускає очищення для конкретного файла `sessions.json`. -- `--json`: виводить підсумок у форматі JSON. Із `--all-agents` вивід містить по одному підсумку для кожного сховища. +- `--dry-run`: попередньо показати, скільки записів було б очищено/обмежено без запису. + - У текстовому режимі dry-run друкує таблицю дій для кожної сесії (`Action`, `Key`, `Age`, `Model`, `Flags`), щоб було видно, що буде збережено, а що видалено. +- `--enforce`: застосувати обслуговування, навіть коли `session.maintenance.mode` має значення `warn`. +- `--fix-missing`: видалити записи, чиї файли транскриптів відсутні, навіть якщо зазвичай вони ще не підпали б під обмеження віку/кількості. +- `--active-key `: захистити певний активний ключ від витіснення через дисковий бюджет. +- `--agent `: запустити очищення для одного налаштованого сховища агента. +- `--all-agents`: запустити очищення для всіх налаштованих сховищ агентів. +- `--store `: виконати для певного файла `sessions.json`. +- `--json`: надрукувати зведення JSON. З `--all-agents` вивід містить одне зведення для кожного сховища. `openclaw sessions cleanup --all-agents --dry-run --json`: @@ -116,11 +126,11 @@ openclaw sessions cleanup --json } ``` -Пов’язане: +Пов'язано: -- Конфігурація сеансів: [Довідник із конфігурації](/uk/gateway/config-agents#session) +- Конфігурація сесій: [довідник конфігурації](/uk/gateway/config-agents#session) -## Пов’язане +## Пов'язано -- [Довідка CLI](/uk/cli) -- [Керування сеансами](/uk/concepts/session) +- [Довідник CLI](/uk/cli) +- [Керування сесіями](/uk/concepts/session) diff --git a/docs/uk/gateway/diagnostics.md b/docs/uk/gateway/diagnostics.md index e170b94b2..19f5a863f 100644 --- a/docs/uk/gateway/diagnostics.md +++ b/docs/uk/gateway/diagnostics.md @@ -1,23 +1,26 @@ --- read_when: - Підготовка звіту про помилку або запиту до служби підтримки - - Налагодження збоїв Gateway, перезапусків, тиску на пам’ять або завеликих корисних навантажень - - Перегляд того, які діагностичні дані записуються або маскуються -summary: Створюйте пакети діагностики Gateway для звітів про помилки, якими можна поділитися -title: Експорт діагностики + - Налагодження збоїв Gateway, перезапусків, нестачі пам’яті або завеликих корисних навантажень + - Перегляд того, які діагностичні дані записуються або приховуються +summary: Створення придатних для поширення діагностичних пакетів Gateway для звітів про помилки +title: Експорт діагностичних даних x-i18n: - generated_at: "2026-04-28T11:11:23Z" + generated_at: "2026-04-28T22:44:31Z" model: gpt-5.5 provider: openai - source_hash: eca1381cfd603eb659a24cd92f2f79a7ed6a8aaf7f451d3662713e0be0ee637e + source_hash: e66f1391da77e531b5d3b0ed19600da222d80960d1b6e54d51925c04b06dae46 source_path: gateway/diagnostics.md workflow: 16 --- -OpenClaw може створити локальний zip-архів діагностики, який безпечно -додавати до звітів про помилки. Він об’єднує санітизовані статус Gateway, -стан здоров’я, журнали, форму конфігурації та нещодавні події стабільності без -payload. +OpenClaw може створити локальний zip-архів діагностики для звітів про помилки. Він об’єднує +очищені статус Gateway, стан працездатності, журнали, форму конфігурації та нещодавні події +стабільності без payload. + +Ставтеся до діагностичних пакетів як до секретів, доки не переглянете їх. Вони +спроєктовані так, щоб пропускати або редагувати payload і облікові дані, але все одно узагальнюють +локальні журнали Gateway та стан середовища виконання на рівні хоста. ## Швидкий старт @@ -25,7 +28,7 @@ payload. openclaw gateway diagnostics export ``` -Команда виводить шлях записаного zip-архіву. Щоб вибрати шлях: +Команда виводить шлях до записаного zip-архіву. Щоб вибрати шлях: ```bash openclaw gateway diagnostics export --output openclaw-diagnostics.zip @@ -37,39 +40,78 @@ openclaw gateway diagnostics export --output openclaw-diagnostics.zip openclaw gateway diagnostics export --json ``` +## Команда чату + +Власники можуть використовувати `/diagnostics [note]` у чаті, щоб запросити локальний експорт Gateway. +Використовуйте це, коли помилка сталася в реальній розмові й вам потрібен один +звіт для підтримки, який можна скопіювати й вставити: + +1. Надішліть `/diagnostics` у розмові, де ви помітили проблему. Додайте + коротку примітку, якщо це допоможе, наприклад `/diagnostics bad tool choice`. +2. OpenClaw надсилає вступ до діагностики та просить одне явне підтвердження exec. + Підтвердження запускає `openclaw gateway diagnostics export --json`. + Не підтверджуйте діагностику через правило allow-all. +3. Після підтвердження OpenClaw відповідає звітом для вставлення, який містить локальний + шлях до пакета, зведення маніфесту, примітки щодо приватності та відповідні ідентифікатори сесій. + +У групових чатах власник усе ще може запустити `/diagnostics`, але OpenClaw не +публікує діагностичні деталі назад у спільний чат. Він надсилає вступ, +запити підтвердження, результат експорту Gateway та розбивку сесії/потоку Codex +власнику через приватний маршрут підтвердження. Група отримує лише коротке повідомлення +про те, що діагностичний процес було надіслано приватно. Якщо OpenClaw не може знайти приватний +маршрут до власника, команда закривається без виконання й просить власника запустити її з DM. + +Коли активна сесія OpenClaw використовує нативний harness OpenAI Codex, +те саме підтвердження exec також охоплює завантаження відгуку OpenAI для потоків +середовища виконання Codex, про які знає OpenClaw. Це завантаження відокремлене від локального +zip-архіву Gateway і з’являється лише для сесій harness Codex. Перед підтвердженням +запит пояснює, що підтвердження діагностики також надішле відгук Codex, але +не перелічує ідентифікатори сесій або потоків Codex. Після підтвердження відповідь у чаті перелічує +канали, ідентифікатори сесій OpenClaw, ідентифікатори потоків Codex і локальні команди відновлення +для потоків, надісланих на сервери OpenAI. Якщо ви відхилите або проігноруєте +підтвердження, OpenClaw не запускає експорт, не надсилає відгук Codex і +не друкує ідентифікатори Codex. + +Це робить типовий цикл налагодження Codex коротким: помітьте неправильну поведінку в +Telegram, Discord або іншому каналі, запустіть `/diagnostics`, підтвердьте один раз, поділіться +звітом із підтримкою, а потім запустіть надруковану команду `codex resume ` +локально, якщо хочете самостійно переглянути нативний потік Codex. Див. +[harness Codex](/uk/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) для +цього процесу перегляду. + ## Що містить експорт Zip-архів містить: -- `summary.md`: зручний для читання огляд для служби підтримки. -- `diagnostics.json`: машинозчитуваний підсумок конфігурації, журналів, статусу, стану здоров’я +- `summary.md`: зрозумілий для людини огляд для підтримки. +- `diagnostics.json`: машинозчитуване зведення конфігурації, журналів, статусу, стану працездатності та даних стабільності. - `manifest.json`: метадані експорту та список файлів. -- Санітизовану форму конфігурації та несекретні деталі конфігурації. -- Санітизовані підсумки журналів і нещодавні відредаговані рядки журналів. -- Найкращі можливі знімки статусу та стану здоров’я Gateway. +- Очищену форму конфігурації та несекретні деталі конфігурації. +- Очищені зведення журналів і нещодавні відредаговані рядки журналів. +- Найкращі можливі знімки статусу та стану працездатності Gateway. - `stability/latest.json`: найновіший збережений пакет стабільності, якщо доступний. -Експорт корисний навіть тоді, коли Gateway несправний. Якщо Gateway не може -відповісти на запити статусу або стану здоров’я, локальні журнали, форма конфігурації та найновіший -пакет стабільності все одно збираються, якщо доступні. +Експорт корисний навіть тоді, коли Gateway нездоровий. Якщо Gateway не може +відповісти на запити статусу або стану працездатності, локальні журнали, форма конфігурації та найновіший +пакет стабільності все одно збираються, коли доступні. ## Модель приватності -Діагностика спроєктована так, щоб нею можна було ділитися. Експорт зберігає операційні дані, -які допомагають у налагодженні, зокрема: +Діагностику спроєктовано так, щоб нею можна було ділитися. Експорт зберігає операційні дані, +які допомагають налагодженню, як-от: -- назви підсистем, ідентифікатори Plugin, ідентифікатори провайдерів, ідентифікатори каналів і налаштовані режими +- назви підсистем, ідентифікатори plugin, ідентифікатори провайдерів, ідентифікатори каналів і налаштовані режими - коди статусу, тривалості, кількість байтів, стан черги та показники пам’яті -- санітизовані метадані журналів і відредаговані операційні повідомлення +- очищені метадані журналів і відредаговані операційні повідомлення - форму конфігурації та несекретні налаштування функцій Експорт пропускає або редагує: -- текст чатів, промпти, інструкції, тіла Webhook і результати інструментів +- текст чату, промпти, інструкції, тіла Webhook і результати інструментів - облікові дані, API-ключі, токени, cookies і секретні значення -- необроблені тіла запитів або відповідей -- ідентифікатори облікових записів, ідентифікатори повідомлень, необроблені ідентифікатори сеансів, імена хостів і локальні імена користувачів +- сирі тіла запитів або відповідей +- ідентифікатори облікових записів, ідентифікатори повідомлень, сирі ідентифікатори сесій, імена хостів і локальні імена користувачів Коли повідомлення журналу схоже на текст користувача, чату, промпта або payload інструмента, експорт зберігає лише факт пропуску повідомлення та кількість байтів. @@ -79,13 +121,13 @@ Zip-архів містить: Gateway за замовчуванням записує обмежений потік стабільності без payload, коли діагностику ввімкнено. Він призначений для операційних фактів, а не для вмісту. -Той самий діагностичний Heartbeat записує попередження про живучість, коли Gateway продовжує +Той самий діагностичний Heartbeat записує попередження про живість, коли Gateway продовжує працювати, але цикл подій Node.js або CPU виглядає перевантаженим. Ці події `diagnostic.liveness.warning` містять затримку циклу подій, використання циклу подій, -співвідношення ядер CPU, а також кількість активних/очікувальних/поставлених у чергу сеансів. Вони -не перезапускають Gateway самі по собі. +співвідношення CPU-core, а також кількість активних/очікувальних/поставлених у чергу сесій. Вони +самі по собі не перезапускають Gateway. -Перегляньте живий реєстратор: +Перегляньте активний реєстратор: ```bash openclaw gateway stability @@ -93,7 +135,7 @@ openclaw gateway stability --type payload.large openclaw gateway stability --json ``` -Перегляньте найновіший збережений пакет стабільності після фатального виходу, тайм-ауту +Перегляньте найновіший збережений пакет стабільності після фатального завершення, таймауту завершення роботи або помилки запуску після перезапуску: ```bash @@ -106,9 +148,9 @@ openclaw gateway stability --bundle latest openclaw gateway stability --bundle latest --export ``` -Збережені пакети містяться в `~/.openclaw/logs/stability/`, коли існують події. +Збережені пакети розміщуються в `~/.openclaw/logs/stability/`, коли події існують. -## Корисні параметри +## Корисні опції ```bash openclaw gateway diagnostics export \ @@ -118,19 +160,19 @@ openclaw gateway diagnostics export \ ``` - `--output `: записати до конкретного шляху zip-архіву. -- `--log-lines `: максимальна кількість санітизованих рядків журналу для включення. +- `--log-lines `: максимальна кількість очищених рядків журналу для включення. - `--log-bytes `: максимальна кількість байтів журналу для перевірки. -- `--url `: WebSocket URL Gateway для знімків статусу та стану здоров’я. -- `--token `: токен Gateway для знімків статусу та стану здоров’я. -- `--password `: пароль Gateway для знімків статусу та стану здоров’я. -- `--timeout `: тайм-аут знімків статусу та стану здоров’я. +- `--url `: URL WebSocket Gateway для знімків статусу та стану працездатності. +- `--token `: токен Gateway для знімків статусу та стану працездатності. +- `--password `: пароль Gateway для знімків статусу та стану працездатності. +- `--timeout `: таймаут знімка статусу та стану працездатності. - `--no-stability-bundle`: пропустити пошук збереженого пакета стабільності. -- `--json`: вивести машинозчитувані метадані експорту. +- `--json`: надрукувати машинозчитувані метадані експорту. ## Вимкнення діагностики Діагностику ввімкнено за замовчуванням. Щоб вимкнути реєстратор стабільності та -збирання діагностичних подій: +збір діагностичних подій: ```json5 { @@ -145,8 +187,8 @@ openclaw gateway diagnostics export \ ## Пов’язане -- [Перевірки стану здоров’я](/uk/gateway/health) +- [Перевірки стану працездатності](/uk/gateway/health) - [CLI Gateway](/uk/cli/gateway#gateway-diagnostics-export) - [Протокол Gateway](/uk/gateway/protocol#system-and-identity) - [Журналювання](/uk/logging) -- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — окремий потік для передавання діагностики до збирача +- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — окремий процес для потокової діагностики до колектора diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index 3b58e18ee..ed11b9d2a 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,195 +1,203 @@ --- read_when: - - Ви хочете використовувати комплектний app-server harness Codex - - Вам потрібні приклади конфігурації harness Codex - - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до Pi -summary: Запускайте вбудовані ходи агента OpenClaw через комплектний app-server harness Codex -title: harness Codex + - Ви хочете використовувати вбудований каркас сервера застосунку Codex + - Вам потрібні приклади конфігурації середовища Codex + - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою, а не переходили на PI як резервний варіант +summary: Запускайте ходи вбудованого агента OpenClaw через комплектний каркас app-server Codex +title: Середовище Codex x-i18n: - generated_at: "2026-04-28T00:34:04Z" - model: gpt-5.4 + generated_at: "2026-04-28T22:44:36Z" + model: gpt-5.5 provider: openai - source_hash: 4275f06cfaba2cc1f3f03204993c5c8678939979f734aca08b8053bbc14d7d8f + source_hash: ab5e03f02121aee4fd328382dfdfd9bfce6a87158758a25b980e7208b22855bd source_path: plugins/codex-harness.md - workflow: 15 + workflow: 16 --- -Комплектний Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через Codex app-server замість вбудованого harness Pi. +Пакетний Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через +app-server Codex замість вбудованого harness PI. -Використовуйте це, коли ви хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативною Compaction і виконанням через app-server. -OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами, погодженнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: +виявленням моделей, нативним відновленням гілки, нативним Compaction і виконанням +app-server. OpenClaw і надалі керує каналами чату, файлами сесій, вибором моделі, +інструментами, схваленнями, доставленням медіа та видимим дзеркалом стенограми. -Якщо ви намагаєтеся зорієнтуватися, почніть із -[Середовища виконання агентів](/uk/concepts/agent-runtimes). Коротка версія така: -`openai/gpt-5.5` — це посилання на модель, `codex` — це середовище виконання, а Telegram, -Discord, Slack або інший канал залишається поверхнею комунікації. +Якщо ви намагаєтеся зорієнтуватися, почніть з +[Середовища виконання агентів](/uk/concepts/agent-runtimes). Коротка версія: +`openai/gpt-5.5` — це ref моделі, `codex` — runtime, а Telegram, +Discord, Slack або інший канал лишається поверхнею комунікації. ## Що змінює цей Plugin -Комплектний Plugin `codex` додає кілька окремих можливостей: +Пакетний Plugin `codex` додає кілька окремих можливостей: -| Можливість | Як це використовувати | Що це робить | -| ------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- | -| Нативне вбудоване середовище виконання | `agentRuntime.id: "codex"` | Запускає вбудовані ходи агента OpenClaw через Codex app-server. | -| Нативні команди керування чатом | `/codex bind`, `/codex resume`, `/codex steer`, ... | Прив’язує та керує потоками Codex app-server із розмови в месенджері. | -| Провайдер/каталог Codex app-server | внутрішні компоненти `codex`, доступні через harness | Дає середовищу виконання змогу виявляти та перевіряти моделі app-server. | -| Шлях розуміння медіа в Codex | шляхи сумісності моделей зображень `codex/*` | Запускає обмежені ходи Codex app-server для підтримуваних моделей розуміння зображень. | -| Нативна ретрансляція hook | hooks Plugin навколо нативних подій Codex | Дає OpenClaw змогу спостерігати/блокувати підтримувані нативні події інструментів/завершення Codex. | +| Можливість | Як її використовувати | Що вона робить | +| -------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | +| Нативний вбудований runtime | `agentRuntime.id: "codex"` | Запускає вбудовані ходи агента OpenClaw через app-server Codex. | +| Нативні команди керування чатом | `/codex bind`, `/codex resume`, `/codex steer`, ... | Прив’язує гілки app-server Codex до розмови в месенджері та керує ними. | +| Провайдер/каталог app-server Codex | внутрішні механізми `codex`, доступні через harness | Дає runtime змогу виявляти й перевіряти моделі app-server. | +| Шлях розуміння медіа Codex | шляхи сумісності моделей зображень `codex/*` | Запускає обмежені ходи app-server Codex для підтримуваних моделей розуміння зображень. | +| Нативний ретранслятор хуків | хуки Plugin навколо нативних подій Codex | Дає OpenClaw змогу спостерігати за підтримуваними нативними подіями інструментів/фіналізації Codex або блокувати їх. | Увімкнення Plugin робить ці можливості доступними. Воно **не**: -- не починає використовувати Codex для кожної моделі OpenAI -- не перетворює посилання на моделі `openai-codex/*` на нативне середовище виконання -- не робить ACP/acpx типовим шляхом Codex -- не перемикає на льоту наявні сесії, у яких уже зафіксоване середовище виконання Pi -- не замінює доставку каналів OpenClaw, файли сесій, сховище auth profile або +- починає використовувати Codex для кожної моделі OpenAI +- перетворює refs моделей `openai-codex/*` на нативний runtime +- робить ACP/acpx типовим шляхом Codex +- гаряче перемикає наявні сесії, які вже записали runtime PI +- замінює доставлення каналів OpenClaw, файли сесій, зберігання auth-profile або маршрутизацію повідомлень -Той самий Plugin також володіє нативною поверхнею команд керування чатом `/codex`. Якщо -Plugin увімкнений і користувач просить прив’язати, відновити, спрямувати, зупинити або перевірити -потоки Codex із чату, агенти мають віддавати перевагу `/codex ...`, а не ACP. ACP залишається -явним резервним варіантом, коли користувач просить ACP/acpx або тестує адаптер ACP +Той самий Plugin також відповідає за нативну поверхню команд керування чатом `/codex`. Якщо +Plugin увімкнено й користувач просить прив’язати, відновити, спрямувати, зупинити або перевірити +гілки Codex із чату, агенти мають віддавати перевагу `/codex ...` над ACP. ACP лишається +явним fallback, коли користувач просить ACP/acpx або тестує адаптер ACP Codex. -Нативні ходи Codex зберігають hooks Plugin OpenClaw як публічний рівень сумісності. -Це внутрішньопроцесні hooks OpenClaw, а не командні hooks Codex `hooks.json`: +Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності. +Це in-process хуки OpenClaw, а не командні хуки Codex `hooks.json`: - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` -- `before_message_write` для дзеркальних записів транскрипту -- `before_agent_finalize` через ретрансляцію Codex `Stop` +- `before_message_write` для дзеркальних записів стенограми +- `before_agent_finalize` через ретранслятор `Stop` Codex - `agent_end` -Plugins також можуть реєструвати нейтральне до середовища виконання middleware результатів інструментів, щоб переписувати динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, як результат буде повернуто в Codex. Це окремо від публічного hook Plugin -`tool_result_persist`, який перетворює записи результатів інструментів у транскрипті, якими володіє OpenClaw. +Plugins також можуть реєструвати runtime-нейтральне middleware результатів інструментів, щоб переписувати +динамічні результати інструментів OpenClaw після виконання інструмента OpenClaw і перед тим, як +результат повертається до Codex. Це окремо від публічного +хука Plugin `tool_result_persist`, який трансформує записи результатів інструментів у стенограмі, +що належать OpenClaw. -Про саму семантику hooks Plugin див. [Hooks Plugin](/uk/plugins/hooks) +Семантику самих хуків Plugin див. у [Хуки Plugin](/uk/plugins/hooks) і [Поведінка guard Plugin](/uk/tools/plugin). -За замовчуванням harness вимкнено. У нових конфігураціях слід зберігати посилання на моделі OpenAI +Harness типово вимкнено. Нові конфіги мають зберігати refs моделей OpenAI канонічними як `openai/gpt-*` і явно примусово задавати -`agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли -потрібне нативне виконання через app-server. Застарілі посилання на моделі `codex/*`, як і раніше, автоматично вибирають -harness для сумісності, але застарілі префікси провайдера, підтримані середовищем виконання, +`agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли їм +потрібне нативне виконання app-server. Застарілі refs моделей `codex/*` усе ще автоматично вибирають +harness для сумісності, але runtime-backed застарілі префікси провайдерів не показуються як звичайні варіанти моделі/провайдера. -Якщо Plugin `codex` увімкнений, але основна модель усе ще -`openai-codex/*`, `openclaw doctor` показує попередження замість зміни маршруту. Це -зроблено навмисно: `openai-codex/*` залишається шляхом OAuth/підписки PI Codex, а -нативне виконання через app-server залишається явним вибором середовища виконання. +Якщо Plugin `codex` увімкнено, але основна модель усе ще +`openai-codex/*`, `openclaw doctor` попереджає замість того, щоб змінювати маршрут. Це +навмисно: `openai-codex/*` лишається шляхом OAuth/підписки Codex через PI, а +нативне виконання app-server лишається явним вибором runtime. ## Мапа маршрутів -Використовуйте цю таблицю перед зміною конфігурації: +Скористайтеся цією таблицею перед зміною конфігу: -| Бажана поведінка | Посилання на модель | Конфігурація середовища виконання | Вимога до Plugin | Очікувана мітка стану | -| ------------------------------------------ | -------------------------- | -------------------------------------- | ------------------------- | ------------------------------ | -| API OpenAI через звичайний runner OpenClaw | `openai/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI | `Runtime: OpenClaw Pi Default` | -| OAuth/підписка Codex через PI | `openai-codex/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OAuth OpenAI Codex | `Runtime: OpenClaw Pi Default` | -| Нативні вбудовані ходи Codex app-server | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | -| Змішані провайдери з консервативним авто-режимом | посилання, специфічні для провайдера | `agentRuntime.id: "auto"` | Необов’язкові середовища виконання Plugin | Залежить від вибраного середовища виконання | -| Явна сесія адаптера Codex ACP | залежить від prompt/моделі ACP | `sessions_spawn` з `runtime: "acp"` | справний бекенд `acpx` | Стан задачі/сесії ACP | +| Бажана поведінка | Ref моделі | Конфіг runtime | Вимога до Plugin | Очікувана мітка статусу | +| ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | +| OpenAI API через звичайний runner OpenClaw | `openai/gpt-*` | опущено або `runtime: "pi"` | Провайдер OpenAI | `Runtime: OpenClaw Pi Default` | +| OAuth/підписка Codex через PI | `openai-codex/gpt-*` | опущено або `runtime: "pi"` | Провайдер OpenAI Codex OAuth | `Runtime: OpenClaw Pi Default` | +| Нативні вбудовані ходи app-server Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | +| Змішані провайдери з консервативним auto-режимом | provider-specific refs | `agentRuntime.id: "auto"` | Необов’язкові runtimes Plugin | Залежить від вибраного runtime | +| Явна сесія адаптера ACP Codex | Залежить від prompt/model ACP | `sessions_spawn` з `runtime: "acp"` | справний backend `acpx` | Статус задачі/сесії ACP | -Важливий поділ тут — провайдер проти середовища виконання: +Важливий поділ — провайдер проти runtime: -- `openai-codex/*` відповідає на запитання «який маршрут провайдера/автентифікації має використовувати PI?» -- `agentRuntime.id: "codex"` відповідає на запитання «який цикл має виконувати цей - вбудований хід?» -- `/codex ...` відповідає на запитання «до якої нативної розмови Codex цей чат має прив’язатися - або якою керувати?» -- ACP відповідає на запитання «який зовнішній процес harness має запускати acpx?» +- `openai-codex/*` відповідає на питання "який маршрут провайдера/auth має використовувати PI?" +- `agentRuntime.id: "codex"` відповідає на питання "який loop має виконати цей + вбудований хід?" +- `/codex ...` відповідає на питання "до якої нативної розмови Codex цей чат має + прив’язатися або якою має керувати?" +- ACP відповідає на питання "який зовнішній процес harness має запустити acpx?" ## Виберіть правильний префікс моделі -Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли вам потрібен -OAuth Codex через PI; використовуйте `openai/*`, коли вам потрібен прямий доступ до API OpenAI або -коли ви примусово використовуєте нативний harness Codex app-server: +Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли хочете +OAuth Codex через PI; використовуйте `openai/*`, коли хочете прямий доступ до OpenAI API або +коли примусово використовуєте нативний harness app-server Codex: -| Посилання на модель | Шлях середовища виконання | Використовуйте, коли | -| -------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Провайдер OpenAI через зв’язку OpenClaw/PI | Вам потрібен поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OAuth OpenAI Codex через OpenClaw/PI | Вам потрібна автентифікація за підпискою ChatGPT/Codex із типовим runner Pi. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | harness Codex app-server | Вам потрібне нативне виконання через Codex app-server для вбудованого ходу агента. | +| Ref моделі | Шлях runtime | Коли використовувати | +| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Провайдер OpenAI через plumbing OpenClaw/PI | Вам потрібен поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна auth підписки ChatGPT/Codex зі стандартним runner PI. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness app-server Codex | Вам потрібне нативне виконання app-server Codex для вбудованого ходу агента. | -Наразі GPT-5.5 в OpenClaw доступна лише через підписку/OAuth. Використовуйте -`openai-codex/gpt-5.5` для OAuth через PI або `openai/gpt-5.5` з harness Codex -app-server. Прямий доступ за API-ключем для `openai/gpt-5.5` підтримуватиметься, +GPT-5.5 зараз доступна в OpenClaw лише через підписку/OAuth. Використовуйте +`openai-codex/gpt-5.5` для OAuth через PI або `openai/gpt-5.5` з harness +app-server Codex. Прямий доступ через API key для `openai/gpt-5.5` підтримується, щойно OpenAI увімкне GPT-5.5 у публічному API. -Застарілі посилання `codex/gpt-*`, як і раніше, приймаються як псевдоніми для сумісності. Doctor -під час міграції сумісності переписує застарілі основні посилання середовища виконання на канонічні посилання на модель -і записує політику середовища виконання окремо, тоді як застарілі посилання, що використовуються лише як резервні, -залишаються без змін, оскільки середовище виконання налаштовується для всього контейнера агента. -У нових конфігураціях PI Codex OAuth слід використовувати `openai-codex/gpt-*`; у нових нативних -конфігураціях harness app-server слід використовувати `openai/gpt-*` разом із +Застарілі refs `codex/gpt-*` лишаються прийнятними як aliases сумісності. Doctor +compatibility migration переписує застарілі refs основного runtime на канонічні refs моделей +і записує політику runtime окремо, тоді як застарілі refs лише для fallback +лишаються без змін, бо runtime налаштовується для всього контейнера агента. +Нові конфіги OAuth PI Codex мають використовувати `openai-codex/gpt-*`; нові конфіги нативного +harness app-server мають використовувати `openai/gpt-*` плюс `agentRuntime.id: "codex"`. `agents.defaults.imageModel` дотримується того самого поділу префіксів. Використовуйте -`openai-codex/gpt-*`, коли розуміння зображень має працювати через шлях провайдера OpenAI +`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися -через обмежений хід Codex app-server. Модель Codex app-server має -заявляти підтримку вхідних зображень; текстові моделі Codex завершуються з помилкою ще до -початку медіа-ходу. +через обмежений хід app-server Codex. Модель app-server Codex має +advertise підтримку вводу зображень; текстові моделі Codex завершуються помилкою до початку +ходу з медіа. -Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. Якщо вибір виявився неочікуваним, увімкніть журналювання налагодження для підсистеми `agents/harness` -і перевірте структурований запис gateway `agent harness selected`. Він -містить ідентифікатор вибраного harness, причину вибору, політику середовища виконання/резервного варіанта та, -у режимі `auto`, результат підтримки для кожного кандидата Plugin. +Використовуйте `/status`, щоб підтвердити ефективний harness для поточної сесії. Якщо +вибір несподіваний, увімкніть debug-логування для підсистеми `agents/harness` +і перегляньте структурований запис Gateway `agent harness selected`. Він +містить id вибраного harness, причину вибору, політику runtime/fallback і, +в режимі `auto`, результат підтримки кожного кандидата Plugin. ### Що означають попередження doctor -`openclaw doctor` показує попередження, коли всі ці умови істинні: +`openclaw doctor` попереджає, коли все це істинно: -- комплектний Plugin `codex` увімкнений або дозволений +- пакетний Plugin `codex` увімкнено або дозволено - основна модель агента — `openai-codex/*` -- фактичне середовище виконання цього агента — не `codex` +- ефективний runtime цього агента не `codex` -Таке попередження існує, тому що користувачі часто очікують, що «Plugin Codex увімкнений» означає -«нативне середовище виконання Codex app-server». OpenClaw не робить такого автоматичного висновку. Попередження означає: +Це попередження існує, бо користувачі часто очікують, що "Plugin Codex увімкнено" означає +"нативний runtime app-server Codex." OpenClaw не робить такого переходу. Попередження +означає: -- **Нічого змінювати не потрібно**, якщо ви мали на увазі OAuth ChatGPT/Codex через PI. -- Змініть модель на `openai/` і встановіть +- **Зміни не потрібні**, якщо ви мали на увазі OAuth ChatGPT/Codex через PI. +- Змініть модель на `openai/` і задайте `agentRuntime.id: "codex"`, якщо ви мали на увазі нативне виконання - через app-server. -- Наявні сесії, як і раніше, потребують `/new` або `/reset` після зміни середовища виконання, - тому що фіксація середовища виконання сесії є сталою. + app-server. +- Наявним сесіям усе ще потрібні `/new` або `/reset` після зміни runtime, + бо pins runtime сесії липкі. -Вибір harness не є механізмом керування живою сесією. Коли виконується вбудований хід, -OpenClaw записує ідентифікатор вибраного harness у цю сесію і продовжує використовувати його для -наступних ходів у межах того самого ідентифікатора сесії. Змініть конфігурацію `agentRuntime` або -`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб у майбутніх сесіях використовувався інший harness; +Вибір harness не є live-керуванням сесією. Коли виконується вбудований хід, +OpenClaw записує id вибраного harness у цій сесії й продовжує використовувати його для +наступних ходів у тому самому id сесії. Змінюйте конфіг `agentRuntime` або +`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної -розмови між PI і Codex. Це дає змогу уникнути повторного програвання одного транскрипту через +розмови між PI і Codex. Це запобігає повторному програванню однієї стенограми через дві несумісні нативні системи сесій. -Застарілі сесії, створені до появи фіксації harness, розглядаються як прив’язані до PI, щойно -вони мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на -Codex після зміни конфігурації. +Застарілі сесії, створені до pins harness, вважаються PI-pinned після того, як +мають історію стенограми. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на +Codex після зміни конфігу. -`/status` показує фактичне середовище виконання моделі. Типовий harness Pi відображається як -`Runtime: OpenClaw Pi Default`, а harness Codex app-server — як +`/status` показує ефективний runtime моделі. Типовий harness PI відображається як +`Runtime: OpenClaw Pi Default`, а harness app-server Codex відображається як `Runtime: OpenAI Codex`. ## Вимоги -- OpenClaw із доступним комплектним Plugin `codex`. -- Codex app-server `0.125.0` або новіший. Комплектний Plugin за замовчуванням керує сумісним - бінарним файлом Codex app-server, тому локальні команди `codex` у `PATH` +- OpenClaw із доступним пакетним Plugin `codex`. +- App-server Codex `0.125.0` або новіший. Пакетний Plugin типово керує сумісним + бінарним файлом app-server Codex, тому локальні команди `codex` у `PATH` не впливають на звичайний запуск harness. -- Доступна автентифікація Codex для процесу app-server або для мосту автентифікації Codex у OpenClaw. +- Auth Codex доступна процесу app-server або мосту auth Codex в OpenClaw. -Plugin блокує старіші або безверсійні handshake app-server. Це утримує -OpenClaw на поверхні протоколу, з якою його тестували. +Plugin блокує старіші або неверсійовані handshakes app-server. Це утримує +OpenClaw на поверхні протоколу, з якою його було протестовано. -Для live- і Docker smoke-тестів автентифікація зазвичай надходить з облікового запису Codex CLI -або з auth profile `openai-codex` в OpenClaw. Локальні запуски app-server через stdio -також можуть використовувати як резервний варіант `CODEX_API_KEY` / `OPENAI_API_KEY`, якщо облікового запису немає. +Для live і Docker smoke tests auth зазвичай надходить з облікового запису Codex CLI +або auth profile OpenClaw `openai-codex`. Локальні запуски stdio app-server також можуть +fallback до `CODEX_API_KEY` / `OPENAI_API_KEY`, коли облікового запису немає. -## Мінімальна конфігурація +## Мінімальний конфіг -Використовуйте `openai/gpt-5.5`, увімкніть комплектний Plugin і примусово задайте harness `codex`: +Використовуйте `openai/gpt-5.5`, увімкніть пакетний Plugin і примусово задайте harness `codex`: ```json5 { @@ -211,7 +219,7 @@ OpenClaw на поверхні протоколу, з якою його тест } ``` -Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`: +Якщо ваш конфіг використовує `plugins.allow`, додайте туди також `codex`: ```json5 { @@ -226,27 +234,27 @@ OpenClaw на поверхні протоколу, з якою його тест } ``` -Застарілі конфігурації, які задають `agents.defaults.model` або модель агента як -`codex/`, як і раніше, автоматично вмикають комплектний Plugin `codex`. У нових конфігураціях слід -використовувати `openai/` разом із явним записом `agentRuntime`, наведеним вище. +Застарілі конфіги, які задають `agents.defaults.model` або модель агента як +`codex/`, усе ще автоматично вмикають пакетний Plugin `codex`. Нові конфіги мають +віддавати перевагу `openai/` плюс явний запис `agentRuntime` вище. -## Додайте Codex поруч з іншими моделями +## Додайте Codex поряд з іншими моделями -Не встановлюйте `agentRuntime.id: "codex"` глобально, якщо той самий агент має вільно перемикатися -між Codex і моделями інших провайдерів. Примусово задане середовище виконання застосовується до кожного +Не задавайте `agentRuntime.id: "codex"` глобально, якщо той самий агент має вільно перемикатися +між Codex і моделями провайдерів, що не є Codex. Примусовий runtime застосовується до кожного вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, коли -це середовище виконання примусово задане, OpenClaw усе одно спробує використати harness Codex і завершиться помилкою -без тихого маршрутизації цього ходу через PI. +цей runtime примусово задано, OpenClaw усе одно спробує harness Codex і fail closed +замість того, щоб мовчки маршрутизувати цей хід через PI. -Використовуйте одну з таких форм: +Натомість використайте одну з цих форм: - Розмістіть Codex на окремому агенті з `agentRuntime.id: "codex"`. -- Залиште типовий агент на `agentRuntime.id: "auto"` з резервним варіантом PI для звичайного змішаного +- Залиште стандартного агента на `agentRuntime.id: "auto"` і резервний PI для звичайного змішаного використання провайдерів. -- Використовуйте застарілі посилання `codex/*` лише для сумісності. У нових конфігураціях слід - надавати перевагу `openai/*` разом із явною політикою середовища виконання Codex. +- Використовуйте застарілі посилання `codex/*` лише для сумісності. Новим конфігураціям варто надавати перевагу + `openai/*` плюс явній політиці середовища виконання Codex. -Наприклад, це залишає типовий агент на звичайному автоматичному виборі та +Наприклад, це залишає стандартного агента зі звичайним автоматичним вибором і додає окремого агента Codex: ```json5 @@ -284,37 +292,39 @@ OpenClaw на поверхні протоколу, з якою його тест } ``` -За такої структури: +З такою формою: -- Типовий агент `main` використовує звичайний шлях провайдера та резервний варіант сумісності PI. -- Агент `codex` використовує harness Codex app-server. -- Якщо для агента `codex` Codex відсутній або не підтримується, хід завершується помилкою +- Стандартний агент `main` використовує звичайний шлях провайдера та резервну сумісність PI. +- Агент `codex` використовує обв'язку app-server Codex. +- Якщо Codex відсутній або не підтримується для агента `codex`, хід завершується помилкою замість тихого використання PI. ## Маршрутизація команд агента Агенти мають маршрутизувати запити користувача за наміром, а не лише за словом "Codex": -| Користувач просить... | Агент має використовувати... | -| ----------------------------------------------------- | ------------------------------------------------ | -| "Прив’яжи цей чат до Codex" | `/codex bind` | -| "Віднови тут потік Codex ``" | `/codex resume ` | -| "Покажи потоки Codex" | `/codex threads` | -| "Використовуй Codex як середовище виконання для цього агента" | зміна конфігурації `agentRuntime.id` | -| "Використовуй мою підписку ChatGPT/Codex зі звичайним OpenClaw" | посилання на моделі `openai-codex/*` | -| "Запусти Codex через ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Запусти Claude Code/Gemini/OpenCode/Cursor у потоці" | ACP/acpx, не `/codex` і не нативні субагенти | +| Користувач просить... | Агент має використати... | +| -------------------------------------------------------- | ------------------------------------------------ | +| "Прив'язати цей чат до Codex" | `/codex bind` | +| "Відновити потік Codex `` тут" | `/codex resume ` | +| "Показати потоки Codex" | `/codex threads` | +| "Подати звіт у підтримку про невдалий запуск Codex" | `/diagnostics [note]` | +| "Надіслати відгук Codex лише для цього вкладеного потоку" | `/codex diagnostics [note]` | +| "Використати Codex як середовище виконання для цього агента" | зміна конфігурації `agentRuntime.id` | +| "Використати мою підписку ChatGPT/Codex зі звичайним OpenClaw" | посилання на моделі `openai-codex/*` | +| "Запустити Codex через ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | +| "Запустити Claude Code/Gemini/OpenCode/Cursor у потоці" | ACP/acpx, а не `/codex` і не нативні субагенти | -OpenClaw показує агентам інструкції щодо запуску через ACP лише тоді, коли ACP увімкнено, -доступний для диспетчеризації та підтримується завантаженим бекендом середовища виконання. Якщо ACP недоступний, -системний prompt і Skills Plugin не повинні навчати агента маршрутизації -через ACP. +OpenClaw рекламує агентам інструкції зі створення ACP лише тоді, коли ACP увімкнено, +доступний для диспетчеризації і підкріплений завантаженим бекендом середовища виконання. Якщо ACP недоступний, +системний prompt і Skills плагіна не повинні навчати агента +маршрутизації ACP. ## Розгортання лише з Codex -Примусово використовуйте harness Codex, коли вам потрібно довести, що кожен вбудований хід агента -використовує Codex. Явні середовища виконання Plugin типово не мають резервного варіанта PI, тож -`fallback: "none"` є необов’язковим, але часто корисним як документація: +Примусово використовуйте обв'язку Codex, коли потрібно довести, що кожен вбудований хід агента +використовує Codex. Явні середовища виконання плагінів за замовчуванням не мають резервного PI, тому +`fallback: "none"` є необов'язковим, але часто корисним як документація: ```json5 { @@ -336,14 +346,14 @@ OpenClaw показує агентам інструкції щодо запус OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Коли Codex примусово задано, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнений, якщо -app-server занадто старий або якщо app-server не може запуститися. Встановлюйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише тоді, коли ви свідомо хочете, щоб PI обробляв -відсутній вибір harness. +Коли Codex примусово увімкнено, OpenClaw рано завершується помилкою, якщо плагін Codex вимкнено, +app-server занадто старий або app-server не може запуститися. Установлюйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв +відсутній вибір обв'язки. ## Codex для окремого агента -Ви можете зробити один агент лише для Codex, тоді як типовий агент зберігатиме звичайний +Ви можете зробити одного агента Codex-only, поки стандартний агент зберігає звичайний автовибір: ```json5 @@ -376,14 +386,14 @@ app-server занадто старий або якщо app-server не може ``` Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову -сесію OpenClaw, а harness Codex за потреби створює або відновлює свій sidecar app-server -потік. `/reset` очищає прив’язку сесії OpenClaw для цього потоку -і дозволяє наступному ходу знову визначити harness з поточної конфігурації. +сесію OpenClaw, а обв'язка Codex створює або відновлює свій допоміжний потік app-server +за потреби. `/reset` очищає прив'язку сесії OpenClaw для цього потоку +і дає наступному ходу знову визначити обв'язку з поточної конфігурації. ## Виявлення моделей -За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо -виявлення завершується помилкою або тайм-аутом, він використовує комплектний резервний каталог для: +За замовчуванням плагін Codex запитує в app-server доступні моделі. Якщо +виявлення завершується помилкою або тайм-аутом, він використовує вбудований резервний каталог для: - GPT-5.5 - GPT-5.4 mini @@ -409,7 +419,7 @@ app-server занадто старий або якщо app-server не може } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не відбувалося зондування Codex і використовувався +Вимкніть виявлення, коли хочете, щоб запуск не перевіряв Codex і використовував резервний каталог: ```json5 @@ -431,25 +441,25 @@ app-server занадто старий або якщо app-server не може ## Підключення app-server і політика -За замовчуванням Plugin локально запускає керований OpenClaw бінарний файл Codex із: +За замовчуванням плагін запускає керований OpenClaw бінарний файл Codex локально з: ```bash codex app-server --listen stdio:// ``` -Керований бінарний файл оголошено як комплектну залежність середовища виконання Plugin і підготовлено -разом з рештою залежностей Plugin `codex`. Це прив’язує версію app-server -до комплектного Plugin, а не до окремого Codex CLI, -який випадково встановлений локально. Встановлюйте `appServer.command` лише тоді, коли -свідомо хочете запустити інший виконуваний файл. +Керований бінарний файл оголошено як вбудовану залежність середовища виконання плагіна та підготовлено +разом з рештою залежностей плагіна `codex`. Це прив'язує версію app-server +до вбудованого плагіна, а не до будь-якого окремого Codex CLI, +який випадково встановлено локально. Установлюйте `appServer.command` лише тоді, коли ви +навмисно хочете запустити інший виконуваний файл. -За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO: +За замовчуванням OpenClaw запускає локальні сесії обв'язки Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і -`sandbox: "danger-full-access"`. Це довірена локальна операційна модель, яка використовується +`sandbox: "danger-full-access"`. Це довірена локальна позиція оператора, яку використовують для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без -зупинки на нативних prompt підтвердження, на які нікому відповісти. +зупинки на нативних запитах схвалення, на які поруч ніхто не відповість. -Щоб увімкнути погодження Codex, перевірювані guardian, задайте `appServer.mode: +Щоб увімкнути схвалення Codex із перевіркою guardian, установіть `appServer.mode: "guardian"`: ```json5 @@ -470,18 +480,18 @@ codex app-server --listen stdio:// } ``` -Режим guardian використовує нативний шлях автоматичної перевірки погоджень Codex. Коли Codex просить -вийти з sandbox, писати поза робочим простором або додати дозволи, як-от доступ до мережі, -Codex маршрутизує цей запит на погодження до нативного рецензента, а не до -людського prompt. Рецензент застосовує модель ризику Codex і схвалює або відхиляє -конкретний запит. Використовуйте Guardian, коли вам потрібні сильніші запобіжники, ніж у режимі YOLO, -але при цьому потрібен прогрес агентів без нагляду. +Режим Guardian використовує нативний шлях автоогляду схвалень Codex. Коли Codex просить +вийти з sandbox, записати поза робочою областю або додати дозволи на кшталт мережевого +доступу, Codex спрямовує цей запит на схвалення до нативного reviewer замість +людського prompt. Reviewer застосовує систему оцінки ризиків Codex і схвалює або відхиляє +конкретний запит. Використовуйте Guardian, коли вам потрібні сильніші обмеження, ніж у режимі YOLO, +але автономним агентам усе ще потрібно просуватися без нагляду. -Шаблон `guardian` розгортається в `approvalPolicy: "on-request"`, +Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` і `sandbox: "workspace-write"`. -Окремі поля політики все ще перевизначають `mode`, тож у розширених розгортаннях можна поєднувати -цей шаблон з явними налаштуваннями. Старіше значення рецензента `guardian_subagent` -і далі приймається як псевдонім сумісності, але в нових конфігураціях слід використовувати +Окремі поля політики все ще перевизначають `mode`, тож розширені розгортання можуть поєднувати +пресет з явними виборами. Старіше значення reviewer `guardian_subagent` +досі приймається як псевдонім сумісності, але новим конфігураціям варто використовувати `auto_review`. Для вже запущеного app-server використовуйте транспорт WebSocket: @@ -506,21 +516,23 @@ Codex маршрутизує цей запит на погодження до н } ``` -Запуски app-server через stdio за замовчуванням успадковують середовище процесу OpenClaw, -але OpenClaw володіє мостом облікового запису Codex app-server. Автентифікація вибирається в такому +Запуски stdio app-server за замовчуванням успадковують середовище процесу OpenClaw, +але OpenClaw керує містком облікового запису app-server Codex. Auth вибирається в такому порядку: -1. Явний auth profile Codex OpenClaw для агента. +1. Явний профіль auth OpenClaw Codex для агента. 2. Наявний обліковий запис app-server, наприклад локальний вхід ChatGPT у Codex CLI. -3. Лише для локальних запусків app-server через stdio — `CODEX_API_KEY`, потім - `OPENAI_API_KEY`, якщо обліковий запис app-server відсутній і автентифікація OpenAI - все ще потрібна. +3. Лише для локальних запусків stdio app-server: `CODEX_API_KEY`, потім + `OPENAI_API_KEY`, коли облікового запису app-server немає, а OpenAI auth усе ще + потрібна. -Коли OpenClaw бачить auth profile Codex у стилі підписки ChatGPT, він видаляє -`CODEX_API_KEY` і `OPENAI_API_KEY` із породженого дочірнього процесу Codex. Це -дозволяє зберегти API-ключі рівня Gateway для embeddings або прямих моделей OpenAI, -не допускаючи при цьому, щоб нативні ходи Codex app-server випадково оплачувалися через API. -Явні профілі Codex з API-ключем і локальний резервний варіант із ключем середовища для stdio використовують вхід app-server замість успадкованого середовища дочірнього процесу. Підключення до app-server через WebSocket не отримують резервного варіанта з API-ключем середовища Gateway; використовуйте явний auth profile або +Коли OpenClaw бачить профіль auth Codex у стилі підписки ChatGPT, він видаляє +`CODEX_API_KEY` і `OPENAI_API_KEY` зі створеного дочірнього процесу Codex. Це +залишає API-ключі рівня Gateway доступними для embeddings або прямих моделей OpenAI +без випадкового білінгу нативних ходів Codex app-server через API. +Явні профілі API-ключів Codex і локальний резервний env-key для stdio використовують вхід app-server +замість успадкованого env дочірнього процесу. Підключення WebSocket app-server +не отримують резервний API-ключ env Gateway; використовуйте явний профіль auth або власний обліковий запис віддаленого app-server. Якщо розгортанню потрібна додаткова ізоляція середовища, додайте ці змінні до @@ -543,25 +555,25 @@ Codex маршрутизує цей запит на погодження до н } ``` -`appServer.clearEnv` впливає лише на породжений дочірній процес Codex app-server через stdio. +`appServer.clearEnv` впливає лише на створений дочірній процес app-server Codex. Підтримувані поля `appServer`: -| Поле | Типове значення | Значення | -| ------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | керований бінарний файл Codex | Виконуваний файл для транспорту stdio. Залиште порожнім, щоб використовувати керований бінарний файл; задавайте лише для явного перевизначення. | -| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не задано | URL app-server WebSocket. | -| `authToken` | не задано | Bearer token для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `clearEnv` | `[]` | Додаткові назви змінних середовища, які видаляються з породженого процесу app-server через stdio після того, як OpenClaw сформує успадковане середовище. | -| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control plane app-server. | -| `mode` | `"yolo"` | Шаблон для виконання в режимі YOLO або з перевіркою guardian. | -| `approvalPolicy` | `"never"` | Нативна політика погоджень Codex, що передається під час старту/відновлення потоку/ходу. | -| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що передається під час старту/відновлення потоку. | -| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні prompt погодження. `guardian_subagent` залишається застарілим псевдонімом. | -| `serviceTier` | не задано | Необов’язковий рівень сервісу Codex app-server: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | +| Поле | Типове значення | Значення | +| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | керований двійковий файл Codex | Виконуваний файл для stdio-транспорту. Залиште невстановленим, щоб використовувати керований двійковий файл; встановлюйте лише для явного перевизначення. | +| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для stdio-транспорту. | +| `url` | не встановлено | URL WebSocket app-server. | +| `authToken` | не встановлено | Bearer-токен для WebSocket-транспорту. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `clearEnv` | `[]` | Додаткові назви змінних середовища, які видаляються із запущеного процесу stdio app-server після того, як OpenClaw сформує успадковане середовище. | +| `requestTimeoutMs` | `60000` | Тайм-аут для викликів площини керування app-server. | +| `mode` | `"yolo"` | Попереднє налаштування для виконання YOLO або виконання з перевіркою guardian. | +| `approvalPolicy` | `"never"` | Нативна політика схвалення Codex, що надсилається під час запуску/відновлення потоку/ходу. | +| `sandbox` | `"danger-full-access"` | Нативний режим пісочниці Codex, що надсилається під час запуску/відновлення потоку. | +| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні запити на схвалення. `guardian_subagent` залишається застарілим псевдонімом. | +| `serviceTier` | не встановлено | Необов’язковий рівень сервісу Codex app-server: `"fast"`, `"flex"` або `null`. Недійсні застарілі значення ігноруються. | Перевизначення через середовище залишаються доступними для локального тестування: @@ -571,29 +583,29 @@ Codex маршрутизує цей запит на погодження до н - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_BIN` обходить керований бінарний файл, коли -`appServer.command` не задано. +`OPENCLAW_CODEX_APP_SERVER_BIN` обходить керований двійковий файл, коли +`appServer.command` не встановлено. -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Використовуйте -`plugins.entries.codex.config.appServer.mode: "guardian"` натомість або -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Для -відтворюваних розгортань перевага надається конфігурації, оскільки вона зберігає поведінку Plugin -в тому самому перевіреному файлі, що й решта налаштування harness Codex. +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Натомість використовуйте +`plugins.entries.codex.config.appServer.mode: "guardian"` або +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для одноразового локального тестування. Конфігурація +краща для повторюваних розгортань, бо вона тримає поведінку Plugin у тому +самому перевіреному файлі, що й решту налаштування обв’язки Codex. ## Використання комп’ютера Використання комп’ютера описано в окремому посібнику з налаштування: [Використання комп’ютера Codex](/uk/plugins/codex-computer-use). -Коротка версія: OpenClaw не постачає застосунок керування робочим столом і не виконує +Коротко: OpenClaw не вбудовує застосунок керування робочим столом і не виконує дії на робочому столі самостійно. Він готує Codex app-server, перевіряє, що MCP-сервер `computer-use` доступний, а потім дозволяє Codex обробляти нативні виклики інструментів MCP під час ходів у режимі Codex. Для прямого доступу до драйвера TryCua поза потоком маркетплейсу Codex зареєструйте -`cua-driver mcp` за допомогою `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. -Див. [Використання комп’ютера Codex](/uk/plugins/codex-computer-use) щодо різниці -між Computer Use, яким керує Codex, і прямою реєстрацією MCP. +`cua-driver mcp` через `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. +Див. [Використання комп’ютера Codex](/uk/plugins/codex-computer-use), щоб зрозуміти відмінність +між використанням комп’ютера, яким керує Codex, і прямою реєстрацією MCP. Мінімальна конфігурація: @@ -623,7 +635,7 @@ MCP-сервер `computer-use` доступний, а потім дозволя } ``` -Налаштування можна перевірити або встановити з поверхні команд: +Налаштування можна перевірити або встановити з командної поверхні: - `/codex computer-use status` - `/codex computer-use install` @@ -631,21 +643,22 @@ MCP-сервер `computer-use` доступний, а потім дозволя - `/codex computer-use install --marketplace-path ` Використання комп’ютера специфічне для macOS і може вимагати локальних дозволів ОС, перш ніж -MCP-сервер Codex зможе керувати застосунками. Якщо `computerUse.enabled` має значення true і MCP-сервер недоступний, ходи в режимі Codex завершуються помилкою до запуску потоку, а не -тихо виконуються без нативних інструментів Computer Use. Див. +MCP-сервер Codex зможе керувати застосунками. Якщо `computerUse.enabled` має значення true, а MCP +сервер недоступний, ходи в режимі Codex завершуються помилкою до запуску потоку, а не +тихо виконуються без нативних інструментів використання комп’ютера. Див. [Використання комп’ютера Codex](/uk/plugins/codex-computer-use) щодо варіантів маркетплейсу, обмежень віддаленого каталогу, причин стану та усунення несправностей. Коли `computerUse.autoInstall` має значення true, OpenClaw може зареєструвати стандартний -комплектний маркетплейс Codex Desktop із +вбудований маркетплейс Codex Desktop із `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`, якщо Codex ще не виявив локальний маркетплейс. Використовуйте `/new` або `/reset` після -зміни конфігурації середовища виконання або Computer Use, щоб наявні сесії не зберігали стару -прив’язку потоку PI або Codex. +зміни конфігурації runtime або використання комп’ютера, щоб наявні сесії не зберігали старе +прив’язування PI або потоку Codex. ## Поширені рецепти -Локальний Codex із типовим транспортом stdio: +Локальний Codex із типовим stdio-транспортом: ```json5 { @@ -659,7 +672,7 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Перевірка harness лише з Codex: +Валідація лише обв’язки Codex: ```json5 { @@ -681,7 +694,7 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Погодження Codex із перевіркою guardian: +Схвалення Codex з перевіркою guardian: ```json5 { @@ -726,193 +739,215 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Перемикання моделей залишається під контролем OpenClaw. Коли сесію OpenClaw приєднано -до наявного потоку Codex, наступний хід знову надсилає до -app-server поточно вибрану модель OpenAI, провайдера, політику погоджень, sandbox і рівень сервісу. -Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку -потоку, але просить Codex продовжити з нововибраною моделлю. +Перемикання моделі залишається під керуванням OpenClaw. Коли сесію OpenClaw приєднано +до наявного потоку Codex, наступний хід знову надсилає поточно вибрану +модель OpenAI, провайдера, політику схвалення, пісочницю та рівень сервісу до +app-server. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає +прив’язування потоку, але просить Codex продовжити з новообраною моделлю. ## Команда Codex -Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є -загальною і працює на будь-якому каналі, що підтримує текстові команди OpenClaw. +Вбудований Plugin реєструє `/codex` як авторизовану slash-команду. Вона +універсальна й працює в будь-якому каналі, що підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills. -- `/codex models` показує список живих моделей Codex app-server. -- `/codex threads [filter]` показує список останніх потоків Codex. +- `/codex status` показує поточне підключення app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills. +- `/codex models` виводить поточні моделі Codex app-server. +- `/codex threads [filter]` виводить нещодавні потоки Codex. - `/codex resume ` приєднує поточну сесію OpenClaw до наявного потоку Codex. -- `/codex compact` просить Codex app-server виконати Compaction для приєднаного потоку. +- `/codex compact` просить Codex app-server стиснути приєднаний потік. - `/codex review` запускає нативну перевірку Codex для приєднаного потоку. -- `/codex computer-use status` перевіряє налаштований Plugin Computer Use і MCP-сервер. -- `/codex computer-use install` встановлює налаштований Plugin Computer Use і перезавантажує MCP-сервери. +- `/codex diagnostics [note]` запитує підтвердження перед надсиланням діагностичного зворотного зв’язку Codex для приєднаного потоку. +- `/codex computer-use status` перевіряє налаштований Plugin використання комп’ютера та MCP-сервер. +- `/codex computer-use install` встановлює налаштований Plugin використання комп’ютера та перезавантажує MCP-сервери. - `/codex account` показує стан облікового запису та лімітів швидкості. -- `/codex mcp` показує список станів MCP-серверів Codex app-server. -- `/codex skills` показує список skills Codex app-server. +- `/codex mcp` виводить стан MCP-серверів Codex app-server. +- `/codex skills` виводить skills Codex app-server. -`/codex resume` записує той самий файл sidecar-прив’язки, який harness використовує для -звичайних ходів. Під час наступного повідомлення OpenClaw відновлює цей потік Codex, передає -поточну вибрану модель OpenClaw в app-server і зберігає ввімкнену -розширену історію. +### Поширений робочий процес налагодження -Поверхня команд вимагає Codex app-server `0.125.0` або новіший. Про окремі -методи керування повідомляється як `unsupported by this Codex app-server`, якщо -майбутній або користувацький app-server не надає цей метод JSON-RPC. +Коли агент на базі Codex робить щось неочікуване в Telegram, Discord, Slack +або іншому каналі, почніть із розмови, де сталася проблема: -## Межі hooks +1. Запустіть `/diagnostics bad tool choice after image upload` або іншу коротку нотатку, + що описує побачене. +2. Підтвердьте діагностичний запит один раз. Схвалення створює локальний zip-файл діагностики Gateway + і, оскільки сесія використовує обв’язку Codex, також + надсилає відповідний пакет зворотного зв’язку Codex на сервери OpenAI. +3. Скопіюйте завершену діагностичну відповідь у звіт про помилку або потік підтримки. + Вона містить локальний шлях пакета, зведення щодо приватності, ідентифікатори сесій OpenClaw, + ідентифікатори потоків Codex і рядок `Inspect locally` для кожного потоку Codex. +4. Якщо ви хочете самостійно налагодити запуск, виконайте надруковану команду `Inspect locally` + у терміналі. Вона виглядає як `codex resume ` і відкриває + нативний потік Codex, щоб ви могли переглянути розмову, продовжити її локально + або запитати Codex, чому він вибрав певний інструмент чи план. -Harness Codex має три шари hooks: +Використовуйте `/codex diagnostics [note]` лише тоді, коли вам спеціально потрібне +завантаження зворотного зв’язку Codex для поточно приєднаного потоку без повного +пакета діагностики Gateway OpenClaw. Для більшості звітів підтримки `/diagnostics [note]` є +кращою початковою точкою, бо він пов’язує локальний стан Gateway та ідентифікатори потоків Codex +в одній відповіді. Див. [Експорт діагностики](/uk/gateway/diagnostics) +щодо повної моделі приватності та поведінки в групових чатах. -| Шар | Власник | Призначення | -| ------------------------------------- | ------------------------ | ------------------------------------------------------------------ | -| hooks Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness Pi і Codex. | -| Middleware розширень Codex app-server | Комплектні plugins OpenClaw | Поведінка адаптера навколо динамічних інструментів OpenClaw для кожного ходу. | -| Нативні hooks Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | +Ядро OpenClaw також надає `/diagnostics [note]` лише для власника як загальну +команду діагностики Gateway. Її запит на схвалення показує преамбулу про чутливі дані, +посилається на [Експорт діагностики](/uk/gateway/diagnostics) і запитує +`openclaw gateway diagnostics export --json` через явне схвалення виконання +кожного разу. Не схвалюйте діагностику правилом allow-all. Після схвалення +OpenClaw надсилає придатний для вставлення звіт із локальним шляхом пакета та зведенням +маніфесту. Коли активна сесія OpenClaw використовує обв’язку Codex, те +саме схвалення також дозволяє надсилати відповідні пакети зворотного зв’язку Codex на +сервери OpenAI. Запит на схвалення повідомляє, що зворотний зв’язок Codex буде надіслано, але +не перелічує ідентифікатори сесій або потоків Codex до схвалення. -OpenClaw не використовує файли `hooks.json` Codex на рівні проєкту або глобально для маршрутизації -поведінки Plugin OpenClaw. Для підтримуваного мосту нативних інструментів і дозволів -OpenClaw впроваджує конфігурацію Codex для кожного потоку для `PreToolUse`, `PostToolUse`, -`PermissionRequest` і `Stop`. Інші hooks Codex, такі як `SessionStart` і -`UserPromptSubmit`, залишаються механізмами керування рівня Codex; вони не відкриваються як -hooks Plugin OpenClaw у контракті v1. +Якщо `/diagnostics` викликає власник у груповому чаті, OpenClaw зберігає +спільний канал чистим: група отримує лише коротке повідомлення, тоді як +діагностична преамбула, запити на схвалення та ідентифікатори сесій/потоків Codex надсилаються +власнику через приватний маршрут схвалення. Якщо приватного маршруту до власника немає, +OpenClaw відхиляє груповий запит і просить власника запустити його з приватного повідомлення. -Для динамічних інструментів OpenClaw OpenClaw виконує інструмент після того, як Codex запитує -виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, у -адаптері harness. Для нативних інструментів Codex Codex володіє канонічним записом інструмента. -OpenClaw може віддзеркалювати вибрані події, але не може переписувати нативний потік Codex, -якщо тільки Codex не надає цю операцію через app-server або нативні -callback hooks. +Схвалене завантаження Codex викликає `feedback/upload` Codex app-server і просить +app-server включити журнали для кожного переліченого потоку та породжених підпотоків Codex, +коли вони доступні. Завантаження проходить через звичайний шлях зворотного зв’язку Codex на сервери OpenAI; +якщо зворотний зв’язок Codex вимкнено в цьому app-server, команда повертає +помилку app-server. Завершена діагностична відповідь перелічує канали, +ідентифікатори сесій OpenClaw, ідентифікатори потоків Codex і локальні команди `codex resume ` +для потоків, які було надіслано. Якщо ви відхилите або проігноруєте схвалення, +OpenClaw не виводить ці ідентифікатори Codex. Це завантаження не замінює локальний +експорт діагностики Gateway. -Проєкції Compaction і життєвого циклу LLM надходять з -сповіщень Codex app-server і стану адаптера OpenClaw, а не з нативних команд hooks Codex. -Події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і -`llm_output` — це спостереження рівня адаптера, а не побайтові захоплення -внутрішнього запиту Codex або payload Compaction. +`/codex resume` записує той самий sidecar-файл прив’язування, який обв’язка використовує для +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає +поточну вибрану модель OpenClaw в app-server і залишає розширену історію +увімкнено. -Нативні сповіщення Codex app-server `hook/started` і `hook/completed` -проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження. -Вони не викликають hooks Plugin OpenClaw. +### Перевірка потоку Codex із CLI + +Найшвидший спосіб розібратися з невдалим запуском Codex часто полягає в тому, щоб відкрити нативний потік Codex безпосередньо: + +```sh +codex resume +``` + +Використовуйте це, коли помічаєте помилку в розмові каналу й хочете перевірити проблемний сеанс Codex, продовжити його локально або запитати Codex, чому він вибрав певний інструмент чи хід міркування. Найпростіший шлях зазвичай такий: спершу запустіть `/diagnostics [note]`; після вашого підтвердження завершений звіт перелічить кожен потік Codex і виведе команду `Inspect locally`, наприклад `codex resume `. Цю команду можна скопіювати безпосередньо в термінал. + +Також можна отримати ідентифікатор потоку з `/codex binding` для поточного чату або з `/codex threads [filter]` для нещодавніх потоків app-server Codex, а потім виконати ту саму команду `codex resume` у своїй оболонці. + +Поверхня команд потребує Codex app-server `0.125.0` або новішого. Окремі методи керування повідомляються як `unsupported by this Codex app-server`, якщо майбутній або користувацький app-server не надає цей метод JSON-RPC. + +## Межі хуків + +Обв'язка Codex має три шари хуків: + +| Шар | Власник | Призначення | +| ------------------------------------ | ------------------------ | ------------------------------------------------------------------ | +| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між обв'язками PI та Codex. | +| Middleware розширення Codex app-server | Bundled plugins OpenClaw | Поведінка адаптера на кожному кроці навколо динамічних інструментів OpenClaw. | +| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | + +OpenClaw не використовує проєктні або глобальні файли Codex `hooks.json` для маршрутизації поведінки Plugin OpenClaw. Для підтримуваного мосту нативних інструментів і дозволів OpenClaw впроваджує конфігурацію Codex на рівні потоку для `PreToolUse`, `PostToolUse`, `PermissionRequest` і `Stop`. Інші хуки Codex, як-от `SessionStart` і `UserPromptSubmit`, залишаються елементами керування рівня Codex; у контракті v1 вони не надаються як хуки Plugin OpenClaw. + +Для динамічних інструментів OpenClaw OpenClaw виконує інструмент після того, як Codex запитує виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє в адаптері обв'язки. Для нативних інструментів Codex канонічним записом інструмента володіє Codex. OpenClaw може дзеркалити вибрані події, але не може переписати нативний потік Codex, якщо Codex не надає цю операцію через app-server або callback-функції нативних хуків. + +Проєкції життєвого циклу Compaction і LLM походять зі сповіщень Codex app-server і стану адаптера OpenClaw, а не з команд нативних хуків Codex. Події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і `llm_output` є спостереженнями рівня адаптера, а не побайтовими знімками внутрішнього запиту Codex або payload Compaction. + +Нативні сповіщення app-server Codex `hook/started` і `hook/completed` проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження. Вони не викликають хуки Plugin OpenClaw. ## Контракт підтримки V1 -Режим Codex — це не PI з іншим викликом моделі під ним. Codex контролює більшу частину -нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сесій -навколо цієї межі. +Режим Codex — це не PI з іншим викликом моделі під капотом. Codex володіє більшою частиною нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сеансу навколо цієї межі. -Підтримується в середовищі виконання Codex v1: +Підтримується в runtime Codex v1: -| Поверхня | Підтримка | Чому | -| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Цикл моделі OpenAI через Codex | Підтримується | Codex app-server керує ходом OpenAI, нативним відновленням потоку та нативним продовженням інструментів. | -| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза середовищем виконання моделі. | -| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тож OpenClaw залишається на шляху виконання. | -| Plugins prompt і контексту | Підтримується | OpenClaw будує накладки prompt і проєктує контекст у хід Codex перед запуском або відновленням потоку. | -| Життєвий цикл рушія контексту | Підтримується | Збирання, поглинання або післяходове обслуговування та координація Compaction рушія контексту виконуються для ходів Codex. | -| hooks динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів працюють навколо динамічних інструментів OpenClaw. | -| hooks життєвого циклу | Підтримується як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` запускаються з коректними payload для режиму Codex. | -| Шлюз перегляду фінальної відповіді | Підтримується через ретрансляцію нативних hooks | Codex `Stop` ретранслюється в `before_agent_finalize`; `revise` просить Codex виконати ще один прохід моделі перед фіналізацією. | -| Нативне shell, patch і блокування або спостереження MCP | Підтримується через ретрансляцію нативних hooks | `PreToolUse` і `PostToolUse` Codex ретранслюються для зафіксованих поверхонь нативних інструментів, включно з payload MCP у Codex app-server `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. | -| Нативна політика дозволів | Підтримується через ретрансляцію нативних hooks | `PermissionRequest` Codex може маршрутизуватися через політику OpenClaw там, де середовище виконання це підтримує. Якщо OpenClaw не повертає рішення, Codex продовжує своїм звичайним шляхом погодження guardian або користувача. | -| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення, які отримує від app-server. | +| Поверхня | Підтримка | Чому | +| -------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Цикл моделі OpenAI через Codex | Підтримується | Codex app-server володіє кроком OpenAI, відновленням нативного потоку та продовженням нативного інструмента. | +| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза runtime моделі. | +| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тому OpenClaw залишається в шляху виконання. | +| Plugin підказок і контексту | Підтримується | OpenClaw будує накладки підказок і проєктує контекст у крок Codex перед запуском або відновленням потоку. | +| Життєвий цикл рушія контексту | Підтримується | Збирання, ingest або обслуговування після кроку, а також координація Compaction рушія контексту виконуються для кроків Codex. | +| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів виконуються навколо динамічних інструментів, якими володіє OpenClaw. | +| Хуки життєвого циклу | Підтримується як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із чесними payload режиму Codex. | +| Шлюз перегляду фінальної відповіді | Підтримується через ретранслятор нативних хуків | Codex `Stop` ретранслюється в `before_agent_finalize`; `revise` просить Codex виконати ще один прохід моделі перед фіналізацією. | +| Блокування або спостереження нативних shell, patch і MCP | Підтримується через ретранслятор нативних хуків | Codex `PreToolUse` і `PostToolUse` ретранслюються для зафіксованих поверхонь нативних інструментів, включно з payload MCP у Codex app-server `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. | +| Політика нативних дозволів | Підтримується через ретранслятор нативних хуків | Codex `PermissionRequest` може маршрутизуватися через політику OpenClaw там, де runtime її надає. Якщо OpenClaw не повертає рішення, Codex продовжує через свій звичайний guardian або шлях підтвердження користувачем. | +| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення app-server, які отримує. | -Не підтримується в середовищі виконання Codex v1: +Не підтримується в runtime Codex v1: -| Поверхня | Межа V1 | Майбутній шлях | -| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -| Мутація аргументів нативних інструментів | Нативні pre-tool hooks Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потребує підтримки hooks/схеми Codex для заміни вхідних даних інструмента. | -| Редагована історія транскрипту нативного Codex | Codex володіє канонічною історією нативного потоку. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не повинен змінювати непідтримувані внутрішні компоненти. | Додати явні API Codex app-server, якщо потрібне втручання в нативний потік. | -| `tool_result_persist` для записів нативних інструментів Codex | Цей hook перетворює записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Може віддзеркалювати перетворені записи, але канонічне переписування потребує підтримки Codex. | -| Розширені метадані нативної Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільного списку збережених/відкинутих елементів, дельти токенів або payload підсумку. | Потребує багатших подій Compaction у Codex. | -| Втручання в Compaction | Поточні hooks Compaction OpenClaw у режимі Codex працюють на рівні сповіщень. | Додати pre/post hooks Compaction у Codex, якщо Plugins потребують блокування або переписування нативної Compaction. | -| Побайтове захоплення запиту до API моделі | OpenClaw може захоплювати запити й сповіщення app-server, але ядро Codex формує фінальний запит до OpenAI API внутрішньо. | Потребує події трасування запиту моделі Codex або API налагодження. | +| Поверхня | Межа V1 | Майбутній шлях | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | +| Мутація аргументів нативних інструментів | Нативні pre-tool хуки Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потребує підтримки хуків/схеми Codex для заміни вхідних даних інструмента. | +| Редагована історія нативного транскрипту Codex | Codex володіє канонічною історією нативного потоку. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не має мутувати непідтримувані internals. | Додати явні API Codex app-server, якщо потрібна хірургія нативного потоку. | +| `tool_result_persist` для записів нативних інструментів Codex | Цей хук трансформує записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Можна дзеркалити трансформовані записи, але канонічне переписування потребує підтримки Codex. | +| Багаті нативні метадані Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільний список збереженого/відкинутого, дельту токенів або payload підсумку. | Потребує багатших подій Compaction Codex. | +| Втручання в Compaction | Поточні хуки Compaction OpenClaw у режимі Codex мають рівень сповіщень. | Додати pre/post хуки Compaction Codex, якщо plugins потребують veto або переписування нативного Compaction. | +| Побайтове захоплення API-запиту моделі | OpenClaw може захоплювати запити app-server і сповіщення, але ядро Codex внутрішньо будує фінальний API-запит OpenAI. | Потребує події трасування запиту моделі Codex або debug API. | ## Інструменти, медіа та Compaction -Harness Codex змінює лише низькорівневий виконавець вбудованого агента. +Обв'язка Codex змінює лише низькорівневий вбудований виконавець агента. -OpenClaw, як і раніше, будує список інструментів і отримує результати динамічних інструментів від -harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів обміну повідомленнями -продовжують проходити через звичайний шлях доставки OpenClaw. +OpenClaw і надалі будує список інструментів і отримує результати динамічних інструментів від обв'язки. Текст, зображення, відео, музика, TTS, підтвердження та вихідні дані messaging-tool продовжують проходити через звичайний шлях доставки OpenClaw. -Ретрансляція нативних hooks навмисно є узагальненою, але контракт підтримки v1 -обмежений нативними шляхами інструментів і дозволів Codex, які тестує OpenClaw. У -середовищі виконання Codex це включає payload `PreToolUse`, -`PostToolUse` і `PermissionRequest` для shell, patch і MCP. Не припускайте, що кожна майбутня -подія hooks Codex є поверхнею Plugin OpenClaw, доки це не буде прямо названо -контрактом середовища виконання. +Ретранслятор нативних хуків навмисно є універсальним, але контракт підтримки v1 обмежений шляхами нативних інструментів і дозволів Codex, які тестує OpenClaw. У runtime Codex це включає payload shell, patch і MCP `PreToolUse`, `PostToolUse` та `PermissionRequest`. Не припускайте, що кожна майбутня подія хуків Codex є поверхнею Plugin OpenClaw, доки runtime-контракт її не назве. -Для `PermissionRequest` OpenClaw повертає явні рішення allow або deny -лише тоді, коли це визначає політика. Результат без рішення — це не allow. Codex трактує його як відсутність -рішення hook і переходить до власного шляху погодження guardian або користувача. +Для `PermissionRequest` OpenClaw повертає явні рішення allow або deny лише тоді, коли це вирішує політика. Результат без рішення не є дозволом. Codex трактує його як відсутність рішення хука й переходить до власного guardian або шляху підтвердження користувачем. -Запити на погодження інструментів MCP Codex маршрутизуються через потік погодження Plugin -OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як -`"mcp_tool_call"`. Prompt `request_user_input` Codex надсилаються назад до -вихідного чату, а наступне поставлене в чергу follow-up повідомлення відповідає на цей нативний -запит сервера, замість того щоб спрямовуватися як додатковий контекст. Інші запити elicitation MCP, як і раніше, завершуються помилкою безпеки. +Запити схвалення інструментів Codex MCP маршрутизуються через потік схвалення Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як `"mcp_tool_call"`. Підказки Codex `request_user_input` надсилаються назад до початкового чату, а наступне повідомлення follow-up у черзі відповідає на цей нативний запит сервера, замість того щоб спрямовуватися як додатковий контекст. Інші запити MCP elicitation і надалі fail closed. -Коли вибрана модель використовує harness Codex, нативна Compaction потоку -делегується Codex app-server. OpenClaw зберігає дзеркало транскрипту для історії каналу, -пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало -включає prompt користувача, фінальний текст асистента та полегшені записи міркувань або плану Codex, коли їх генерує app-server. Наразі OpenClaw лише записує сигнали початку й завершення нативної Compaction. Він поки що не показує -людинозрозумілий підсумок Compaction або придатний для аудиту список записів, які Codex -зберіг після Compaction. +Коли вибрана модель використовує обв'язку Codex, нативний Compaction потоку делегується Codex app-server. OpenClaw зберігає дзеркало транскрипту для історії каналів, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або обв'язки. Дзеркало включає підказку користувача, фінальний текст асистента та легкі записи міркувань або плану Codex, коли app-server їх emits. Наразі OpenClaw записує лише сигнали початку й завершення нативного Compaction. Він ще не надає читабельний для людини підсумок Compaction або аудитований список того, які записи Codex зберіг після Compaction. -Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не -переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли -OpenClaw записує результат інструмента у транскрипт сесії, яким володіє OpenClaw. +Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли OpenClaw записує результат інструмента в транскрипт сеансу, яким володіє OpenClaw. -Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа, як і раніше, використовують відповідні налаштування провайдера/моделі, як-от -`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і -`messages.tts`. +Генерація медіа не потребує PI. Розуміння зображень, відео, музики, PDF, TTS і медіа й надалі використовує відповідні налаштування provider/model, як-от `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. ## Усунення несправностей -**Codex не з’являється як звичайний провайдер `/model`:** це очікувана поведінка для -нових конфігурацій. Виберіть модель `openai/gpt-*` з -`agentRuntime.id: "codex"` (або застарілим посиланням `codex/*`), увімкніть -`plugins.entries.codex.enabled` і перевірте, чи не виключає `plugins.allow` +**Codex не відображається як звичайний провайдер `/model`:** це очікувано для +нових конфігурацій. Виберіть модель `openai/gpt-*` із +`agentRuntime.id: "codex"` (або застаріле посилання `codex/*`), увімкніть +`plugins.entries.codex.enabled` і перевірте, чи `plugins.allow` не виключає `codex`. **OpenClaw використовує PI замість Codex:** `agentRuntime.id: "auto"` усе ще може використовувати PI як -бекенд сумісності, коли жоден harness Codex не бере на себе виконання. Встановіть -`agentRuntime.id: "codex"`, щоб примусово вибрати Codex під час тестування. Тепер -примусове середовище виконання Codex завершується помилкою замість переходу до PI, якщо ви -явно не встановите `agentRuntime.fallback: "pi"`. Щойно буде -вибрано Codex app-server, його помилки відображаються безпосередньо без додаткової конфігурації резервного варіанта. +сумісний бекенд, коли жоден harness Codex не бере запуск на себе. Установіть +`agentRuntime.id: "codex"`, щоб примусово вибрати Codex під час тестування. A +примусовий runtime Codex тепер завершується помилкою замість повернення до PI, якщо ви +явно не встановите `agentRuntime.fallback: "pi"`. Коли app-server Codex +вибрано, його помилки відображаються напряму без додаткової конфігурації fallback. -**app-server відхиляється:** оновіть Codex так, щоб handshake app-server -повідомляв версію `0.125.0` або новішу. Попередні випуски тієї самої версії або версії -із суфіксом збірки, як-от `0.125.0-alpha.2` або `0.125.0+custom`, відхиляються, оскільки -стабільний поріг протоколу `0.125.0` — це те, що тестує OpenClaw. +**App-server відхилено:** оновіть Codex, щоб handshake app-server +повідомляв версію `0.125.0` або новішу. Пререлізи тієї самої версії або версії із суфіксом збірки, +такі як `0.125.0-alpha.2` або `0.125.0+custom`, відхиляються, оскільки +стабільний мінімум протоколу `0.125.0` — це те, що тестує OpenClaw. -**Виявлення моделі повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` +**Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken` -і те, що віддалений app-server використовує ту саму версію протоколу Codex app-server. +**Транспорт WebSocket одразу завершується збоєм:** перевірте `appServer.url`, `authToken`, +і що віддалений app-server використовує ту саму версію протоколу app-server Codex. -**Модель не Codex використовує PI:** це очікувана поведінка, якщо ви не примусово встановили +**Модель не Codex використовує PI:** це очікувано, якщо тільки ви не примусили `agentRuntime.id: "codex"` для цього агента або не вибрали застаріле посилання `codex/*`. Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму звичайному -шляху провайдера в режимі `auto`. Якщо ви примусово задасте `agentRuntime.id: "codex"`, кожен вбудований +шляху провайдера в режимі `auto`. Якщо ви примусово встановите `agentRuntime.id: "codex"`, кожен вбудований хід для цього агента має бути моделлю OpenAI, яку підтримує Codex. -**Computer Use встановлено, але інструменти не працюють:** перевірте -`/codex computer-use status` у новій сесії. Якщо інструмент повідомляє -`Native hook relay unavailable`, використайте `/new` або `/reset`; якщо проблема не зникає, перезапустіть -gateway, щоб очистити застарілі реєстрації нативних hooks. Якщо `computer-use.list_apps` -зависає за тайм-аутом, перезапустіть Codex Computer Use або Codex Desktop і повторіть спробу. +**Computer Use установлено, але інструменти не запускаються:** перевірте +`/codex computer-use status` із нового сеансу. Якщо інструмент повідомляє +`Native hook relay unavailable`, використайте `/new` або `/reset`; якщо це не зникає, перезапустіть +Gateway, щоб очистити застарілі реєстрації native hook. Якщо `computer-use.list_apps` +завершується за timeout, перезапустіть Codex Computer Use або Codex Desktop і повторіть спробу. ## Пов’язане -- [Plugins harness агента](/uk/plugins/sdk-agent-harness) -- [Середовища виконання агентів](/uk/concepts/agent-runtimes) +- [Плагіни agent harness](/uk/plugins/sdk-agent-harness) +- [Runtime агентів](/uk/concepts/agent-runtimes) - [Провайдери моделей](/uk/concepts/model-providers) - [Провайдер OpenAI](/uk/providers/openai) - [Стан](/uk/cli/status) -- [Hooks Plugin](/uk/plugins/hooks) -- [Довідник з конфігурації](/uk/gateway/configuration-reference) +- [Хуки Plugin](/uk/plugins/hooks) +- [Довідник конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/uk/tools/slash-commands.md b/docs/uk/tools/slash-commands.md index dbe7b0039..f05485d56 100644 --- a/docs/uk/tools/slash-commands.md +++ b/docs/uk/tools/slash-commands.md @@ -6,17 +6,17 @@ sidebarTitle: Slash commands summary: 'Слеш-команди: текстові й нативні, конфігурація та підтримувані команди' title: Слеш-команди x-i18n: - generated_at: "2026-04-28T11:28:17Z" + generated_at: "2026-04-28T22:44:22Z" model: gpt-5.5 provider: openai - source_hash: e799ffb979cb405ee29e606ac914684595ddb59d7f878fab741c7dda90401a4c + source_hash: f9dfa0d86b953fe83989f117a27e5c05ee151ee7bd54c9db3c4190db4418043b source_path: tools/slash-commands.md workflow: 16 --- -Команди обробляє Gateway. Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`. Хостова команда bash-чату використовує `! ` (з `/bash ` як псевдонімом). +Команди обробляє Gateway. Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`. Команда bash-чату лише для хоста використовує `! ` (з `/bash ` як псевдонімом). -Коли розмова або гілка прив’язана до ACP-сесії, звичайний подальший текст спрямовується до цього ACP harness. Команди керування Gateway залишаються локальними: `/acp ...` завжди потрапляє до обробника команд OpenClaw ACP, а `/status` і `/unfocus` залишаються локальними щоразу, коли обробку команд увімкнено для цієї поверхні. +Коли розмову або гілку прив’язано до ACP-сеансу, звичайний подальший текст маршрутизується до цього ACP-обв’язування. Команди керування Gateway все одно залишаються локальними: `/acp ...` завжди потрапляє до обробника команд OpenClaw ACP, а `/status` і `/unfocus` залишаються локальними щоразу, коли обробку команд увімкнено для цієї поверхні. Є дві пов’язані системи: @@ -27,16 +27,16 @@ x-i18n: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. - - Директиви вилучаються з повідомлення до того, як модель його побачить. - - У звичайних повідомленнях чату (не лише з директивами) вони трактуються як "вбудовані підказки" і **не** зберігають налаштування сесії. - - У повідомленнях лише з директивами (повідомлення містить тільки директиви) вони зберігаються в сесії й відповідають підтвердженням. - - Директиви застосовуються лише для **авторизованих відправників**. Якщо встановлено `commands.allowFrom`, використовується тільки цей список дозволених; інакше авторизація походить зі списків дозволених каналів/спарювання плюс `commands.useAccessGroups`. Неавторизовані відправники бачать директиви як звичайний текст. + - Директиви видаляються з повідомлення до того, як модель його побачить. + - У звичайних повідомленнях чату (не лише з директивами) вони трактуються як "вбудовані підказки" і **не** зберігають налаштування сеансу. + - У повідомленнях лише з директивами (повідомлення містить тільки директиви) вони зберігаються в сеансі й відповідають підтвердженням. + - Директиви застосовуються лише для **авторизованих відправників**. Якщо встановлено `commands.allowFrom`, використовується тільки цей список дозволених; інакше авторизація походить зі списків дозволених/сполучення каналу плюс `commands.useAccessGroups`. Неавторизовані відправники бачать директиви як звичайний текст. Лише відправники зі списку дозволених/авторизовані: `/help`, `/commands`, `/status`, `/whoami` (`/id`). - Вони виконуються негайно, вилучаються до того, як модель побачить повідомлення, а решта тексту продовжує проходити звичайним потоком. + Вони виконуються негайно, видаляються до того, як модель побачить повідомлення, а решта тексту продовжує проходити звичайним потоком. @@ -69,19 +69,19 @@ x-i18n: ``` - Вмикає розбір `/...` у повідомленнях чату. На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо встановити це значення на `false`. + Вмикає розбір `/...` у повідомленнях чату. На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо встановити це значення в `false`. - Реєструє нативні команди. Авто: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте slash commands); ігнорується для провайдерів без нативної підтримки. Установіть `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native`, щоб перевизначити для окремого провайдера (bool або `"auto"`). `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Команди Slack керуються в застосунку Slack і не видаляються автоматично. + Реєструє нативні команди. Автоматично: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте slash-команди); ігнорується для провайдерів без нативної підтримки. Установіть `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native`, щоб перевизначити для окремого провайдера (булеве значення або `"auto"`). `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Команди Slack керуються в застосунку Slack і не видаляються автоматично. - Реєструє команди **skill** нативно, коли це підтримується. Авто: увімкнено для Discord/Telegram; вимкнено для Slack (Slack вимагає створення slash command для кожного skill). Установіть `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills`, щоб перевизначити для окремого провайдера (bool або `"auto"`). + Реєструє команди **skill** нативно, коли це підтримується. Автоматично: увімкнено для Discord/Telegram; вимкнено для Slack (Slack вимагає створення slash-команди для кожного skill). Установіть `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills`, щоб перевизначити для окремого провайдера (булеве значення або `"auto"`). Вмикає `! ` для запуску команд оболонки хоста (`/bash ` є псевдонімом; потребує списків дозволених `tools.elevated`). - Керує тим, як довго bash чекає перед переходом у фоновий режим (`0` переводить у фон негайно). + Керує тим, як довго bash очікує перед перемиканням у фоновий режим (`0` переводить у фон негайно). Вмикає `/config` (читає/записує `openclaw.json`). @@ -96,22 +96,22 @@ x-i18n: Вмикає `/debug` (перевизначення лише під час виконання). - Вмикає `/restart` плюс дії інструмента перезапуску Gateway. + Вмикає `/restart` плюс дії інструментів перезапуску Gateway. - Задає явний список дозволених власників для командних/інструментальних поверхонь лише для власника. Окремо від `commands.allowFrom`. + Установлює явний список дозволених власників для поверхонь команд/інструментів лише для власника. Це обліковий запис оператора-людини, який може схвалювати небезпечні дії та запускати команди на кшталт `/diagnostics`, `/export-trajectory` і `/config`. Він окремий від `commands.allowFrom` і від доступу через сполучення DM. - Для кожного каналу: вимагає **ідентичність власника** для виконання команд лише для власника на цій поверхні. Коли `true`, відправник має або відповідати розв’язаному кандидату власника (наприклад, запису в `commands.ownerAllowFrom` або нативним для провайдера метаданим власника), або мати внутрішню область дії `operator.admin` у внутрішньому каналі повідомлень. Запис із wildcard у `allowFrom` каналу або порожній/нерозв’язаний список кандидатів власника **не** є достатнім — команди лише для власника на цьому каналі відмовляють за замовчуванням. Залиште це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися тільки `ownerAllowFrom` і стандартними списками дозволених команд. + Для кожного каналу: змушує команди лише для власника вимагати **ідентичність власника** для запуску на цій поверхні. Коли `true`, відправник має або збігатися з визначеним кандидатом у власники (наприклад, записом у `commands.ownerAllowFrom` або нативними метаданими власника від провайдера), або мати внутрішню область `operator.admin` у внутрішньому каналі повідомлень. Запис із wildcard у `allowFrom` каналу або порожній/невизначений список кандидатів у власники **не** є достатнім — команди лише для власника на цьому каналі завершуються закритою відмовою. Залиште це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися тільки `ownerAllowFrom` і стандартними списками дозволених команд. - Керує тим, як ідентифікатори власників відображаються в системному промпті. + Керує тим, як ідентифікатори власників з’являються в системному промпті. - Необов’язково задає секрет HMAC, який використовується, коли `commands.ownerDisplay="hash"`. + Необов’язково встановлює HMAC-секрет, що використовується, коли `commands.ownerDisplay="hash"`. - Список дозволених для авторизації команд за провайдером. Коли налаштовано, це єдине джерело авторизації для команд і директив (списки дозволених каналів/спарювання та `commands.useAccessGroups` ігноруються). Використовуйте `"*"` для глобального значення за замовчуванням; ключі конкретних провайдерів його перевизначають. + Список дозволених для авторизації команд на рівні провайдера. Коли налаштовано, він є єдиним джерелом авторизації для команд і директив (списки дозволених/сполучення каналів і `commands.useAccessGroups` ігноруються). Використовуйте `"*"` для глобального стандартного значення; ключі конкретних провайдерів перевизначають його. Застосовує списки дозволених/політики для команд, коли `commands.allowFrom` не встановлено. @@ -121,79 +121,80 @@ x-i18n: Поточне джерело істини: -- вбудовані команди ядра походять із `src/auto-reply/commands-registry.shared.ts` -- згенеровані команди докування походять із `src/auto-reply/commands-registry.data.ts` -- команди Plugin походять із викликів Plugin `registerCommand()` -- фактична доступність на вашому gateway усе ще залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених plugins +- основні вбудовані команди походять із `src/auto-reply/commands-registry.shared.ts` +- згенеровані команди dock походять із `src/auto-reply/commands-registry.data.ts` +- Plugin-команди походять із викликів `registerCommand()` Plugin +- фактична доступність на вашому gateway все ще залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених Plugin -### Вбудовані команди ядра +### Основні вбудовані команди - - - `/new [model]` запускає нову сесію; `/reset` є псевдонімом скидання. - - `/reset soft [message]` зберігає поточну стенограму, відкидає повторно використані ідентифікатори сесій бекенда CLI та повторно запускає завантаження стартового/системного промпта на місці. - - `/compact [instructions]` ущільнює контекст сесії. Див. [Compaction](/uk/concepts/compaction). + + - `/new [model]` запускає новий сеанс; `/reset` є псевдонімом скидання. + - `/reset soft [message]` зберігає поточну стенограму, відкидає повторно використані ідентифікатори сеансів CLI-бекенда й повторно запускає завантаження запуску/системного промпта на місці. + - `/compact [instructions]` стискає контекст сеансу. Див. [Compaction](/uk/concepts/compaction). - `/stop` перериває поточний запуск. - - `/session idle ` і `/session max-age ` керують строком дії прив'язки потоку. - - `/export-session [path]` експортує поточну сесію в HTML. Псевдонім: `/export`. - - `/export-trajectory [path]` експортує JSONL [пакет траєкторії](/uk/tools/trajectory) для поточної сесії. Псевдонім: `/trajectory`. + - `/session idle ` і `/session max-age ` керують завершенням строку дії прив’язки гілки. + - `/export-session [path]` експортує поточний сеанс у HTML. Псевдонім: `/export`. + - `/export-trajectory [path]` просить схвалення exec, а потім експортує JSONL [пакет траєкторії](/uk/tools/trajectory) для поточного сеансу. Використовуйте це, коли вам потрібна часова шкала промпта, інструмента й стенограми для одного сеансу OpenClaw. У групових чатах запит схвалення та результат експорту надсилаються власнику приватно. Псевдонім: `/trajectory`. - - - `/think ` задає рівень мислення. Параметри беруться з профілю провайдера активної моделі; поширені рівні: `off`, `minimal`, `low`, `medium` і `high`, а користувацькі рівні, як-от `xhigh`, `adaptive`, `max`, або двійковий `on`, доступні лише там, де підтримуються. Псевдоніми: `/thinking`, `/t`. + + - `/think ` установлює рівень мислення. Варіанти походять із профілю провайдера активної моделі; поширені рівні: `off`, `minimal`, `low`, `medium` і `high`, а власні рівні, як-от `xhigh`, `adaptive`, `max` або бінарний `on`, доступні лише там, де підтримуються. Псевдоніми: `/thinking`, `/t`. - `/verbose on|off|full` перемикає докладний вивід. Псевдонім: `/v`. - - `/trace on|off` перемикає вивід трасування plugin для поточної сесії. - - `/fast [status|on|off]` показує або задає швидкий режим. - - `/reasoning [on|off|stream]` перемикає видимість міркування. Псевдонім: `/reason`. + - `/trace on|off` перемикає вивід трасування Plugin для поточного сеансу. + - `/fast [status|on|off]` показує або встановлює швидкий режим. + - `/reasoning [on|off|stream]` перемикає видимість міркувань. Псевдонім: `/reason`. - `/elevated [on|off|ask|full]` перемикає підвищений режим. Псевдонім: `/elev`. - - `/exec host= security= ask= node=` показує або задає типові параметри exec. - - `/model [name|#|status]` показує або задає модель. + - `/exec host= security= ask= node=` показує або встановлює стандартні значення exec. + - `/model [name|#|status]` показує або встановлює модель. - `/models [provider] [page] [limit=|size=|all]` перелічує провайдерів або моделі для провайдера. - `/queue ` керує поведінкою черги (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) плюс параметрами на кшталт `debounce:2s cap:25 drop:summarize`. - - `/help` показує коротку довідку. + - `/help` показує коротке зведення довідки. - `/commands` показує згенерований каталог команд. - - `/tools [compact|verbose]` показує, що поточний агент може використовувати прямо зараз. - - `/status` показує стан виконання/середовища виконання, зокрема мітки `Execution`/`Runtime` і використання/квоту провайдера, якщо доступно. + - `/tools [compact|verbose]` показує, що поточний агент може використовувати просто зараз. + - `/status` показує стан виконання/середовища виконання, зокрема мітки `Execution`/`Runtime` і використання/квоту провайдера, коли доступно. + - `/diagnostics [note]` — це потік звіту підтримки лише для власника для помилок Gateway і запусків обв’язування Codex. Він щоразу просить явне схвалення exec перед запуском `openclaw gateway diagnostics export --json`; не схвалюйте діагностику правилом allow-all. Після схвалення він надсилає звіт, придатний для вставлення, із локальним шляхом пакета, зведенням маніфесту, примітками щодо приватності та відповідними ідентифікаторами сеансу. У групових чатах запит схвалення та звіт надсилаються власнику приватно. Коли активний сеанс використовує обв’язування OpenAI Codex, те саме схвалення також надсилає відповідний відгук Codex на сервери OpenAI, а завершена відповідь перелічує ідентифікатори сеансів OpenClaw, ідентифікатори гілок Codex і команди `codex resume `. Див. [Експорт діагностики](/uk/gateway/diagnostics). - `/crestodian ` запускає помічник налаштування та ремонту Crestodian з DM власника. - - `/tasks` перелічує активні/нещодавні фонові завдання для поточної сесії. + - `/tasks` перелічує активні/нещодавні фонові завдання для поточного сеансу. - `/context [list|detail|json]` пояснює, як збирається контекст. - `/whoami` показує ваш ідентифікатор відправника. Псевдонім: `/id`. - - `/usage off|tokens|full|cost` керує нижнім колонтитулом використання для кожної відповіді або друкує локальний підсумок вартості. + - `/usage off|tokens|full|cost` керує нижнім колонтитулом використання для кожної відповіді або друкує локальне зведення витрат. - + - `/skill [input]` запускає skill за назвою. - - `/allowlist [list|add|remove] ...` керує записами списку дозволів. Лише текст. + - `/allowlist [list|add|remove] ...` керує записами списку дозволених. Лише текст. - `/approve ` вирішує запити схвалення exec. - - `/btw ` ставить побічне запитання без зміни майбутнього контексту сесії. Див. [BTW](/uk/tools/btw). + - `/btw ` ставить побічне запитання без зміни майбутнього контексту сеансу. Див. [BTW](/uk/tools/btw). - - `/subagents list|kill|log|info|send|steer|spawn` керує запусками субагентів для поточної сесії. - - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сесіями ACP і параметрами середовища виконання. - - `/focus ` прив'язує поточний потік Discord або тему/розмову Telegram до цілі сесії. - - `/unfocus` видаляє поточну прив'язку. - - `/agents` перелічує агентів, прив'язаних до потоку, для поточної сесії. + - `/subagents list|kill|log|info|send|steer|spawn` керує запусками субагентів для поточного сеансу. + - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує ACP-сеансами та параметрами середовища виконання. + - `/focus ` прив’язує поточну гілку Discord або тему/розмову Telegram до цільового сеансу. + - `/unfocus` видаляє поточну прив’язку. + - `/agents` перелічує агентів, прив’язаних до гілки, для поточного сеансу. - `/kill ` перериває одного або всіх запущених субагентів. - `/steer ` надсилає керування запущеному субагенту. Псевдонім: `/tell`. - - - `/config show|get|set|unset` читає або записує `openclaw.json`. Лише для власника. Потребує `commands.config: true`. - - `/mcp show|get|set|unset` читає або записує керовану OpenClaw конфігурацію MCP-сервера в `mcp.servers`. Лише для власника. Потребує `commands.mcp: true`. - - `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан plugin. `/plugin` є псевдонімом. Запис лише для власника. Потребує `commands.plugins: true`. - - `/debug show|set|unset|reset` керує перевизначеннями конфігурації лише на час виконання. Лише для власника. Потребує `commands.debug: true`. - - `/restart` перезапускає OpenClaw, коли увімкнено. Типово: увімкнено; задайте `commands.restart: false`, щоб вимкнути. + + - `/config show|get|set|unset` читає або записує `openclaw.json`. Лише для власника. Потрібно `commands.config: true`. + - `/mcp show|get|set|unset` читає або записує конфігурацію MCP-сервера, керовану OpenClaw, у `mcp.servers`. Лише для власника. Потрібно `commands.mcp: true`. + - `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан plugin. `/plugin` є псевдонімом. Записи лише для власника. Потрібно `commands.plugins: true`. + - `/debug show|set|unset|reset` керує перевизначеннями конфігурації лише для runtime. Лише для власника. Потрібно `commands.debug: true`. + - `/restart` перезапускає OpenClaw, якщо це ввімкнено. Типово: ввімкнено; задайте `commands.restart: false`, щоб вимкнути. - `/send on|off|inherit` задає політику надсилання. Лише для власника. - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` керує TTS. Див. [TTS](/uk/tools/tts). - - `/activation mention|always` задає режим активації групи. - - `/bash ` запускає команду оболонки хоста. Лише текст. Псевдонім: `! `. Потребує `commands.bash: true` плюс списки дозволів `tools.elevated`. + - `/activation mention|always` задає режим активації в групі. + - `/bash ` запускає команду оболонки хоста. Лише текст. Псевдонім: `! `. Потрібно `commands.bash: true` плюс allowlist для `tools.elevated`. - `!poll [sessionId]` перевіряє фонове завдання bash. - `!stop [sessionId]` зупиняє фонове завдання bash. @@ -202,33 +203,33 @@ x-i18n: ### Згенеровані команди докування -Команди докування перемикають маршрут відповіді поточної сесії на інший зв'язаний +Команди докування перемикають маршрут відповіді поточного сеансу на інший пов'язаний канал. Див. [Докування каналів](/uk/concepts/channel-docking) щодо налаштування, прикладів і усунення несправностей. -Команди dock генеруються з каналів plugins із підтримкою native-command. Поточний вбудований набір: +Команди докування генеруються з plugin каналів із підтримкою нативних команд. Поточний вбудований набір: - `/dock-discord` (псевдонім: `/dock_discord`) - `/dock-mattermost` (псевдонім: `/dock_mattermost`) - `/dock-slack` (псевдонім: `/dock_slack`) - `/dock-telegram` (псевдонім: `/dock_telegram`) -Використовуйте команди dock із прямого чату, щоб перемкнути маршрут відповіді поточного сеансу на інший прив’язаний канал. Агент зберігає той самий контекст сеансу, але майбутні відповіді для цього сеансу доставляються вибраному співрозмовнику каналу. +Використовуйте команди докування з прямого чату, щоб перемкнути маршрут відповіді поточного сеансу на інший пов'язаний канал. Агент зберігає той самий контекст сеансу, але майбутні відповіді для цього сеансу доставляються вибраному співрозмовнику каналу. -Команди dock потребують `session.identityLinks`. Початковий відправник і цільовий співрозмовник мають бути в тій самій групі ідентичності, наприклад `["telegram:123", "discord:456"]`. Якщо користувач Telegram з id `123` надсилає `/dock_discord`, OpenClaw зберігає `lastChannel: "discord"` і `lastTo: "456"` в активному сеансі. Якщо відправника не прив’язано до співрозмовника Discord, команда відповідає підказкою з налаштування замість переходу до звичайного чату. +Команди докування потребують `session.identityLinks`. Відправник-джерело й цільовий співрозмовник мають бути в одній групі ідентичностей, наприклад `["telegram:123", "discord:456"]`. Якщо користувач Telegram з id `123` надсилає `/dock_discord`, OpenClaw зберігає `lastChannel: "discord"` і `lastTo: "456"` в активному сеансі. Якщо відправника не пов'язано зі співрозмовником Discord, команда відповідає підказкою з налаштування замість переходу до звичайного чату. -Docking змінює лише активний маршрут сеансу. Він не створює облікові записи каналів, не надає доступ, не обходить allowlists каналів і не переносить історію стенограми до іншого сеансу. Використовуйте `/dock-telegram`, `/dock-slack`, `/dock-mattermost` або іншу згенеровану команду dock, щоб знову перемкнути маршрут. +Докування змінює лише маршрут активного сеансу. Воно не створює облікові записи каналів, не надає доступ, не обходить allowlist каналів і не переносить історію транскрипту в інший сеанс. Використовуйте `/dock-telegram`, `/dock-slack`, `/dock-mattermost` або іншу згенеровану команду докування, щоб знову перемкнути маршрут. -### Команди вбудованих plugins +### Команди вбудованих plugin Вбудовані plugins можуть додавати більше slash-команд. Поточні вбудовані команди в цьому репозиторії: -- `/dreaming [on|off|status|help]` перемикає dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming). -- `/pair [qr|status|pending|approve|cleanup|notify]` керує процесом сполучення/налаштування пристрою. Див. [Сполучення](/uk/channels/pairing). -- `/phone status|arm [duration]|disarm` тимчасово вмикає високоризикові команди phone node. +- `/dreaming [on|off|status|help]` перемикає Dreaming пам'яті. Див. [Dreaming](/uk/concepts/dreaming). +- `/pair [qr|status|pending|approve|cleanup|notify]` керує процесом спарювання/налаштування пристрою. Див. [Спарювання](/uk/channels/pairing). +- `/phone status|arm [duration]|disarm` тимчасово вмикає команди телефонного Node з високим ризиком. - `/voice status|list [limit]|set ` керує конфігурацією голосу Talk. У Discord назва нативної команди — `/talkvoice`. -- `/card ...` надсилає пресети насичених карток LINE. Див. [LINE](/uk/channels/line). -- `/codex status|models|threads|resume|compact|review|account|mcp|skills` перевіряє і керує вбудованим harness сервера застосунку Codex. Див. [Harness Codex](/uk/plugins/codex-harness). +- `/card ...` надсилає пресети розширених карток LINE. Див. [LINE](/uk/channels/line). +- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` перевіряє й керує вбудованим app-server harness Codex. Див. [Harness Codex](/uk/plugins/codex-harness). - Команди лише для QQBot: - `/bot-ping` - `/bot-version` @@ -241,82 +242,82 @@ Docking змінює лише активний маршрут сеансу. Ві Skills, які може викликати користувач, також доступні як slash-команди: - `/skill [input]` завжди працює як загальна точка входу. -- skills також можуть з’являтися як прямі команди на кшталт `/prose`, коли skill/plugin їх реєструє. -- нативна реєстрація команд Skills керується `commands.nativeSkills` і `channels..commands.nativeSkills`. +- Skills також можуть з'являтися як прямі команди, наприклад `/prose`, коли skill/plugin їх реєструє. +- реєстрація нативних команд Skills керується `commands.nativeSkills` і `channels..commands.nativeSkills`. - - - Команди приймають необов’язковий `:` між командою та аргументами (наприклад, `/think: high`, `/send: on`, `/help:`). + + - Команди приймають необов'язковий `:` між командою та аргументами (наприклад, `/think: high`, `/send: on`, `/help:`). - `/new ` приймає псевдонім моделі, `provider/model` або назву провайдера (нечіткий збіг); якщо збігу немає, текст вважається тілом повідомлення. - - Для повного розподілу використання провайдера використовуйте `openclaw status --usage`. + - Для повного розбору використання провайдера використовуйте `openclaw status --usage`. - `/allowlist add|remove` потребує `commands.config=true` і враховує `configWrites` каналу. - - У багатооблікових каналах орієнтовані на конфігурацію `/allowlist --account ` і `/config set channels..accounts....` також враховують `configWrites` цільового облікового запису. + - У багатооблікових каналах `/allowlist --account ` із цільовою конфігурацією та `/config set channels..accounts....` також враховують `configWrites` цільового облікового запису. - `/usage` керує футером використання для кожної відповіді; `/usage cost` друкує локальний підсумок вартості з журналів сеансів OpenClaw. - - `/restart` увімкнено за замовчуванням; встановіть `commands.restart: false`, щоб вимкнути його. - - `/plugins install ` приймає ті самі специфікації Plugin, що й `openclaw plugins install`: локальний шлях/архів, npm-пакет або `clawhub:`. - - `/plugins enable|disable` оновлює конфігурацію Plugin і може запропонувати перезапуск. + - `/restart` увімкнено типово; задайте `commands.restart: false`, щоб вимкнути. + - `/plugins install ` приймає ті самі специфікації plugin, що й `openclaw plugins install`: локальний шлях/архів, npm-пакет або `clawhub:`. + - `/plugins enable|disable` оновлює конфігурацію plugin і може запропонувати перезапуск. - - Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (недоступна як текст). `join` потребує guild і вибраного голосового/stage каналу. Потребує `channels.discord.voice` і нативних команд. - - Команди прив’язки потоків Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) потребують увімкнених ефективних прив’язок потоків (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`). - - Довідник команд ACP і поведінка під час виконання: [агенти ACP](/uk/tools/acp-agents). + - Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (недоступна як текст). `join` потребує guild і вибраного голосового/сценічного каналу. Потрібні `channels.discord.voice` і нативні команди. + - Команди прив'язки потоків Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) потребують увімкнених ефективних прив'язок потоків (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`). + - Довідник команд ACP і поведінка runtime: [Агенти ACP](/uk/tools/acp-agents). - - `/verbose` призначено для налагодження та додаткової видимості; у звичайному використанні тримайте його **вимкненим**. - - `/trace` вужчий за `/verbose`: він розкриває лише trace/debug-рядки, що належать plugin, і не вмикає звичайний verbose-шум інструментів. - - `/fast on|off` зберігає перевизначення сеансу. Використовуйте опцію `inherit` в UI Sessions, щоб очистити його та повернутися до стандартних значень конфігурації. - - `/fast` залежить від провайдера: OpenAI/OpenAI Codex відображають його в `service_tier=priority` на нативних endpoints Responses, тоді як прямі публічні запити Anthropic, зокрема OAuth-автентифікований трафік, надісланий до `api.anthropic.com`, відображають його в `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic). - - Підсумки помилок інструментів усе ще показуються, коли доречно, але докладний текст помилки включається лише тоді, коли `/verbose` має значення `on` або `full`. - - `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішнє reasoning, вивід інструментів або діагностику plugin, яку ви не мали наміру показувати. Краще залишати їх вимкненими, особливо в групових чатах. + - `/verbose` призначено для налагодження та додаткової видимості; тримайте його **вимкненим** під час звичайного використання. + - `/trace` вужчий за `/verbose`: він показує лише trace/debug-рядки, що належать plugin, і не вмикає звичайний докладний шум інструментів. + - `/fast on|off` зберігає перевизначення сеансу. Використовуйте опцію `inherit` в UI сеансів, щоб очистити його й повернутися до типових значень конфігурації. + - `/fast` залежить від провайдера: OpenAI/OpenAI Codex зіставляють його з `service_tier=priority` на нативних endpoints Responses, тоді як прямі публічні запити Anthropic, зокрема трафік, автентифікований через OAuth і надісланий до `api.anthropic.com`, зіставляють його з `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic). + - Підсумки збоїв інструментів усе ще показуються, коли це доречно, але докладний текст збою включається лише коли `/verbose` має значення `on` або `full`. + - `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішнє reasoning, вивід інструментів або діагностику plugin, які ви не мали наміру показувати. Краще залишати їх вимкненими, особливо в групових чатах. - `/model` негайно зберігає нову модель сеансу. - - Якщо агент неактивний, наступний запуск одразу її використовує. - - Якщо запуск уже активний, OpenClaw позначає live-перемикання як очікуване й перезапускається з новою моделлю лише в чистій точці повторної спроби. - - Якщо активність інструментів або вивід відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача. - - У локальному TUI `/crestodian [request]` повертає зі звичайного TUI агента до Crestodian. Це окремо від rescue mode каналу повідомлень і не надає віддалених повноважень на зміну конфігурації. + - Якщо агент простоює, наступний запуск використовує її відразу. + - Якщо запуск уже активний, OpenClaw позначає живе перемикання як очікуване й перезапускається з новою моделлю лише в чистій точці повтору. + - Якщо активність інструментів або вивід відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повтору або наступного ходу користувача. + - У локальному TUI `/crestodian [request]` повертає зі звичайного TUI агента до Crestodian. Це окремо від режиму порятунку в каналі повідомлень і не надає віддалених повноважень на конфігурацію. - - - **Швидкий шлях:** повідомлення лише з командами від відправників з allowlist обробляються негайно (обхід черги + моделі). - - **Обмеження згадками в групах:** повідомлення лише з командами від відправників з allowlist обходять вимоги до згадки. - - **Inline-скорочення (лише відправники з allowlist):** деякі команди також працюють, коли вбудовані у звичайне повідомлення, і вилучаються до того, як модель побачить решту тексту. - - Приклад: `hey /status` запускає відповідь зі статусом, а решта тексту продовжує оброблятися звичайним потоком. + + - **Швидкий шлях:** повідомлення лише з командою від відправників з allowlist обробляються негайно (обхід черги + моделі). + - **Гейт за згадкою в групі:** повідомлення лише з командою від відправників з allowlist обходять вимоги згадки. + - **Вбудовані скорочення (лише відправники з allowlist):** певні команди також працюють, коли вбудовані у звичайне повідомлення, і вилучаються до того, як модель побачить решту тексту. + - Приклад: `hey /status` викликає відповідь зі статусом, а решта тексту проходить через звичайний потік. - Наразі: `/help`, `/commands`, `/status`, `/whoami` (`/id`). - - Неавторизовані повідомлення лише з командами тихо ігноруються, а inline-токени `/...` трактуються як звичайний текст. + - Неавторизовані повідомлення лише з командою мовчки ігноруються, а вбудовані токени `/...` трактуються як звичайний текст. - - **Команди Skills:** skills `user-invocable` доступні як slash-команди. Назви санітизуються до `a-z0-9_` (макс. 32 символи); колізії отримують числові суфікси (наприклад, `_2`). - - `/skill [input]` запускає skill за назвою (корисно, коли обмеження нативних команд не дають створити окремі команди для кожної skill). - - За замовчуванням команди Skills пересилаються моделі як звичайний запит. - - Skills можуть необов’язково оголосити `command-dispatch: tool`, щоб спрямувати команду безпосередньо до інструмента (детерміновано, без моделі). - - Приклад: `/prose` (OpenProse plugin) — див. [OpenProse](/uk/prose). - - **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних опцій (і меню кнопок, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти вибору, а ви пропускаєте аргумент. Динамічні варіанти визначаються відносно цільової моделі сеансу, тому специфічні для моделі опції, як-от рівні `/think`, враховують перевизначення `/model` цього сеансу. + - **Команди Skills:** Skills `user-invocable` доступні як slash-команди. Назви очищуються до `a-z0-9_` (максимум 32 символи); колізії отримують числові суфікси (наприклад, `_2`). + - `/skill [input]` запускає skill за назвою (корисно, коли обмеження нативних команд не дозволяють команди для кожного skill). + - Типово команди Skills пересилаються моделі як звичайний запит. + - Skills можуть необов'язково оголошувати `command-dispatch: tool`, щоб спрямувати команду напряму до інструмента (детерміновано, без моделі). + - Приклад: `/prose` (plugin OpenProse) — див. [OpenProse](/uk/prose). + - **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних опцій (і меню кнопок, коли ви пропускаєте обов'язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти вибору, а ви пропускаєте аргумент. Динамічні варіанти вибору визначаються відносно моделі цільового сеансу, тому опції, специфічні для моделі, як-от рівні `/think`, дотримуються перевизначення `/model` цього сеансу. ## `/tools` -`/tools` відповідає на питання про середовище виконання, а не про конфігурацію: **що цей агент може використовувати просто зараз у цій розмові**. +`/tools` відповідає на питання runtime, а не на питання конфігурації: **що цей агент може використовувати прямо зараз у цій розмові**. -- Стандартний `/tools` компактний і оптимізований для швидкого перегляду. +- Типовий `/tools` компактний і оптимізований для швидкого перегляду. - `/tools verbose` додає короткі описи. -- Поверхні нативних команд, які підтримують аргументи, надають той самий перемикач режиму `compact|verbose`. -- Результати прив’язані до сеансу, тому зміна агента, каналу, потоку, авторизації відправника або моделі може змінити вивід. -- `/tools` включає інструменти, які фактично доступні під час виконання, зокрема основні інструменти, підключені інструменти plugin і інструменти, що належать каналу. +- Поверхні нативних команд, які підтримують аргументи, надають той самий перемикач режиму, що й `compact|verbose`. +- Результати обмежені сеансом, тому зміна агента, каналу, потоку, авторизації відправника або моделі може змінити вивід. +- `/tools` включає інструменти, які фактично доступні під час runtime, зокрема основні інструменти, підключені інструменти plugin та інструменти, що належать каналу. -Для редагування профілю та перевизначень використовуйте панель Tools у Control UI або поверхні конфігурації/каталогу, замість того щоб трактувати `/tools` як статичний каталог. +Для редагування профілю й перевизначень використовуйте панель Control UI Tools або поверхні конфігурації/каталогу, а не розглядайте `/tools` як статичний каталог. ## Поверхні використання (що де показується) -- **Використання/квота провайдера** (приклад: "Claude 80% left") показується в `/status` для поточного провайдера моделі, коли ввімкнено відстеження використання. OpenClaw нормалізує вікна провайдерів до `% left`; для MiniMax поля відсотка лише залишку інвертуються перед показом, а відповіді `model_remains` віддають перевагу запису chat-model плюс позначці плану з тегом моделі. -- **Рядки token/cache** у `/status` можуть повертатися до останнього запису використання стенограми, коли live-знімок сеансу розріджений. Наявні ненульові live-значення все одно мають пріоритет, а резервне використання стенограми також може відновити активну мітку runtime-моделі плюс більший prompt-орієнтований підсумок, коли збережені підсумки відсутні або менші. -- **Execution vs runtime:** `/status` повідомляє `Execution` для ефективного шляху sandbox і `Runtime` для того, хто фактично виконує сеанс: `OpenClaw Pi Default`, `OpenAI Codex`, CLI backend або ACP backend. +- **Використання/квота провайдера** (приклад: "Claude 80% left") показується в `/status` для поточного провайдера моделі, коли відстеження використання ввімкнено. OpenClaw нормалізує вікна провайдерів до `% left`; для MiniMax поля відсотків лише залишку інвертуються перед відображенням, а відповіді `model_remains` віддають перевагу запису чат-моделі плюс мітці плану з тегом моделі. +- **Рядки токенів/кешу** в `/status` можуть повертатися до останнього запису використання транскрипту, коли живий знімок сеансу розріджений. Наявні ненульові живі значення все одно мають пріоритет, а fallback транскрипту також може відновити активну мітку runtime-моделі плюс більшу prompt-орієнтовану суму, коли збережені підсумки відсутні або менші. +- **Виконання vs runtime:** `/status` повідомляє `Execution` для ефективного шляху sandbox і `Runtime` для того, хто фактично запускає сеанс: `OpenClaw Pi Default`, `OpenAI Codex`, бекенд CLI або бекенд ACP. - **Токени/вартість для кожної відповіді** керуються `/usage off|tokens|full` (додається до звичайних відповідей). - `/model status` стосується **моделей/автентифікації/endpoints**, а не використання. @@ -335,16 +336,16 @@ Skills, які може викликати користувач, також до /model status ``` -Нотатки: +Примітки: -- `/model` і `/model list` показують компактний нумерований picker (родина моделі + доступні провайдери). -- У Discord `/model` і `/models` відкривають інтерактивний picker з dropdown провайдера й моделі плюс крок Submit. -- `/model <#>` вибирає з цього picker (і за можливості віддає перевагу поточному провайдеру). +- `/model` і `/model list` показують компактний нумерований вибір (сімейство моделей + доступні провайдери). +- У Discord `/model` і `/models` відкривають інтерактивний вибір із dropdown провайдера та моделі плюс крок Submit. +- `/model <#>` вибирає з цього списку (і віддає перевагу поточному провайдеру, коли можливо). - `/model status` показує докладний вигляд, зокрема налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли доступно. -## Перевизначення debug +## Перевизначення налагодження -`/debug` дає змогу встановлювати **лише runtime** перевизначення конфігурації (у пам’яті, не на диску). Лише для власника. Вимкнено за замовчуванням; увімкніть через `commands.debug: true`. +`/debug` дає змогу встановлювати перевизначення конфігурації **лише для часу виконання** (у пам’яті, не на диску). Лише для власника. Вимкнено за замовчуванням; увімкніть через `commands.debug: true`. Приклади: @@ -357,12 +358,12 @@ Skills, які може викликати користувач, також до ``` -Перевизначення застосовуються негайно до нових читань конфігурації, але **не** записуються в `openclaw.json`. Використовуйте `/debug reset`, щоб очистити всі перевизначення й повернутися до конфігурації на диску. +Перевизначення негайно застосовуються до нових читань конфігурації, але **не** записуються в `openclaw.json`. Використовуйте `/debug reset`, щоб очистити всі перевизначення й повернутися до конфігурації на диску. -## Вивід trace plugin +## Вивід трасування Plugin -`/trace` дає змогу перемикати **прив’язані до сеансу trace/debug-рядки plugin** без увімкнення повного verbose mode. +`/trace` дає змогу перемикати **рядки трасування/налагодження Plugin у межах сесії** без увімкнення повного докладного режиму. Приклади: @@ -372,14 +373,14 @@ Skills, які може викликати користувач, також до /trace off ``` -Нотатки: +Примітки: -- `/trace` без аргументів показує поточний стан trace сеансу. -- `/trace on` вмикає trace-рядки plugin для поточного сеансу. +- `/trace` без аргументу показує поточний стан трасування сесії. +- `/trace on` вмикає рядки трасування Plugin для поточної сесії. - `/trace off` знову вимикає їх. -- Trace-рядки plugin можуть з’являтися в `/status` і як подальше діагностичне повідомлення після звичайної відповіді асистента. -- `/trace` не замінює `/debug`; `/debug` і далі керує лише runtime перевизначеннями конфігурації. -- `/trace` не замінює `/verbose`; звичайний verbose-вивід інструментів/статусу все ще належить до `/verbose`. +- Рядки трасування Plugin можуть з’являтися в `/status` і як подальше діагностичне повідомлення після звичайної відповіді асистента. +- `/trace` не замінює `/debug`; `/debug` і далі керує перевизначеннями конфігурації лише для часу виконання. +- `/trace` не замінює `/verbose`; звичайний докладний вивід інструментів/стану й далі належить до `/verbose`. ## Оновлення конфігурації @@ -401,7 +402,7 @@ Skills, які може викликати користувач, також до ## Оновлення MCP -`/mcp` записує визначення MCP-серверів, керовані OpenClaw, у `mcp.servers`. Лише для власників. Вимкнено за замовчуванням; увімкніть через `commands.mcp: true`. +`/mcp` записує визначення серверів MCP, керовані OpenClaw, у `mcp.servers`. Лише для власника. Вимкнено за замовчуванням; увімкніть через `commands.mcp: true`. Приклади: @@ -413,12 +414,12 @@ Skills, які може викликати користувач, також до ``` -`/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, що належать Pi. Runtime-адаптери визначають, які транспорти фактично можна виконувати. +`/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, що належать Pi. Runtime-адаптери визначають, які транспорти фактично можна виконати. ## Оновлення Plugin -`/plugins` дає операторам змогу переглядати знайдені plugins і перемикати їх увімкнення в конфігурації. Потоки лише для читання можуть використовувати `/plugin` як псевдонім. Вимкнено за замовчуванням; увімкніть через `commands.plugins: true`. +`/plugins` дає операторам змогу переглядати виявлені plugins і перемикати ввімкнення в конфігурації. Потоки лише для читання можуть використовувати `/plugin` як псевдонім. Вимкнено за замовчуванням; увімкніть через `commands.plugins: true`. Приклади: @@ -431,45 +432,45 @@ Skills, які може викликати користувач, також до ``` -- `/plugins list` і `/plugins show` використовують реальне виявлення plugin для поточної робочої області плюс конфігурацію на диску. -- `/plugins enable|disable` оновлює лише конфігурацію plugin; це не встановлює й не видаляє plugins. -- Після змін увімкнення/вимкнення перезапустіть Gateway, щоб застосувати їх. +- `/plugins list` і `/plugins show` використовують справжнє виявлення plugins у поточній робочій області разом із конфігурацією на диску. +- `/plugins enable|disable` оновлює лише конфігурацію Plugin; це не встановлює й не видаляє plugins. +- Після змін увімкнення/вимкнення перезапустіть gateway, щоб застосувати їх. ## Примітки щодо поверхонь - - - **Текстові команди** виконуються у звичайній сесії чату (DM використовують спільну `main`, групи мають власну сесію). + + - **Текстові команди** виконуються у звичайній чат-сесії (DM використовують спільну `main`, групи мають власну сесію). - **Нативні команди** використовують ізольовані сесії: - Discord: `agent::discord:slash:` - Slack: `agent::slack:slash:` (префікс налаштовується через `channels.slack.slashCommand.sessionPrefix`) - - Telegram: `telegram:slash:` (спрямовує до сесії чату через `CommandTargetSessionKey`) - - **`/stop`** спрямовується до активної сесії чату, щоб вона могла перервати поточний запуск. + - Telegram: `telegram:slash:` (спрямовує на чат-сесію через `CommandTargetSessionKey`) + - **`/stop`** спрямовується на активну чат-сесію, щоб мати змогу перервати поточний запуск. - - `channels.slack.slashCommand` і надалі підтримується для однієї команди у стилі `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити по одній slash-команді Slack для кожної вбудованої команди (ті самі назви, що й у `/help`). Меню аргументів команд для Slack надсилаються як ephemeral кнопки Block Kit. + + `channels.slack.slashCommand` і далі підтримується для однієї команди в стилі `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити одну slash-команду Slack для кожної вбудованої команди (з тими самими назвами, що й `/help`). Меню аргументів команд для Slack доставляються як ефемерні кнопки Block Kit. - Виняток для нативних команд Slack: зареєструйте `/agentstatus` (а не `/status`), оскільки Slack резервує `/status`. Текстова `/status` і далі працює в повідомленнях Slack. + Виняток для нативного Slack: зареєструйте `/agentstatus` (не `/status`), оскільки Slack резервує `/status`. Текстова `/status` і далі працює в повідомленнях Slack. -## Додаткові запитання BTW +## Побічні запитання BTW -`/btw` — це швидке **додаткове запитання** про поточну сесію. +`/btw` — це швидке **побічне запитання** про поточну сесію. На відміну від звичайного чату: - воно використовує поточну сесію як фоновий контекст, -- воно виконується як окремий одноразовий виклик **без інструментів**, -- воно не змінює майбутній контекст сесії, -- воно не записується в історію транскрипту, -- воно доставляється як живий побічний результат, а не як звичайне повідомлення асистента. +- виконується як окремий одноразовий виклик **без інструментів**, +- не змінює майбутній контекст сесії, +- не записується в історію транскрипта, +- доставляється як живий побічний результат, а не як звичайне повідомлення асистента. -Завдяки цьому `/btw` корисна, коли потрібне тимчасове уточнення, поки основне завдання продовжується. +Це робить `/btw` корисним, коли вам потрібне тимчасове уточнення, поки основне завдання триває. Приклад: @@ -477,7 +478,7 @@ Skills, які може викликати користувач, також до /btw what are we doing right now? ``` -Див. [Додаткові запитання BTW](/uk/tools/btw), щоб дізнатися повну поведінку та деталі UX клієнта. +Дивіться [Побічні запитання BTW](/uk/tools/btw), щоб дізнатися повну поведінку й деталі UX клієнта. ## Пов’язане diff --git a/docs/uk/tools/trajectory.md b/docs/uk/tools/trajectory.md index 78b54b14b..be60bd226 100644 --- a/docs/uk/tools/trajectory.md +++ b/docs/uk/tools/trajectory.md @@ -1,31 +1,37 @@ --- read_when: - - Налагодження того, чому агент відповів, завершився помилкою або викликав інструменти певним чином + - Налагодження того, чому агент відповів, зазнав невдачі або викликав інструменти певним чином - Експорт пакета підтримки для сеансу OpenClaw - Дослідження контексту промпта, викликів інструментів, помилок виконання або метаданих використання - - Вимкнення або перенесення запису траєкторій -summary: Експортуйте пакети траєкторій із вилученими чутливими даними для налагодження сеансу агента OpenClaw + - Вимкнення або перенесення захоплення траєкторії +summary: Експортуйте редаговані пакети траєкторій для налагодження сеансу агента OpenClaw title: Пакети траєкторій x-i18n: - generated_at: "2026-04-28T11:28:42Z" + generated_at: "2026-04-28T22:45:05Z" model: gpt-5.5 provider: openai - source_hash: df51c82ee5609ce19480c5b7f6fe037acda0e4ce927d5a748c9685c1809689d9 + source_hash: 8dad01b3662d5e75b7626eb7ed3c3ac2dce4e3a7db2ba5952d7086c721151d1f source_path: tools/trajectory.md workflow: 16 --- -Trajectory capture — це реєстратор перебігу для кожної сесії OpenClaw. Він записує +Захоплення траєкторії — це посесійний бортовий реєстратор OpenClaw. Воно записує структуровану часову шкалу для кожного запуску агента, а потім `/export-trajectory` пакує -поточну сесію в редагований пакет підтримки. +поточну сесію в редагований пакет для підтримки. -Використовуйте його, коли потрібно відповісти на такі запитання: +Використовуйте це, коли потрібно відповісти на такі запитання: -- Який prompt, system prompt і tools було надіслано моделі? -- Які повідомлення транскрипту й виклики tools привели до цієї відповіді? -- Чи завершився запуск через тайм-аут, переривання, compact, чи натрапив на помилку провайдера? -- Які модель, plugins, skills і параметри середовища виконання були активні? -- Які метадані usage і prompt-cache повернув провайдер? +- Які prompt, системний prompt і інструменти були надіслані моделі? +- Які повідомлення транскрипту й виклики інструментів призвели до цієї відповіді? +- Чи завершився запуск за тайм-аутом, був перерваний, ущільнений або натрапив на помилку провайдера? +- Які модель, плагіни, Skills і налаштування середовища виконання були активними? +- Які метадані використання та prompt-кешу повернув провайдер? + +Якщо ви подаєте широкий звіт до підтримки щодо live-проблеми Gateway, почніть із +[`/diagnostics`](/uk/gateway/diagnostics#chat-command). Діагностика збирає +санітизований пакет Gateway і, для сесій OpenAI Codex harness, також може надіслати +відгук Codex на сервери OpenAI після схвалення. Використовуйте `/export-trajectory`, коли +вам потрібна саме детальна посесійна часова шкала prompt, інструментів і транскрипту. ## Швидкий старт @@ -47,23 +53,37 @@ OpenClaw записує пакет у workspace: .openclaw/trajectory-exports/openclaw-trajectory--/ ``` -Можна вибрати відносну назву вихідного каталогу: +Ви можете вибрати відносну назву вихідного каталогу: ```text /export-trajectory bug-1234 ``` -Користувацький шлях розв’язується всередині `.openclaw/trajectory-exports/`. Абсолютні +Власний шлях розв’язується всередині `.openclaw/trajectory-exports/`. Абсолютні шляхи та шляхи з `~` відхиляються. +Пакети траєкторії можуть містити prompts, повідомлення моделі, схеми інструментів, результати +інструментів, події середовища виконання та локальні шляхи. Тому чат-команда зі slash щоразу +проходить через exec approval. Схваліть експорт один раз, коли маєте намір +створити пакет; не використовуйте allow-all. У групових чатах OpenClaw надсилає +запит на схвалення та результат експорту власнику приватно, замість того щоб публікувати +деталі траєкторії назад у спільну кімнату. + +Для локальної перевірки або процесів підтримки ви також можете напряму виконати схвалений +шлях команди: + +```bash +openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace . +``` + ## Доступ -Експорт траєкторії є командою власника. Відправник має пройти звичайні перевірки +Експорт траєкторії — це команда власника. Відправник має пройти звичайні перевірки авторизації команд і перевірки власника для каналу. ## Що записується -Trajectory capture увімкнено за замовчуванням для запусків агентів OpenClaw. +Захоплення траєкторії ввімкнене за замовчуванням для запусків агентів OpenClaw. Події середовища виконання включають: @@ -71,20 +91,20 @@ Trajectory capture увімкнено за замовчуванням для з - `trace.metadata` - `context.compiled` - `prompt.submitted` -- `model.fallback_step`, зокрема початкову модель, наступну модель, причину/деталі збою, позицію в ланцюжку та те, чи fallback просунувся, успішно завершився або вичерпав ланцюжок +- `model.fallback_step`, включно з вихідною моделлю, наступною моделлю, причиною/деталями помилки, позицією в ланцюжку та тим, чи fallback просунувся далі, успішно завершився або вичерпав ланцюжок - `model.completed` - `trace.artifacts` - `session.ended` -Події транскрипту також відтворюються з активної гілки сесії: +Події транскрипту також реконструюються з активної гілки сесії: - повідомлення користувача - повідомлення асистента -- виклики tools -- результати tools -- compactions +- виклики інструментів +- результати інструментів +- ущільнення - зміни моделі -- мітки та користувацькі записи сесії +- мітки та власні записи сесії Події записуються як JSON Lines із таким маркером схеми: @@ -104,11 +124,11 @@ Trajectory capture увімкнено за замовчуванням для з | `manifest.json` | Схема пакета, вихідні файли, кількість подій і список згенерованих файлів | | `events.jsonl` | Упорядкована часова шкала середовища виконання та транскрипту | | `session-branch.json` | Редагована активна гілка транскрипту та заголовок сесії | -| `metadata.json` | Версія OpenClaw, OS/середовище виконання, модель, знімок конфігурації, plugins, skills і метадані prompt | -| `artifacts.json` | Фінальний статус, помилки, usage, prompt cache, кількість compaction, текст асистента й метадані tools | +| `metadata.json` | Версія OpenClaw, ОС/середовище виконання, модель, знімок конфігурації, плагіни, Skills і метадані prompt | +| `artifacts.json` | Фінальний статус, помилки, використання, prompt-кеш, кількість ущільнень, текст асистента та метадані інструментів | | `prompts.json` | Надіслані prompts і вибрані деталі побудови prompt | -| `system-prompt.txt` | Останній скомпільований system prompt, якщо його захоплено | -| `tools.json` | Визначення tools, надіслані моделі, якщо їх захоплено | +| `system-prompt.txt` | Останній скомпільований системний prompt, якщо його захоплено | +| `tools.json` | Визначення інструментів, надіслані моделі, якщо їх захоплено | `manifest.json` перелічує файли, наявні в цьому пакеті. Деякі файли пропускаються, коли сесія не захопила відповідні дані середовища виконання. @@ -127,18 +147,18 @@ OpenClaw також записує best-effort файл-вказівник по .trajectory-path.json ``` -Установіть `OPENCLAW_TRAJECTORY_DIR`, щоб зберігати runtime trajectory sidecars у +Установіть `OPENCLAW_TRAJECTORY_DIR`, щоб зберігати sidecar-файли траєкторії середовища виконання у виділеному каталозі: ```bash export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories ``` -Коли цю змінну встановлено, OpenClaw записує один JSONL-файл на id сесії в цьому +Коли цю змінну встановлено, OpenClaw записує один JSONL-файл на кожен ідентифікатор сесії в цьому каталозі. -Обслуговування сесій видаляє trajectory sidecars, коли їхній власний запис сесії -обрізано, обмежено або витіснено дисковим бюджетом сесій. Файли середовища виконання поза +Обслуговування сесій видаляє sidecar-файли траєкторії, коли належний їм запис сесії +обрізається, обмежується або витісняється бюджетом диска для сесій. Файли середовища виконання поза каталогом сесій видаляються лише тоді, коли ціль вказівника все ще доводить, що вона належить цій сесії. @@ -150,52 +170,52 @@ export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories export OPENCLAW_TRAJECTORY=0 ``` -Це вимикає захоплення траєкторії середовища виконання. `/export-trajectory` усе ще може експортувати -гілку транскрипту, але файли лише середовища виконання, як-от скомпільований контекст, +Це вимикає захоплення траєкторії середовища виконання. `/export-trajectory` все ще може експортувати +гілку транскрипту, але файли, наявні лише під час виконання, як-от скомпільований контекст, артефакти провайдера та метадані prompt, можуть бути відсутні. -## Приватність і обмеження +## Конфіденційність і обмеження -Пакети траєкторії призначені для підтримки та налагодження, а не для публічної публікації. +Пакети траєкторії призначені для підтримки та налагодження, а не для публічного розміщення. OpenClaw редагує чутливі значення перед записом файлів експорту: - облікові дані та відомі поля payload, схожі на секрети - дані зображень -- шляхи локального стану +- локальні шляхи стану - шляхи workspace, замінені на `$WORKSPACE_DIR` -- шляхи домашнього каталогу, коли їх виявлено +- шляхи домашнього каталогу, якщо їх виявлено Експортер також обмежує розмір вхідних даних: -- runtime sidecar файли: 50 MiB -- файли сесій: 50 MiB -- події середовища виконання: 200,000 -- загалом експортованих подій: 250,000 -- окремі рядки подій середовища виконання обрізаються понад 256 KiB +- runtime sidecar files: 50 MiB +- session files: 50 MiB +- runtime events: 200,000 +- total exported events: 250,000 +- окремі рядки подій середовища виконання обрізаються, якщо перевищують 256 KiB -Переглядайте пакети перед передаванням їх за межі вашої команди. Редагування є best-effort +Переглядайте пакети перед тим, як ділитися ними поза своєю командою. Редагування є best-effort і не може знати кожен секрет, специфічний для застосунку. ## Усунення несправностей -Якщо в експорті немає подій середовища виконання: +Якщо експорт не має подій середовища виконання: - підтвердьте, що OpenClaw було запущено без `OPENCLAW_TRAJECTORY=0` -- перевірте, чи `OPENCLAW_TRAJECTORY_DIR` вказує на каталог із правом запису -- надішліть ще одне повідомлення в сесії, а потім експортуйте знову +- перевірте, чи `OPENCLAW_TRAJECTORY_DIR` вказує на каталог, доступний для запису +- виконайте ще одне повідомлення в сесії, а потім експортуйте знову - перевірте `manifest.json` на `runtimeEventCount` Якщо команда відхиляє вихідний шлях: -- використовуйте відносну назву, як-от `bug-1234` +- використовуйте відносну назву, наприклад `bug-1234` - не передавайте `/tmp/...` або `~/...` - тримайте експорт усередині `.openclaw/trajectory-exports/` Якщо експорт завершується помилкою розміру, сесія або sidecar перевищили -безпечні обмеження експорту. Почніть нову сесію або експортуйте менше відтворення. +безпечні ліміти експорту. Почніть нову сесію або експортуйте менше відтворення. ## Пов’язане - [Diffs](/uk/tools/diffs) - [Керування сесіями](/uk/concepts/session) -- [Exec tool](/uk/tools/exec) +- [Інструмент Exec](/uk/tools/exec)