chore(i18n): refresh uk translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-24 18:48:12 +00:00
parent 1f993555a6
commit 02bdca2309
2 changed files with 451 additions and 445 deletions

View File

@ -1,28 +1,28 @@
---
read_when:
- Налаштування значень агента за замовчуванням (моделі, thinking, робочий простір, Heartbeat, медіа, Skills)
- Налаштування маршрутизації та прив’язок для кількох агентів
- Налаштування поведінки сесій, доставки повідомлень і режиму talk
summary: Значення за замовчуванням для агента, маршрутизація кількох агентів, сесія, повідомлення та конфігурація talk
- Налаштування маршрутизації між кількома агентами та прив’язок
- Налаштування поведінки сесії, доставки повідомлень і режиму talk
summary: Значення агента за замовчуванням, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk
title: Конфігурація — агенти
x-i18n:
generated_at: "2026-04-24T03:44:07Z"
generated_at: "2026-04-24T18:44:26Z"
model: gpt-5.4
provider: openai
source_hash: de1587358404808b4a11a92a9392d7cc5bdd2b599773f8a0f7b4331551841991
source_hash: 85840fbc565a3d7d79a9ccaf20132225aa2a363d7ca6c6964e219b561235d183
source_path: gateway/config-agents.md
workflow: 15
---
Ключі конфігурації на рівні агента в `agents.*`, `multiAgent.*`, `session.*`,
`messages.*` і `talk.*`. Для каналів, інструментів, runtime Gateway та інших
ключів верхнього рівня див. [Configuration reference](/uk/gateway/configuration-reference).
Ключі конфігурації в межах агента під `agents.*`, `multiAgent.*`, `session.*`,
`messages.*` і `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших
ключів верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference).
## Значення агента за замовчуванням
### `agents.defaults.workspace`
Типово: `~/.openclaw/workspace`.
За замовчуванням: `~/.openclaw/workspace`.
```json5
{
@ -32,7 +32,7 @@ x-i18n:
### `agents.defaults.repoRoot`
Необов’язковий корінь репозиторію, який показується в рядку Runtime системного prompt. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору.
Необов’язковий кореневий каталог репозиторію, який показується в рядку Runtime системного запиту. Якщо не вказано, OpenClaw автоматично визначає його, піднімаючись угору від робочого простору.
```json5
{
@ -42,7 +42,7 @@ x-i18n:
### `agents.defaults.skills`
Необов’язковий allowlist Skills за замовчуванням для агентів, які не задають
Необов’язковий типовий список дозволених Skills для агентів, які не задають
`agents.list[].skills`.
```json5
@ -58,15 +58,15 @@ x-i18n:
}
```
- Не вказуйте `agents.defaults.skills`, щоб типово дозволити необмежені Skills.
- Не вказуйте `agents.defaults.skills`, щоб Skills за замовчуванням були без обмежень.
- Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням.
- Установіть `agents.list[].skills: []`, щоб не було Skills.
- Встановіть `agents.list[].skills: []`, щоб не було Skills.
- Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він
не об’єднується зі значеннями за замовчуванням.
### `agents.defaults.skipBootstrap`
Вимикає автоматичне створення bootstrap-файлів робочого простору (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
Вимикає автоматичне створення файлів початкового налаштування робочого простору (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
```json5
{
@ -76,9 +76,9 @@ x-i18n:
### `agents.defaults.contextInjection`
Керує тим, коли bootstrap-файли робочого простору інжектуються в системний prompt. Типово: `"always"`.
Керує тим, коли файли початкового налаштування робочого простору додаються до системного запиту. За замовчуванням: `"always"`.
- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторну інжекцію bootstrap робочого простору, зменшуючи розмір prompt. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст.
- `"continuation-skip"`: у безпечних ходах продовження (після завершеної відповіді асистента) повторне додавання bootstrap-файлів робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст.
```json5
{
@ -88,7 +88,7 @@ x-i18n:
### `agents.defaults.bootstrapMaxChars`
Максимальна кількість символів на один bootstrap-файл робочого простору до усікання. Типово: `12000`.
Максимальна кількість символів для кожного bootstrap-файлу робочого простору до обрізання. За замовчуванням: `12000`.
```json5
{
@ -98,7 +98,7 @@ x-i18n:
### `agents.defaults.bootstrapTotalMaxChars`
Максимальна загальна кількість символів, що інжектуються з усіх bootstrap-файлів робочого простору. Типово: `60000`.
Максимальна загальна кількість символів, що додаються з усіх bootstrap-файлів робочого простору. За замовчуванням: `60000`.
```json5
{
@ -108,12 +108,12 @@ x-i18n:
### `agents.defaults.bootstrapPromptTruncationWarning`
Керує видимим агенту текстом попередження, коли bootstrap-контекст усічено.
Типово: `"once"`.
Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається.
За замовчуванням: `"once"`.
- `"off"`: ніколи не інжектувати текст попередження в системний prompt.
- `"once"`: інжектувати попередження один раз для кожного унікального сигнатурного усікання (рекомендовано).
- `"always"`: інжектувати попередження під час кожного запуску, коли є усікання.
- `"off"`: ніколи не додавати текст попередження до системного запиту.
- `"once"`: додавати попередження один раз для кожного унікального сигнатурного набору обрізання (рекомендовано).
- `"always"`: додавати попередження при кожному запуску, коли є обрізання.
```json5
{
@ -121,26 +121,26 @@ x-i18n:
}
```
### Карта власності бюджету контексту
### Карта володіння бюджетами контексту
OpenClaw має кілька великих бюджетів prompt/контексту, і вони
навмисно розділені за підсистемами, а не проходять через один загальний
перемикач.
OpenClaw має кілька великих бюджетів запиту/контексту, і вони
навмисно розділені між підсистемами, замість того щоб усі проходили через один
загальний параметр.
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`:
звичайна інжекція bootstrap робочого простору.
звичайне додавання bootstrap-даних робочого простору.
- `agents.defaults.startupContext.*`:
одноразова стартова преамбула для `/new` і `/reset`, включно з недавніми щоденними
файлами `memory/*.md`.
одноразовий стартовий прелюд для `/new` і `/reset`, зокрема нещодавні
файли `memory/*.md` за днями.
- `skills.limits.*`:
компактний список Skills, інжектований у системний prompt.
компактний список Skills, що додається до системного запиту.
- `agents.defaults.contextLimits.*`:
обмежені runtime-уривки та інжектовані блоки, якими володіє runtime.
обмежені витяги середовища виконання та додані блоки, що належать runtime.
- `memory.qmd.limits.*`:
розмір фрагментів і інжекції для індексованого пошуку по пам’яті.
розмір фрагментів індексованого пошуку пам’яті та додавання їх до контексту.
Використовуйте відповідне перевизначення для конкретного агента лише тоді, коли одному агенту потрібен інший
Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший
бюджет:
- `agents.list[].skillsLimits.maxSkillsPromptChars`
@ -148,7 +148,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
#### `agents.defaults.startupContext`
Керує стартовою преамбулою першого ходу, яка інжектується під час запусків bare `/new` і `/reset`.
Керує стартовим прелюдом першого ходу, який додається під час порожніх запусків `/new` і `/reset`.
```json5
{
@ -186,16 +186,18 @@ OpenClaw має кілька великих бюджетів prompt/контек
}
```
- `memoryGetMaxChars`: типовий ліміт уривка `memory_get` до додавання метаданих
усікання та повідомлення про продовження.
- `memoryGetDefaultLines`: типове вікно рядків для `memory_get`, коли `lines`
- `memoryGetMaxChars`: типовий ліміт витягу `memory_get` перед додаванням метаданих
обрізання та повідомлення про продовження.
- `memoryGetDefaultLines`: типове вікно рядків для `memory_get`, якщо `lines`
не вказано.
- `toolResultMaxChars`: поточний ліміт результатів інструментів, який використовується для збережених результатів і відновлення після переповнення.
- `postCompactionMaxChars`: ліміт уривка AGENTS.md, який використовується під час інжекції оновлення після Compaction.
- `toolResultMaxChars`: поточний ліміт результату інструмента, що використовується для збережених результатів і
відновлення після переповнення.
- `postCompactionMaxChars`: ліміт витягу AGENTS.md, який використовується під час додавання
оновлення після Compaction.
#### `agents.list[].contextLimits`
Перевизначення на рівні агента для спільних перемикачів `contextLimits`. Невказані поля успадковуються
Перевизначення для окремого агента для спільних параметрів `contextLimits`. Поля, які не вказано, успадковуються
з `agents.defaults.contextLimits`.
```json5
@ -222,7 +224,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
#### `skills.limits.maxSkillsPromptChars`
Глобальний ліміт для компактного списку Skills, інжектованого в системний prompt. Це
Глобальний ліміт для компактного списку Skills, що додається до системного запиту. Це
не впливає на читання файлів `SKILL.md` на вимогу.
```json5
@ -237,7 +239,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
#### `agents.list[].skillsLimits.maxSkillsPromptChars`
Перевизначення на рівні агента для бюджету prompt Skills.
Перевизначення для окремого агента для бюджету запиту Skills.
```json5
{
@ -256,11 +258,11 @@ OpenClaw має кілька великих бюджетів prompt/контек
### `agents.defaults.imageMaxDimensionPx`
Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера.
Типово: `1200`.
Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень транскрипту/інструментів перед викликами провайдера.
За замовчуванням: `1200`.
Нижчі значення зазвичай зменшують використання vision-токенів і розмір payload запиту для запусків із великою кількістю знімків екрана.
Вищі значення зберігають більше візуальних деталей.
Менші значення зазвичай зменшують використання vision-токенів і розмір тіла запиту для сценаріїв із великою кількістю скриншотів.
Більші значення зберігають більше візуальних деталей.
```json5
{
@ -270,7 +272,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
### `agents.defaults.userTimezone`
Часовий пояс для контексту системного prompt (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста.
Часовий пояс для контексту системного запиту (не міток часу повідомлень). Якщо не вказано, використовується часовий пояс хоста.
```json5
{
@ -280,7 +282,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
### `agents.defaults.timeFormat`
Формат часу в системному prompt. Типово: `auto` (налаштування ОС).
Формат часу в системному запиті. За замовчуванням: `auto` (параметри ОС).
```json5
{
@ -318,9 +320,9 @@ OpenClaw має кілька великих бюджетів prompt/контек
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.4-mini"],
},
params: { cacheRetention: "long" }, // глобальні параметри провайдера за замовчуванням
params: { cacheRetention: "long" }, // глобальні типові параметри провайдера
embeddedHarness: {
runtime: "auto", // auto | pi | зареєстрований id harness, наприклад codex
runtime: "auto", // auto | pi | зареєстрований ідентифікатор harness, наприклад codex
fallback: "pi", // pi | none
},
pdfMaxBytesMb: 10,
@ -339,50 +341,50 @@ OpenClaw має кілька великих бюджетів prompt/контек
- `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Форма рядка задає лише основну модель.
- Форма об’єкта задає основну модель плюс упорядковані failover-моделі.
- Форма об’єкта задає основну модель і впорядкований список резервних моделей.
- `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується шляхом інструмента `image` як конфігурація vision-моделі.
- Також використовується як fallback-маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення.
- Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати вхідні зображення.
- `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею tool/plugin, що генерує зображення.
- Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення.
- Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images.
- Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`).
- Якщо параметр пропущено, `image_generate` усе одно може вивести типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації зображень у порядку id провайдера.
- Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`).
- Якщо не вказано, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів.
- `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`.
- Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`.
- Якщо параметр пропущено, `music_generate` усе одно може вивести типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації музики в порядку id провайдера.
- Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key.
- Якщо не вказано, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів.
- Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API-ключ.
- `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`.
- Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`.
- Якщо параметр пропущено, `video_generate` усе одно може вивести типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації відео в порядку id провайдера.
- Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key.
- Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`.
- Якщо не вказано, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів.
- Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API-ключ.
- Вбудований провайдер генерації відео Qwen підтримує не більше ніж 1 вихідне відео, 1 вхідне зображення, 4 вхідних відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`.
- `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується інструментом `pdf` для маршрутизації моделей.
- Якщо параметр пропущено, інструмент PDF повертається до `imageModel`, а потім до визначеної моделі сесії/типової моделі.
- Використовується інструментом `pdf` для маршрутизації моделі.
- Якщо не вказано, інструмент PDF використовує `imageModel`, а потім визначену модель сесії/типову модель.
- `pdfMaxBytesMb`: типовий ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику.
- `pdfMaxPages`: типова максимальна кількість сторінок, яку враховує режим fallback-витягування в інструменті `pdf`.
- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типово: `"off"`.
- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типово: `"on"`.
- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4` для доступу через API key або `openai-codex/gpt-5.5` для Codex OAuth). Якщо ви не вкажете провайдера, OpenClaw спочатку спробує alias, потім унікальний збіг exact model id серед налаштованих провайдерів і лише після цього повернеться до налаштованого провайдера за замовчуванням (застаріла поведінка для сумісності, тому краще вказувати явний `provider/model`). Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw повернеться до першої налаштованої пари provider/model замість того, щоб показувати застаріле типове значення від видаленого провайдера.
- `models`: налаштований каталог моделей і allowlist для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`).
- Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додавати записи. `config set` відмовляється від замін, які вилучили б наявні записи allowlist, якщо не передати `--replace`.
- Потоки configure/onboarding на рівні провайдера об’єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштованих непов’язаних провайдерів.
- Для прямих моделей OpenAI Responses компакція на стороні сервера вмикається автоматично. Використовуйте `params.responsesServerCompaction: false`, щоб припинити інжекцію `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [OpenAI server-side compaction](/uk/providers/openai#server-side-compaction-responses-api).
- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`).
- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. [Prompt Caching](/uk/reference/prompt-caching).
- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим plugin harness брати на себе підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний fallback до PI.
- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта та, за можливості, зберігають наявні списки fallback.
- `maxConcurrent`: максимальна кількість паралельних запусків агента між сесіями (кожна сесія все одно серіалізується). Типово: 4.
- `pdfMaxPages`: типова максимальна кількість сторінок, яку враховує резервний режим витягування в інструменті `pdf`.
- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. За замовчуванням: `"off"`.
- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. За замовчуванням: `"on"`.
- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо не вказати провайдера, OpenClaw спочатку пробує alias, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі і лише після цього переходить до типового налаштованого провайдера (застаріла сумісна поведінка, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення від видаленого провайдера.
- `models`: каталог налаштованих моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`).
- Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додати записи. `config set` відхиляє заміни, які видалили б наявні записи зі списку дозволених значень, якщо ви не передали `--replace`.
- Потоки налаштування/онбордингу на рівні провайдера об’єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштованих, не пов’язаних із цим, провайдерів.
- Для прямих моделей OpenAI Responses серверний Compaction вмикається автоматично. Використовуйте `params.responsesServerCompaction: false`, щоб припинити додавання `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Докладніше див. у [Серверний Compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api).
- `params`: глобальні типові параметри провайдера, які застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`).
- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає значення за ключами. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching).
- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим harness із Plugin брати на себе підтримувані моделі, `runtime: "pi"` — щоб примусово використовувати вбудований PI harness, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Встановіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. Нові конфігурації Codex harness повинні зберігати посилання на моделі в канонічному форматі `openai/*` і вибирати harness тут, а не використовувати застарілі посилання на моделі `codex/*`.
- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну форму об’єкта і, коли можливо, зберігають наявні списки резервних моделей.
- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). За замовчуванням: 4.
### `agents.defaults.embeddedHarness`
`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента.
У більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`.
Використовуйте це, коли довірений plugin надає нативний harness, наприклад вбудований
harness app-server Codex.
`embeddedHarness` визначає, який низькорівневий виконавець запускає ходи вбудованого агента.
Для більшості розгортань слід залишати типове значення `{ runtime: "auto", fallback: "pi" }`.
Використовуйте його, коли довірений Plugin надає нативний harness, наприклад вбудований
harness сервера застосунку Codex.
```json5
{
@ -398,35 +400,35 @@ harness app-server Codex.
}
```
- `runtime`: `"auto"`, `"pi"` або id зареєстрованого plugin harness. Вбудований plugin Codex реєструє `codex`.
- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як fallback для сумісності, коли не вибрано жодного plugin harness. `"none"` змушує відсутній або непідтримуваний вибір plugin harness завершуватися помилкою замість тихого використання PI. Збої вибраного plugin harness завжди показуються напряму.
- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає fallback до PI для цього процесу.
- Для розгортань лише з Codex установіть `model: "openai/gpt-5.5"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`.
- Вибір harness фіксується для кожного id сесії після першого вбудованого запуску. Зміни config/env впливають на нові або скинуті сесії, але не на наявний transcript. Застарілі сесії з історією transcript, але без зафіксованого значення, вважаються прив’язаними до PI. `/status` показує id harness, відмінні від PI, наприклад `codex`, поруч із `Fast`.
- Це керує лише вбудованим harness чату. Генерація медіа, vision, PDF, музики, відео та TTS усе ще використовують свої налаштування provider/model.
- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого harness із Plugin. Вбудований Plugin Codex реєструє `codex`.
- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований PI harness як сумісний резервний варіант, коли не вибрано жодного harness із Plugin. `"none"` призводить до помилки, якщо вибраний harness із Plugin відсутній або не підтримується, замість тихого використання PI. Помилки вибраного harness із Plugin завжди показуються безпосередньо.
- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу.
- Для розгортань лише з Codex встановіть `model: "openai/gpt-5.5"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`.
- Вибір harness закріплюється за ідентифікатором сесії після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сесії, але не на наявний транскрипт. Застарілі сесії з історією транскрипту, але без записаного закріплення, вважаються закріпленими за PI. `/status` показує ідентифікатори harness, відмінні від PI, наприклад `codex`, поруч із `Fast`.
- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео і TTS, як і раніше, використовують свої параметри провайдер/модель.
**Вбудовані alias-скорочення** (застосовуються лише тоді, коли модель є в `agents.defaults.models`):
**Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`):
| Alias | Модель |
| ------------------- | -------------------------------------------------- |
| `opus` | `anthropic/claude-opus-4-6` |
| `sonnet` | `anthropic/claude-sonnet-4-6` |
| `gpt` | `openai/gpt-5.4` або налаштований Codex OAuth GPT-5.5 |
| `gpt` | `openai/gpt-5.4` або налаштована Codex OAuth GPT-5.5 |
| `gpt-mini` | `openai/gpt-5.4-mini` |
| `gpt-nano` | `openai/gpt-5.4-nano` |
| `gemini` | `google/gemini-3.1-pro-preview` |
| `gemini-flash` | `google/gemini-3-flash-preview` |
| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
Ваші налаштовані alias завжди мають пріоритет над типовими.
Налаштовані вами alias завжди мають пріоритет над типовими.
Для моделей Z.AI GLM-4.x режим thinking вмикається автоматично, якщо ви не встановите `--thinking off` або самостійно не задасте `agents.defaults.models["zai/<model>"].params.thinking`.
Для моделей Z.AI за замовчуванням увімкнено `tool_stream` для потокового передавання викликів інструментів. Установіть `agents.defaults.models["zai/<model>"].params.tool_stream` у `false`, щоб вимкнути його.
Для моделей Z.AI `tool_stream` увімкнено за замовчуванням для потокової передачі викликів інструментів. Встановіть `agents.defaults.models["zai/<model>"].params.tool_stream` у `false`, щоб вимкнути це.
Для моделей Anthropic Claude 4.6 за замовчуванням використовується thinking `adaptive`, якщо не задано явний рівень thinking.
### `agents.defaults.cliBackends`
Необов’язкові CLI backends для text-only fallback-запусків (без викликів інструментів). Корисно як резервний варіант, коли API-провайдери недоступні.
Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють.
```json5
{
@ -454,13 +456,13 @@ harness app-server Codex.
}
```
- CLI backends орієнтовані насамперед на текст; інструменти завжди вимкнені.
- Сесії підтримуються, коли задано `sessionArg`.
- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів.
- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені.
- Сесії підтримуються, якщо задано `sessionArg`.
- Передавання зображень підтримується, якщо `imageArg` приймає шляхи до файлів.
### `agents.defaults.systemPromptOverride`
Замінює весь системний prompt, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із prompt.
Замінює весь системний запит, зібраний OpenClaw, на фіксований рядок. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами.
```json5
{
@ -474,7 +476,7 @@ harness app-server Codex.
### `agents.defaults.promptOverlays`
Незалежні від провайдера накладки prompt, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний поведінковий контракт між провайдерами; `personality` керує лише дружнім шаром стилю взаємодії.
Незалежні від провайдера накладки запитів, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії.
```json5
{
@ -490,9 +492,9 @@ harness app-server Codex.
}
```
- `"friendly"` (типово) і `"on"` вмикають дружній шар стилю взаємодії.
- `"off"` вимикає лише дружній шар; позначений поведінковий контракт GPT-5 залишається ввімкненим.
- Застарілий `plugins.entries.openai.config.personality` усе ще читається, коли це спільне налаштування не задано.
- `"friendly"` (типово) і `"on"` вмикають шар дружнього стилю взаємодії.
- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається увімкненим.
- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, якщо цей спільний параметр не задано.
### `agents.defaults.heartbeat`
@ -506,13 +508,13 @@ harness app-server Codex.
every: "30m", // 0m вимикає
model: "openai/gpt-5.4-mini",
includeReasoning: false,
includeSystemPromptSection: true, // типово: true; false прибирає секцію Heartbeat із системного prompt
lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору
isolatedSession: false, // типово: false; true запускає кожен Heartbeat у новій сесії (без історії розмови)
includeSystemPromptSection: true, // за замовчуванням: true; false не додає розділ Heartbeat до системного запиту
lightContext: false, // за замовчуванням: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору
isolatedSession: false, // за замовчуванням: false; true запускає кожен heartbeat у новій сесії (без історії розмови)
session: "main",
to: "+15555550123",
directPolicy: "allow", // allow (типово) | block
target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ...
directPolicy: "allow", // allow (за замовчуванням) | block
target: "none", // за замовчуванням: none | варіанти: last | whatsapp | telegram | discord | ...
prompt: "Read HEARTBEAT.md if it exists...",
ackMaxChars: 300,
suppressToolErrorWarnings: false,
@ -523,15 +525,15 @@ harness app-server Codex.
}
```
- `every`: рядок тривалості (ms/s/m/h). Типово: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути.
- `includeSystemPromptSection`: коли `false`, прибирає секцію Heartbeat із системного prompt і пропускає інжекцію `HEARTBEAT.md` у bootstrap-контекст. Типово: `true`.
- `suppressToolErrorWarnings`: коли `true`, пригнічує payload попереджень про помилки інструментів під час запусків Heartbeat.
- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat до його переривання. Залиште незаданим, щоб використовувати `agents.defaults.timeoutSeconds`.
- `directPolicy`: політика прямої доставки/доставки в приватні повідомлення. `allow` (типово) дозволяє доставку за прямою ціллю. `block` пригнічує доставку за прямою ціллю та виводить `reason=dm-blocked`.
- `lightContext`: коли `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору.
- `isolatedSession`: коли `true`, кожен Heartbeat запускається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує вартість одного Heartbeat за токенами приблизно зі ~100K до ~25K токенів.
- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, Heartbeat запускаються **лише для цих агентів**.
- Heartbeat запускають повні ходи агента — коротші інтервали спалюють більше токенів.
- `every`: рядок тривалості (ms/s/m/h). За замовчуванням: `30m` (автентифікація через API-ключ) або `1h` (автентифікація через OAuth). Встановіть `0m`, щоб вимкнути.
- `includeSystemPromptSection`: якщо `false`, не додає розділ Heartbeat до системного запиту і пропускає додавання `HEARTBEAT.md` до bootstrap-контексту. За замовчуванням: `true`.
- `suppressToolErrorWarnings`: якщо `true`, пригнічує корисне навантаження попереджень про помилки інструментів під час запусків heartbeat.
- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після чого його буде перервано. Якщо не вказано, використовується `agents.defaults.timeoutSeconds`.
- `directPolicy`: політика доставки напряму/в особисті повідомлення. `allow` (за замовчуванням) дозволяє доставку безпосередньо цілі. `block` пригнічує доставку безпосередньо цілі та генерує `reason=dm-blocked`.
- `lightContext`: якщо `true`, запуски heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору.
- `isolatedSession`: якщо `true`, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів.
- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, **heartbeat запускаються лише для цих агентів**.
- Heartbeat виконують повноцінні ходи агента — коротші інтервали спалюють більше токенів.
### `agents.defaults.compaction`
@ -541,14 +543,14 @@ harness app-server Codex.
defaults: {
compaction: {
mode: "safeguard", // default | safeguard
provider: "my-provider", // id зареєстрованого Plugin провайдера Compaction (необов’язково)
provider: "my-provider", // id зареєстрованого Plugin провайдера compaction (необов’язково)
timeoutSeconds: 900,
reserveTokensFloor: 24000,
identifierPolicy: "strict", // strict | off | custom
identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom
postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторну інжекцію
model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для Compaction
notifyUser: true, // надсилати короткі сповіщення користувачу, коли Compaction починається і завершується (типово: false)
postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне додавання
model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction
notifyUser: true, // надсилати короткі сповіщення користувачу, коли compaction починається і завершується (за замовчуванням: false)
memoryFlush: {
enabled: true,
softThresholdTokens: 6000,
@ -561,15 +563,15 @@ harness app-server Codex.
}
```
- `mode`: `default` або `safeguard` (підсумовування довгих історій частинами). Див. [Compaction](/uk/concepts/compaction).
- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого LLM-підсумовування викликається `summarize()` цього провайдера. У разі помилки відбувається fallback до вбудованого. Установлення провайдера примусово вмикає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction).
- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction до того, як OpenClaw перерве її. Типово: `900`.
- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування Compaction.
- `identifierInstructions`: необов’язковий власний текст для збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`.
- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md для повторної інжекції після Compaction. Типово `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторну інжекцію. Якщо значення не задано або явно встановлено цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий fallback.
- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки Compaction — виконуватися на іншій; якщо не задано, Compaction використовує основну модель сесії.
- `notifyUser`: коли `true`, надсилає короткі сповіщення користувачу, коли Compaction починається і завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction залишався тихим.
- `memoryFlush`: тихий хід агента перед автоматичним Compaction для збереження довготривалої пам’яті. Пропускається, коли робочий простір доступний лише для читання.
- `mode`: `default` або `safeguard` (підсумовування частинами для довгих історій). Див. [Compaction](/uk/concepts/compaction).
- `provider`: id зареєстрованого Plugin провайдера compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` цього провайдера. У разі помилки повертається до вбудованого механізму. Встановлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction).
- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. За замовчуванням: `900`.
- `identifierPolicy`: `strict` (за замовчуванням), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування compaction.
- `identifierInstructions`: необов’язковий власний текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`.
- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md, які потрібно повторно додати після compaction. За замовчуванням `["Session Startup", "Red Lines"]`; встановіть `[]`, щоб вимкнути повторне додавання. Якщо значення не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як резервний варіант для сумісності.
- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки compaction повинні виконуватися на іншій; якщо не задано, compaction використовує основну модель сесії.
- `notifyUser`: якщо `true`, надсилає користувачу короткі сповіщення, коли compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). За замовчуванням вимкнено, щоб compaction залишався непомітним.
- `memoryFlush`: тихий агентний хід перед автоматичним compaction для збереження довготривалої пам’яті. Пропускається, якщо робочий простір доступний лише для читання.
### `agents.defaults.contextPruning`
@ -581,7 +583,7 @@ harness app-server Codex.
defaults: {
contextPruning: {
mode: "cache-ttl", // off | cache-ttl
ttl: "1h", // тривалість (ms/s/m/h), типова одиниця: хвилини
ttl: "1h", // тривалість (ms/s/m/h), одиниця за замовчуванням: хвилини
keepLastAssistants: 3,
softTrimRatio: 0.3,
hardClearRatio: 0.5,
@ -603,19 +605,19 @@ harness app-server Codex.
**М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині.
**Повне очищення** замінює весь результат інструмента заповнювачем.
**Повне очищення** замінює весь результат інструмента на заповнювач.
Примітки:
- Блоки зображень ніколи не обрізаються і не очищаються.
- Співвідношення базуються на символах (приблизно), а не на точних кількостях токенів.
- Якщо повідомлень асистента менше, ніж `keepLastAssistants`, обрізання пропускається.
- Співвідношення базуються на кількості символів (приблизно), а не на точній кількості токенів.
- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається.
</Accordion>
Докладніше про поведінку див. [Session Pruning](/uk/concepts/session-pruning).
Докладніше про поведінку див. у [Обрізання сесії](/uk/concepts/session-pruning).
### Block streaming
### Блокове потокове передавання
```json5
{
@ -631,13 +633,13 @@ harness app-server Codex.
}
```
- Для каналів, відмінних від Telegram, потрібне явне `*.blockStreaming: true`, щоб увімкнути відповіді блоками.
- Перевизначення для каналів: `channels.<channel>.blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`.
- `humanDelay`: випадкова пауза між блоками відповіді. `natural` = 8002500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`.
- Канали, окрім Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути відповіді блоками.
- Перевизначення для каналів: `channels.<channel>.blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat за замовчуванням `minChars: 1500`.
- `humanDelay`: випадкова пауза між відповідями блоками. `natural` = 8002500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`.
Докладніше про поведінку та розбиття див. [Streaming](/uk/concepts/streaming).
Докладніше про поведінку та розбиття на блоки див. у [Потокове передавання](/uk/concepts/streaming).
### Індикатори набору
### Індикатори набору тексту
```json5
{
@ -650,16 +652,16 @@ harness app-server Codex.
}
```
- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадок.
- Перевизначення для окремих сесій: `session.typingMode`, `session.typingIntervalSeconds`.
- Значення за замовчуванням: `instant` для прямих чатів/згадок, `message` для групових чатів без згадок.
- Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`.
Див. [Typing Indicators](/uk/concepts/typing-indicators).
Див. [Індикатори набору тексту](/uk/concepts/typing-indicators).
<a id="agentsdefaultssandbox"></a>
### `agents.defaults.sandbox`
Необов’язкова Sandbox-ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing).
Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у [Ізоляція](/uk/gateway/sandboxing).
```json5
{
@ -754,24 +756,24 @@ harness app-server Codex.
}
```
<Accordion title="Деталі Sandbox">
<Accordion title="Деталі sandbox">
**Backend:**
- `docker`: локальний runtime Docker (типово)
- `ssh`: універсальний віддалений runtime через SSH
- `openshell`: runtime OpenShell
- `docker`: локальне середовище виконання Docker (за замовчуванням)
- `ssh`: загальне віддалене середовище виконання на основі SSH
- `openshell`: середовище виконання OpenShell
Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться в
Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться до
`plugins.entries.openshell.config`.
**Конфігурація SSH backend:**
- `target`: ціль SSH у форматі `user@host[:port]`
- `command`: команда SSH-клієнта (типово: `ssh`)
- `workspaceRoot`: абсолютний віддалений корінь для робочих просторів за scope
- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються до OpenSSH
- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує в тимчасові файли під час runtime
- `command`: команда SSH-клієнта (за замовчуванням: `ssh`)
- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах області видимості
- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані до OpenSSH
- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, який OpenClaw матеріалізує у тимчасові файли під час виконання
- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH
**Пріоритет автентифікації SSH:**
@ -779,26 +781,26 @@ harness app-server Codex.
- `identityData` має пріоритет над `identityFile`
- `certificateData` має пріоритет над `certificateFile`
- `knownHostsData` має пріоритет над `knownHostsFile`
- Значення `*Data`, що використовують SecretRef, визначаються з активного знімка runtime секретів перед стартом Sandbox-сесії
- Значення `*Data` на основі SecretRef визначаються з активного знімка середовища виконання секретів до початку сесії sandbox
**Поведінка SSH backend:**
- один раз засіває віддалений робочий простір після створення або повторного створення
- потім зберігає віддалений робочий простір SSH як канонічний
- маршрутизує `exec`, файлові інструменти й шляхи медіа через SSH
- не синхронізує віддалені зміни назад на хост автоматично
- не підтримує browser-контейнери Sandbox
- один раз ініціалізує віддалений робочий простір після створення або повторного створення
- потім підтримує віддалений робочий простір SSH як канонічний
- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH
- не синхронізує автоматично віддалені зміни назад на хост
- не підтримує браузерні контейнери sandbox
**Доступ до робочого простору:**
- `none`: робочий простір Sandbox за scope у `~/.openclaw/sandboxes`
- `ro`: робочий простір Sandbox у `/workspace`, робочий простір агента монтується лише для читання в `/agent`
- `rw`: робочий простір агента монтується для читання/запису в `/workspace`
- `none`: робочий простір sandbox у межах області видимості під `~/.openclaw/sandboxes`
- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента змонтовано лише для читання в `/agent`
- `rw`: робочий простір агента змонтовано для читання/запису в `/workspace`
**Scope:**
**Область видимості:**
- `session`: окремий контейнер + робочий простір для кожної сесії
- `agent`: один контейнер + робочий простір на агента (типово)
- `session`: окремий контейнер і робочий простір на сесію
- `agent`: один контейнер і робочий простір на агента (за замовчуванням)
- `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями)
**Конфігурація Plugin OpenShell:**
@ -829,32 +831,32 @@ harness app-server Codex.
**Режим OpenShell:**
- `mirror`: перед `exec` віддалений простір засівається з локального, після `exec` синхронізується назад; локальний робочий простір залишається канонічним
- `remote`: віддалений простір засівається один раз під час створення Sandbox, після чого канонічним залишається віддалений робочий простір
- `mirror`: ініціалізує віддалений простір із локального перед exec, синхронізує назад після exec; локальний робочий простір залишається канонічним
- `remote`: один раз ініціалізує віддалений простір під час створення sandbox, після чого віддалений робочий простір залишається канонічним
У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються в Sandbox автоматично після кроку засівання.
Транспортом є SSH у Sandbox OpenShell, але Plugin керує життєвим циклом Sandbox і необов’язковою дзеркальною синхронізацією.
У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються автоматично в sandbox після кроку ініціалізації.
Транспортом є SSH у sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією.
**`setupCommand`** запускається один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, кореневої файлової системи з можливістю запису та користувача root.
**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, записуваного кореня та користувача root.
**Типово контейнери мають `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ.
`"host"` заблоковано. `"container:<id>"` типово заблоковано, якщо ви явно не встановите
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим).
**Для контейнерів за замовчуванням встановлено `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ.
`"host"` заблоковано. `"container:<id>"` також заблоковано за замовчуванням, якщо ви явно не встановите
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний варіант).
**Вхідні вкладення** розміщуються у `media/inbound/*` в активному робочому просторі.
**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі.
**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються.
**`docker.binds`** монтує додаткові каталоги хоста; глобальні монтування та монтування для окремих агентів об’єднуються.
**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC інжектується в системний prompt. Не потребує `browser.enabled` у `openclaw.json`.
Доступ спостерігача через noVNC типово використовує автентифікацію VNC, і OpenClaw видає короткоживучий URL із токеном (замість того, щоб розкривати пароль у спільному URL).
**Ізольований браузер** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC додається до системного запиту. Не потребує `browser.enabled` в `openclaw.json`.
Доступ спостерігача через noVNC за замовчуванням використовує VNC-автентифікацію, і OpenClaw генерує URL із короткоживучим токеном (замість показу пароля в спільному URL).
- `allowHostControl: false` (типово) блокує націлювання з Sandbox-сесій на browser хоста.
- `network` типово має значення `openclaw-sandbox-browser` (окрема bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність bridge.
- `cdpSourceRange` за бажанням обмежує вхідний доступ CDP на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`).
- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер browser Sandbox. Якщо параметр задано (включно з `[]`), він замінює `docker.binds` для контейнера browser.
- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для контейнерних хостів:
- `allowHostControl: false` (за замовчуванням) блокує для ізольованих сесій націлювання на браузер хоста.
- Для `network` за замовчуванням використовується `openclaw-sandbox-browser` (окрема bridge-мережа). Встановлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність.
- `cdpSourceRange` за потреби обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`).
- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер ізольованого браузера. Якщо задано (включно з `[]`), він замінює `docker.binds` для контейнера браузера.
- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів контейнерів:
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
- `--remote-debugging-port=<похідне від OPENCLAW_BROWSER_CDP_PORT>`
- `--user-data-dir=${HOME}/.chrome`
- `--no-first-run`
- `--no-default-browser-check`
@ -869,28 +871,28 @@ harness app-server Codex.
- `--renderer-process-limit=2`
- `--no-zygote`
- `--metrics-recording-only`
- `--disable-extensions` (типово ввімкнено)
- `--disable-extensions` (увімкнено за замовчуванням)
- `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu`
увімкнені типово й можуть бути вимкнені через
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для WebGL/3D це потрібно.
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає extensions, якщо ваш workflow
увімкнені за замовчуванням і можуть бути вимкнені через
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для використання WebGL/3D це потрібно.
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес
залежить від них.
- `--renderer-process-limit=2` можна змінити через
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; установіть `0`, щоб використовувати
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; встановіть `0`, щоб використовувати
типовий ліміт процесів Chromium.
- а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`.
- Типові значення — це базова конфігурація образу контейнера; використовуйте власний образ browser із власним
entrypoint, щоб змінити типові значення контейнера.
- а також `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`.
- Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний
образ браузера з власним entrypoint.
</Accordion>
Sandbox-ізоляція browser і `sandbox.docker.binds` доступні лише для Docker.
Ізоляція браузера та `sandbox.docker.binds` працюють лише з Docker.
Збірка образів:
Зібрати образи:
```bash
scripts/sandbox-setup.sh # основний образ sandbox
scripts/sandbox-browser-setup.sh # необов’язковий образ browser
scripts/sandbox-browser-setup.sh # необов’язковий образ браузера
```
### `agents.list` (перевизначення для окремого агента)
@ -908,9 +910,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
model: "anthropic/claude-opus-4-6", // або { primary, fallbacks }
thinkingDefault: "high", // перевизначення рівня thinking для окремого агента
reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента
fastModeDefault: false, // перевизначення fast mode для окремого агента
fastModeDefault: false, // перевизначення швидкого режиму для окремого агента
embeddedHarness: { runtime: "auto", fallback: "pi" },
params: { cacheRetention: "none" }, // перевизначає за ключами відповідні params з defaults.models
params: { cacheRetention: "none" }, // перевизначає params відповідного defaults.models за ключами
skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано
identity: {
name: "Samantha",
@ -943,26 +945,26 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
```
- `id`: стабільний id агента (обов’язково).
- `default`: якщо задано кілька значень, перше має пріоритет (записується попередження в лог). Якщо не задано жодного, типовим буде перший елемент у списку.
- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron-завдання, які перевизначають лише `primary`, усе ще успадковують типові fallback, якщо не встановити `fallbacks: []`.
- `params`: параметри потоку для окремого агента, які об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей.
- `skills`: необов’язковий allowlist Skills для окремого агента. Якщо параметр пропущено, агент успадковує `agents.defaults.skills`, якщо його задано; явний список замінює типові значення замість злиття, а `[]` означає відсутність Skills.
- `default`: якщо задано кілька, перший має пріоритет (записується попередження). Якщо не задано жодного, типовим буде перший елемент списку.
- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні моделі). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові резервні моделі, якщо ви не задасте `fallbacks: []`.
- `params`: параметри потоку для окремого агента, які об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей.
- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли його задано; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills.
- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для повідомлення або сесії.
- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для повідомлення або сесії.
- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast mode для повідомлення або сесії.
- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише Codex, тоді як інші агенти зберігатимуть типовий fallback до PI.
- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP.
- `identity.avatar`: шлях відносно робочого простору, `http(s)` URL або `data:` URI.
- `reasoningDefault`: необов’язкова типова видимість reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning для повідомлення або сесії.
- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення швидкого режиму для повідомлення або сесії.
- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише Codex, а інші агенти зберігали типовий резервний PI.
- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` зі значеннями `runtime.acp` за замовчуванням (`agent`, `backend`, `mode`, `cwd`), коли агент має за замовчуванням використовувати сесії harness ACP.
- `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`.
- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`.
- `subagents.allowAgents`: allowlist id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент).
- Захист успадкування Sandbox: якщо сесія-ініціатор працює в Sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без Sandbox.
- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, які не містять `agentId` (примушує до явного вибору профілю; типово: false).
- `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; за замовчуванням: лише той самий агент).
- Захист успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox.
- `subagents.requireAgentId`: якщо `true`, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; за замовчуванням: false).
---
## Маршрутизація кількох агентів
## Маршрутизація між кількома агентами
Запускайте кілька ізольованих агентів у межах одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent).
Запускайте кількох ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent).
```json5
{
@ -979,16 +981,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
}
```
### Поля відповідності binding
### Поля збігу для прив’язок
- `type` (необов’язково): `route` для звичайної маршрутизації (відсутнє значення типово означає route), `acp` для постійних binding розмов ACP.
- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип не вказано, за замовчуванням використовується route), `acp` для постійних прив’язок розмов ACP.
- `match.channel` (обов’язково)
- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = типовий обліковий запис)
- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо не вказано = типовий обліковий запис)
- `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`)
- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу)
- `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }`
- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу)
- `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }`
**Детермінований порядок відповідності:**
**Детермінований порядок збігів:**
1. `match.peer`
2. `match.guildId`
@ -997,9 +999,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
5. `match.accountId: "*"` (на весь канал)
6. Типовий агент
У межах кожного рівня перший відповідний запис у `bindings` має пріоритет.
У межах кожного рівня перемагає перший відповідний запис у `bindings`.
Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів route binding, наведений вище.
Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів прив’язки route, наведений вище.
### Профілі доступу для окремих агентів
@ -1050,7 +1052,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
</Accordion>
<Accordion title="Без доступу до файлової системи (лише повідомлення)">
<Accordion title="Без доступу до файлової системи (лише обмін повідомленнями)">
```json5
{
@ -1096,7 +1098,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
</Accordion>
Докладніше про пріоритети див. [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools).
Докладніше про пріоритети див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools).
---
@ -1122,7 +1124,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
},
resetTriggers: ["/new", "/reset"],
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
parentForkMaxTokens: 100000, // пропустити fork батьківського thread вище цього ліміту токенів (0 вимикає)
parentForkMaxTokens: 100000, // пропускати відгалуження від батьківського потоку вище цього числа токенів (0 вимикає)
maintenance: {
mode: "warn", // warn | enforce
pruneAfter: "30d",
@ -1134,10 +1136,10 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
},
threadBindings: {
enabled: true,
idleHours: 24, // типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає)
idleHours: 24, // типове автоматичне зняття фокусу через неактивність у годинах (`0` вимикає)
maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає)
},
mainKey: "main", // застаріле (runtime завжди використовує "main")
mainKey: "main", // застаріле поле (runtime завжди використовує "main")
agentToAgent: { maxPingPongTurns: 5 },
sendPolicy: {
rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
@ -1147,36 +1149,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
}
```
<Accordion title=еталі полів сесії">
<Accordion title=окладно про поля session">
- **`scope`**: базова стратегія групування сесій для контекстів групового чату.
- `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу.
- `global`: усі учасники в контексті каналу ділять одну спільну сесію (використовуйте лише тоді, коли потрібен спільний контекст).
- **`dmScope`**: як групуються приватні повідомлення.
- `main`: усі приватні повідомлення використовують головну сесію.
- `per-sender` (за замовчуванням): кожен відправник отримує ізольовану сесію в межах контексту каналу.
- `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст).
- **`dmScope`**: як групуються особисті повідомлення.
- `main`: усі особисті повідомлення спільно використовують основну сесію.
- `per-peer`: ізоляція за id відправника між каналами.
- `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для inbox із кількома користувачами).
- `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для спільних inbox).
- `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів).
- **`identityLinks`**: мапа канонічних id до peer із префіксом провайдера для спільного використання сесій між каналами.
- **`reset`**: основна політика скидання. `daily` скидає в `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує те, що спливе першим.
- **`identityLinks`**: мапа канонічних id на peer із префіксом провайдера для спільного використання сесій між каналами.
- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, що настане раніше.
- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`.
- **`parentForkMaxTokens`**: максимальне значення `totalTokens` у батьківській сесії, дозволене під час створення сесії fork для thread (типово `100000`).
- Якщо значення `totalTokens` у батьківській сесії перевищує це число, OpenClaw починає нову сесію thread замість успадкування історії transcript батьківської сесії.
- Установіть `0`, щоб вимкнути цей захист і завжди дозволяти fork від батьківської сесії.
- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для головного кошика прямого чату.
- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів між агентами під час обміну agent-to-agent (ціле число, діапазон: `0``5`). `0` вимикає ланцюжки ping-pong.
- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перше правило deny має пріоритет.
- **`maintenance`**: очищення сховища сесій + керування retention.
- `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення.
- `pruneAfter`: віковий поріг для застарілих записів (типово `30d`).
- `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`).
- `rotateBytes`: ротація `sessions.json`, коли він перевищує цей розмір (типово `10mb`).
- `resetArchiveRetention`: retention для архівів transcript `*.reset.<timestamp>`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути.
- `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сесій. У режимі `warn` лише пише попередження в лог; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії.
- `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово `80%` від `maxDiskBytes`.
- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до thread.
- **`parentForkMaxTokens`**: максимальне значення `totalTokens` у батьківській сесії, дозволене під час створення відгалуженої сесії потоку (за замовчуванням `100000`).
- Якщо `totalTokens` у батьківській сесії перевищує це значення, OpenClaw починає нову сесію потоку замість успадкування історії транскрипту батьківської сесії.
- Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти відгалуження від батьківської сесії.
- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика особистих чатів.
- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповіді у зворотному напрямку між агентами під час обміну агент-агент (ціле число, діапазон: `0``5`). `0` вимикає ping-pong-ланцюжок.
- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перший `deny` має пріоритет.
- **`maintenance`**: очищення сховища сесій і керування термінами зберігання.
- `mode`: `warn` лише генерує попередження; `enforce` застосовує очищення.
- `pruneAfter`: поріг віку для застарілих записів (за замовчуванням `30d`).
- `maxEntries`: максимальна кількість записів у `sessions.json` (за замовчуванням `500`).
- `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (за замовчуванням `10mb`).
- `resetArchiveRetention`: термін зберігання архівів транскрипту `*.reset.<timestamp>`. За замовчуванням дорівнює `pruneAfter`; встановіть `false`, щоб вимкнути.
- `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сесій. У режимі `warn` лише журналює попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії.
- `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. За замовчуванням `80%` від `maxDiskBytes`.
- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до потоків.
- `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`)
- `idleHours`: типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати)
- `idleHours`: типове автоматичне зняття фокусу через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати)
- `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати)
</Accordion>
@ -1217,36 +1219,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
Перевизначення для каналу/облікового запису: `channels.<channel>.responsePrefix`, `channels.<channel>.accounts.<id>.responsePrefix`.
Визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`.
Визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскад. `"auto"` формує `[{identity.name}]`.
**Змінні шаблону:**
| Змінна | Опис | Приклад |
| ---------------- | ----------------------- | --------------------------- |
| `{model}` | Коротка назва моделі | `claude-opus-4-6` |
| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` |
| `{provider}` | Назва провайдера | `anthropic` |
| Variable | Опис | Example |
| ----------------- | ---------------------- | --------------------------- |
| `{model}` | Коротка назва моделі | `claude-opus-4-6` |
| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` |
| `{provider}` | Назва провайдера | `anthropic` |
| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` |
| `{identity.name}` | Ім’я identity агента | (те саме, що й `"auto"`) |
| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) |
Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`.
### Ack reaction
### Реакція підтвердження
- Типово береться з `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути.
- За замовчуванням використовується `identity.emoji` активного агента, інакше `"👀"`. Встановіть `""`, щоб вимкнути.
- Перевизначення для каналу: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
- Порядок визначення: обліковий запис → канал → `messages.ackReaction`fallback до identity.
- Область дії: `group-mentions` (типово), `group-all`, `direct`, `all`.
- `removeAckAfterReply`: видаляє ack після відповіді в Slack, Discord і Telegram.
- Порядок визначення: обліковий запис → канал → `messages.ackReaction`резервне значення з identity.
- Область: `group-mentions` (за замовчуванням), `group-all`, `direct`, `all`.
- `removeAckAfterReply`: видаляє підтвердження після відповіді в Slack, Discord і Telegram.
- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram.
У Slack і Discord незадане значення зберігає реакції статусу ввімкненими, коли активні ack reaction.
У Slack і Discord, якщо не задано, реакції статусу залишаються увімкненими, коли активні реакції підтвердження.
У Telegram установіть це значення явно в `true`, щоб увімкнути реакції статусу життєвого циклу.
### Inbound debounce
### Debounce для вхідних повідомлень
Об’єднує швидку послідовність текстових повідомлень від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Керувальні команди обходять debounce.
Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування обходять debounce.
### TTS (text-to-speech)
### TTS (синтез мовлення)
```json5
{
@ -1287,12 +1289,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
}
```
- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні prefs, а `/tts status` показує фактичний стан.
- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку.
- `modelOverrides` увімкнено за замовчуванням; `modelOverrides.allowProvider` типово дорівнює `false` (потрібне явне ввімкнення).
- API keys повертаються до `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`.
- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: config, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`.
- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw вважає його OpenAI-сумісним TTS-сервером і послаблює валідацію model/voice.
- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан.
- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумовування.
- `modelOverrides` увімкнено за замовчуванням; `modelOverrides.allowProvider` за замовчуванням має значення `false` (явне ввімкнення).
- API-ключі резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`.
- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`.
- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw вважає його OpenAI-сумісним TTS-сервером і послаблює перевірку моделі/голосу.
---
@ -1323,17 +1325,17 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
```
- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk.
- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) потрібні лише для сумісності й автоматично мігруються в `talk.providers.<provider>`.
- Voice ID повертаються до `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`.
- `providers.*.apiKey` приймає рядки відкритого тексту або об’єкти SecretRef.
- Fallback до `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано.
- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні імена.
- `silenceTimeoutMs` визначає, скільки режим Talk чекає після тиші користувача перед надсиланням transcript. Якщо не задано, зберігається типове вікно паузи для платформи (`700 ms на macOS і Android, 900 ms на iOS`).
- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються до `talk.providers.<provider>`.
- Ідентифікатори голосів резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`.
- `providers.*.apiKey` приймає звичайні рядки або об’єкти SecretRef.
- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API-ключ Talk не налаштовано.
- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви.
- `silenceTimeoutMs` визначає, скільки часу режим Talk чекає після того, як користувач замовкне, перш ніж надіслати транскрипт. Якщо не задано, зберігається типове для платформи вікно паузи (`700 ms на macOS і Android, 900 ms на iOS`).
---
## Пов’язане
- [Configuration reference](/uk/gateway/configuration-reference) — усі інші ключі конфігурації
- [Configuration](/uk/gateway/configuration) — поширені завдання та швидке налаштування
- [Configuration examples](/uk/gateway/configuration-examples)
- [Довідник із конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації
- [Конфігурація](/uk/gateway/configuration) — поширені завдання та швидке налаштування
- [Приклади конфігурації](/uk/gateway/configuration-examples)

View File

@ -1,24 +1,26 @@
---
read_when:
- Ви хочете використовувати комплектний app-server harness Codex
- Вам потрібні посилання на моделі Codex і приклади конфігурації
- Ви хочете вимкнути резервний перехід на PI для розгортань лише з Codex
- Ви хочете використати комплектний app-server harness Codex
- Вам потрібні приклади конфігурації harness Codex
- Ви хочете вимкнути резервний варіант Pi для розгортань лише з Codex
summary: Запустіть вбудовані ходи агента OpenClaw через комплектний app-server harness Codex
title: harness Codex
x-i18n:
generated_at: "2026-04-24T07:31:32Z"
generated_at: "2026-04-24T18:44:26Z"
model: gpt-5.4
provider: openai
source_hash: c02b1e6cbaaefee858db7ebd7e306261683278ed9375bca6fe74855ca84eabd8
source_hash: 1942e571358674066a7a92139c0ab05273b8196ad68ae3ca2349e2be33cac403
source_path: plugins/codex-harness.md
workflow: 15
---
Комплектний 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, як і раніше, керує каналами чату, файлами сесії, вибором моделі, інструментами,
підтвердженнями, доставкою медіа та видимим дзеркалом транскрипту.
Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності.
Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`:
@ -30,85 +32,88 @@ OpenClaw, як і раніше, керує чат-каналами, файлам
- `before_message_write` для дзеркальних записів транскрипту
- `agent_end`
Комплектні Plugins також можуть реєструвати фабрику розширення Codex app-server, щоб додавати
Комплектні plugins також можуть реєструвати фабрику розширення app-server Codex, щоб додати
асинхронне проміжне ПЗ `tool_result`. Це проміжне ПЗ виконується для динамічних інструментів OpenClaw
після того, як OpenClaw виконає інструмент, і до того, як результат буде повернено в Codex. Воно
відокремлене від публічного хука Plugin `tool_result_persist`, який перетворює записи
результатів інструментів у транскрипті, якими керує OpenClaw.
відокремлене від публічного хука Plugin `tool_result_persist`, який перетворює записи результатів
інструментів у транскрипті, якими керує OpenClaw.
За замовчуванням harness вимкнений. У нових конфігураціях слід зберігати посилання на моделі OpenAI
За замовчуванням harness вимкнено. Нові конфігурації мають зберігати посилання на моделі OpenAI
канонічними як `openai/gpt-*` і явно примусово вказувати
`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли
потрібне нативне виконання через app-server. Застарілі посилання на моделі `codex/*` і надалі
автоматично вибирають harness для сумісності.
`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли вони
хочуть нативне виконання через app-server. Застарілі посилання на моделі `codex/*` і далі
автоматично вибирають harness для сумісності, але не показуються як звичайні варіанти
моделей/провайдерів.
## Виберіть правильний префікс моделі
Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли потрібна
автентифікація Codex OAuth через PI; використовуйте `openai/*`, коли потрібен прямий доступ до OpenAI API або
коли ви примусово використовуєте нативний harness Codex app-server:
Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, якщо хочете
Codex OAuth через 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` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна автентифікація підписки ChatGPT/Codex із типовим раннером PI. |
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness Codex app-server | Вам потрібне нативне виконання через Codex app-server для вбудованого ходу агента. |
| Посилання на модель | Шлях runtime | Використовуйте, коли |
| --------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------- |
| `openai/gpt-5.4` | Провайдер OpenAI через інфраструктуру OpenClaw/PI | Ви хочете поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Ви хочете автентифікацію за підпискою ChatGPT/Codex зі стандартним runner PI. |
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Harness app-server Codex | Ви хочете нативне виконання через app-server Codex для вбудованого ходу агента. |
Наразі GPT-5.5 в OpenClaw доступний лише через підписку/OAuth. Використовуйте
`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` із harness
Codex app-server. Прямий доступ за API-ключем для `openai/gpt-5.5` підтримуватиметься,
Наразі GPT-5.5 в OpenClaw доступна лише через підписку/OAuth. Використовуйте
`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` з harness
app-server Codex. Прямий доступ за API-ключем для `openai/gpt-5.5` підтримуватиметься,
щойно OpenAI увімкне GPT-5.5 у публічному API.
Застарілі посилання `codex/gpt-*` залишаються прийнятними як псевдоніми сумісності. Нові конфігурації
PI Codex OAuth повинні використовувати `openai-codex/gpt-*`; нові конфігурації
нативного harness app-server повинні використовувати `openai/gpt-*` разом із `embeddedHarness.runtime:
"codex"`.
Застарілі посилання `codex/gpt-*` і далі приймаються як сумісні псевдоніми. Міграція сумісності
doctor переписує застарілі основні посилання `codex/*` на `openai/*`
і окремо зберігає політику harness Codex. Нові конфігурації PI Codex OAuth
мають використовувати `openai-codex/gpt-*`; нові конфігурації нативного harness app-server
мають використовувати `openai/gpt-*` разом із `embeddedHarness.runtime: "codex"`.
`agents.defaults.imageModel` дотримується того самого поділу за префіксами. Використовуйте
`agents.defaults.imageModel` дотримується того самого розділення за префіксами. Використовуйте
`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI
Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися
через обмежений хід Codex app-server. Модель Codex app-server повинна
заявляти підтримку вхідних зображень; текстові моделі Codex завершуються помилкою ще до початку
медіа-ходу.
через обмежений хід app-server Codex. Модель app-server Codex має
оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються з помилкою до початку
ходу з медіа.
Використовуйте `/status`, щоб підтвердити ефективний harness для поточної сесії. Якщо
вибір виглядає неочікуваним, увімкніть налагоджувальне логування для підсистеми `agents/harness`
і перевірте структурований запис gateway `agent harness selected`. Він
містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback і,
у режимі `auto`, результат підтримки для кожного кандидата Plugin.
вибір виглядає неочікуваним, увімкніть журналювання налагодження для підсистеми `agents/harness`
та перевірте структурований запис gateway `agent harness selected`. Він
містить id вибраного harness, причину вибору, політику runtime/резервного варіанта, а
в режимі `auto` результат підтримки для кожного кандидата Plugin.
Вибір harness не є елементом керування живою сесією. Коли вбудований хід виконується,
OpenClaw записує ідентифікатор вибраного harness у цю сесію та продовжує використовувати його для
наступних ходів у межах того самого ідентифікатора сесії. Змінюйте конфігурацію `embeddedHarness` або
Вибір harness не є елементом керування живою сесією. Коли виконується вбудований хід,
OpenClaw записує id вибраного harness для цієї сесії та продовжує використовувати його для
наступних ходів у межах того самого id сесії. Змініть конфігурацію `embeddedHarness` або
`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness;
використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної
розмови між PI і Codex. Це дає змогу уникнути повторного відтворення одного транскрипту через
розмови між PI та Codex. Це дає змогу уникнути повторного відтворення одного транскрипту через
дві несумісні нативні системи сесій.
Застарілі сесії, створені до прив’язок harness, вважаються прив’язаними до PI, щойно вони
мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на
Застарілі сесії, створені до появи фіксації harness, вважаються прив’язаними до PI, щойно вони
мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести таку розмову на
Codex після зміни конфігурації.
`/status` показує ефективний не-PI harness поруч із `Fast`, наприклад
`Fast · codex`. Типовий harness PI залишається `Runner: pi (embedded)` і
`/status` показує ефективний harness, відмінний від PI, поруч із `Fast`, наприклад
`Fast · codex`. Стандартний harness PI і далі показується як `Runner: pi (embedded)` і
не додає окремий бейдж harness.
## Вимоги
- OpenClaw із доступним комплектним Plugin `codex`.
- Codex app-server `0.118.0` або новіший.
- Доступна автентифікація Codex для процесу app-server.
- app-server Codex версії `0.118.0` або новішої.
- Автентифікація Codex, доступна для процесу app-server.
Plugin блокує старіші або безверсійні handshake app-server. Це утримує
OpenClaw у межах поверхні протоколу, з якою його було протестовано.
Plugin блокує старіші або неверсіоновані рукостискання app-server. Це утримує
OpenClaw на поверхні протоколу, з якою його було протестовано.
Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також із
Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також
необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і
`~/.codex/config.toml`. Використовуйте ті самі дані автентифікації, що й ваш локальний Codex app-server.
`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, що й ваш локальний
app-server Codex.
## Мінімальна конфігурація
Використовуйте `openai/gpt-5.5`, увімкніть комплектний Plugin і примусово вкажіть harness `codex`:
Використовуйте `openai/gpt-5.5`, увімкніть комплектний Plugin і примусово задайте harness `codex`:
```json5
{
@ -131,7 +136,7 @@ OpenClaw у межах поверхні протоколу, з якою його
}
```
Якщо ваша конфігурація використовує `plugins.allow`, додайте туди також `codex`:
Якщо ваша конфігурація використовує `plugins.allow`, також додайте туди `codex`:
```json5
{
@ -147,14 +152,14 @@ OpenClaw у межах поверхні протоколу, з якою його
```
Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента в
`codex/<model>`, і надалі автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають
віддавати перевагу `openai/<model>` разом із явним записом `embeddedHarness`, наведеним вище.
`codex/<model>`, і далі автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають
надавати перевагу `openai/<model>` разом із явним записом `embeddedHarness`, наведеним вище.
## Додайте Codex без заміни інших моделей
Залишайте `runtime: "auto"`, якщо хочете, щоб застарілі посилання `codex/*` вибирали Codex, а
Зберігайте `runtime: "auto"`, якщо хочете, щоб застарілі посилання `codex/*` вибирали Codex, а
PI — для всього іншого. Для нових конфігурацій надавайте перевагу явному `runtime: "codex"` для
агентів, які мають використовувати цей harness.
тих агентів, які мають використовувати harness.
```json5
{
@ -184,15 +189,15 @@ PI — для всього іншого. Для нових конфігурац
}
```
За такої форми:
Із такою конфігурацією:
- `/model gpt` або `/model openai/gpt-5.5` використовує harness Codex app-server для цієї конфігурації.
- `/model gpt` або `/model openai/gpt-5.5` використовує harness app-server Codex для цієї конфігурації.
- `/model opus` використовує шлях провайдера Anthropic.
- Якщо вибрано не-Codex модель, PI залишається harness сумісності.
- Якщо вибрано не модель Codex, PI залишається harness сумісності.
## Розгортання лише з Codex
Вимкніть fallback на PI, коли потрібно гарантувати, що кожен вбудований хід агента використовує
Вимкніть резервний варіант PI, коли вам потрібно довести, що кожен вбудований хід агента використовує
harness Codex:
```json5
@ -209,7 +214,7 @@ harness Codex:
}
```
Перевизначення через середовище:
Перевизначення через змінні середовища:
```bash
OPENCLAW_AGENT_RUNTIME=codex \
@ -217,12 +222,12 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run
```
Коли fallback вимкнено, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнено,
app-server надто старий або app-server не вдається запустити.
Якщо резервний варіант вимкнено, OpenClaw завершується з помилкою рано, якщо Plugin Codex вимкнено,
app-server надто старий або app-server не може запуститися.
## Codex для окремого агента
Ви можете зробити один агент лише для Codex, тоді як агент за замовчуванням зберігатиме звичайний
Ви можете зробити один агент лише-Codex, тоді як стандартний агент зберігатиме звичайний
автовибір:
```json5
@ -254,15 +259,15 @@ app-server надто старий або app-server не вдається за
}
```
Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову
сесію OpenClaw, а harness Codex за потреби створює або відновлює свій sidecar-потік app-server.
`/reset` очищує прив’язку сесії OpenClaw для цього потоку й дозволяє наступному ходу знову
визначити harness із поточної конфігурації.
Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову
сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-потік app-server
за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку
і дає змогу наступному ходу знову визначити harness на основі поточної конфігурації.
## Виявлення моделей
За замовчуванням Plugin Codex запитує в app-server доступні моделі. Якщо
виявлення завершується помилкою або перевищує час очікування, він використовує комплектний резервний каталог для:
За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо
виявлення завершується помилкою або за тайм-аутом, він використовує комплектний резервний каталог для:
- GPT-5.5
- GPT-5.4 mini
@ -308,9 +313,9 @@ app-server надто старий або app-server не вдається за
}
```
## З’єднання з app-server і політика
## Підключення app-server і політика
За замовчуванням Plugin запускає Codex локально так:
За замовчуванням Plugin запускає Codex локально командою:
```bash
codex app-server --listen stdio://
@ -318,11 +323,11 @@ codex app-server --listen stdio://
За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO:
`approvalPolicy: "never"`, `approvalsReviewer: "user"` і
`sandbox: "danger-full-access"`. Це поза довіри для локального оператора, що використовується
для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без
зупинки на нативних запитах підтвердження, на які нікому відповісти.
`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, що використовується
для автономних Heartbeat: Codex може використовувати shell та мережеві інструменти без
зупинки на нативних запитах на підтвердження, на які нікому відповісти.
Щоб увімкнути перевірювані Guardian схвалення Codex, установіть `appServer.mode:
Щоб увімкнути підтвердження Codex із перевіркою guardian, задайте `appServer.mode:
"guardian"`:
```json5
@ -343,9 +348,9 @@ codex app-server --listen stdio://
}
```
Guardian — це нативний рецензент схвалень Codex. Коли Codex просить вийти із sandbox, записувати поза межами workspace або додати дозволи, як-от мережевий доступ, Codex спрямовує цей запит на схвалення до субагента-рецензента замість запиту людині. Рецензент застосовує модель ризиків Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, коли вам потрібно більше запобіжників, ніж у режимі YOLO, але все ж потрібні агенти без нагляду, які можуть просуватися далі.
Guardian — це нативний рецензент підтверджень Codex. Коли Codex просить вийти із sandbox, записати дані поза робочим простором або додати дозволи, як-от доступ до мережі, Codex спрямовує цей запит на підтвердження до субагента-рецензента замість запиту в людини. Рецензент застосовує рамку ризиків Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, якщо вам потрібні кращі запобіжники, ніж у режимі YOLO, але все ще потрібно, щоб агенти без нагляду могли просуватися далі.
Набір `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики, як і раніше, мають пріоритет над `mode`, тому розширені розгортання можуть поєднувати цей набір із явними виборами.
Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики, як і раніше, перевизначають `mode`, тому розширені розгортання можуть поєднувати пресет із явними параметрами.
Для вже запущеного app-server використовуйте транспорт WebSocket:
@ -371,23 +376,23 @@ Guardian — це нативний рецензент схвалень Codex. К
Підтримувані поля `appServer`:
| Поле | Типове значення | Значення |
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. |
| `command` | `"codex"` | Виконуваний файл для транспорту stdio. |
| Поле | За замовчуванням | Значення |
| ------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `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. |
| `requestTimeoutMs` | `60000` | Час очікування для викликів control-plane app-server. |
| `mode` | `"yolo"` | Набір параметрів для виконання в режимі YOLO або з перевіркою Guardian. |
| `approvalPolicy` | `"never"` | Нативна політика схвалення Codex, яка надсилається під час запуску/відновлення потоку/ходу. |
| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, який надсилається під час запуску/відновлення потоку. |
| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти запити. |
| `serviceTier` | не встановлено | Необов’язковий рівень сервісу Codex app-server: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. |
| `url` | не задано | URL WebSocket app-server. |
| `authToken` | не задано | Bearer-токен для транспорту WebSocket. |
| `headers` | `{}` | Додаткові заголовки WebSocket. |
| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane app-server. |
| `mode` | `"yolo"` | Пресет для виконання в режимі YOLO або з перевіркою guardian. |
| `approvalPolicy` | `"never"` | Нативна політика підтверджень Codex, що надсилається під час запуску/відновлення потоку та ходу. |
| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час запуску/відновлення потоку. |
| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти запити. |
| `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. |
Старі змінні середовища все ще працюють як резервні варіанти для локального тестування, коли
відповідне поле конфігурації не встановлено:
Старі змінні середовища й далі працюють як резервні варіанти для локального тестування, коли
відповідне поле конфігурації не задано:
- `OPENCLAW_CODEX_APP_SERVER_BIN`
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
@ -395,15 +400,15 @@ Guardian — це нативний рецензент схвалень Codex. К
- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` видалено. Натомість використовуйте
`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_MODE=guardian` для одноразового локального тестування. Конфігурація
є бажаним варіантом для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin у тому
самому перевіреному файлі, що й решта налаштування harness Codex.
## Поширені рецепти
Локальний Codex із типовим транспортом stdio:
Локальний Codex зі стандартним транспортом stdio:
```json5
{
@ -417,7 +422,7 @@ Guardian — це нативний рецензент схвалень Codex. К
}
```
Перевірка harness лише з Codex із вимкненим fallback на PI:
Перевірка harness лише з Codex, із вимкненим резервним варіантом PI:
```json5
{
@ -434,7 +439,7 @@ Guardian — це нативний рецензент схвалень Codex. К
}
```
Схвалення Codex із перевіркою Guardian:
Підтвердження Codex із перевіркою Guardian:
```json5
{
@ -479,68 +484,68 @@ Guardian — це нативний рецензент схвалень Codex. К
}
```
Перемикання моделей залишається під керуванням OpenClaw. Коли сесію OpenClaw приєднано
Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw прив’язано
до наявного потоку Codex, наступний хід знову надсилає в
app-server поточну вибрану модель OpenAI, провайдера, політику схвалення, sandbox і рівень сервісу.
Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку до потоку, але просить Codex
продовжити роботу з новою вибраною моделлю.
app-server поточно вибрану модель OpenAI, провайдера, політику підтверджень, sandbox і
рівень сервісу. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає
прив’язку до потоку, але просить Codex продовжити роботу з новою вибраною моделлю.
## Команда Codex
Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є
загальною і працює в будь-якому каналі, який підтримує текстові команди OpenClaw.
універсальною та працює на будь-якому каналі, що підтримує текстові команди OpenClaw.
Поширені форми:
- `/codex status` показує поточне підключення до app-server, моделі, обліковий запис, ліміти запитів, сервери MCP і skills.
- `/codex models` перелічує поточні моделі Codex app-server.
- `/codex threads [filter]` перелічує нещодавні потоки Codex.
- `/codex resume <thread-id>` приєднує поточну сесію OpenClaw до наявного потоку Codex.
- `/codex compact` просить Codex app-server виконати Compaction для приєднаного потоку.
- `/codex review` запускає нативну перевірку Codex для приєднаного потоку.
- `/codex account` показує стан облікового запису та лімітів запитів.
- `/codex mcp` показує стан серверів MCP у Codex app-server.
- `/codex skills` показує skills Codex app-server.
- `/codex status` показує активне підключення до app-server, моделі, обліковий запис, ліміти швидкості, сервери MCP і skills.
- `/codex models` виводить список активних моделей app-server Codex.
- `/codex threads [filter]` виводить список нещодавніх потоків Codex.
- `/codex resume <thread-id>` прив’язує поточну сесію OpenClaw до наявного потоку Codex.
- `/codex compact` просить app-server Codex виконати Compaction для прив’язаного потоку.
- `/codex review` запускає нативну перевірку Codex для прив’язаного потоку.
- `/codex account` показує стан облікового запису та лімітів швидкості.
- `/codex mcp` показує стан серверів MCP app-server Codex.
- `/codex skills` показує skills app-server Codex.
`/codex resume` записує той самий файл sidecar-прив’язки, який harness використовує для
звичайних ходів. Під час наступного повідомлення OpenClaw відновлює цей потік Codex, передає
поточну вибрану модель OpenClaw в app-server і залишає
розширену історію ввімкненою.
`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для
звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає
поточну вибрану модель OpenClaw в app-server і зберігає
увімкнену розширену історію.
Поверхня команд вимагає Codex app-server `0.118.0` або новішої версії. Окремі
методи керування позначаються як `unsupported by this Codex app-server`, якщо
майбутній або нестандартний app-server не надає цей метод JSON-RPC.
Поверхня команд вимагає app-server Codex `0.118.0` або новішої версії. Для окремих
методів керування буде показано `unsupported by this Codex app-server`, якщо
майбутній або кастомний app-server не надає цей метод JSON-RPC.
## Межі хуків
Harness Codex має три шари хуків:
| Шар | Власник | Призначення |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness PI і Codex. |
| Проміжне ПЗ розширення Codex app-server | Комплектні Plugins OpenClaw | Поведінка адаптера на рівні ходу навколо динамічних інструментів OpenClaw. |
| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. |
| Шар | Власник | Призначення |
| ------------------------------------- | ------------------------ | -------------------------------------------------------------------- |
| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness PI і Codex. |
| Middleware розширення app-server Codex | Комплектні plugins OpenClaw | Поведінка адаптера на кожному ході навколо динамічних інструментів OpenClaw. |
| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і нативна політика інструментів із конфігурації Codex. |
OpenClaw не використовує файли проєкту або глобальні файли Codex `hooks.json` для маршрутизації
поведінки Plugin OpenClaw. Нативні хуки Codex корисні для операцій, якими володіє
Codex, таких як політика shell, перевірка результатів нативних інструментів,
обробка зупинки та життєвий цикл нативних моделей/Compaction, але вони не є API Plugin OpenClaw.
OpenClaw не використовує файли проєктного чи глобального Codex `hooks.json` для маршрутизації
поведінки Plugin OpenClaw. Нативні хуки Codex корисні для операцій, якими володіє Codex,
таких як політика shell, нативна перевірка результатів інструментів, обробка зупинки та
нативний життєвий цикл Compaction/моделі, але вони не є API Plugin OpenClaw.
Для динамічних інструментів OpenClaw OpenClaw виконує інструмент після того, як Codex запитує
виклик, тому OpenClaw запускає поведінку Plugin і проміжного ПЗ, якою він володіє, в
адаптері harness. Для нативних інструментів Codex канонічним записом інструмента володіє Codex.
OpenClaw може дзеркалювати окремі події, але не може переписувати нативний потік Codex,
якщо Codex не надає цю операцію через app-server або колбеки нативних хуків.
виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, в
адаптері harness. Для нативних інструментів Codex саме Codex володіє канонічним записом інструмента.
OpenClaw може віддзеркалювати окремі події, але не може переписати нативний
потік Codex, якщо тільки Codex не надає цю операцію через app-server або callbacks нативних хуків.
Коли новіші збірки Codex app-server надають події хуків життєвого циклу нативних моделей і Compaction,
OpenClaw має керувати підтримкою цього протоколу за версіями та відображати
події в наявний контракт хуків OpenClaw там, де семантика є коректною.
Коли новіші збірки app-server Codex надаватимуть події нативних хуків життєвого циклу Compaction і моделі,
OpenClaw має обмежувати підтримку цього протоколу за версією та відображати ці
події в наявний контракт хуків OpenClaw там, де семантика є чесною.
До того часу події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і
`llm_output` є спостереженнями на рівні адаптера, а не побайтовими захопленнями
`llm_output` є спостереженнями на рівні адаптера, а не побайтними копіями
внутрішнього запиту Codex або payload Compaction.
Нативні сповіщення Codex app-server `hook/started` і `hook/completed`
проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження.
Нативні сповіщення app-server Codex `hook/started` і `hook/completed` проєктуються як
події агента `codex_app_server.hook` для траєкторії та налагодження.
Вони не викликають хуки Plugin OpenClaw.
## Інструменти, медіа та Compaction
@ -548,59 +553,58 @@ OpenClaw має керувати підтримкою цього протоко
Harness Codex змінює лише низькорівневий виконавець вбудованого агента.
OpenClaw, як і раніше, формує список інструментів і отримує результати динамічних інструментів від
harness. Текст, зображення, відео, музика, TTS, схвалення та вивід інструментів обміну повідомленнями
і далі проходять через звичайний шлях доставки OpenClaw.
harness. Текст, зображення, відео, музика, TTS, підтвердження та вивід інструментів обміну повідомленнями
й далі проходять через звичайний шлях доставки OpenClaw.
Запити на схвалення інструментів MCP Codex маршрутизуються через потік схвалення Plugin OpenClaw,
коли Codex позначає `_meta.codex_approval_kind` як
Запити на підтвердження для інструментів MCP Codex маршрутизуються через потік
підтверджень Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як
`"mcp_tool_call"`. Запити Codex `request_user_input` надсилаються назад у
вихідний чат, а наступне поставлене в чергу додаткове повідомлення відповідає на цей нативний
запит сервера замість того, щоб скеровуватися як додатковий контекст. Інші запити elicitation MCP
і далі завершуються безпечним блокуванням.
початковий чат, а наступне повідомлення в черзі відповідає на цей нативний запит
сервера замість того, щоб бути спрямованим як додатковий контекст. Інші запити elicitation MCP,
як і раніше, завершуються із закритою відмовою.
Коли вибрана модель використовує harness Codex, нативний Compaction потоку делегується
Codex app-server. OpenClaw зберігає дзеркало транскрипту для історії каналу,
app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу,
пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало
включає запит користувача, фінальний текст асистента та полегшені записи міркувань
або плану Codex, коли їх генерує app-server. Наразі OpenClaw записує лише сигнали
початку та завершення нативного Compaction. Він ще не показує
людинозрозумілий підсумок Compaction або придатний до аудиту список того, які записи Codex
зберіг після Compaction.
містить запит користувача, фінальний текст помічника та полегшені записи міркувань або плану Codex,
коли app-server їх надсилає. Наразі OpenClaw записує лише сигнали початку та завершення
нативного Compaction. Він іще не показує зручний для читання людиною підсумок Compaction
або придатний до аудиту список того, які записи Codex зберіг після Compaction.
Оскільки канонічним нативним потоком володіє Codex, `tool_result_persist` наразі не
Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не
переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли
OpenClaw записує результат інструмента в транскрипт сесії, яким володіє OpenClaw.
Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і
розуміння медіа і далі використовують відповідні налаштування провайдера/моделі, такі як
Генерація медіа не вимагає PI. Генерація зображень, відео, музики, PDF, TTS та розуміння медіа
й далі використовують відповідні параметри провайдера/моделі, такі як
`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і
`messages.tts`.
## Усунення проблем
## Усунення неполадок
**Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`,
виберіть модель `openai/gpt-*` з `embeddedHarness.runtime: "codex"` (або
застаріле посилання `codex/*`) і перевірте, чи `plugins.allow` не виключає `codex`.
**OpenClaw використовує PI замість Codex:** якщо жоден harness Codex не бере виконання,
OpenClaw може використовувати PI як сумісний бекенд. Установіть
**OpenClaw використовує PI замість Codex:** якщо жоден harness Codex не бере виконання на себе,
OpenClaw може використовувати PI як бекенд сумісності. Установіть
`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування, або
`embeddedHarness.fallback: "none"`, щоб отримувати помилку, коли жоден harness Plugin не підходить. Щойно
вибрано Codex app-server, його збої відображаються безпосередньо без додаткової
конфігурації fallback.
вибрано app-server Codex, його збої відображаються безпосередньо без додаткової
конфігурації резервного варіанта.
**app-server відхиляється:** оновіть Codex, щоб handshake app-server
повідомляв версію `0.118.0` або новішу.
**app-server відхиляється:** оновіть Codex, щоб рукостискання app-server
повідомляло про версію `0.118.0` або новішу.
**Виявлення моделей повільне:** зменште `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:** це очікувана поведінка, якщо ви не примусово задали
`embeddedHarness.runtime: "codex"` (або не вибрали застаріле посилання `codex/*`). Звичайні
`openai/gpt-*` та посилання інших провайдерів залишаються на своєму стандартному шляху провайдера.
посилання `openai/gpt-*` та інших провайдерів залишаються на своєму стандартному шляху провайдера.
## Пов’язане