diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index 3dc255774..0358d011c 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,90 +1,81 @@ --- read_when: - - Вам потрібен довідник із налаштування моделей для кожного провайдера отдельно - - Ви хочете приклади конфігурацій або команди CLI-онбордингу для провайдерів моделей -summary: Огляд провайдерів моделей із прикладами конфігурацій + CLI-процесами -title: Провайдери моделей + - Потрібен довідник із налаштування моделей для кожного постачальника окремо + - Вам потрібні приклади конфігурацій або команди онбордингу CLI для постачальників моделей +summary: Огляд постачальника моделей із прикладами конфігурацій + потоками CLI +title: Постачальники моделей x-i18n: - generated_at: "2026-04-24T03:44:20Z" + generated_at: "2026-04-24T05:42:13Z" model: gpt-5.4 provider: openai - source_hash: ce2fc2b932ddc5d5b6066b70c4b0090868ad450e193f48d89daee9e65ceb9200 + source_hash: ac9bf48897446576d8bc339b340295691741a589863bb57b379c17a5519bffd7 source_path: concepts/model-providers.md workflow: 15 --- -Ця сторінка охоплює **провайдерів LLM/моделей** (а не чат-канали на кшталт WhatsApp/Telegram). +Ця сторінка охоплює **постачальників LLM/моделей** (а не чат-канали на кшталт WhatsApp/Telegram). Правила вибору моделей див. у [/concepts/models](/uk/concepts/models). ## Швидкі правила -- Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`). -- `agents.defaults.models` працює як allowlist, якщо задано. -- Допоміжні CLI-команди: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `contextTokens` — це фактичне обмеження runtime. -- Правила резервного перемикання, cooldown probes і збереження перевизначень сесії: [Model failover](/uk/concepts/model-failover). -- Маршрути сімейства OpenAI залежать від префікса: `openai/` використовує прямого провайдера API-ключа - OpenAI у PI, `openai-codex/` використовує Codex OAuth у PI, - а `openai/` плюс `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний harness app-server Codex. Див. [OpenAI](/uk/providers/openai) - і [Codex harness](/uk/plugins/codex-harness). -- GPT-5.5 наразі доступний через маршрути підписки/OAuth: - `openai-codex/gpt-5.5` у PI або `openai/gpt-5.5` з harness app-server Codex. - Прямий маршрут API-ключа для `openai/gpt-5.5` підтримується, щойно - OpenAI увімкне GPT-5.5 у публічному API; до того часу використовуйте моделі з увімкненим API, - як-от `openai/gpt-5.4`, для конфігурацій `OPENAI_API_KEY`. +- Посилання на моделі використовують `provider/model` (приклад: `opencode/claude-opus-4-6`). +- `agents.defaults.models` працює як allowlist, коли його задано. +- Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. +- `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `contextTokens` — це фактичне обмеження середовища виконання. +- Правила резервного перемикання, перевірки cooldown і збереження перевизначень сеансу: [Відмовостійкість моделей](/uk/concepts/model-failover). +- Маршрути сімейства OpenAI залежать від префікса: `openai/` використовує прямого постачальника API-ключа OpenAI у PI, `openai-codex/` використовує OAuth Codex у PI, а `openai/` разом із `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний harness app-server Codex. Див. [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). +- Автоматичне ввімкнення Plugin дотримується цієї ж межі: `openai-codex/` належить до Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/`. +- GPT-5.5 наразі доступна через маршрути підписки/OAuth: `openai-codex/gpt-5.5` у PI або `openai/gpt-5.5` з harness app-server Codex. Прямий маршрут API-ключа для `openai/gpt-5.5` підтримується, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу використовуйте моделі з доступом через API, як-от `openai/gpt-5.4`, для конфігурацій `OPENAI_API_KEY`. -## Поведінка провайдерів, що належить Plugin +## Поведінка постачальників, що належить Plugin -Більшість логіки, специфічної для провайдера, живе в Plugin провайдерів (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл інференсу. Plugins відповідають за онбординг, каталоги моделей, зіставлення auth env var, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітність про використання, профілі thinking/reasoning тощо. +Більшість специфічної для постачальника логіки живе в Plugin постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл інференсу. Plugin відповідають за онбординг, каталоги моделей, зіставлення auth env-var, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітування про використання, профілі thinking/reasoning тощо. -Повний список хуків provider-SDK і приклади вбудованих Plugins наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Провайдер, якому потрібен повністю кастомний виконавець запитів, — це окрема, глибша поверхня розширення. +Повний список хуків provider-SDK і приклади вбудованих Plugin наведено в [Plugin постачальників](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю власний виконавець запитів, є окремою, глибшою поверхнею розширення. -`capabilities` runtime провайдера — це спільні метадані runner (сімейство провайдера, особливості transcript/tooling, підказки для transport/cache). Це не те саме, що [public capability model](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий інференс, мовлення тощо). +Runtime `capabilities` постачальника — це спільні метадані раннера (сімейство постачальника, особливості transcript/tooling, підказки для транспорту/кешу). Це не те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий інференс, мовлення тощо). ## Ротація API-ключів -- Підтримується загальна ротація ключів провайдерів для вибраних провайдерів. +- Підтримує загальну ротацію постачальників для вибраних постачальників. - Налаштуйте кілька ключів через: - `OPENCLAW_LIVE__KEY` (одне live-перевизначення, найвищий пріоритет) - `_API_KEYS` (список через кому або крапку з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) -- Для Google провайдерів `GOOGLE_API_KEY` також включається як резервний варіант. +- Для постачальників Google як fallback також включається `GOOGLE_API_KEY`. - Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень. -- Запити повторюються з наступним ключем лише у відповідь на rate-limit - (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +- Запити повторюються з наступним ключем лише у відповідь на rate-limit помилки (наприклад, `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). -- Помилки, не пов’язані з rate-limit, одразу завершуються помилкою; ротація ключів не виконується. -- Коли всі кандидатні ключі не спрацьовують, повертається фінальна помилка з останньої спроби. +- Помилки, не пов’язані з rate-limit, завершуються негайно; ротація ключів не виконується. +- Коли всі доступні ключі не спрацьовують, повертається фінальна помилка з останньої спроби. -## Вбудовані провайдери (каталог pi-ai) +## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi‑ai. Для цих провайдерів **не** -потрібна конфігурація `models.providers`; достатньо задати auth + вибрати модель. +OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна** +конфігурація `models.providers`; достатньо налаштувати auth і вибрати модель. ### OpenAI -- Провайдер: `openai` +- Постачальник: `openai` - Auth: `OPENAI_API_KEY` - Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) - Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-mini` -- Пряма підтримка GPT-5.5 через API тут готова на майбутнє, щойно OpenAI відкриє GPT-5.5 в API +- Пряма підтримка API для GPT-5.5 тут готова заздалегідь, щойно OpenAI відкриє GPT-5.5 в API - CLI: `openclaw onboard --auth-choice openai-api-key` -- Типовий transport — `auto` (спочатку WebSocket, резервно SSE) +- Типовий транспорт — `auto` (спочатку WebSocket, fallback на SSE) - Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Розігрів WebSocket для OpenAI Responses типово увімкнений через `params.openaiWsWarmup` (`true`/`false`) -- Пріоритетну обробку OpenAI можна увімкнути через `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` і `params.fastMode` зіставляють прямі запити `openai/*` Responses з `service_tier=priority` на `api.openai.com` -- Використовуйте `params.serviceTier`, якщо вам потрібен явний tier замість спільного перемикача `/fast` +- Попередній прогрів 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-compatible proxy -- Нативні маршрути OpenAI також зберігають `store` Responses, підказки prompt-cache і - формування payload для сумісності reasoning OpenAI; proxy-маршрути цього не роблять -- `openai/gpt-5.3-codex-spark` навмисно пригнічується в OpenClaw, оскільки live-запити OpenAI API його відхиляють, а поточний каталог Codex його не надає + `User-Agent`) застосовуються лише до нативного трафіку OpenAI до `api.openai.com`, а не до загальних OpenAI-сумісних проксі +- Нативні маршрути OpenAI також зберігають Responses `store`, підказки кешу prompt і формування payload для сумісності з OpenAI reasoning; проксі-маршрути цього не роблять +- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити OpenAI API його відхиляють, а поточний каталог Codex його не надає ```json5 { @@ -94,14 +85,14 @@ OpenClaw постачається з каталогом pi‑ai. Для цих ### Anthropic -- Провайдер: `anthropic` +- Постачальник: `anthropic` - Auth: `ANTHROPIC_API_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-key та OAuth на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` vs `standard_only`) -- Примітка Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- Токен налаштування Anthropic залишається підтримуваним шляхом токена OpenClaw, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI і `claude -p`, якщо вони доступні. +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком, автентифікованим через API-ключ і OAuth, що надсилається на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Примітка Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволено, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- Setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо. ```json5 { @@ -111,22 +102,23 @@ OpenClaw постачається з каталогом pi‑ai. Для цих ### OpenAI Codex OAuth -- Провайдер: `openai-codex` +- Постачальник: `openai-codex` - Auth: OAuth (ChatGPT) -- Посилання на модель PI: `openai-codex/gpt-5.5` -- Посилання на нативний harness app-server Codex: `openai/gpt-5.5` з `agents.defaults.embeddedHarness.runtime: "codex"` +- Посилання на модель у PI: `openai-codex/gpt-5.5` +- Посилання нативного harness app-server Codex: `openai/gpt-5.5` з `agents.defaults.embeddedHarness.runtime: "codex"` - Застарілі посилання на моделі: `codex/gpt-*` +- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin app-server Codex вибирається лише рантаймом Codex harness або застарілими посиланнями `codex/*`. - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Типовий transport — `auto` (спочатку WebSocket, резервно SSE) +- Типовий транспорт — `auto` (спочатку WebSocket, fallback на SSE) - Перевизначення для окремої моделі PI через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- `params.serviceTier` також передається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) +- `params.serviceTier` також пересилається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex на - `chatgpt.com/backend-api`, а не до загальних OpenAI-compatible proxy + `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі - Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` -- `openai-codex/gpt-5.5` зберігає нативні `contextWindow = 1000000` і типові runtime `contextTokens = 272000`; перевизначте runtime-ліміт через `models.providers.openai-codex.models[].contextTokens` +- `openai-codex/gpt-5.5` зберігає нативні `contextWindow = 1000000` і типове runtime-обмеження `contextTokens = 272000`; перевизначте runtime-обмеження через `models.providers.openai-codex.models[].contextTokens` - Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/процесів на кшталт OpenClaw. -- Поточний доступ до GPT-5.5 використовує цей маршрут OAuth/підписки, доки OpenAI не увімкне GPT-5.5 у публічному API. +- Поточний доступ до GPT-5.5 використовує цей маршрут OAuth/підписки, доки OpenAI не ввімкне GPT-5.5 у публічному API. ```json5 { @@ -148,15 +140,15 @@ OpenClaw постачається з каталогом pi‑ai. Для цих ### Інші розміщені варіанти у стилі підписки -- [Qwen Cloud](/uk/providers/qwen): поверхня провайдера Qwen Cloud плюс зіставлення endpoint Alibaba DashScope і Coding Plan -- [MiniMax](/uk/providers/minimax): OAuth або API key доступ MiniMax Coding Plan -- [GLM Models](/uk/providers/glm): Z.AI Coding Plan або загальні API endpoint +- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud, а також зіставлення кінцевих точок Alibaba DashScope і Coding Plan +- [MiniMax](/uk/providers/minimax): OAuth або доступ за API-ключем MiniMax Coding Plan +- [GLM Models](/uk/providers/glm): кінцеві точки Z.AI Coding Plan або загального API ### OpenCode - Auth: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) -- Провайдер Zen runtime: `opencode` -- Провайдер Go runtime: `opencode-go` +- Постачальник runtime Zen: `opencode` +- Постачальник runtime Go: `opencode-go` - Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go` @@ -166,48 +158,46 @@ OpenClaw постачається з каталогом pi‑ai. Для цих } ``` -### Google Gemini (API key) +### Google Gemini (API-ключ) -- Провайдер: `google` +- Постачальник: `google` - Auth: `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`, fallback `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` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` - (або застарілий `cached_content`) для передавання нативного для провайдера - handle `cachedContents/...`; cache hit Gemini відображаються як OpenClaw `cacheRead` + (або застаріле `cached_content`) для пересилання нативного + дескриптора `cachedContents/...`; попадання в кеш Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI -- Провайдери: `google-vertex`, `google-gemini-cli` -- Auth: Vertex використовує gcloud ADC; Gemini CLI використовує власний OAuth flow -- Застереження: OAuth Gemini CLI в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. -- Gemini CLI OAuth постачається як частина вбудованого Plugin `google`. +- Постачальники: `google-vertex`, `google-gemini-cli` +- Auth: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth +- Застереження: OAuth Gemini CLI в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження Google-акаунтів після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний акаунт, якщо вирішите продовжити. +- OAuth Gemini CLI постачається як частина вбудованого Plugin `google`. - Спочатку встановіть Gemini CLI: - `brew install gemini-cli` - або `npm install -g @google/gemini-cli` - - Увімкнення: `openclaw plugins enable google` - - Вхід: `openclaw models auth login --provider google-gemini-cli --set-default` + - Увімкніть: `openclaw plugins enable google` + - Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` - Типова модель: `google-gemini-cli/gemini-3-flash-preview` - - Примітка: ви **не** вставляєте client id або secret у `openclaw.json`. Процес входу CLI зберігає - токени в auth profiles на хості gateway. - - Якщо запити не працюють після входу, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway. - - JSON-відповіді Gemini CLI розбираються з `response`; usage резервно береться з - `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. + - Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає токени в auth profiles на хості Gateway. + - Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway. + - JSON-відповіді Gemini CLI розбираються з `response`; дані про використання беруться з `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. ### Z.AI (GLM) -- Провайдер: `zai` +- Постачальник: `zai` - Auth: `ZAI_API_KEY` - Приклад моделі: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - - Аліаси: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` - - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово задають конкретну поверхню + - Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` + - `zai-api-key` автоматично визначає відповідну кінцеву точку Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню ### Vercel AI Gateway -- Провайдер: `vercel-ai-gateway` +- Постачальник: `vercel-ai-gateway` - Auth: `AI_GATEWAY_API_KEY` - Приклади моделей: `vercel-ai-gateway/anthropic/claude-opus-4.6`, `vercel-ai-gateway/moonshotai/kimi-k2.6` @@ -215,22 +205,22 @@ OpenClaw постачається з каталогом pi‑ai. Для цих ### Kilo Gateway -- Провайдер: `kilocode` +- Постачальник: `kilocode` - Auth: `KILOCODE_API_KEY` - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Base URL: `https://api.kilo.ai/api/gateway/` -- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live-виявлення через - `https://api.kilo.ai/api/gateway/models` може додатково розширити runtime-каталог. -- Точна маршрутизація upstream за `kilocode/kilo/auto` належить Kilo Gateway, +- Базовий URL: `https://api.kilo.ai/api/gateway/` +- Статичний fallback-каталог постачається з `kilocode/kilo/auto`; live-виявлення через + `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог runtime. +- Точна маршрутизація апстриму за `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. Деталі налаштування див. у [/providers/kilocode](/uk/providers/kilocode). -### Інші вбудовані Plugins провайдерів +### Інші вбудовані Plugin постачальників -| Провайдер | Id | Auth env | Приклад моделі | -| ------------------------ | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | +| Постачальник | Id | Auth env | Приклад моделі | +| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | | BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | | Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | | Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | @@ -254,30 +244,30 @@ OpenClaw постачається з каталогом pi‑ai. Для цих | xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | | Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -Особливості, які варто знати: +Варто знати такі особливості: -- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Як proxy-style шлях OpenAI-compatible, він пропускає формування, доступне лише для нативного OpenAI (`serviceTier`, `store` Responses, підказки prompt-cache, сумісність reasoning OpenAI). Посилання на моделі на базі Gemini зберігають лише очищення thought-signature для proxy-Gemini. -- **Kilo Gateway** для посилань на моделі на базі Gemini використовує той самий шлях очищення proxy-Gemini; `kilocode/kilo/auto` та інші посилання, які не підтримують proxy reasoning, пропускають ін’єкцію proxy reasoning. -- **MiniMax** онбординг через API key записує явні визначення моделей M2.7 з `input: ["text", "image"]`; вбудований каталог зберігає chat-посилання лише текстовими, доки ця конфігурація не буде матеріалізована. -- **xAI** використовує шлях xAI Responses. `/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`. -- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; base URL у форматі OpenAI-compatible — `https://api.cerebras.ai/v1`. +- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Як проксі-стиль OpenAI-сумісного шляху, він пропускає формування, притаманне лише нативному OpenAI (`serviceTier`, Responses `store`, підказки кешу prompt, сумісність reasoning OpenAI). Посилання на основі Gemini зберігають лише очищення thought-signature для проксі Gemini. +- **Kilo Gateway** для посилань на основі Gemini дотримується того самого шляху очищення проксі Gemini; `kilocode/kilo/auto` та інші посилання, де reasoning через проксі не підтримується, пропускають ін’єкцію reasoning через проксі. +- **MiniMax** онбординг за API-ключем записує явні визначення моделей M2.7 з `input: ["text", "image"]`; вбудований каталог зберігає chat-посилання лише текстовими, доки цю конфігурацію не буде матеріалізовано. +- **xAI** використовує шлях xAI Responses. `/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`. +- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; базовий URL, сумісний з OpenAI, — `https://api.cerebras.ai/v1`. -## Провайдери через `models.providers` (custom/base URL) +## Постачальники через `models.providers` (custom/base URL) -Використовуйте `models.providers` (або `models.json`), щоб додавати **custom** провайдерів або -OpenAI/Anthropic‑compatible proxy. +Використовуйте `models.providers` (або `models.json`), щоб додати **власних** постачальників або +OpenAI/Anthropic-сумісні проксі. -Багато з наведених нижче вбудованих Plugins провайдерів уже публікують типовий каталог. +Багато вбудованих нижче Plugin постачальників уже публікують типовий каталог. Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити -типовий base URL, headers або список моделей. +типовий base URL, заголовки або список моделей. ### Moonshot AI (Kimi) -Moonshot постачається як вбудований Plugin провайдера. Використовуйте вбудованого провайдера -типово, а явний запис `models.providers.moonshot` додавайте лише тоді, коли +Moonshot постачається як вбудований Plugin постачальника. Типово використовуйте +вбудованого постачальника і додавайте явний запис `models.providers.moonshot` лише тоді, коли потрібно перевизначити base URL або метадані моделі: -- Провайдер: `moonshot` +- Постачальник: `moonshot` - Auth: `MOONSHOT_API_KEY` - Приклад моделі: `moonshot/kimi-k2.6` - CLI: `openclaw onboard --auth-choice moonshot-api-key` або `openclaw onboard --auth-choice moonshot-api-key-cn` @@ -315,9 +305,9 @@ Moonshot постачається як вбудований Plugin провай ### Kimi Coding -Kimi Coding використовує Anthropic-compatible endpoint від Moonshot AI: +Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI: -- Провайдер: `kimi` +- Постачальник: `kimi` - Auth: `KIMI_API_KEY` - Приклад моделі: `kimi/kimi-code` @@ -330,13 +320,13 @@ Kimi Coding використовує Anthropic-compatible endpoint від Moonsh } ``` -Застарілий ідентифікатор моделі `kimi/k2p5` і далі приймається для сумісності. +Застарілий `kimi/k2p5` і далі приймається як сумісний id моделі. ### Volcano Engine (Doubao) Volcano Engine (火山引擎) надає доступ до Doubao та інших моделей у Китаї. -- Провайдер: `volcengine` (coding: `volcengine-plan`) +- Постачальник: `volcengine` (coding: `volcengine-plan`) - Auth: `VOLCANO_ENGINE_API_KEY` - Приклад моделі: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -349,13 +339,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Під час онбордингу типово вибирається поверхня coding, але загальний каталог `volcengine/*` +Онбординг типово використовує поверхню coding, але загальний каталог `volcengine/*` реєструється одночасно. -У селекторах вибору моделі під час онбордингу/налаштування вибір auth для Volcengine віддає перевагу рядкам -`volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, -OpenClaw повертається до нефільтрованого каталогу замість показу порожнього -селектора в межах провайдера. +У засобах вибору моделі під час онбордингу/налаштування вибір auth для Volcengine надає перевагу рядкам +`volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажено, +OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній +засіб вибору в межах постачальника. Доступні моделі: @@ -377,7 +367,7 @@ OpenClaw повертається до нефільтрованого катал BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine. -- Провайдер: `byteplus` (coding: `byteplus-plan`) +- Постачальник: `byteplus` (coding: `byteplus-plan`) - Auth: `BYTEPLUS_API_KEY` - Приклад моделі: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -390,13 +380,13 @@ BytePlus ARK надає міжнародним користувачам дост } ``` -Під час онбордингу типово вибирається поверхня coding, але загальний каталог `byteplus/*` +Онбординг типово використовує поверхню coding, але загальний каталог `byteplus/*` реєструється одночасно. -У селекторах вибору моделі під час онбордингу/налаштування вибір auth для BytePlus віддає перевагу і рядкам -`byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, -OpenClaw повертається до нефільтрованого каталогу замість показу порожнього -селектора в межах провайдера. +У засобах вибору моделі під час онбордингу/налаштування вибір auth для BytePlus надає перевагу обом +рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, +OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній +засіб вибору в межах постачальника. Доступні моделі: @@ -414,9 +404,9 @@ OpenClaw повертається до нефільтрованого катал ### Synthetic -Synthetic надає Anthropic-compatible моделі через провайдера `synthetic`: +Synthetic надає Anthropic-сумісні моделі через постачальника `synthetic`: -- Провайдер: `synthetic` +- Постачальник: `synthetic` - Auth: `SYNTHETIC_API_KEY` - Приклад моделі: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI: `openclaw onboard --auth-choice synthetic-api-key` @@ -442,35 +432,35 @@ Synthetic надає Anthropic-compatible моделі через провайд ### MiniMax -MiniMax налаштовується через `models.providers`, оскільки використовує custom endpoint: +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` - Auth: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` Деталі налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). -На Anthropic-compatible streaming-шляху MiniMax OpenClaw типово вимикає thinking, +На Anthropic-сумісному потоковому шляху MiniMax OpenClaw типово вимикає thinking, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Поділ можливостей, що належить Plugin: +Розділення можливостей, що належить Plugin: - Типові значення text/chat залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це керований Plugin `MiniMax-VL-01` на обох auth-шляхах MiniMax -- Вебпошук залишається на id провайдера `minimax` +- Розуміння зображень — це керований Plugin `MiniMax-VL-01` на обох шляхах auth MiniMax +- Вебпошук залишається на id постачальника `minimax` ### LM Studio -LM Studio постачається як вбудований Plugin провайдера, який використовує нативний API: +LM Studio постачається як вбудований Plugin постачальника, який використовує нативний API: -- Провайдер: `lmstudio` +- Постачальник: `lmstudio` - Auth: `LM_API_TOKEN` -- Типовий base URL для інференсу: `http://localhost:1234/v1` +- Типовий base URL інференсу: `http://localhost:1234/v1` Потім задайте модель (замініть на один з id, які повертає `http://localhost:1234/api/v1/models`): @@ -482,16 +472,16 @@ LM Studio постачається як вбудований Plugin провай } ``` -OpenClaw використовує нативні `/api/v1/models` і `/api/v1/models/load` у LM Studio -для виявлення та auto-load, а типово для інференсу — `/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` -- Auth: не потрібна (локальний сервер) +- Постачальник: `ollama` +- Auth: не потрібен (локальний сервер) - Приклад моделі: `ollama/llama3.3` - Встановлення: [https://ollama.com/download](https://ollama.com/download) @@ -509,20 +499,20 @@ ollama pull llama3.3 ``` Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте це через -`OLLAMA_API_KEY`, а вбудований Plugin провайдера додає Ollama безпосередньо до -`openclaw onboard` і селектора моделей. Див. [/providers/ollama](/uk/providers/ollama) -щодо онбордингу, cloud/local mode і custom-конфігурації. +`OLLAMA_API_KEY`, а вбудований Plugin постачальника додає Ollama безпосередньо до +`openclaw onboard` і засобу вибору моделі. Див. [/providers/ollama](/uk/providers/ollama) +щодо онбордингу, хмарного/локального режиму та власної конфігурації. ### vLLM -vLLM постачається як вбудований Plugin провайдера для локальних/self-hosted OpenAI-compatible +vLLM постачається як вбудований Plugin постачальника для локальних/self-hosted OpenAI-сумісних серверів: -- Провайдер: `vllm` -- Auth: необов’язкова (залежить від вашого сервера) +- Постачальник: `vllm` +- Auth: необов’язковий (залежить від вашого сервера) - Типовий base URL: `http://127.0.0.1:8000/v1` -Щоб увімкнути auto-discovery локально (підійде будь-яке значення, якщо ваш сервер не вимагає auth): +Щоб увімкнути автовиявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає auth): ```bash export VLLM_API_KEY="vllm-local" @@ -538,18 +528,18 @@ export VLLM_API_KEY="vllm-local" } ``` -Деталі див. у [/providers/vllm](/uk/providers/vllm). +Подробиці див. у [/providers/vllm](/uk/providers/vllm). ### SGLang -SGLang постачається як вбудований Plugin провайдера для швидких self-hosted -OpenAI-compatible серверів: +SGLang постачається як вбудований Plugin постачальника для швидких self-hosted +OpenAI-сумісних серверів: -- Провайдер: `sglang` -- Auth: необов’язкова (залежить від вашого сервера) +- Постачальник: `sglang` +- Auth: необов’язковий (залежить від вашого сервера) - Типовий base URL: `http://127.0.0.1:30000/v1` -Щоб увімкнути auto-discovery локально (підійде будь-яке значення, якщо ваш сервер не +Щоб увімкнути автовиявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає auth): ```bash @@ -566,11 +556,11 @@ export SGLANG_API_KEY="sglang-local" } ``` -Деталі див. у [/providers/sglang](/uk/providers/sglang). +Подробиці див. у [/providers/sglang](/uk/providers/sglang). -### Локальні proxy (LM Studio, vLLM, LiteLLM тощо) +### Локальні проксі (LM Studio, vLLM, LiteLLM тощо) -Приклад (OpenAI‑compatible): +Приклад (OpenAI‑сумісний): ```json5 { @@ -605,21 +595,18 @@ export SGLANG_API_KEY="sglang-local" Примітки: -- Для custom-провайдерів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. - Якщо їх не задано, OpenClaw типово використовує: +- Для власних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. + Якщо їх пропущено, OpenClaw типово використовує: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашого proxy/моделі. -- Для `api: "openai-completions"` на ненативних endpoint (будь-який непорожній `baseUrl`, у якого host не `api.openai.com`), OpenClaw примусово задає `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від провайдера через непідтримувані ролі `developer`. -- Proxy-style маршрути OpenAI-compatible також пропускають формування запитів, притаманне лише нативному OpenAI: - без `service_tier`, без `store` Responses, без підказок prompt-cache, без - формування payload для сумісності reasoning OpenAI та без прихованих - заголовків атрибуції OpenClaw. -- Якщо `baseUrl` порожній/не заданий, OpenClaw зберігає типову поведінку OpenAI (яка веде до `api.openai.com`). -- З міркувань безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних endpoint `openai-completions`. +- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашого проксі/моделі. +- Для `api: "openai-completions"` на ненативних кінцевих точках (будь-який непорожній `baseUrl`, у якого host не `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від постачальника через непідтримувані ролі `developer`. +- OpenAI-сумісні маршрути у стилі проксі також пропускають формування запитів, притаманне лише нативному OpenAI: без `service_tier`, без Responses `store`, без підказок кешу prompt, без формування payload для сумісності з OpenAI reasoning і без прихованих заголовків атрибуції OpenClaw. +- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка веде до `api.openai.com`). +- Для безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на ненативних кінцевих точках `openai-completions`. ## Приклади CLI @@ -631,9 +618,9 @@ openclaw models list Див. також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації. -## Пов’язане +## Пов’язані сторінки -- [Models](/uk/concepts/models) — конфігурація моделей та аліаси -- [Model Failover](/uk/concepts/model-failover) — ланцюги fallback і поведінка повторних спроб -- [Configuration Reference](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей -- [Providers](/uk/providers) — інструкції з налаштування для кожного провайдера +- [Моделі](/uk/concepts/models) — конфігурація моделей і псевдоніми +- [Відмовостійкість моделей](/uk/concepts/model-failover) — ланцюжки резервного перемикання та поведінка повторних спроб +- [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей +- [Постачальники](/uk/providers) — інструкції з налаштування для кожного постачальника diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index 9e47b031b..de5ee34e0 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -2,64 +2,71 @@ read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - Ви хочете використовувати автентифікацію за підпискою Codex замість API-ключів - - Вам потрібні суворіші правила виконання агента GPT-5 + - Вам потрібна суворіша поведінка виконання агента GPT-5 summary: Використовуйте OpenAI через API-ключі або підписку Codex в OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-24T02:37:02Z" + generated_at: "2026-04-24T05:42:20Z" model: gpt-5.4 provider: openai - source_hash: 8337990d0de692b32746b05ab344695fc5a54ab3855993ac7795fabf38d4d19d + source_hash: 3d533338fa15d866bb69584706162ce099bb4a1edc9851183fb5442730ebdd9b source_path: providers/openai.md workflow: 15 --- OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі визначає маршрут: -- **API-ключ** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`) -- **Підписка Codex через PI** — вхід через ChatGPT/Codex з доступом за підпискою (моделі `openai-codex/*`) -- **Codex app-server harness** — нативне виконання через Codex app-server (`openai/*` моделі плюс `agents.defaults.embeddedHarness.runtime: "codex"`) +- **API key** — прямий доступ до платформи OpenAI з оплатою за використання (моделі `openai/*`) +- **Підписка Codex через PI** — вхід через ChatGPT/Codex із доступом за підпискою (моделі `openai-codex/*`) +- **Обв’язка app-server Codex** — нативне виконання через app-server Codex (`openai/*` моделі плюс `agents.defaults.embeddedHarness.runtime: "codex"`) -OpenAI прямо підтримує використання OAuth-підписки в зовнішніх інструментах і робочих процесах, таких як OpenClaw. +OpenAI прямо підтримує використання OAuth-підписки у зовнішніх інструментах і робочих процесах, таких як OpenClaw. GPT-5.5 наразі доступна в OpenClaw через маршрути підписки/OAuth: -`openai-codex/gpt-5.5` з PI runner або `openai/gpt-5.5` з -Codex app-server harness. Прямий доступ за API-ключем для `openai/gpt-5.5` -підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API; до того -часу використовуйте модель, доступну через API, наприклад `openai/gpt-5.4`, для конфігурацій +`openai-codex/gpt-5.5` із виконавцем PI або `openai/gpt-5.5` з +обв’язкою app-server Codex. Прямий доступ за API-ключем для `openai/gpt-5.5` +підтримується, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу використовуйте +модель з доступом через API, наприклад `openai/gpt-5.4`, для конфігурацій `OPENAI_API_KEY`. -## Покриття функцій OpenClaw + +Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не +увімкне вбудований Plugin app-server Codex. OpenClaw вмикає цей Plugin лише +коли ви явно вибираєте нативну обв’язку Codex через +`embeddedHarness.runtime: "codex"` або використовуєте застаріле посилання на модель `codex/*`. + -| Можливість OpenAI | Поверхня OpenClaw | Статус | -| ------------------------- | -------------------------------------------------------- | ------------------------------------------------------- | -| Chat / Responses | постачальник моделей `openai/` | Так | -| Моделі за підпискою Codex | `openai-codex/` з OAuth `openai-codex` | Так | -| Codex app-server harness | `openai/` з `embeddedHarness.runtime: codex` | Так | -| Пошук у вебі на боці сервера | нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і постачальника не зафіксовано | -| Зображення | `image_generate` | Так | -| Відео | `video_generate` | Так | -| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так | -| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так | -| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так | +## Покриття можливостей OpenClaw + +| Можливість OpenAI | Поверхня OpenClaw | Статус | +| ------------------------- | --------------------------------------------------------- | ------------------------------------------------------ | +| Chat / Responses | постачальник моделі `openai/` | Так | +| Моделі підписки Codex | `openai-codex/` з OAuth `openai-codex` | Так | +| Обв’язка app-server Codex | `openai/` з `embeddedHarness.runtime: codex` | Так | +| Пошук у вебі на стороні сервера | нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і постачальник не закріплений | +| Зображення | `image_generate` | Так | +| Відео | `video_generate` | Так | +| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так | +| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так | +| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так | | Голос у реальному часі | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так | -| Вбудовування | постачальник вбудовувань пам’яті | Так | +| Embeddings | постачальник embedding для пам’яті | Так | ## Початок роботи -Виберіть бажаний спосіб автентифікації й виконайте кроки налаштування. +Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування. - + **Найкраще для:** прямого доступу до API та оплати за використання. - - Створіть або скопіюйте API-ключ з [панелі OpenAI Platform](https://platform.openai.com/api-keys). + + Створіть або скопіюйте API key з [інформаційної панелі платформи OpenAI](https://platform.openai.com/api-keys). - + ```bash openclaw onboard --auth-choice openai-api-key ``` @@ -70,7 +77,7 @@ Codex app-server harness. Прямий доступ за API-ключем для openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` @@ -79,16 +86,16 @@ Codex app-server harness. Прямий доступ за API-ключем для ### Підсумок маршруту - | Посилання на модель | Маршрут | Автентифікація | - |-----------|-------|------| - | `openai/gpt-5.4` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.4-mini` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.5` | Майбутній прямий маршрут API, щойно OpenAI увімкне GPT-5.5 в API | `OPENAI_API_KEY` | + | Model ref | Маршрут | Автентифікація | + |-----------|---------|----------------| + | `openai/gpt-5.4` | Прямий API платформи OpenAI | `OPENAI_API_KEY` | + | `openai/gpt-5.4-mini` | Прямий API платформи OpenAI | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | Майбутній прямий маршрут API, коли OpenAI увімкне GPT-5.5 в API | `OPENAI_API_KEY` | `openai/*` — це прямий маршрут OpenAI за API-ключем, якщо ви явно не примусите - використання Codex app-server harness. Сама GPT-5.5 наразі доступна лише через підписку/OAuth; - використовуйте `openai-codex/*` для Codex OAuth через стандартний PI runner. + обв’язку app-server Codex. Сама GPT-5.5 наразі доступна лише через підписку/OAuth; + використовуйте `openai-codex/*` для OAuth Codex через виконавець PI за замовчуванням. ### Приклад конфігурації @@ -101,16 +108,16 @@ Codex app-server harness. Прямий доступ за API-ключем для ``` - OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Живі запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає. + OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Активні запити до API OpenAI відхиляють цю модель, і поточний каталог Codex також її не надає. - **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API-ключа. Codex cloud вимагає входу через ChatGPT. + **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API key. Codex cloud потребує входу через ChatGPT. - + ```bash openclaw onboard --auth-choice openai-codex ``` @@ -121,18 +128,18 @@ Codex app-server harness. Прямий доступ за API-ключем для openclaw models auth login --provider openai-codex ``` - Для headless-середовищ або конфігурацій, де незручно використовувати callback, додайте `--device-code`, щоб увійти через потік коду пристрою ChatGPT замість callback локального браузера: + Для безголових середовищ або конфігурацій, де зворотний виклик незручний, додайте `--device-code`, щоб увійти через потік коду пристрою ChatGPT замість зворотного виклику браузера localhost: ```bash openclaw models auth login --provider openai-codex --device-code ``` - + ```bash openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` @@ -141,14 +148,15 @@ Codex app-server harness. Прямий доступ за API-ключем для ### Підсумок маршруту - | Посилання на модель | Маршрут | Автентифікація | - |-----------|-------|------| - | `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth через PI | вхід Codex | - | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | автентифікація Codex app-server | + | Model ref | Маршрут | Автентифікація | + |-----------|---------|----------------| + | `openai-codex/gpt-5.5` | OAuth ChatGPT/Codex через PI | Вхід Codex | + | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Обв’язка app-server Codex | Автентифікація app-server Codex | Продовжуйте використовувати ідентифікатор постачальника `openai-codex` для команд автентифікації/профілю. Префікс моделі - `openai-codex/*` також є явним маршрутом PI для Codex OAuth. + `openai-codex/*` також є явним маршрутом PI для OAuth Codex. + Він не вибирає і не автовмикає вбудовану обв’язку app-server Codex. ### Приклад конфігурації @@ -160,29 +168,29 @@ Codex app-server harness. Прямий доступ за API-ключем для ``` - Початкове налаштування більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через OAuth у браузері (типовий варіант) або через потік коду пристрою, вказаний вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента. + Первинне налаштування більше не імпортує OAuth-матеріали з `~/.codex`. Увійдіть через OAuth у браузері (за замовчуванням) або через потік коду пристрою вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента. ### Індикатор стану - Chat `/status` показує, який вбудований harness активний для поточної - сесії. Стандартний PI harness відображається як `Runner: pi (embedded)` і - не додає окремий індикатор. Коли вибрано вбудований Codex app-server harness, - `/status` додає ідентифікатор не-PI harness поруч із `Fast`, наприклад - `Fast · codex`. Наявні сесії зберігають записаний для них ідентифікатор harness, тому використовуйте + У чаті `/status` показує, яка вбудована обв’язка активна для поточної + сесії. Обв’язка PI за замовчуванням відображається як `Runner: pi (embedded)` і + не додає окремого значка. Коли вибрано вбудовану обв’язку app-server Codex, + `/status` додає ідентифікатор обв’язки не-PI поруч із `Fast`, наприклад + `Fast · codex`. Наявні сесії зберігають записаний для них ідентифікатор обв’язки, тому використовуйте `/new` або `/reset` після зміни `embeddedHarness`, якщо хочете, щоб `/status` відображав новий вибір PI/Codex. ### Обмеження вікна контексту - OpenClaw розглядає метадані моделі та обмеження контексту під час виконання як окремі значення. + OpenClaw розглядає метадані моделі та обмеження контексту середовища виконання як окремі значення. - Для `openai-codex/gpt-5.5` через Codex OAuth: + Для `openai-codex/gpt-5.5` через OAuth Codex: - Нативний `contextWindow`: `1000000` - - Стандартне обмеження `contextTokens` під час виконання: `272000` + - Обмеження `contextTokens` середовища виконання за замовчуванням: `272000` - Менше стандартне обмеження на практиці дає кращі характеристики затримки й якості. Перевизначте його через `contextTokens`: + Менше обмеження за замовчуванням на практиці дає кращі характеристики затримки та якості. Перевизначте його через `contextTokens`: ```json5 { @@ -197,7 +205,7 @@ Codex app-server harness. Прямий доступ за API-ключем для ``` - Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання. + Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту середовища виконання. @@ -206,18 +214,18 @@ Codex app-server harness. Прямий доступ за API-ключем для ## Генерація зображень Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. -Він підтримує як генерацію зображень OpenAI за API-ключем, так і генерацію зображень -через Codex OAuth, використовуючи те саме посилання на модель `openai/gpt-image-2`. +Він підтримує і генерацію зображень OpenAI за API-ключем, і генерацію зображень через OAuth Codex +через те саме посилання на модель `openai/gpt-image-2`. -| Можливість | API-ключ OpenAI | Codex OAuth | -| ------------------------- | ---------------------------------- | ------------------------------------ | -| Посилання на модель | `openai/gpt-image-2` | `openai/gpt-image-2` | -| Автентифікація | `OPENAI_API_KEY` | вхід через OpenAI Codex OAuth | -| Транспорт | OpenAI Images API | бекенд Codex Responses | -| Макс. кількість зображень на запит | 4 | 4 | -| Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) | -| Перевизначення розміру | Підтримується, зокрема розміри 2K/4K | Підтримується, зокрема розміри 2K/4K | -| Співвідношення сторін / роздільна здатність | Не передається до OpenAI Images API | Зіставляється з підтримуваним розміром, коли це безпечно | +| Можливість | API key OpenAI | OAuth Codex | +| ------------------------ | ---------------------------------- | ----------------------------------- | +| Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` | +| Автентифікація | `OPENAI_API_KEY` | Вхід через OAuth OpenAI Codex | +| Транспорт | API зображень OpenAI | бекенд Codex Responses | +| Макс. зображень на запит | 4 | 4 | +| Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) | +| Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | Підтримується, включно з розмірами 2K/4K | +| Співвідношення сторін / роздільна здатність | Не передається до API зображень OpenAI | Відображається у підтримуваний розмір, коли це безпечно | ```json5 { @@ -230,33 +238,35 @@ Codex app-server harness. Прямий доступ за API-ключем для ``` -Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору постачальника та поведінки failover. +Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку при перемиканні на резервний варіант. -`gpt-image-2` — це стандартне значення і для генерації зображень з тексту OpenAI, і для редагування зображень. `gpt-image-1` залишається доступною як явне перевизначення моделі, але нові робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`. +`gpt-image-2` — модель за замовчуванням і для перетворення тексту на зображення OpenAI, і для +редагування зображень. `gpt-image-1` залишається доступною як явне перевизначення моделі, але нові +робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`. -Для установок із Codex OAuth зберігайте те саме посилання `openai/gpt-image-2`. Коли -налаштовано OAuth-профіль `openai-codex`, OpenClaw визначає цей збережений токен -доступу OAuth і надсилає запити на зображення через бекенд Codex Responses. Він -не намагається спочатку використати `OPENAI_API_KEY` і не виконує тихий перехід на API-ключ для цього -запиту. Явно налаштуйте `models.providers.openai` з API-ключем, -власною базовою URL-адресою або Azure endpoint, якщо хочете використовувати прямий маршрут -OpenAI Images API. -Якщо цей власний endpoint зображень перебуває в довіреній LAN/приватній адресі, також задайте -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw і далі -блокує приватні/внутрішні OpenAI-сумісні endpoint зображень, якщо цей явний дозвіл +Для інсталяцій із OAuth Codex зберігайте те саме посилання `openai/gpt-image-2`. Коли +налаштовано OAuth-профіль `openai-codex`, OpenClaw визначає цей збережений токен доступу OAuth +і надсилає запити на зображення через бекенд Codex Responses. Він +не спочатку пробує `OPENAI_API_KEY` і не виконує безшумний перехід на API key для цього +запиту. Явно налаштуйте `models.providers.openai` з API key, +власним базовим URL або кінцевою точкою Azure, якщо ви хочете використовувати +прямий маршрут API зображень OpenAI. +Якщо ця власна кінцева точка зображень розташована в довіреній LAN/приватній адресі, також встановіть +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw і надалі +блокує приватні/внутрішні OpenAI-сумісні кінцеві точки зображень, якщо цей явний дозвіл не задано. -Згенерувати: +Генерація: ``` -/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 +/tool image_generate model=openai/gpt-image-2 prompt="Відполірований постер запуску OpenClaw на macOS" size=3840x2160 count=1 ``` -Відредагувати: +Редагування: ``` -/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 +/tool image_generate model=openai/gpt-image-2 prompt="Збережіть форму об’єкта, змініть матеріал на напівпрозоре скло" image=/path/to/reference.png size=1024x1536 ``` ## Генерація відео @@ -265,10 +275,10 @@ OpenAI Images API. | Можливість | Значення | | ---------------- | --------------------------------------------------------------------------------- | -| Стандартна модель | `openai/sora-2` | -| Режими | Текст у відео, зображення у відео, редагування одного відео | -| Вхідні еталони | 1 зображення або 1 відео | -| Перевизначення розміру | Підтримується | +| Модель за замовчуванням | `openai/sora-2` | +| Режими | Перетворення тексту на відео, зображення на відео, редагування одного відео | +| Еталонні вхідні дані | 1 зображення або 1 відео | +| Перевизначення розміру | Підтримується | | Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента | ```json5 @@ -282,22 +292,22 @@ OpenAI Images API. ``` -Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору постачальника та поведінки failover. +Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку при перемиканні на резервний варіант. -## Внесок у prompt GPT-5 +## Внесок у промпт GPT-5 -OpenClaw додає спільний внесок у prompt GPT-5 для запусків сімейства GPT-5 у різних постачальників. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.4`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x — ні. +OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних постачальників. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.4`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують однакове накладання. Старіші моделі GPT-4.x цього не отримують. -Вбудований нативний Codex harness використовує ту саму поведінку GPT-5 і overlay Heartbeat через інструкції розробника Codex app-server, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі вказівки щодо доведення дій до завершення та проактивного Heartbeat, навіть попри те, що рештою prompt harness керує Codex. +Вбудована нативна обв’язка Codex використовує ту саму поведінку GPT-5 і накладання Heartbeat через інструкції розробника app-server Codex, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі вказівки щодо доведення справ до кінця та проактивного Heartbeat, навіть попри те, що рештою промпта обв’язки керує Codex. -Внесок GPT-5 додає тегований контракт поведінки для збереження persona, безпеки виконання, дисципліни використання інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналів поведінка відповіді та тихих повідомлень залишається у спільному системному prompt OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди ввімкнені для відповідних моделей. Рівень дружнього стилю взаємодії є окремим і налаштовуваним. +Внесок GPT-5 додає тегований контракт поведінки для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналів поведінка відповіді та тихих повідомлень залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди ввімкнені для відповідних моделей. Шар дружнього стилю взаємодії є окремим і налаштовуваним. | Значення | Ефект | | ---------------------- | ------------------------------------------ | -| `"friendly"` (типово) | Увімкнути рівень дружнього стилю взаємодії | +| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії | | `"on"` | Псевдонім для `"friendly"` | -| `"off"` | Вимкнути лише рівень дружнього стилю | +| `"off"` | Вимкнути лише шар дружнього стилю | @@ -321,11 +331,11 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап -Значення під час виконання не чутливі до регістру, тому і `"Off"`, і `"off"` вимикають дружній стиль. +Під час виконання значення нечутливі до регістру, тому і `"Off"`, і `"off"` вимикають шар дружнього стилю. -Застарілий `plugins.entries.openai.config.personality` усе ще читається як сумісний запасний варіант, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. +Застаріле `plugins.entries.openai.config.personality` усе ще зчитується як резервний варіант сумісності, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задане. ## Голос і мовлення @@ -334,15 +344,15 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `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` | Використовується `OPENAI_API_KEY` як запасний варіант | - | Базова URL-адреса | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | + | API key | `messages.tts.providers.openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | + | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`. @@ -359,21 +369,21 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап ``` - Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базову URL-адресу TTS без впливу на endpoint chat API. + Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS, не впливаючи на кінцеву точку API чату. Вбудований Plugin `openai` реєструє пакетне перетворення мовлення на текст через - поверхню транскрибування розуміння медіа OpenClaw. + поверхню транскрибування розуміння медіа в OpenClaw. - Типова модель: `gpt-4o-transcribe` - - Endpoint: OpenAI REST `/v1/audio/transcriptions` - - Шлях вхідних даних: multipart-вивантаження аудіофайлу - - Підтримується в OpenClaw всюди, де транскрибування вхідного аудіо використовує - `tools.media.audio`, зокрема у сегментах голосових каналів Discord і - аудіовкладеннях каналів + - Кінцева точка: OpenAI REST `/v1/audio/transcriptions` + - Шлях введення: multipart-вивантаження аудіофайлу + - Підтримується в OpenClaw всюди, де вхідне транскрибування аудіо використовує + `tools.media.audio`, включно з сегментами голосових каналів Discord і + аудіовкладеннями каналів Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо: @@ -395,25 +405,25 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап } ``` - Підказки щодо мови та prompt передаються до OpenAI, коли вони задані - у спільній конфігурації аудіомедіа або в запиті транскрибування для конкретного виклику. + Підказки щодо мови та промпта передаються до OpenAI, коли вони надаються + спільною конфігурацією аудіомедіа або запитом транскрибування для окремого виклику. Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call. - | Налаштування | Шлях конфігурації | Типове значення | + | Налаштування | Шлях конфігурації | Типово | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | Мова | `...openai.language` | (не задано) | - | Prompt | `...openai.prompt` | (не задано) | + | Промпт | `...openai.prompt` | (не задано) | | Тривалість тиші | `...openai.silenceDurationMs` | `800` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | - | API-ключ | `...openai.apiKey` | Використовується `OPENAI_API_KEY` як запасний варіант | + | API key | `...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`. @@ -421,47 +431,47 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call. - | Налаштування | Шлях конфігурації | Типове значення | + | Налаштування | Шлях конфігурації | Типово | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | | Голос | `...openai.voice` | `alloy` | | Temperature | `...openai.temperature` | `0.8` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | | Тривалість тиші | `...openai.silenceDurationMs` | `500` | - | API-ключ | `...openai.apiKey` | Використовується `OPENAI_API_KEY` як запасний варіант | + | API key | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | - Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлені виклики інструментів. Використовує аудіоформат G.711 u-law. + Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує аудіоформат G.711 u-law. -## Endpoint Azure OpenAI +## Кінцеві точки Azure OpenAI -Вбудований постачальник `openai` може використовувати ресурс Azure OpenAI для -генерації зображень шляхом перевизначення базової URL-адреси. На шляху -генерації зображень OpenClaw автоматично виявляє хости Azure у `models.providers.openai.baseUrl` і перемикається на -форму запиту Azure. +Вбудований постачальник `openai` може спрямовувати генерацію зображень до ресурсу Azure OpenAI +шляхом перевизначення базового 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. +часі** в розділі [Голос і мовлення](#voice-and-speech) для його налаштувань Azure. -Використовуйте Azure OpenAI, коли: +Використовуйте Azure OpenAI, якщо: -- У вас уже є підписка, квота або корпоративна угода Azure OpenAI -- Вам потрібні регіональне зберігання даних або засоби відповідності вимогам, які надає Azure -- Ви хочете, щоб трафік залишався в межах наявного орендаря Azure +- У вас уже є підписка Azure OpenAI, квота або корпоративна угода +- Вам потрібна регіональна локалізація даних або засоби відповідності вимогам, які надає Azure +- Ви хочете зберігати трафік у межах наявного середовища Azure ### Конфігурація Для генерації зображень через Azure за допомогою вбудованого постачальника `openai` вкажіть -`models.providers.openai.baseUrl` на ваш ресурс Azure і задайте `apiKey` як -ключ Azure OpenAI (а не ключ OpenAI Platform): +`models.providers.openai.baseUrl` на ваш ресурс Azure і встановіть `apiKey` у значення +ключа Azure OpenAI (а не ключа платформи OpenAI): ```json5 { @@ -485,16 +495,17 @@ OpenClaw розпізнає такі суфікси хостів Azure для м Для запитів генерації зображень на розпізнаному хості Azure OpenClaw: - Надсилає заголовок `api-key` замість `Authorization: Bearer` -- Використовує шляхи з прив’язкою до deployment (`/openai/deployments/{deployment}/...`) +- Використовує шляхи, прив’язані до розгортання (`/openai/deployments/{deployment}/...`) - Додає `?api-version=...` до кожного запиту -Інші базові URL-адреси (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартну -форму запиту OpenAI для зображень. +Інші базові URL (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартний +формат запиту зображень OpenAI. -Маршрутизація Azure для шляху генерації зображень постачальника `openai` -потребує OpenClaw 2026.4.22 або новішої версії. Раніші версії обробляють будь-який користувацький -`openai.baseUrl` як публічний endpoint OpenAI і завершуються помилкою при роботі з deployment зображень Azure. +Маршрутизація Azure для шляху генерації зображень постачальника `openai` вимагає +OpenClaw 2026.4.22 або новішої версії. У раніших версіях будь-який користувацький +`openai.baseUrl` обробляється як публічна кінцева точка OpenAI і не працюватиме з розгортаннями +зображень Azure. ### Версія API @@ -506,68 +517,68 @@ OpenClaw розпізнає такі суфікси хостів Azure для м export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` -Типове значення — `2024-12-01-preview`, якщо змінну не задано. +Типове значення — `2024-12-01-preview`, коли змінну не задано. -### Імена моделей — це імена deployment +### Імена моделей є іменами розгортань -Azure OpenAI прив’язує моделі до deployment. Для запитів генерації зображень Azure, -маршрутизованих через вбудований постачальник `openai`, поле `model` в OpenClaw -має бути **іменем deployment Azure**, яке ви налаштували в порталі Azure, а не +Azure OpenAI прив’язує моделі до розгортань. Для запитів генерації зображень Azure, +спрямованих через вбудованого постачальника `openai`, поле `model` в OpenClaw +має бути **іменем розгортання Azure**, яке ви налаштували в порталі Azure, а не ідентифікатором публічної моделі 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 +/tool image_generate model=openai/gpt-image-2-prod prompt="Чистий постер" size=1024x1024 count=1 ``` -Те саме правило імен deployment застосовується до викликів генерації зображень, -маршрутизованих через вбудований постачальник `openai`. +Те саме правило імені розгортання застосовується до викликів генерації зображень, +спрямованих через вбудованого постачальника `openai`. ### Регіональна доступність -Генерація зображень Azure наразі доступна лише в обмеженій кількості регіонів +Генерація зображень Azure наразі доступна лише в підмножині регіонів (наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`, `uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням -deployment і підтвердьте, що конкретна модель доступна у вашому регіоні. +розгортання, а також підтвердьте, що конкретна модель доступна у вашому регіоні. ### Відмінності параметрів 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, але не отримує -приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні маршрути та OpenAI-сумісні +Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує +приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні та OpenAI-сумісні маршрути** в розділі [Розширена конфігурація](#advanced-configuration). -Для трафіку chat або Responses на Azure (поза генерацією зображень) використовуйте -потік початкового налаштування або окрему конфігурацію постачальника Azure — одного лише -`openai.baseUrl` недостатньо, щоб отримати форму API/автентифікації Azure. Існує окремий -постачальник `azure-openai-responses/*`; див. +Для трафіку чату або Responses в Azure (поза генерацією зображень) використовуйте +потік первинного налаштування або окрему конфігурацію постачальника Azure — одного лише +`openai.baseUrl` недостатньо, щоб застосувати формат API/автентифікації Azure. Існує +окремий постачальник `azure-openai-responses/*`; див. акордеон Server-side Compaction нижче. ## Розширена конфігурація - - OpenClaw використовує WebSocket-first із запасним переходом на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. + + OpenClaw використовує пріоритет WebSocket із резервним переходом на SSE (`"auto"`) і для `openai/*`, і для `openai-codex/*`. У режимі `"auto"` OpenClaw: - Повторює одну ранню помилку WebSocket перед переходом на SSE - - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження + - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час періоду охолодження - Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і перепідключень - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту | Значення | Поведінка | |-------|----------| - | `"auto"` (типово) | Спочатку WebSocket, потім запасний перехід на SSE | + | `"auto"` (типово) | Спочатку WebSocket, резервний перехід на SSE | | `"sse"` | Примусово лише SSE | | `"websocket"` | Примусово лише WebSocket | @@ -588,17 +599,17 @@ Azure OpenAI використовує нативний транспорт і п } ``` - Пов’язана документація OpenAI: - - [Realtime API з WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) - - [Потокові відповіді API (SSE)](https://platform.openai.com/docs/guides/streaming-responses) + Пов’язані документи OpenAI: + - [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) + - [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses) - - OpenClaw типово вмикає прогрів WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу. + + OpenClaw типово вмикає прогрівання WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу. ```json5 - // Вимкнути прогрів + // Вимкнути прогрівання { agents: { defaults: { @@ -617,10 +628,10 @@ Azure OpenAI використовує нативний транспорт і п 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 { @@ -635,13 +646,13 @@ Azure OpenAI використовує нативний транспорт і п ``` - Перевизначення сесії мають вищий пріоритет за конфігурацію. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого типового значення. + Перевизначення сесії мають вищий пріоритет за конфігурацію. Очищення перевизначення сесії в UI сесій повертає сесію до налаштованого типового значення. - API OpenAI надає пріоритетну обробку через `service_tier`. Задайте її для кожної моделі в OpenClaw: + API OpenAI надає пріоритетну обробку через `service_tier`. Налаштуйте її для кожної моделі в OpenClaw: ```json5 { @@ -658,23 +669,23 @@ Azure OpenAI використовує нативний транспорт і п Підтримувані значення: `auto`, `default`, `flex`, `priority`. - `serviceTier` передається лише до нативних endpoint OpenAI (`api.openai.com`) і нативних endpoint 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`) stream wrapper Pi-harness Plugin `openai` автоматично вмикає Server-side Compaction: + Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) обгортка потоку Pi-harness Plugin OpenAI автоматично вмикає Server-side Compaction: - - Примусово задає `store: true` (якщо сумісність моделі не встановлює `supportsStore: false`) + - Примусово встановлює `store: true` (якщо лише compat моделі не задає `supportsStore: false`) - Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]` - - Типове значення `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо значення недоступне) + - Типове значення `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо недоступне) - Це застосовується до вбудованого шляху Pi harness і до хуків постачальника OpenAI, які використовуються вбудованими запусками. Нативний Codex app-server harness керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`. + Це застосовується до вбудованого шляху Pi harness і до хуків постачальника OpenAI, які використовуються вбудованими запусками. Нативна обв’язка app-server Codex керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`. - - Корисно для сумісних endpoint, таких як Azure OpenAI Responses: + + Корисно для сумісних кінцевих точок, таких як Azure OpenAI Responses: ```json5 { @@ -708,7 +719,7 @@ Azure OpenAI використовує нативний транспорт і п } ``` - + ```json5 { agents: { @@ -726,7 +737,7 @@ Azure OpenAI використовує нативний транспорт і п - `responsesServerCompaction` керує лише вставленням `context_management`. Прямі моделі OpenAI Responses все одно примусово використовують `store: true`, якщо compat не задає `supportsStore: false`. + `responsesServerCompaction` керує лише вставкою `context_management`. Прямі моделі OpenAI Responses усе одно примусово використовують `store: true`, якщо compat не задає `supportsStore: false`. @@ -744,33 +755,33 @@ Azure OpenAI використовує нативний транспорт і п } ``` - З `strict-agentic` OpenClaw: - - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія через інструмент + Із `strict-agentic` OpenClaw: + - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента - Повторює хід із вказівкою діяти негайно - Автоматично вмикає `update_plan` для суттєвої роботи - - Показує явний стан блокування, якщо модель продовжує планувати без дії + - Показує явний заблокований стан, якщо модель продовжує планувати без дій - Обмежено лише запуском OpenAI і Codex сімейства GPT-5. Інші постачальники й старіші сімейства моделей зберігають типову поведінку. + Обмежено лише запуском сімейства GPT-5 OpenAI і Codex. Інші постачальники та старіші сімейства моделей зберігають типову поведінку. - - OpenClaw по-різному обробляє прямі endpoint OpenAI, Codex і Azure OpenAI порівняно із загальними OpenAI-сумісними проксі `/v1`: + + OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI порівняно із загальними OpenAI-сумісними проксі `/v1`: **Нативні маршрути** (`openai/*`, Azure OpenAI): - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` effort - Пропускають вимкнений reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"` - - Типово використовують строгий режим для схем інструментів + - Типово використовують суворий режим для схем інструментів - Додають приховані заголовки атрибуції лише на перевірених нативних хостах - - Зберігають формування запитів, характерне лише для OpenAI (`service_tier`, `store`, reasoning-compat, підказки prompt-cache) + - Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, compat reasoning, підказки кешу промптів) **Проксі/сумісні маршрути:** - Використовують м’якшу compat-поведінку - - Не примушують строгі схеми інструментів або нативні заголовки + - Не примушують до суворих схем інструментів або нативних заголовків - Azure OpenAI використовує нативний транспорт і compat-поведінку, але не отримує приховані заголовки атрибуції. + Azure OpenAI використовує нативний транспорт і compat-поведінку, але не отримує прихованих заголовків атрибуції. @@ -779,15 +790,15 @@ Azure OpenAI використовує нативний транспорт і п - Вибір постачальників, посилань на моделі та поведінки failover. + Вибір постачальників, посилань на моделі та поведінки резервного перемикання. Спільні параметри інструмента зображень і вибір постачальника. - Спільні параметри інструмента відео та вибір постачальника. + Спільні параметри інструмента відео і вибір постачальника. - - Докладніше про автентифікацію та правила повторного використання облікових даних. + + Подробиці автентифікації та правила повторного використання облікових даних. diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index 690af377d..fe4631b7b 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -1,27 +1,27 @@ --- read_when: - - Установлення або налаштування Plugin-ів - - Розуміння правил виявлення та завантаження Plugin-ів - - Робота з bundle-ами Plugin-ів, сумісними з Codex/Claude + - Встановлення або налаштування плагінів + - Розуміння правил виявлення та завантаження плагінів + - Робота з сумісними з Codex/Claude пакетами плагінів sidebarTitle: Install and Configure -summary: Установлення, налаштування та керування Plugin OpenClaw -title: Plugins +summary: Встановлюйте, налаштовуйте та керуйте плагінами OpenClaw +title: Плагіни x-i18n: - generated_at: "2026-04-23T21:16:47Z" + generated_at: "2026-04-24T05:42:16Z" model: gpt-5.4 provider: openai - source_hash: a2cf5cb6146ae5e52a32201ee08c03211dbea2313b884c696307abc56d3f9cbf + source_hash: a93114ddb312552f4c321b6e318f3e19810cf5059dd0c68fde93da41936566b8 source_path: tools/plugin.md workflow: 15 --- -Plugins розширюють OpenClaw новими можливостями: channels, model providers, -tools, Skills, speech, realtime transcription, realtime voice, -media-understanding, image generation, video generation, web fetch, web -search тощо. Деякі plugins є **core** (постачаються разом з OpenClaw), інші — -**external** (публікуються спільнотою в npm). +Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей, +інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному часі, +розуміння медіа, генерація зображень, генерація відео, отримання даних з вебу, вебпошук +та інше. Деякі плагіни є **core** (постачаються разом з OpenClaw), інші — +**external** (опубліковані спільнотою в npm). -## Швидкий старт +## Швидкий початок @@ -30,12 +30,12 @@ search тощо. Деякі plugins є **core** (постачаються раз ``` - + ```bash # З npm openclaw plugins install @openclaw/voice-call - # З локального каталогу або archive + # З локального каталогу або архіву openclaw plugins install ./my-plugin openclaw plugins install ./my-plugin.tgz ``` @@ -52,7 +52,7 @@ search тощо. Деякі plugins є **core** (постачаються раз -Якщо вам зручніше керувати через чат, увімкніть `commands.plugins: true` і використовуйте: +Якщо ви віддаєте перевагу керуванню безпосередньо в чаті, увімкніть `commands.plugins: true` і використовуйте: ```text /plugin install clawhub:@openclaw/voice-call @@ -60,51 +60,53 @@ search тощо. Деякі plugins є **core** (постачаються раз /plugin enable voice-call ``` -Шлях install використовує той самий resolver, що й CLI: local path/archive, явний -`clawhub:` або звичайний package spec (спочатку ClawHub, потім fallback до npm). +Шлях встановлення використовує той самий механізм визначення, що й CLI: локальний +шлях/архів, явний `clawhub:` або специфікація пакета без префікса +(спочатку ClawHub, потім резервно npm). -Якщо config невалідна, install зазвичай завершується в закритий спосіб і вказує вам на -`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення bundled-plugin -для plugins, які явно підтримують +Якщо конфігурація недійсна, встановлення зазвичай безпечно завершується з помилкою і вказує на +`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях +перевстановлення вбудованого плагіна для плагінів, які явно підтримують `openclaw.install.allowInvalidConfigRecovery`. -Пакетні встановлення OpenClaw не встановлюють eager-способом усе дерево runtime dependencies кожного bundled plugin. -Коли bundled Plugin, яким володіє OpenClaw, активний через -конфігурацію plugin, legacy channel config або default-enabled manifest, startup -відновлює лише задекларовані runtime dependencies цього plugin перед його import. Зовнішні plugins і custom load paths однаково повинні встановлюватися через +У пакетних інсталяціях OpenClaw не виконується завчасне встановлення всього дерева +runtime-залежностей кожного вбудованого плагіна. Коли вбудований плагін, що належить OpenClaw, активний через +конфігурацію плагіна, застарілу конфігурацію каналу або маніфест із увімкненням за замовчуванням, +під час запуску відновлюються лише оголошені runtime-залежності цього плагіна перед його імпортом. +External-плагіни та користувацькі шляхи завантаження, як і раніше, потрібно встановлювати через `openclaw plugins install`. -## Типи Plugin-ів +## Типи плагінів -OpenClaw розпізнає два формати Plugin-ів: +OpenClaw розпізнає два формати плагінів: -| Формат | Як це працює | Приклади | -| ---------- | --------------------------------------------------------------- | ------------------------------------------------------ | -| **Native** | `openclaw.plugin.json` + runtime module; виконується in-process | Офіційні plugins, community npm packages | -| **Bundle** | Сумісний із Codex/Claude/Cursor layout; відображається на можливості OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| Формат | Як це працює | Приклади | +| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------ | +| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в тому ж процесі | Офіційні плагіни, пакети npm від спільноти | +| **Bundle** | Сумісне з Codex/Claude/Cursor компонування; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Обидва типи з’являються в `openclaw plugins list`. Деталі щодо bundles див. в [Plugin Bundles](/uk/plugins/bundles). +Обидва відображаються в `openclaw plugins list`. Див. [Пакети плагінів](/uk/plugins/bundles) для деталей про пакети. -Якщо ви пишете native Plugin, почніть із [Building Plugins](/uk/plugins/building-plugins) -та [Plugin SDK Overview](/uk/plugins/sdk-overview). +Якщо ви пишете native-плагін, почніть з [Створення плагінів](/uk/plugins/building-plugins) +та [Огляд Plugin SDK](/uk/plugins/sdk-overview). -## Офіційні plugins +## Офіційні плагіни -### Установлювані (npm) +### Доступні для встановлення (npm) -| Plugin | Пакет | Документація | +| Плагін | Пакет | Документація | | --------------- | --------------------- | ------------------------------------ | | Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) | | Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) | | Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) | -| Voice Call | `@openclaw/voice-call`| [Voice Call](/uk/plugins/voice-call) | +| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) | | Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | -### Core (постачаються з OpenClaw) +### Core (постачаються разом з OpenClaw) - + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, @@ -112,22 +114,22 @@ OpenClaw розпізнає два формати Plugin-ів: `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - - - `memory-core` — вбудований memory search (типово через `plugins.slots.memory`) - - `memory-lancedb` — memory довгого зберігання з install-on-demand та auto-recall/capture (установіть `plugins.slots.memory = "memory-lancedb"`) + + - `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`) + - `memory-lancedb` — довготривала пам’ять зі встановленням на вимогу з автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`) - + `elevenlabs`, `microsoft` - - `browser` — вбудований browser plugin для browser tool, CLI `openclaw browser`, gateway method `browser.request`, browser runtime і типового browser control service (увімкнено типово; вимкніть перед заміною) - - `copilot-proxy` — bridge VS Code Copilot Proxy (типово вимкнено) + - `browser` — вбудований browser-плагін для browser-інструмента, CLI `openclaw browser`, методу Gateway `browser.request`, browser runtime та стандартного сервісу керування browser (увімкнений за замовчуванням; вимкніть його перед заміною) + - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням) -Шукаєте сторонні plugins? Див. [Community Plugins](/uk/plugins/community). +Шукаєте сторонні плагіни? Див. [Плагіни спільноти](/uk/plugins/community). ## Конфігурація @@ -145,103 +147,110 @@ OpenClaw розпізнає два формати Plugin-ів: } ``` -| Поле | Опис | +| Поле | Опис | | ---------------- | --------------------------------------------------------- | | `enabled` | Головний перемикач (типово: `true`) | -| `allow` | Allowlist Plugin-ів (необов’язково) | -| `deny` | Denylist Plugin-ів (необов’язково; deny має пріоритет) | -| `load.paths` | Додаткові файли/каталоги Plugin-ів | -| `slots` | Вибір exclusive slot-ів (наприклад `memory`, `contextEngine`) | -| `entries.\` | Перемикачі для окремого Plugin + config | +| `allow` | Список дозволених плагінів (необов’язково) | +| `deny` | Список заборонених плагінів (необов’язково; deny має пріоритет) | +| `load.paths` | Додаткові файли/каталоги плагінів | +| `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) | +| `entries.\` | Перемикачі та конфігурація для окремого плагіна | -Зміни конфігурації **вимагають перезапуску gateway**. Якщо Gateway працює з config -watch + in-process restart enabled (типовий шлях `openclaw gateway`), цей -перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації. +Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з увімкненими +відстеженням конфігурації та внутрішньопроцесним перезапуском (типовий шлях `openclaw gateway`), +цей перезапуск зазвичай виконується автоматично невдовзі після запису змін у конфігурацію. - - - **Disabled**: plugin існує, але правила enablement його вимкнули. Config зберігається. - - **Missing**: config посилається на plugin id, якого виявлення не знайшло. - - **Invalid**: plugin існує, але його config не відповідає задекларованій schema. + + - **Вимкнений**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається. + - **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення. + - **Недійсний**: плагін існує, але його конфігурація не відповідає оголошеній схемі. -## Discovery і precedence +## Виявлення та пріоритет -OpenClaw сканує plugins у такому порядку (перше співпадіння перемагає): +OpenClaw сканує плагіни в такому порядку (перше співпадіння перемагає): - + `plugins.load.paths` — явні шляхи до файлів або каталогів. - + `\/.openclaw//*.ts` і `\/.openclaw//*/index.ts`. - + `~/.openclaw//*.ts` і `~/.openclaw//*/index.ts`. - - Постачаються з OpenClaw. Багато з них увімкнені типово (model providers, speech). + + Постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (постачальники моделей, мовлення). Інші потребують явного ввімкнення. -### Правила enablement +### Правила ввімкнення -- `plugins.enabled: false` вимикає всі plugins +- `plugins.enabled: false` вимикає всі плагіни - `plugins.deny` завжди має пріоритет над allow -- `plugins.entries.\.enabled: false` вимикає цей plugin -- Plugins, що походять із workspace, **типово вимкнені** (їх потрібно явно ввімкнути) -- Bundled plugins дотримуються вбудованого набору default-on, якщо не перевизначено -- Exclusive slots можуть примусово ввімкнути plugin, вибраний для цього slot +- `plugins.entries.\.enabled: false` вимикає цей плагін +- Плагіни з робочого простору **вимкнені за замовчуванням** (їх треба явно ввімкнути) +- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо не перевизначено +- Ексклюзивні слоти можуть примусово ввімкнути вибраний для цього слота плагін +- Деякі вбудовані плагіни з режимом явного підключення автоматично вмикаються, коли конфігурація вказує + на поверхню, що належить плагіну, наприклад посилання на модель постачальника, конфігурацію каналу або runtime + harness +- Маршрути Codex сімейства OpenAI зберігають окремі межі плагінів: + `openai-codex/*` належить плагіну OpenAI, тоді як вбудований плагін + app-server Codex вибирається через `embeddedHarness.runtime: "codex"` або застарілі + посилання на модель `codex/*` -## Plugin slots (exclusive categories) +## Слоти плагінів (ексклюзивні категорії) -Деякі категорії є exclusive (одночасно може бути активною лише одна): +Деякі категорії є ексклюзивними (одночасно активний лише один плагін): ```json5 { plugins: { slots: { - memory: "memory-core", // або "none" для вимкнення - contextEngine: "legacy", // або plugin id + memory: "memory-core", // або "none", щоб вимкнути + contextEngine: "legacy", // або ідентифікатор плагіна }, }, } ``` -| Slot | Що він контролює | Типове значення | -| --------------- | ---------------------- | ------------------ | -| `memory` | Активний memory plugin | `memory-core` | -| `contextEngine` | Активний context engine| `legacy` (built-in) | +| Слот | Що він контролює | Типове значення | +| --------------- | ----------------------- | ------------------- | +| `memory` | Active Memory plugin | `memory-core` | +| `contextEngine` | Активний механізм контексту | `legacy` (вбудований) | ## Довідка CLI ```bash -openclaw plugins list # компактний інвентар -openclaw plugins list --enabled # лише завантажені plugins -openclaw plugins list --verbose # докладні рядки для кожного plugin -openclaw plugins list --json # машиночитаний інвентар -openclaw plugins inspect # глибокі деталі -openclaw plugins inspect --json # машиночитаний формат +openclaw plugins list # стислий перелік +openclaw plugins list --enabled # лише завантажені плагіни +openclaw plugins list --verbose # детальні рядки для кожного плагіна +openclaw plugins list --json # перелік у машиночитному форматі +openclaw plugins inspect # докладна інформація +openclaw plugins inspect --json # машиночитний формат openclaw plugins inspect --all # таблиця для всього набору -openclaw plugins info # псевдонім inspect +openclaw plugins info # псевдонім для inspect openclaw plugins doctor # діагностика -openclaw plugins install # установлення (спочатку ClawHub, потім npm) -openclaw plugins install clawhub: # установлення лише з ClawHub +openclaw plugins install # встановити (спочатку ClawHub, потім npm) +openclaw plugins install clawhub: # встановити лише з ClawHub openclaw plugins install --force # перезаписати наявне встановлення -openclaw plugins install # установлення з локального шляху -openclaw plugins install -l # link (без копіювання) для dev +openclaw plugins install # встановити з локального шляху +openclaw plugins install -l # підключити (без копіювання) для розробки openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # записати точний resolved npm spec +openclaw plugins install --pin # зберегти точну розв’язану npm-специфікацію openclaw plugins install --dangerously-force-unsafe-install -openclaw plugins update # оновити один plugin +openclaw plugins update # оновити один плагін openclaw plugins update --dangerously-force-unsafe-install openclaw plugins update --all # оновити всі -openclaw plugins uninstall # прибрати записи config/install +openclaw plugins uninstall # видалити записи конфігурації/встановлення openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -250,54 +259,59 @@ openclaw plugins enable openclaw plugins disable ``` -Bundled plugins постачаються з OpenClaw. Багато з них увімкнені типово (наприклад -bundled model providers, bundled speech providers і bundled browser -plugin). Інші bundled plugins однаково потребують `openclaw plugins enable `. +Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад, +вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser-плагін). +Інші вбудовані плагіни все одно потребують `openclaw plugins enable `. -`--force` перезаписує наявний встановлений plugin або hook pack на місці. Використовуйте -`openclaw plugins update ` для звичайних оновлень відстежуваних npm -plugins. Він не підтримується разом із `--link`, який повторно використовує шлях до source -замість копіювання до керованої цілі встановлення. +`--force` перезаписує наявний встановлений плагін або пакет хуків на місці. Використовуйте +`openclaw plugins update ` для звичайних оновлень відстежуваних npm-плагінів. +Він не підтримується з `--link`, який повторно використовує шлях до джерела замість +копіювання в кероване місце встановлення. Коли `plugins.allow` уже задано, `openclaw plugins install` додає -id встановленого plugin до цього allowlist перед його ввімкненням, тож після перезапуску встановлення -одразу можна буде завантажити. +ідентифікатор встановленого плагіна до цього списку allow перед його ввімкненням, щоб установлені +плагіни можна було одразу завантажити після перезапуску. -`openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання -npm package spec з dist-tag або точною версією розв’язує ім’я пакета -назад до запису відстежуваного plugin і записує новий spec для майбутніх оновлень. -Передавання імені пакета без версії переводить exact pinned install назад на -типову release line registry. Якщо встановлений npm plugin уже відповідає -розв’язаній версії й записаній artifact identity, OpenClaw пропускає оновлення -без завантаження, перевстановлення або переписування config. +`openclaw plugins update ` застосовується до відстежуваних установлень. Передача +специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета +назад із записом відстежуваного плагіна і зберігає нову специфікацію для майбутніх оновлень. +Передача назви пакета без версії переводить точне закріплене встановлення назад на +типову лінійку релізів реєстру. Якщо встановлений npm-плагін уже відповідає +розв’язаній версії та збереженій ідентичності артефакту, OpenClaw пропускає оновлення +без завантаження, перевстановлення чи перезапису конфігурації. -`--pin` працює лише з npm. Він не підтримується з `--marketplace`, оскільки -встановлення з marketplace зберігають метадані джерела marketplace, а не npm spec. +`--pin` працює лише для npm. Він не підтримується з `--marketplace`, оскільки +встановлення з marketplace зберігають метадані джерела marketplace замість npm-специфікації. -`--dangerously-force-unsafe-install` — це break-glass override для хибнопозитивних спрацьовувань -вбудованого scanner dangerous-code. Він дозволяє продовжити install і update plugin-ів попри вбудовані findings рівня `critical`, але все одно не обходить policy blocks `before_install` plugin-а або блокування через збій scanner-а. +`--dangerously-force-unsafe-install` — це аварійний режим обходу для хибних +спрацьовувань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення +та оновлення плагінів попри вбудовані результати `critical`, але все одно +не обходить блокування політики плагіна `before_install` або блокування через помилки сканування. -Цей прапорець CLI застосовується лише до потоків install/update plugin-ів. Установлення залежностей для Skills, що працює через Gateway, використовує відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` лишається окремим потоком завантаження/встановлення Skills із ClawHub. +Цей прапорець CLI застосовується лише до процесів встановлення/оновлення плагінів. Встановлення залежностей Skills через Gateway +натомість використовують відповідний параметр запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` +залишається окремим процесом завантаження/встановлення Skills через ClawHub. -Сумісні bundles беруть участь у тому самому потоці list/inspect/enable/disable plugin-ів. Поточна підтримка runtime включає bundle Skills, command-skills Claude, -типові значення `settings.json` Claude, типові значення `.lsp.json` Claude та -`lspServers`, оголошені в manifest, command-skills Cursor і сумісні каталоги hooks Codex. +Сумісні пакети беруть участь у тому самому процесі list/inspect/enable/disable +для плагінів. Поточна підтримка runtime охоплює bundle Skills, Claude command-skills, +типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і +оголошені в маніфесті типові значення `lspServers`, Cursor command-skills і сумісні каталоги хуків Codex. -`openclaw plugins inspect ` також повідомляє про виявлені можливості bundle плюс -підтримувані або непідтримувані записи MCP і LSP server для plugin-ів на основі bundle. +`openclaw plugins inspect ` також повідомляє про виявлені можливості пакета, а також +підтримувані чи непідтримувані записи серверів MCP і LSP для плагінів на основі пакетів. -Джерелами marketplace можуть бути відома назва marketplace Claude з -`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях -`marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію GitHub -або URL git. Для віддалених marketplace записи plugin мають залишатися всередині -клонованого репозиторію marketplace і використовувати лише відносні джерела шляхів. +Джерелами marketplace можуть бути відома назва Claude marketplace з +`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях до +`marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub +або git URL. Для віддалених marketplace записи плагінів мають залишатися в межах +клонованого репозиторію marketplace і використовувати лише відносні шляхи як джерела. -Повні подробиці див. у [довідці CLI `openclaw plugins`](/uk/cli/plugins). +Див. [довідку CLI `openclaw plugins`](/uk/cli/plugins) для повної інформації. -## Огляд API Plugin +## Огляд Plugin API -Native plugins експортують об’єкт entry, який відкриває `register(api)`. Старіші -plugins усе ще можуть використовувати `activate(api)` як legacy alias, але нові plugins мають +Native-плагіни експортують об’єкт entry, який надає `register(api)`. Старіші +плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни мають використовувати `register`. ```typescript @@ -319,47 +333,48 @@ export default definePluginEntry({ ``` OpenClaw завантажує об’єкт entry і викликає `register(api)` під час активації -plugin. Loader усе ще повертається до `activate(api)` для старіших plugins, -але bundled plugins і нові external plugins мають вважати `register` публічним контрактом. +плагіна. Завантажувач усе ще використовує `activate(api)` як запасний варіант для старіших плагінів, +але вбудовані плагіни та нові external-плагіни мають розглядати `register` як +публічний контракт. Поширені методи реєстрації: -| Метод | Що він реєструє | -| --------------------------------------- | --------------------------- | -| `registerProvider` | Model provider (LLM) | -| `registerChannel` | Chat channel | -| `registerTool` | Agent tool | -| `registerHook` / `on(...)` | Lifecycle hooks | -| `registerSpeechProvider` | Text-to-speech / STT | -| `registerRealtimeTranscriptionProvider` | Streaming STT | -| `registerRealtimeVoiceProvider` | Duplex realtime voice | -| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | -| `registerImageGenerationProvider` | Генерування зображень | -| `registerMusicGenerationProvider` | Генерування музики | -| `registerVideoGenerationProvider` | Генерування відео | -| `registerWebFetchProvider` | Provider web fetch / scrape | -| `registerWebSearchProvider` | Web search | -| `registerHttpRoute` | HTTP endpoint | -| `registerCommand` / `registerCli` | Команди CLI | -| `registerContextEngine` | Context engine | -| `registerService` | Background service | +| Метод | Що він реєструє | +| --------------------------------------- | -------------------------- | +| `registerProvider` | Постачальник моделей (LLM) | +| `registerChannel` | Канал чату | +| `registerTool` | Інструмент агента | +| `registerHook` / `on(...)` | Хуки життєвого циклу | +| `registerSpeechProvider` | Синтез мовлення / STT | +| `registerRealtimeTranscriptionProvider` | Потоковий STT | +| `registerRealtimeVoiceProvider` | Двоспрямований голос у реальному часі | +| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | +| `registerImageGenerationProvider` | Генерація зображень | +| `registerMusicGenerationProvider` | Генерація музики | +| `registerVideoGenerationProvider` | Генерація відео | +| `registerWebFetchProvider` | Постачальник отримання/скрапінгу з вебу | +| `registerWebSearchProvider` | Вебпошук | +| `registerHttpRoute` | HTTP-ендпоінт | +| `registerCommand` / `registerCli` | Команди CLI | +| `registerContextEngine` | Механізм контексту | +| `registerService` | Фонова служба | -Поведінка guard hooks для типізованих lifecycle hooks: +Поведінка guard-хуків для типізованих хуків життєвого циклу: -- `before_tool_call`: `{ block: true }` є термінальним; handlers нижчого пріоритету пропускаються. -- `before_tool_call`: `{ block: false }` — no-op і не скасовує раніше встановлений block. -- `before_install`: `{ block: true }` є термінальним; handlers нижчого пріоритету пропускаються. -- `before_install`: `{ block: false }` — no-op і не скасовує раніше встановлений block. -- `message_sending`: `{ cancel: true }` є термінальним; handlers нижчого пріоритету пропускаються. -- `message_sending`: `{ cancel: false }` — no-op і не скасовує раніше встановлений cancel. +- `before_tool_call`: `{ block: true }` є остаточним; обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: `{ block: false }` не має ефекту і не скасовує попереднє блокування. +- `before_install`: `{ block: true }` є остаточним; обробники з нижчим пріоритетом пропускаються. +- `before_install`: `{ block: false }` не має ефекту і не скасовує попереднє блокування. +- `message_sending`: `{ cancel: true }` є остаточним; обробники з нижчим пріоритетом пропускаються. +- `message_sending`: `{ cancel: false }` не має ефекту і не скасовує попереднє скасування. -Повну поведінку типізованих hooks див. в [SDK Overview](/uk/plugins/sdk-overview#hook-decision-semantics). +Для повної інформації про поведінку типізованих хуків див. [Огляд SDK](/uk/plugins/sdk-overview#hook-decision-semantics). ## Пов’язане -- [Building Plugins](/uk/plugins/building-plugins) — створення власного Plugin -- [Plugin Bundles](/uk/plugins/bundles) — сумісність bundle-ів Codex/Claude/Cursor -- [Plugin Manifest](/uk/plugins/manifest) — схема маніфесту -- [Registering Tools](/uk/plugins/building-plugins#registering-agent-tools) — додавання agent tools у Plugin -- [Plugin Internals](/uk/plugins/architecture) — модель capability і pipeline завантаження -- [Community Plugins](/uk/plugins/community) — списки сторонніх Plugin-ів +- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін +- [Пакети плагінів](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor +- [Маніфест плагіна](/uk/plugins/manifest) — схема маніфесту +- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додавання агентських інструментів у плагін +- [Внутрішня архітектура плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження +- [Плагіни спільноти](/uk/plugins/community) — сторонні каталоги