From 499eb0b1d408080e4dead48e1d66dcfc8f9f880b Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 02:40:34 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/agent-runtimes.md | 275 ++++---- docs/uk/concepts/model-providers.md | 259 ++++---- docs/uk/concepts/models.md | 170 ++--- docs/uk/gateway/doctor.md | 396 +++++------ docs/uk/help/faq-first-run.md | 479 +++++++------- docs/uk/help/faq-models.md | 260 ++++---- docs/uk/plugins/codex-harness.md | 951 ++++++++++++++------------- docs/uk/plugins/sdk-agent-harness.md | 277 +++----- docs/uk/providers/openai.md | 522 ++++++++------- 9 files changed, 1780 insertions(+), 1809 deletions(-) diff --git a/docs/uk/concepts/agent-runtimes.md b/docs/uk/concepts/agent-runtimes.md index d3410f007..896235b1f 100644 --- a/docs/uk/concepts/agent-runtimes.md +++ b/docs/uk/concepts/agent-runtimes.md @@ -1,68 +1,69 @@ --- read_when: - - Ви обираєте між PI, Codex, ACP або іншим нативним середовищем виконання агента - - Ви заплуталися в мітках провайдера/моделі/середовища виконання в status або config - - Ви документуєте паритет підтримки для нативного harness -summary: Як OpenClaw розділяє провайдерів моделей, моделі, канали та середовища виконання агентів + - Ви обираєте між Pi, Codex, ACP або іншим нативним середовищем виконання агента + - Вас плутають позначки постачальника/моделі/середовища виконання у статусі або конфігурації + - Ви документуєте паритет підтримки для нативної обв'язки +summary: Як OpenClaw розділяє постачальників моделей, моделі, канали та середовища виконання агентів title: Середовища виконання агентів x-i18n: - generated_at: "2026-04-26T07:47:36Z" - model: gpt-5.4 + generated_at: "2026-05-02T02:37:16Z" + model: gpt-5.5 provider: openai - source_hash: f99e88a47a78c48b2f2408a3feedf15cde66a6bacc4e7bfadb9e47c74f7ce633 + source_hash: bae2dd55491e5411983da942b2bdc4868d3b2cb5a4eb5d94fbb5a779dc4d679a source_path: concepts/agent-runtimes.md - workflow: 15 + workflow: 16 --- -**Середовище виконання агента** — це компонент, який керує одним підготовленим циклом моделі: він -отримує запит, керує виводом моделі, обробляє нативні виклики інструментів і повертає +**Середовище виконання агента** — це компонент, який володіє одним підготовленим циклом моделі: він +отримує промпт, керує виведенням моделі, обробляє нативні виклики інструментів і повертає завершений хід до OpenClaw. -Середовища виконання легко сплутати з провайдерами, оскільки обидва з’являються поруч із +Середовища виконання легко сплутати з провайдерами, бо обидва з'являються поруч із конфігурацією моделі. Це різні рівні: -| Рівень | Приклади | Що це означає | -| ------------- | ------------------------------------- | ------------------------------------------------------------------ | -| Провайдер | `openai`, `anthropic`, `openai-codex` | Як OpenClaw автентифікується, знаходить моделі та називає посилання на моделі. | -| Модель | `gpt-5.5`, `claude-opus-4-6` | Модель, вибрана для ходу агента. | -| Середовище виконання агента | `pi`, `codex`, `claude-cli` | Низькорівневий цикл або бекенд, який виконує підготовлений хід. | -| Канал | Telegram, Discord, Slack, WhatsApp | Звідки повідомлення надходять до OpenClaw і куди виходять. | +| Рівень | Приклади | Що це означає | +| ------------- | ------------------------------------- | ------------------------------------------------------------------- | +| Провайдер | `openai`, `anthropic`, `openai-codex` | Як OpenClaw автентифікується, виявляє моделі та іменує посилання на моделі. | +| Модель | `gpt-5.5`, `claude-opus-4-6` | Модель, вибрана для ходу агента. | +| Середовище виконання агента | `pi`, `codex`, `claude-cli` | Низькорівневий цикл або бекенд, який виконує підготовлений хід. | +| Канал | Telegram, Discord, Slack, WhatsApp | Де повідомлення входять в OpenClaw і виходять із нього. | -У коді ви також побачите слово **harness**. Harness — це реалізація, -яка надає середовище виконання агента. Наприклад, вбудований Codex harness -реалізує середовище виконання `codex`. У публічній конфігурації використовується `agentRuntime.id`; `openclaw -doctor --fix` переписує старі ключі політики середовища виконання в цю форму. +У коді ви також побачите слово **обв'язка**. Обв'язка — це реалізація, +яка надає середовище виконання агента. Наприклад, вбудована обв'язка Codex +реалізує середовище виконання `codex`. Публічна конфігурація використовує `agentRuntime.id`; `openclaw +doctor --fix` переписує старіші ключі політики середовища виконання до цієї форми. -Є дві родини середовищ виконання: +Є два сімейства середовищ виконання: -- **Вбудовані harness-и** працюють усередині підготовленого циклу агента OpenClaw. Наразі це - вбудоване середовище виконання `pi`, а також зареєстровані harness-и Plugin, такі як +- **Вбудовані обв'язки** працюють усередині підготовленого агентського циклу OpenClaw. Сьогодні це + вбудоване середовище виконання `pi` плюс зареєстровані обв'язки plugin, як-от `codex`. -- **CLI-бекенди** запускають локальний процес CLI, зберігаючи при цьому - канонічне посилання на модель. Наприклад, `anthropic/claude-opus-4-7` з - `agentRuntime.id: "claude-cli"` означає «вибрати модель Anthropic, виконати - через Claude CLI». `claude-cli` не є ідентифікатором вбудованого harness-а і не повинен - передаватися для вибору AgentHarness. +- **CLI-бекенди** запускають локальний процес CLI, зберігаючи канонічне посилання на модель. + Наприклад, `anthropic/claude-opus-4-7` з + `agentRuntime.id: "claude-cli"` означає "вибрати модель Anthropic, виконати + через Claude CLI." `claude-cli` не є id вбудованої обв'язки, і його не можна + передавати до вибору AgentHarness. -## Три речі з назвою Codex +## Поверхні Codex -Найбільше непорозумінь виникає через три різні поверхні з однаковою назвою Codex: +Найбільше плутанини виникає через кілька різних поверхонь, які мають назву Codex: -| Поверхня | Назва/конфігурація в OpenClaw | Що вона робить | -| --------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| Маршрут OAuth-провайдера Codex | посилання на моделі `openai-codex/*` | Використовує OAuth підписки ChatGPT/Codex через звичайний виконавець PI в OpenClaw. | -| Нативне середовище виконання Codex app-server | `agentRuntime.id: "codex"` | Запускає вбудований хід агента через комплектний harness Codex app-server. | -| ACP-адаптер Codex | `runtime: "acp"`, `agentId: "codex"` | Запускає Codex через зовнішню площину керування ACP/acpx. Використовуйте лише коли явно запитано ACP/acpx. | -| Нативний набір команд керування чатом Codex | `/codex ...` | Прив’язує, відновлює, спрямовує, зупиняє та перевіряє потоки Codex app-server із чату. | -| Маршрут OpenAI Platform API для моделей у стилі GPT/Codex | посилання на моделі `openai/*` | Використовує автентифікацію OpenAI API key, якщо лише перевизначення середовища виконання, наприклад `runtime: "codex"`, не запускає хід. | +| Поверхня | Назва/конфігурація OpenClaw | Що вона робить | +| ---------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | +| Нативне середовище виконання app-server Codex | `openai/*` плюс `agentRuntime.id: "codex"` | Запускає вбудований агентський хід через app-server Codex. Це звичайне налаштування підписки ChatGPT/Codex. | +| Маршрут провайдера Codex OAuth | Посилання на моделі `openai-codex/*` | Використовує OAuth підписки ChatGPT/Codex через звичайний раннер OpenClaw PI. | +| Адаптер Codex ACP | `runtime: "acp"`, `agentId: "codex"` | Запускає Codex через зовнішню площину керування ACP/acpx. Використовуйте лише тоді, коли ACP/acpx явно запитано. | +| Нативний набір команд керування чатом Codex | `/codex ...` | Прив'язує, відновлює, спрямовує, зупиняє та інспектує потоки app-server Codex із чату. | +| Маршрут OpenAI Platform API для моделей у стилі GPT/Codex | Посилання на моделі `openai/*` | Використовує автентифікацію OpenAI API-ключем, якщо перевизначення середовища виконання, як-от `agentRuntime.id: "codex"`, не запускає хід. | -Ці поверхні навмисно незалежні. Увімкнення Plugin `codex` робить -доступними нативні можливості app-server; воно не переписує -`openai-codex/*` у `openai/*`, не змінює наявні сесії й не робить -ACP типовим варіантом для Codex. Вибір `openai-codex/*` означає «використовувати маршрут -OAuth-провайдера Codex», якщо ви окремо не примусите інше середовище виконання. +Ці поверхні навмисно незалежні. Увімкнення plugin `codex` робить +нативні можливості app-server доступними; воно не переписує +`openai-codex/*` на `openai/*`, не змінює наявні сесії та не +робить ACP типовим варіантом Codex. Вибір `openai-codex/*` означає "використовувати маршрут +провайдера Codex OAuth", якщо окремо не примусити середовище виконання. -Типове налаштування Codex використовує провайдера `openai` із середовищем виконання `codex`: +Поширене налаштування підписки ChatGPT/Codex використовує Codex OAuth для автентифікації, але зберігає +посилання на модель як `openai/*` і вибирає середовище виконання `codex`: ```json5 { @@ -77,85 +78,87 @@ OAuth-провайдера Codex», якщо ви окремо не примус } ``` -Це означає, що OpenClaw вибирає посилання на модель OpenAI, а потім просить середовище виконання -Codex app-server запустити вбудований хід агента. Це не означає, що канал, -каталог провайдерів моделей або сховище сесій OpenClaw стає Codex. +Це означає, що OpenClaw вибирає посилання на модель OpenAI, а потім просить середовище виконання app-server +Codex запустити вбудований агентський хід. Це не означає "використовувати API-білінг", +і не означає, що канал, каталог провайдера моделей або сховище сесій OpenClaw +стає Codex. -Коли комплектний Plugin `codex` увімкнено, для природномовного керування Codex -слід використовувати нативну поверхню команд `/codex` (`/codex bind`, `/codex threads`, +Коли вбудований plugin `codex` увімкнено, керування Codex природною мовою +має використовувати нативну командну поверхню `/codex` (`/codex bind`, `/codex threads`, `/codex resume`, `/codex steer`, `/codex stop`) замість ACP. Використовуйте ACP для -Codex лише коли користувач явно просить ACP/acpx або тестує шлях ACP-адаптера. -Claude Code, Gemini CLI, OpenCode, Cursor та подібні зовнішні -harness-и й далі використовують ACP. +Codex лише тоді, коли користувач явно просить ACP/acpx або тестує шлях адаптера ACP. +Claude Code, Gemini CLI, OpenCode, Cursor та подібні зовнішні обв'язки +далі використовують ACP. -Ось дерево рішень для агента: +Це дерево рішень для агента: -1. Якщо користувач просить **Codex bind/control/thread/resume/steer/stop**, використовуйте - нативну поверхню команд `/codex`, коли комплектний Plugin `codex` увімкнено. -2. Якщо користувач просить **Codex як вбудоване середовище виконання**, використовуйте +1. Якщо користувач просить **прив'язати/керувати/потік/відновити/спрямувати/зупинити Codex**, використовуйте + нативну командну поверхню `/codex`, коли вбудований plugin `codex` увімкнено. +2. Якщо користувач просить **Codex як вбудоване середовище виконання** або хоче звичайний + агентський досвід Codex із підтримкою підписки, використовуйте `openai/` з `agentRuntime.id: "codex"`. -3. Якщо користувач просить **Codex OAuth/автентифікацію за підпискою у звичайному виконавці OpenClaw**, - використовуйте `openai-codex/` і залишайте середовище виконання як PI. -4. Якщо користувач явно каже **ACP**, **acpx** або **ACP-адаптер Codex**, використовуйте +3. Якщо користувач просить **Codex OAuth/автентифікацію підписки на звичайному раннері OpenClaw**, + використовуйте `openai-codex/` і залиште середовище виконання як PI. +4. Якщо користувач явно каже **ACP**, **acpx** або **адаптер Codex ACP**, використовуйте ACP з `runtime: "acp"` і `agentId: "codex"`. 5. Якщо запит стосується **Claude Code, Gemini CLI, OpenCode, Cursor, Droid або - іншого зовнішнього harness-а**, використовуйте ACP/acpx, а не нативне середовище виконання субагента. + іншої зовнішньої обв'язки**, використовуйте ACP/acpx, а не нативне середовище виконання під-агента. -| Ви маєте на увазі... | Використовуйте... | -| -------------------------------------- | ---------------------------------------------- | -| Керування чатом/потоками Codex app-server | `/codex ...` із комплектного Plugin `codex` | -| Вбудоване середовище виконання агента Codex app-server | `agentRuntime.id: "codex"` | -| OpenAI Codex OAuth у виконавці PI | посилання на моделі `openai-codex/*` | -| Claude Code або інший зовнішній harness | ACP/acpx | +| Ви маєте на увазі... | Використовуйте... | +| --------------------------------------- | -------------------------------------------- | +| Керування чатом/потоками app-server Codex | `/codex ...` з вбудованого plugin `codex` | +| Вбудоване середовище виконання агента app-server Codex | `agentRuntime.id: "codex"` | +| OpenAI Codex OAuth на раннері PI | Посилання на моделі `openai-codex/*` | +| Claude Code або інша зовнішня обв'язка | ACP/acpx | -Щодо поділу префіксів родини OpenAI див. [OpenAI](/uk/providers/openai) і -[Провайдери моделей](/uk/concepts/model-providers). Щодо контракту підтримки середовища виконання Codex -див. [Codex harness](/uk/plugins/codex-harness#v1-support-contract). +Про розділення префіксів сімейства OpenAI див. [OpenAI](/uk/providers/openai) і +[Провайдери моделей](/uk/concepts/model-providers). Про контракт підтримки середовища виконання Codex +див. [Обв'язка Codex](/uk/plugins/codex-harness#v1-support-contract). -## Володіння середовищем виконання +## Відповідальність середовища виконання -Різні середовища виконання керують різними частинами циклу. +Різні середовища виконання володіють різними частинами циклу. -| Поверхня | Вбудований PI OpenClaw | Codex app-server | -| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------- | -| Хто керує циклом моделі | OpenClaw через вбудований виконавець PI | Codex app-server | -| Канонічний стан потоку | транскрипт OpenClaw | потік Codex плюс дзеркало транскрипту OpenClaw | -| Динамічні інструменти OpenClaw | нативний цикл інструментів OpenClaw | Мостом через адаптер Codex | -| Нативні shell- та файлові інструменти | шлях PI/OpenClaw | Нативні інструменти Codex, передані через нативні hooks, де це підтримується | -| Рушій контексту | нативне збирання контексту OpenClaw | контекст проєктів OpenClaw, зібраний у хід Codex | -| Compaction | OpenClaw або вибраний рушій контексту | нативний Compaction Codex із сповіщеннями OpenClaw і підтримкою дзеркала | -| Доставка через канал | OpenClaw | OpenClaw | +| Поверхня | Вбудований PI OpenClaw | app-server Codex | +| --------------------------- | --------------------------------------- | --------------------------------------------------------------------------- | +| Власник циклу моделі | OpenClaw через вбудований раннер PI | app-server Codex | +| Канонічний стан потоку | Транскрипт OpenClaw | Потік Codex, плюс дзеркало транскрипту OpenClaw | +| Динамічні інструменти OpenClaw | Нативний цикл інструментів OpenClaw | Передаються через адаптер Codex | +| Нативні інструменти оболонки та файлів | Шлях PI/OpenClaw | Нативні інструменти Codex, передані через нативні хуки там, де підтримується | +| Контекстний рушій | Нативне складання контексту OpenClaw | OpenClaw проєктує зібраний контекст у хід Codex | +| Compaction | OpenClaw або вибраний контекстний рушій | Нативна Compaction Codex, зі сповіщеннями OpenClaw і підтримкою дзеркала | +| Доставка каналом | OpenClaw | OpenClaw | -Цей поділ володіння є головним правилом проєктування: +Цей розподіл відповідальності є головним правилом проєктування: -- Якщо поверхнею керує OpenClaw, OpenClaw може надавати звичайну поведінку hooks Plugin. -- Якщо поверхнею керує нативне середовище виконання, OpenClaw потребує подій середовища виконання або нативних hooks. -- Якщо нативне середовище виконання керує канонічним станом потоку, OpenClaw має дзеркалити й проєктувати контекст, а не переписувати непідтримувані внутрішні механізми. +- Якщо OpenClaw володіє поверхнею, OpenClaw може надати звичайну поведінку хуків plugin. +- Якщо нативне середовище виконання володіє поверхнею, OpenClaw потребує подій середовища виконання або нативних хуків. +- Якщо нативне середовище виконання володіє канонічним станом потоку, OpenClaw має дзеркалити і проєктувати контекст, а не переписувати непідтримувані внутрішні механізми. ## Вибір середовища виконання OpenClaw вибирає вбудоване середовище виконання після визначення провайдера та моделі: -1. Пріоритет має записане для сесії середовище виконання. Зміни конфігурації не перемикають - існуючий транскрипт «на гарячу» на іншу нативну систему потоків. +1. Записане середовище виконання сесії має пріоритет. Зміни конфігурації не перемикають на льоту + наявний транскрипт на іншу нативну систему потоків. 2. `OPENCLAW_AGENT_RUNTIME=` примусово встановлює це середовище виконання для нових або скинутих сесій. -3. `agents.defaults.agentRuntime.id` або `agents.list[].agentRuntime.id` можуть встановлювати - `auto`, `pi`, ідентифікатор зареєстрованого вбудованого harness-а, наприклад `codex`, або - підтримуваний псевдонім CLI-бекенда, наприклад `claude-cli`. -4. У режимі `auto` зареєстровані середовища виконання Plugin можуть заявляти підтримувані - пари провайдер/модель. -5. Якщо жодне середовище виконання не бере хід у режимі `auto`, а встановлено - `fallback: "pi"` (типове значення), OpenClaw використовує PI як сумісний резервний варіант. Установіть - `fallback: "none"`, щоб вибір у режимі `auto` завершувався помилкою, якщо немає відповідності. +3. `agents.defaults.agentRuntime.id` або `agents.list[].agentRuntime.id` може встановити + `auto`, `pi`, зареєстрований id вбудованої обв'язки, як-от `codex`, або + підтримуваний псевдонім CLI-бекенду, як-от `claude-cli`. +4. У режимі `auto` зареєстровані середовища виконання plugin можуть заявляти підтримувані пари + провайдер/модель. +5. Якщо жодне середовище виконання не заявляє хід у режимі `auto` і встановлено `fallback: "pi"` + (типово), OpenClaw використовує PI як резерв сумісності. Установіть + `fallback: "none"`, щоб натомість зробити невідповідний вибір у режимі `auto` помилкою. -Явно задані середовища виконання Plugin типово працюють у закритому режимі. Наприклад, -`runtime: "codex"` означає Codex або чітку помилку вибору, якщо лише ви не встановите +Явні середовища виконання plugin типово завершуються закритою помилкою. Наприклад, +`agentRuntime.id: "codex"` означає Codex або зрозумілу помилку вибору, якщо ви не встановите `fallback: "pi"` у тій самій області перевизначення. Перевизначення середовища виконання не успадковує -ширше налаштування fallback, тому `runtime: "codex"` на рівні агента не буде мовчки -спрямовано назад до PI лише тому, що в значеннях за замовчуванням було `fallback: "pi"`. +ширше резервне налаштування, тому `agentRuntime.id: "codex"` на рівні агента не буде +непомітно перенаправлено назад до PI лише тому, що типові значення використовували `fallback: "pi"`. -Псевдоніми CLI-бекендів відрізняються від ідентифікаторів вбудованих harness-ів. Бажана -форма для Claude CLI така: +Псевдоніми CLI-бекендів відрізняються від id вбудованих обв'язок. Бажана +форма Claude CLI така: ```json5 { @@ -168,60 +171,60 @@ OpenClaw вибирає вбудоване середовище виконанн } ``` -Застарілі посилання на кшталт `claude-cli/claude-opus-4-7` і далі підтримуються для -сумісності, але в новій конфігурації слід зберігати канонічну форму провайдера/моделі, а -бекенд виконання вказувати в `agentRuntime.id`. +Застарілі посилання, як-от `claude-cli/claude-opus-4-7`, залишаються підтримуваними для +сумісності, але нова конфігурація має зберігати провайдера/модель канонічними і розміщувати +бекенд виконання в `agentRuntime.id`. -Режим `auto` навмисно консервативний. Середовища виконання Plugin можуть заявляти -пари провайдер/модель, які вони розуміють, але Plugin Codex не заявляє +Режим `auto` навмисно консервативний. Середовища виконання plugin можуть заявляти +пари провайдер/модель, які вони розуміють, але plugin Codex не заявляє провайдера `openai-codex` у режимі `auto`. Це зберігає -`openai-codex/*` як явний маршрут PI Codex OAuth і не дає мовчки -перемістити конфігурації з автентифікацією за підпискою на нативний harness app-server. +`openai-codex/*` як явний маршрут PI Codex OAuth і не дає непомітно +перемістити конфігурації автентифікації підписки на нативну обв'язку app-server. -Якщо `openclaw doctor` попереджає, що Plugin `codex` увімкнено, але -`openai-codex/*` усе ще маршрутизується через PI, сприймайте це як діагностику, а не -міграцію. Залишайте конфігурацію без змін, якщо вам потрібен саме PI Codex OAuth. -Переходьте на `openai/` плюс `agentRuntime.id: "codex"` лише коли вам потрібне нативне -виконання через Codex app-server. +Якщо `openclaw doctor` попереджає, що plugin `codex` увімкнено, тоді як +`openai-codex/*` усе ще маршрутизується через PI, сприймайте це як діагностику, а не як +міграцію. Залиште конфігурацію без змін, коли PI Codex OAuth — це те, що вам потрібно. +Перемикайтеся на `openai/` плюс `agentRuntime.id: "codex"` лише тоді, коли вам потрібне нативне +виконання app-server Codex. ## Контракт сумісності -Коли середовище виконання — не PI, воно має документувати, які поверхні OpenClaw воно підтримує. -Для документації середовищ виконання використовуйте таку форму: +Коли середовище виконання не є PI, воно має документувати, які поверхні OpenClaw підтримує. +Використовуйте цю форму для документації середовищ виконання: -| Питання | Чому це важливо | -| ------------------------------------- | --------------------------------------------------------------------------------------------- | -| Хто керує циклом моделі? | Визначає, де відбуваються повторні спроби, продовження інструментів і рішення щодо фінальної відповіді. | -| Хто керує канонічною історією потоку? | Визначає, чи може OpenClaw редагувати історію, чи лише дзеркалити її. | -| Чи працюють динамічні інструменти OpenClaw? | На це спираються повідомлення, сесії, Cron та інструменти, що належать OpenClaw. | -| Чи працюють hooks динамічних інструментів? | Plugins очікують `before_tool_call`, `after_tool_call` і middleware навколо інструментів, що належать OpenClaw. | -| Чи працюють hooks нативних інструментів? | Інструментам shell, patch та інструментам, що належать середовищу виконання, потрібна підтримка нативних hooks для політик і спостереження. | -| Чи виконується життєвий цикл рушія контексту? | Plugins пам’яті та контексту залежать від життєвого циклу assemble, ingest, after-turn і Compaction. | -| Які дані Compaction відкриті? | Деяким Plugins потрібні лише сповіщення, а іншим — метадані про збережене/відкинуте. | -| Що навмисно не підтримується? | Користувачі не повинні припускати еквівалентність із PI там, де нативне середовище виконання керує більшою частиною стану. | +| Запитання | Чому це важливо | +| -------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| Хто керує циклом моделі? | Визначає, де відбуваються повторні спроби, продовження інструментів і рішення щодо фінальної відповіді. | +| Хто керує канонічною історією потоку? | Визначає, чи OpenClaw може редагувати історію, чи лише віддзеркалювати її. | +| Чи працюють динамічні інструменти OpenClaw? | Обмін повідомленнями, сеанси, cron і інструменти, що належать OpenClaw, залежать від цього. | +| Чи працюють хуки динамічних інструментів? | Plugins очікують `before_tool_call`, `after_tool_call` і middleware навколо інструментів, що належать OpenClaw. | +| Чи працюють хуки нативних інструментів? | Shell, patch та інструментам, що належать runtime, потрібна нативна підтримка хуків для політик і спостереження. | +| Чи запускається життєвий цикл контекстного рушія? | Plugins пам’яті й контексту залежать від життєвого циклу assemble, ingest, after-turn і compaction. | +| Які дані compaction відкриваються? | Деяким plugins потрібні лише сповіщення, тоді як іншим потрібні метадані збереженого/відкинутого. | +| Що навмисно не підтримується? | Користувачі не повинні припускати еквівалентність PI там, де нативний runtime керує більшою кількістю стану. | -Контракт підтримки середовища виконання Codex задокументовано в +Контракт підтримки runtime Codex задокументовано в [Codex harness](/uk/plugins/codex-harness#v1-support-contract). -## Мітки status +## Мітки стану -У виводі status можуть показуватися мітки `Execution` і `Runtime`. Сприймайте їх як +Вивід стану може показувати обидві мітки: `Execution` і `Runtime`. Сприймайте їх як діагностику, а не як назви провайдерів. -- Посилання на модель, наприклад `openai/gpt-5.5`, повідомляє про вибраного провайдера/модель. -- Ідентифікатор середовища виконання, наприклад `codex`, повідомляє, який цикл виконує цей хід. -- Мітка каналу, наприклад Telegram або Discord, повідомляє, де відбувається розмова. +- Посилання на модель, як-от `openai/gpt-5.5`, показує вибраного провайдера/модель. +- Ідентифікатор runtime, як-от `codex`, показує, який цикл виконує хід. +- Мітка каналу, як-от Telegram або Discord, показує, де відбувається розмова. -Якщо після зміни конфігурації середовища виконання сесія все ще показує PI, почніть нову сесію -через `/new` або очистьте поточну через `/reset`. Наявні сесії зберігають своє -записане середовище виконання, щоб транскрипт не відтворювався через дві несумісні нативні -системи сесій. +Якщо сеанс усе ще показує PI після зміни конфігурації runtime, почніть новий сеанс +за допомогою `/new` або очистьте поточний за допомогою `/reset`. Наявні сеанси зберігають свій +записаний runtime, щоб transcript не відтворювався через дві несумісні нативні +системи сеансів. ## Пов’язане - [Codex harness](/uk/plugins/codex-harness) - [OpenAI](/uk/providers/openai) -- [Plugins harness агента](/uk/plugins/sdk-agent-harness) +- [Agent harness plugins](/uk/plugins/sdk-agent-harness) - [Цикл агента](/uk/concepts/agent-loop) - [Моделі](/uk/concepts/models) -- [Status](/uk/cli/status) +- [Стан](/uk/cli/status) diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index ea78c3b98..d16c5d0d8 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,68 +1,68 @@ --- read_when: - - Вам потрібен довідник із налаштування моделей для кожного провайдера + - Вам потрібен довідник з налаштування моделей для кожного постачальника - Вам потрібні приклади конфігурацій або команди CLI для початкового налаштування постачальників моделей sidebarTitle: Model providers -summary: Огляд постачальників моделей із прикладами конфігурацій + робочими процесами CLI -title: Постачальники моделей +summary: Огляд постачальників моделей із прикладами конфігурацій + сценаріями CLI +title: Провайдери моделей x-i18n: - generated_at: "2026-05-02T02:28:51Z" + generated_at: "2026-05-02T02:37:10Z" model: gpt-5.5 provider: openai - source_hash: 6b1523616a846b2bf0cad46f9f4a713fbb5e8bd7327108ab593eea8c841d5eef + source_hash: 34e6a6b691b447a66a94f69a7b609f26c587eaa5bc55c5ed62460ce14cc288fd source_path: concepts/model-providers.md workflow: 16 --- -Довідка для **постачальників LLM/моделей** (не каналів чату на кшталт WhatsApp/Telegram). Правила вибору моделей див. у [Моделі](/uk/concepts/models). +Довідка для **постачальників LLM/моделей** (не каналів чату, як-от WhatsApp/Telegram). Правила вибору моделей див. у [Моделі](/uk/concepts/models). -## Швидкі правила +## Короткі правила - + - Посилання на моделі використовують `provider/model` (приклад: `opencode/claude-opus-4-6`). - - `agents.defaults.models` діє як список дозволених моделей, якщо задано. - - Помічники CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. + - `agents.defaults.models` діє як список дозволених, коли його задано. + - CLI-помічники: `openclaw onboard`, `openclaw models list`, `openclaw models set `. - `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` задають типові значення на рівні постачальника; `models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` перевизначають їх для окремої моделі. - - Правила резервного перемикання, проби після періоду охолодження та збереження перевизначень сеансу: [Резервне перемикання моделей](/uk/concepts/model-failover). + - Правила резервного перемикання, проби після cooldown і збереження перевизначень сеансу: [Резервне перемикання моделей](/uk/concepts/model-failover). - `openclaw configure` зберігає наявне значення `agents.defaults.model.primary`, коли ви додаєте або повторно автентифікуєте постачальника. Plugin постачальника все ще може повернути рекомендовану типову модель у своєму патчі конфігурації автентифікації, але configure трактує це як "зробити цю модель доступною", якщо основна модель уже існує, а не як "замінити поточну основну модель". + `openclaw configure` зберігає наявний `agents.defaults.model.primary`, коли ви додаєте або повторно автентифікуєте постачальника. Plugin-и постачальників усе ще можуть повертати рекомендовану типову модель у своєму патчі конфігурації автентифікації, але configure трактує це як "зробити цю модель доступною", якщо основна модель уже існує, а не як "замінити поточну основну модель." - Щоб навмисно перемкнути типову модель, скористайтеся `openclaw models set ` або `openclaw models auth login --provider --set-default`. + Щоб навмисно змінити типову модель, використайте `openclaw models set ` або `openclaw models auth login --provider --set-default`. - - Маршрути сімейства OpenAI залежать від префікса: + + Маршрути родини OpenAI залежать від префікса: - - `openai/` використовує прямого постачальника OpenAI з API-ключем у PI. + - `openai/` разом із `agents.defaults.agentRuntime.id: "codex"` використовує нативний harness сервера застосунку Codex. Це звичайне налаштування для підписки ChatGPT/Codex. - `openai-codex/` використовує Codex OAuth у PI. - - `openai/` разом із `agents.defaults.agentRuntime.id: "codex"` використовує нативну обгортку сервера застосунку Codex. + - `openai/` без перевизначення середовища виконання Codex використовує прямого постачальника OpenAI з API-ключем у PI. - Див. [OpenAI](/uk/providers/openai) і [обгортку Codex](/uk/plugins/codex-harness). Якщо розділення постачальника та середовища виконання незрозуміле, спочатку прочитайте [Середовища виконання агентів](/uk/concepts/agent-runtimes). + Див. [OpenAI](/uk/providers/openai) і [harness Codex](/uk/plugins/codex-harness). Якщо розділення постачальника/середовища виконання незрозуміле, спершу прочитайте [Середовища виконання агентів](/uk/concepts/agent-runtimes). - Автоматичне ввімкнення Plugin дотримується тієї самої межі: `openai-codex/` належить до OpenAI plugin, тоді як Codex plugin вмикається через `agentRuntime.id: "codex"` або застарілі посилання `codex/`. + Автоматичне вмикання Plugin дотримується тієї самої межі: `openai-codex/` належить до Plugin OpenAI, тоді як Plugin Codex вмикається через `agentRuntime.id: "codex"` або застарілі посилання `codex/`. - GPT-5.5 доступна через `openai/gpt-5.5` для прямого трафіку з API-ключем, `openai-codex/gpt-5.5` у PI для Codex OAuth і нативну обгортку сервера застосунку Codex, коли задано `agentRuntime.id: "codex"`. + GPT-5.5 доступна через нативний harness сервера застосунку Codex, коли задано `agentRuntime.id: "codex"`, через `openai-codex/gpt-5.5` у PI для Codex OAuth і через `openai/gpt-5.5` у PI для прямого трафіку з API-ключем, коли ваш обліковий запис це надає. - - Середовища виконання CLI використовують те саме розділення: виберіть канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задайте `agents.defaults.agentRuntime.id` як `claude-cli`, `google-gemini-cli` або `codex-cli`, коли потрібен локальний бекенд CLI. + + CLI-середовища виконання використовують те саме розділення: виберіть канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задайте `agents.defaults.agentRuntime.id` як `claude-cli`, `google-gemini-cli` або `codex-cli`, коли потрібен локальний CLI-бекенд. - Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальника, а середовище виконання записується окремо. + Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальників, а середовище виконання записується окремо. -## Поведінка постачальника, якою володіє Plugin +## Поведінка постачальника, керована Plugin -Більшість логіки, специфічної для постачальників, міститься у plugins постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл inference. Plugins володіють onboarding, каталогами моделей, зіставленням env var автентифікації, нормалізацією транспорту/конфігурації, очищенням схем інструментів, класифікацією резервного перемикання, оновленням OAuth, звітуванням про використання, профілями thinking/reasoning тощо. +Більшість специфічної для постачальника логіки живе в Plugin-ах постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає універсальний цикл інференсу. Plugin-и відповідають за onboarding, каталоги моделей, зіставлення env-var для автентифікації, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію резервного перемикання, оновлення OAuth, звітування про використання, профілі thinking/reasoning тощо. -Повний список хуків provider-SDK і прикладів bundled-plugin міститься в [Plugins постачальників](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю власний виконавець запитів, є окремою, глибшою поверхнею розширення. +Повний список хуків provider-SDK і прикладів вбудованих Plugin-ів міститься в [Plugin-и постачальників](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю власний виконавець запитів, є окремою, глибшою поверхнею розширення. -Поведінка runner, якою володіє постачальник, розміщена на явних хуках постачальника, як-от політика відтворення, нормалізація схем інструментів, обгортання stream і помічники транспорту/запитів. Застарілий статичний набір `ProviderPlugin.capabilities` призначений лише для сумісності й більше не читається спільною логікою runner. +Поведінка runner, що належить постачальнику, живе в явних хуках постачальника, як-от політика replay, нормалізація схем інструментів, обгортання потоку та помічники транспорту/запитів. Застарілий статичний набір `ProviderPlugin.capabilities` існує лише для сумісності й більше не читається спільною логікою runner. ## Ротація API-ключів @@ -71,43 +71,43 @@ x-i18n: Налаштуйте кілька ключів через: - - `OPENCLAW_LIVE__KEY` (одне live-перевизначення, найвищий пріоритет) + - `OPENCLAW_LIVE__KEY` (єдине live-перевизначення, найвищий пріоритет) - `_API_KEYS` (список через кому або крапку з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) - Для постачальників Google `GOOGLE_API_KEY` також включено як резервний варіант. Порядок вибору ключів зберігає пріоритет і видаляє дублікати значень. + Для постачальників Google `GOOGLE_API_KEY` також включено як fallback. Порядок вибору ключів зберігає пріоритет і усуває дублікати значень. - - Запити повторюються з наступним ключем лише для відповідей про rate limit (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). - - Помилки, не пов'язані з rate limit, одразу завершуються невдачею; ротація ключів не виконується. - - Коли всі ключі-кандидати не спрацьовують, фінальна помилка повертається з останньої спроби. + - Запити повторюються з наступним ключем лише для відповідей про обмеження швидкості (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). + - Помилки, не пов'язані з обмеженням швидкості, завершуються одразу; ротація ключів не виконується. + - Коли всі ключі-кандидати зазнають невдачі, повертається фінальна помилка з останньої спроби. ## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi-ai. Ці постачальники **не** потребують конфігурації `models.providers`; просто задайте автентифікацію та виберіть модель. +OpenClaw постачається з каталогом pi‑ai. Ці постачальники **не** потребують конфігурації `models.providers`; просто задайте автентифікацію й виберіть модель. ### OpenAI - Постачальник: `openai` - Автентифікація: `OPENAI_API_KEY` -- Необов'язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, плюс `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) +- Необов'язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, плюс `OPENCLAW_LIVE_OPENAI_KEY` (єдине перевизначення) - Приклади моделей: `openai/gpt-5.5`, `openai/gpt-5.4-mini` - Перевірте доступність облікового запису/моделі за допомогою `openclaw models list --provider openai`, якщо конкретне встановлення або API-ключ поводиться інакше. - CLI: `openclaw onboard --auth-choice openai-api-key` -- Типовий транспорт: `auto` (спочатку WebSocket, резервно SSE) +- Типовий транспорт — `auto` (спочатку WebSocket, fallback на SSE) - Перевизначайте для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Прогрів OpenAI Responses WebSocket типово ввімкнено через `params.openaiWsWarmup` (`true`/`false`) +- Розігрів OpenAI Responses WebSocket типово ввімкнений через `params.openaiWsWarmup` (`true`/`false`) - Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier` - `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` з `service_tier=priority` на `api.openai.com` - Використовуйте `params.serviceTier`, коли потрібен явний рівень замість спільного перемикача `/fast` -- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) застосовуються лише до нативного трафіку OpenAI до `api.openai.com`, а не до загальних OpenAI-сумісних проксі +- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) застосовуються лише до нативного трафіку OpenAI до `api.openai.com`, а не до універсальних OpenAI-сумісних проксі - Нативні маршрути OpenAI також зберігають Responses `store`, підказки prompt-cache і формування payload для сумісності з reasoning OpenAI; проксі-маршрути цього не роблять -- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити OpenAI API відхиляють його, а поточний каталог Codex його не експонує +- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити OpenAI API його відхиляють, а поточний каталог Codex його не надає ```json5 { @@ -119,17 +119,17 @@ OpenClaw постачається з каталогом pi-ai. Ці постач - Постачальник: `anthropic` - Автентифікація: `ANTHROPIC_API_KEY` -- Необов'язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, плюс `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) +- Необов'язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, плюс `OPENCLAW_LIVE_ANTHROPIC_KEY` (єдине перевизначення) - Приклад моделі: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком з API-ключем і OAuth-автентифікацією, надісланим до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) -- Бажана конфігурація Claude CLI зберігає посилання на модель канонічним і вибирає бекенд CLI - окремо: `anthropic/claude-opus-4-7` з - `agents.defaults.agentRuntime.id: "claude-cli"`. Застарілі посилання - `claude-cli/claude-opus-4-7` усе ще працюють для сумісності. +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком з API-ключем і OAuth-автентифікацією, що надсилається до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Бажана конфігурація Claude CLI зберігає посилання на модель канонічним і вибирає CLI + бекенд окремо: `anthropic/claude-opus-4-7` з + `agents.defaults.agentRuntime.id: "claude-cli"`. Застарілі + посилання `claude-cli/claude-opus-4-7` усе ще працюють для сумісності. -Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, доки Anthropic не опублікує нову політику. Setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але OpenClaw тепер надає перевагу повторному використанню Claude CLI та `claude -p`, коли вони доступні. +Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволено, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. Anthropic setup-token залишається доступним як підтримуваний шлях токена OpenClaw, але OpenClaw тепер надає перевагу повторному використанню Claude CLI і `claude -p`, коли вони доступні. ```json5 @@ -143,23 +143,30 @@ OpenClaw постачається з каталогом pi-ai. Ці постач - Постачальник: `openai-codex` - Автентифікація: OAuth (ChatGPT) - Посилання на модель PI: `openai-codex/gpt-5.5` -- Посилання на нативну обгортку сервера застосунку Codex: `openai/gpt-5.5` з `agents.defaults.agentRuntime.id: "codex"` -- Документація нативної обгортки сервера застосунку Codex: [Обгортка Codex](/uk/plugins/codex-harness) +- Посилання на нативний harness сервера застосунку Codex: `openai/gpt-5.5` з `agents.defaults.agentRuntime.id: "codex"` +- Документація нативного harness сервера застосунку Codex: [harness Codex](/uk/plugins/codex-harness) - Застарілі посилання на моделі: `codex/gpt-*` -- Межа Plugin: `openai-codex/*` завантажує OpenAI plugin; нативний plugin сервера застосунку Codex вибирається лише середовищем виконання обгортки Codex або застарілими посиланнями `codex/*`. +- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin сервера застосунку Codex вибирається лише середовищем виконання harness Codex або застарілими посиланнями `codex/*`. - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Типовий транспорт: `auto` (спочатку WebSocket, резервно SSE) -- Перевизначайте для окремої PI-моделі через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- `params.serviceTier` також передається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) -- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex до `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі -- Має той самий спільний перемикач `/fast` і конфігурацію `params.fastMode`, що й прямі `openai/*`; OpenClaw зіставляє це з `service_tier=priority` -- `openai-codex/gpt-5.5` використовує нативні для каталогу Codex `contextWindow = 400000` і типове runtime `contextTokens = 272000`; перевизначте обмеження runtime через `models.providers.openai-codex.models[].contextTokens` +- Типовий транспорт — `auto` (спочатку WebSocket, fallback на SSE) +- Перевизначайте для окремої моделі PI через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- `params.serviceTier` також передається у нативних запитах Codex Responses (`chatgpt.com/backend-api`) +- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex до `chatgpt.com/backend-api`, а не до універсальних OpenAI-сумісних проксі +- Має ту саму конфігурацію спільного перемикача `/fast` і `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` +- `openai-codex/gpt-5.5` використовує нативний для каталогу Codex `contextWindow = 400000` і типове середовище виконання `contextTokens = 272000`; перевизначте ліміт середовища виконання через `models.providers.openai-codex.models[].contextTokens` - Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/робочих процесів на кшталт OpenClaw. -- Використовуйте `openai-codex/gpt-5.5`, коли потрібен маршрут Codex OAuth/підписки; використовуйте `openai/gpt-5.5`, коли ваше налаштування API-ключа та локальний каталог експонують публічний API-маршрут. +- Для поширеного маршруту з підпискою плюс нативним середовищем виконання Codex увійдіть через автентифікацію `openai-codex`, але налаштуйте `openai/gpt-5.5` плюс `agents.defaults.agentRuntime.id: "codex"`. +- Використовуйте `openai-codex/gpt-5.5` лише коли потрібен маршрут Codex OAuth/підписки через PI; використовуйте `openai/gpt-5.5` без перевизначення середовища виконання Codex, коли ваше налаштування API-ключа й локальний каталог надають маршрут публічного API. ```json5 { - agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } }, + plugins: { entries: { codex: { enabled: true } } }, + agents: { + defaults: { + model: { primary: "openai/gpt-5.5" }, + agentRuntime: { id: "codex", fallback: "none" }, + }, + }, } ``` @@ -179,13 +186,13 @@ OpenClaw постачається з каталогом pi-ai. Ці постач - Z.AI Coding Plan або загальні API endpoint. + Z.AI Coding Plan або загальні API-ендпоїнти. MiniMax Coding Plan OAuth або доступ за API-ключем. - Поверхня постачальника Qwen Cloud плюс зіставлення endpoint Alibaba DashScope і Coding Plan. + Поверхня постачальника Qwen Cloud плюс зіставлення ендпоїнтів Alibaba DashScope і Coding Plan. @@ -205,23 +212,23 @@ OpenClaw постачається з каталогом pi-ai. Ці постач ### Google Gemini (API-ключ) -- Постачальник: `google` +- Провайдер: `google` - Автентифікація: `GEMINI_API_KEY` -- Необов'язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) +- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, запасний варіант `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одинарне перевизначення) - Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Сумісність: застаріла конфігурація OpenClaw, що використовує `google/gemini-3.1-flash-preview`, нормалізується до `google/gemini-3-flash-preview` -- Псевдонім: `google/gemini-3.1-pro` приймається та нормалізується до live-ID Gemini API від Google, `google/gemini-3.1-pro-preview` +- Псевдонім: `google/gemini-3.1-pro` приймається та нормалізується до ідентифікатора поточного Gemini API від Google, `google/gemini-3.1-pro-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` -- Thinking: `/think adaptive` використовує динамічне thinking Google. Gemini 3/3.1 пропускають фіксований `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`. -- Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` (або застаріле `cached_content`) для пересилання нативного для постачальника handle `cachedContents/...`; cache hits Gemini відображаються як OpenClaw `cacheRead` +- Мислення: `/think adaptive` використовує динамічне мислення Google. Gemini 3/3.1 не вказує фіксований `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`. +- Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` (або застарілий `cached_content`), щоб передати власний для провайдера дескриптор `cachedContents/...`; влучання в кеш Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI -- Постачальники: `google-vertex`, `google-gemini-cli` +- Провайдери: `google-vertex`, `google-gemini-cli` - Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує свій потік OAuth -Gemini CLI OAuth в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження облікових записів Google після використання сторонніх клієнтів. Перегляньте умови Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. +Gemini CLI OAuth в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Перегляньте умови Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. Gemini CLI OAuth постачається як частина вбудованого Plugin `google`. @@ -251,7 +258,7 @@ Gemini CLI OAuth постачається як частина вбудовано openclaw models auth login --provider google-gemini-cli --set-default ``` - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview`. Ви **не** вставляєте ідентифікатор клієнта або секрет у `openclaw.json`. Процес входу через CLI зберігає токени в профілях автентифікації на хості Gateway. + Стандартна модель: `google-gemini-cli/gemini-3-flash-preview`. Ви **не** вставляєте ідентифікатор клієнта чи секрет у `openclaw.json`. Потік входу CLI зберігає токени в профілях автентифікації на хості Gateway. @@ -259,7 +266,7 @@ Gemini CLI OAuth постачається як частина вбудовано -JSON-відповіді Gemini CLI розбираються з `response`; використання повертається до `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. +JSON-відповіді Gemini CLI розбираються з `response`; usage використовує запасний варіант `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. ### Z.AI (GLM) @@ -283,15 +290,15 @@ JSON-відповіді Gemini CLI розбираються з `response`; ви - Автентифікація: `KILOCODE_API_KEY` - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Базовий URL: `https://api.kilo.ai/api/gateway/` -- Статичний резервний каталог постачає `kilocode/kilo/auto`; живе виявлення `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог виконання. +- Базова URL-адреса: `https://api.kilo.ai/api/gateway/` +- Статичний запасний каталог постачає `kilocode/kilo/auto`; поточне виявлення `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог середовища виконання. - Точна висхідна маршрутизація за `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. -Докладні відомості про налаштування див. у [/providers/kilocode](/uk/providers/kilocode). +Див. [/providers/kilocode](/uk/providers/kilocode) для подробиць налаштування. ### Інші вбудовані Plugin провайдерів -| Провайдер | Ідентифікатор | Змінна середовища автентифікації | Приклад моделі | +| Провайдер | Ідентифікатор | Змінна середовища автентифікації | Приклад моделі | | ----------------------- | -------------------------------- | ------------------------------------------------------------ | --------------------------------------------- | | BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | | Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | @@ -322,38 +329,38 @@ JSON-відповіді Gemini CLI розбираються з `response`; ви - Застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Посилання DeepSeek, Moonshot і ZAI придатні для cache-TTL у керованому OpenRouter кешуванні підказок, але не отримують кеш-маркерів Anthropic. Як проксі-шлях, сумісний з OpenAI, він пропускає формування, призначене лише для нативного OpenAI (`serviceTier`, Responses `store`, підказки кешу підказок, сумісність міркування OpenAI). Посилання на базі Gemini зберігають лише санітизацію thought-signature проксі-Gemini. + Застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Посилання DeepSeek, Moonshot і ZAI придатні для cache-TTL у керованому OpenRouter кешуванні промптів, але не отримують маркерів кешу Anthropic. Як proxy-стиль OpenAI-сумісного шляху, він пропускає формування, властиве лише нативному OpenAI (`serviceTier`, Responses `store`, підказки prompt-cache, сумісність reasoning OpenAI). Посилання на базі Gemini зберігають лише proxy-Gemini очищення thought-signature. - Посилання на базі Gemini використовують той самий шлях санітизації проксі-Gemini; `kilocode/kilo/auto` та інші посилання проксі, що не підтримують міркування, пропускають ін’єкцію проксі-міркування. + Посилання на базі Gemini проходять той самий шлях очищення proxy-Gemini; `kilocode/kilo/auto` та інші посилання, що не підтримують proxy reasoning, пропускають інʼєкцію proxy reasoning. - Онбординг через API-ключ записує явні текстові визначення чат-моделей M2.7; розуміння зображень лишається на медіапровайдері `MiniMax-VL-01`, що належить Plugin. + Онбординг з API-ключем записує явні текстові визначення чат-моделей M2.7; розуміння зображень залишається на медіапровайдері `MiniMax-VL-01`, що належить Plugin. - Ідентифікатори моделей використовують простір імен `nvidia//` (наприклад, `nvidia/nvidia/nemotron-...` поряд із `nvidia/moonshotai/kimi-k2.5`); засоби вибору зберігають буквальну композицію `/`, тоді як канонічний ключ, що надсилається до API, лишається з одним префіксом. + Ідентифікатори моделей використовують простір імен `nvidia//` (наприклад, `nvidia/nvidia/nemotron-...` поряд із `nvidia/moonshotai/kimi-k2.5`); вибирачі зберігають буквальну композицію `/`, тоді як канонічний ключ, надісланий до API, залишається з одним префіксом. - Використовує шлях xAI Responses. `grok-4.3` є вбудованою чат-моделлю за замовчуванням. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` увімкнено за замовчуванням; вимкніть через `agents.defaults.models["xai/"].params.tool_stream=false`. + Використовує шлях xAI Responses. `grok-4.3` є вбудованою типовою чат-моделлю. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` увімкнено за замовчуванням; вимкніть через `agents.defaults.models["xai/"].params.tool_stream=false`. - Постачається як вбудований Plugin провайдера `cerebras`. GLM використовує `zai-glm-4.7`; базовий URL, сумісний з OpenAI, — `https://api.cerebras.ai/v1`. + Постачається як вбудований Plugin провайдера `cerebras`. GLM використовує `zai-glm-4.7`; OpenAI-сумісний базовий URL: `https://api.cerebras.ai/v1`. ## Провайдери через `models.providers` (користувацький/базовий URL) -Використовуйте `models.providers` (або `models.json`), щоб додати **користувацьких** провайдерів або проксі, сумісні з OpenAI/Anthropic. +Використовуйте `models.providers` (або `models.json`), щоб додати **користувацьких** провайдерів або OpenAI/Anthropic‑сумісні проксі. -Багато з наведених нижче вбудованих Plugin провайдерів уже публікують каталог за замовчуванням. Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити базовий URL, заголовки або список моделей. +Багато наведених нижче вбудованих Plugin провайдерів уже публікують типовий каталог. Використовуйте явні записи `models.providers.` лише тоді, коли потрібно перевизначити типовий базовий URL, заголовки або список моделей. -Перевірки можливостей моделей Gateway також читають явні метадані `models.providers..models[]`. Якщо користувацька або проксі-модель приймає зображення, задайте `input: ["text", "image"]` для цієї моделі, щоб WebChat і шляхи вкладень із походженням від вузла передавали зображення як нативні вхідні дані моделі, а не як медіа-посилання лише для тексту. +Перевірки можливостей моделей Gateway також читають явні метадані `models.providers..models[]`. Якщо користувацька або проксі-модель приймає зображення, установіть `input: ["text", "image"]` для цієї моделі, щоб WebChat і шляхи вкладень із джерелом у вузлі передавали зображення як нативні входи моделі, а не як текстові медіапосилання. ### Moonshot AI (Kimi) -Moonshot постачається як вбудований Plugin постачальника. За замовчуванням використовуйте вбудований постачальник і додавайте явний запис `models.providers.moonshot` лише тоді, коли потрібно перевизначити базову URL-адресу або метадані моделі: +Moonshot постачається як вбудований Plugin провайдера. Використовуйте вбудованого провайдера за замовчуванням і додавайте явний запис `models.providers.moonshot` лише тоді, коли потрібно перевизначити базовий URL або метадані моделі: -- Постачальник: `moonshot` +- Провайдер: `moonshot` - Автентифікація: `MOONSHOT_API_KEY` - Приклад моделі: `moonshot/kimi-k2.6` - CLI: `openclaw onboard --auth-choice moonshot-api-key` або `openclaw onboard --auth-choice moonshot-api-key-cn` @@ -389,11 +396,11 @@ Moonshot постачається як вбудований Plugin постач } ``` -### Кодування Kimi +### Kimi для програмування -Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI: +Kimi Coding використовує Anthropic-сумісний кінцевий пункт Moonshot AI: -- Постачальник: `kimi` +- Провайдер: `kimi` - Автентифікація: `KIMI_API_KEY` - Приклад моделі: `kimi/kimi-code` @@ -406,13 +413,13 @@ Kimi Coding використовує Anthropic-сумісну кінцеву т } ``` -Застарілий `kimi/k2p5` і надалі приймається як ідентифікатор моделі для сумісності. +Застарілий `kimi/k2p5` і надалі приймається як сумісний ідентифікатор моделі. ### Volcano Engine (Doubao) Volcano Engine (火山引擎) надає доступ до Doubao та інших моделей у Китаї. -- Постачальник: `volcengine` (кодування: `volcengine-plan`) +- Провайдер: `volcengine` (кодування: `volcengine-plan`) - Автентифікація: `VOLCANO_ENGINE_API_KEY` - Приклад моделі: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -425,9 +432,9 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Onboarding за замовчуванням використовує поверхню для кодування, але загальний каталог `volcengine/*` реєструється водночас. +Під час онбордингу за замовчуванням використовується поверхня для кодування, але загальний каталог `volcengine/*` реєструється одночасно. -У засобах вибору моделі під час onboarding/configure варіант автентифікації Volcengine надає перевагу рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній засіб вибору, обмежений постачальником. +У засобах вибору моделей під час онбордингу/налаштування варіант автентифікації Volcengine віддає перевагу рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажено, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього засобу вибору, обмеженого провайдером. @@ -438,7 +445,7 @@ Onboarding за замовчуванням використовує поверх - `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K) - + - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` - `volcengine-plan/kimi-k2.5` @@ -452,7 +459,7 @@ Onboarding за замовчуванням використовує поверх BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine. -- Провайдер: `byteplus` (для програмування: `byteplus-plan`) +- Провайдер: `byteplus` (кодування: `byteplus-plan`) - Автентифікація: `BYTEPLUS_API_KEY` - Приклад моделі: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -465,9 +472,9 @@ BytePlus ARK надає міжнародним користувачам дост } ``` -Onboarding типово використовує поверхню для програмування, але загальний каталог `byteplus/*` реєструється одночасно. +Під час онбордингу за замовчуванням використовується поверхня для кодування, але загальний каталог `byteplus/*` реєструється одночасно. -У засобах вибору моделі під час onboarding/configure варіант автентифікації BytePlus віддає перевагу рядкам і `byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, OpenClaw натомість повертається до нефільтрованого каталогу, а не показує порожній засіб вибору, обмежений провайдером. +У засобах вибору моделей під час онбордингу/налаштування варіант автентифікації BytePlus віддає перевагу рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього засобу вибору, обмеженого провайдером. @@ -476,7 +483,7 @@ Onboarding типово використовує поверхню для про - `byteplus/glm-4-7-251222` (GLM 4.7) - + - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` - `byteplus-plan/kimi-k2.5` @@ -520,30 +527,30 @@ MiniMax налаштовується через `models.providers`, оскіль - MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- MiniMax API key (Global): `--auth-choice minimax-global-api` -- MiniMax API key (CN): `--auth-choice minimax-cn-api` +- Ключ API MiniMax (Global): `--auth-choice minimax-global-api` +- Ключ API MiniMax (CN): `--auth-choice minimax-cn-api` - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` Див. [/providers/minimax](/uk/providers/minimax), щоб дізнатися подробиці налаштування, варіанти моделей і фрагменти конфігурації. -На Anthropic-сумісному шляху потокового передавання MiniMax OpenClaw типово вимикає мислення, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. +На Anthropic-сумісному шляху потокового передавання MiniMax OpenClaw за замовчуванням вимикає мислення, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Розділення можливостей, якими володіє Plugin: +Розподіл можливостей, якими володіє Plugin: -- Типові налаштування тексту/чату залишаються на `minimax/MiniMax-M2.7` +- Стандартні значення для тексту/чату залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень належить Plugin: `MiniMax-VL-01` на обох шляхах автентифікації MiniMax +- Розуміння зображень належить Plugin: `MiniMax-VL-01` в обох шляхах автентифікації MiniMax - Вебпошук залишається на ідентифікаторі провайдера `minimax` ### LM Studio -LM Studio постачається як вбудований Plugin провайдера, який використовує нативний API: +LM Studio постачається як вбудований Plugin провайдера, що використовує нативний API: - Провайдер: `lmstudio` - Автентифікація: `LM_API_TOKEN` -- Типова базова URL-адреса інференсу: `http://localhost:1234/v1` +- Базова URL-адреса інференсу за замовчуванням: `http://localhost:1234/v1` Потім задайте модель (замініть на один з ідентифікаторів, повернених `http://localhost:1234/api/v1/models`): @@ -555,11 +562,11 @@ LM Studio постачається як вбудований Plugin провай } ``` -OpenClaw використовує нативні `/api/v1/models` і `/api/v1/models/load` LM Studio для виявлення й автозавантаження, а `/v1/chat/completions` типово для інференсу. Див. [/providers/lmstudio](/uk/providers/lmstudio), щоб дізнатися про налаштування та усунення несправностей. +OpenClaw використовує нативні `/api/v1/models` і `/api/v1/models/load` LM Studio для виявлення й автоматичного завантаження, а `/v1/chat/completions` — для інференсу за замовчуванням. Див. [/providers/lmstudio](/uk/providers/lmstudio) для налаштування й усунення несправностей. ### Ollama -Ollama постачається як вбудований Plugin провайдера й використовує нативний API Ollama: +Ollama постачається як вбудований Plugin провайдера та використовує нативний API Ollama: - Провайдер: `ollama` - Автентифікація: не потрібна (локальний сервер) @@ -579,17 +586,17 @@ ollama pull llama3.3 } ``` -Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви вмикаєте її через `OLLAMA_API_KEY`, а вбудований Plugin провайдера додає Ollama безпосередньо до `openclaw onboard` і засобу вибору моделі. Див. [/providers/ollama](/uk/providers/ollama), щоб дізнатися про onboarding, хмарний/локальний режим і власну конфігурацію. +Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте це через `OLLAMA_API_KEY`, а вбудований Plugin провайдера додає Ollama безпосередньо до `openclaw onboard` і засобу вибору моделей. Див. [/providers/ollama](/uk/providers/ollama) для онбордингу, хмарного/локального режиму та власної конфігурації. ### vLLM -vLLM постачається як вбудований Plugin провайдера для локальних/самостійно розміщених серверів, сумісних з OpenAI: +vLLM постачається як вбудований Plugin провайдера для локальних/самостійно розгорнутих серверів, сумісних з OpenAI: - Провайдер: `vllm` - Автентифікація: необов’язкова (залежить від вашого сервера) -- Типова базова URL-адреса: `http://127.0.0.1:8000/v1` +- Базова URL-адреса за замовчуванням: `http://127.0.0.1:8000/v1` -Щоб увімкнути локальне автоматичне виявлення (будь-яке значення працює, якщо ваш сервер не вимагає автентифікації): +Щоб явно ввімкнути локальне автоматичне виявлення (працює будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export VLLM_API_KEY="vllm-local" @@ -605,17 +612,17 @@ export VLLM_API_KEY="vllm-local" } ``` -Див. [/providers/vllm](/uk/providers/vllm), щоб дізнатися подробиці. +Див. [/providers/vllm](/uk/providers/vllm) для подробиць. ### SGLang -SGLang постачається як вбудований Plugin провайдера для швидких самостійно розміщених серверів, сумісних з OpenAI: +SGLang постачається як вбудований Plugin провайдера для швидких самостійно розгорнутих серверів, сумісних з OpenAI: - Провайдер: `sglang` - Автентифікація: необов’язкова (залежить від вашого сервера) -- Типова базова URL-адреса: `http://127.0.0.1:30000/v1` +- Базова URL-адреса за замовчуванням: `http://127.0.0.1:30000/v1` -Щоб увімкнути локальне автоматичне виявлення (будь-яке значення працює, якщо ваш сервер не вимагає автентифікації): +Щоб явно ввімкнути локальне автоматичне виявлення (працює будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export SGLANG_API_KEY="sglang-local" @@ -631,7 +638,7 @@ export SGLANG_API_KEY="sglang-local" } ``` -Див. [/providers/sglang](/uk/providers/sglang), щоб дізнатися подробиці. +Див. [/providers/sglang](/uk/providers/sglang) для подробиць. ### Локальні проксі (LM Studio, vLLM, LiteLLM тощо) @@ -670,8 +677,8 @@ export SGLANG_API_KEY="sglang-local" ``` - - Для власних провайдерів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. Якщо їх пропущено, OpenClaw типово використовує: + + Для власних провайдерів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. Якщо їх пропущено, OpenClaw використовує такі стандартні значення: - `reasoning: false` - `input: ["text"]` @@ -679,18 +686,18 @@ export SGLANG_API_KEY="sglang-local" - `contextWindow: 200000` - `maxTokens: 8192` - Рекомендовано: задавайте явні значення, які відповідають обмеженням вашого проксі/моделі. + Рекомендовано: задайте явні значення, що відповідають обмеженням вашого проксі/моделі. - - - Для `api: "openai-completions"` на ненативних кінцевих точках (будь-яка непорожня `baseUrl`, хост якої не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок провайдера 400 для непідтримуваних ролей `developer`. - - Проксі-стиль маршрутів, сумісних з OpenAI, також пропускає нативне формування запитів, властиве лише OpenAI: без `service_tier`, без Responses `store`, без Completions `store`, без підказок prompt-cache, без формування payload сумісності OpenAI reasoning і без прихованих заголовків атрибуції OpenClaw. - - Для OpenAI-сумісних проксі Completions, яким потрібні поля, специфічні для постачальника, задайте `agents.defaults.models["provider/model"].params.extra_body` (або `extraBody`), щоб об’єднати додатковий JSON з тілом вихідного запиту. + + - Для `api: "openai-completions"` на ненативних кінцевих точках (будь-яка непорожня `baseUrl`, хост якої не є `api.openai.com`) OpenClaw примусово задає `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від провайдера для непідтримуваних ролей `developer`. + - Проксі-маршрути, сумісні з OpenAI, також пропускають формування запитів, специфічне лише для нативного OpenAI: без `service_tier`, без Responses `store`, без Completions `store`, без підказок кешу промптів, без формування payload сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw. + - Для проксі OpenAI-сумісних Completions, яким потрібні поля, специфічні для постачальника, задайте `agents.defaults.models["provider/model"].params.extra_body` (або `extraBody`), щоб об’єднати додатковий JSON у вихідне тіло запиту. - Для елементів керування chat-template vLLM задайте `agents.defaults.models["provider/model"].params.chat_template_kwargs`. Вбудований Plugin vLLM автоматично надсилає `enable_thinking: false` і `force_nonempty_content: true` для `vllm/nemotron-3-*`, коли рівень мислення сесії вимкнено. - - Для повільних локальних моделей або віддалених хостів LAN/tailnet задайте `models.providers..timeoutSeconds`. Це розширює обробку HTTP-запиту моделі провайдера, включно з підключенням, заголовками, потоковою передачею тіла й загальним перериванням guarded-fetch, не збільшуючи загальний тайм-аут виконання агента. - - Якщо `baseUrl` порожній/пропущений, OpenClaw зберігає типову поведінку OpenAI (яка розв’язується в `api.openai.com`). - - З міркувань безпеки явний `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних кінцевих точках `openai-completions`. - - Для `api: "anthropic-messages"` на непрямих кінцевих точках (будь-який провайдер, крім канонічного `anthropic`, або власний `models.providers.anthropic.baseUrl`, хост якого не є публічною кінцевою точкою `api.anthropic.com`) OpenClaw пригнічує неявні бета-заголовки Anthropic, як-от `claude-code-20250219`, `interleaved-thinking-2025-05-14` і маркери OAuth, щоб власні Anthropic-сумісні проксі не відхиляли непідтримувані бета-прапорці. Явно задайте `models.providers..headers["anthropic-beta"]`, якщо вашому проксі потрібні конкретні бета-функції. + - Для повільних локальних моделей або віддалених хостів LAN/tailnet задайте `models.providers..timeoutSeconds`. Це розширює обробку HTTP-запитів до моделей провайдера, включно з підключенням, заголовками, потоковим передаванням тіла та повним guarded-fetch abort, не збільшуючи загальний тайм-аут виконання агента. + - Якщо `baseUrl` порожній/пропущений, OpenClaw зберігає стандартну поведінку OpenAI (яка розв’язується до `api.openai.com`). + - З міркувань безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних кінцевих точках `openai-completions`. + - Для `api: "anthropic-messages"` на непрямих кінцевих точках (будь-який провайдер, окрім канонічного `anthropic`, або власний `models.providers.anthropic.baseUrl`, хост якого не є публічною кінцевою точкою `api.anthropic.com`) OpenClaw пригнічує неявні бета-заголовки Anthropic, як-от `claude-code-20250219`, `interleaved-thinking-2025-05-14` і маркери OAuth, щоб власні Anthropic-сумісні проксі не відхиляли непідтримувані бета-прапорці. Явно задайте `models.providers..headers["anthropic-beta"]`, якщо вашому проксі потрібні певні бета-функції. @@ -707,7 +714,7 @@ openclaw models list ## Пов’язане -- [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей -- [Відмовостійке перемикання моделей](/uk/concepts/model-failover) — ланцюжки резервування та поведінка повторних спроб +- [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделі +- [Відмовостійкість моделей](/uk/concepts/model-failover) — ланцюжки резервування та поведінка повторних спроб - [Моделі](/uk/concepts/models) — конфігурація моделей і псевдоніми - [Провайдери](/uk/providers) — посібники з налаштування для кожного провайдера diff --git a/docs/uk/concepts/models.md b/docs/uk/concepts/models.md index 73fea634c..05d3de997 100644 --- a/docs/uk/concepts/models.md +++ b/docs/uk/concepts/models.md @@ -1,36 +1,36 @@ --- read_when: - Додавання або змінення CLI для моделей (models list/set/scan/aliases/fallbacks) - - Зміна поведінки резервного перемикання моделі або користувацького досвіду вибору + - Зміна поведінки резервного переходу моделі або UX вибору - Оновлення зондів сканування моделей (інструменти/зображення) sidebarTitle: Models CLI -summary: 'CLI моделей: список, задання, псевдоніми, резервні варіанти, сканування, статус' +summary: 'CLI моделей: список, встановлення, псевдоніми, резервні варіанти, сканування, статус' title: CLI моделей x-i18n: - generated_at: "2026-04-29T17:09:53Z" + generated_at: "2026-05-02T02:37:24Z" model: gpt-5.5 provider: openai - source_hash: 64b97ddfcc6f804044580dfc9a441d426f737e9e7d007d78b0b045a52068b34f + source_hash: 620df60ee1117a32f0232bf4b56fbc5a9558be5cc3b73a31336f8ab64fd29ebb source_path: concepts/models.md workflow: 16 --- - - Ротація профілів автентифікації, періоди охолодження та їхня взаємодія з резервними варіантами. + + Ротація профілів автентифікації, періоди очікування та як це взаємодіє з резервними варіантами. - - Короткий огляд постачальників і приклади. + + Короткий огляд провайдерів і приклади. PI, Codex та інші середовища виконання циклу агента. - Ключі конфігурації моделей. + Ключі конфігурації моделі. -Посилання на моделі вибирають постачальника й модель. Зазвичай вони не вибирають низькорівневе середовище виконання агента. Наприклад, `openai/gpt-5.5` може працювати через звичайний шлях постачальника OpenAI або через середовище виконання app-server Codex, залежно від `agents.defaults.agentRuntime.id`. Див. [Середовища виконання агентів](/uk/concepts/agent-runtimes). +Посилання на моделі вибирають провайдера й модель. Зазвичай вони не вибирають низькорівневе середовище виконання агента. Наприклад, `openai/gpt-5.5` може запускатися через звичайний шлях провайдера OpenAI або через середовище виконання app-server Codex, залежно від `agents.defaults.agentRuntime.id`. У режимі середовища виконання Codex посилання `openai/gpt-*` не означає оплату за API-ключем; автентифікація може надходити з облікового запису Codex або профілю автентифікації `openai-codex`. Див. [Середовища виконання агентів](/uk/concepts/agent-runtimes). ## Як працює вибір моделі @@ -43,8 +43,8 @@ OpenClaw вибирає моделі в такому порядку: `agents.defaults.model.fallbacks` (за порядком). - - Аварійне перемикання автентифікації відбувається всередині постачальника перед переходом до наступної моделі. + + Відмовостійке перемикання автентифікації відбувається всередині провайдера перед переходом до наступної моделі. @@ -52,41 +52,41 @@ OpenClaw вибирає моделі в такому порядку: - `agents.defaults.models` — це allowlist/каталог моделей, які OpenClaw може використовувати (плюс псевдоніми). - `agents.defaults.imageModel` використовується **лише коли** основна модель не може приймати зображення. - - `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо його пропущено, інструмент переходить до `agents.defaults.imageModel`, а потім до визначеної моделі сеансу/типової моделі. - - `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо його пропущено, `image_generate` усе ще може визначити типове значення постачальника з підтримкою автентифікації. Спочатку він пробує поточного типового постачальника, потім решту зареєстрованих постачальників генерації зображень у порядку provider-id. Якщо ви задаєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника. - - `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його пропущено, `music_generate` усе ще може визначити типове значення постачальника з підтримкою автентифікації. Спочатку він пробує поточного типового постачальника, потім решту зареєстрованих постачальників генерації музики в порядку provider-id. Якщо ви задаєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника. - - `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його пропущено, `video_generate` усе ще може визначити типове значення постачальника з підтримкою автентифікації. Спочатку він пробує поточного типового постачальника, потім решту зареєстрованих постачальників генерації відео в порядку provider-id. Якщо ви задаєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника. - - Типові значення для окремих агентів можуть перевизначати `agents.defaults.model` через `agents.list[].model` плюс прив’язки (див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent)). + - `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо його не вказано, інструмент переходить до `agents.defaults.imageModel`, а потім до розв’язаної моделі сесії/моделі за замовчуванням. + - `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо його не вказано, `image_generate` усе ще може вивести стандартного провайдера, підкріпленого автентифікацією. Спершу він пробує поточного стандартного провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера. + - `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його не вказано, `music_generate` усе ще може вивести стандартного провайдера, підкріпленого автентифікацією. Спершу він пробує поточного стандартного провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера. + - `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його не вказано, `video_generate` усе ще може вивести стандартного провайдера, підкріпленого автентифікацією. Спершу він пробує поточного стандартного провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера. + - Стандартні значення для окремого агента можуть перевизначати `agents.defaults.model` через `agents.list[].model` плюс прив’язки (див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent)). -## Джерело вибору та поведінка резервних варіантів +## Джерело вибору й поведінка резервного переходу -Один і той самий `provider/model` може означати різні речі залежно від того, звідки він узявся: +Однакове `provider/model` може означати різні речі залежно від того, звідки воно походить: -- Налаштовані типові значення (`agents.defaults.model.primary` і основні моделі для конкретних агентів) є звичайною початковою точкою та використовують `agents.defaults.model.fallbacks`. -- Автоматичні резервні вибори — це тимчасовий стан відновлення. Вони зберігаються з `modelOverrideSource: "auto"`, щоб наступні ходи могли й надалі використовувати ланцюжок резервних варіантів без початкової перевірки відомо несправної основної моделі. -- Вибори користувача в сеансі є точними. `/model`, вибір моделі, `session_status(model=...)` і `sessions.patch` зберігають `modelOverrideSource: "user"`; якщо вибраний постачальник/модель недоступні, OpenClaw завершується з видимою помилкою замість переходу до іншої налаштованої моделі. -- Cron `--model` / payload `model` — це основна модель для окремого завдання. Вона все одно використовує налаштовані резервні варіанти, якщо завдання не надає явні payload `fallbacks` (використовуйте `fallbacks: []` для строгого запуску cron). -- Засоби вибору типової моделі CLI та allowlist поважають `models.mode: "replace"`, показуючи явні `models.providers.*.models` замість завантаження повного вбудованого каталогу. -- Засіб вибору моделей Control UI запитує в Gateway налаштований перегляд моделей: `agents.defaults.models`, якщо він наявний, інакше явні `models.providers.*.models` плюс постачальники з придатною автентифікацією. Повний вбудований каталог зарезервовано для явних переглядів огляду, таких як `models.list` з `view: "all"` або `openclaw models list --all`. +- Налаштовані стандартні значення (`agents.defaults.model.primary` та специфічні для агента основні моделі) є звичайною відправною точкою й використовують `agents.defaults.model.fallbacks`. +- Автоматичні резервні вибори — це тимчасовий стан відновлення. Вони зберігаються з `modelOverrideSource: "auto"`, щоб наступні ходи могли далі використовувати резервний ланцюжок без попереднього зондування відомої проблемної основної моделі. +- Вибори користувача для сесії є точними. `/model`, засіб вибору моделі, `session_status(model=...)` і `sessions.patch` зберігають `modelOverrideSource: "user"`; якщо вибраний provider/model недоступний, OpenClaw завершується видимою помилкою замість переходу до іншої налаштованої моделі. +- Cron `--model` / payload `model` — це основна модель для окремого завдання. Вона все одно використовує налаштовані резервні варіанти, якщо завдання не надає явні payload `fallbacks` (використовуйте `fallbacks: []` для суворого запуску cron). +- CLI default-model і засоби вибору allowlist поважають `models.mode: "replace"`, показуючи явні `models.providers.*.models` замість завантаження повного вбудованого каталогу. +- Засіб вибору моделі в Control UI запитує в Gateway налаштоване подання моделей: `agents.defaults.models`, якщо воно наявне, інакше явні `models.providers.*.models` плюс провайдери з придатною автентифікацією. Повний вбудований каталог зарезервований для явних подань перегляду, таких як `models.list` з `view: "all"` або `openclaw models list --all`. ## Коротка політика моделей -- Установіть основною найсильнішу модель найновішого покоління, доступну вам. -- Використовуйте резервні варіанти для завдань, чутливих до вартості/затримки, і менш критичного чату. -- Для агентів із підтримкою інструментів або недовірених вхідних даних уникайте старіших/слабших рівнів моделей. +- Задайте основною найпотужнішу доступну вам модель останнього покоління. +- Використовуйте резервні варіанти для завдань, чутливих до вартості/затримки, і чатів із нижчими ризиками. +- Для агентів з увімкненими інструментами або недовірених вхідних даних уникайте старіших/слабших рівнів моделей. -## Початкове налаштування (рекомендовано) +## Онбординг (рекомендовано) -Якщо ви не хочете редагувати конфігурацію вручну, запустіть початкове налаштування: +Якщо ви не хочете редагувати конфігурацію вручну, запустіть онбординг: ```bash openclaw onboard ``` -Воно може налаштувати модель + автентифікацію для поширених постачальників, зокрема **підписку OpenAI Code (Codex)** (OAuth) і **Anthropic** (API key або Claude CLI). +Він може налаштувати модель + автентифікацію для поширених провайдерів, зокрема **підписку OpenAI Code (Codex)** (OAuth) і **Anthropic** (API-ключ або Claude CLI). ## Ключі конфігурації (огляд) @@ -95,18 +95,18 @@ openclaw onboard - `agents.defaults.pdfModel.primary` і `agents.defaults.pdfModel.fallbacks` - `agents.defaults.imageGenerationModel.primary` і `agents.defaults.imageGenerationModel.fallbacks` - `agents.defaults.videoGenerationModel.primary` і `agents.defaults.videoGenerationModel.fallbacks` -- `agents.defaults.models` (allowlist + псевдоніми + параметри постачальника) -- `models.providers` (користувацькі постачальники, записані в `models.json`) +- `agents.defaults.models` (allowlist + псевдоніми + параметри провайдера) +- `models.providers` (користувацькі провайдери, записані в `models.json`) -Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми постачальників, як-от `z.ai/*`, нормалізуються до `zai/*`. +Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів на кшталт `z.ai/*` нормалізуються до `zai/*`. -Приклади конфігурації постачальників (включно з OpenCode) розміщені в [OpenCode](/uk/providers/opencode). +Приклади конфігурації провайдерів (включно з OpenCode) містяться в [OpenCode](/uk/providers/opencode). ### Безпечні редагування allowlist -Використовуйте адитивні записи під час ручного оновлення `agents.defaults.models`: +Використовуйте адитивні записи, коли оновлюєте `agents.defaults.models` вручну: ```bash openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge @@ -114,23 +114,23 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json - `openclaw config set` захищає мапи моделей/постачальників від випадкових перезаписів. Просте присвоєння об’єкта до `agents.defaults.models`, `models.providers` або `models.providers..models` відхиляється, якщо воно видалило б наявні записи. Використовуйте `--merge` для адитивних змін; використовуйте `--replace` лише тоді, коли надане значення має стати повним цільовим значенням. + `openclaw config set` захищає мапи моделей/провайдерів від випадкових перезаписів. Звичайне присвоєння об’єкта до `agents.defaults.models`, `models.providers` або `models.providers..models` відхиляється, якщо воно вилучило б наявні записи. Використовуйте `--merge` для адитивних змін; використовуйте `--replace` лише тоді, коли надане значення має стати повним цільовим значенням. - Інтерактивне налаштування постачальника й `openclaw configure --section model` також об’єднують вибори в межах постачальника з наявним allowlist, тому додавання Codex, Ollama або іншого постачальника не видаляє непов’язані записи моделей. Configure зберігає наявний `agents.defaults.model.primary`, коли автентифікацію постачальника застосовують повторно. Явні команди встановлення типового значення, такі як `openclaw models auth login --provider --set-default` і `openclaw models set `, усе ще замінюють `agents.defaults.model.primary`. + Інтерактивне налаштування провайдера й `openclaw configure --section model` також зливають вибори в межах провайдера з наявним allowlist, тож додавання Codex, Ollama або іншого провайдера не видаляє непов’язані записи моделей. Configure зберігає наявний `agents.defaults.model.primary`, коли автентифікацію провайдера застосовують повторно. Явні команди встановлення стандартного значення, такі як `openclaw models auth login --provider --set-default` і `openclaw models set `, усе ще замінюють `agents.defaults.model.primary`. -## «Модель не дозволена» (і чому відповіді зупиняються) +## "Модель не дозволена" (і чому відповіді зупиняються) -Якщо `agents.defaults.models` задано, він стає **allowlist** для `/model` і для перевизначень сеансу. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає: +Якщо `agents.defaults.models` задано, він стає **allowlist** для `/model` і перевизначень сесії. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` -Це відбувається **до** генерації звичайної відповіді, тому може здаватися, що повідомлення «не відповіло». Виправлення таке: +Це відбувається **до** створення звичайної відповіді, тому може здаватися, що повідомлення "не відповіло". Виправлення: зробіть одне з такого: - Додайте модель до `agents.defaults.models`, або - Очистьте allowlist (видаліть `agents.defaults.models`), або @@ -138,7 +138,7 @@ Model "provider/model" is not allowed. Use /model to list available models. -Для локальних/GGUF моделей зберігайте повне посилання з префіксом постачальника в allowlist, +Для локальних/GGUF-моделей зберігайте повне посилання з префіксом провайдера в allowlist, наприклад `ollama/gemma4:26b`, `lmstudio/Gemma4-26b-a4-it-gguf` або точний provider/model, показаний `openclaw models list --provider `. Самих локальних імен файлів або відображуваних назв недостатньо, коли allowlist @@ -160,7 +160,7 @@ Model "provider/model" is not allowed. Use /model to list available models. ## Перемикання моделей у чаті (`/model`) -Ви можете перемикати моделі для поточного сеансу без перезапуску: +Ви можете перемикати моделі для поточної сесії без перезапуску: ``` /model @@ -172,28 +172,28 @@ Model "provider/model" is not allowed. Use /model to list available models. - - `/model` (і `/model list`) — це компактний нумерований засіб вибору (родина моделей + доступні постачальники). - - У Discord `/model` і `/models` відкривають інтерактивний засіб вибору з розкривними списками постачальника й моделі плюс кроком Submit. - - `/models add` застарів і тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. + - `/model` (і `/model list`) — це компактний нумерований засіб вибору (родина моделі + доступні провайдери). + - У Discord `/model` і `/models` відкривають інтерактивний засіб вибору з випадаючими списками провайдера й моделі та кроком Submit. + - `/models add` застарілий і тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. - `/model <#>` вибирає з цього засобу вибору. - - `/model` негайно зберігає новий вибір сеансу. - - Якщо агент бездіяльний, наступний запуск одразу використовує нову модель. - - Якщо запуск уже активний, OpenClaw позначає живе перемикання як очікуване й перезапускає в нову модель лише в чистій точці повтору. - - Якщо активність інструментів або виведення відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повтору або наступного ходу користувача. - - Вибране користувачем посилання `/model` є строгим для цього сеансу: якщо вибраний постачальник/модель недоступні, відповідь завершується з видимою помилкою замість тихої відповіді з `agents.defaults.model.fallbacks`. Це відрізняється від налаштованих типових значень і основних моделей завдань cron, які все ще можуть використовувати ланцюжки резервних варіантів. - - `/model status` — це докладний перегляд (кандидати автентифікації та, якщо налаштовано, endpoint постачальника `baseUrl` + режим `api`). + - `/model` одразу зберігає новий вибір сесії. + - Якщо агент бездіє, наступний запуск одразу використовує нову модель. + - Якщо запуск уже активний, OpenClaw позначає живе перемикання як очікуване й перезапускає в нову модель лише в чистій точці повторної спроби. + - Якщо активність інструментів або виведення відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача. + - Вибране користувачем посилання `/model` є суворим для цієї сесії: якщо вибраний provider/model недоступний, відповідь завершується видимою помилкою замість тихого використання `agents.defaults.model.fallbacks`. Це відрізняється від налаштованих стандартних значень і основних моделей cron-завдань, які все ще можуть використовувати резервні ланцюжки. + - `/model status` — це детальне подання (кандидати автентифікації та, коли налаштовано, endpoint провайдера `baseUrl` + режим `api`). - Посилання на моделі розбираються поділом за **першим** `/`. Використовуйте `provider/model`, коли вводите `/model `. - - Якщо ID моделі сам містить `/` (у стилі OpenRouter), потрібно включити префікс постачальника (приклад: `/model openrouter/moonshotai/kimi-k2`). - - Якщо ви пропустите постачальника, OpenClaw визначає введення в такому порядку: + - Якщо сам ID моделі містить `/` (у стилі OpenRouter), потрібно включити префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`). + - Якщо ви пропускаєте провайдера, OpenClaw розв’язує введення в такому порядку: 1. збіг псевдоніма - 2. унікальний збіг налаштованого постачальника для цього точного ID моделі без префікса - 3. застарілий перехід до налаштованого типового постачальника — якщо цей постачальник більше не надає налаштовану типову модель, OpenClaw натомість переходить до першого налаштованого постачальника/моделі, щоб уникнути показу застарілого типового значення видаленого постачальника. + 2. унікальний збіг налаштованого провайдера для цього точного id моделі без префікса + 3. застарілий резервний перехід до налаштованого стандартного провайдера — якщо цей провайдер більше не надає налаштовану стандартну модель, OpenClaw натомість переходить до першого налаштованого provider/model, щоб не показувати застаріле стандартне значення вилученого провайдера. @@ -229,13 +229,13 @@ openclaw models image-fallbacks clear За замовчуванням показує налаштовані/доступні через автентифікацію моделі. Корисні прапорці: - Повний каталог. Містить рядки вбудованого статичного каталогу, що належать постачальникам, до налаштування автентифікації, тому перегляди лише для виявлення можуть показувати моделі, недоступні, доки ви не додасте відповідні облікові дані постачальника. + Повний каталог. Містить статичні рядки каталогу вбудованих моделей, що належать провайдерам, ще до налаштування автентифікації, тому подання лише для виявлення можуть показувати моделі, недоступні, доки ви не додасте відповідні облікові дані провайдера. - Лише локальні постачальники. + Лише локальні провайдери. - Фільтрувати за ID постачальника, наприклад `moonshot`. Відображувані мітки з інтерактивних засобів вибору не приймаються. + Фільтрувати за ідентифікатором провайдера, наприклад `moonshot`. Відображувані мітки з інтерактивних вибирачів не приймаються. Одна модель на рядок. @@ -246,21 +246,21 @@ openclaw models image-fallbacks clear ### `models status` -Показує визначену основну модель, резервні варіанти, модель зображень і огляд автентифікації налаштованих провайдерів. Також показує статус завершення терміну дії OAuth для профілів, знайдених у сховищі автентифікації (за замовчуванням попереджає протягом 24 год). `--plain` друкує лише визначену основну модель. +Показує визначену основну модель, резервні варіанти, модель зображень і огляд автентифікації налаштованих провайдерів. Також показує статус завершення терміну дії OAuth для профілів, знайдених у сховищі автентифікації (за замовчуванням попереджає за 24 год). `--plain` друкує лише визначену основну модель. - + - Статус OAuth показується завжди (і включається у вивід `--json`). Якщо налаштований провайдер не має облікових даних, `models status` друкує розділ **Відсутня автентифікація**. - - JSON містить `auth.oauth` (вікно попередження + профілі) і `auth.providers` (ефективна автентифікація для кожного провайдера, включно з обліковими даними з env). `auth.oauth` відображає лише стан профілів у сховищі автентифікації; провайдери лише з env там не з'являються. - - Використовуйте `--check` для автоматизації (код виходу `1`, якщо відсутньо або прострочено, `2`, якщо термін дії незабаром завершується). - - Використовуйте `--probe` для живих перевірок автентифікації; рядки перевірки можуть походити з профілів автентифікації, облікових даних env або `models.json`. - - Якщо явний `auth.order.` пропускає збережений профіль, перевірка повідомляє `excluded_by_auth_order` замість спроби його використати. Якщо автентифікація існує, але для цього провайдера неможливо визначити модель для перевірки, перевірка повідомляє `status: no_model`. + - JSON містить `auth.oauth` (вікно попередження + профілі) і `auth.providers` (ефективна автентифікація для кожного провайдера, включно з обліковими даними з env). `auth.oauth` показує лише стан профілів зі сховища автентифікації; провайдери лише з env там не з'являються. + - Використовуйте `--check` для автоматизації (код виходу `1`, коли бракує або завершився термін дії, `2`, коли термін дії скоро завершиться). + - Використовуйте `--probe` для live-перевірок автентифікації; рядки перевірок можуть надходити з профілів автентифікації, облікових даних env або `models.json`. + - Якщо явний `auth.order.` пропускає збережений профіль, перевірка повідомляє `excluded_by_auth_order` замість спроби використати його. Якщо автентифікація існує, але для цього провайдера не можна визначити модель, придатну до перевірки, перевірка повідомляє `status: no_model`. -Вибір автентифікації залежить від провайдера й облікового запису. Для постійно активних хостів Gateway API-ключі зазвичай є найпередбачуванішими; також підтримуються повторне використання Claude CLI та наявні профілі Anthropic OAuth/токенів. +Вибір автентифікації залежить від провайдера й облікового запису. Для постійно ввімкнених хостів Gateway ключі API зазвичай найпередбачуваніші; також підтримується повторне використання Claude CLI та наявні профілі Anthropic OAuth/token. Приклад (Claude CLI): @@ -275,7 +275,7 @@ openclaw models status `openclaw models scan` перевіряє **каталог безкоштовних моделей** OpenRouter і може додатково перевіряти моделі на підтримку інструментів і зображень. - Пропустити живі перевірки (лише метадані). + Пропустити live-перевірки (лише метадані). Мінімальний розмір параметрів (у мільярдах). @@ -290,14 +290,14 @@ openclaw models status Розмір списку резервних варіантів. - Встановити `agents.defaults.model.primary` на перший вибраний варіант. + Установити `agents.defaults.model.primary` на перший вибраний варіант. - Встановити `agents.defaults.imageModel.primary` на перший вибраний варіант зображень. + Установити `agents.defaults.imageModel.primary` на перший вибраний варіант зображень. -Каталог OpenRouter `/models` є публічним, тому сканування лише метаданих може показувати безкоштовних кандидатів без ключа. Перевірка та інференс усе одно потребують API-ключа OpenRouter (із профілів автентифікації або `OPENROUTER_API_KEY`). Якщо ключ недоступний, `openclaw models scan` повертається до виводу лише метаданих і залишає конфігурацію без змін. Використовуйте `--no-probe`, щоб явно запросити режим лише метаданих. +Каталог OpenRouter `/models` є публічним, тому сканування лише метаданих може показувати безкоштовних кандидатів без ключа. Перевірки й інференс усе одно потребують ключа API OpenRouter (з профілів автентифікації або `OPENROUTER_API_KEY`). Якщо ключ недоступний, `openclaw models scan` повертається до виводу лише метаданих і залишає конфігурацію без змін. Використовуйте `--no-probe`, щоб явно запросити режим лише метаданих. Результати сканування ранжуються за: @@ -310,24 +310,24 @@ openclaw models status Вхідні дані: - Список OpenRouter `/models` (фільтр `:free`) -- Живі перевірки потребують API-ключа OpenRouter із профілів автентифікації або `OPENROUTER_API_KEY` (див. [Змінні середовища](/uk/help/environment)) +- Live-перевірки потребують ключа API OpenRouter з профілів автентифікації або `OPENROUTER_API_KEY` (див. [Змінні середовища](/uk/help/environment)) - Необов'язкові фільтри: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates` - Елементи керування запитами/перевірками: `--timeout`, `--concurrency` -Коли живі перевірки виконуються в TUI, ви можете інтерактивно вибирати резервні варіанти. У неінтерактивному режимі передайте `--yes`, щоб прийняти типові значення. Результати лише метаданих є інформаційними; `--set-default` і `--set-image` потребують живих перевірок, щоб OpenClaw не налаштував непридатну до використання модель OpenRouter без ключа. +Коли live-перевірки виконуються в TTY, ви можете інтерактивно вибирати резервні варіанти. У неінтерактивному режимі передайте `--yes`, щоб прийняти значення за замовчуванням. Результати лише за метаданими є інформаційними; `--set-default` і `--set-image` потребують live-перевірок, щоб OpenClaw не налаштував непридатну до використання модель OpenRouter без ключа. ## Реєстр моделей (`models.json`) -Користувацькі провайдери в `models.providers` записуються в `models.json` у каталозі агента (за замовчуванням `~/.openclaw/agents//agent/models.json`). Цей файл за замовчуванням об'єднується, якщо `models.mode` не встановлено на `replace`. +Користувацькі провайдери в `models.providers` записуються в `models.json` у каталозі агента (за замовчуванням `~/.openclaw/agents//agent/models.json`). Цей файл за замовчуванням об'єднується, якщо `models.mode` не встановлено в `replace`. - Пріоритет режиму об'єднання для відповідних ID провайдерів: + Пріоритет режиму об'єднання для відповідних ідентифікаторів провайдерів: - - Непорожній `baseUrl`, уже наявний в агентському `models.json`, має пріоритет. - - Непорожній `apiKey` в агентському `models.json` має пріоритет лише тоді, коли цей провайдер не керується SecretRef у поточному контексті конфігурації/профілю автентифікації. - - Значення `apiKey` провайдера, керованого SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів. - - Значення заголовків провайдера, керованого SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань). + - Непорожній `baseUrl`, уже наявний в агентському `models.json`, має перевагу. + - Непорожній `apiKey` в агентському `models.json` має перевагу лише тоді, коли цей провайдер не керується SecretRef у поточному контексті конфігурації/профілю автентифікації. + - Значення `apiKey` провайдера, керованого SecretRef, оновлюються з вихідних маркерів (`ENV_VAR_NAME` для посилань env, `secretref-managed` для посилань file/exec) замість збереження визначених секретів. + - Значення заголовків провайдера, керованого SecretRef, оновлюються з вихідних маркерів (`secretref-env:ENV_VAR_NAME` для посилань env, `secretref-managed` для посилань file/exec). - Порожні або відсутні агентські `apiKey`/`baseUrl` повертаються до `models.providers` з конфігурації. - Інші поля провайдера оновлюються з конфігурації та нормалізованих даних каталогу. @@ -335,15 +335,15 @@ openclaw models status -Збереження маркерів спирається на джерело як авторитетне: OpenClaw записує маркери з активного знімка конфігурації джерела (до визначення), а не з визначених значень runtime-секретів. Це застосовується щоразу, коли OpenClaw регенерує `models.json`, зокрема в шляхах, керованих командами, як-от `openclaw agent`. +Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка вихідної конфігурації (до визначення), а не з визначених значень runtime-секретів. Це застосовується щоразу, коли OpenClaw регенерує `models.json`, зокрема для шляхів, керованих командами, як-от `openclaw agent`. ## Пов'язане -- [Runtime агента](/uk/concepts/agent-runtimes) — PI, Codex та інші runtime циклу агента +- [Середовища виконання агентів](/uk/concepts/agent-runtimes) — PI, Codex та інші середовища виконання агентського циклу - [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей -- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделі зображень -- [Відмовостійкість моделей](/uk/concepts/model-failover) — ланцюжки резервних варіантів -- [Провайдери моделей](/uk/concepts/model-providers) — маршрутизація й автентифікація провайдерів -- [Генерація музики](/uk/tools/music-generation) — конфігурація моделі музики -- [Генерація відео](/uk/tools/video-generation) — конфігурація моделі відео +- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделей зображень +- [Відмовостійке перемикання моделей](/uk/concepts/model-failover) — ланцюжки резервних варіантів +- [Провайдери моделей](/uk/concepts/model-providers) — маршрутизація провайдерів і автентифікація +- [Генерація музики](/uk/tools/music-generation) — конфігурація моделей музики +- [Генерація відео](/uk/tools/video-generation) — конфігурація моделей відео diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index 552f00310..3fc551032 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - - Додавання або змінення міграцій doctor - - Запровадження змін конфігурації, що порушують сумісність + - Додавання або змінення діагностичних міграцій + - Впровадження несумісних змін конфігурації sidebarTitle: Doctor -summary: 'Команда doctor: перевірки справності, міграції конфігурації та кроки відновлення' +summary: 'Команда doctor: перевірки працездатності, міграції конфігурації та кроки відновлення' title: Діагностика x-i18n: - generated_at: "2026-05-01T21:50:52Z" + generated_at: "2026-05-02T02:37:09Z" model: gpt-5.5 provider: openai - source_hash: bbcac6787b25db196dfc6bf7afc44afc26e9b19d219106c407e32e1d090c2344 + source_hash: ff4ab00fd6a11588abe790350fe139bc49f61e688bcd741389dd63732aa4430c source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє справність і надає практичні кроки для відновлення. +`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє справність і надає дієві кроки з відновлення. ## Швидкий старт @@ -22,7 +22,7 @@ x-i18n: openclaw doctor ``` -### Безголові режими та режими автоматизації +### Режими без інтерфейсу та автоматизації @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - Прийняти типові значення без запитів (зокрема кроки відновлення перезапуску/служби/пісочниці, коли це застосовно). + Приймати типові значення без запитів (зокрема кроки перезапуску/служби/відновлення sandbox, коли застосовно). @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски там, де це безпечно). + Застосувати рекомендовані відновлення без запитів (відновлення + перезапуски там, де це безпечно). @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - Також застосувати агресивні виправлення (перезаписує користувацькі конфігурації супервізора). + Також застосувати агресивні відновлення (перезаписує власні конфігурації supervisor). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - Запустити без запитів і застосувати лише безпечні міграції (нормалізацію конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службою/пісочницею, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично після виявлення. + Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/служби/sandbox, які потребують підтвердження людини. Застарілі міграції стану запускаються автоматично, коли їх виявлено. @@ -62,7 +62,7 @@ openclaw doctor openclaw doctor --deep ``` - Сканувати системні служби на наявність додаткових інсталяцій gateway (launchd/systemd/schtasks). + Сканувати системні служби на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks). @@ -76,118 +76,118 @@ cat ~/.openclaw/openclaw.json ## Що він робить (коротко) - + - Необов’язкове попереднє оновлення для git-інсталяцій (лише інтерактивно). - - Перевірка актуальності протоколу UI (перезбирає Control UI, коли схема протоколу новіша). + - Перевірка актуальності протоколу інтерфейсу (перезбирає інтерфейс керування, коли схема протоколу новіша). - Перевірка справності + запит на перезапуск. - - Підсумок стану Skills (придатні/відсутні/заблоковані) і стан Plugin. + - Зведення стану Skills (придатні/відсутні/заблоковані) і стан Plugin. - Нормалізація конфігурації для застарілих значень. - - Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. + - Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.`. - Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. - Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - Попередження про затінення Codex OAuth (`models.providers.openai-codex`). - Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth. - Попередження allowlist Plugin/інструментів, коли `plugins.allow` є обмежувальним, але політика інструментів усе ще запитує wildcard або інструменти, що належать Plugin. - - Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp). + - Міграція застарілого стану на диску (сеанси/каталог агента/автентифікація WhatsApp). - Міграція застарілих ключів контракту маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля доставки/корисного навантаження верхнього рівня, `provider` у корисному навантаженні, прості fallback-завдання Webhook `notify: true`). - - Міграція застарілої політики runtime агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. - - Очищення застарілої конфігурації Plugin, коли плагіни увімкнені; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною конфігурацією ізоляції та зберігаються. + - Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля доставки/payload верхнього рівня, payload `provider`, прості резервні завдання Webhook `notify: true`). + - Міграція застарілої політики виконання агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. + - Очищення застарілої конфігурації Plugin, коли plugins увімкнені; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною конфігурацією стримування та зберігаються. - - Перевірка файлів блокування сесій і очищення застарілих блокувань. - - Відновлення транскриптів сесій для дубльованих гілок переписування промптів, створених ураженими збірками 2026.4.24. - - Виявлення tombstone для відновлення після перезапуску завислого субагента з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб запуск не продовжував трактувати дочірній процес як перерваний перезапуском. - - Перевірки цілісності стану та дозволів (сесії, транскрипти, каталог стану). + - Перевірка файлів блокування сеансів і очищення застарілих блокувань. + - Відновлення транскриптів сеансів для дубльованих гілок переписування prompt, створених ураженими збірками 2026.4.24. + - Виявлення tombstone для відновлення після перезапуску завислого subagent, з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб запуск не продовжував вважати дочірній процес перерваним під час перезапуску. + - Перевірки цілісності стану та дозволів (сеанси, транскрипти, каталог стану). - Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску. - - Справність автентифікації моделі: перевіряє завершення строку дії OAuth, може оновлювати токени, що скоро спливають, і повідомляє про cooldown/вимкнені стани auth-profile. + - Справність автентифікації моделей: перевіряє завершення терміну дії OAuth, може оновлювати токени, що скоро завершаться, і повідомляє про стани cooldown/вимкнення auth-profile. - Виявлення додаткового каталогу робочого простору (`~/openclaw`). - - - Відновлення образу пісочниці, коли пісочницю увімкнено. - - Міграція застарілої служби та виявлення додаткових gateway. + + - Відновлення образу sandbox, коли sandboxing увімкнено. + - Міграція застарілої служби та виявлення додаткових Gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). - - Перевірки runtime Gateway (службу встановлено, але вона не запущена; кешована мітка launchd). - - Попередження стану каналів (перевіряються з запущеного gateway). - - Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим відновленням. - - Очищення середовища вбудованого проксі для служб gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час інсталяції або оновлення. + - Перевірки виконання Gateway (службу встановлено, але не запущено; кешована мітка launchd). + - Попередження стану каналів (перевіряються з запущеного Gateway). + - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням. + - Очищення середовища вбудованого proxy для служб Gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення. - Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи менеджера версій). - - Діагностика конфлікту порту Gateway (типово `18789`). + - Діагностика конфліктів портів Gateway (типово `18789`). - Попередження безпеки для відкритих політик DM. - - Перевірки автентифікації Gateway для режиму локального токена (пропонує згенерувати токен, коли джерела токена немає; не перезаписує конфігурації токена SecretRef). - - Виявлення проблем зі спарюванням пристрою (очікувані запити першого спарювання, очікувані підвищення ролі/обсягу, застаріле розходження кешу локального device-token і розходження автентифікації paired-record). + - Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена немає; не перезаписує конфігурації SecretRef токена). + - Виявлення проблем зі спарюванням пристроїв (очікувані запити першого спарювання, очікувані підвищення ролі/обсягу, дрейф застарілого локального кешу device-token і дрейф автентифікації paired-record). - Перевірка systemd linger у Linux. - - Перевірка розміру bootstrap-файлу робочого простору (попередження про усічення/наближення до ліміту для контекстних файлів). - - Перевірка стану shell completion і автоінсталяція/оновлення. - - Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, ключ віддаленого API або бінарний файл QMD). - - Перевірки інсталяції з вихідного коду (невідповідність pnpm workspace, відсутні UI-активи, відсутній бінарний файл tsx). + - Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів). + - Перевірка стану shell completion і автоматичне встановлення/оновлення. + - Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, ключ віддаленого API або binary QMD). + - Перевірки інсталяції з вихідного коду (невідповідність робочого простору pnpm, відсутні UI assets, відсутній binary tsx). - Записує оновлену конфігурацію + метадані майстра. -## Зворотне заповнення та скидання UI Dreams +## Зворотне заповнення та скидання інтерфейсу Dreams -Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи gateway у стилі doctor, але вони **не** є частиною CLI-відновлення/міграції `openclaw doctor`. +Сцена Dreams в інтерфейсі керування містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи Gateway у стилі doctor, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`. Що вони роблять: - **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує оборотні записи зворотного заповнення в `DREAMS.md`. -- **Reset** видаляє лише ці позначені diary-записи зворотного заповнення з `DREAMS.md`. -- **Clear Grounded** видаляє лише підготовлені короткострокові записи only-grounded, які надійшли з історичного відтворення й ще не накопичили live recall або daily support. +- **Reset** видаляє лише ці позначені записи щоденника зворотного заповнення з `DREAMS.md`. +- **Clear Grounded** видаляє лише staged короткострокові записи тільки grounded, які походять з історичного replay і ще не накопичили live recall або daily support. -Що вони **не** роблять самі по собі: +Чого вони **не** роблять самі по собі: - вони не редагують `MEMORY.md` - вони не запускають повні міграції doctor -- вони не готують grounded-кандидатів автоматично в live short-term promotion store, якщо ви явно не запустите staged CLI path спочатку +- вони не додають grounded candidates автоматично в live short-term promotion store, якщо ви спочатку явно не запустите staged CLI path -Якщо ви хочете, щоб grounded historical replay впливав на звичайний deep promotion lane, натомість використовуйте CLI-потік: +Якщо ви хочете, щоб grounded historical replay впливав на звичайну deep promotion lane, натомість використовуйте потік CLI: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -Це готує grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду. +Це додає grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду. ## Детальна поведінка та обґрунтування - Якщо це git checkout і doctor запускається інтерактивно, він пропонує оновитися (fetch/rebase/build) перед запуском doctor. + Якщо це git checkout і doctor працює інтерактивно, він пропонує оновити (fetch/rebase/build) перед запуском doctor. - Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх у поточну схему. + Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. - Це охоплює застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдера. + Це включає застарілі пласкі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдерів. Doctor також попереджає, коли `plugins.allow` не порожній, а політика інструментів використовує wildcard або записи інструментів, що належать Plugin. `tools.allow: ["*"]` відповідає лише інструментам - із Plugin, які фактично завантажуються; це не обходить ексклюзивний + із plugins, які фактично завантажуються; він не обходить ексклюзивний allowlist Plugin. - Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися й просять вас запустити `openclaw doctor`. + Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися та просять виконати `openclaw doctor`. Doctor: - Пояснить, які застарілі ключі знайдено. - Покаже застосовану міграцію. - - Перепише `~/.openclaw/openclaw.json` з оновленою схемою. + - Перезапише `~/.openclaw/openclaw.json` оновленою схемою. - Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. Міграції сховища завдань Cron обробляються через `openclaw doctor --fix`. + Gateway також автоматично запускає міграції doctor під час запуску, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації відновлюються без ручного втручання. Міграції сховища cron-завдань обробляє `openclaw doctor --fix`. Поточні міграції: @@ -196,7 +196,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `routing.queue` → `messages.queue` - - `routing.bindings` → верхньорівневий `bindings` + - `routing.bindings` → верхньорівневі `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` - застарілі `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` @@ -212,87 +212,87 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - Для каналів із іменованими `accounts`, але залишковими верхньорівневими значеннями каналу для одного облікового запису, перемістіть ці значення в межах облікового запису до підвищеного облікового запису, вибраного для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/стандартну ціль) + - Для каналів з іменованими `accounts`, але залишковими верхньорівневими значеннями каналу для одного облікового запису, перемістіть ці значення з областю дії облікового запису в підвищений обліковий запис, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - видаліть `agents.defaults.llm`; використовуйте `models.providers..timeoutSeconds` для тайм-аутів повільних провайдерів/моделей - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - видаліть `browser.relayBindHost` (застаріле налаштування реле розширення) - - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск Gateway також пропускає провайдерів, у яких `api` встановлено на майбутнє або невідоме значення enum, замість аварійного завершення в закритому режимі) + - видаліть `browser.relayBindHost` (застаріле налаштування ретрансляції розширення) + - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (під час запуску Gateway також пропускає провайдерів, у яких `api` задано майбутнім або невідомим значенням enum, замість аварійно завершуватися у закритому режимі) - Попередження doctor також містять настанови щодо стандартного облікового запису для каналів із кількома обліковими записами: + Попередження doctor також містять настанови щодо типового облікового запису для багатооблікових каналів: - Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. - - Якщо `channels..defaultAccount` задано як невідомий ID облікового запису, doctor попереджає про це й перелічує налаштовані ID облікових записів. + - Якщо `channels..defaultAccount` задано як невідомий ID облікового запису, doctor попереджає і перелічує налаштовані ID облікових записів. - + Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі до неправильного API або обнулити витрати. Doctor попереджає, щоб ви могли видалити перевизначення й відновити маршрутизацію API та витрати для кожної моделі. - - Якщо ваша конфігурація браузера досі вказує на видалений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості: + + Якщо ваша конфігурація браузера все ще вказує на видалений шлях розширення Chrome, doctor нормалізує її до поточної моделі локального для хоста підключення Chrome MCP: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` - `browser.relayBindHost` видаляється - Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: + Doctor також перевіряє локальний для хоста шлях Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: - - перевіряє, чи встановлено Google Chrome на тому самому хості для стандартних профілів автоматичного підключення - - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 + - перевіряє, чи Google Chrome встановлено на тому самому хості для типових профілів автоматичного підключення + - перевіряє виявлену версію Chrome і попереджає, коли вона нижча за Chrome 144 - нагадує ввімкнути віддалене налагодження на сторінці інспектування браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) - Doctor не може ввімкнути налаштування на боці Chrome замість вас. Chrome MCP на локальному хості все ще потребує: + Doctor не може ввімкнути налаштування на боці Chrome за вас. Локальний для хоста Chrome MCP все ще потребує: - - браузер на основі Chromium 144+ на хості Gateway/Node - - браузер, запущений локально - - віддалене налагодження, увімкнене в цьому браузері - - схвалення першого запиту згоди на підключення в браузері + - браузера на базі Chromium 144+ на хості gateway/node + - локально запущеного браузера + - увімкненого віддаленого налагодження в цьому браузері + - підтвердження першого запиту згоди на підключення в браузері - Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або профілю raw CDP. + Готовність тут стосується лише локальних передумов підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або raw CDP-профілю. Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP. - - Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку авторизації OpenAI, щоб переконатися, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить настанови з виправлення для конкретної платформи. На macOS із Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний. + + Коли налаштовано OAuth-профіль OpenAI Codex, doctor перевіряє кінцеву точку авторизації OpenAI, щоб переконатися, що локальний TLS-стек Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить настанови з виправлення для конкретної платформи. На macOS із Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний. - - Якщо ви раніше додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту поряд із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не викликають цього попередження. + + Якщо раніше ви додали застарілі транспортні налаштування OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування разом із Codex OAuth, щоб ви могли видалити або переписати застаріле транспортне перевизначення й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не спричиняють це попередження. - - Коли ввімкнено вбудований Plugin Codex, doctor також перевіряє, чи основні посилання на моделі `openai-codex/*` досі вирішуються через стандартний runner PI. Ця комбінація чинна, коли вам потрібна автентифікація Codex OAuth/підписки через PI, але її легко сплутати з нативним app-server harness Codex. Doctor попереджає й вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. + + Коли ввімкнено вбудований Codex Plugin, doctor також перевіряє, чи основні посилання на моделі `openai-codex/*` досі розв’язуються через типовий PI runner. Ця комбінація коректна, коли ви хочете автентифікацію Codex OAuth/передплати через PI, але її легко сплутати з нативним harness сервера застосунку Codex. Doctor попереджає і вказує на явну форму сервера застосунку: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. - Doctor не виправляє це автоматично, оскільки обидва маршрути чинні: + Doctor не виправляє це автоматично, бо обидва маршрути коректні: - - `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw." - - `openai/*` + `runtime: "codex"` означає "запустити вбудований хід через нативний Codex app-server." - - `/codex ...` означає "керувати нативною розмовою Codex або прив'язати її з чату." - - `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx." + - `openai-codex/*` + PI означає «використовувати автентифікацію Codex OAuth/передплати через звичайний runner OpenClaw». + - `openai/*` + `agentRuntime.id: "codex"` означає «виконати вбудований turn через нативний сервер застосунку Codex». + - `/codex ...` означає «керувати нативною розмовою Codex із чату або прив’язати її». + - `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx». - Якщо з'являється попередження, виберіть потрібний маршрут і вручну відредагуйте конфігурацію. Залиште попередження без змін, коли PI Codex OAuth є навмисним. + Якщо попередження з’являється, виберіть задуманий маршрут і відредагуйте конфігурацію вручну. Залиште попередження без змін, коли PI Codex OAuth є навмисним. - - Doctor може мігрувати старіші структури на диску до поточної структури: + + Doctor може мігрувати старіші дискові структури до поточної структури: - Сховище сеансів + транскрипти: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - Каталог агента: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - - із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (стандартний ID облікового запису: `default`) + - із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`) + - до `~/.openclaw/credentials/whatsapp//...` (типовий ID облікового запису: `default`) - Ці міграції виконуються за принципом найкращого зусилля та є ідемпотентними; doctor виводитиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапляли в шлях для кожного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера/карти провайдерів Talk тепер порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють повторні no-op зміни `doctor --fix`. + Ці міграції виконуються за принципом best-effort і є ідемпотентними; doctor виводитиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапили в шлях для відповідного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера talk/карти провайдерів тепер порівнює за структурною рівністю, тому diff лише через порядок ключів більше не спричиняє повторних no-op змін `doctor --fix`. - - Doctor сканує всі встановлені маніфести plugin на наявність застарілих верхньорівневих ключів можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх в об'єкт `contracts` і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже має такі самі значення, застарілий ключ видаляється без дублювання даних. + + Doctor сканує всі встановлені маніфести plugin на наявність застарілих верхньорівневих ключів можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх в об’єкт `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже має ті самі значення, застарілий ключ видаляється без дублювання даних. - - Doctor також перевіряє сховище завдань cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо перевизначено) на старі форми завдань, які планувальник усе ще приймає для сумісності. + + Doctor також перевіряє сховище cron-завдань (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які scheduler досі приймає для сумісності. Поточні очищення cron включають: @@ -300,201 +300,201 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `schedule.cron` → `schedule.expr` - верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload` - верхньорівневі поля доставки (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - - псевдоніми доставки payload `provider` → явний `delivery.channel` - - прості застарілі резервні webhook-завдання `notify: true` → явний `delivery.mode="webhook"` із `delivery.to=cron.webhook` + - псевдоніми доставки `provider` у payload → явний `delivery.channel` + - прості застарілі fallback-завдання webhook `notify: true` → явне `delivery.mode="webhook"` з `delivery.to=cron.webhook` - Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом доставки, відмінним від webhook, doctor попереджає й залишає це завдання для ручного перегляду. + Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий fallback notify з наявним режимом доставки не через webhook, doctor попереджає і залишає це завдання для ручного перегляду. - На Linux doctor також попереджає, коли crontab користувача досі викликає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`. Цей скрипт локального хоста не підтримується поточним OpenClaw і може записувати хибні повідомлення `Gateway inactive` до `~/.openclaw/logs/whatsapp-health.log`, коли cron не може досягти користувацької шини systemd. Видаліть застарілий запис crontab за допомогою `crontab -e`; використовуйте `openclaw channels status --probe`, `openclaw doctor` і `openclaw gateway status` для поточних перевірок справності. + На Linux doctor також попереджає, коли crontab користувача досі викликає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`. Цей локальний для хоста скрипт не підтримується поточним OpenClaw і може записувати хибні повідомлення `Gateway inactive` у `~/.openclaw/logs/whatsapp-health.log`, коли cron не може дістатися до шини користувача systemd. Видаліть застарілий запис crontab за допомогою `crontab -e`; використовуйте `openclaw channels status --probe`, `openclaw doctor` і `openclaw gateway status` для поточних перевірок справності. - Лікар сканує кожен каталог сеансів агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старіше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку та вказує повторно запустити з `--fix`. + Doctor сканує кожен каталог сеансу агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку та вказує повторно запустити з `--fix`. - - Лікар сканує JSONL-файли сеансів агента на дубльовану форму гілки, створену помилкою переписування транскрипту підказки 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw плюс активний сусідній хід із тією самою видимою підказкою користувача. У режимі `--fix` / `--repair` лікар створює резервну копію кожного ураженого файла поруч з оригіналом і переписує транскрипт на активну гілку, щоб історія Gateway і читачі пам’яті більше не бачили дубльовані ходи. + + Doctor сканує JSONL-файли сеансів агентів на дубльовану форму гілки, створену помилкою переписування транскрипта промпта 2026.4.24: покинутий хід користувача з внутрішнім контекстом виконання OpenClaw плюс активний сусідній елемент із тим самим видимим промптом користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного зачепленого файлу поруч з оригіналом і переписує транскрипт на активну гілку, щоб історія gateway і читачі пам’яті більше не бачили дубльованих ходів. - Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій деінде). + Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій деінде). - Лікар перевіряє: + Doctor перевіряє: - **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані. - **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку `chown`, коли виявлено невідповідність власника/групи). - - **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розв’язується всередині iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи з синхронізацією можуть спричиняти повільніше I/O та перегони блокувань/синхронізації. - - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розв’язується до джерела монтування `mmcblk*`, оскільки випадкове I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів та облікових даних. - - **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення збоїв `ENOENT`. - - **Невідповідність транскрипту**: попереджає, коли в недавніх записах сеансів бракує файлів транскрипту. - - **Основний сеанс "1-line JSONL"**: позначає випадки, коли основний транскрипт має лише один рядок (історія не накопичується). - - **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує деінде (історія може розділитися між інсталяціями). - - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, лікар нагадує запустити його на віддаленому хості (стан живе там). - - **Дозволи конфігураційного файла**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує посилити дозволи до `600`. + - **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розміщується під iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, тому що шляхи, підтримувані синхронізацією, можуть спричиняти повільніший I/O і перегони блокувань/синхронізації. + - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розміщується на джерелі монтування `mmcblk*`, тому що випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів та облікових даних. + - **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення аварій `ENOENT`. + - **Невідповідність транскрипта**: попереджає, коли нещодавні записи сеансів мають відсутні файли транскриптів. + - **Головний сеанс "1-line JSONL"**: позначає випадок, коли головний транскрипт має лише один рядок (історія не накопичується). + - **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділятися між інсталяціями). + - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (стан живе там). + - **Дозволи конфігураційного файлу**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує обмежити до `600`. - - Лікар перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли токени скоро закінчаться або вже закінчилися, і може оновити їх, коли це безпечно. Якщо OAuth/токен-профіль Anthropic застарів, він пропонує ключ API Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. + + Doctor перевіряє профілі OAuth у сховищі авторизації, попереджає, коли термін дії токенів скоро спливає або вже сплив, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/токена застарів, він пропонує ключ Anthropic API або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. - Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або провайдер каже увійти знову), лікар повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати. + Коли оновлення OAuth остаточно не вдається (наприклад `refresh_token_reused`, `invalid_grant` або провайдер просить увійти знову), doctor повідомляє, що потрібна повторна авторизація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати. - Лікар також повідомляє про профілі автентифікації, які тимчасово непридатні через: + Doctor також повідомляє про профілі авторизації, які тимчасово непридатні через: - - короткі періоди очікування (ліміти швидкості/тайм-аути/збої автентифікації) - - триваліші вимкнення (збої білінгу/кредитів) + - короткі періоди очікування (ліміти частоти/таймаути/збої авторизації) + - довші вимкнення (збої білінгу/кредитів) - - Якщо `hooks.gmail.model` задано, лікар перевіряє посилання на модель за каталогом і списком дозволених та попереджає, коли його неможливо розв’язати або воно заборонене. + + Якщо `hooks.gmail.model` задано, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли його не вдасться розв’язати або воно заборонене. - Коли пісочницю ввімкнено, лікар перевіряє Docker-образи та пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній. + Коли пісочницю ввімкнено, doctor перевіряє образи Docker і пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній. - - Лікар видаляє застарілий створений OpenClaw проміжний стан залежностей Plugin у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення та локальні для пакета залишки від попереднього коду виправлення залежностей вбудованих Plugin. + + Doctor видаляє застарілий згенерований OpenClaw проміжний стан залежностей Plugin у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу інсталяції та локальне сміття пакета з попереднього коду виправлення залежностей bundled-plugin. - Лікар також може повторно встановити налаштовані завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр plugin не може їх знайти. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; установлення plugin лишається явною роботою doctor/install/update. + Doctor також може перевстановити налаштовані завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр Plugin не може їх знайти. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; інсталяції Plugin залишаються явною роботою doctor/install/update. - Лікар виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw з використанням поточного порту gateway. Він також може сканувати додаткові сервіси, схожі на gateway, і друкувати підказки з очищення. Сервіси OpenClaw gateway, названі за профілем, вважаються повноцінними і не позначаються як "додаткові". + Doctor виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw з використанням поточного порту gateway. Він також може сканувати додаткові gateway-подібні сервіси та друкувати підказки з очищення. Сервіси OpenClaw gateway з іменами профілів вважаються повноцінними й не позначаються як "extra." - У Linux, якщо сервіс gateway рівня користувача відсутній, але сервіс OpenClaw gateway системного рівня існує, лікар не встановлює другий сервіс рівня користувача автоматично. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, а потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний супервізор керує життєвим циклом gateway. + На Linux, якщо сервіс gateway рівня користувача відсутній, але існує системний сервіс OpenClaw gateway, doctor не встановлює автоматично другий сервіс рівня користувача. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний супервізор керує життєвим циклом gateway. - Коли обліковий запис каналу Matrix має очікувану або придатну до дії міграцію застарілого стану, лікар (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує міграційні кроки з найкращим зусиллям: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, і запуск продовжується. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. + Коли обліковий запис каналу Matrix має очікувану або придатну до дії міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім запускає кроки міграції best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. - - Тепер лікар перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки стану. + + Doctor тепер перевіряє стан спарювання пристроїв як частину звичайної перевірки справності. Що він повідомляє: - - очікувані запити першого сполучення - - очікувані підвищення ролей для вже сполучених пристроїв - - очікувані підвищення scope для вже сполучених пристроїв - - виправлення невідповідності публічного ключа, коли ідентифікатор пристрою все ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом - - сполучені записи, у яких відсутній активний токен для затвердженої ролі - - сполучені токени, чиї scopes відхиляються за межі затвердженої базової лінії сполучення - - локально кешовані записи device-token для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope + - очікувані запити на перше спарювання + - очікувані підвищення ролі для вже спарених пристроїв + - очікувані підвищення scope для вже спарених пристроїв + - виправлення невідповідності публічного ключа, коли id пристрою все ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом + - спарені записи, яким бракує активного токена для затвердженої ролі + - спарені токени, чиї scopes відхиляються від затвердженої базової лінії спарювання + - локальні кешовані записи токенів пристроїв для поточної машини, що передують ротації токена на боці gateway або містять застарілі метадані scope - Лікар не затверджує запити на сполучення автоматично і не обертає токени пристроїв автоматично. Натомість він друкує точні наступні кроки: + Doctor не схвалює автоматично запити на спарювання й не ротує автоматично токени пристроїв. Натомість він друкує точні наступні кроки: - - перегляньте очікувані запити за допомогою `openclaw devices list` - - затвердьте точний запит за допомогою `openclaw devices approve ` - - оберніть свіжий токен за допомогою `openclaw devices rotate --device --role ` - - видаліть і повторно затвердьте застарілий запис за допомогою `openclaw devices remove ` + - перевірте очікувані запити за допомогою `openclaw devices list` + - схваліть точний запит за допомогою `openclaw devices approve ` + - згенеруйте свіжий токен ротацією за допомогою `openclaw devices rotate --device --role ` + - видаліть і повторно схваліть застарілий запис за допомогою `openclaw devices remove ` - Це закриває поширену прогалину "already paired but still getting pairing required": тепер лікар відрізняє перше сполучення від очікуваних підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою. + Це закриває поширену прогалину "already paired but still getting pairing required": doctor тепер відрізняє перше спарювання від очікуваних підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою. - Лікар видає попередження, коли провайдер відкритий для DM без списку дозволених або коли політику налаштовано небезпечно. + Doctor виводить попередження, коли провайдер відкритий для DM без allowlist або коли політику налаштовано небезпечним способом. - Якщо запущено як користувацький сервіс systemd, лікар гарантує, що lingering увімкнено, щоб gateway залишався активним після виходу з системи. + Якщо запущено як користувацький сервіс systemd, doctor переконується, що linger увімкнено, щоб gateway залишався активним після виходу з системи. - Лікар друкує підсумок стану робочого простору для агента за замовчуванням: + Doctor друкує підсумок стану робочого простору для стандартного агента: - - **Стан Skills**: рахує skills, які відповідають вимогам, мають відсутні вимоги та заблоковані списком дозволених. + - **Стан Skills**: рахує придатні, з відсутніми вимогами та заблоковані allowlist skills. - **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поруч із поточним робочим простором. - - **Стан Plugin**: рахує ввімкнені/вимкнені/помилкові plugins; перелічує ідентифікатори plugin для будь-яких помилок; повідомляє можливості bundle plugin. + - **Стан Plugin**: рахує ввімкнені/вимкнені/помилкові plugins; перелічує ID Plugin для будь-яких помилок; повідомляє можливості bundle plugin. - **Попередження сумісності Plugin**: позначає plugins, які мають проблеми сумісності з поточним runtime. - - **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, видані реєстром plugin. + - **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, виведені реєстром Plugin. - - Лікар перевіряє, чи bootstrap-файли робочого простору (наприклад, `AGENTS.md`, `CLAUDE.md` або інші вставлені контекстні файли) наближаються до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файла сирі та вставлені кількості символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість вставлених символів як частку загального бюджету. Коли файли обрізано або вони наближаються до ліміту, лікар друкує поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. + + Doctor перевіряє, чи файли bootstrap робочого простору (наприклад `AGENTS.md`, `CLAUDE.md` або інші вставлені контекстні файли) близькі до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу необроблену кількість символів проти вставленої, відсоток усічення, причину усічення (`max/file` або `max/total`) і загальну кількість вставлених символів як частку від загального бюджету. Коли файли усічено або вони близькі до ліміту, doctor друкує поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. - - Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє висячу конфігурацію в області каналу, яка посилалася на цей plugin: записи `channels.`, цілі heartbeat, що називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив’язатися до нього. + + Коли `openclaw doctor --fix` видаляє відсутній Plugin каналу, він також видаляє завислу конфігурацію в області каналу, яка посилалася на цей Plugin: записи `channels.`, цілі heartbeat, що називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив’язатися до нього. - Лікар перевіряє, чи встановлено автодоповнення табуляцією для поточної оболонки (zsh, bash, fish або PowerShell): + Doctor перевіряє, чи встановлено автодоповнення клавішею Tab для поточної оболонки (zsh, bash, fish або PowerShell): - - Якщо профіль оболонки використовує повільний динамічний шаблон автодоповнення (`source <(openclaw completion ...)`), лікар оновлює його до швидшого варіанта з кешованим файлом. - - Якщо автодоповнення налаштовано в профілі, але файл кешу відсутній, лікар автоматично повторно генерує кеш. - - Якщо автодоповнення взагалі не налаштовано, лікар пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`). + - Якщо профіль оболонки використовує повільний динамічний шаблон доповнення (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта кешованого файлу. + - Якщо доповнення налаштовано в профілі, але файл кешу відсутній, doctor автоматично регенерує кеш. + - Якщо доповнення взагалі не налаштовано, doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`). - Запустіть `openclaw completion --write-state`, щоб повторно згенерувати кеш вручну. + Запустіть `openclaw completion --write-state`, щоб вручну регенерувати кеш. - - Лікар перевіряє готовність автентифікації локального gateway токеном. + + Doctor перевіряє готовність авторизації локального gateway за токеном. - - Якщо режим токена потребує токен, а джерела токена немає, лікар пропонує згенерувати його. - - Якщо `gateway.auth.token` керується SecretRef, але недоступний, лікар попереджає і не перезаписує його відкритим текстом. - - `openclaw doctor --generate-gateway-token` примусово генерує лише тоді, коли не налаштовано SecretRef для токена. + - Якщо режим токена потребує токена, а джерела токена немає, doctor пропонує згенерувати його. + - Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом. + - `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef. - - Деякі потоки виправлення мають перевіряти налаштовані облікові дані без послаблення runtime-поведінки швидкого збою. + + Деякі потоки виправлення мають перевіряти налаштовані облікові дані, не послаблюючи поведінку швидкого збою runtime. - - `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації. - - Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, коли вони доступні. - - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, лікар повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або помилкового повідомлення про відсутній токен. + - `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації. + - Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані bot, коли вони доступні. + - Якщо токен bot Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або помилкового повідомлення, що токен відсутній. - - Лікар виконує перевірку стану і пропонує перезапустити gateway, коли він виглядає несправним. + + Doctor запускає перевірку справності та пропонує перезапустити gateway, коли він виглядає несправним. - - Лікар перевіряє, чи налаштований провайдер embedding для пошуку в пам’яті готовий для агента за замовчуванням. Поведінка залежить від налаштованого backend і провайдера: + + Doctor перевіряє, чи налаштований провайдер embedding для пошуку пам’яті готовий для стандартного агента. Поведінка залежить від налаштованого backend і провайдера: - - **Бекенд QMD**: перевіряє, чи доступний і чи може запускатися виконуваний файл `qmd`. Якщо ні, виводить інструкції з виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файлу. - - **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаної URL-адреси віддаленої/завантажуваної моделі. Якщо відсутній, пропонує перейти на віддаленого провайдера. - - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє наявність API-ключа в середовищі або сховищі автентифікації. Якщо ключ відсутній, виводить дієві підказки для виправлення. - - **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, потім пробує кожного віддаленого провайдера в порядку автоматичного вибору. + - **Бекенд QMD**: перевіряє, чи доступний і чи може запускатися двійковий файл `qmd`. Якщо ні, виводить інструкції з виправлення, зокрема npm-пакет і варіант ручного шляху до двійкового файла. + - **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаної віддаленої/завантажуваної URL-адреси моделі. Якщо її немає, пропонує перейти на віддаленого провайдера. + - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки для виправлення. + - **Автопровайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого провайдера в порядку автовибору. - Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-які розбіжності. Doctor не запускає новий ping вбудовувань на типовому шляху; використовуйте команду глибокого статусу пам’яті, коли потрібна жива перевірка провайдера. + Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-які розбіжності. Doctor не запускає нову перевірку embedding за стандартним шляхом; використовуйте команду глибокого статусу пам’яті, коли потрібна жива перевірка провайдера. - Використовуйте `openclaw memory status --deep`, щоб перевірити готовність вбудовувань під час виконання. + Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання. - - Якщо Gateway справний, doctor запускає перевірку статусу каналів і повідомляє попередження із запропонованими виправленнями. + + Якщо Gateway справний, doctor запускає перевірку стану каналів і повідомляє попередження із запропонованими виправленнями. - Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі типові значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, рекомендує оновлення й може переписати файл служби/завдання до поточних типових значень. + Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі стандартні значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, рекомендує оновлення і може переписати файл служби/завдання до поточних стандартних значень. Примітки: - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації супервізора. - - `openclaw doctor --yes` приймає типові запити на відновлення. + - `openclaw doctor --yes` приймає стандартні запити на відновлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації супервізора. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби Gateway. Він усе ще повідомляє про стан служби й виконує відновлення, не пов’язані зі службою, але пропускає install/start/restart/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній супервізор. - - У Linux doctor не переписує метадані команди/точки входу, доки відповідний systemd-модуль Gateway активний. Він також ігнорує неактивні додаткові модулі, схожі на Gateway і не застарілі, під час пошуку дубльованих служб, щоб супутні файли служб не створювали зайвий шум очищення. + - `openclaw doctor --repair --force` перезаписує власні конфігурації супервізора. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби Gateway. Він усе ще повідомляє про стан служби й запускає відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, бо цим життєвим циклом керує зовнішній супервізор. + - У Linux doctor не переписує метадані команди/точки входу, доки відповідний systemd-модуль Gateway активний. Він також ігнорує неактивні додаткові модулі, схожі на Gateway і не застарілі, під час пошуку дубльованих служб, щоб супровідні файли служб не створювали шум очищення. - Якщо автентифікація токеном вимагає токен і `gateway.auth.token` керується SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища служби супервізора. - - Doctor виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела виконання, а не з визначення супервізора. - - Doctor виявляє, коли команда служби досі фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт. - - Якщо автентифікація токеном вимагає токен, а налаштований SecretRef токена не розв’язано, doctor блокує шлях встановлення/відновлення з дієвими інструкціями. + - Doctor виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела runtime, а не з визначення супервізора. + - Doctor виявляє, коли команда служби все ще фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт. + - Якщо автентифікація токеном вимагає токен, а налаштований SecretRef токена не розв’язується, doctor блокує шлях встановлення/відновлення з практичними вказівками. - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде задано явно. - - Для користувацьких systemd-модулів Linux перевірки дрейфу токена doctor тепер враховують як джерела `Environment=`, так і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. - - Відновлення служби doctor відмовляються переписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файла OpenClaw, коли конфігурацію востаннє було записано новішою версією. Див. [усунення неполадок Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). + - Для користувацьких systemd-модулів Linux перевірки розбіжності токенів у doctor тепер враховують джерела `Environment=` і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. + - Відновлення служби doctor відмовляються переписувати, зупиняти або перезапускати службу Gateway зі старішого двійкового файла OpenClaw, якщо конфігурацію востаннє записала новіша версія. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`. - - Doctor перевіряє середовище виконання служби (PID, останній статус виходу) і попереджає, коли служба встановлена, але фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже працює, SSH-тунель). + + Doctor перевіряє runtime служби (PID, останній статус виходу) і попереджає, коли службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти портів на порту Gateway (стандартно `18789`) і повідомляє ймовірні причини (Gateway уже запущено, SSH-тунель). - - Doctor попереджає, коли служба Gateway працює на Bun або шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, оскільки служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує мігрувати на системне встановлення Node, коли воно доступне (Homebrew/apt/choco). + + Doctor попереджає, коли служба Gateway працює на Bun або на шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, бо служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, коли воно доступне (Homebrew/apt/choco). - Нововстановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні користувацькі каталоги bin, але припущені резервні каталоги менеджерів версій записуються в PATH служби лише тоді, коли ці каталоги існують на диску. Це узгоджує згенерований PATH супервізора з тим самим аудитом мінімального PATH, який doctor запускає пізніше. + Нововстановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але припущені резервні каталоги менеджерів версій записуються в PATH служби лише тоді, коли ці каталоги існують на диску. Це узгоджує згенерований PATH супервізора з тим самим аудитом мінімального PATH, який doctor запускає пізніше. - Doctor зберігає будь-які зміни конфігурації та ставить позначку в метаданих майстра, щоб зафіксувати запуск doctor. + Doctor зберігає всі зміни конфігурації та ставить мітку метаданих майстра, щоб зафіксувати запуск doctor. - - Doctor пропонує систему пам’яті робочого простору, коли її бракує, і виводить пораду щодо резервної копії, якщо робочий простір ще не перебуває під керуванням git. + + Doctor пропонує систему пам’яті робочої області, коли її немає, і виводить пораду щодо резервного копіювання, якщо робоча область ще не перебуває під git. - Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури робочого простору та резервного копіювання в git (рекомендовано приватний GitHub або GitLab). + Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника зі структури робочої області та резервного копіювання git (рекомендовано приватний GitHub або GitLab). ## Пов’язане -- [Runbook Gateway](/uk/gateway) -- [Усунення неполадок Gateway](/uk/gateway/troubleshooting) +- [Регламент Gateway](/uk/gateway) +- [Усунення несправностей Gateway](/uk/gateway/troubleshooting) diff --git a/docs/uk/help/faq-first-run.md b/docs/uk/help/faq-first-run.md index 97d9436cc..41ffcc043 100644 --- a/docs/uk/help/faq-first-run.md +++ b/docs/uk/help/faq-first-run.md @@ -1,54 +1,54 @@ --- read_when: - - Нове встановлення, зависання під час первинного налаштування або помилки першого запуску - - Вибір автентифікації та підписок провайдерів - - Не вдається отримати доступ до docs.openclaw.ai, не вдається відкрити панель керування, встановлення зависло + - Нове встановлення, зависання онбордингу або помилки першого запуску + - Вибір автентифікації та підписок провайдера + - Немає доступу до docs.openclaw.ai, не вдається відкрити панель керування, встановлення зависло sidebarTitle: First-run FAQ -summary: 'Поширені запитання: швидкий старт і налаштування першого запуску — встановлення, підключення, автентифікація, підписки, початкові збої' -title: 'Поширені запитання: початкове налаштування' +summary: 'Поширені запитання: швидкий старт і налаштування першого запуску — встановлення, онбординг, автентифікація, підписки, початкові збої' +title: 'Поширені запитання: налаштування під час першого запуску' x-i18n: - generated_at: "2026-04-28T11:15:32Z" + generated_at: "2026-05-02T02:37:15Z" model: gpt-5.5 provider: openai - source_hash: 959e5c8a94cce6369af84d3d1e252dbfb22acb5891ac1d8b64722c4c40679e65 + source_hash: 469fbd24fea69d91c5b0408dff9c7d7b2382f9c59430a1d5331cb5dcabdce295 source_path: help/faq-first-run.md workflow: 16 --- - Q&A для швидкого старту й першого запуску. Для повсякденних операцій, моделей, автентифікації, сесій + Швидкий старт і Q&A для першого запуску. Для щоденних операцій, моделей, автентифікації, сесій і усунення несправностей див. основний [FAQ](/uk/help/faq). ## Швидкий старт і налаштування першого запуску - Використовуйте локального AI-агента, який може **бачити вашу машину**. Це значно ефективніше, ніж питати - в Discord, бо більшість випадків "я застряг" є **проблемами локальної конфігурації або середовища**, + Використайте локального AI-агента, який може **бачити вашу машину**. Це значно ефективніше, ніж питати + в Discord, бо більшість випадків "я застряг" є **локальними проблемами конфігурації або середовища**, які віддалені помічники не можуть перевірити. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) Ці інструменти можуть читати репозиторій, запускати команди, переглядати журнали й допомагати виправляти - налаштування на рівні машини (PATH, сервіси, дозволи, файли автентифікації). Дайте їм **повний checkout вихідного коду** через - hackable (git) install: + налаштування на рівні машини (PATH, служби, дозволи, файли автентифікації). Надайте їм **повний checkout вихідного коду** через + встановлення hackable (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це встановлює OpenClaw **з git checkout**, тож агент може читати код і документацію та - міркувати про саме ту версію, яку ви запускаєте. Пізніше ви завжди можете повернутися до стабільної версії, + Це встановлює OpenClaw **з git checkout**, тож агент може читати код + документацію і + міркувати про точну версію, яку ви запускаєте. Пізніше завжди можна повернутися до stable, повторно запустивши інсталятор без `--install-method git`. - Порада: попросіть агента **спланувати й проконтролювати** виправлення (крок за кроком), а потім виконати лише - необхідні команди. Так зміни залишаються невеликими й простішими для аудиту. + Порада: попросіть агента **спланувати й супроводжувати** виправлення (крок за кроком), а потім виконати лише + необхідні команди. Так зміни лишаються невеликими й простішими для аудиту. - Якщо ви знайдете справжню помилку або виправлення, будь ласка, створіть GitHub issue або надішліть PR: + Якщо ви виявили справжню помилку або виправлення, будь ласка, створіть GitHub issue або надішліть PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - Почніть із цих команд (діліться виводом, коли просите допомоги): + Почніть із цих команд (діліться виводом, коли просите про допомогу): ```bash openclaw status @@ -58,34 +58,34 @@ x-i18n: Що вони роблять: - - `openclaw status`: швидкий знімок стану Gateway/агента + базова конфігурація. + - `openclaw status`: короткий знімок стану gateway/агента + базова конфігурація. - `openclaw models status`: перевіряє автентифікацію провайдера + доступність моделей. - - `openclaw doctor`: перевіряє й виправляє поширені проблеми конфігурації/стану. + - `openclaw doctor`: перевіряє і виправляє типові проблеми конфігурації/стану. - Інші корисні CLI-перевірки: `openclaw status --all`, `openclaw logs --follow`, + Інші корисні перевірки CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламано](#first-60-seconds-if-something-is-broken). - Документація встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). + Документація зі встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). - Поширені причини пропуску Heartbeat: + Типові причини пропуску Heartbeat: - `quiet-hours`: поза налаштованим вікном активних годин - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожній/тільки заголовковий каркас - - `no-tasks-due`: режим завдань `HEARTBEAT.md` активний, але жоден з інтервалів завдань ще не настав - - `alerts-disabled`: уся видимість heartbeat вимкнена (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) + - `no-tasks-due`: режим завдань `HEARTBEAT.md` активний, але інтервали жодного завдання ще не настали + - `alerts-disabled`: усю видимість Heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) - У режимі завдань часові мітки виконання просуваються лише після завершення справжнього запуску Heartbeat. - Пропущені запуски не позначають завдання як завершені. + У режимі завдань часові позначки настання просуваються лише після завершення + справжнього запуску Heartbeat. Пропущені запуски не позначають завдання як виконані. Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація та завдання](/uk/automation). - + Репозиторій рекомендує запуск із вихідного коду та використання onboarding: ```bash @@ -93,9 +93,9 @@ x-i18n: openclaw onboard --install-daemon ``` - Майстер також може автоматично зібрати UI-ресурси. Після onboarding ви зазвичай запускаєте Gateway на порту **18789**. + Майстер також може автоматично зібрати ресурси UI. Після onboarding ви зазвичай запускаєте Gateway на порту **18789**. - З вихідного коду (для контриб'юторів/розробників): + З вихідного коду (контриб'ютори/розробка): ```bash git clone https://github.com/openclaw/openclaw.git @@ -106,90 +106,90 @@ x-i18n: openclaw onboard ``` - Якщо глобального встановлення ще немає, запустіть це через `pnpm openclaw onboard`. + Якщо у вас ще немає глобального встановлення, запустіть це через `pnpm openclaw onboard`. - - Майстер відкриває ваш браузер із чистою (без токена) URL-адресою dashboard одразу після onboarding, а також друкує посилання в підсумку. Тримайте цю вкладку відкритою; якщо вона не запустилася, скопіюйте/вставте надруковану URL-адресу на тій самій машині. + + Майстер відкриває ваш браузер із чистою (нетокенізованою) URL-адресою панелі керування одразу після onboarding, а також друкує посилання в підсумку. Тримайте цю вкладку відкритою; якщо вона не запустилася, скопіюйте/вставте надруковану URL-адресу на тій самій машині. - + **Localhost (та сама машина):** - Відкрийте `http://127.0.0.1:18789/`. - - Якщо запитується автентифікація shared-secret, вставте налаштований токен або пароль у налаштування Control UI. + - Якщо запитується автентифікація через shared-secret, вставте налаштований токен або пароль у налаштування Control UI. - Джерело токена: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`). - Джерело пароля: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - Якщо shared secret ще не налаштовано, згенеруйте токен за допомогою `openclaw doctor --generate-gateway-token`. **Не на localhost:** - - **Tailscale Serve** (рекомендовано): залиште bind loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, identity headers задовольняють автентифікацію Control UI/WebSocket (без вставленого shared secret, передбачається довірений хост gateway); HTTP API все ще потребують автентифікації shared-secret, якщо ви навмисно не використовуєте private-ingress `none` або HTTP-автентифікацію trusted-proxy. - Невдалі одночасні спроби автентифікації Serve від того самого клієнта серіалізуються перед тим, як обмежувач failed-auth їх записує, тож друга невдала повторна спроба вже може показати `retry later`. - - **Tailnet bind**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, потім вставте відповідний shared secret у налаштування dashboard. - - **Identity-aware reverse proxy**: тримайте Gateway за trusted proxy, налаштуйте `gateway.auth.mode: "trusted-proxy"`, потім відкрийте URL проксі. Same-host loopback proxies потребують явного `gateway.auth.trustedProxy.allowLoopback = true`. - - **SSH-тунель**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, потім відкрийте `http://127.0.0.1:18789/`. Автентифікація shared-secret усе ще застосовується через тунель; вставте налаштований токен або пароль, якщо буде запит. + - **Tailscale Serve** (рекомендовано): лишайте прив'язку до loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентичності задовольняють автентифікацію Control UI/WebSocket (без вставленого shared secret, передбачається довірений хост Gateway); HTTP API все одно потребують автентифікації через shared-secret, якщо ви свідомо не використовуєте private-ingress `none` або HTTP-автентифікацію trusted-proxy. + Невдалі паралельні спроби автентифікації Serve від одного клієнта серіалізуються до того, як лімітатор failed-auth їх записує, тому друга невдала повторна спроба вже може показати `retry later`. + - **Прив'язка Tailnet**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, а потім вставте відповідний shared secret у налаштуваннях панелі керування. + - **Identity-aware reverse proxy**: тримайте Gateway за довіреним проксі, налаштуйте `gateway.auth.mode: "trusted-proxy"`, потім відкрийте URL проксі. Проксі same-host loopback потребують явного `gateway.auth.trustedProxy.allowLoopback = true`. + - **SSH-тунель**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, потім відкрийте `http://127.0.0.1:18789/`. Автентифікація через shared-secret усе одно застосовується через тунель; вставте налаштований токен або пароль, якщо буде запит. - Див. [Dashboard](/uk/web/dashboard) і [Вебповерхні](/uk/web) щодо режимів bind та деталей автентифікації. + Див. [Панель керування](/uk/web/dashboard) і [Вебповерхні](/uk/web) щодо режимів прив'язки й деталей автентифікації. - - Вони керують різними рівнями: + + Вони керують різними шарами: - - `approvals.exec`: пересилає запити approval до chat destinations - - `channels..execApprovals`: змушує цей канал діяти як native approval client для exec approvals + - `approvals.exec`: пересилає запити підтвердження до чат-призначень + - `channels..execApprovals`: змушує цей канал діяти як нативний клієнт підтвердження для exec-підтверджень - Host exec policy усе ще є справжнім шлюзом approval. Chat config лише керує тим, де - з'являються запити approval і як люди можуть на них відповідати. + Політика host exec усе одно є справжнім шлюзом підтвердження. Конфігурація чату лише керує тим, де + з'являються запити підтвердження і як люди можуть на них відповідати. - У більшості налаштувань вам **не** потрібні обидві: + У більшості налаштувань вам **не** потрібні обидва: - - Якщо chat уже підтримує команди й відповіді, same-chat `/approve` працює через спільний шлях. - - Якщо підтримуваний native channel може безпечно визначити approvers, OpenClaw тепер автоматично вмикає DM-first native approvals, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. - - Коли доступні native approval cards/buttons, цей native UI є основним шляхом; агент має включати ручну команду `/approve` лише якщо результат інструмента каже, що chat approvals недоступні або ручний approval є єдиним шляхом. - - Використовуйте `approvals.exec` лише коли запити також потрібно пересилати в інші чати або явні ops rooms. - - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише коли ви явно хочете, щоб запити approval публікувалися назад у вихідну кімнату/тему. - - Plugin approvals знову окремі: вони за замовчуванням використовують same-chat `/approve`, необов'язкове пересилання `approvals.plugin`, і лише деякі native channels додатково зберігають plugin-approval-native handling. + - Якщо чат уже підтримує команди й відповіді, same-chat `/approve` працює через спільний шлях. + - Якщо підтримуваний нативний канал може безпечно визначати approvers, OpenClaw тепер автоматично вмикає DM-first нативні підтвердження, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. + - Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve` лише якщо результат інструмента каже, що чат-підтвердження недоступні або ручне підтвердження є єдиним шляхом. + - Використовуйте `approvals.exec` лише коли запити також потрібно пересилати в інші чати або явні ops-кімнати. + - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише коли ви явно хочете, щоб запити підтвердження публікувалися назад у початкову кімнату/тему. + - Plugin-підтвердження знову окремі: вони використовують same-chat `/approve` за замовчуванням, необов'язкове пересилання `approvals.plugin`, і лише деякі нативні канали зберігають plugin-approval-native обробку поверх цього. - Коротко: forwarding призначений для маршрутизації, native client config — для багатшого channel-specific UX. + Коротко: пересилання потрібне для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. Див. [Exec Approvals](/uk/tools/exec-approvals). - - Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендовано** для Gateway. + + Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендований** для Gateway. - Так. Gateway легкий - документація вказує **512MB-1GB RAM**, **1 core** і приблизно **500MB** + Так. Gateway легковаговий - документація вказує **512MB-1GB RAM**, **1 ядро** і приблизно **500MB** диска як достатні для особистого використання, а також зазначає, що **Raspberry Pi 4 може його запускати**. - Якщо вам потрібен додатковий запас (журнали, медіа, інші сервіси), **рекомендовано 2GB**, але це + Якщо потрібен додатковий запас (журнали, медіа, інші служби), **рекомендовано 2GB**, але це не жорсткий мінімум. - Порада: невеликий Pi/VPS може хостити Gateway, а ви можете спарити **nodes** на ноутбуці/телефоні для - локального екрана/камери/canvas або виконання команд. Див. [Nodes](/uk/nodes). + Порада: невеликий Pi/VPS може розміщувати Gateway, а ви можете під'єднати **вузли** на ноутбуці/телефоні для + локального екрана/камери/canvas або виконання команд. Див. [Вузли](/uk/nodes). - Коротко: це працює, але очікуйте шорсткостей. + Коротко: це працює, але очікуйте шорсткі місця. - Використовуйте **64-bit** OS і тримайте Node >= 22. - Віддавайте перевагу **hackable (git) install**, щоб бачити журнали й швидко оновлюватися. - - Почніть без channels/skills, потім додавайте їх по одному. - - Якщо натрапите на дивні проблеми з binary, зазвичай це проблема **ARM compatibility**. + - Почніть без каналів/Skills, потім додавайте їх по одному. + - Якщо натрапите на дивні проблеми з бінарними файлами, зазвичай це проблема **ARM-сумісності**. Документація: [Linux](/uk/platforms/linux), [Встановлення](/uk/install). - - Цей екран залежить від того, чи Gateway доступний і автентифікований. TUI також надсилає - "Wake up, my friend!" автоматично під час першого hatch. Якщо ви бачите цей рядок **без відповіді** - й tokens залишаються на 0, агент ніколи не запускався. + + Цей екран залежить від того, чи Gateway доступний і автентифікований. TUI також автоматично надсилає + "Wake up, my friend!" під час першого hatch. Якщо ви бачите цей рядок **без відповіді** + і токени лишаються на 0, агент ніколи не запускався. 1. Перезапустіть Gateway: @@ -212,74 +212,74 @@ x-i18n: ``` Якщо Gateway віддалений, переконайтеся, що тунель/з'єднання Tailscale активне і що UI - спрямований на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). + вказує на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). - Так. Скопіюйте **каталог стану** й **робочу область**, потім один раз запустіть Doctor. Це - збереже вашого бота "точно таким самим" (пам'ять, історію сесій, автентифікацію та стан каналу), - якщо ви скопіюєте **обидва** розташування: + Так. Скопіюйте **каталог стану** і **робочий простір**, потім один раз запустіть Doctor. Це + збереже вашого бота "точно таким самим" (memory, історія сесій, автентифікація і стан каналів), + якщо скопіювати **обидві** локації: - 1. Установіть OpenClaw на новій машині. + 1. Встановіть OpenClaw на новій машині. 2. Скопіюйте `$OPENCLAW_STATE_DIR` (за замовчуванням: `~/.openclaw`) зі старої машини. - 3. Скопіюйте свою робочу область (за замовчуванням: `~/.openclaw/workspace`). - 4. Запустіть `openclaw doctor` і перезапустіть сервіс Gateway. + 3. Скопіюйте свій робочий простір (за замовчуванням: `~/.openclaw/workspace`). + 4. Запустіть `openclaw doctor` і перезапустіть службу Gateway. - Це зберігає конфігурацію, профілі автентифікації, облікові дані WhatsApp, сесії та пам'ять. Якщо ви в - remote mode, пам'ятайте, що gateway host володіє session store і workspace. + Це зберігає конфігурацію, профілі автентифікації, облікові дані WhatsApp, сесії та memory. Якщо ви в + віддаленому режимі, пам'ятайте, що хост gateway володіє сховищем сесій і робочим простором. - **Важливо:** якщо ви лише commit/push свою робочу область на GitHub, ви створюєте резервну копію - **memory + bootstrap files**, але **не** історії сесій або автентифікації. Вони живуть - у `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). + **Важливо:** якщо ви лише commit/push свій робочий простір у GitHub, ви створюєте резервну копію + **memory + bootstrap-файлів**, але **не** історії сесій або автентифікації. Вони живуть + у `~/.openclaw/` (наприклад `~/.openclaw/agents//sessions/`). - Дотичне: [Міграція](/uk/install/migrating), [Де речі зберігаються на диску](#where-things-live-on-disk), - [Робоча область агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), - [Remote mode](/uk/gateway/remote). + Пов'язане: [Міграція](/uk/install/migrating), [Де речі живуть на диску](#where-things-live-on-disk), + [Робочий простір агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), + [Віддалений режим](/uk/gateway/remote). - Перевірте changelog на GitHub: + Перевірте GitHub changelog: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Найновіші записи розташовані вгорі. Якщо верхній розділ позначено **Unreleased**, наступний датований - розділ є останньою випущеною версією. Записи згруповані за **Highlights**, **Changes** і - **Fixes** (плюс розділи документації/іншого, коли потрібно). + Найновіші записи зверху. Якщо верхній розділ позначено **Unreleased**, наступний датований + розділ є останньою випущеною версією. Записи згруповано за **Highlights**, **Changes** і + **Fixes** (плюс розділи docs/other, коли потрібно). - - Деякі з'єднання Comcast/Xfinity неправильно блокують `docs.openclaw.ai` через Xfinity - Advanced Security. Вимкніть це або додайте `docs.openclaw.ai` до allowlist, потім повторіть спробу. + + Деякі підключення Comcast/Xfinity некоректно блокують `docs.openclaw.ai` через Xfinity + Advanced Security. Вимкніть це або додайте `docs.openclaw.ai` до allowlist, потім спробуйте знову. Будь ласка, допоможіть нам розблокувати це, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - Якщо ви все ще не можете відкрити сайт, документація дзеркалиться на GitHub: + Якщо ви все ще не можете дістатися сайту, документація дзеркалиться на GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - - **Стабільна версія** і **бета-версія** — це **npm dist-tags**, а не окремі гілки коду: + + **Стабільна** і **бета** — це **npm dist-tags**, а не окремі гілки коду: - - `latest` = стабільна версія + - `latest` = стабільна - `beta` = рання збірка для тестування - Зазвичай стабільний реліз спершу потрапляє в **бета-версію**, а потім окремий - крок просування переміщує ту саму версію до `latest`. Супровідники також можуть - публікувати одразу в `latest`, коли це потрібно. Саме тому бета-версія і стабільна версія можуть + Зазвичай стабільний реліз спочатку потрапляє в **beta**, а потім явний + крок просування переносить ту саму версію в `latest`. Супровідники також можуть + публікувати напряму в `latest`, коли це потрібно. Саме тому бета й стабільна версія можуть вказувати на **ту саму версію** після просування. - Перегляньте, що змінилося: + Подивіться, що змінилося: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Однорядкові команди встановлення та різницю між бета-версією і dev дивіться в акордеоні нижче. + Однорядкові команди встановлення та різницю між бета й dev дивіться в акордеоні нижче. - **Бета-версія** — це npm dist-tag `beta` (після просування може збігатися з `latest`). - **Dev** — це рухома вершина `main` (git); після публікації вона використовує npm dist-tag `dev`. + **Бета** — це npm dist-tag `beta` (може збігатися з `latest` після просування). + **Dev** — це рухома вершина `main` (git); під час публікації вона використовує npm dist-tag `dev`. Однорядкові команди (macOS/Linux): @@ -291,7 +291,7 @@ x-i18n: curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Інсталятор для Windows (PowerShell): + Інсталятор Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) Докладніше: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer). @@ -309,15 +309,15 @@ x-i18n: Це перемикає на гілку `main` і оновлює з вихідного коду. - 2. **Встановлення з можливістю редагування (із сайту інсталятора):** + 2. **Встановлення з можливістю змін (із сайту інсталятора):** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це дає вам локальний репозиторій, який можна редагувати, а потім оновлювати через git. + Це дає локальний репозиторій, який можна редагувати, а потім оновлювати через git. - Якщо ви віддаєте перевагу чистому клонуванню вручну, використовуйте: + Якщо віддаєте перевагу чистому ручному клонуванню, використайте: ```bash git clone https://github.com/openclaw/openclaw.git @@ -331,31 +331,31 @@ x-i18n: - + Орієнтовно: - **Встановлення:** 2-5 хвилин - - **Onboarding:** 5-15 хвилин залежно від кількості каналів/моделей, які ви налаштовуєте + - **Онбординг:** 5-15 хвилин залежно від кількості каналів/моделей, які ви налаштовуєте - Якщо процес зависає, скористайтеся [Інсталятор завис](#quick-start-and-first-run-setup) + Якщо процес зависає, скористайтеся [Інсталятор застряг](#quick-start-and-first-run-setup) і швидким циклом налагодження в [Я застряг](#quick-start-and-first-run-setup). - + Повторно запустіть інсталятор із **докладним виводом**: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - Встановлення бета-версії з докладним виводом: + Встановлення бета з докладним виводом: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - Для встановлення з можливістю редагування (git): + Для встановлення з можливістю змін (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose @@ -370,31 +370,31 @@ x-i18n: Set-PSDebug -Trace 0 ``` - Більше параметрів: [Прапорці інсталятора](/uk/install/installer). + Більше варіантів: [Прапорці інсталятора](/uk/install/installer). - + Дві поширені проблеми Windows: - **1) помилка npm spawn git / git не знайдено** + **1) Помилка npm spawn git / git не знайдено** - Установіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. - - Закрийте й знову відкрийте PowerShell, потім повторно запустіть інсталятор. + - Закрийте й знову відкрийте PowerShell, а потім повторно запустіть інсталятор. - **2) openclaw не розпізнано після встановлення** + **2) openclaw не розпізнається після встановлення** - - Глобальна папка npm bin не додана до PATH. + - Ваша глобальна папка bin для npm не додана до PATH. - Перевірте шлях: ```powershell npm config get prefix ``` - - Додайте цей каталог до свого користувацького PATH (у Windows суфікс `\bin` не потрібен; у більшості систем це `%AppData%\npm`). - - Закрийте й знову відкрийте PowerShell після оновлення PATH. + - Додайте цей каталог до PATH користувача (у Windows суфікс `\bin` не потрібен; у більшості систем це `%AppData%\npm`). + - Після оновлення PATH закрийте й знову відкрийте PowerShell. - Якщо вам потрібне найзручніше налаштування Windows, використовуйте **WSL2** замість нативної Windows. + Якщо хочете найзручніше налаштування Windows, використовуйте **WSL2** замість нативного Windows. Документація: [Windows](/uk/platforms/windows). @@ -404,8 +404,8 @@ x-i18n: Симптоми: - - вивід `system.run`/`exec` відображає китайський текст як mojibake - - та сама команда виглядає нормально в іншому профілі термінала + - Вивід `system.run`/`exec` показує китайський текст як mojibake + - Та сама команда виглядає нормально в іншому профілі термінала Швидкий обхідний шлях у PowerShell: @@ -422,14 +422,14 @@ x-i18n: openclaw gateway restart ``` - Якщо ви все ще відтворюєте це в найновішому OpenClaw, відстежуйте/повідомте про це тут: + Якщо це все ще відтворюється в найновішому OpenClaw, відстежуйте/повідомте про це тут: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - Використайте **встановлення з можливістю редагування (git)**, щоб мати повний вихідний код і документацію локально, а потім запитайте + Використайте **встановлення з можливістю змін (git)**, щоб мати повний вихідний код і документацію локально, а потім запитайте свого бота (або Claude/Codex) _з цієї папки_, щоб він міг прочитати репозиторій і відповісти точно. ```bash @@ -441,23 +441,23 @@ x-i18n: - Коротка відповідь: дотримуйтесь посібника для Linux, а потім запустіть onboarding. + Коротка відповідь: дотримуйтесь посібника для Linux, а потім запустіть онбординг. - - Швидкий шлях для Linux + встановлення служби: [Linux](/uk/platforms/linux). + - Швидкий шлях для Linux + встановлення сервісу: [Linux](/uk/platforms/linux). - Повний покроковий посібник: [Початок роботи](/uk/start/getting-started). - Інсталятор + оновлення: [Встановлення й оновлення](/uk/install/updating). - Підійде будь-який Linux VPS. Установіть на сервері, а потім використовуйте SSH/Tailscale, щоб дістатися до Gateway. + Підійде будь-який Linux VPS. Установіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. Посібники: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). - Віддалений доступ: [Gateway віддалено](/uk/gateway/remote). + Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). - + Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Виберіть один і дотримуйтесь посібника: - [VPS-хостинг](/uk/vps) (усі провайдери в одному місці) @@ -466,22 +466,22 @@ x-i18n: - [exe.dev](/uk/install/exe-dev) Як це працює в хмарі: **Gateway працює на сервері**, а ви отримуєте до нього доступ - зі свого ноутбука/телефона через Control UI (або Tailscale/SSH). Ваш стан + робочий простір - зберігаються на сервері, тому вважайте хост джерелом істини й створюйте його резервні копії. + із ноутбука/телефона через Control UI (або Tailscale/SSH). Ваш стан + робочий простір + зберігаються на сервері, тож вважайте хост джерелом істини й створюйте його резервні копії. - Ви можете поєднати **вузли** (Mac/iOS/Android/headless) із цим хмарним Gateway, щоб отримувати доступ - до локального екрана/камери/canvas або запускати команди на своєму ноутбуці, залишаючи + Ви можете прив’язати **вузли** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримувати доступ + до локального екрана/камери/canvas або запускати команди на ноутбуці, залишаючи Gateway у хмарі. - Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Gateway віддалено](/uk/gateway/remote). + Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). Вузли: [Вузли](/uk/nodes), [CLI вузлів](/uk/cli/nodes). - Коротка відповідь: **можливо, але не рекомендовано**. Потік оновлення може перезапустити - Gateway (що обірве активну сесію), може потребувати чистого git checkout і - може запитувати підтвердження. Безпечніше: запускати оновлення з оболонки як оператор. + Коротка відповідь: **можливо, але не рекомендовано**. Процес оновлення може перезапустити + Gateway (що перерве активний сеанс), може потребувати чистого git checkout і + може запитати підтвердження. Безпечніше: запускати оновлення з оболонки як оператор. Використовуйте CLI: @@ -493,7 +493,7 @@ x-i18n: openclaw update --no-restart ``` - Якщо вам потрібно автоматизувати з агента: + Якщо потрібно автоматизувати з агента: ```bash openclaw update --yes --no-restart @@ -504,35 +504,35 @@ x-i18n: - - `openclaw onboard` — це рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: + + `openclaw onboard` — рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: - - **Налаштування моделі/автентифікації** (OAuth провайдера, API-ключі, Anthropic setup-token, а також параметри локальних моделей, як-от LM Studio) + - **Налаштування моделі/автентифікації** (OAuth провайдера, API-ключі, setup-token Anthropic, а також локальні варіанти моделей, як-от LM Studio) - Розташування **робочого простору** + початкові файли - **Налаштування Gateway** (bind/port/auth/tailscale) - **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також вбудовані Plugin каналів, як-от QQ Bot) - - **Встановлення демона** (LaunchAgent на macOS; користувацький systemd unit у Linux/WSL2) - - **Перевірки стану** і вибір **skills** + - **Встановлення демона** (LaunchAgent на macOS; користувацький systemd unit на Linux/WSL2) + - **Перевірки стану** і вибір **Skills** - Він також попереджає, якщо налаштована модель невідома або в неї бракує автентифікації. + Він також попереджає, якщо налаштована модель невідома або їй бракує автентифікації. Ні. Ви можете запускати OpenClaw з **API-ключами** (Anthropic/OpenAI/інші) або з - **моделями лише локально**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude - Pro/Max або OpenAI Codex) — це необов'язкові способи автентифікації в цих провайдерів. + **суто локальними моделями**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude + Pro/Max або OpenAI Codex) — необов’язкові способи автентифікації цих провайдерів. Для Anthropic в OpenClaw практичний поділ такий: - - **API-ключ Anthropic**: звичайний білінг Anthropic API + - **API-ключ Anthropic**: звичайна оплата Anthropic API - **Claude CLI / автентифікація підписки Claude в OpenClaw**: співробітники Anthropic - повідомили нам, що це використання знову дозволене, і OpenClaw розглядає використання `claude -p` - як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову + повідомили нам, що це використання знову дозволене, і OpenClaw вважає використання `claude -p` + санкціонованим для цієї інтеграції, доки Anthropic не опублікує нову політику - Для довготривалих хостів gateway API-ключі Anthropic усе ще є більш - передбачуваним налаштуванням. OpenAI Codex OAuth явно підтримується для зовнішніх + Для довготривалих хостів gateway API-ключі Anthropic усе ще є + передбачуванішим налаштуванням. OAuth OpenAI Codex явно підтримується для зовнішніх інструментів, як-от OpenClaw. OpenClaw також підтримує інші розміщені варіанти в стилі підписки, зокрема @@ -550,24 +550,25 @@ x-i18n: Так. Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому - OpenClaw розглядає автентифікацію підписки Claude і використання `claude -p` як санкціоновані - для цієї інтеграції, якщо Anthropic не опублікує нову політику. Якщо вам потрібне - найбільш передбачуване серверне налаштування, натомість використовуйте API-ключ Anthropic. + OpenClaw вважає автентифікацію підписки Claude і використання `claude -p` санкціонованими + для цієї інтеграції, доки Anthropic не опублікує нову політику. Якщо ви хочете + найпередбачуваніше серверне налаштування, натомість використовуйте API-ключ Anthropic. Так. - Співробітники Anthropic повідомили нам, що це використання знову дозволене, тому OpenClaw розглядає - повторне використання Claude CLI і використання `claude -p` як санкціоновані для цієї інтеграції, - якщо Anthropic не опублікує нову політику. + Співробітники Anthropic повідомили нам, що це використання знову дозволене, тому OpenClaw вважає + повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, + доки Anthropic не опублікує нову політику. Anthropic setup-token усе ще доступний як підтримуваний шлях токена OpenClaw, але OpenClaw тепер віддає перевагу повторному використанню Claude CLI і `claude -p`, коли вони доступні. - Для продакшну або багатокористувацьких навантажень автентифікація API-ключем Anthropic усе ще є + Для продакшн або багатокористувацьких навантажень автентифікація API-ключем Anthropic усе ще є безпечнішим і передбачуванішим вибором. Якщо вам потрібні інші розміщені варіанти в стилі підписки в OpenClaw, дивіться [OpenAI](/uk/providers/openai), [Qwen / Model - Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [Моделі GLM](/uk/providers/glm). + Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [GLM + Models](/uk/providers/glm). @@ -577,58 +578,60 @@ x-i18n: - Це означає, що вашу **квоту/ліміт частоти Anthropic** вичерпано для поточного вікна. Якщо ви - використовуєте **Claude CLI**, дочекайтеся скидання вікна або оновіть свій план. Якщо ви + Це означає, що ваша **квота/ліміт швидкості Anthropic** вичерпані для поточного вікна. Якщо ви + використовуєте **Claude CLI**, зачекайте скидання вікна або оновіть свій план. Якщо ви використовуєте **API-ключ Anthropic**, перевірте Anthropic Console - щодо використання/білінгу та за потреби підніміть ліміти. + щодо використання/оплати й підвищте ліміти за потреби. Якщо повідомлення саме таке: `Extra usage is required for long context requests`, запит намагається використати бета-версію контексту 1M від Anthropic (`context1m: true`). Це працює лише тоді, коли ваші - облікові дані придатні для білінгу довгого контексту (білінг API-ключа або + облікові дані придатні для оплати довгого контексту (оплата API-ключем або шлях входу Claude в OpenClaw з увімкненим Extra Usage). - Порада: задайте **резервну модель**, щоб OpenClaw міг продовжувати відповідати, поки провайдер обмежений лімітом запитів. + Порада: налаштуйте **резервну модель**, щоб OpenClaw міг продовжувати відповідати, коли провайдер має обмеження частоти. Див. [Моделі](/uk/cli/models), [OAuth](/uk/concepts/oauth) і [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Так. OpenClaw має вбудованого провайдера **Amazon Bedrock (Converse)**. За наявності маркерів середовища AWS OpenClaw може автоматично виявити потоковий/текстовий каталог Bedrock і об’єднати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-сумісний проксі перед Bedrock також залишається припустимим варіантом. + Так. OpenClaw має вбудованого провайдера **Amazon Bedrock (Converse)**. За наявності маркерів середовища AWS OpenClaw може автоматично виявляти потоковий/текстовий каталог Bedrock і об’єднувати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо вам зручніший керований потік ключів, OpenAI-сумісний проксі перед Bedrock також залишається коректним варіантом. - OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Використовуйте - `openai-codex/gpt-5.5` для Codex OAuth через типовий раннер PI. Використовуйте - `openai/gpt-5.5` для прямого доступу за API-ключем OpenAI. GPT-5.5 також може використовувати - підписку/OAuth через `openai-codex/gpt-5.5` або нативні запуски Codex app-server - з `openai/gpt-5.5` і `agentRuntime.id: "codex"`. - Див. [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). + OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід ChatGPT). Використовуйте + `openai/gpt-5.5` з `agentRuntime.id: "codex"` для типового налаштування: + автентифікація підписки ChatGPT/Codex плюс нативне виконання на сервері застосунку Codex. Використовуйте + `openai-codex/gpt-5.5` лише тоді, коли потрібен Codex OAuth через стандартний + раннер PI. Використовуйте `openai/gpt-5.5` без перевизначення середовища виконання Codex для + прямого доступу з API-ключем OpenAI. + Див. [Провайдери моделей](/uk/concepts/model-providers) і [Початкове налаштування (CLI)](/uk/start/wizard). `openai-codex` — це ідентифікатор провайдера та профілю автентифікації для ChatGPT/Codex OAuth. Це також явний префікс моделі PI для Codex OAuth: - - `openai/gpt-5.5` = поточний прямий маршрут OpenAI API-ключа в PI - - `openai-codex/gpt-5.5` = маршрут Codex OAuth в PI - - `openai/gpt-5.5` + `agentRuntime.id: "codex"` = нативний маршрут Codex app-server + - `openai/gpt-5.5` + `agentRuntime.id: "codex"` = автентифікація підписки ChatGPT/Codex з нативним середовищем виконання Codex + - `openai-codex/gpt-5.5` = маршрут Codex OAuth у PI + - `openai/gpt-5.5` без перевизначення середовища виконання Codex = прямий маршрут з API-ключем OpenAI у PI - `openai-codex:...` = ідентифікатор профілю автентифікації, а не посилання на модель Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, задайте - `OPENAI_API_KEY`. Якщо вам потрібна автентифікація підписки ChatGPT/Codex, увійдіть через - `openclaw models auth login --provider openai-codex` і використовуйте - посилання на моделі `openai-codex/*` для запусків PI. + `OPENAI_API_KEY`. Якщо потрібна автентифікація підписки ChatGPT/Codex, увійдіть через + `openclaw models auth login --provider openai-codex`. Для нативного середовища виконання Codex + залиште посилання на модель як `openai/gpt-5.5` і задайте + `agentRuntime.id: "codex"`. Використовуйте посилання на моделі `openai-codex/*` лише для запусків PI. Codex OAuth використовує керовані OpenAI квотні вікна, що залежать від плану. На практиці ці ліміти можуть відрізнятися від досвіду на сайті/в застосунку ChatGPT, навіть коли - обидва прив’язані до одного облікового запису. + обидва прив’язані до того самого облікового запису. - OpenClaw може показати поточно видимі вікна використання/квот провайдера в + OpenClaw може показувати поточно видимі вікна використання/квот провайдера в `openclaw models status`, але він не вигадує й не нормалізує права ChatGPT-web у прямий доступ до API. Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, використовуйте `openai/*` з API-ключем. @@ -636,11 +639,11 @@ x-i18n: - Так. OpenClaw повністю підтримує **підписку OpenAI Code (Codex) через OAuth**. - OpenAI явно дозволяє використання OAuth підписки в зовнішніх інструментах/робочих процесах, - таких як OpenClaw. Онбординг може виконати OAuth-потік за вас. + Так. OpenClaw повністю підтримує **OpenAI Code (Codex) subscription OAuth**. + OpenAI явно дозволяє використання subscription OAuth у зовнішніх інструментах/робочих процесах, + таких як OpenClaw. Початкове налаштування може виконати OAuth-потік за вас. - Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). + Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Початкове налаштування (CLI)](/uk/start/wizard). @@ -654,49 +657,49 @@ x-i18n: - npm: `npm install -g @google/gemini-cli` 2. Увімкніть Plugin: `openclaw plugins enable google` 3. Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` - 4. Типова модель після входу: `google-gemini-cli/gemini-3-flash-preview` - 5. Якщо запити не виконуються, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway + 4. Стандартна модель після входу: `google-gemini-cli/gemini-3-flash-preview` + 5. Якщо запити не виконуються, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway - Це зберігає OAuth-токени в профілях автентифікації на хості Gateway. Докладніше: [Провайдери моделей](/uk/concepts/model-providers). + Це зберігає OAuth-токени в профілях автентифікації на хості gateway. Докладніше: [Провайдери моделей](/uk/concepts/model-providers). - - Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі карти обрізають і пропускають дані. Якщо необхідно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантовані моделі підвищують ризик prompt-injection — див. [Безпека](/uk/gateway/security). + + Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі карти обрізають і пропускають дані. Якщо все ж потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt-injection — див. [Безпека](/uk/gateway/security). - - Обирайте ендпоїнти, прив’язані до регіону. OpenRouter надає варіанти, розміщені в США, для MiniMax, Kimi і GLM; оберіть варіант, розміщений у США, щоб дані залишалися в регіоні. Ви все одно можете перелічити Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними з дотриманням обраного регіонального провайдера. + + Вибирайте кінцеві точки, прив’язані до регіону. OpenRouter надає варіанти, розміщені у США, для MiniMax, Kimi та GLM; виберіть варіант, розміщений у США, щоб утримувати дані в регіоні. Ви все ще можете перелічувати Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними з дотриманням вибраного регіонального провайдера. - + Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini необов’язковий — деякі люди - купують його як постійно ввімкнений хост, але невеликий VPS, домашній сервер або пристрій класу Raspberry Pi також підійдуть. + купують його як постійно ввімкнений хост, але невеликий VPS, домашній сервер або пристрій класу Raspberry Pi також підійде. - Mac потрібен лише **для інструментів, доступних тільки на macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або під’єднайте вузол macOS. + Mac потрібен лише **для інструментів, доступних тільки на macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або спарюйте вузол macOS. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Вузли](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - Вам потрібен **будь-який пристрій macOS**, на якому виконано вхід у Messages. Це **не** обов’язково має бути Mac mini — + Вам потрібен **якийсь пристрій macOS**, на якому виконано вхід у Messages. Це **не** обов’язково має бути Mac mini — підійде будь-який Mac. **Використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) для iMessage — сервер BlueBubbles працює на macOS, тоді як Gateway може працювати на Linux або деінде. Типові налаштування: - Запустіть Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, де виконано вхід у Messages. - - Запустіть усе на Mac, якщо хочете найпростіше налаштування на одній машині. + - Запустіть усе на Mac, якщо хочете найпростіше налаштування на одному комп’ютері. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Вузли](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - + Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключатися як **вузол** (супровідний пристрій). Вузли не запускають Gateway — вони надають додаткові - можливості, як-от екран/камера/полотно і `system.run` на цьому пристрої. + можливості, як-от екран/камера/полотно та `system.run` на цьому пристрої. Типовий шаблон: @@ -708,19 +711,19 @@ x-i18n: - - Bun **не рекомендовано**. Ми бачимо помилки виконання, особливо з WhatsApp і Telegram. - Використовуйте **Node** для стабільних Gateway. + + Bun **не рекомендовано**. Ми бачимо помилки середовища виконання, особливо з WhatsApp і Telegram. + Використовуйте **Node** для стабільних gateway. - Якщо ви все ж хочете поекспериментувати з Bun, робіть це на не продукційному Gateway + Якщо все ж хочете експериментувати з Bun, робіть це на не production gateway без WhatsApp/Telegram. - `channels.telegram.allowFrom` — це **ідентифікатор користувача Telegram людини-відправника** (числовий). Це не ім’я користувача бота. + `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не ім’я користувача бота. - Налаштування просить лише числові ідентифікатори користувачів. Якщо у вас уже є застарілі записи `@username` у конфігурації, `openclaw doctor --fix` може спробувати їх розв’язати. + Налаштування запитує лише числові ідентифікатори користувачів. Якщо у вас уже є застарілі записи `@username` у конфігурації, `openclaw doctor --fix` може спробувати їх розпізнати. Безпечніше (без стороннього бота): @@ -730,7 +733,7 @@ x-i18n: - Напишіть своєму боту в DM, потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. - Сторонні сервіси (менш приватно): + Сторонній варіант (менш приватний): - Напишіть у DM `@userinfobot` або `@getidsbot`. @@ -738,12 +741,12 @@ x-i18n: - - Так, через **маршрутизацію кількох агентів**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, відправник E.164 на кшталт `+15551234567`) до іншого `agentId`, щоб кожна людина отримала власний робочий простір і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). + + Так, через **маршрутизацію кількох агентів**. Прив’яжіть **DM** кожного відправника WhatsApp (peer `kind: "direct"`, відправник E.164 на кшталт `+15551234567`) до іншого `agentId`, щоб кожна людина мала власний робочий простір і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). - - Так. Використовуйте маршрутизацію кількох агентів: задайте кожному агенту власну типову модель, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретних peer) до кожного агента. Приклад конфігурації наведено в [Маршрутизація кількох агентів](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). + + Так. Використовуйте маршрутизацію кількох агентів: задайте кожному агенту власну стандартну модель, потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретних peers) до кожного агента. Приклад конфігурації наведено в [Маршрутизація кількох агентів](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). @@ -756,24 +759,24 @@ x-i18n: brew install ``` - Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH служби містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб установлені через `brew` інструменти знаходилися в не login-оболонках. - Останні збірки також додають на початок поширені користувацькі bin-каталоги в службах Linux systemd (наприклад, `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, коли вони задані. + Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу містить `/home/linuxbrew/.linuxbrew/bin` (або ваш brew-префікс), щоб інструменти, встановлені через `brew`, знаходилися в non-login shells. + Останні збірки також додають на початок поширені користувацькі bin-каталоги в сервісах Linux systemd (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, коли їх задано. - - - **Hackable (git) install:** повний checkout вихідного коду, придатний для редагування, найкраще для контриб’юторів. + + - **Hackable (git) install:** повний checkout вихідного коду, редагований, найкращий для контриб’юторів. Ви запускаєте збірки локально й можете виправляти код/документацію. - - **npm install:** глобальна інсталяція CLI, без репозиторію, найкраще для "просто запустити". + - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для варіанту "просто запустити". Оновлення надходять із npm dist-tags. Документація: [Початок роботи](/uk/start/getting-started), [Оновлення](/uk/install/updating). - + Так. Використовуйте `openclaw update --channel ...`, коли OpenClaw уже встановлено. - Це **не видаляє ваші дані** — воно лише змінює інсталяцію коду OpenClaw. + Це **не видаляє ваші дані** — це лише змінює встановлення коду OpenClaw. Ваш стан (`~/.openclaw`) і робочий простір (`~/.openclaw/workspace`) залишаються недоторканими. З npm на git: @@ -789,8 +792,8 @@ x-i18n: ``` Додайте `--dry-run`, щоб спочатку переглянути заплановане перемикання режиму. Оновлювач запускає - подальші дії Doctor, оновлює джерела Plugin для цільового каналу й - перезапускає Gateway, якщо ви не передасте `--no-restart`. + подальші дії Doctor, оновлює джерела Plugin для цільового каналу та + перезапускає gateway, якщо ви не передасте `--no-restart`. Інсталятор також може примусово вибрати будь-який режим: @@ -803,60 +806,60 @@ x-i18n: - + Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібне мінімальне тертя й вас влаштовують сон/перезапуски, запускайте локально. **Ноутбук (локальний Gateway)** - - **Переваги:** немає вартості сервера, прямий доступ до локальних файлів, живе вікно браузера. - - **Недоліки:** сон/мережеві збої = роз’єднання, оновлення ОС/перезавантаження переривають роботу, має залишатися ввімкненим. + - **Переваги:** немає витрат на сервер, прямий доступ до локальних файлів, живе вікно браузера. + - **Недоліки:** сон/розриви мережі = відключення, оновлення/перезавантаження ОС переривають роботу, має залишатися ввімкненим. **VPS / хмара** - - **Переваги:** завжди ввімкнений, стабільна мережа, немає проблем зі сном ноутбука, легше підтримувати роботу. - - **Недоліки:** часто працює без дисплея (використовуйте знімки екрана), лише віддалений доступ до файлів, потрібно використовувати SSH для оновлень. + - **Переваги:** завжди ввімкнено, стабільна мережа, немає проблем зі сном ноутбука, легше підтримувати роботу. + - **Недоліки:** часто працює без графічного інтерфейсу (використовуйте знімки екрана), лише віддалений доступ до файлів, для оновлень потрібно підключатися через SSH. - **Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord нормально працюють із VPS. Єдиний справжній компроміс — **headless browser** проти видимого вікна. Див. [Браузер](/uk/tools/browser). + **Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord добре працюють із VPS. Єдиний справжній компроміс — **headless browser** проти видимого вікна. Див. [Браузер](/uk/tools/browser). - **Рекомендовано за замовчуванням:** VPS, якщо раніше у вас були розриви з’єднання Gateway. Локальний запуск чудово підходить, коли ви активно користуєтеся Mac і хочете мати локальний доступ до файлів або автоматизацію UI з видимим браузером. + **Рекомендований варіант за замовчуванням:** VPS, якщо раніше у вас були розриви з’єднання Gateway. Локальний запуск чудово підходить, коли ви активно використовуєте Mac і хочете локальний доступ до файлів або автоматизацію UI з видимим браузером. Не обов’язково, але **рекомендовано для надійності та ізоляції**. - - **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, простіше підтримувати роботу. - - **Спільний ноутбук/настільний комп’ютер:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина переходить у сон або оновлюється. + - **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон або перезавантаження, чистіші дозволи, легше підтримувати роботу. + - **Спільний ноутбук/настільний комп’ютер:** цілком підходить для тестування та активного використання, але очікуйте пауз, коли машина переходить у сон або оновлюється. - Якщо хочете найкраще з обох варіантів, тримайте Gateway на виділеному хості й під’єднайте ноутбук як **Node** для локальних інструментів екрана/камери/виконання команд. Див. [Nodes](/uk/nodes). + Якщо хочете отримати переваги обох підходів, тримайте Gateway на виділеному хості та спаруйте ноутбук як **вузол** для локальних інструментів екрана/камери/exec. Див. [Вузли](/uk/nodes). Рекомендації з безпеки див. у [Безпека](/uk/gateway/security). - OpenClaw легкий. Для базового Gateway + одного каналу чату: + OpenClaw легковаговий. Для базового Gateway + одного каналу чату: - - **Абсолютний мінімум:** 1 vCPU, 1 ГБ RAM, ~500 МБ диска. - - **Рекомендовано:** 1–2 vCPU, 2 ГБ RAM або більше для запасу (журнали, медіа, кілька каналів). Інструменти Node та автоматизація браузера можуть вимагати багато ресурсів. + - **Абсолютний мінімум:** 1 vCPU, 1GB RAM, ~500MB диска. + - **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше для запасу (журнали, медіа, кілька каналів). Інструменти Node та автоматизація браузера можуть потребувати багато ресурсів. - ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення Linux найкраще протестований саме там. + ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення Linux найкраще протестовано там. Документація: [Linux](/uk/platforms/linux), [VPS-хостинг](/uk/vps). - - Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкнена, доступна й мати достатньо - RAM для Gateway та будь-яких каналів, які ви ввімкнете. + + Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкнена, доступна та мати достатньо + RAM для Gateway і всіх каналів, які ви вмикаєте. Базові рекомендації: - - **Абсолютний мінімум:** 1 vCPU, 1 ГБ RAM. - - **Рекомендовано:** 2 ГБ RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера або медіаінструменти. + - **Абсолютний мінімум:** 1 vCPU, 1GB RAM. + - **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера або медіаінструменти. - **ОС:** Ubuntu LTS або інший сучасний Debian/Ubuntu. - Якщо ви на Windows, **WSL2 — найпростіший варіант налаштування у стилі VM** і має найкращу сумісність + Якщо ви на Windows, **WSL2 — найпростіший варіант налаштування в стилі VM** і має найкращу сумісність з інструментами. Див. [Windows](/uk/platforms/windows), [VPS-хостинг](/uk/vps). Якщо ви запускаєте macOS у VM, див. [macOS VM](/uk/install/macos-vm). @@ -865,7 +868,7 @@ x-i18n: ## Пов’язане -- [FAQ](/uk/help/faq) — основний FAQ (моделі, сесії, Gateway, безпека тощо) +- [FAQ](/uk/help/faq) — основний FAQ (моделі, сесії, gateway, безпека тощо) - [Огляд встановлення](/uk/install) - [Початок роботи](/uk/start/getting-started) - [Усунення несправностей](/uk/help/troubleshooting) diff --git a/docs/uk/help/faq-models.md b/docs/uk/help/faq-models.md index 984c5de15..5c1260419 100644 --- a/docs/uk/help/faq-models.md +++ b/docs/uk/help/faq-models.md @@ -1,21 +1,21 @@ --- read_when: - Вибір або перемикання моделей, налаштування псевдонімів - - Налагодження резервного перемикання моделей / "Усі моделі завершилися помилкою" - - Розуміння профілів автентифікації та керування ними + - Налагодження аварійного перемикання моделей / "Усі моделі не спрацювали" + - Що таке профілі автентифікації та як ними керувати sidebarTitle: Models FAQ -summary: 'Поширені запитання: типові налаштування моделей, вибір, псевдоніми, перемикання, аварійне перемикання та профілі автентифікації' +summary: 'Поширені запитання: типові налаштування моделей, вибір, псевдоніми, перемикання, резервне перемикання та профілі автентифікації' title: 'Поширені запитання: моделі та автентифікація' x-i18n: - generated_at: "2026-04-29T11:04:02Z" + generated_at: "2026-05-02T02:37:18Z" model: gpt-5.5 provider: openai - source_hash: eaa72bf66d3f1528f95762e2a2763bc2f6bfddbc1d4c24a9ec2df7f943ebc14b + source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884 source_path: help/faq-models.md workflow: 16 --- - Модельні та автентифікаційно-профільні запитання й відповіді. Щодо налаштування, сеансів, Gateway, каналів і + Запитання й відповіді щодо моделей і профілів автентифікації. Щодо налаштування, сеансів, gateway, каналів і усунення несправностей див. основний [FAQ](/uk/help/faq). ## Моделі: типові значення, вибір, псевдоніми, перемикання @@ -28,24 +28,24 @@ x-i18n: agents.defaults.model.primary ``` - Моделі вказуються як `provider/model` (приклад: `openai/gpt-5.5` або `openai-codex/gpt-5.5`). Якщо ви не вкажете провайдера, OpenClaw спочатку спробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього повернеться до налаштованого типового провайдера як застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повернеться до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. Вам усе одно слід **явно** задавати `provider/model`. + Моделі задаються як `provider/model` (приклад: `openai/gpt-5.5` або `openai-codex/gpt-5.5`). Якщо ви не вкажете провайдера, OpenClaw спершу спробує псевдонім, потім унікальний збіг налаштованого провайдера для саме цього ідентифікатора моделі, і лише після цього повернеться до налаштованого типового провайдера як застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повернеться до першої налаштованої пари провайдер/модель замість показу застарілого типового значення для вилученого провайдера. Все одно варто **явно** задавати `provider/model`. - **Рекомендоване типове значення:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. - **Для агентів із підтримкою інструментів або недовіреним введенням:** віддавайте перевагу потужності моделі, а не вартості. - **Для звичайного/низькоризикового чату:** використовуйте дешевші резервні моделі й маршрутизуйте за роллю агента. + **Рекомендовано за замовчуванням:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. + **Для агентів з інструментами або недовіреним введенням:** надавайте пріоритет потужності моделі, а не вартості. + **Для звичайного чату з низькими ризиками:** використовуйте дешевші резервні моделі й маршрутизуйте за роллю агента. MiniMax має власну документацію: [MiniMax](/uk/providers/minimax) і - [Локальні моделі](/uk/gateway/local-models). + [локальні моделі](/uk/gateway/local-models). - Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити**, для роботи з високими ставками, і дешевшу - модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі для кожного агента й використовувати субагентів, щоб - паралелізувати довгі завдання (кожен субагент споживає токени). Див. [Моделі](/uk/concepts/models) і + Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити** для роботи з високими ризиками, і дешевшу + модель для звичайного чату або підсумків. Можна маршрутизувати моделі для кожного агента й використовувати субагентів для + паралельного виконання довгих завдань (кожен субагент споживає токени). Див. [Моделі](/uk/concepts/models) і [Субагенти](/uk/tools/subagents). - Серйозне попередження: слабші/надмірно квантовані моделі вразливіші до prompt + Суворе попередження: слабші або надмірно квантизовані моделі вразливіші до prompt injection і небезпечної поведінки. Див. [Безпека](/uk/gateway/security). Більше контексту: [Моделі](/uk/concepts/models). @@ -60,18 +60,18 @@ x-i18n: - `/model` у чаті (швидко, для окремого сеансу) - `openclaw models set ...` (оновлює лише конфігурацію моделі) - `openclaw configure --section model` (інтерактивно) - - редагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` + - редагувати `agents.defaults.model` у `~/.openclaw/openclaw.json` - Уникайте `config.apply` із частковим об'єктом, якщо не маєте наміру замінити всю конфігурацію. - Для RPC-редагувань спочатку перевірте через `config.schema.lookup` і надавайте перевагу `config.patch`. Корисне навантаження lookup дає нормалізований шлях, поверхневу документацію/обмеження схеми й короткі описи безпосередніх дочірніх елементів. + Уникайте `config.apply` з частковим обʼєктом, якщо не маєте наміру замінити всю конфігурацію. + Для RPC-редагувань спершу перевірте через `config.schema.lookup` і надавайте перевагу `config.patch`. Корисне навантаження lookup дає нормалізований шлях, стислі документи/обмеження схеми й підсумки безпосередніх дочірніх елементів для часткових оновлень. - Якщо ви перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення. + Якщо ви перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для відновлення. Документація: [Моделі](/uk/concepts/models), [Налаштування](/uk/cli/configure), [Конфігурація](/uk/cli/config), [Doctor](/uk/gateway/doctor). - + Так. Ollama — найпростіший шлях для локальних моделей. Найшвидше налаштування: @@ -82,15 +82,15 @@ x-i18n: 4. Запустіть `openclaw onboard` і виберіть `Ollama` 5. Виберіть `Local` або `Cloud + Local` - Примітки: + Нотатки: - - `Cloud + Local` дає вам хмарні моделі плюс ваші локальні моделі Ollama - - хмарні моделі, як-от `kimi-k2.5:cloud`, не потребують локального завантаження + - `Cloud + Local` дає хмарні моделі разом із вашими локальними моделями Ollama + - хмарні моделі на кшталт `kimi-k2.5:cloud` не потребують локального завантаження - для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/` - Примітка щодо безпеки: менші або сильно квантовані моделі вразливіші до prompt - injection. Ми настійно рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти. - Якщо ви все ж хочете малі моделі, увімкніть sandboxing і суворі списки дозволених інструментів. + Примітка щодо безпеки: менші або сильно квантизовані моделі вразливіші до prompt + injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти. + Якщо ви все одно хочете малі моделі, увімкніть sandboxing і суворі списки дозволених інструментів. Документація: [Ollama](/uk/providers/ollama), [Локальні моделі](/uk/gateway/local-models), [Провайдери моделей](/uk/concepts/model-providers), [Безпека](/uk/gateway/security), @@ -99,9 +99,9 @@ x-i18n: - - Ці розгортання можуть відрізнятися й змінюватися з часом; сталої рекомендації щодо провайдера немає. + - Ці розгортання можуть відрізнятися й змінюватися з часом; фіксованої рекомендації щодо провайдера немає. - Перевірте поточне runtime-налаштування на кожному gateway за допомогою `openclaw models status`. - - Для чутливих до безпеки агентів або агентів із підтримкою інструментів використовуйте найсильнішу модель останнього покоління, доступну вам. + - Для агентів, чутливих до безпеки або з інструментами, використовуйте найсильнішу модель останнього покоління з доступних. @@ -118,9 +118,9 @@ x-i18n: /model gemini-flash-lite ``` - Це вбудовані псевдоніми. Користувацькі псевдоніми можна додати через `agents.defaults.models`. + Це вбудовані псевдоніми. Власні псевдоніми можна додати через `agents.defaults.models`. - Ви можете переглянути доступні моделі за допомогою `/model`, `/model list` або `/model status`. + Доступні моделі можна переглянути за допомогою `/model`, `/model list` або `/model status`. `/model` (і `/model list`) показує компактний нумерований вибір. Виберіть за номером: @@ -128,17 +128,17 @@ x-i18n: /model 3 ``` - Ви також можете примусово задати конкретний профіль автентифікації для провайдера (для окремого сеансу): + Також можна примусово задати конкретний профіль автентифікації для провайдера (для окремого сеансу): ``` /model opus@anthropic:default /model opus@anthropic:work ``` - Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробовано далі. - Він також показує налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли вони доступні. + Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробувано далі. + Також показує налаштовану endpoint-адресу провайдера (`baseUrl`) і режим API (`api`), коли вони доступні. - **Як відкріпити профіль, який я встановив через @profile?** + **Як відкріпити профіль, який я задав через @profile?** Повторно запустіть `/model` **без** суфікса `@profile`: @@ -151,22 +151,23 @@ x-i18n: - - Так. Встановіть одну модель типовою й перемикайтеся за потреби: + + Так. Розглядайте вибір моделі й вибір runtime окремо: - - **Швидке перемикання (для окремого сеансу):** `/model openai/gpt-5.5` для поточних завдань із прямим ключем OpenAI API або `/model openai-codex/gpt-5.5` для завдань GPT-5.5 Codex OAuth. - - **Типове значення:** встановіть `agents.defaults.model.primary` на `openai/gpt-5.5` для використання API-ключа або `openai-codex/gpt-5.5` для використання GPT-5.5 Codex OAuth. - - **Субагенти:** маршрутизуйте завдання кодування до субагентів з іншою типовою моделлю. + - **Нативний агент програмування Codex:** установіть `agents.defaults.model.primary` на `openai/gpt-5.5`, а `agents.defaults.agentRuntime.id` на `"codex"`. Увійдіть через `openclaw models auth login --provider openai-codex`, коли хочете автентифікацію підписки ChatGPT/Codex. + - **Прямі завдання OpenAI API через PI:** використовуйте `/model openai/gpt-5.5` без перевизначення runtime Codex і налаштуйте `OPENAI_API_KEY`. + - **Codex OAuth через PI:** використовуйте `/model openai-codex/gpt-5.5` лише тоді, коли свідомо хочете звичайний PI runner із Codex OAuth. + - **Субагенти:** маршрутизуйте завдання програмування до агента лише для Codex з власною моделлю і типовим `agentRuntime`. - Див. [Моделі](/uk/concepts/models) і [Slash-команди](/uk/tools/slash-commands). + Див. [Моделі](/uk/concepts/models) і [Slash commands](/uk/tools/slash-commands). - + Використовуйте перемикач сеансу або типове значення конфігурації: - **Для окремого сеансу:** надішліть `/fast on`, поки сеанс використовує `openai/gpt-5.5` або `openai-codex/gpt-5.5`. - - **Типове значення для моделі:** встановіть `agents.defaults.models["openai/gpt-5.5"].params.fastMode` або `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` у `true`. + - **Типове значення для моделі:** установіть `agents.defaults.models["openai/gpt-5.5"].params.fastMode` або `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` на `true`. Приклад: @@ -186,40 +187,39 @@ x-i18n: } ``` - Для OpenAI швидкий режим відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Перевизначення сеансу `/fast` мають пріоритет над типовими значеннями конфігурації. + Для OpenAI fast mode відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Сеансові перевизначення `/fast` мають пріоритет над типовими значеннями конфігурації. - Див. [Мислення і швидкий режим](/uk/tools/thinking) і [Швидкий режим OpenAI](/uk/providers/openai#fast-mode). + Див. [Thinking і fast mode](/uk/tools/thinking) та [OpenAI fast mode](/uk/providers/openai#fast-mode). - Якщо `agents.defaults.models` встановлено, це стає **списком дозволених** для `/model` і будь-яких - перевизначень сеансу. Вибір моделі, якої немає в цьому списку, повертає: + Якщо встановлено `agents.defaults.models`, це стає **списком дозволених** для `/model` і будь-яких + сеансових перевизначень. Вибір моделі, якої немає в цьому списку, повертає: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` Ця помилка повертається **замість** звичайної відповіді. Виправлення: додайте модель до - `agents.defaults.models`, видаліть список дозволених або виберіть модель із `/model list`. + `agents.defaults.models`, вилучіть список дозволених або виберіть модель з `/model list`. - Це означає, що **провайдера не налаштовано** (не знайдено конфігурації провайдера MiniMax або профілю - автентифікації), тому модель неможливо розв'язати. + Це означає, що **провайдера не налаштовано** (не знайдено конфігурацію провайдера MiniMax або профіль автентифікації), тож модель не можна розвʼязати. Контрольний список виправлення: - 1. Оновіться до поточного випуску OpenClaw (або запустіть із вихідного коду `main`), потім перезапустіть gateway. - 2. Переконайтеся, що MiniMax налаштовано (майстер або JSON), або що автентифікація MiniMax - існує в env/профілях автентифікації, щоб відповідний провайдер можна було ін'єктувати + 1. Оновіться до поточного випуску OpenClaw (або запустіть із source `main`), потім перезапустіть gateway. + 2. Переконайтеся, що MiniMax налаштовано (майстром або JSON), або що автентифікація MiniMax + існує в env/профілях автентифікації, щоб відповідний провайдер можна було інʼєктувати (`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений MiniMax OAuth для `minimax-portal`). 3. Використовуйте точний ідентифікатор моделі (з урахуванням регістру) для вашого шляху автентифікації: - `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування з API-ключем, + `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування з API-key, або `minimax-portal/MiniMax-M2.7` / - `minimax-portal/MiniMax-M2.7-highspeed` для налаштування OAuth. + `minimax-portal/MiniMax-M2.7-highspeed` для налаштування з OAuth. 4. Запустіть: ```bash @@ -232,8 +232,8 @@ x-i18n: - - Так. Використовуйте **MiniMax як типову модель** і перемикайте моделі **для окремого сеансу**, коли потрібно. + + Так. Використовуйте **MiniMax як типовий варіант** і перемикайте моделі **для окремого сеансу**, коли потрібно. Резервні варіанти призначені для **помилок**, а не для "складних завдань", тому використовуйте `/model` або окремого агента. **Варіант A: перемикання для окремого сеансу** @@ -261,31 +261,31 @@ x-i18n: **Варіант B: окремі агенти** - - Типова модель агента A: MiniMax - - Типова модель агента B: OpenAI + - Типове значення агента A: MiniMax + - Типове значення агента B: OpenAI - Маршрутизуйте за агентом або використовуйте `/agent` для перемикання - Документація: [Моделі](/uk/concepts/models), [Маршрутизація кількох агентів](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). + Документація: [Моделі](/uk/concepts/models), [Multi-Agent Routing](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). - Так. OpenClaw постачається з кількома типовими скороченнями (застосовуються лише тоді, коли модель існує в `agents.defaults.models`): + Так. OpenClaw постачається з кількома типовими скороченнями (застосовуються лише коли модель існує в `agents.defaults.models`): - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` - - `gpt` → `openai/gpt-5.5` для налаштувань з API-ключем або `openai-codex/gpt-5.5`, коли налаштовано Codex OAuth + - `gpt` → `openai/gpt-5.5` для налаштувань з API-key або `openai-codex/gpt-5.5`, коли налаштовано Codex OAuth - `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` - Якщо ви задасте власний псевдонім із такою самою назвою, ваше значення матиме пріоритет. + Якщо ви задасте власний псевдонім із тією самою назвою, ваше значення матиме пріоритет. - + Псевдоніми беруться з `agents.defaults.models..alias`. Приклад: ```json5 @@ -303,12 +303,12 @@ x-i18n: } ``` - Тоді `/model sonnet` (або `/`, коли підтримується) розв'язується в цей ідентифікатор моделі. + Потім `/model sonnet` (або `/`, коли підтримується) розвʼязується в цей ідентифікатор моделі. - - OpenRouter (оплата за токени; багато моделей): + + OpenRouter (оплата за токен; багато моделей): ```json5 { @@ -338,9 +338,9 @@ x-i18n: Якщо ви посилаєтеся на постачальника/модель, але потрібний ключ постачальника відсутній, ви отримаєте помилку автентифікації під час виконання (наприклад, `No API key found for provider "zai"`). - **Ключ API для постачальника не знайдено після додавання нового агента** + **Не знайдено API-ключ для постачальника після додавання нового агента** - Зазвичай це означає, що **новий агент** має порожнє сховище автентифікації. Автентифікація прив’язана до агента й + Зазвичай це означає, що **новий агент** має порожнє сховище автентифікації. Автентифікація є окремою для кожного агента й зберігається в: ``` @@ -350,8 +350,8 @@ x-i18n: Варіанти виправлення: - Запустіть `openclaw agents add ` і налаштуйте автентифікацію під час роботи майстра. - - Або скопіюйте лише переносні статичні профілі `api_key` / `token` зі сховища автентифікації основного агента до сховища автентифікації нового агента. - - Для профілів OAuth увійдіть із нового агента, коли йому потрібен власний обліковий запис; інакше OpenClaw може читати через стандартного/основного агента без клонування токенів оновлення. + - Або скопіюйте лише портативні статичні профілі `api_key` / `token` зі сховища автентифікації основного агента до сховища автентифікації нового агента. + - Для профілів OAuth увійдіть із нового агента, коли йому потрібен власний обліковий запис; інакше OpenClaw може читати з агента за замовчуванням/основного агента без клонування refresh-токенів. **Не** використовуйте повторно `agentDir` для різних агентів; це спричиняє конфлікти автентифікації/сеансів. @@ -365,94 +365,94 @@ x-i18n: Резервне перемикання відбувається у два етапи: 1. **Ротація профілів автентифікації** у межах того самого постачальника. - 2. **Резервний перехід моделі** до наступної моделі в `agents.defaults.model.fallbacks`. + 2. **Резервне перемикання моделі** на наступну модель у `agents.defaults.model.fallbacks`. - Періоди охолодження застосовуються до профілів, що зазнають помилок (експоненційне відтермінування), тому OpenClaw може продовжувати відповідати, навіть коли постачальник обмежує частоту запитів або тимчасово не працює. + Для проблемних профілів застосовуються періоди очікування (експоненційна затримка), тож OpenClaw може продовжувати відповідати, навіть коли постачальник обмежує частоту запитів або тимчасово не працює. - Сегмент обмеження частоти містить більше, ніж звичайні відповіді `429`. OpenClaw - також розглядає повідомлення на кшталт `Too many concurrent requests`, + Бакет обмеження частоти містить не лише звичайні відповіді `429`. OpenClaw + також трактує повідомлення на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` і періодичні - обмеження вікна використання (`weekly/monthly limit reached`) як обмеження частоти, - достатні для резервного перемикання. + ліміти вікна використання (`weekly/monthly limit reached`) як обмеження + частоти, що потребують резервного перемикання. Деякі відповіді, схожі на білінгові, не є `402`, а деякі HTTP-відповіді `402` - також залишаються в цьому тимчасовому сегменті. Якщо постачальник повертає - явний білінговий текст для `401` або `403`, OpenClaw усе ще може залишити це - в білінговій гілці, але специфічні для постачальника зіставлення тексту залишаються обмеженими - постачальником, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402` - натомість виглядає як придатне до повтору вікно використання або + також залишаються в цьому тимчасовому бакеті. Якщо постачальник повертає + явний білінговий текст на `401` або `403`, OpenClaw усе одно може залишити це + в білінговій смузі, але специфічні для постачальника текстові збіги залишаються + обмеженими постачальником, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402` + натомість виглядає як повторюване вікно використання або ліміт витрат організації/робочого простору (`daily limit reached, resets tomorrow`, - `organization spending limit exceeded`), OpenClaw розглядає його як - `rate_limit`, а не як тривале вимкнення через білінг. + `organization spending limit exceeded`), OpenClaw трактує його як + `rate_limit`, а не як довге білінгове вимкнення. - Помилки переповнення контексту відрізняються: сигнатури на кшталт + Помилки переповнення контексту інші: сигнатури на кшталт `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` або `ollama error: context length - exceeded` залишаються на шляху Compaction/повторної спроби, а не просувають - резервний перехід моделі. + exceeded` залишаються на шляху Compaction/повторної спроби замість просування до + резервного перемикання моделі. - Загальний текст помилки сервера навмисно вужчий, ніж "будь-що з - unknown/error у ньому". OpenClaw справді розглядає тимчасові форми, обмежені постачальником, - як-от Anthropic bare `An unknown error occurred`, OpenRouter bare + Універсальний текст серверної помилки навмисно вужчий, ніж "будь-що з + unknown/error у ньому". OpenClaw справді трактує прив’язані до постачальника тимчасові форми, + як-от Anthropic без додаткових даних `An unknown error occurred`, OpenRouter без додаткових даних `Provider returned error`, помилки причини зупинки на кшталт `Unhandled stop reason: - error`, корисні навантаження JSON `api_error` із тимчасовим серверним текстом + error`, JSON-навантаження `api_error` з тимчасовим серверним текстом (`internal server error`, `unknown error, 520`, `upstream error`, `backend error`) і помилки зайнятості постачальника, як-от `ModelNotReadyException`, як - сигнали таймауту/перевантаження, достатні для резервного перемикання, коли контекст постачальника + сигнали тайм-ауту/перевантаження, що потребують резервного перемикання, коли контекст постачальника збігається. - Загальний внутрішній текст резервної помилки на кшталт `LLM request failed with an unknown - error.` залишається консервативним і сам по собі не запускає резервний перехід моделі. + Універсальний внутрішній текст резервного шляху, як-от `LLM request failed with an unknown + error.`, залишається консервативним і сам по собі не запускає резервне перемикання моделі. - Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації. + Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти облікові дані для нього в очікуваному сховищі автентифікації. **Контрольний список виправлення:** - - **Підтвердьте, де зберігаються профілі автентифікації** (нові та застарілі шляхи) + - **Підтвердьте, де зберігаються профілі автентифікації** (нові й застарілі шляхи) - Поточний: `~/.openclaw/agents//agent/auth-profiles.json` - Застарілий: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`) - - **Підтвердьте, що ваша змінна середовища завантажується Gateway** - - Якщо ви задали `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або ввімкніть `env.shellEnv`. - - **Переконайтеся, що редагуєте правильного агента** - - У конфігураціях із кількома агентами може бути кілька файлів `auth-profiles.json`. + - **Підтвердьте, що ваша змінна середовища завантажена Gateway** + - Якщо ви встановили `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або увімкніть `env.shellEnv`. + - **Переконайтеся, що ви редагуєте правильного агента** + - У налаштуваннях із кількома агентами може бути кілька файлів `auth-profiles.json`. - **Перевірте стан моделі/автентифікації** - - Використайте `openclaw models status`, щоб побачити налаштовані моделі та чи автентифіковані постачальники. + - Використайте `openclaw models status`, щоб побачити налаштовані моделі й чи автентифіковані постачальники. **Контрольний список виправлення для "No credentials found for profile anthropic"** - Це означає, що запуск прив’язано до профілю автентифікації Anthropic, але Gateway + Це означає, що запуск закріплено за профілем автентифікації Anthropic, але Gateway не може знайти його у своєму сховищі автентифікації. - **Використайте Claude CLI** - - Запустіть `openclaw models auth login --provider anthropic --method cli --set-default` на хості Gateway. - - **Якщо натомість хочете використати ключ API** - - Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості Gateway**. - - Очистьте будь-який закріплений порядок, який примусово вимагає відсутній профіль: + - Запустіть `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway. + - **Якщо натомість ви хочете використати API-ключ** + - Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**. + - Очистьте будь-який закріплений порядок, який примусово використовує відсутній профіль: ```bash openclaw models auth order clear --provider anthropic ``` - - **Підтвердьте, що виконуєте команди на хості Gateway** - - У віддаленому режимі профілі автентифікації зберігаються на машині Gateway, а не на вашому ноутбуці. + - **Підтвердьте, що ви виконуєте команди на хості gateway** + - У віддаленому режимі профілі автентифікації зберігаються на машині gateway, а не на вашому ноутбуці. - - Якщо ваша конфігурація моделі містить Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного переходу моделі. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`. + + Якщо ваша конфігурація моделі містить Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного перемикання моделі. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`. - Виправлення: або надайте автентифікацію Google, або вилучіть/уникайте моделей Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервний перехід не маршрутизував туди. + Виправлення: або надайте автентифікацію Google, або видаліть/уникайте моделей Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервне перемикання не маршрутизувало туди. - **Запит LLM відхилено: потрібна сигнатура thinking (Google Antigravity)** + **Запит LLM відхилено: потрібен підпис thinking (Google Antigravity)** - Причина: історія сеансу містить **блоки thinking без сигнатур** (часто з - перерваного/часткового потоку). Google Antigravity вимагає сигнатури для блоків thinking. + Причина: історія сеансу містить **блоки thinking без підписів** (часто з + перерваного/часткового потоку). Google Antigravity вимагає підписів для блоків thinking. - Виправлення: OpenClaw тепер вилучає непідписані блоки thinking для Google Antigravity Claude. Якщо це все ще з’являється, почніть **новий сеанс** або встановіть `/thinking off` для цього агента. + Виправлення: OpenClaw тепер видаляє непідписані блоки thinking для Google Antigravity Claude. Якщо це все ще з’являється, почніть **новий сеанс** або встановіть `/thinking off` для цього агента. @@ -463,7 +463,7 @@ x-i18n: - Профіль автентифікації — це іменований запис облікових даних (OAuth або ключ API), прив’язаний до постачальника. Профілі зберігаються в: + Профіль автентифікації — це іменований запис облікових даних (OAuth або API-ключ), прив’язаний до постачальника. Профілі зберігаються в: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -471,25 +471,25 @@ x-i18n: - - OpenClaw використовує ID із префіксом постачальника, як-от: + + OpenClaw використовує ID з префіксом постачальника, наприклад: - - `anthropic:default` (поширено, коли немає ідентичності електронної пошти) + - `anthropic:default` (типово, коли немає ідентичності електронної пошти) - `anthropic:` для ідентичностей OAuth - - власні ID, які ви вибираєте (наприклад, `anthropic:work`) + - власні ID, які ви обираєте (наприклад, `anthropic:work`) - + Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного постачальника (`auth.order.`). Це **не** зберігає секрети; це зіставляє ID з постачальником/режимом і задає порядок ротації. - OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **періоді охолодження** (обмеження частоти/таймаути/помилки автентифікації) або в тривалішому **вимкненому** стані (білінг/недостатньо кредитів). Щоб це перевірити, запустіть `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. + OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **періоді очікування** (обмеження частоти/тайм-аути/збої автентифікації) або в довшому стані **вимкнено** (білінг/недостатньо кредитів). Щоб перевірити це, запустіть `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. - Періоди охолодження через обмеження частоти можуть бути обмежені моделлю. Профіль, який охолоджується + Періоди очікування через обмеження частоти можуть бути прив’язані до моделі. Профіль, який охолоджується для однієї моделі, усе ще може бути придатним для спорідненої моделі в того самого постачальника, тоді як білінгові/вимкнені вікна все одно блокують увесь профіль. - Ви також можете задати перевизначення порядку **для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI: + Ви також можете встановити перевизначення порядку **для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI: ```bash # Defaults to the configured default agent (omit --agent) @@ -511,31 +511,31 @@ x-i18n: openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - Щоб перевірити, що фактично пробуватиметься, використайте: + Щоб перевірити, що насправді буде спробовано, використайте: ```bash openclaw models status --probe ``` Якщо збережений профіль пропущено в явному порядку, probe повідомляє - `excluded_by_auth_order` для цього профілю замість того, щоб мовчки пробувати його. + `excluded_by_auth_order` для цього профілю замість того, щоб непомітно спробувати його. - + OpenClaw підтримує обидва варіанти: - **OAuth** часто використовує доступ за підпискою (де це застосовно). - - **Ключі API** використовують оплату за токени. + - **API-ключі** використовують оплату за токени. - Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і ключі API. + Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API-ключі. -## Пов’язано +## Пов’язане - [FAQ](/uk/help/faq) — основний FAQ -- [FAQ — швидкий старт і початкове налаштування](/uk/help/faq-first-run) +- [FAQ — швидкий старт і перше налаштування](/uk/help/faq-first-run) - [Вибір моделі](/uk/concepts/model-providers) - [Резервне перемикання моделей](/uk/concepts/model-failover) diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index 512691106..f54151d42 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,48 +1,58 @@ --- read_when: - - Ви хочете використати вбудовану обв’язку сервера застосунку Codex - - Вам потрібні приклади конфігурації harness для Codex + - Ви хочете використовувати вбудований стенд Codex app-server + - Вам потрібні приклади конфігурації середовища Codex - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість резервного переходу на PI -summary: Запускайте ходи вбудованого агента OpenClaw через комплектну обв’язку app-server Codex -title: обв’язка Codex +summary: Запускайте ходи вбудованого агента OpenClaw через комплектну обв’язку Codex app-server +title: Середовище Codex x-i18n: - generated_at: "2026-05-01T20:39:57Z" + generated_at: "2026-05-02T02:37:21Z" model: gpt-5.5 provider: openai - source_hash: 082c3a81eb6ef238477ca4013114a84e6ea7b188e23fb31855297beaaa7fec40 + source_hash: 107f9fc0a3e8ad6a4790fc9eb68276c81d299236f11293014d2ab9bf6e235133 source_path: plugins/codex-harness.md workflow: 16 --- -Вбудований plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через -Codex app-server замість вбудованого PI harness. +Пакетний Plugin `codex` дає OpenClaw змогу виконувати вбудовані ходи агента через +app-server Codex замість вбудованого середовища PI. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: -виявленням моделей, нативним відновленням потоку, нативним Compaction і виконанням -app-server. OpenClaw і надалі керує каналами чату, файлами сесій, вибором моделей, -інструментами, схваленнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли потрібно, щоб Codex керував низькорівневою сесією агента: виявленням +моделей, нативним відновленням гілки, нативною Compaction та виконанням через app-server. +OpenClaw і далі керує чат-каналами, файлами сесій, вибором моделі, інструментами, +схваленнями, доставкою медіа та видимим дзеркалом транскрипту. -Коли хід із вихідного чату виконується через Codex harness, видимі відповіді за -замовчуванням використовують інструмент OpenClaw `message`, якщо розгортання явно -не налаштувало `messages.visibleReplies`. Агент усе ще може завершити свій хід -Codex приватно; він публікує в канал лише тоді, коли викликає `message(action="send")`. -Задайте `messages.visibleReplies: "automatic"`, щоб зберегти фінальні відповіді -прямого чату на застарілому автоматичному шляху доставки. +Коли хід із початкового чату виконується через середовище Codex, видимі відповіді за замовчуванням +надсилаються через інструмент OpenClaw `message`, якщо розгортання явно не налаштувало +`messages.visibleReplies`. Агент усе ще може завершити свій хід Codex приватно; +він публікує повідомлення в каналі лише тоді, коли викликає `message(action="send")`. Установіть +`messages.visibleReplies: "automatic"`, щоб зберегти фінальні відповіді в прямому чаті на +застарілому автоматичному шляху доставки. -Ходи Codex heartbeat також за замовчуванням отримують інструмент `heartbeat_respond`, -щоб агент міг записати, чи пробудження має залишитися тихим або надіслати -сповіщення, не кодувавши цей керівний потік у фінальному тексті. +Ходи Heartbeat у Codex також за замовчуванням отримують інструмент `heartbeat_respond`, щоб +агент міг записати, чи пробудження має залишитися тихим або надіслати сповіщення, не кодувавши +цей потік керування у фінальному тексті. Якщо ви намагаєтеся зорієнтуватися, почніть з -[Середовища виконання агентів](/uk/concepts/agent-runtimes). Коротко: -`openai/gpt-5.5` — це посилання на модель, `codex` — runtime, а Telegram, +[Середовищ виконання агентів](/uk/concepts/agent-runtimes). Коротко: +`openai/gpt-5.5` — це посилання на модель, `codex` — середовище виконання, а Telegram, Discord, Slack або інший канал залишається поверхнею комунікації. ## Швидка конфігурація -Щоб використовувати Codex harness для ходів агента GPT, зберігайте канонічне -посилання на модель як `openai/gpt-*`, увімкніть вбудований plugin `codex` і задайте -`agentRuntime.id: "codex"`: +Більшість користувачів, які хочуть "Codex в OpenClaw", потребують цього маршруту: увійти з +підпискою ChatGPT/Codex, а потім виконувати вбудовані ходи агента через нативне +середовище виконання app-server Codex. Посилання на модель і далі залишається канонічним як +`openai/gpt-*`; автентифікація підписки надходить з облікового запису/профілю Codex, а не +з префікса моделі `openai-codex/*`. + +Спершу увійдіть через Codex OAuth, якщо ще цього не зробили: + +```bash +openclaw models auth login --provider openai-codex +``` + +Потім увімкніть пакетний Plugin `codex` і примусово задайте середовище виконання Codex: ```json5 { @@ -65,7 +75,7 @@ Discord, Slack або інший канал залишається поверх } ``` -Якщо ваша конфігурація використовує `plugins.allow`, додайте туди також `codex`: +Якщо ваша конфігурація використовує `plugins.allow`, також додайте туди `codex`: ```json5 { @@ -80,40 +90,39 @@ Discord, Slack або інший канал залишається поверх } ``` -Не використовуйте `openai-codex/gpt-*` для цього шляху. Це вибирає Codex OAuth -через звичайний PI runner, якщо ви окремо не примусите runtime. Зміни -конфігурації застосовуються до нових або скинутих сесій; наявні сесії зберігають -свій записаний runtime. +Не використовуйте `openai-codex/gpt-*`, коли маєте на увазі нативне середовище виконання Codex. Цей префікс +є явним маршрутом "Codex OAuth через PI". Зміни конфігурації застосовуються до нових або +скинутих сесій; наявні сесії зберігають записане середовище виконання. -## Що змінює цей plugin +## Що змінює цей Plugin -Вбудований plugin `codex` додає кілька окремих можливостей: +Пакетний Plugin `codex` додає кілька окремих можливостей: -| Можливість | Як ви її використовуєте | Що вона робить | -| -------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------- | -| Нативний вбудований runtime | `agentRuntime.id: "codex"` | Запускає вбудовані ходи агента OpenClaw через Codex app-server. | -| Нативні команди керування чатом | `/codex bind`, `/codex resume`, `/codex steer`, ... | Прив’язує та керує потоками Codex app-server із розмови в месенджері. | -| Провайдер/каталог Codex app-server | внутрішні механізми `codex`, доступні через harness | Дає runtime змогу виявляти й перевіряти моделі app-server. | -| Шлях розуміння медіа Codex | шляхи сумісності моделей зображень `codex/*` | Запускає обмежені ходи Codex app-server для підтримуваних моделей розуміння зображень. | -| Нативна ретрансляція hooks | Plugin hooks навколо нативних подій Codex | Дає OpenClaw змогу спостерігати/блокувати підтримувані нативні події інструментів/фіналізації Codex. | +| Можливість | Як ви її використовуєте | Що вона робить | +| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | +| Нативне вбудоване середовище виконання | `agentRuntime.id: "codex"` | Виконує вбудовані ходи агента OpenClaw через app-server Codex. | +| Нативні команди керування чатом | `/codex bind`, `/codex resume`, `/codex steer`, ... | Прив’язує гілки app-server Codex до розмови в месенджері та керує ними. | +| Провайдер/каталог app-server Codex | внутрішні механізми `codex`, доступні через середовище | Дає середовищу виконання змогу виявляти й перевіряти моделі app-server. | +| Шлях розуміння медіа Codex | шляхи сумісності моделей зображень `codex/*` | Виконує обмежені ходи app-server Codex для підтримуваних моделей розуміння зображень. | +| Нативна ретрансляція хуків | Хуки Plugin навколо нативних подій Codex | Дає OpenClaw змогу спостерігати/блокувати підтримувані нативні події інструментів/фіналізації Codex. | -Увімкнення plugin робить ці можливості доступними. Воно **не**: +Увімкнення Plugin робить ці можливості доступними. Воно **не**: - починає використовувати Codex для кожної моделі OpenAI -- перетворює посилання на моделі `openai-codex/*` на нативний runtime +- перетворює посилання на моделі `openai-codex/*` на нативне середовище виконання - робить ACP/acpx стандартним шляхом Codex -- гаряче перемикає наявні сесії, які вже записали PI runtime -- замінює доставку каналів OpenClaw, файли сесій, сховище auth-profile або +- гаряче перемикає наявні сесії, які вже записали середовище виконання PI +- замінює доставку каналами OpenClaw, файли сесій, сховище профілів автентифікації або маршрутизацію повідомлень -Той самий plugin також володіє нативною поверхнею команд керування чатом -`/codex`. Якщо plugin увімкнений і користувач просить прив’язати, відновити, -скерувати, зупинити або переглянути потоки Codex із чату, агенти мають надавати -перевагу `/codex ...` над ACP. ACP залишається явним запасним варіантом, коли -користувач просить ACP/acpx або тестує адаптер ACP Codex. +Цей самий Plugin також відповідає за нативну поверхню команд керування чатом `/codex`. Якщо +Plugin увімкнено й користувач просить прив’язати, відновити, скерувати, зупинити або переглянути +гілки Codex із чату, агенти мають надавати перевагу `/codex ...` перед ACP. ACP залишається +явним резервним варіантом, коли користувач просить ACP/acpx або тестує адаптер ACP +Codex. -Нативні ходи Codex зберігають OpenClaw plugin hooks як публічний шар сумісності. -Це внутрішньопроцесні hooks OpenClaw, а не командні hooks Codex `hooks.json`: +Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності. +Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`: - `before_prompt_build` - `before_compaction`, `after_compaction` @@ -123,159 +132,158 @@ Discord, Slack або інший канал залишається поверх - `before_agent_finalize` через ретрансляцію Codex `Stop` - `agent_end` -Plugins також можуть реєструвати runtime-нейтральне проміжне ПЗ результатів -інструментів, щоб переписувати динамічні результати інструментів OpenClaw після -того, як OpenClaw виконає інструмент, і до повернення результату в Codex. Це -окремо від публічного plugin hook `tool_result_persist`, який трансформує -належні OpenClaw записи результатів інструментів у транскрипті. +Plugins також можуть реєструвати нейтральне до середовища виконання проміжне ПЗ результатів інструментів, щоб переписувати +динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, як +результат буде повернуто до Codex. Це окремо від публічного +хука Plugin `tool_result_persist`, який трансформує записи результатів інструментів у транскрипті, +що належать OpenClaw. -Щодо семантики самих plugin hooks див. [Plugin hooks](/uk/plugins/hooks) -і [Поведінка Plugin guard](/uk/tools/plugin). +Про саму семантику хуків Plugin див. [Хуки Plugin](/uk/plugins/hooks) +і [Поведінка захисту Plugin](/uk/tools/plugin). -Harness вимкнений за замовчуванням. Нові конфігурації мають зберігати посилання -на моделі OpenAI канонічними як `openai/gpt-*` і явно примушувати -`agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли їм потрібне -нативне виконання app-server. Застарілі посилання на моделі `codex/*` усе ще -автоматично вибирають harness для сумісності, але застарілі runtime-backed -префікси провайдерів не показуються як звичайні варіанти моделей/провайдерів. +Середовище вимкнено за замовчуванням. Нові конфігурації мають зберігати посилання на моделі OpenAI +канонічними як `openai/gpt-*` і явно задавати +`agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли їм +потрібне нативне виконання app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають +це середовище для сумісності, але застарілі префікси провайдерів, підкріплені середовищем виконання, +не показуються як звичайні варіанти моделей/провайдерів. -Якщо plugin `codex` увімкнений, але основна модель усе ще -`openai-codex/*`, `openclaw doctor` попереджає замість зміни маршруту. Це -навмисно: `openai-codex/*` залишається шляхом PI Codex OAuth/підписки, а -нативне виконання app-server залишається явним вибором runtime. +Якщо Plugin `codex` увімкнено, але основна модель і далі +`openai-codex/*`, `openclaw doctor` попереджає замість того, щоб змінювати маршрут. Це +навмисно: `openai-codex/*` залишається шляхом Codex OAuth/підписки через PI, а +нативне виконання app-server лишається явним вибором середовища виконання. -## Карта маршрутів +## Мапа маршрутів -Використовуйте цю таблицю перед зміною конфігурації: +Скористайтеся цією таблицею перед зміною конфігурації: -| Бажана поведінка | Посилання на модель | Конфігурація runtime | Вимога до plugin | Очікувана мітка стану | -| ------------------------------------------ | ------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ | -| OpenAI API через звичайний runner OpenClaw | `openai/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI | `Runtime: OpenClaw Pi Default` | -| Codex OAuth/підписка через PI | `openai-codex/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI Codex OAuth | `Runtime: OpenClaw Pi Default` | -| Нативні вбудовані ходи Codex app-server | `openai/gpt-*` | `agentRuntime.id: "codex"` | plugin `codex` | `Runtime: OpenAI Codex` | -| Змішані провайдери з консервативним автоматичним режимом | посилання, специфічні для провайдера | `agentRuntime.id: "auto"` | Необов’язкові plugin runtimes | Залежить від вибраного runtime | -| Явна сесія адаптера Codex ACP | залежить від ACP prompt/model | `sessions_spawn` з `runtime: "acp"` | справний бекенд `acpx` | Стан ACP завдання/сесії | +| Бажана поведінка | Посилання на модель | Конфігурація середовища виконання | Маршрут автентифікації/профілю | Очікувана мітка стану | +| ---------------------------------------------------- | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ | +| Підписка ChatGPT/Codex з нативним середовищем виконання Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth або обліковий запис Codex | `Runtime: OpenAI Codex` | +| OpenAI API через звичайний runner OpenClaw | `openai/gpt-*` | пропущено або `runtime: "pi"` | ключ OpenAI API | `Runtime: OpenClaw Pi Default` | +| Підписка ChatGPT/Codex через PI | `openai-codex/gpt-*` | пропущено або `runtime: "pi"` | провайдер OpenAI Codex OAuth | `Runtime: OpenClaw Pi Default` | +| Змішані провайдери з консервативним автоматичним режимом | посилання, специфічні для провайдера | `agentRuntime.id: "auto"` | Для вибраного провайдера | Залежить від вибраного середовища виконання | +| Явна сесія адаптера Codex ACP | залежить від prompt/моделі ACP | `sessions_spawn` з `runtime: "acp"` | автентифікація бекенду ACP | стан завдання/сесії ACP | -Важливий поділ — провайдер проти runtime: +Важливий поділ — між провайдером і середовищем виконання: -- `openai-codex/*` відповідає на запитання «який маршрут провайдера/автентифікації має використовувати PI?» -- `agentRuntime.id: "codex"` відповідає на запитання «який цикл має виконувати цей - вбудований хід?» -- `/codex ...` відповідає на запитання «до якої нативної розмови Codex має бути прив’язаний - або якою має керувати цей чат?» -- ACP відповідає на запитання «який зовнішній harness-процес має запустити acpx?» +- `openai-codex/*` відповідає на запитання "який маршрут провайдера/автентифікації має використовувати PI?" +- `agentRuntime.id: "codex"` відповідає на запитання "який цикл має виконати цей + вбудований хід?" +- `/codex ...` відповідає на запитання "яку нативну розмову Codex має прив’язати + або контролювати цей чат?" +- ACP відповідає на запитання "який зовнішній процес середовища має запустити acpx?" ## Виберіть правильний префікс моделі -Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, -коли хочете Codex OAuth через PI; використовуйте `openai/*`, коли хочете прямий -доступ до OpenAI API або коли примушуєте нативний Codex app-server harness: +Маршрути сімейства OpenAI залежать від префікса. Для поширеного налаштування з підпискою плюс +нативним середовищем виконання Codex використовуйте `openai/*` з `agentRuntime.id: "codex"`. +Використовуйте `openai-codex/*` лише тоді, коли навмисно хочете Codex OAuth через PI: -| Посилання на модель | Шлях 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 зі стандартним PI runner. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | Вам потрібне нативне виконання Codex app-server для вбудованого ходу агента. | +| Посилання на модель | Шлях середовища виконання | Коли використовувати | +| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | +| `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` + `agentRuntime.id: "codex"` | Середовище app-server Codex | Потрібна автентифікація підписки ChatGPT/Codex з нативним виконанням Codex. | -GPT-5.5 наразі в OpenClaw доступний лише через підписку/OAuth. Використовуйте -`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` з Codex -app-server harness. Прямий доступ через API-ключ для `openai/gpt-5.5` -підтримується після того, як OpenAI увімкне GPT-5.5 у публічному API. +GPT-5.5 може з’являтися і на прямих маршрутах OpenAI API-ключа, і на маршрутах підписки Codex, +коли ваш обліковий запис їх відкриває. Використовуйте `openai/gpt-5.5` із середовищем app-server +Codex для нативного середовища виконання Codex, `openai-codex/gpt-5.5` для PI OAuth або +`openai/gpt-5.5` без перевизначення середовища виконання Codex для прямого трафіку через API-ключ. -Застарілі посилання `codex/gpt-*` і далі приймаються як aliases сумісності. -Сумісна міграція Doctor переписує застарілі основні посилання runtime на -канонічні посилання на моделі й окремо записує політику runtime, тоді як -застарілі посилання лише для fallback залишаються без змін, бо runtime -налаштовується для всього контейнера агента. Нові конфігурації PI Codex OAuth -мають використовувати `openai-codex/gpt-*`; нові конфігурації нативного -app-server harness мають використовувати `openai/gpt-*` плюс +Застарілі посилання `codex/gpt-*` і далі приймаються як сумісні псевдоніми. Міграція сумісності +doctor переписує застарілі посилання на основне середовище виконання в канонічні посилання на модель +і записує політику середовища виконання окремо, тоді як застарілі посилання лише для резерву +залишаються без змін, бо середовище виконання налаштовується для всього контейнера агента. +Нові конфігурації PI Codex OAuth мають використовувати `openai-codex/gpt-*`; нові конфігурації +нативного середовища app-server мають використовувати `openai/gpt-*` плюс `agentRuntime.id: "codex"`. -`agents.defaults.imageModel` дотримується того самого поділу префіксів. -Використовуйте `openai-codex/gpt-*`, коли розуміння зображень має виконуватися -через шлях провайдера OpenAI Codex OAuth. Використовуйте `codex/gpt-*`, коли -розуміння зображень має виконуватися через обмежений хід Codex app-server. -Модель Codex app-server має оголошувати підтримку введення зображень; текстові -моделі Codex завершуються помилкою до початку медіаходу. +`agents.defaults.imageModel` використовує той самий поділ префіксів. Використовуйте +`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI +Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися +через обмежений хід app-server Codex. Модель app-server Codex має +оголошувати підтримку введення зображень; текстові моделі Codex завершуються помилкою до початку +ходу з медіа. -Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. -Якщо вибір неочікуваний, увімкніть debug-логування для підсистеми -`agents/harness` і перегляньте структурований запис gateway `agent harness selected`. -Він містить вибраний ідентифікатор harness, причину вибору, політику runtime/fallback, -а в режимі `auto` — результат підтримки кожного кандидата plugin. +Використовуйте `/status`, щоб підтвердити фактичне середовище для поточної сесії. Якщо вибір +неочікуваний, увімкніть debug-журналювання для підсистеми `agents/harness` +і перегляньте структурований запис Gateway `agent harness selected`. Він +містить вибраний ідентифікатор середовища, причину вибору, політику середовища виконання/резерву та, +у режимі `auto`, результат підтримки кожного кандидата Plugin. ### Що означають попередження doctor `openclaw doctor` попереджає, коли всі ці умови істинні: -- вбудований plugin `codex` увімкнений або дозволений +- пакетний Plugin `codex` увімкнено або дозволено - основна модель агента — `openai-codex/*` -- фактичний runtime цього агента не `codex` +- фактичне середовище виконання цього агента не `codex` -Це попередження існує тому, що користувачі часто очікують, що «увімкнений Codex -plugin» означає «нативний runtime Codex app-server». OpenClaw не робить такого -стрибка. Попередження означає: +Це попередження існує тому, що користувачі часто очікують, що "Plugin Codex увімкнено" означає +"нативне середовище виконання app-server Codex." OpenClaw не робить такого переходу. Попередження +означає: -- **Зміни не потрібні**, якщо ви мали на увазі ChatGPT/Codex OAuth через PI. -- Змініть модель на `openai/` і задайте +- **Жодних змін не потрібно**, якщо ви мали на увазі ChatGPT/Codex OAuth через PI. +- Змініть модель на `openai/` і встановіть `agentRuntime.id: "codex"`, якщо ви мали на увазі нативне виконання app-server. -- Наявним сесіям усе ще потрібні `/new` або `/reset` після зміни runtime, - бо прив’язки runtime сесій липкі. +- Наявним сесіям після зміни середовища виконання все одно потрібні `/new` або `/reset`, + бо прив’язки середовища виконання сесій липкі. -Вибір harness не є керуванням живою сесією. Коли виконується вбудований хід, -OpenClaw записує вибраний ідентифікатор harness у цій сесії й продовжує -використовувати його для подальших ходів у тому самому ідентифікаторі сесії. -Змініть конфігурацію `agentRuntime` або `OPENCLAW_AGENT_RUNTIME`, коли хочете, -щоб майбутні сесії використовували інший harness; використовуйте `/new` або -`/reset`, щоб почати свіжу сесію перед перемиканням наявної розмови між PI і -Codex. Це запобігає повторному програванню одного транскрипту через дві -несумісні нативні системи сесій. +Вибір середовища не є живим керуванням сесією. Коли виконується вбудований хід, +OpenClaw записує ідентифікатор вибраного середовища на цю сесію і продовжує використовувати його для +подальших ходів у тій самій сесії. Змініть конфігурацію `agentRuntime` або +`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інше середовище; +використовуйте `/new` або `/reset`, щоб почати свіжу сесію перед перемиканням наявної +розмови між PI і Codex. Це запобігає повторному відтворенню одного транскрипту через +дві несумісні нативні системи сесій. -Застарілі сесії, створені до появи прив’язок harness, вважаються прив’язаними -до PI після того, як у них з’являється історія транскрипту. Використовуйте -`/new` або `/reset`, щоб після зміни конфігурації перевести цю розмову на Codex. +Застарілі сесії, створені до появи прив’язок середовищ, вважаються прив’язаними до PI, щойно вони +мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб включити цю розмову в +Codex після зміни конфігурації. -`/status` показує фактичний runtime моделі. Стандартний PI harness відображається -як `Runtime: OpenClaw Pi Default`, а Codex app-server harness — як +`/status` показує ефективне середовище виконання моделі. Типова обв’язка PI відображається як +`Runtime: OpenClaw Pi Default`, а обв’язка app-server Codex — як `Runtime: OpenAI Codex`. ## Вимоги -- OpenClaw із доступним вбудованим Plugin `codex`. -- Codex app-server `0.125.0` або новіший. Вбудований Plugin типово керує сумісним +- OpenClaw із доступним вбудованим `codex` plugin. +- Codex app-server `0.125.0` або новіший. Вбудований plugin типово керує сумісним бінарним файлом Codex app-server, тому локальні команди `codex` у `PATH` не - впливають на звичайний запуск harness. -- Авторизація Codex доступна процесу app-server або Codex auth - bridge OpenClaw. Локальні запуски app-server використовують керований OpenClaw Codex home для кожного - агента та ізольований дочірній `HOME`, тому типово вони не читають ваш особистий - обліковий запис `~/.codex`, skills, plugins, config, стан thread або нативні - `$HOME/.agents/skills`. + впливають на звичайний запуск обв’язки. +- Авторизація Codex доступна процесу app-server або мосту авторизації Codex в + OpenClaw. Локальні запуски app-server використовують керований OpenClaw дім Codex + для кожного агента й ізольований дочірній `HOME`, тому типово не читають ваш + особистий обліковий запис `~/.codex`, Skills, plugins, конфігурацію, стан + ланцюжків або нативні `$HOME/.agents/skills`. -Plugin блокує старіші або неверсіоновані app-server handshakes. Це утримує -OpenClaw на поверхні протоколу, з якою він був протестований. +Plugin блокує старіші або неверсіоновані рукостискання app-server. Це утримує +OpenClaw на тій поверхні протоколу, проти якої його було протестовано. -Для live і Docker smoke tests авторизація зазвичай надходить з облікового запису Codex CLI -або auth profile OpenClaw `openai-codex`. Локальні запуски stdio app-server також можуть -резервно використовувати `CODEX_API_KEY` / `OPENAI_API_KEY`, коли обліковий запис відсутній. +Для живих і Docker smoke-тестів авторизація зазвичай надходить з облікового запису +Codex CLI або профілю авторизації OpenClaw `openai-codex`. Локальні stdio-запуски +app-server також можуть повертатися до `CODEX_API_KEY` / `OPENAI_API_KEY`, коли +обліковий запис відсутній. -## Додайте Codex поруч з іншими моделями +## Додавання Codex поруч з іншими моделями -Не встановлюйте `agentRuntime.id: "codex"` глобально, якщо той самий агент має вільно перемикатися -між моделями провайдерів Codex і не-Codex. Примусовий runtime застосовується до кожного -вбудованого turn для цього агента або session. Якщо вибрати модель Anthropic, коли -цей runtime примусово задано, OpenClaw все одно спробує Codex harness і завершиться помилкою -замість того, щоб непомітно спрямувати цей turn через PI. +Не задавайте `agentRuntime.id: "codex"` глобально, якщо той самий агент має вільно +перемикатися між моделями Codex і моделями провайдерів не Codex. Примусове середовище +виконання застосовується до кожного вбудованого ходу для цього агента або сеансу. Якщо +ви виберете модель Anthropic, коли це середовище виконання примусове, OpenClaw усе одно +спробує обв’язку Codex і відмовить без прихованого маршрутизування цього ходу через PI. -Натомість використовуйте один із цих варіантів: +Натомість використайте одну з таких форм: -- Розмістіть Codex на окремому агенті з `agentRuntime.id: "codex"`. -- Залиште агент за замовчуванням на `agentRuntime.id: "auto"` і PI fallback для звичайного змішаного +- Винесіть Codex в окремого агента з `agentRuntime.id: "codex"`. +- Залиште типового агента на `agentRuntime.id: "auto"` і fallback до PI для звичайного змішаного використання провайдерів. -- Використовуйте застарілі refs `codex/*` лише для сумісності. Нові configs мають віддавати перевагу - `openai/*` плюс явній політиці Codex runtime. +- Використовуйте застарілі посилання `codex/*` лише для сумісності. Нові конфігурації мають надавати перевагу + `openai/*` плюс явній політиці середовища виконання Codex. -Наприклад, це залишає агент за замовчуванням на звичайному автоматичному виборі та +Наприклад, це залишає типового агента на звичайному автоматичному виборі й додає окремого агента Codex: ```json5 @@ -313,37 +321,37 @@ OpenClaw на поверхні протоколу, з якою він був п } ``` -З такою формою: +З цією формою: -- Агент `main` за замовчуванням використовує звичайний шлях провайдера та PI compatibility fallback. -- Агент `codex` використовує Codex app-server harness. -- Якщо Codex відсутній або не підтримується для агента `codex`, turn завершується помилкою +- Типовий агент `main` використовує звичайний шлях провайдера та fallback сумісності PI. +- Агент `codex` використовує обв’язку Codex app-server. +- Якщо Codex відсутній або не підтримується для агента `codex`, хід завершується помилкою замість тихого використання PI. ## Маршрутизація команд агента Агенти мають маршрутизувати запити користувача за наміром, а не лише за словом "Codex": -| Користувач просить... | Агент має використовувати... | -| -------------------------------------------------------- | ------------------------------------------------ | -| "Прив’язати цей чат до Codex" | `/codex bind` | -| "Відновити thread Codex `` тут" | `/codex resume ` | -| "Показати threads Codex" | `/codex threads` | -| "Подати support report для невдалого запуску Codex" | `/diagnostics [note]` | -| "Надіслати Codex feedback лише для цього вкладеного thread" | `/codex diagnostics [note]` | -| "Використати Codex як runtime для цього агента" | зміна config на `agentRuntime.id` | -| "Використати мою підписку ChatGPT/Codex зі звичайним OpenClaw" | refs моделі `openai-codex/*` | -| "Запустити Codex через ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Запустити Claude Code/Gemini/OpenCode/Cursor у thread" | ACP/acpx, не `/codex` і не нативні sub-agents | +| Користувач просить... | Агент має використати... | +| ------------------------------------------------------ | ------------------------------------------------ | +| "Прив’язати цей чат до Codex" | `/codex bind` | +| "Відновити ланцюжок Codex `` тут" | `/codex resume ` | +| "Показати ланцюжки Codex" | `/codex threads` | +| "Створити звіт підтримки про невдалий запуск Codex" | `/diagnostics [note]` | +| "Надіслати відгук Codex лише для цього вкладеного ланцюжка" | `/codex diagnostics [note]` | +| "Використати мою підписку ChatGPT/Codex із середовищем виконання Codex" | `openai/*` плюс `agentRuntime.id: "codex"` | +| "Використати мою підписку ChatGPT/Codex через PI" | посилання моделей `openai-codex/*` | +| "Запустити Codex через ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | +| "Запустити Claude Code/Gemini/OpenCode/Cursor у ланцюжку" | ACP/acpx, а не `/codex` і не нативні субагенти | -OpenClaw показує агентам рекомендації ACP spawn лише тоді, коли ACP увімкнено, -доступний для dispatch і підтриманий завантаженим runtime backend. Якщо ACP недоступний, -system prompt і plugin skills не мають навчати агента маршрутизації ACP. +OpenClaw рекламує агентам підказки запуску ACP лише тоді, коли ACP увімкнено, +доступний для диспетчеризації та підкріплений завантаженим бекендом середовища виконання. Якщо ACP недоступний, +системний prompt і plugin Skills не мають навчати агента маршрутизації ACP. ## Розгортання лише з Codex -Примусово використовуйте Codex harness, коли потрібно довести, що кожен вбудований turn агента -використовує Codex. Явні plugin runtimes типово не мають PI fallback, тому +Примусово використовуйте обв’язку Codex, коли потрібно довести, що кожен вбудований хід агента +використовує Codex. Явні середовища виконання plugin типово не мають fallback до PI, тому `fallback: "none"` необов’язковий, але часто корисний як документація: ```json5 @@ -360,20 +368,20 @@ system prompt і plugin skills не мають навчати агента ма } ``` -Перевизначення середовища: +Перевизначення через середовище: ```bash OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Коли Codex примусово задано, OpenClaw рано завершується помилкою, якщо Codex plugin вимкнено, -app-server занадто старий або app-server не може запуститися. Встановлюйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв -відсутній вибір harness. +Коли Codex примусово ввімкнено, OpenClaw рано завершується помилкою, якщо plugin Codex вимкнено, +app-server занадто старий або app-server не може запуститися. Задавайте +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо навмисно хочете, щоб PI обробляв +відсутній вибір обв’язки. ## Codex для окремого агента -Можна зробити одного агента лише Codex, тоді як агент за замовчуванням збереже звичайний +Ви можете зробити одного агента лише Codex, тоді як типовий агент зберігатиме звичайний автовибір: ```json5 @@ -405,21 +413,21 @@ app-server занадто старий або app-server не може запу } ``` -Використовуйте звичайні session commands, щоб перемикати агентів і моделі. `/new` створює нову -OpenClaw session, а Codex harness створює або відновлює свій sidecar app-server -thread за потреби. `/reset` очищає прив’язку OpenClaw session для цього thread -і дозволяє наступному turn знову визначити harness із поточного config. +Використовуйте звичайні команди сеансу для перемикання агентів і моделей. `/new` створює свіжий +сеанс OpenClaw, а обв’язка Codex створює або відновлює свій допоміжний ланцюжок app-server +за потреби. `/reset` очищає прив’язку сеансу OpenClaw для цього ланцюжка +й дає наступному ходу знову визначити обв’язку з поточної конфігурації. ## Виявлення моделей -Типово Codex plugin запитує в app-server доступні моделі. Якщо -виявлення завершується помилкою або timeout, він використовує вбудований fallback catalog для: +Типово plugin Codex запитує app-server про доступні моделі. Якщо +виявлення завершується помилкою або тайм-аутом, він використовує вбудований fallback-каталог для: - GPT-5.5 - GPT-5.4 mini - GPT-5.2 -Можна налаштувати виявлення в `plugins.entries.codex.config.discovery`: +Ви можете налаштувати виявлення в `plugins.entries.codex.config.discovery`: ```json5 { @@ -439,8 +447,8 @@ thread за потреби. `/reset` очищає прив’язку OpenClaw s } ``` -Вимкніть виявлення, коли хочете, щоб запуск уникав probing Codex і використовував -fallback catalog: +Вимикайте виявлення, коли хочете, щоб запуск не зондував Codex і тримався +fallback-каталогу: ```json5 { @@ -459,26 +467,26 @@ fallback catalog: } ``` -## З’єднання app-server і політика +## Підключення app-server і політика -Типово Plugin запускає керований OpenClaw бінарний файл Codex локально з: +Типово plugin запускає керований OpenClaw бінарний файл Codex локально з: ```bash codex app-server --listen stdio:// ``` -Керований бінарний файл постачається з пакетом Plugin `codex`. Це зберігає -версію app-server прив’язаною до вбудованого Plugin, а не до будь-якого окремого -Codex CLI, який випадково встановлено локально. Встановлюйте `appServer.command` лише тоді, -коли ви навмисно хочете запустити інший executable. +Керований бінарний файл постачається з пакетом plugin `codex`. Це прив’язує версію +app-server до вбудованого plugin, а не до будь-якого окремого Codex CLI, який випадково +встановлено локально. Задавайте `appServer.command` лише тоді, коли навмисно хочете +запустити інший виконуваний файл. -Типово OpenClaw запускає локальні sessions Codex harness у режимі YOLO: +Типово OpenClaw запускає локальні сеанси обв’язки Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і -`sandbox: "danger-full-access"`. Це довірена позиція локального оператора, яку використовують -для автономних heartbeats: Codex може використовувати shell і network tools без -зупинки на нативних approval prompts, на які нікому відповісти. +`sandbox: "danger-full-access"`. Це довірена позиція локального оператора, що використовується +для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без +зупинок на нативних prompt затвердження, на які нікому відповісти. -Щоб увімкнути approvals, перевірені Codex guardian, встановіть `appServer.mode: +Щоб увімкнути затвердження Codex з перевіркою guardian, задайте `appServer.mode: "guardian"`: ```json5 @@ -499,21 +507,21 @@ Codex CLI, який випадково встановлено локально. } ``` -Режим Guardian використовує нативний шлях Codex auto-review approval. Коли Codex просить -вийти за межі sandbox, писати поза workspace або додати permissions на кшталт network -access, Codex маршрутизує цей approval request до нативного reviewer замість -людського prompt. Reviewer застосовує Codex risk framework і схвалює або відхиляє -конкретний request. Використовуйте Guardian, коли потрібні жорсткіші guardrails, ніж у режимі YOLO, -але unattended agents усе ще мають просувати роботу вперед. +Режим Guardian використовує нативний шлях автоогляду затверджень Codex. Коли Codex просить +вийти з sandbox, записати поза workspace або додати дозволи на кшталт мережевого +доступу, Codex маршрутизує цей запит затвердження до нативного reviewer замість +людського prompt. Reviewer застосовує рамку оцінки ризиків Codex і затверджує або відхиляє +конкретний запит. Використовуйте Guardian, коли хочете більше запобіжників, ніж у режимі YOLO, +але все одно потребуєте, щоб агенти без нагляду просувалися вперед. -Preset `guardian` розгортається в `approvalPolicy: "on-request"`, +Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` і `sandbox: "workspace-write"`. -Окремі policy fields усе ще перевизначають `mode`, тому advanced deployments можуть поєднувати -preset з явними choices. Старіше значення reviewer `guardian_subagent` -досі приймається як compatibility alias, але нові configs мають використовувати +Окремі поля політики все ще перевизначають `mode`, тому розширені розгортання можуть поєднувати +пресет з явними виборами. Старіше значення reviewer `guardian_subagent` +досі приймається як псевдонім сумісності, але нові конфігурації мають використовувати `auto_review`. -Для app-server, який уже запущено, використовуйте WebSocket transport: +Для вже запущеного app-server використовуйте транспорт WebSocket: ```json5 { @@ -535,17 +543,17 @@ preset з явними choices. Старіше значення reviewer `guardi } ``` -Запуски stdio app-server типово успадковують process environment OpenClaw, -але OpenClaw володіє account bridge Codex app-server і встановлює і -`CODEX_HOME`, і `HOME` у per-agent directories під state OpenClaw цього агента. -Власний skill loader Codex читає `$CODEX_HOME/skills` і +Stdio-запуски app-server типово успадковують процесне середовище OpenClaw, +але OpenClaw володіє мостом облікового запису Codex app-server і задає як +`CODEX_HOME`, так і `HOME` у каталоги кожного агента під станом OpenClaw +цього агента. Власний завантажувач Skills Codex читає `$CODEX_HOME/skills` і `$HOME/.agents/skills`, тому обидва значення ізольовані для локальних запусків app-server. -Це утримує Codex-native skills, plugins, config, accounts і стан thread -у межах агента OpenClaw замість витоку з особистого Codex CLI home оператора. +Це тримає нативні для Codex Skills, plugins, конфігурацію, облікові записи й стан +ланцюжків у межах агента OpenClaw, а не пропускає їх з особистого дому Codex CLI оператора. -OpenClaw plugins і OpenClaw skill snapshots і далі проходять через власний -plugin registry і skill loader OpenClaw. Особисті assets Codex CLI не проходять. Якщо у вас є -корисні skills або plugins Codex CLI, які мають стати частиною агента OpenClaw, +Plugins OpenClaw і знімки Skills OpenClaw усе ще проходять через власний +реєстр plugin і завантажувач Skills OpenClaw. Особисті ресурси Codex CLI не проходять. Якщо у вас є +корисні Skills або plugins Codex CLI, які мають стати частиною агента OpenClaw, явно інвентаризуйте їх: ```bash @@ -553,27 +561,27 @@ openclaw migrate codex --dry-run openclaw migrate apply codex --yes ``` -Codex migration provider копіює skills у поточний workspace агента OpenClaw. -Нативні plugins, hooks і config files Codex повідомляються або архівуються -для ручного перегляду замість автоматичної активації, оскільки вони можуть -виконувати commands, відкривати MCP servers або містити credentials. +Провайдер міграції Codex копіює Skills у поточний workspace агента OpenClaw. +Нативні plugins, hooks і файли конфігурації Codex звітуються або архівуються +для ручного огляду замість автоматичної активації, оскільки вони можуть +виконувати команди, відкривати MCP-сервери або містити облікові дані. -Auth вибирається в такому порядку: +Авторизація вибирається в такому порядку: -1. Явний auth profile OpenClaw Codex для агента. -2. Наявний обліковий запис app-server у Codex home цього агента. -3. Лише для локальних запусків stdio app-server: `CODEX_API_KEY`, потім - `OPENAI_API_KEY`, коли немає облікового запису app-server, а OpenAI auth +1. Явний профіль авторизації OpenClaw Codex для агента. +2. Наявний обліковий запис app-server у домі Codex цього агента. +3. Лише для локальних stdio-запусків app-server: `CODEX_API_KEY`, потім + `OPENAI_API_KEY`, коли обліковий запис app-server відсутній, а авторизація OpenAI усе ще потрібна. -Коли OpenClaw бачить Codex auth profile у стилі підписки ChatGPT, він прибирає +Коли OpenClaw бачить профіль авторизації Codex у стилі підписки ChatGPT, він видаляє `CODEX_API_KEY` і `OPENAI_API_KEY` із породженого дочірнього процесу Codex. Це -залишає Gateway-level API keys доступними для embeddings або прямих моделей OpenAI -без випадкового billing нативних turns Codex app-server через API. -Явні Codex API-key profiles і локальний stdio env-key fallback використовують app-server -login замість inherited child-process env. WebSocket app-server connections -не отримують fallback Gateway env API-key; використовуйте явний auth profile або -власний обліковий запис remote app-server. +залишає API-ключі рівня Gateway доступними для embeddings або прямих моделей OpenAI +без випадкового виставлення рахунку за нативні ходи Codex app-server через API. +Явні профілі API-ключа Codex і локальний stdio fallback через env-key використовують вхід app-server +замість успадкованого env дочірнього процесу. WebSocket-підключення app-server +не отримують fallback API-ключа з env Gateway; використовуйте явний профіль авторизації або +власний обліковий запис віддаленого app-server. Якщо розгортанню потрібна додаткова ізоляція середовища, додайте ці змінні до `appServer.clearEnv`: @@ -597,51 +605,50 @@ login замість inherited child-process env. WebSocket app-server connectio `appServer.clearEnv` впливає лише на породжений дочірній процес Codex app-server. -Codex dynamic tools типово використовують профіль `native-first`. У цьому режимі -OpenClaw не відкриває dynamic tools, що дублюють Codex-native workspace -operations: `read`, `write`, `edit`, `apply_patch`, `exec`, `process` і -`update_plan`. OpenClaw integration tools, як-от messaging, sessions, media, -cron, browser, nodes, gateway, `heartbeat_respond` і `web_search`, залишаються +Динамічні інструменти Codex типово використовують профіль `native-first`. У цьому режимі +OpenClaw не відкриває динамічні інструменти, які дублюють нативні для Codex операції +workspace: `read`, `write`, `edit`, `apply_patch`, `exec`, `process` і +`update_plan`. Інтеграційні інструменти OpenClaw, як-от messaging, sessions, media, +cron, browser, nodes, Gateway, `heartbeat_respond` і `web_search`, залишаються доступними. -Підтримувані top-level поля Codex plugin: +Підтримувані поля верхнього рівня Plugin Codex: -| Поле | За замовчуванням | Значення | -| -------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- | -| `codexDynamicToolsProfile` | `"native-first"` | Використовуйте `"openclaw-compat"`, щоб надати Codex app-server повний набір динамічних інструментів OpenClaw. | -| `codexDynamicToolsExclude` | `[]` | Додаткові назви динамічних інструментів OpenClaw, які треба пропускати в зверненнях Codex app-server. | +| Поле | Типове значення | Значення | +| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------ | +| `codexDynamicToolsProfile` | `"native-first"` | Використовуйте `"openclaw-compat"`, щоб надати app-server Codex повний набір динамічних інструментів OpenClaw. | +| `codexDynamicToolsExclude` | `[]` | Додаткові назви динамічних інструментів OpenClaw, які треба пропускати під час ходів app-server Codex. | Підтримувані поля `appServer`: -| Поле | За замовчуванням | Значення | -| ------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | керований бінарний файл Codex | Виконуваний файл для транспорту stdio. Не задавайте, щоб використовувати керований бінарний файл; задавайте лише для явного перевизначення. | -| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не задано | URL WebSocket app-server. | -| `authToken` | не задано | Bearer-токен для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `clearEnv` | `[]` | Додаткові назви змінних середовища, які видаляються із запущеного процесу stdio app-server після того, як OpenClaw побудує успадковане середовище. `CODEX_HOME` і `HOME` зарезервовані для ізоляції Codex на кожного агента OpenClaw під час локальних запусків. | -| `requestTimeoutMs` | `60000` | Тайм-аут для викликів площини керування app-server. | -| `mode` | `"yolo"` | Пресет для YOLO або виконання з перевіркою guardian. | -| `approvalPolicy` | `"never"` | Нативна політика підтверджень Codex, яку надсилають під час start/resume/turn потоку. | -| `sandbox` | `"danger-full-access"` | Нативний режим пісочниці Codex, який надсилають під час start/resume потоку. | -| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex переглядати нативні запити підтвердження. `guardian_subagent` залишається застарілим псевдонімом. | -| `serviceTier` | не задано | Необов’язковий рівень сервісу Codex app-server: `"fast"`, `"flex"` або `null`. Недійсні застарілі значення ігноруються. | +| Поле | Типове значення | Значення | +| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | керований бінарний файл Codex | Виконуваний файл для транспорту stdio. Залиште незаданим, щоб використовувати керований бінарний файл; задавайте лише для явного перевизначення. | +| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | +| `url` | не задано | URL WebSocket app-server. | +| `authToken` | не задано | Bearer-токен для транспорту WebSocket. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `clearEnv` | `[]` | Додаткові назви змінних середовища, які видаляються із запущеного процесу stdio app-server після того, як OpenClaw побудує успадковане середовище. `CODEX_HOME` і `HOME` зарезервовані для ізоляції Codex для кожного агента OpenClaw під час локальних запусків. | +| `requestTimeoutMs` | `60000` | Тайм-аут для викликів площини керування app-server. | +| `mode` | `"yolo"` | Набір налаштувань для виконання YOLO або виконання з переглядом guardian. | +| `approvalPolicy` | `"never"` | Власна політика затверджень Codex, що надсилається під час старту/відновлення/ходу треду. | +| `sandbox` | `"danger-full-access"` | Власний режим пісочниці Codex, що надсилається під час старту/відновлення треду. | +| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex переглядати власні запити на затвердження. `guardian_subagent` залишається застарілим псевдонімом. | +| `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Недійсні застарілі значення ігноруються. | Виклики динамічних інструментів, якими володіє OpenClaw, обмежуються незалежно від `appServer.requestTimeoutMs`: кожен запит Codex `item/tool/call` має отримати відповідь OpenClaw протягом 30 секунд. У разі тайм-ауту OpenClaw перериває сигнал -інструмента там, де це підтримується, і повертає Codex невдалу відповідь -динамічного інструмента, щоб звернення могло продовжитися, а не залишало сесію в -`processing`. +інструмента там, де це підтримується, і повертає Codex відповідь динамічного інструмента з помилкою, щоб +хід міг продовжитися замість того, щоб залишити сеанс у стані `processing`. -Після того як OpenClaw відповідає на запит app-server у межах звернення Codex, -обв’язка також очікує, що Codex завершить нативне звернення через -`turn/completed`. Якщо app-server мовчить 60 секунд після цієї відповіді, -OpenClaw докладає зусиль, щоб перервати звернення Codex, записує діагностичний -тайм-аут і звільняє смугу сесії OpenClaw, щоб наступні повідомлення чату не -ставали в чергу за застарілим нативним зверненням. +Після того як OpenClaw відповідає на запит app-server Codex у межах ходу, harness +також очікує, що Codex завершить власний хід через `turn/completed`. Якщо +app-server не подає ознак активності протягом 60 секунд після цієї відповіді, OpenClaw у режимі best-effort +перериває хід Codex, записує діагностичний тайм-аут і звільняє +смугу сеансу OpenClaw, щоб наступні повідомлення чату не ставали в чергу за застарілим +власним ходом. Перевизначення середовища залишаються доступними для локального тестування: @@ -654,28 +661,26 @@ OpenClaw докладає зусиль, щоб перервати звернен `OPENCLAW_CODEX_APP_SERVER_BIN` обходить керований бінарний файл, коли `appServer.command` не задано. -`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 у тому самому перевіреному файлі, що й -решту налаштування обв’язки Codex. +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для одноразового локального тестування. Конфігурація +бажаніша для повторюваних розгортань, бо вона тримає поведінку Plugin у тому самому +переглянутому файлі, що й решта налаштування harness Codex. ## Використання комп’ютера Використання комп’ютера описано в окремому посібнику з налаштування: [Використання комп’ютера Codex](/uk/plugins/codex-computer-use). -Коротко: OpenClaw не постачає вендоризований застосунок керування робочим столом -і не виконує дії на робочому столі самостійно. Він готує Codex app-server, -перевіряє, що MCP-сервер `computer-use` доступний, а потім дозволяє Codex -обробляти нативні виклики інструментів MCP під час звернень у режимі Codex. +Коротко: OpenClaw не постачає застосунок керування робочим столом і не виконує +дії на робочому столі самостійно. Він готує app-server Codex, перевіряє, що +MCP-сервер `computer-use` доступний, а потім дозволяє Codex обробляти власні +виклики інструментів MCP під час ходів у режимі Codex. -Для прямого доступу до драйвера TryCua поза потоком marketplace Codex -зареєструйте `cua-driver mcp` через `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. -Див. [Використання комп’ютера Codex](/uk/plugins/codex-computer-use), щоб -зрозуміти різницю між використанням комп’ютера, яким володіє Codex, і прямою -реєстрацією MCP. +Для прямого доступу до драйвера TryCua поза потоком маркетплейсу Codex зареєструйте +`cua-driver mcp` за допомогою `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. +Див. [Використання комп’ютера Codex](/uk/plugins/codex-computer-use), щоб зрозуміти різницю +між використанням комп’ютера під керуванням Codex і прямою реєстрацією MCP. Мінімальна конфігурація: @@ -712,25 +717,23 @@ OpenClaw докладає зусиль, щоб перервати звернен - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -Використання комп’ютера є специфічним для macOS і може потребувати локальних -дозволів ОС, перш ніж MCP-сервер Codex зможе керувати застосунками. Якщо -`computerUse.enabled` має значення true, а MCP-сервер недоступний, звернення в -режимі Codex завершується помилкою до запуску потоку, замість того щоб тихо -працювати без нативних інструментів використання комп’ютера. Див. -[Використання комп’ютера Codex](/uk/plugins/codex-computer-use) щодо варіантів -marketplace, обмежень віддаленого каталогу, причин статусу й усунення -несправностей. +Використання комп’ютера специфічне для macOS і може вимагати локальних дозволів ОС, перш ніж +MCP-сервер Codex зможе керувати застосунками. Якщо `computerUse.enabled` має значення true, а MCP +сервер недоступний, ходи в режимі Codex завершуються помилкою до старту треду замість того, +щоб непомітно виконуватися без власних інструментів використання комп’ютера. Див. +[Використання комп’ютера Codex](/uk/plugins/codex-computer-use) щодо варіантів маркетплейсу, +обмежень віддаленого каталогу, причин статусу та усунення несправностей. -Коли `computerUse.autoInstall` має значення true, OpenClaw може зареєструвати -стандартний комплектний marketplace Codex Desktop з +Коли `computerUse.autoInstall` має значення true, OpenClaw може зареєструвати стандартний +вбудований маркетплейс Codex Desktop з `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`, якщо Codex -ще не виявив локальний marketplace. Використовуйте `/new` або `/reset` після -зміни runtime чи конфігурації використання комп’ютера, щоб наявні сесії не -зберігали стару прив’язку PI або потоку Codex. +ще не виявив локальний маркетплейс. Використовуйте `/new` або `/reset` після +зміни конфігурації runtime або використання комп’ютера, щоб наявні сеанси не зберігали стару +прив’язку PI або треду Codex. ## Поширені рецепти -Локальний Codex із транспортом stdio за замовчуванням: +Локальний Codex із типовим транспортом stdio: ```json5 { @@ -744,7 +747,7 @@ marketplace, обмежень віддаленого каталогу, прич } ``` -Перевірка обв’язки лише для Codex: +Валідація harness лише для Codex: ```json5 { @@ -766,7 +769,7 @@ marketplace, обмежень віддаленого каталогу, прич } ``` -Підтвердження Codex із перевіркою guardian: +Затвердження Codex із переглядом guardian: ```json5 { @@ -811,97 +814,95 @@ marketplace, обмежень віддаленого каталогу, прич } ``` -Перемикання моделей залишається під керуванням OpenClaw. Коли сесію OpenClaw -приєднано до наявного потоку Codex, наступне звернення знову надсилає до -app-server поточну вибрану модель OpenAI, провайдера, політику підтверджень, -пісочницю та рівень сервісу. Перемикання з `openai/gpt-5.5` на -`openai/gpt-5.2` зберігає прив’язку потоку, але просить Codex продовжити з -новою вибраною моделлю. +Перемикання моделей залишається під контролем OpenClaw. Коли сеанс OpenClaw приєднано +до наявного треду Codex, наступний хід знову надсилає поточно вибрану +модель OpenAI, провайдера, політику затверджень, пісочницю та рівень сервісу до +app-server. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає +прив’язку треду, але просить Codex продовжити з новообраною моделлю. ## Команда Codex -Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є -узагальненою та працює в будь-якому каналі, який підтримує текстові команди -OpenClaw. +Вбудований Plugin реєструє `/codex` як авторизовану slash-команду. Вона +універсальна й працює в будь-якому каналі, що підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує поточне підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills. -- `/codex models` перелічує поточні моделі Codex app-server. -- `/codex threads [filter]` перелічує нещодавні потоки Codex. -- `/codex resume ` приєднує поточну сесію OpenClaw до наявного потоку Codex. -- `/codex compact` просить Codex app-server ущільнити приєднаний потік. -- `/codex review` запускає нативний review Codex для приєднаного потоку. -- `/codex diagnostics [note]` запитує перед надсиланням діагностичного відгуку Codex для приєднаного потоку. +- `/codex status` показує поточне підключення до app-server, моделі, обліковий запис, ліміти запитів, MCP-сервери та Skills. +- `/codex models` перелічує поточні моделі app-server Codex. +- `/codex threads [filter]` перелічує нещодавні треди Codex. +- `/codex resume ` приєднує поточний сеанс OpenClaw до наявного треду Codex. +- `/codex compact` просить app-server Codex стиснути приєднаний тред. +- `/codex review` запускає власний перегляд Codex для приєднаного треду. +- `/codex diagnostics [note]` запитує перед надсиланням діагностичного відгуку Codex для приєднаного треду. - `/codex computer-use status` перевіряє налаштований Plugin використання комп’ютера та MCP-сервер. - `/codex computer-use install` встановлює налаштований Plugin використання комп’ютера та перезавантажує MCP-сервери. -- `/codex account` показує статус облікового запису та лімітів швидкості. -- `/codex mcp` перелічує статус MCP-серверів Codex app-server. -- `/codex skills` перелічує skills Codex app-server. +- `/codex account` показує стан облікового запису та лімітів запитів. +- `/codex mcp` перелічує стан MCP-серверів app-server Codex. +- `/codex skills` перелічує skills app-server Codex. ### Поширений робочий процес налагодження -Коли агент на основі Codex робить щось неочікуване в Telegram, Discord, Slack -або іншому каналі, почніть із розмови, де сталася проблема: +Коли агент на базі Codex робить щось несподіване в Telegram, Discord, Slack +або іншому каналі, почніть із розмови, у якій сталася проблема: 1. Запустіть `/diagnostics bad tool choice after image upload` або іншу коротку нотатку, яка описує побачене. -2. Один раз схваліть запит діагностики. Схвалення створює локальний zip-файл - діагностики Gateway і, оскільки сеанс використовує середовище Codex, також +2. Один раз схваліть запит діагностики. Схвалення створює локальний zip-архів + діагностики Gateway і, оскільки сеанс використовує обв’язку Codex, також надсилає відповідний пакет відгуку Codex на сервери OpenAI. 3. Скопіюйте завершену відповідь діагностики у звіт про помилку або гілку - підтримки. Вона містить шлях до локального пакета, зведення про приватність, - ідентифікатори сеансів OpenClaw, ідентифікатори гілок Codex і рядок - `Inspect locally` для кожної гілки Codex. + підтримки. Вона містить локальний шлях до пакета, підсумок приватності, + ідентифікатори сеансів OpenClaw, ідентифікатори потоків Codex і рядок + `Inspect locally` для кожного потоку Codex. 4. Якщо ви хочете самостійно налагодити запуск, виконайте надруковану команду `Inspect locally` у терміналі. Вона має вигляд `codex resume ` і - відкриває нативну гілку Codex, щоб ви могли переглянути розмову, продовжити її - локально або запитати Codex, чому він вибрав певний інструмент чи план. + відкриває нативний потік Codex, щоб ви могли переглянути розмову, продовжити + її локально або запитати Codex, чому він вибрав певний інструмент чи план. Використовуйте `/codex diagnostics [note]` лише тоді, коли вам потрібне саме -завантаження відгуку Codex для поточної приєднаної гілки без повного пакета +завантаження відгуку Codex для поточного приєднаного потоку без повного пакета діагностики OpenClaw Gateway. Для більшості звітів підтримки `/diagnostics [note]` -є кращою початковою точкою, бо він пов'язує локальний стан Gateway і -ідентифікатори гілок Codex в одній відповіді. Див. [Експорт діагностики](/uk/gateway/diagnostics) -для повної моделі приватності та поведінки в груповому чаті. +є кращою відправною точкою, оскільки пов’язує локальний стан Gateway та +ідентифікатори потоків Codex в одній відповіді. Див. [Експорт діагностики](/uk/gateway/diagnostics) +для повної моделі приватності та поведінки в групових чатах. -Ядро OpenClaw також надає доступну лише власнику команду `/diagnostics [note]` -як загальну команду діагностики Gateway. Її запит схвалення показує вступ про -чутливі дані, посилається на [Експорт діагностики](/uk/gateway/diagnostics) і щоразу +Ядро OpenClaw також надає команду лише для власників `/diagnostics [note]` як +загальну команду діагностики Gateway. Її запит на схвалення показує преамбулу +про чутливі дані, посилається на [Експорт діагностики](/uk/gateway/diagnostics) і щоразу запитує `openclaw gateway diagnostics export --json` через явне схвалення exec. Не схвалюйте діагностику правилом allow-all. Після схвалення OpenClaw надсилає -звіт, який можна вставити, зі шляхом до локального пакета та зведенням -маніфесту. Коли активний сеанс OpenClaw використовує середовище Codex, те саме -схвалення також дозволяє надсилання відповідних пакетів відгуку Codex на -сервери OpenAI. Запит схвалення повідомляє, що відгук Codex буде надіслано, але -не перелічує ідентифікатори сеансів або гілок Codex до схвалення. +звіт, який можна вставити, з локальним шляхом до пакета та підсумком маніфесту. +Коли активний сеанс OpenClaw використовує обв’язку Codex, те саме схвалення також +дозволяє надсилати відповідні пакети відгуку Codex на сервери OpenAI. Запит на +схвалення повідомляє, що відгук Codex буде надіслано, але не перелічує +ідентифікатори сеансу або потоку Codex до схвалення. Якщо `/diagnostics` викликає власник у груповому чаті, OpenClaw зберігає спільний -канал чистим: група отримує лише коротке сповіщення, тоді як вступ діагностики, -запити схвалення та ідентифікатори сеансів/гілок Codex надсилаються власнику -через приватний маршрут схвалення. Якщо приватного маршруту власника немає, -OpenClaw відхиляє груповий запит і просить власника запустити його з DM. +канал чистим: група отримує лише коротке повідомлення, тоді як преамбула +діагностики, запити на схвалення та ідентифікатори сеансу/потоку Codex +надсилаються власнику через приватний маршрут схвалення. Якщо приватного маршруту +до власника немає, OpenClaw відхиляє груповий запит і просить власника запустити +його з DM. -Схвалене завантаження Codex викликає `feedback/upload` сервера застосунку Codex -і просить сервер застосунку включити журнали для кожної переліченої гілки та -створених підгілок Codex, коли вони доступні. Завантаження проходить звичайним -шляхом відгуку Codex на сервери OpenAI; якщо відгук Codex вимкнено на цьому -сервері застосунку, команда повертає помилку сервера застосунку. Завершена -відповідь діагностики перелічує канали, ідентифікатори сеансів OpenClaw, -ідентифікатори гілок Codex і локальні команди `codex resume ` для -надісланих гілок. Якщо ви відхилите або проігноруєте схвалення, OpenClaw не -виведе ці ідентифікатори Codex. Це завантаження не замінює локальний експорт -діагностики Gateway. +Схвалене завантаження Codex викликає app-server Codex `feedback/upload` і просить +app-server включити журнали для кожного переліченого потоку та породжених +підпотоків Codex, коли вони доступні. Завантаження проходить звичайним шляхом +відгуку Codex до серверів OpenAI; якщо відгук Codex вимкнено в цьому app-server, +команда повертає помилку app-server. Завершена відповідь діагностики перелічує +канали, ідентифікатори сеансів OpenClaw, ідентифікатори потоків Codex і локальні +команди `codex resume ` для надісланих потоків. Якщо ви відхилите або +проігноруєте схвалення, OpenClaw не надрукує ці ідентифікатори Codex. Це +завантаження не замінює локальний експорт діагностики Gateway. -`/codex resume` записує той самий бічний файл прив'язки, який середовище +`/codex resume` записує той самий sidecar-файл прив’язки, який обв’язка використовує для звичайних ходів. У наступному повідомленні OpenClaw відновлює -цю гілку Codex, передає поточно вибрану модель OpenClaw на сервер застосунку та -залишає розширену історію ввімкненою. +цей потік Codex, передає поточно вибрану модель OpenClaw в app-server і залишає +розширену історію ввімкненою. -### Перегляд гілки Codex із CLI +### Перегляд потоку Codex з CLI -Найшвидший спосіб зрозуміти невдалий запуск Codex часто полягає у прямому -відкритті нативної гілки Codex: +Найшвидший спосіб зрозуміти невдалий запуск Codex часто полягає в тому, щоб +відкрити нативний потік Codex напряму: ```sh codex resume @@ -909,181 +910,181 @@ codex resume Використовуйте це, коли помічаєте помилку в розмові каналу й хочете переглянути проблемний сеанс Codex, продовжити його локально або запитати Codex, чому він -зробив певний вибір інструмента чи міркування. Найпростіший шлях зазвичай - -спочатку запустити `/diagnostics [note]`: після схвалення завершений звіт -перелічує кожну гілку Codex і друкує команду `Inspect locally`, наприклад +зробив певний вибір інструмента чи міркування. Найпростіший шлях зазвичай — +спершу запустити `/diagnostics [note]`: після схвалення завершений звіт перелічує +кожен потік Codex і друкує команду `Inspect locally`, наприклад `codex resume `. Ви можете скопіювати цю команду безпосередньо в термінал. -Також можна отримати ідентифікатор гілки з `/codex binding` для поточного чату -або `/codex threads [filter]` для нещодавніх гілок сервера застосунку Codex, а -потім виконати ту саму команду `codex resume` у вашій оболонці. +Ви також можете отримати ідентифікатор потоку з `/codex binding` для поточного +чату або `/codex threads [filter]` для нещодавніх потоків app-server Codex, а +потім виконати ту саму команду `codex resume` у своїй оболонці. -Поверхня команд потребує сервера застосунку Codex `0.125.0` або новішого. -Окремі методи керування повідомляються як `unsupported by this Codex app-server`, -якщо майбутній або власний сервер застосунку не надає цей метод JSON-RPC. +Поверхня команд потребує app-server Codex `0.125.0` або новішого. Окремі методи +керування повідомляються як `unsupported by this Codex app-server`, якщо +майбутній або кастомний app-server не надає цей метод JSON-RPC. ## Межі хуків -Середовище Codex має три рівні хуків: +Обв’язка Codex має три рівні хуків: | Рівень | Власник | Призначення | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------ | -| Хуки плагінів OpenClaw | OpenClaw | Сумісність продукту/плагіна між середовищами PI та Codex. | -| Middleware розширень сервера застосунку Codex | Пакетні плагіни OpenClaw | Поведінка адаптера на кожному ході навколо динамічних інструментів OpenClaw. | -| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | +| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між обв’язками PI та Codex. | +| Middleware розширень app-server Codex | Вбудовані Plugin OpenClaw | Поведінка адаптера для кожного ходу навколо динамічних інструментів OpenClaw. | +| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і нативна політика інструментів з конфігурації Codex. | OpenClaw не використовує проєктні або глобальні файли Codex `hooks.json` для -маршрутизації поведінки плагінів OpenClaw. Для підтримуваного моста нативних -інструментів і дозволів OpenClaw впроваджує конфігурацію Codex для кожної гілки -для `PreToolUse`, `PostToolUse`, `PermissionRequest` і `Stop`. Інші хуки Codex, -як-от `SessionStart` і `UserPromptSubmit`, залишаються засобами керування рівня -Codex; вони не надаються як хуки плагінів OpenClaw у контракті v1. +маршрутизації поведінки Plugin OpenClaw. Для підтримуваного мосту нативних +інструментів і дозволів OpenClaw впроваджує конфігурацію Codex для кожного +потоку для `PreToolUse`, `PostToolUse`, `PermissionRequest` і `Stop`. Інші хуки +Codex, як-от `SessionStart` і `UserPromptSubmit`, залишаються засобами керування +рівня Codex; вони не надаються як хуки Plugin OpenClaw у контракті v1. Для динамічних інструментів OpenClaw OpenClaw виконує інструмент після того, як -Codex запитує виклик, тож OpenClaw запускає поведінку плагіна й middleware, якою -володіє, в адаптері середовища. Для нативних інструментів Codex канонічним -записом інструмента володіє Codex. OpenClaw може віддзеркалювати вибрані події, -але не може переписати нативну гілку Codex, якщо Codex не надає цю операцію -через сервер застосунку або callback-и нативних хуків. +Codex запитує виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою +він володіє в адаптері обв’язки. Для нативних інструментів Codex саме Codex +володіє канонічним записом інструмента. OpenClaw може віддзеркалювати вибрані +події, але не може переписати нативний потік Codex, якщо Codex не надає цю +операцію через app-server або зворотні виклики нативних хуків. -Проєкції Compaction і життєвого циклу LLM надходять зі сповіщень сервера -застосунку Codex і стану адаптера OpenClaw, а не з команд нативних хуків Codex. -Події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і -`llm_output` є спостереженнями рівня адаптера, а не побайтовими знімками -внутрішнього запиту Codex або корисних даних Compaction. +Проєкції Compaction і життєвого циклу LLM надходять зі сповіщень app-server Codex +і стану адаптера OpenClaw, а не з команд нативних хуків Codex. Події OpenClaw +`before_compaction`, `after_compaction`, `llm_input` і `llm_output` є +спостереженнями рівня адаптера, а не побайтовими знімками внутрішнього запиту +Codex або корисного навантаження Compaction. -Нативні сповіщення сервера застосунку Codex `hook/started` і `hook/completed` +Нативні сповіщення app-server Codex `hook/started` і `hook/completed` проєктуються як події агента `codex_app_server.hook` для траєкторії та -налагодження. Вони не викликають хуки плагінів OpenClaw. +налагодження. Вони не викликають хуки Plugin OpenClaw. ## Контракт підтримки V1 -Режим Codex - це не PI з іншим викликом моделі під ним. Codex володіє більшою -частиною нативного циклу моделі, а OpenClaw адаптує свої поверхні плагінів і +Режим Codex — це не PI з іншим викликом моделі під капотом. Codex володіє більшою +частиною нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сеансів навколо цієї межі. -Підтримується в середовищі виконання Codex v1: +Підтримується в runtime Codex v1: | Поверхня | Підтримка | Чому | | --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Цикл моделі OpenAI через Codex | Підтримується | Сервер застосунку Codex володіє ходом OpenAI, відновленням нативної гілки та продовженням нативних інструментів. | -| Маршрутизація й доставлення каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза середовищем виконання моделі. | -| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тож OpenClaw залишається на шляху виконання. | -| Плагіни промптів і контексту | Підтримується | OpenClaw будує накладки промптів і проєктує контекст у хід Codex перед запуском або відновленням гілки. | -| Життєвий цикл рушія контексту | Підтримується | Збирання, приймання або обслуговування після ходу, а також координація Compaction рушія контексту виконуються для ходів Codex. | -| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів виконуються навколо динамічних інструментів, якими володіє OpenClaw. | -| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із чесними корисними даними режиму Codex. | -| Шлюз перегляду фінальної відповіді | Підтримується через ретрансляцію нативних хуків | Codex `Stop` ретранслюється до `before_agent_finalize`; `revise` просить Codex виконати ще один прохід моделі перед фіналізацією. | -| Блокування або спостереження нативної оболонки, патчів і MCP | Підтримується через ретрансляцію нативних хуків | Codex `PreToolUse` і `PostToolUse` ретранслюються для зафіксованих поверхонь нативних інструментів, включно з корисними даними MCP на сервері застосунку Codex `0.125.0` або новішому. Блокування підтримується; переписування аргументів - ні. | -| Політика нативних дозволів | Підтримується через ретрансляцію нативних хуків | Codex `PermissionRequest` може маршрутизуватися через політику OpenClaw там, де середовище виконання це надає. Якщо OpenClaw не повертає рішення, Codex продовжує через звичайний guardian або шлях схвалення користувачем. | -| Захоплення траєкторії сервера застосунку | Підтримується | OpenClaw записує запит, який він надіслав на сервер застосунку, і сповіщення сервера застосунку, які отримує. | +| Цикл моделі OpenAI через Codex | Підтримується | app-server Codex володіє ходом OpenAI, відновленням нативного потоку та продовженням нативного інструмента. | +| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза runtime моделі. | +| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тому OpenClaw залишається на шляху виконання. | +| Plugin підказок і контексту | Підтримується | OpenClaw будує накладки підказок і проєктує контекст у хід Codex перед запуском або відновленням потоку. | +| Життєвий цикл рушія контексту | Підтримується | Збирання, внесення або обслуговування після ходу та координація Compaction рушія контексту виконуються для ходів Codex. | +| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів виконуються навколо динамічних інструментів, якими володіє OpenClaw. | +| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із чесними корисними навантаженнями режиму Codex. | +| Шлюз ревізії фінальної відповіді | Підтримується через нативний ретранслятор хуків | Codex `Stop` ретранслюється до `before_agent_finalize`; `revise` просить Codex виконати ще один прохід моделі перед фіналізацією. | +| Блокування або спостереження нативних shell, patch і MCP | Підтримується через нативний ретранслятор хуків | Codex `PreToolUse` і `PostToolUse` ретранслюються для зафіксованих поверхонь нативних інструментів, включно з корисними навантаженнями MCP на app-server Codex `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. | +| Нативна політика дозволів | Підтримується через нативний ретранслятор хуків | Codex `PermissionRequest` може маршрутизуватися через політику OpenClaw там, де runtime це надає. Якщо OpenClaw не повертає рішення, Codex продовжує через свій звичайний шлях guardian або схвалення користувача. | +| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який надіслав до app-server, і сповіщення app-server, які отримує. | -Не підтримується в середовищі виконання Codex v1: +Не підтримується в runtime Codex v1: -| Поверхня | Межа V1 | Майбутній шлях | +| Поверхня | Межа V1 | Майбутній шлях | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| Зміна аргументів нативного інструмента | Нативні передінструментальні хуки Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потребує підтримки хуків/схем Codex для заміни вхідних даних інструмента. | -| Редагована нативна історія транскрипту Codex | Codex володіє канонічною нативною історією потоку. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не повинен змінювати непідтримувані внутрішні структури. | Додати явні API сервера застосунку Codex, якщо потрібне хірургічне редагування нативного потоку. | -| `tool_result_persist` для записів нативних інструментів Codex | Цей хук трансформує записи транскрипту, що належать OpenClaw, а не записи нативних інструментів Codex. | Можна дзеркалити трансформовані записи, але канонічне переписування потребує підтримки Codex. | -| Багаті нативні метадані Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільного списку збереженого/відкинутого, дельти токенів або корисного навантаження підсумку. | Потребує багатших подій Compaction у Codex. | -| Втручання в Compaction | Поточні хуки Compaction OpenClaw у режимі Codex мають рівень сповіщень. | Додати хуки Codex до/після Compaction, якщо plugins потрібно забороняти або переписувати нативну Compaction. | -| Побайтове захоплення запиту до API моделі | OpenClaw може захоплювати запити й сповіщення сервера застосунку, але ядро Codex внутрішньо формує фінальний запит OpenAI API. | Потребує події трасування запиту моделі Codex або API налагодження. | +| Мутація аргументів нативного інструмента | Нативні pre-tool хуки Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потребує підтримки хуків/схеми Codex для заміни вхідних даних інструмента. | +| Редагована нативна історія транскрипту Codex | Codex володіє канонічною нативною історією треду. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не повинен мутувати непідтримувані внутрішні компоненти. | Додати явні API app-server Codex, якщо потрібна хірургічна зміна нативного треду. | +| `tool_result_persist` для записів нативних інструментів Codex | Цей хук трансформує записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Можна дзеркалити трансформовані записи, але канонічне переписування потребує підтримки Codex. | +| Насичені нативні метадані Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільного списку збереженого/відкинутого, дельти токенів або payload підсумку. | Потребує багатших подій Compaction від Codex. | +| Втручання в Compaction | Поточні хуки Compaction OpenClaw у режимі Codex працюють на рівні сповіщень. | Додати pre/post хуки Compaction Codex, якщо plugins потрібно накладати вето або переписувати нативний Compaction. | +| Побайтне захоплення запиту до API моделі | OpenClaw може захоплювати запити app-server і сповіщення, але ядро Codex внутрішньо формує фінальний запит до OpenAI API. | Потребує події трасування запиту моделі Codex або debug API. | ## Інструменти, медіа та Compaction -Обв’язка Codex змінює лише низькорівневий вбудований виконавець агента. +Харнес Codex змінює лише низькорівневий вбудований виконавець агента. -OpenClaw і далі формує список інструментів і отримує динамічні результати інструментів від -обв’язки. Текст, зображення, відео, музика, TTS, затвердження та вивід інструментів обміну повідомленнями -далі проходять звичайним шляхом доставки OpenClaw. +OpenClaw і надалі формує список інструментів і отримує динамічні результати інструментів від +харнеса. Текст, зображення, відео, музика, TTS, схвалення та вивід інструментів повідомлень +і далі проходять звичайним шляхом доставлення OpenClaw. -Нативний ретранслятор хуків навмисно є універсальним, але контракт підтримки v1 +Нативний relay хуків навмисно є узагальненим, але контракт підтримки v1 обмежений шляхами нативних інструментів і дозволів Codex, які тестує OpenClaw. У -середовищі виконання Codex це включає корисні навантаження shell, patch і MCP `PreToolUse`, +runtime Codex це включає payloads shell, patch і MCP `PreToolUse`, `PostToolUse` та `PermissionRequest`. Не припускайте, що кожна майбутня -подія хуків Codex є поверхнею OpenClaw Plugin, доки контракт середовища виконання -не назве її. +подія хуків Codex є поверхнею Plugin OpenClaw, доки runtime-контракт не назве +її. -Для `PermissionRequest` OpenClaw повертає явні рішення дозволити або заборонити -лише тоді, коли це вирішує політика. Результат без рішення не є дозволом. Codex -розглядає його як відсутність рішення хука й переходить до власного guardian або шляху затвердження користувачем. +Для `PermissionRequest` OpenClaw повертає явні рішення allow або deny лише +коли це визначає policy. Результат без рішення не є allow. Codex трактує його як +відсутність рішення хука й переходить до власного guardian або шляху схвалення +користувача. -Запити на затвердження інструментів Codex MCP спрямовуються через потік -затвердження Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як +Elicitations схвалення інструментів Codex MCP маршрутизуються через потік +схвалення Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як `"mcp_tool_call"`. Підказки Codex `request_user_input` надсилаються назад до -початкового чату, а наступне поставлене в чергу подальше повідомлення відповідає на цей нативний -запит сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити -на отримання даних MCP і далі закриваються з помилкою. +початкового чату, а наступне поставлене в чергу follow-up повідомлення відповідає на цей нативний +запит сервера замість того, щоб бути спрямованим як додатковий контекст. Інші запити MCP elicitation +і надалі завершуються закрито. -Спрямування черги активного запуску відображається на `turn/steer` сервера застосунку Codex. З -типовим `messages.queue.mode: "steer"` OpenClaw пакетно збирає повідомлення чату в черзі -протягом налаштованого тихого вікна й надсилає їх як один запит `turn/steer` у -порядку надходження. Застарілий режим `queue` надсилає окремі запити `turn/steer`. Огляди Codex -і ручні ходи Compaction можуть відхиляти спрямування в тому самому ході; у такому разі -OpenClaw використовує чергу подальших повідомлень, коли вибраний режим дозволяє резервний шлях. Див. +Спрямування черги активного запуску відображається на `turn/steer` app-server Codex. З +типовим `messages.queue.mode: "steer"` OpenClaw групує поставлені в чергу повідомлення чату +для налаштованого тихого вікна й надсилає їх як один запит `turn/steer` у +порядку надходження. Застарілий режим `queue` надсилає окремі запити `turn/steer`. Codex +review і ручні ходи Compaction можуть відхиляти спрямування в межах того самого ходу; у такому разі +OpenClaw використовує followup queue, коли вибраний режим дозволяє fallback. Див. [Черга спрямування](/uk/concepts/queue-steering). -Коли вибрана модель використовує обв’язку Codex, нативна Compaction потоку -делегується серверу застосунку Codex. OpenClaw зберігає дзеркало транскрипту для історії -каналу, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або обв’язки. Дзеркало -містить запит користувача, фінальний текст асистента та легкі записи міркувань -або плану Codex, коли сервер застосунку їх видає. Наразі OpenClaw записує лише -сигнали початку й завершення нативної Compaction. Він ще не надає -людинозрозумілий підсумок Compaction або придатний для аудиту список записів, які Codex -зберіг після Compaction. +Коли вибрана модель використовує харнес Codex, нативний Compaction треду +делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, +пошуку, `/new`, `/reset` і майбутнього перемикання моделі або харнеса. Дзеркало +містить prompt користувача, фінальний текст assistant і легковагові записи reasoning або plan Codex, +коли app-server їх емітує. Нині OpenClaw записує лише сигнали початку та завершення +нативного Compaction. Він ще не надає читабельного для людини підсумку Compaction +або придатного для аудиту списку того, які записи Codex зберіг після Compaction. -Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не +Оскільки Codex володіє канонічним нативним тредом, `tool_result_persist` наразі не переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли -OpenClaw записує результат інструмента до транскрипту сеансу, що належить OpenClaw. +OpenClaw записує результат інструмента транскрипту сесії, яким володіє OpenClaw. Генерація медіа не потребує PI. Зображення, відео, музика, PDF, TTS і розуміння медіа -й далі використовують відповідні налаштування провайдера/моделі, як-от +й надалі використовують відповідні налаштування провайдера/моделі, як-от `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. ## Усунення несправностей -**Codex не відображається як звичайний провайдер `/model`:** це очікувано для +**Codex не з’являється як звичайний провайдер `/model`:** це очікувано для нових конфігурацій. Виберіть модель `openai/gpt-*` з -`agentRuntime.id: "codex"` (або застаріле посилання `codex/*`), увімкніть +`agentRuntime.id: "codex"` (або застарілий ref `codex/*`), увімкніть `plugins.entries.codex.enabled` і перевірте, чи `plugins.allow` не виключає `codex`. **OpenClaw використовує PI замість Codex:** `agentRuntime.id: "auto"` усе ще може використовувати PI як -бекенд сумісності, коли жодна обв’язка Codex не приймає запуск. Установіть -`agentRuntime.id: "codex"`, щоб примусово вибрати Codex під час тестування. -Примусове середовище виконання Codex тепер завершується помилкою замість повернення до PI, якщо ви -явно не встановите `agentRuntime.fallback: "pi"`. Щойно сервер застосунку Codex -вибрано, його помилки відображаються напряму без додаткової конфігурації резервного шляху. +backend сумісності, коли жоден харнес Codex не заявляє запуск. Установіть +`agentRuntime.id: "codex"`, щоб примусово вибрати Codex під час тестування. Примусовий +runtime Codex тепер завершується помилкою замість fallback до PI, якщо ви явно не +встановите `agentRuntime.fallback: "pi"`. Після вибору app-server Codex +його помилки проявляються напряму без додаткової конфігурації fallback. -**Сервер застосунку відхилено:** оновіть Codex, щоб узгодження із сервером застосунку -повідомляло версію `0.125.0` або новішу. Передрелізи тієї самої версії або версії із суфіксом збірки, -як-от `0.125.0-alpha.2` чи `0.125.0+custom`, відхиляються, бо -стабільний мінімум протоколу `0.125.0` є тим, що тестує OpenClaw. +**app-server відхилено:** оновіть Codex, щоб handshake app-server +повідомляв версію `0.125.0` або новішу. Prereleases тієї самої версії або версії із суфіксом build, +як-от `0.125.0-alpha.2` чи `0.125.0+custom`, відхиляються, тому що +стабільний протокольний мінімум `0.125.0` — це те, що тестує OpenClaw. **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken` -і те, що віддалений сервер застосунку використовує ту саму версію протоколу сервера застосунку Codex. +**Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken`, +і що віддалений app-server говорить тією самою версією протоколу app-server Codex. **Модель не Codex використовує PI:** це очікувано, якщо ви не примусили -`agentRuntime.id: "codex"` для цього агента або не вибрали застаріле -посилання `codex/*`. Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму звичайному +`agentRuntime.id: "codex"` для цього агента або не вибрали застарілий ref +`codex/*`. Звичайні `openai/gpt-*` та ref інших провайдерів залишаються на своєму звичайному шляху провайдера в режимі `auto`. Якщо ви примусово встановите `agentRuntime.id: "codex"`, кожен вбудований -хід для цього агента має бути моделлю OpenAI, яку підтримує Codex. +хід для цього агента має бути підтримуваною Codex моделлю OpenAI. -**Computer Use установлено, але інструменти не запускаються:** перевірте -`/codex computer-use status` із нового сеансу. Якщо інструмент повідомляє -`Native hook relay unavailable`, використайте `/new` або `/reset`; якщо це не зникає, перезапустіть -gateway, щоб очистити застарілі реєстрації нативних хуків. Якщо `computer-use.list_apps` -завершується тайм-аутом, перезапустіть Codex Computer Use або Codex Desktop і повторіть спробу. +**Computer Use встановлено, але інструменти не запускаються:** перевірте +`/codex computer-use status` із нової сесії. Якщо інструмент повідомляє +`Native hook relay unavailable`, використайте `/new` або `/reset`; якщо проблема зберігається, перезапустіть +Gateway, щоб очистити застарілі реєстрації нативних хуків. Якщо `computer-use.list_apps` +перевищує час очікування, перезапустіть Codex Computer Use або Codex Desktop і повторіть спробу. ## Пов’язане -- [Plugins обв’язки агента](/uk/plugins/sdk-agent-harness) -- [Середовища виконання агентів](/uk/concepts/agent-runtimes) +- [Plugins харнеса агента](/uk/plugins/sdk-agent-harness) +- [Runtime агента](/uk/concepts/agent-runtimes) - [Провайдери моделей](/uk/concepts/model-providers) - [Провайдер OpenAI](/uk/providers/openai) - [Статус](/uk/cli/status) diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index 0e861f746..7bc76798e 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,72 +1,62 @@ --- read_when: - - Ви змінюєте вбудоване середовище виконання агента або реєстр середовища агента - - Ви реєструєте середовище агента з вбудованого або довіреного плагіна - - Вам потрібно зрозуміти, як Plugin Codex пов’язаний із постачальниками моделей + - Ви змінюєте вбудоване середовище виконання агента або реєстр обв'язок + - Ви реєструєте обв’язку агента з вбудованого або довіреного Plugin + - Потрібно розуміти, як плагін Codex пов’язаний із постачальниками моделей sidebarTitle: Agent Harness -summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий виконавець вбудованого агента -title: Плагіни середовища агента +summary: Експериментальна поверхня SDK для Plugin, які замінюють низькорівневого вбудованого виконавця агента +title: Плагіни обв’язки агента x-i18n: - generated_at: "2026-04-26T07:50:15Z" - model: gpt-5.4 + generated_at: "2026-05-02T02:37:22Z" + model: gpt-5.5 provider: openai - source_hash: 340fc6207dabc6ffe7ffb9c07ca9e80e76f1034d4978c41279dc826468302181 + source_hash: b6e55d2df09c3965e1397be72f19dec2a6ed941ac8b7b01be8eee0f9713400dc source_path: plugins/sdk-agent-harness.md - workflow: 15 + workflow: 16 --- -**Середовище агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. -Для користувацької ментальної моделі див. [Середовища виконання агента](/uk/concepts/agent-runtimes). +**Обв’язка агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделі, не канал і не реєстр інструментів. Для користувацької ментальної моделі див. [Середовища виконання агентів](/uk/concepts/agent-runtimes). -Використовуйте цю поверхню лише для вбудованих або довірених native-плагінів. Контракт -досі є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний -вбудований виконавець. +Використовуйте цю поверхню лише для вбудованих або довірених нативних Plugin. Контракт досі експериментальний, бо типи параметрів навмисно віддзеркалюють поточний вбудований runner. -## Коли використовувати harness +## Коли використовувати обв’язку -Реєструйте середовище агента, коли сімейство моделей має власне native-сеансове -середовище виконання і звичайний транспорт постачальника OpenClaw є хибною абстракцією. +Зареєструйте обв’язку агента, коли сімейство моделей має власне нативне середовище виконання сесій, а звичайний транспорт постачальника OpenClaw є неправильною абстракцією. Приклади: -- native-сервер coding-agent, який володіє тредами та Compaction -- локальний CLI або демон, який має стримити native-події plan/reasoning/tool -- середовище виконання моделі, якому потрібен власний resume id на додачу до - стенограми сеансу OpenClaw +- нативний сервер агента для кодування, який володіє потоками й compaction +- локальний CLI або daemon, який має транслювати нативні події плану/міркування/інструментів +- середовище виконання моделі, якому потрібен власний ідентифікатор відновлення на додачу до стенограми сесії OpenClaw -**Не** реєструйте harness лише для додавання нового LLM API. Для звичайних HTTP або -WebSocket API моделей створюйте [плагін постачальника](/uk/plugins/sdk-provider-plugins). +Не реєструйте обв’язку лише для додавання нового LLM API. Для звичайних HTTP- або WebSocket-API моделей створіть [Plugin постачальника](/uk/plugins/sdk-provider-plugins). -## Чим усе ще володіє ядро +## Чим досі володіє ядро -Перш ніж буде вибрано harness, OpenClaw уже розв’язав: +Перш ніж буде вибрано обв’язку, OpenClaw уже розв’язав: - постачальника і модель -- стан автентифікації середовища виконання -- рівень thinking і бюджет контексту -- файл стенограми/сеансу OpenClaw -- робочий простір, sandbox і політику інструментів -- зворотні виклики відповіді каналу та зворотні виклики стримінгу -- політику fallback моделі та live-перемикання моделей +- стан авторизації середовища виконання +- рівень мислення і бюджет контексту +- файл стенограми/сесії OpenClaw +- робочу область, sandbox і політику інструментів +- callback-и відповіді каналу та callback-и streaming +- політику fallback моделі й live перемикання моделей -Такий поділ навмисний. Harness виконує підготовлену спробу; він не вибирає -постачальників, не замінює доставку каналу і не перемикає моделі непомітно. +Цей поділ навмисний. Обв’язка виконує підготовлену спробу; вона не вибирає постачальників, не замінює доставлення каналом і не перемикає моделі непомітно. -Підготовлена спроба також містить `params.runtimePlan` — пакет політик, що належить OpenClaw, для рішень середовища виконання, які мають залишатися спільними між PI та native-harness: +Підготовлена спроба також містить `params.runtimePlan`, пакет політик, яким володіє OpenClaw, для рішень середовища виконання, що мають залишатися спільними для PI та нативних обв’язок: - `runtimePlan.tools.normalize(...)` і - `runtimePlan.tools.logDiagnostics(...)` для політики схеми інструментів з урахуванням постачальника -- `runtimePlan.transcript.resolvePolicy(...)` для політики санітизації стенограми та - відновлення викликів інструментів -- `runtimePlan.delivery.isSilentPayload(...)` для спільного приглушення доставки `NO_REPLY` і медіа + `runtimePlan.tools.logDiagnostics(...)` для політики схем інструментів з урахуванням постачальника +- `runtimePlan.transcript.resolvePolicy(...)` для санітизації стенограми й політики відновлення викликів інструментів +- `runtimePlan.delivery.isSilentPayload(...)` для спільного `NO_REPLY` і приглушення доставлення медіа - `runtimePlan.outcome.classifyRunResult(...)` для класифікації fallback моделі -- `runtimePlan.observability` для розв’язаних метаданих постачальника/моделі/harness +- `runtimePlan.observability` для розв’язаних метаданих постачальника/моделі/обв’язки -Harness можуть використовувати план для рішень, які мають збігатися з поведінкою PI, але -все одно повинні трактувати його як стан спроби, що належить хосту. Не змінюйте його і не використовуйте для -перемикання постачальників/моделей усередині ходу. +Обв’язки можуть використовувати план для рішень, які мають відповідати поведінці PI, але все одно повинні трактувати його як стан спроби, яким володіє host. Не змінюйте його й не використовуйте для перемикання постачальників/моделей усередині ходу. -## Зареєструвати harness +## Зареєструвати обв’язку **Імпорт:** `openclaw/plugin-sdk/agent-harness` @@ -76,7 +66,7 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; const myHarness: AgentHarness = { id: "my-harness", - label: "Моє native-середовище агента", + label: "My native agent harness", supports(ctx) { return ctx.provider === "my-provider" @@ -85,17 +75,17 @@ const myHarness: AgentHarness = { }, async runAttempt(params) { - // Запустіть або відновіть ваш native-тред. - // Використовуйте params.prompt, params.tools, params.images, params.onPartialReply, - // params.onAgentEvent та інші поля підготовленої спроби. + // Start or resume your native thread. + // Use params.prompt, params.tools, params.images, params.onPartialReply, + // params.onAgentEvent, and the other prepared attempt fields. return await runMyNativeTurn(params); }, }; export default definePluginEntry({ id: "my-native-agent", - name: "Мій Native Agent", - description: "Запускає вибрані моделі через native-демон агента.", + name: "My Native Agent", + description: "Runs selected models through a native agent daemon.", register(api) { api.registerAgentHarness(myHarness); }, @@ -104,127 +94,62 @@ export default definePluginEntry({ ## Політика вибору -OpenClaw вибирає harness після розв’язання постачальника/моделі: +OpenClaw вибирає обв’язку після розв’язання постачальника/моделі: -1. Записаний id harness наявного сеансу має перевагу, тож зміни config/env не - перемикають цю стенограму на інше середовище виконання «на гарячу». -2. `OPENCLAW_AGENT_RUNTIME=` примусово вибирає зареєстрований harness з цим id для - сеансів, які ще не закріплені. -3. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудований harness PI. -4. `OPENCLAW_AGENT_RUNTIME=auto` запитує в зареєстрованих harness, чи підтримують вони розв’язану - пару постачальник/модель. -5. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо fallback PI - не вимкнено. +1. Перемагає записаний ідентифікатор обв’язки наявної сесії, тому зміни config/env не перемикають цю стенограму гаряче на інше середовище виконання. +2. `OPENCLAW_AGENT_RUNTIME=` примусово вибирає зареєстровану обв’язку з цим ідентифікатором для сесій, які ще не закріплено. +3. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудовану обв’язку PI. +4. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані обв’язки, чи підтримують вони розв’язаного постачальника/модель. +5. Якщо жодна зареєстрована обв’язка не підходить, OpenClaw використовує PI, якщо fallback PI не вимкнено. -Помилки harness плагіна відображаються як помилки виконання. У режимі `auto` fallback на PI -використовується лише тоді, коли жоден зареєстрований harness плагіна не підтримує розв’язану -пару постачальник/модель. Щойно harness плагіна заявив про виконання, OpenClaw не -повторює той самий хід через PI, оскільки це може змінити семантику автентифікації/середовища виконання -або дублювати побічні ефекти. +Збої обв’язок Plugin відображаються як збої запуску. У режимі `auto` fallback PI використовується лише тоді, коли жодна зареєстрована обв’язка Plugin не підтримує розв’язаного постачальника/модель. Щойно обв’язка Plugin заявила запуск, OpenClaw не відтворює той самий хід через PI, бо це може змінити семантику авторизації/середовища виконання або дублювати побічні ефекти. -Вибраний id harness зберігається разом з id сеансу після вбудованого запуску. -Застарілі сеанси, створені до появи закріплення harness, вважаються закріпленими за PI, щойно в них -з’являється історія стенограми. Використовуйте новий/скинутий сеанс, коли перемикаєтеся між PI та -native-harness плагіна. `/status` показує нестандартні id harness, як-от `codex`, -поруч із `Fast`; PI приховано, оскільки це типовий шлях сумісності. -Якщо вибраний harness виглядає несподіваним, увімкніть журналювання налагодження `agents/harness` і -перегляньте структурований запис gateway `agent harness selected`. Він містить -вибраний id harness, причину вибору, політику runtime/fallback і, у режимі -`auto`, результат підтримки для кожного кандидата-плагіна. +Ідентифікатор вибраної обв’язки зберігається разом з ідентифікатором сесії після вбудованого запуску. Застарілі сесії, створені до закріплення обв’язок, вважаються закріпленими за PI, щойно вони мають історію стенограми. Використовуйте нову/скинуту сесію під час перемикання між PI і нативною обв’язкою Plugin. `/status` показує ідентифікатори обв’язок, відмінні від типових, наприклад `codex`, поруч із `Fast`; PI приховано, бо це типовий шлях сумісності. Якщо вибрана обв’язка несподівана, увімкніть debug-логування `agents/harness` і перегляньте структурований запис Gateway `agent harness selected`. Він містить ідентифікатор вибраної обв’язки, причину вибору, політику середовища виконання/fallback і, у режимі `auto`, результат підтримки кожного кандидата Plugin. -Вбудований плагін Codex реєструє `codex` як свій id harness. Ядро трактує це як -звичайний id harness плагіна; специфічні для Codex аліаси мають належати плагіну -або конфігурації оператора, а не спільному селектору середовища виконання. +Вбудований Plugin Codex реєструє `codex` як свій ідентифікатор обв’язки. Ядро трактує це як звичайний ідентифікатор обв’язки Plugin; специфічні для Codex alias-и належать до Plugin або операторського config, а не до спільного селектора середовища виконання. -## Поєднання постачальника й harness +## Пара постачальника й обв’язки -Більшість harness також мають реєструвати постачальника. Постачальник робить посилання на моделі, -статус автентифікації, метадані моделі та вибір `/model` видимими для решти -OpenClaw. Потім harness заявляє цей постачальник у `supports(...)`. +Більшість обв’язок також мають реєструвати постачальника. Постачальник робить посилання моделей, стан авторизації, метадані моделей і вибір `/model` видимими для решти OpenClaw. Потім обв’язка заявляє цього постачальника в `supports(...)`. -Вбудований плагін Codex дотримується цієї схеми: +Вбудований Plugin Codex дотримується цього шаблону: -- бажані користувацькі посилання на моделі: `openai/gpt-5.5` плюс +- бажані користувацькі посилання моделей: `openai/gpt-5.5` плюс `agentRuntime.id: "codex"` -- посилання сумісності: застарілі посилання `codex/gpt-*` усе ще приймаються, але нові - конфігурації не повинні використовувати їх як звичайні посилання постачальник/модель -- id harness: `codex` -- auth: синтетична доступність постачальника, оскільки harness Codex володіє - native-входом/сеансом Codex -- запит app-server: OpenClaw надсилає до Codex чистий id моделі і дозволяє - harness спілкуватися з native-протоколом app-server +- посилання сумісності: застарілі посилання `codex/gpt-*` залишаються прийнятними, але нові config не повинні використовувати їх як звичайні посилання постачальника/моделі +- ідентифікатор обв’язки: `codex` +- авторизація: синтетична доступність постачальника, бо обв’язка Codex володіє нативним login/сесією Codex +- запит app-server: OpenClaw надсилає Codex чистий ідентифікатор моделі й дозволяє обв’язці говорити нативним протоколом app-server -Плагін Codex є адитивним. Звичайні посилання `openai/gpt-*` і далі використовують -звичайний шлях постачальника OpenClaw, якщо ви не примусите harness Codex через -`agentRuntime.id: "codex"`. Старіші посилання `codex/gpt-*` для сумісності все ще вибирають -постачальника і harness Codex. +Plugin Codex є додатковим. Звичайні посилання `openai/gpt-*` продовжують використовувати нормальний шлях постачальника OpenClaw, якщо ви не примусите обв’язку Codex через `agentRuntime.id: "codex"`. Старіші посилання `codex/gpt-*` досі вибирають постачальника й обв’язку Codex для сумісності. -Для налаштування оператором, прикладів префіксів моделей і конфігурацій лише для Codex див. -[Harness Codex](/uk/plugins/codex-harness). +Для операторського налаштування, прикладів префіксів моделей і config лише для Codex див. [Обв’язка Codex](/uk/plugins/codex-harness). -OpenClaw вимагає Codex app-server версії `0.125.0` або новішої. Плагін Codex перевіряє -initialize-handshake app-server і блокує старіші або неверсіоновані сервери, щоб -OpenClaw працював лише з тією поверхнею протоколу, на якій його було протестовано. Поріг -`0.125.0` включає підтримку native payload hook MCP, що з’явилася в Codex `0.124.0`, -водночас прив’язуючи OpenClaw до новішої протестованої стабільної гілки. +OpenClaw потребує Codex app-server `0.125.0` або новішого. Plugin Codex перевіряє initialize handshake app-server і блокує старіші або неверсійовані сервери, щоб OpenClaw запускався лише проти тієї поверхні протоколу, з якою його протестовано. Мінімальна версія `0.125.0` містить підтримку нативного payload MCP hook, що з’явилася в Codex `0.124.0`, водночас закріплюючи OpenClaw за новішою протестованою стабільною лінією. -### Проміжний шар результатів інструментів +### Middleware результатів інструментів -Вбудовані плагіни можуть підключати нейтральний до середовища виконання проміжний шар результатів інструментів через -`api.registerAgentToolResultMiddleware(...)`, коли їхній маніфест оголошує -цільові id середовищ виконання в `contracts.agentToolResultMiddleware`. Цей довірений -шов призначено для асинхронних перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex подадуть -вивід інструмента назад у модель. +Вбудовані Plugin можуть під’єднувати runtime-neutral middleware результатів інструментів через `api.registerAgentToolResultMiddleware(...)`, коли їхній manifest оголошує цільові ідентифікатори середовища виконання в `contracts.agentToolResultMiddleware`. Ця довірена точка розширення призначена для async-перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex передає вихід інструмента назад у модель. -Застарілі вбудовані плагіни все ще можуть використовувати -`api.registerCodexAppServerExtensionFactory(...)` для проміжного шару лише для Codex app-server, -але нові перетворення результатів мають використовувати нейтральний до середовища виконання API. -Хук лише для Pi `api.registerEmbeddedExtensionFactory(...)` було видалено; -перетворення результатів інструментів Pi мають використовувати нейтральний проміжний шар. +Застарілі вбудовані Plugin досі можуть використовувати `api.registerCodexAppServerExtensionFactory(...)` для middleware лише Codex app-server, але нові перетворення результатів повинні використовувати runtime-neutral API. Hook лише для Pi `api.registerEmbeddedExtensionFactory(...)` вилучено; перетворення результатів інструментів Pi мають використовувати runtime-neutral middleware. -### Класифікація термінального результату +### Класифікація кінцевого результату -Native-harness, які володіють власною проєкцією протоколу, можуть використовувати -`classifyAgentHarnessTerminalOutcome(...)` з -`openclaw/plugin-sdk/agent-harness-runtime`, коли завершений хід не породив -видимого тексту помічника. Допоміжна функція повертає `empty`, `reasoning-only` або -`planning-only`, щоб політика fallback OpenClaw могла вирішити, чи повторювати спробу на -іншій моделі. Вона навмисно залишає некласифікованими помилки prompt, ходи в процесі виконання -та навмисно тихі відповіді, такі як `NO_REPLY`. +Нативні обв’язки, які володіють власною проєкцією протоколу, можуть використовувати `classifyAgentHarnessTerminalOutcome(...)` з `openclaw/plugin-sdk/agent-harness-runtime`, коли завершений хід не створив видимого тексту assistant. Помічник повертає `empty`, `reasoning-only` або `planning-only`, щоб політика fallback OpenClaw могла вирішити, чи повторювати спробу на іншій моделі. Він навмисно не класифікує помилки prompt, ходи в процесі та навмисні тихі відповіді, як-от `NO_REPLY`. -### Режим native-harness Codex +### Нативний режим обв’язки Codex -Вбудований harness `codex` — це native-режим Codex для вбудованих ходів -агента OpenClaw. Спочатку увімкніть вбудований плагін `codex` і додайте `codex` до -`plugins.allow`, якщо у вашій конфігурації використовується обмежувальний allowlist. Конфігурації native app-server -мають використовувати `openai/gpt-*` з `agentRuntime.id: "codex"`. -Натомість використовуйте `openai-codex/*` для Codex OAuth через PI. Застарілі посилання моделей `codex/*` -залишаються аліасами сумісності для native-harness. +Вбудована обв’язка `codex` — це нативний режим Codex для вбудованих ходів агента OpenClaw. Спочатку увімкніть вбудований Plugin `codex` і додайте `codex` до `plugins.allow`, якщо ваш config використовує обмежувальний allowlist. Нативні config app-server повинні використовувати `openai/gpt-*` з `agentRuntime.id: "codex"`. Використовуйте `openai-codex/*` для Codex OAuth через PI натомість. Застарілі посилання моделей `codex/*` залишаються alias-ами сумісності для нативної обв’язки. -Коли цей режим працює, Codex володіє native id треду, поведінкою resume, -Compaction і виконанням app-server. OpenClaw і далі володіє chat-каналом, -дзеркалом видимої стенограми, політикою інструментів, погодженнями, доставкою медіа та -вибором сеансу. Використовуйте `agentRuntime.id: "codex"` без перевизначення `fallback`, -коли вам потрібно довести, що лише шлях app-server Codex може заявити це виконання. -Явні runtime плагінів уже типово завершуються fail-closed. Установлюйте `fallback: "pi"` -лише тоді, коли ви навмисно хочете, щоб PI обробляв відсутність вибору harness. Помилки Codex -app-server уже завершуються безпосередньо, а не повторюються через PI. +Коли цей режим виконується, Codex володіє нативним ідентифікатором потоку, поведінкою відновлення, compaction і виконанням app-server. OpenClaw досі володіє чат-каналом, видимим дзеркалом стенограми, політикою інструментів, approvals, доставленням медіа та вибором сесії. Використовуйте `agentRuntime.id: "codex"` без override `fallback`, коли потрібно довести, що лише шлях Codex app-server може заявити запуск. Явні середовища виконання Plugin уже типово fail closed. Установлюйте `fallback: "pi"` лише тоді, коли навмисно хочете, щоб PI обробляв відсутній вибір обв’язки. Збої Codex app-server уже завершуються напряму, а не повторюються через PI. -## Вимкнення fallback на PI +## Вимкнути fallback PI -Типово OpenClaw запускає вбудованих агентів з `agents.defaults.agentRuntime`, -встановленим у `{ id: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані harness -плагінів можуть заявляти пару постачальник/модель. Якщо жоден не підходить, OpenClaw -повертається до PI. +Типово OpenClaw запускає вбудованих агентів з `agents.defaults.agentRuntime`, установленим на `{ id: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані обв’язки Plugin можуть заявити пару постачальник/модель. Якщо жодна не підходить, OpenClaw fallback-иться до PI. -У режимі `auto` встановлюйте `fallback: "none"`, коли вам потрібно, щоб відсутність вибору harness плагіна -призводила до помилки, а не до використання PI. Явні runtime плагінів, як-от -`runtime: "codex"`, уже типово завершуються fail-closed, якщо лише `fallback: "pi"` не -задано в тій самій конфігурації або області перевизначення середовища. Помилки вибраного harness плагіна -завжди є жорсткими збоями. Це не блокує явний `runtime: "pi"` або -`OPENCLAW_AGENT_RUNTIME=pi`. +У режимі `auto` установіть `fallback: "none"`, коли потрібно, щоб відсутній вибір обв’язки Plugin завершувався збоєм замість використання PI. Явні середовища виконання Plugin, як-от `agentRuntime.id: "codex"`, уже типово fail closed, якщо `fallback: "pi"` не встановлено в тому самому config або області env override. Збої вибраних обв’язок Plugin завжди завершуються жорстким збоєм. Це не блокує явний `agentRuntime.id: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. -Для вбудованих запусків лише з Codex: +Для вбудованих запусків лише Codex: ```json { @@ -239,9 +164,7 @@ app-server уже завершуються безпосередньо, а не } ``` -Якщо ви хочете, щоб будь-який зареєстрований harness плагіна заявляв відповідні моделі, але ніколи -не хочете, щоб OpenClaw непомітно повертався до PI, залишайте `runtime: "auto"` і вимикайте -fallback: +Якщо ви хочете, щоб будь-яка зареєстрована обв’язка Plugin заявляла відповідні моделі, але не хочете, щоб OpenClaw непомітно fallback-ився до PI, залиште `runtime: "auto"` і вимкніть fallback: ```json { @@ -256,7 +179,7 @@ fallback: } ``` -Перевизначення для окремих агентів використовують ту саму форму: +Per-agent override-и використовують ту саму форму: ```json { @@ -281,9 +204,7 @@ fallback: } ``` -`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштоване середовище виконання. Використовуйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback на PI з -середовища. +`OPENCLAW_AGENT_RUNTIME` досі override-ить налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback PI із середовища. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -291,51 +212,45 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Коли fallback вимкнено, сеанс завершується рано з помилкою, якщо запитаний harness не -зареєстровано, він не підтримує розв’язану пару постачальник/модель або завершується помилкою до -породження побічних ефектів ходу. Це навмисно для розгортань лише з Codex і -для live-тестів, які мають довести, що шлях app-server Codex справді використовується. +Коли fallback вимкнено, сесія завершується рано збоєм, якщо запитану обв’язку не зареєстровано, вона не підтримує розв’язаного постачальника/модель або завершується збоєм до створення побічних ефектів ходу. Це навмисно для розгортань лише Codex і для live-тестів, які мають довести, що шлях Codex app-server справді використовується. -Це налаштування керує лише вбудованим harness агента. Воно не вимикає -маршрутизацію зображень, відео, музики, TTS, PDF або іншого маршрутизування моделей, специфічного для постачальника. +Це налаштування керує лише обв’язкою вбудованого агента. Воно не вимикає маршрутизацію моделей для зображень, відео, музики, TTS, PDF або інших можливостей, специфічних для постачальника. -## Native-сеанси та дзеркало стенограми +## Нативні сесії та дзеркало стенограми -Harness може зберігати native id сеансу, id треду або daemon-side токен відновлення. -Явно зберігайте цей зв’язок асоційованим із сеансом OpenClaw і продовжуйте -дзеркалити видимий користувачу вивід помічника/інструментів у стенограму OpenClaw. +Обв’язка може зберігати нативний ідентифікатор сесії, ідентифікатор потоку або resume token на боці daemon. Тримайте цю прив’язку явно пов’язаною із сесією OpenClaw і продовжуйте дзеркалити видимий для користувача вихід assistant/інструментів у стенограму OpenClaw. Стенограма OpenClaw залишається шаром сумісності для: -- видимої в каналі історії сеансу -- пошуку та індексації стенограми -- перемикання назад до вбудованого harness PI на пізнішому ході -- загальної поведінки `/new`, `/reset` і видалення сеансу +- видимої в каналі історії сесії +- пошуку й індексації стенограм +- перемикання назад на вбудовану обв’язку PI в пізнішому ході +- загальної поведінки `/new`, `/reset` і видалення сесій -Якщо ваш harness зберігає sidecar-зв’язування, реалізуйте `reset(...)`, щоб OpenClaw міг -очистити його, коли пов’язаний сеанс OpenClaw скидається. +Якщо ваша обв’язка зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її під час скидання власної сесії OpenClaw. ## Результати інструментів і медіа -Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу. -Коли harness виконує динамічний виклик інструмента, повертайте результат інструмента -назад через форму результату harness замість того, щоб самостійно надсилати медіа в канал. +Core формує список інструментів OpenClaw і передає його в підготовлену спробу. +Коли тестовий середовищний виконувач запускає динамічний виклик інструмента, повертайте результат інструмента через +форму результату цього середовищного виконувача, а не надсилайте медіа каналу самостійно. -Це зберігає текст, зображення, відео, музику, TTS, погодження та виводи -інструментів обміну повідомленнями на тому самому шляху доставки, що й у запусків на основі PI. +Це зберігає текстові, графічні, відео-, музичні, TTS-, approval- та messaging-tool-виводи +на тому самому шляху доставки, що й запуски на базі PI. ## Поточні обмеження -- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів досі +- Публічний шлях імпорту є узагальненим, але деякі псевдоніми типів спроби/результату досі містять назви `Pi` для сумісності. -- Установлення сторонніх harness є експериментальним. Віддавайте перевагу плагінам постачальників, - доки вам не знадобиться native-сеансове середовище виконання. -- Перемикання harness підтримується між ходами. Не перемикайте harness посеред ходу після того, як уже почалися native-інструменти, погодження, текст помічника або надсилання повідомлень. +- Встановлення сторонніх середовищних виконувачів є експериментальним. Надавайте перевагу provider plugins, + доки вам не знадобиться нативний runtime сеансу. +- Перемикання середовищних виконувачів підтримується між ходами. Не перемикайте середовищні виконувачі + посеред ходу після того, як уже почалися native tools, approvals, текст асистента або надсилання повідомлень. ## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) -- [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) -- [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) -- [Harness Codex](/uk/plugins/codex-harness) +- [Допоміжні засоби Runtime](/uk/plugins/sdk-runtime) +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) +- [Codex Harness](/uk/plugins/codex-harness) - [Постачальники моделей](/uk/concepts/model-providers) diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index 03edb525c..83884055d 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -1,84 +1,103 @@ --- read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - - Вам потрібна автентифікація через передплату Codex замість API-ключів + - Вам потрібна автентифікація через підписку Codex замість API-ключів - Вам потрібна суворіша поведінка виконання агента GPT-5 -summary: Використовуйте OpenAI через ключі API або передплату Codex в OpenClaw +summary: Використовуйте OpenAI в OpenClaw за допомогою API-ключів або підписки Codex title: OpenAI x-i18n: - generated_at: "2026-05-01T22:03:36Z" + generated_at: "2026-05-02T02:38:33Z" model: gpt-5.5 provider: openai - source_hash: bd9a8f05d31800354307c6fd7beb8cd1eed3d234e5c1e939e895cd99658b540b + source_hash: d7e98179f5a7d90289ed6cdad1c4dd03834f42e3fcc747d24c7d29a47e103392 source_path: providers/openai.md workflow: 16 --- -OpenAI надає developer API для моделей GPT, а Codex також доступний як агент для програмування в плані ChatGPT через клієнти Codex від OpenAI. OpenClaw тримає ці поверхні окремо, щоб конфігурація залишалася передбачуваною. +OpenAI надає API для розробників для моделей GPT, а Codex також доступний як +агент для кодування в межах плану ChatGPT через клієнти Codex від OpenAI. OpenClaw тримає ці +поверхні окремими, щоб конфігурація лишалася передбачуваною. -OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі вибирає маршрут провайдера/автентифікації; окреме налаштування runtime вибирає, хто виконує вбудований цикл агента: +OpenClaw підтримує три маршрути родини OpenAI. Більшості підписників ChatGPT/Codex, +яким потрібна поведінка Codex, слід використовувати нативне середовище виконання сервера застосунку Codex. Префікс +моделі вибирає провайдера/назву моделі; окреме налаштування середовища виконання вибирає, +хто виконує вбудований цикл агента: -- **Ключ API** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`) -- **Підписка Codex через PI** — вхід ChatGPT/Codex з доступом за підпискою (моделі `openai-codex/*`) -- **Обв’язка Codex app-server** — нативне виконання Codex app-server (моделі `openai/*` плюс `agents.defaults.agentRuntime.id: "codex"`) +- **Ключ API** - прямий доступ до OpenAI Platform з оплатою за використання (`openai/*` models) +- **Підписка Codex з нативним середовищем виконання Codex** - вхід через ChatGPT/Codex плюс виконання сервером застосунку Codex (`openai/*` models plus `agents.defaults.agentRuntime.id: "codex"`) +- **Підписка Codex через PI** - вхід через ChatGPT/Codex зі звичайним раннером OpenClaw PI (`openai-codex/*` models) -OpenAI явно підтримує використання OAuth за підпискою в зовнішніх інструментах і робочих процесах на кшталт OpenClaw. +OpenAI явно підтримує використання OAuth підписки в зовнішніх інструментах і робочих процесах на кшталт OpenClaw. -Провайдер, модель, runtime і канал — це окремі шари. Якщо ці мітки змішуються між собою, прочитайте [runtime агентів](/uk/concepts/agent-runtimes), перш ніж змінювати конфігурацію. +Провайдер, модель, середовище виконання та канал є окремими шарами. Якщо ці мітки +змішуються, прочитайте [середовища виконання агентів](/uk/concepts/agent-runtimes), перш ніж +змінювати конфігурацію. ## Швидкий вибір -| Ціль | Використовуйте | Примітки | -| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- | -| Пряма оплата за ключем API | `openai/gpt-5.5` | Установіть `OPENAI_API_KEY` або запустіть onboarding ключа API OpenAI. | -| GPT-5.5 з автентифікацією підписки ChatGPT/Codex | `openai-codex/gpt-5.5` | Стандартний маршрут PI для OAuth Codex. Найкращий перший вибір для налаштувань із підпискою. | -| GPT-5.5 з нативною поведінкою Codex app-server | `openai/gpt-5.5` плюс `agentRuntime.id: "codex"` | Примусово вмикає обв’язку Codex app-server для цього посилання на модель. | -| Генерація або редагування зображень | `openai/gpt-image-2` | Працює з `OPENAI_API_KEY` або OAuth OpenAI Codex. | -| Зображення з прозорим фоном | `openai/gpt-image-1.5` | Використовуйте `outputFormat=png` або `webp` і `openai.background=transparent`. | +| Ціль | Використовуйте | Примітки | +| ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- | +| Підписка ChatGPT/Codex з нативним середовищем виконання Codex | `openai/gpt-5.5` plus `agentRuntime.id: "codex"` | Рекомендоване налаштування Codex для більшості користувачів. Увійдіть за допомогою автентифікації `openai-codex`. | +| Пряма оплата за ключем API | `openai/gpt-5.5` | Установіть `OPENAI_API_KEY` або запустіть онбординг ключа API OpenAI. | +| Автентифікація підписки ChatGPT/Codex через PI | `openai-codex/gpt-5.5` | Використовуйте лише тоді, коли свідомо хочете звичайний раннер PI. | +| Генерування або редагування зображень | `openai/gpt-image-2` | Працює з `OPENAI_API_KEY` або OpenAI Codex OAuth. | +| Зображення з прозорим тлом | `openai/gpt-image-1.5` | Використовуйте `outputFormat=png` або `webp` і `openai.background=transparent`. | ## Мапа назв Назви схожі, але не взаємозамінні: -| Назва, яку ви бачите | Шар | Значення | +| Назва, яку ви бачите | Шар | Значення | | ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- | -| `openai` | Префікс провайдера | Прямий маршрут API OpenAI Platform. | -| `openai-codex` | Префікс провайдера | Маршрут OAuth/підписки OpenAI Codex через звичайний runner OpenClaw PI. | -| Plugin `codex` | Plugin | Вбудований Plugin OpenClaw, який надає нативний runtime Codex app-server і керування чатом `/codex`. | -| `agentRuntime.id: codex` | Runtime агента | Примусово використовує нативну обв’язку Codex app-server для вбудованих ходів. | -| `/codex ...` | Набір команд чату | Прив’язує/керує потоками Codex app-server з розмови. | -| `runtime: "acp", agentId: "codex"` | Маршрут сесії ACP | Явний fallback-шлях, який запускає Codex через ACP/acpx. | +| `openai` | Префікс провайдера | Прямий маршрут API OpenAI Platform. | +| `openai-codex` | Префікс провайдера | Маршрут OpenAI Codex OAuth/підписки через звичайний раннер OpenClaw PI. | +| `codex` plugin | Plugin | Вбудований Plugin OpenClaw, який надає нативне середовище виконання сервера застосунку Codex і керування чатом `/codex`. | +| `agentRuntime.id: codex` | Середовище виконання агента | Примусово використовувати нативну обв’язку сервера застосунку Codex для вбудованих ходів. | +| `/codex ...` | Набір чат-команд | Прив’язувати/керувати потоками сервера застосунку Codex із розмови. | +| `runtime: "acp", agentId: "codex"` | Маршрут сесії ACP | Явний резервний шлях, який запускає Codex через ACP/acpx. | -Це означає, що конфігурація може навмисно містити і `openai-codex/*`, і Plugin `codex`. Це коректно, коли потрібен OAuth Codex через PI, а також доступне нативне керування чатом `/codex`. `openclaw doctor` попереджає про таку комбінацію, щоб ви могли підтвердити, що вона навмисна; він не переписує її. +Це означає, що конфігурація може навмисно містити і `openai-codex/*`, і +`codex` plugin. Це коректно, коли вам потрібен Codex OAuth через PI і також потрібні +доступні нативні елементи керування чатом `/codex`. `openclaw doctor` попереджає про цю +комбінацію, щоб ви могли підтвердити, що вона навмисна; він не переписує її. -GPT-5.5 доступна як через прямий доступ за ключем API OpenAI Platform, так і через маршрути підписки/OAuth. Використовуйте `openai/gpt-5.5` для прямого трафіку `OPENAI_API_KEY`, `openai-codex/gpt-5.5` для OAuth Codex через PI або `openai/gpt-5.5` з `agentRuntime.id: "codex"` для нативної обв’язки Codex app-server. +GPT-5.5 доступна як через прямий доступ ключем API OpenAI Platform, так і через +маршрути підписки/OAuth. Для підписки ChatGPT/Codex плюс нативного виконання Codex +використовуйте `openai/gpt-5.5` з `agentRuntime.id: "codex"`. Використовуйте +`openai-codex/gpt-5.5` лише для Codex OAuth через PI, або `openai/gpt-5.5` +без перевизначення середовища виконання Codex для прямого трафіку `OPENAI_API_KEY`. -Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не вмикає вбудований Plugin Codex app-server. OpenClaw вмикає цей Plugin лише тоді, коли ви явно вибираєте нативну обв’язку Codex за допомогою `agentRuntime.id: "codex"` або використовуєте застаріле посилання на модель `codex/*`. -Якщо вбудований Plugin `codex` увімкнено, але `openai-codex/*` усе ще визначається через PI, `openclaw doctor` попереджає і залишає маршрут без змін. +Увімкнення OpenAI plugin або вибір моделі `openai-codex/*` не +вмикає вбудований plugin сервера застосунку Codex. OpenClaw вмикає цей plugin лише +коли ви явно вибираєте нативну обв’язку Codex за допомогою +`agentRuntime.id: "codex"` або використовуєте застаріле посилання на модель `codex/*`. +Якщо вбудований `codex` plugin увімкнено, але `openai-codex/*` усе ще обробляється +через PI, `openclaw doctor` попереджає і залишає маршрут без змін. ## Покриття можливостей OpenClaw -| Можливість OpenAI | Поверхня OpenClaw | Статус | +| Можливість OpenAI | Поверхня OpenClaw | Статус | | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | -| Чат / Responses | Провайдер моделей `openai/` | Так | -| Моделі підписки Codex | `openai-codex/` з OAuth `openai-codex` | Так | -| Обв’язка Codex app-server | `openai/` з `agentRuntime.id: codex` | Так | -| Серверний вебпошук | Нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і провайдер не закріплено | -| Зображення | `image_generate` | Так | -| Відео | `video_generate` | Так | -| Text-to-speech | `messages.tts.provider: "openai"` / `tts` | Так | -| Пакетне speech-to-text | `tools.media.audio` / розуміння медіа | Так | -| Потокове speech-to-text | Voice Call `streaming.provider: "openai"` | Так | -| Голос у реальному часі | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так | -| Embeddings | Провайдер embedding для пам’яті | Так | +| Чат / Responses | Провайдер моделі `openai/` | Так | +| Моделі підписки Codex | `openai-codex/` з `openai-codex` OAuth | Так | +| Обв’язка сервера застосунку Codex | `openai/` з `agentRuntime.id: codex` | Так | +| Серверний вебпошук | Нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і провайдера не закріплено | +| Зображення | `image_generate` | Так | +| Відео | `video_generate` | Так | +| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так | +| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так | +| Потокове перетворення мовлення на текст | Голосовий виклик `streaming.provider: "openai"` | Так | +| Голос у реальному часі | Голосовий виклик `realtime.provider: "openai"` / Control UI Talk | Так | +| Ембеддинги | Провайдер ембеддингів пам’яті | Так | -## Embeddings пам’яті +## Ембеддинги пам’яті -OpenClaw може використовувати OpenAI або сумісний з OpenAI endpoint embeddings для індексації `memory_search` і embeddings запитів: +OpenClaw може використовувати OpenAI або OpenAI-сумісну кінцеву точку ембеддингів для +індексації `memory_search` і ембеддингів запитів: ```json5 { @@ -93,7 +112,11 @@ OpenClaw може використовувати OpenAI або сумісний } ``` -Для сумісних з OpenAI endpoint, які потребують асиметричних міток embeddings, задайте `queryInputType` і `documentInputType` у `memorySearch`. OpenClaw передає їх як специфічні для провайдера поля запиту `input_type`: embeddings запитів використовують `queryInputType`; проіндексовані фрагменти пам’яті та пакетна індексація використовують `documentInputType`. Повний приклад див. у [довіднику конфігурації пам’яті](/uk/reference/memory-config#provider-specific-config). +Для OpenAI-сумісних кінцевих точок, яким потрібні асиметричні мітки ембеддингів, установіть +`queryInputType` і `documentInputType` у `memorySearch`. OpenClaw передає +їх як специфічні для провайдера поля запиту `input_type`: ембеддинги запитів використовують +`queryInputType`; індексовані фрагменти пам’яті та пакетна індексація використовують +`documentInputType`. Див. повний приклад у [довіднику конфігурації пам’яті](/uk/reference/memory-config#provider-specific-config). ## Початок роботи @@ -104,10 +127,10 @@ OpenClaw може використовувати OpenAI або сумісний **Найкраще для:** прямого доступу до API та оплати за використання. - + Створіть або скопіюйте ключ API з [панелі OpenAI Platform](https://platform.openai.com/api-keys). - + ```bash openclaw onboard --auth-choice openai-api-key ``` @@ -127,14 +150,17 @@ OpenClaw може використовувати OpenAI або сумісний ### Підсумок маршруту - | Посилання на модель | Конфігурація runtime | Маршрут | Автентифікація | + | Посилання на модель | Конфігурація середовища виконання | Маршрут | Автентифікація | | ---------------------- | -------------------------- | --------------------------- | ---------------- | - | `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Обв’язка Codex app-server | Codex app-server | + | `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | + | `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Обв’язка сервера застосунку Codex | Сервер застосунку Codex | - `openai/*` — це прямий маршрут ключа API OpenAI, якщо ви явно не примусите використання обв’язки Codex app-server. Використовуйте `openai-codex/*` для OAuth Codex через стандартний runner PI або `openai/gpt-5.5` з `agentRuntime.id: "codex"` для нативного виконання Codex app-server. + `openai/*` є прямим маршрутом ключа API OpenAI, якщо ви явно не примусите + обв’язку сервера застосунку Codex. Використовуйте `openai-codex/*` для Codex OAuth через + стандартний раннер PI або використовуйте `openai/gpt-5.5` з + `agentRuntime.id: "codex"` для нативного виконання сервером застосунку Codex. ### Приклад конфігурації @@ -153,10 +179,10 @@ OpenClaw може використовувати OpenAI або сумісний - **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого ключа API. Codex cloud потребує входу ChatGPT. + **Найкраще для:** використання вашої підписки ChatGPT/Codex з нативним виконанням сервером застосунку Codex замість окремого ключа API. Хмара Codex потребує входу в ChatGPT. - + ```bash openclaw onboard --auth-choice openai-codex ``` @@ -167,77 +193,95 @@ OpenClaw може використовувати OpenAI або сумісний openclaw models auth login --provider openai-codex ``` - Для headless-середовищ або налаштувань, де callback незручний, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість callback браузера localhost: + Для безголових налаштувань або середовищ, ворожих до callback, додайте `--device-code`, щоб увійти через потік коду пристрою ChatGPT замість callback браузера localhost: ```bash openclaw models auth login --provider openai-codex --device-code ``` - + ```bash - openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 + openclaw config set plugins.entries.codex '{ enabled: true }' --strict-json --merge + openclaw config set agents.defaults.model.primary openai/gpt-5.5 + openclaw config set agents.defaults.agentRuntime '{ id: "codex", fallback: "none" }' --strict-json ``` - + ```bash openclaw models list --provider openai-codex ``` + + Після запуску gateway надішліть `/codex status` або `/codex models` + у чаті, щоб перевірити нативне середовище виконання сервера застосунку. ### Підсумок маршруту - | Посилання на модель | Конфігурація runtime | Маршрут | Автентифікація | + | Посилання на модель | Конфігурація середовища виконання | Маршрут | Автентифікація | |-----------|----------------|-------|------| - | `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | OAuth ChatGPT/Codex через PI | Вхід Codex | - | `openai-codex/gpt-5.4-mini` | omitted / `runtime: "pi"` | OAuth ChatGPT/Codex через PI | Вхід Codex | - | `openai-codex/gpt-5.5` | `runtime: "auto"` | Усе ще PI, якщо Plugin явно не оголошує `openai-codex` | Вхід Codex | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Обв’язка Codex app-server | Автентифікація Codex app-server | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Нативна обв’язка сервера застосунку Codex | Вхід Codex або вибраний профіль `openai-codex` | + | `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | ChatGPT/Codex OAuth через PI | Вхід Codex | + | `openai-codex/gpt-5.4-mini` | omitted / `runtime: "pi"` | ChatGPT/Codex OAuth через PI | Вхід Codex | + | `openai-codex/gpt-5.5` | `runtime: "auto"` | Усе ще PI, якщо plugin явно не заявляє `openai-codex` | Вхід Codex | - Продовжуйте використовувати id провайдера `openai-codex` для команд автентифікації/профілю. Префікс моделі `openai-codex/*` також є явним маршрутом PI для OAuth Codex. Він не вибирає і не вмикає автоматично вбудовану обв’язку Codex app-server. + Продовжуйте використовувати ідентифікатор провайдера `openai-codex` для команд автентифікації/профілю. Префікс моделі + `openai-codex/*` також є явним маршрутом PI для Codex OAuth. + Він не вибирає й не вмикає автоматично вбудовану обв’язку app-server Codex. Для + поширеного налаштування з підпискою і native runtime увійдіть через + `openai-codex`, але залиште посилання на модель як `openai/gpt-5.5` і задайте + `agentRuntime.id: "codex"`. ### Приклад конфігурації ```json5 { - agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } }, + plugins: { entries: { codex: { enabled: true } } }, + agents: { + defaults: { + model: { primary: "openai/gpt-5.5" }, + agentRuntime: { id: "codex", fallback: "none" }, + }, + }, } ``` + Щоб натомість залишити Codex OAuth на звичайному runner PI, використовуйте + `openai-codex/gpt-5.5` і опустіть перевизначення runtime Codex. + - Onboarding більше не імпортує матеріал OAuth з `~/.codex`. Увійдіть через OAuth у браузері (стандартно) або через потік device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента. + Onboarding більше не імпортує матеріали OAuth із `~/.codex`. Увійдіть через browser OAuth (типово) або через flow device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агентів. - ### Індикатор статусу + ### Індикатор стану - Chat `/status` показує, яке середовище виконання моделі активне для поточного сеансу. - Стандартна обв’язка PI відображається як `Runtime: OpenClaw Pi Default`. Коли вибрано - вбудовану обв’язку Codex app-server, `/status` показує - `Runtime: OpenAI Codex`. Наявні сеанси зберігають записаний ідентифікатор обв’язки, тому використовуйте + Chat `/status` показує, який runtime моделі активний для поточної сесії. + Типова обв’язка PI відображається як `Runtime: OpenClaw Pi Default`. Коли + вибрано вбудовану обв’язку app-server Codex, `/status` показує + `Runtime: OpenAI Codex`. Наявні сесії зберігають записаний ідентифікатор обв’язки, тому використовуйте `/new` або `/reset` після зміни `agentRuntime`, якщо хочете, щоб `/status` відображав новий вибір PI/Codex. - ### Попередження Doctor + ### Попередження doctor - Якщо вбудований Plugin `codex` увімкнено, коли вибрано маршрут - `openai-codex/*` цієї вкладки, `openclaw doctor` попереджає, що модель - досі визначається через PI. Залиште конфігурацію без змін, якщо це - очікуваний маршрут автентифікації за підпискою. Перемикайтеся на `openai/` плюс - `agentRuntime.id: "codex"` лише тоді, коли потрібне нативне виконання - Codex app-server. + Якщо вбудований plugin `codex` увімкнено, коли вибрано маршрут `openai-codex/*`, + `openclaw doctor` попереджає, що модель усе ще resolve через PI. + Залишайте конфігурацію без змін лише тоді, коли цей маршрут автентифікації підписки PI + є навмисним. Перейдіть на `openai/` плюс `agentRuntime.id: "codex"`, коли + потрібне native виконання app-server Codex. - ### Обмеження контекстного вікна + ### Ліміт контекстного вікна - OpenClaw розглядає метадані моделі та обмеження контексту середовища виконання як окремі значення. + OpenClaw розглядає metadata моделі й ліміт runtime context як окремі значення. Для `openai-codex/gpt-5.5` через Codex OAuth: - - Нативний `contextWindow`: `1000000` - - Стандартне обмеження `contextTokens` середовища виконання: `272000` + - Native `contextWindow`: `1000000` + - Типовий ліміт runtime `contextTokens`: `272000` - Менше стандартне обмеження на практиці має кращі характеристики затримки та якості. Перевизначте його за допомогою `contextTokens`: + Менший типовий ліміт на практиці має кращі характеристики затримки та якості. Перевизначте його за допомогою `contextTokens`: ```json5 { @@ -252,24 +296,24 @@ OpenClaw може використовувати OpenAI або сумісний ``` - Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту середовища виконання. + Використовуйте `contextWindow`, щоб оголошувати native metadata моделі. Використовуйте `contextTokens`, щоб обмежувати бюджет runtime context. ### Відновлення каталогу - OpenClaw використовує метадані upstream-каталогу Codex для `gpt-5.5`, коли вони - наявні. Якщо live-виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, коли + OpenClaw використовує upstream metadata каталогу Codex для `gpt-5.5`, коли вона + присутня. Якщо live discovery Codex пропускає рядок `openai-codex/gpt-5.5`, коли обліковий запис автентифіковано, OpenClaw синтезує цей рядок моделі OAuth, щоб - cron, субагент і запуски зі сконфігурованою стандартною моделлю не завершувалися помилкою + cron, sub-agent і запуски з налаштованою типовою моделлю не завершувалися помилкою `Unknown model`. -## Нативна автентифікація Codex app-server +## Native автентифікація app-server Codex -Нативна обв’язка Codex app-server використовує посилання на моделі `openai/*` плюс -`agentRuntime.id: "codex"`, але її автентифікація все одно прив’язана до облікового запису. OpenClaw +Native обв’язка app-server Codex використовує посилання на моделі `openai/*` плюс +`agentRuntime.id: "codex"`, але її автентифікація все одно базується на обліковому записі. OpenClaw вибирає автентифікацію в такому порядку: 1. Явний профіль автентифікації OpenClaw `openai-codex`, прив’язаний до агента. @@ -278,29 +322,29 @@ OpenClaw може використовувати OpenAI або сумісний `OPENAI_API_KEY`, коли app-server повідомляє, що облікового запису немає, але все ще потребує автентифікації OpenAI. -Це означає, що локальний вхід за підпискою ChatGPT/Codex не замінюється лише -через те, що процес Gateway також має `OPENAI_API_KEY` для прямих моделей OpenAI -або embeddings. Резервний env API-ключ використовується лише для локального stdio-шляху без облікового запису; він -не надсилається до WebSocket-з’єднань app-server. Коли вибрано профіль Codex -підпискового типу, OpenClaw також не передає `CODEX_API_KEY` і `OPENAI_API_KEY` +Це означає, що локальний вхід із підпискою ChatGPT/Codex не замінюється лише +через те, що процес gateway також має `OPENAI_API_KEY` для прямих моделей OpenAI +або embeddings. Fallback через env API-key — це лише локальний шлях stdio без облікового запису; його +не надсилають до WebSocket-з’єднань app-server. Коли вибрано профіль Codex +у стилі підписки, OpenClaw також не передає `CODEX_API_KEY` і `OPENAI_API_KEY` у породжений дочірній процес stdio app-server і надсилає вибрані облікові дані -через RPC входу app-server. +через login RPC app-server. -## Генерування зображень +## Генерація зображень -Вбудований Plugin `openai` реєструє генерування зображень через інструмент `image_generate`. -Він підтримує як генерування зображень за API-ключем OpenAI, так і генерування зображень через Codex OAuth +Вбудований plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. +Він підтримує як генерацію зображень за OpenAI API-key, так і генерацію зображень через Codex OAuth через те саме посилання на модель `openai/gpt-image-2`. -| Можливість | API-ключ OpenAI | Codex OAuth | +| Можливість | OpenAI API key | Codex OAuth | | ------------------------ | ---------------------------------- | ------------------------------------ | | Посилання на модель | `openai/gpt-image-2` | `openai/gpt-image-2` | -| Автентифікація | `OPENAI_API_KEY` | Вхід через OpenAI Codex OAuth | +| Автентифікація | `OPENAI_API_KEY` | Вхід OpenAI Codex OAuth | | Транспорт | OpenAI Images API | Backend Codex Responses | | Макс. зображень на запит | 4 | 4 | -| Режим редагування | Увімкнено (до 5 референсних зображень) | Увімкнено (до 5 референсних зображень) | -| Перевизначення розміру | Підтримується, зокрема розміри 2K/4K | Підтримується, зокрема розміри 2K/4K | -| Співвідношення сторін / роздільна здатність | Не передається до OpenAI Images API | Зіставляється з підтримуваним розміром, коли це безпечно | +| Режим редагування | Увімкнено (до 5 reference images) | Увімкнено (до 5 reference images) | +| Перевизначення розміру | Підтримуються, включно з розмірами 2K/4K | Підтримуються, включно з розмірами 2K/4K | +| Aspect ratio / resolution | Не передається до OpenAI Images API | Зіставляється з підтримуваним розміром, коли це безпечно | ```json5 { @@ -313,24 +357,24 @@ OpenClaw може використовувати OpenAI або сумісний ``` -Див. [Генерування зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. +Див. [Генерація зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. -`gpt-image-2` є стандартним для генерування зображень із тексту OpenAI і для редагування зображень. -`gpt-image-1.5`, `gpt-image-1` і `gpt-image-1-mini` лишаються доступними як -явні перевизначення моделі. Використовуйте `openai/gpt-image-1.5` для виводу -PNG/WebP із прозорим фоном; поточний API `gpt-image-2` відхиляє +`gpt-image-2` є типовим для генерації OpenAI text-to-image і редагування зображень. +`gpt-image-1.5`, `gpt-image-1` і `gpt-image-1-mini` залишаються придатними як +явні перевизначення моделі. Використовуйте `openai/gpt-image-1.5` для виводу PNG/WebP +із прозорим фоном; поточний API `gpt-image-2` відхиляє `background: "transparent"`. Для запиту з прозорим фоном агенти мають викликати `image_generate` з `model: "openai/gpt-image-1.5"`, `outputFormat: "png"` або `"webp"` і `background: "transparent"`; старіший параметр провайдера `openai.background` -досі приймається. OpenClaw також захищає публічні маршрути OpenAI та -OpenAI Codex OAuth, переписуючи стандартні прозорі запити `openai/gpt-image-2` -на `gpt-image-1.5`; Azure і власні OpenAI-сумісні endpoints зберігають -сконфігуровані назви deployment/моделей. +досі приймається. OpenClaw також захищає публічні маршрути OpenAI і +OpenAI Codex OAuth, переписуючи типові прозорі запити `openai/gpt-image-2` +на `gpt-image-1.5`; Azure і користувацькі OpenAI-сумісні endpoints зберігають +свої налаштовані deployment/model names. -Той самий параметр доступний для headless-запусків CLI: +Те саме налаштування доступне для headless запусків CLI: ```bash openclaw infer image generate \ @@ -342,19 +386,18 @@ openclaw infer image generate \ ``` Використовуйте ті самі прапорці `--output-format` і `--background` з -`openclaw infer image edit`, коли починаєте з вхідного файлу. -`--openai-background` лишається доступним як специфічний для OpenAI псевдонім. +`openclaw infer image edit`, коли починаєте з input file. +`--openai-background` залишається доступним як alias, специфічний для OpenAI. Для встановлень Codex OAuth залишайте те саме посилання `openai/gpt-image-2`. Коли -налаштовано OAuth-профіль `openai-codex`, OpenClaw визначає збережений access token OAuth +налаштовано профіль OAuth `openai-codex`, OpenClaw resolve збережений access token OAuth і надсилає запити зображень через backend Codex Responses. Він -спершу не пробує `OPENAI_API_KEY` і не виконує тихий fallback до API-ключа для цього -запиту. Налаштуйте `models.providers.openai` явно з API-ключем, -власною базовою URL-адресою або endpoint Azure, коли потрібен прямий маршрут OpenAI Images API -натомість. -Якщо цей власний endpoint зображень розташований у довіреній LAN/приватній адресі, також задайте +не пробує спершу `OPENAI_API_KEY` і не виконує тихий fallback до API key для цього +запиту. Явно налаштуйте `models.providers.openai` з API key, +користувацьким base URL або Azure endpoint, коли натомість потрібен прямий маршрут OpenAI Images API. +Якщо цей користувацький image endpoint розташований у довіреній LAN/приватній адресі, також задайте `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw залишає -приватні/внутрішні OpenAI-сумісні endpoints зображень заблокованими, якщо цього opt-in +приватні/внутрішні OpenAI-сумісні image endpoints заблокованими, якщо цього opt-in немає. Згенерувати: @@ -375,16 +418,16 @@ openclaw infer image generate \ /tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 ``` -## Генерування відео +## Генерація відео -Вбудований Plugin `openai` реєструє генерування відео через інструмент `video_generate`. +Вбудований plugin `openai` реєструє генерацію відео через інструмент `video_generate`. | Можливість | Значення | | ---------------- | --------------------------------------------------------------------------------- | -| Стандартна модель | `openai/sora-2` | -| Режими | Текст-у-відео, зображення-у-відео, редагування одного відео | -| Референсні вхідні дані | 1 зображення або 1 відео | -| Перевизначення розміру | Підтримується | +| Типова модель | `openai/sora-2` | +| Режими | Text-to-video, image-to-video, single-video edit | +| Reference inputs | 1 зображення або 1 відео | +| Перевизначення розміру | Підтримуються | | Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента | ```json5 @@ -398,22 +441,22 @@ openclaw infer image generate \ ``` -Див. [Генерування відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. +Див. [Генерація відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. -## Внесок GPT-5 у prompt +## Внесок промпта GPT-5 -OpenClaw додає спільний внесок GPT-5 у prompt для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x не отримують. +OpenClaw додає спільний внесок промпта GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за model id, тому `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x — ні. -Вбудована нативна обв’язка Codex використовує ту саму поведінку GPT-5 і overlay Heartbeat через інструкції розробника Codex app-server, тому сеанси `openai/gpt-5.x`, примусово спрямовані через `agentRuntime.id: "codex"`, зберігають ті самі настанови щодо доведення справ до кінця й проактивного Heartbeat, хоча рештою prompt обв’язки керує Codex. +Вбудована native обв’язка Codex використовує ту саму поведінку GPT-5 і overlay heartbeat через developer instructions app-server Codex, тому сесії `openai/gpt-5.x`, примусово спрямовані через `agentRuntime.id: "codex"`, зберігають ті самі настанови follow-through і проактивного heartbeat, хоча Codex володіє рештою промпта обв’язки. -Внесок GPT-5 додає тегований контракт поведінки для збереження persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей, специфічна для каналу, і поведінка silent-message лишаються у спільному системному prompt OpenClaw і політиці вихідної доставки. Настанови GPT-5 завжди увімкнені для відповідних моделей. Дружній шар стилю взаємодії є окремим і налаштовуваним. +Внесок GPT-5 додає tagged behavior contract для збереження persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Channel-specific поведінка відповідей і silent-message залишається у спільному system prompt OpenClaw і outbound delivery policy. Настанови GPT-5 завжди увімкнені для відповідних моделей. Friendly interaction-style layer є окремим і налаштовуваним. -| Значення | Ефект | -| --------------------- | ------------------------------------------ | -| `"friendly"` (стандартно) | Увімкнути дружній шар стилю взаємодії | -| `"on"` | Псевдонім для `"friendly"` | -| `"off"` | Вимкнути лише дружній шар стилю | +| Значення | Ефект | +| ---------------------- | ------------------------------------------ | +| `"friendly"` (типово) | Увімкнути friendly interaction-style layer | +| `"on"` | Alias для `"friendly"` | +| `"off"` | Вимкнути лише friendly style layer | @@ -437,33 +480,33 @@ OpenClaw додає спільний внесок GPT-5 у prompt для зап -Значення не чутливі до регістру під час виконання, тому `"Off"` і `"off"` обидва вимикають дружній шар стилю. +Під час runtime значення не залежать від регістру, тому `"Off"` і `"off"` обидва вимикають friendly style layer. -Застарілий `plugins.entries.openai.config.personality` досі читається як fallback сумісності, коли спільний параметр `agents.defaults.promptOverlays.gpt5.personality` не задано. +Застарілий `plugins.entries.openai.config.personality` досі читається як compatibility fallback, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. ## Голос і мовлення - Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. + Вбудований plugin `openai` реєструє синтез мовлення для surface `messages.tts`. - | Параметр | Шлях конфігурації | Стандартно | + | Налаштування | Шлях конфігурації | Типово | |---------|------------|---------| | Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | | Голос | `messages.tts.providers.openai.voice` | `coral` | | Швидкість | `messages.tts.providers.openai.speed` | (не задано) | | Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) | | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів | - | API-ключ | `messages.tts.providers.openai.apiKey` | fallback до `OPENAI_API_KEY` | - | Базова URL-адреса | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | + | API-ключ | `messages.tts.providers.openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | + | Базовий URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | | Додаткове тіло | `messages.tts.providers.openai.extraBody` / `extra_body` | (не задано) | Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`. - `extraBody` об’єднується з JSON запиту `/audio/speech` після згенерованих OpenClaw полів, тому використовуйте його для OpenAI-сумісних endpoints, які потребують додаткових ключів, як-от `lang`. Prototype-ключі ігноруються. + `extraBody` об’єднується з JSON запиту `/audio/speech` після полів, згенерованих OpenClaw, тому використовуйте його для OpenAI-сумісних кінцевих точок, які потребують додаткових ключів, як-от `lang`. Ключі прототипу ігноруються. ```json5 { @@ -478,23 +521,23 @@ OpenClaw додає спільний внесок GPT-5 у prompt для зап ``` - Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базову URL-адресу TTS, не впливаючи на endpoint chat API. + Задайте `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на кінцеву точку API чату. - Вбудований Plugin `openai` реєструє пакетне перетворення мовлення в текст через - поверхню транскрипції media-understanding OpenClaw. + Вбудований plugin `openai` реєструє пакетне перетворення мовлення в текст через + поверхню транскрипції для розуміння медіа в OpenClaw. - - Стандартна модель: `gpt-4o-transcribe` + - Типова модель: `gpt-4o-transcribe` - Кінцева точка: OpenAI REST `/v1/audio/transcriptions` - Шлях введення: завантаження аудіофайлу multipart - - Підтримується OpenClaw усюди, де транскрибування вхідного аудіо використовує - `tools.media.audio`, зокрема сегменти голосових каналів Discord і - аудіовкладення каналів + - Підтримується OpenClaw всюди, де вхідна аудіотранскрипція використовує + `tools.media.audio`, зокрема сегменти голосових каналів Discord і аудіовкладення + каналів - Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо: + Щоб примусово використовувати OpenAI для транскрипції вхідного аудіо: ```json5 { @@ -514,53 +557,53 @@ OpenClaw додає спільний внесок GPT-5 у prompt для зап } ``` - Підказки щодо мови та промпта передаються до OpenAI, коли їх надає - спільна конфігурація аудіомедіа або запит транскрибування окремого виклику. + Підказки мови та промпта передаються в OpenAI, коли їх надано через + спільну конфігурацію аудіомедіа або запит транскрипції для окремого виклику. - - Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call. + + Вбудований plugin `openai` реєструє транскрипцію в реальному часі для Voice Call plugin. - | Налаштування | Шлях конфігурації | Стандартне значення | + | Налаштування | Шлях конфігурації | Типово | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | - | Мова | `...openai.language` | (не встановлено) | - | Промпт | `...openai.prompt` | (не встановлено) | + | Мова | `...openai.language` | (не задано) | + | Промпт | `...openai.prompt` | (не задано) | | Тривалість тиші | `...openai.silenceDurationMs` | `800` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | - | Ключ API | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант | + | API-ключ | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | - Використовує з'єднання WebSocket із `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрибування в реальному часі Voice Call; голос Discord наразі записує короткі сегменти й натомість використовує пакетний шлях транскрибування `tools.media.audio`. + Використовує WebSocket-з’єднання з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрипції в реальному часі Voice Call; голос Discord наразі записує короткі сегменти й натомість використовує пакетний шлях транскрипції `tools.media.audio`. - Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call. + Вбудований plugin `openai` реєструє голос у реальному часі для Voice Call plugin. - | Налаштування | Шлях конфігурації | Стандартне значення | + | Налаштування | Шлях конфігурації | Типово | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | | Голос | `...openai.voice` | `alloy` | | Температура | `...openai.temperature` | `0.8` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | | Тривалість тиші | `...openai.silenceDurationMs` | `500` | - | Ключ API | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант | + | API-ключ | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | - Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment` для серверних мостів реального часу. Підтримує двоспрямовані виклики інструментів. Використовує аудіоформат G.711 u-law. + Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment` для бекенд-мостів реального часу. Підтримує двонапрямлені виклики інструментів. Використовує аудіоформат G.711 u-law. Control UI Talk використовує браузерні сесії OpenAI у реальному часі з - ефемерним клієнтським секретом, створеним Gateway, і прямим браузерним обміном WebRTC SDP з - OpenAI Realtime API. Жива перевірка для супровідників доступна через + ефемерним клієнтським секретом, виданим Gateway, і прямим браузерним обміном WebRTC SDP з + OpenAI Realtime API. Жива перевірка супровідником доступна через `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`; - гілка OpenAI створює клієнтський секрет у Node, генерує браузерну пропозицію SDP - з фейковим мікрофонним медіа, надсилає її до OpenAI і застосовує відповідь SDP - без логування секретів. + гілка OpenAI створює клієнтський секрет у Node, генерує браузерну SDP-пропозицію + з фіктивним медіа мікрофона, надсилає її в OpenAI і застосовує SDP-відповідь + без журналювання секретів. @@ -569,27 +612,27 @@ OpenClaw додає спільний внесок GPT-5 у prompt для зап ## Кінцеві точки Azure OpenAI Вбудований провайдер `openai` може націлюватися на ресурс Azure OpenAI для генерації -зображень через перевизначення базової URL-адреси. На шляху генерації зображень OpenClaw +зображень шляхом перевизначення базового URL. На шляху генерації зображень OpenClaw виявляє імена хостів Azure у `models.providers.openai.baseUrl` і автоматично перемикається на форму запиту Azure. Голос у реальному часі використовує окремий шлях конфігурації (`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) -і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у реальному -часі** в розділі [Голос і мовлення](#voice-and-speech) щодо його налаштувань Azure. +і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у реальному часі** +у розділі [Голос і мовлення](#voice-and-speech) для його налаштувань Azure. Використовуйте Azure OpenAI, коли: -- У вас уже є підписка Azure OpenAI, квота або корпоративна угода +- У вас уже є передплата Azure OpenAI, квота або корпоративна угода - Вам потрібні регіональне розміщення даних або засоби контролю відповідності, які надає Azure -- Ви хочете залишити трафік усередині наявного тенанта Azure +- Ви хочете утримувати трафік у межах наявного тенанту Azure ### Конфігурація -Для генерації зображень Azure через вбудований провайдер `openai` спрямуйте -`models.providers.openai.baseUrl` на свій ресурс Azure і встановіть `apiKey` як +Для генерації зображень Azure через вбудований провайдер `openai` вкажіть +`models.providers.openai.baseUrl` на ваш ресурс Azure і задайте `apiKey` як ключ Azure OpenAI (не ключ OpenAI Platform): ```json5 @@ -605,8 +648,7 @@ OpenClaw додає спільний внесок GPT-5 у prompt для зап } ``` -OpenClaw розпізнає ці суфікси хостів Azure для маршруту генерації зображень -Azure: +OpenClaw розпізнає ці суфікси хостів Azure для маршруту генерації зображень Azure: - `*.openai.azure.com` - `*.services.ai.azure.com` @@ -615,73 +657,73 @@ Azure: Для запитів генерації зображень на розпізнаному хості Azure OpenClaw: - Надсилає заголовок `api-key` замість `Authorization: Bearer` -- Використовує шляхи з областю deployment (`/openai/deployments/{deployment}/...`) +- Використовує шляхи з областю розгортання (`/openai/deployments/{deployment}/...`) - Додає `?api-version=...` до кожного запиту -- Використовує стандартний тайм-аут запиту 600 с для викликів генерації зображень Azure. - Значення `timeoutMs` для окремого виклику й далі перевизначають це стандартне значення. +- Використовує типовий тайм-аут запиту 600 с для викликів генерації зображень Azure. + Значення `timeoutMs` для окремого виклику все одно перевизначають це типове значення. -Інші базові URL-адреси (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартну +Інші базові URL (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартну форму запиту зображень OpenAI. Маршрутизація Azure для шляху генерації зображень провайдера `openai` потребує OpenClaw 2026.4.22 або новішої версії. Раніші версії обробляють будь-який користувацький -`openai.baseUrl` як публічну кінцеву точку OpenAI і завершаться помилкою з -deployment зображень Azure. +`openai.baseUrl` як публічну кінцеву точку OpenAI і зазнають помилки з розгортаннями +зображень Azure. ### Версія API -Встановіть `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview- або GA-версію Azure +Задайте `AZURE_OPENAI_API_VERSION`, щоб закріпити конкретну preview- або GA-версію Azure для шляху генерації зображень Azure: ```bash export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` -Стандартне значення — `2024-12-01-preview`, коли змінну не встановлено. +Типове значення — `2024-12-01-preview`, коли змінну не задано. -### Назви моделей є назвами deployment +### Імена моделей є іменами розгортань -Azure OpenAI прив'язує моделі до deployment. Для запитів генерації зображень Azure, +Azure OpenAI прив’язує моделі до розгортань. Для запитів генерації зображень Azure, маршрутизованих через вбудований провайдер `openai`, поле `model` в OpenClaw -має бути **назвою deployment Azure**, яку ви налаштували на порталі Azure, а не -ідентифікатором публічної моделі OpenAI. +має бути **іменем розгортання Azure**, яке ви налаштували на порталі Azure, а не +публічним id моделі OpenAI. -Якщо ви створюєте deployment із назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`: +Якщо ви створюєте розгортання з назвою `gpt-image-2-prod`, яке обслуговує `gpt-image-2`: ``` /tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 ``` -Те саме правило назви deployment застосовується до викликів генерації зображень, -маршрутизованих через вбудований провайдер `openai`. +Те саме правило імені розгортання застосовується до викликів генерації зображень, маршрутизованих через +вбудований провайдер `openai`. ### Регіональна доступність -Генерація зображень Azure наразі доступна лише в частині регіонів +Генерація зображень Azure наразі доступна лише в підмножині регіонів (наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`, -`uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням -deployment і підтвердьте, що конкретна модель пропонується у вашому регіоні. +`uaenorth`). Перевірте поточний список регіонів Microsoft перед створенням +розгортання та підтвердьте, що конкретна модель пропонується у вашому регіоні. ### Відмінності параметрів Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень. Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні -значення `background` для `gpt-image-2`), або надавати їх лише для конкретних версій -моделі. Ці відмінності походять від Azure і базової моделі, а не від -OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте -набір параметрів, який підтримують ваш конкретний deployment і версія API на +значення `background` на `gpt-image-2`), або надавати їх лише в окремих версіях +моделей. Ці відмінності походять від Azure і базової моделі, а не від +OpenClaw. Якщо запит Azure зазнає помилки перевірки, перевірте +набір параметрів, підтримуваний вашим конкретним розгортанням і версією API, на порталі Azure. -Azure OpenAI використовує нативний транспорт і compat-поведінку, але не отримує +Azure OpenAI використовує нативний транспорт і сумісну поведінку, але не отримує прихованих заголовків атрибуції OpenClaw — див. акордеон **Нативні та OpenAI-сумісні -маршрути** в розділі [Розширена конфігурація](#advanced-configuration). +маршрути** у розділі [Розширена конфігурація](#advanced-configuration). -Для трафіку chat або Responses в Azure (поза генерацією зображень) використовуйте -процес onboarding або спеціальну конфігурацію провайдера Azure — самого лише -`openai.baseUrl` недостатньо, щоб застосувати форму Azure API/auth. Існує окремий +Для трафіку чату або Responses в Azure (поза генерацією зображень) використовуйте +процес онбордингу або спеціальну конфігурацію провайдера Azure — одного лише `openai.baseUrl` +недостатньо, щоб підхопити форму API/автентифікації Azure. Існує окремий провайдер `azure-openai-responses/*`; див. акордеон Server-side compaction нижче. @@ -689,17 +731,17 @@ Azure OpenAI використовує нативний транспорт і com - OpenClaw використовує WebSocket як пріоритетний варіант із запасним SSE (`"auto"`) для `openai/*` і `openai-codex/*`. + OpenClaw використовує підхід WebSocket-first із резервним SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. У режимі `"auto"` OpenClaw: - - Повторює одну ранню невдалу спробу WebSocket перед переходом на SSE - - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження - - Додає стабільні заголовки ідентичності сесії та turn для повторних спроб і повторних підключень + - Повторює одну ранню помилку WebSocket перед переходом на SSE + - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час періоду охолодження + - Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і повторних підключень - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту | Значення | Поведінка | |-------|----------| - | `"auto"` (стандартно) | Спочатку WebSocket, SSE як запасний варіант | + | `"auto"` (типово) | Спочатку WebSocket, резервно SSE | | `"sse"` | Примусово лише SSE | | `"websocket"` | Примусово лише WebSocket | @@ -720,14 +762,14 @@ Azure OpenAI використовує нативний транспорт і com } ``` - Пов'язані документи OpenAI: + Пов’язані документи OpenAI: - [Realtime API з WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) - [Потокові відповіді API (SSE)](https://platform.openai.com/docs/guides/streaming-responses) - - OpenClaw стандартно вмикає прогрівання WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого turn. + + OpenClaw вмикає прогрів WebSocket типово для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу. ```json5 // Disable warm-up @@ -749,10 +791,10 @@ Azure OpenAI використовує нативний транспорт і com OpenClaw надає спільний перемикач швидкого режиму для `openai/*` і `openai-codex/*`: - - **Chat/UI:** `/fast status|on|off` + - **Чат/UI:** `/fast status|on|off` - **Конфігурація:** `agents.defaults.models["/"].params.fastMode` - Коли його ввімкнено, OpenClaw відображає швидкий режим на пріоритетну обробку OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`. + Коли ввімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, і швидкий режим не переписує `reasoning` або `text.verbosity`. ```json5 { @@ -767,13 +809,13 @@ Azure OpenAI використовує нативний транспорт і com ``` - Перевизначення сесії мають перевагу над конфігурацією. Очищення перевизначення сесії в Sessions UI повертає сесію до налаштованого стандартного значення. + Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого типового значення. - API OpenAI надає пріоритетну обробку через `service_tier`. Встановіть її для кожної моделі в OpenClaw: + API OpenAI надає пріоритетну обробку через `service_tier`. Задайте її для кожної моделі в OpenClaw: ```json5 { @@ -790,19 +832,19 @@ Azure OpenAI використовує нативний транспорт і com Підтримувані значення: `auto`, `default`, `flex`, `priority`. - `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з провайдерів через проксі, OpenClaw залишає `service_tier` без змін. + `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви спрямовуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін. - Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) потокова обгортка Pi-harness Plugin OpenAI автоматично вмикає серверну Compaction: + Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) обгортка потоку Pi-harness Plugin OpenAI автоматично вмикає серверну Compaction: - - Примусово встановлює `store: true` (якщо model compat не встановлює `supportsStore: false`) - - Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]` - - Стандартне значення `compact_threshold`: 70% від `contextWindow` (або `80000`, коли недоступно) + - Примусово встановлює `store: true` (якщо сумісність моделі не встановлює `supportsStore: false`) + - Додає `context_management: [{ type: "compaction", compact_threshold: ... }]` + - Типове значення `compact_threshold`: 70% від `contextWindow` (або `80000`, коли недоступно) - Це застосовується до вбудованого шляху Pi harness і до hooks провайдера OpenAI, які використовують вбудовані запуски. Нативний app-server harness Codex керує власним контекстом через Codex і налаштовується окремо за допомогою `agents.defaults.agentRuntime.id`. + Це застосовується до вбудованого шляху Pi harness і до хуків провайдера OpenAI, які використовуються вбудованими запусками. Нативний harness сервера застосунку Codex керує власним контекстом через Codex і налаштовується окремо за допомогою `agents.defaults.agentRuntime.id`. @@ -858,13 +900,13 @@ Azure OpenAI використовує нативний транспорт і com - `responsesServerCompaction` керує лише інʼєкцією `context_management`. Прямі моделі OpenAI Responses усе одно примусово використовують `store: true`, якщо шар сумісності не встановлює `supportsStore: false`. + `responsesServerCompaction` керує лише додаванням `context_management`. Прямі моделі OpenAI Responses все одно примусово встановлюють `store: true`, якщо сумісність не встановлює `supportsStore: false`. - - Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати строгіший вбудований контракт виконання: + + Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший контракт вбудованого виконання: ```json5 { @@ -878,32 +920,32 @@ Azure OpenAI використовує нативний транспорт і com З `strict-agentic` OpenClaw: - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента - - Повторює хід зі скеровуванням діяти зараз + - Повторює хід із вказівкою діяти зараз - Автоматично вмикає `update_plan` для суттєвої роботи - Показує явний заблокований стан, якщо модель продовжує планувати без дій - Обмежено лише запусками сімейства OpenAI і Codex GPT-5. Інші провайдери та старіші сімейства моделей зберігають типову поведінку. + Застосовується лише до запусків OpenAI і Codex сімейства GPT-5. Інші провайдери та старіші сімейства моделей зберігають типову поведінку. - - OpenClaw обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI інакше, ніж універсальні OpenAI-сумісні проксі `/v1`: + + OpenClaw обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI інакше, ніж загальні OpenAI-сумісні проксі `/v1`: **Нативні маршрути** (`openai/*`, Azure OpenAI): - - Зберігають `reasoning: { effort: "none" }` лише для моделей, що підтримують рівень зусиль OpenAI `none` + - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують зусилля OpenAI `none` - Пропускають вимкнене міркування для моделей або проксі, які відхиляють `reasoning.effort: "none"` - - Типово використовують строгий режим для схем інструментів + - За замовчуванням переводять схеми інструментів у суворий режим - Додають приховані заголовки атрибуції лише на перевірених нативних хостах - - Зберігають формування запитів, специфічне лише для OpenAI (`service_tier`, `store`, сумісність міркування, підказки кешу промптів) + - Зберігають формування запитів лише для OpenAI (`service_tier`, `store`, сумісність reasoning, підказки кешу промптів) **Проксі/сумісні маршрути:** - - Використовують вільнішу поведінку сумісності - - Вилучають Completions `store` з ненативних корисних навантажень `openai-completions` + - Використовують менш сувору поведінку сумісності + - Видаляють Completions `store` з ненативних payload `openai-completions` - Приймають розширений наскрізний JSON `params.extra_body`/`params.extraBody` для OpenAI-сумісних проксі Completions - - Приймають `params.chat_template_kwargs` для OpenAI-сумісних проксі Completions, таких як vLLM - - Не примушують строгі схеми інструментів або лише нативні заголовки + - Приймають `params.chat_template_kwargs` для OpenAI-сумісних проксі Completions, як-от vLLM + - Не примушують суворі схеми інструментів або заголовки лише для нативних маршрутів Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує приховані заголовки атрибуції. @@ -914,7 +956,7 @@ Azure OpenAI використовує нативний транспорт і com - Вибір провайдерів, посилань на моделі та поведінки відновлення після збою. + Вибір провайдерів, посилань на моделі та поведінки відмовостійкого перемикання. Спільні параметри інструмента зображень і вибір провайдера.