chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
33051cdc10
commit
f279357f1c
@ -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 <provider/model>`.
|
||||
- `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `contextTokens` — це фактичне обмеження runtime.
|
||||
- Правила резервного перемикання, cooldown probes і збереження перевизначень сесії: [Model failover](/uk/concepts/model-failover).
|
||||
- Маршрути сімейства OpenAI залежать від префікса: `openai/<model>` використовує прямого провайдера API-ключа
|
||||
OpenAI у PI, `openai-codex/<model>` використовує Codex OAuth у PI,
|
||||
а `openai/<model>` плюс `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 <provider/model>`.
|
||||
- `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `contextTokens` — це фактичне обмеження середовища виконання.
|
||||
- Правила резервного перемикання, перевірки cooldown і збереження перевизначень сеансу: [Відмовостійкість моделей](/uk/concepts/model-failover).
|
||||
- Маршрути сімейства OpenAI залежать від префікса: `openai/<model>` використовує прямого постачальника API-ключа OpenAI у PI, `openai-codex/<model>` використовує OAuth Codex у PI, а `openai/<model>` разом із `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний harness app-server Codex. Див. [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness).
|
||||
- Автоматичне ввімкнення Plugin дотримується цієї ж межі: `openai-codex/<model>` належить до Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/<model>`.
|
||||
- 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). Постачальник, якому потрібен повністю власний виконавець запитів, є окремою, глибшою поверхнею розширення.
|
||||
|
||||
<Note>
|
||||
`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 (текстовий інференс, мовлення тощо).
|
||||
</Note>
|
||||
|
||||
## Ротація API-ключів
|
||||
|
||||
- Підтримується загальна ротація ключів провайдерів для вибраних провайдерів.
|
||||
- Підтримує загальну ротацію постачальників для вибраних постачальників.
|
||||
- Налаштуйте кілька ключів через:
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (одне live-перевизначення, найвищий пріоритет)
|
||||
- `<PROVIDER>_API_KEYS` (список через кому або крапку з комою)
|
||||
- `<PROVIDER>_API_KEY` (основний ключ)
|
||||
- `<PROVIDER>_API_KEY_*` (нумерований список, наприклад `<PROVIDER>_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/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Розігрів WebSocket для OpenAI Responses типово увімкнений через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Пріоритетну обробку OpenAI можна увімкнути через `agents.defaults.models["openai/<model>"].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/<model>"].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/<model>"].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/<model>"].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/<model>"].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/<model>"].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.<id>` лише тоді, коли хочете перевизначити
|
||||
типовий 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) — інструкції з налаштування для кожного постачальника
|
||||
|
||||
@ -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.
|
||||
|
||||
<Note>
|
||||
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`.
|
||||
</Note>
|
||||
|
||||
## Покриття функцій OpenClaw
|
||||
<Note>
|
||||
Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не
|
||||
увімкне вбудований Plugin app-server Codex. OpenClaw вмикає цей Plugin лише
|
||||
коли ви явно вибираєте нативну обв’язку Codex через
|
||||
`embeddedHarness.runtime: "codex"` або використовуєте застаріле посилання на модель `codex/*`.
|
||||
</Note>
|
||||
|
||||
| Можливість OpenAI | Поверхня OpenClaw | Статус |
|
||||
| ------------------------- | -------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| Chat / Responses | постачальник моделей `openai/<model>` | Так |
|
||||
| Моделі за підпискою Codex | `openai-codex/<model>` з OAuth `openai-codex` | Так |
|
||||
| Codex app-server harness | `openai/<model>` з `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/<model>` | Так |
|
||||
| Моделі підписки Codex | `openai-codex/<model>` з OAuth `openai-codex` | Так |
|
||||
| Обв’язка app-server Codex | `openai/<model>` з `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 для пам’яті | Так |
|
||||
|
||||
## Початок роботи
|
||||
|
||||
Виберіть бажаний спосіб автентифікації й виконайте кроки налаштування.
|
||||
Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API-ключ (OpenAI Platform)">
|
||||
<Tab title="API key (платформа OpenAI)">
|
||||
**Найкраще для:** прямого доступу до API та оплати за використання.
|
||||
|
||||
<Steps>
|
||||
<Step title="Отримайте свій API-ключ">
|
||||
Створіть або скопіюйте API-ключ з [панелі OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
<Step title="Отримайте свій API key">
|
||||
Створіть або скопіюйте API key з [інформаційної панелі платформи OpenAI](https://platform.openai.com/api-keys).
|
||||
</Step>
|
||||
<Step title="Запустіть початкове налаштування">
|
||||
<Step title="Запустіть первинне налаштування">
|
||||
```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"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Переконайтеся, що модель доступна">
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
```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` |
|
||||
|
||||
<Note>
|
||||
`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 за замовчуванням.
|
||||
</Note>
|
||||
|
||||
### Приклад конфігурації
|
||||
@ -101,16 +108,16 @@ Codex app-server harness. Прямий доступ за API-ключем для
|
||||
```
|
||||
|
||||
<Warning>
|
||||
OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Живі запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає.
|
||||
OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Активні запити до API OpenAI відхиляють цю модель, і поточний каталог Codex також її не надає.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Підписка Codex">
|
||||
**Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API-ключа. Codex cloud вимагає входу через ChatGPT.
|
||||
**Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API key. Codex cloud потребує входу через ChatGPT.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть Codex OAuth">
|
||||
<Step title="Запустіть OAuth Codex">
|
||||
```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
|
||||
```
|
||||
</Step>
|
||||
<Step title="Задайте модель за замовчуванням">
|
||||
<Step title="Встановіть модель за замовчуванням">
|
||||
```bash
|
||||
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
|
||||
```
|
||||
</Step>
|
||||
<Step title="Переконайтеся, що модель доступна">
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
```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 |
|
||||
|
||||
<Note>
|
||||
Продовжуйте використовувати ідентифікатор постачальника `openai-codex` для команд автентифікації/профілю. Префікс моделі
|
||||
`openai-codex/*` також є явним маршрутом PI для Codex OAuth.
|
||||
`openai-codex/*` також є явним маршрутом PI для OAuth Codex.
|
||||
Він не вибирає і не автовмикає вбудовану обв’язку app-server Codex.
|
||||
</Note>
|
||||
|
||||
### Приклад конфігурації
|
||||
@ -160,29 +168,29 @@ Codex app-server harness. Прямий доступ за API-ключем для
|
||||
```
|
||||
|
||||
<Note>
|
||||
Початкове налаштування більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через OAuth у браузері (типовий варіант) або через потік коду пристрою, вказаний вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента.
|
||||
Первинне налаштування більше не імпортує OAuth-матеріали з `~/.codex`. Увійдіть через OAuth у браузері (за замовчуванням) або через потік коду пристрою вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента.
|
||||
</Note>
|
||||
|
||||
### Індикатор стану
|
||||
|
||||
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-ключем для
|
||||
```
|
||||
|
||||
<Note>
|
||||
Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання.
|
||||
Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту середовища виконання.
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
@ -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-ключем для
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору постачальника та поведінки failover.
|
||||
Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку при перемиканні на резервний варіант.
|
||||
</Note>
|
||||
|
||||
`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.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору постачальника та поведінки failover.
|
||||
Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку при перемиканні на резервний варіант.
|
||||
</Note>
|
||||
|
||||
## Внесок у 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"` | Вимкнути лише шар дружнього стилю |
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Конфігурація">
|
||||
@ -321,11 +331,11 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
Значення під час виконання не чутливі до регістру, тому і `"Off"`, і `"off"` вимикають дружній стиль.
|
||||
Під час виконання значення нечутливі до регістру, тому і `"Off"`, і `"off"` вимикають шар дружнього стилю.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Застарілий `plugins.entries.openai.config.personality` усе ще читається як сумісний запасний варіант, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано.
|
||||
Застаріле `plugins.entries.openai.config.personality` усе ще зчитується як резервний варіант сумісності, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задане.
|
||||
</Note>
|
||||
|
||||
## Голос і мовлення
|
||||
@ -334,15 +344,15 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап
|
||||
<Accordion title="Синтез мовлення (TTS)">
|
||||
Вбудований 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 для зап
|
||||
```
|
||||
|
||||
<Note>
|
||||
Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базову URL-адресу TTS без впливу на endpoint chat API.
|
||||
Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS, не впливаючи на кінцеву точку API чату.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Перетворення мовлення на текст">
|
||||
Вбудований 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, коли вони надаються
|
||||
спільною конфігурацією аудіомедіа або запитом транскрибування для окремого виклику.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Транскрибування в реальному часі">
|
||||
Вбудований 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` |
|
||||
|
||||
<Note>
|
||||
Використовує 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`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -421,47 +431,47 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап
|
||||
<Accordion title="Голос у реальному часі">
|
||||
Вбудований 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` |
|
||||
|
||||
<Note>
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлені виклики інструментів. Використовує аудіоформат G.711 u-law.
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує аудіоформат G.711 u-law.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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.
|
||||
|
||||
<Note>
|
||||
Голос у реальному часі використовує окремий шлях конфігурації
|
||||
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
|
||||
і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у реальному
|
||||
часі** в розділі [Голос і мовлення](#voice-and-speech) для налаштувань Azure.
|
||||
часі** в розділі [Голос і мовлення](#voice-and-speech) для його налаштувань Azure.
|
||||
</Note>
|
||||
|
||||
Використовуйте 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.
|
||||
|
||||
<Note>
|
||||
Маршрутизація Azure для шляху генерації зображень постачальника `openai`
|
||||
потребує OpenClaw 2026.4.22 або новішої версії. Раніші версії обробляють будь-який користувацький
|
||||
`openai.baseUrl` як публічний endpoint OpenAI і завершуються помилкою при роботі з deployment зображень Azure.
|
||||
Маршрутизація Azure для шляху генерації зображень постачальника `openai` вимагає
|
||||
OpenClaw 2026.4.22 або новішої версії. У раніших версіях будь-який користувацький
|
||||
`openai.baseUrl` обробляється як публічна кінцева точка OpenAI і не працюватиме з розгортаннями
|
||||
зображень Azure.
|
||||
</Note>
|
||||
|
||||
### Версія 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.
|
||||
|
||||
<Note>
|
||||
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 нижче.
|
||||
</Note>
|
||||
|
||||
## Розширена конфігурація
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Транспорт (WebSocket чи SSE)">
|
||||
OpenClaw використовує WebSocket-first із запасним переходом на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`.
|
||||
<Accordion title="Транспорт (WebSocket проти SSE)">
|
||||
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)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Прогрів WebSocket">
|
||||
OpenClaw типово вмикає прогрів WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу.
|
||||
<Accordion title="Прогрівання WebSocket">
|
||||
OpenClaw типово вмикає прогрівання WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу.
|
||||
|
||||
```json5
|
||||
// Вимкнути прогрів
|
||||
// Вимкнути прогрівання
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
@ -617,10 +628,10 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
<Accordion title="Швидкий режим">
|
||||
OpenClaw надає спільний перемикач швидкого режиму для `openai/*` і `openai-codex/*`:
|
||||
|
||||
- **Chat/UI:** `/fast status|on|off`
|
||||
- **Чат/UI:** `/fast status|on|off`
|
||||
- **Конфігурація:** `agents.defaults.models["<provider>/<model>"].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 використовує нативний транспорт і п
|
||||
```
|
||||
|
||||
<Note>
|
||||
Перевизначення сесії мають вищий пріоритет за конфігурацію. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого типового значення.
|
||||
Перевизначення сесії мають вищий пріоритет за конфігурацію. Очищення перевизначення сесії в UI сесій повертає сесію до налаштованого типового значення.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Пріоритетна обробка (service_tier)">
|
||||
API OpenAI надає пріоритетну обробку через `service_tier`. Задайте її для кожної моделі в OpenClaw:
|
||||
API OpenAI надає пріоритетну обробку через `service_tier`. Налаштуйте її для кожної моделі в OpenClaw:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -658,23 +669,23 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
Підтримувані значення: `auto`, `default`, `flex`, `priority`.
|
||||
|
||||
<Warning>
|
||||
`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` без змін.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Server-side Compaction (Responses API)">
|
||||
Для прямих моделей 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`.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Явне ввімкнення">
|
||||
Корисно для сумісних endpoint, таких як Azure OpenAI Responses:
|
||||
<Tab title="Явно ввімкнути">
|
||||
Корисно для сумісних кінцевих точок, таких як Azure OpenAI Responses:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -708,7 +719,7 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Вимкнення">
|
||||
<Tab title="Вимкнути">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -726,7 +737,7 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` керує лише вставленням `context_management`. Прямі моделі OpenAI Responses все одно примусово використовують `store: true`, якщо compat не задає `supportsStore: false`.
|
||||
`responsesServerCompaction` керує лише вставкою `context_management`. Прямі моделі OpenAI Responses усе одно примусово використовують `store: true`, якщо compat не задає `supportsStore: false`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -744,33 +755,33 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
}
|
||||
```
|
||||
|
||||
З `strict-agentic` OpenClaw:
|
||||
- Більше не вважає хід лише з планом успішним прогресом, коли доступна дія через інструмент
|
||||
Із `strict-agentic` OpenClaw:
|
||||
- Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента
|
||||
- Повторює хід із вказівкою діяти негайно
|
||||
- Автоматично вмикає `update_plan` для суттєвої роботи
|
||||
- Показує явний стан блокування, якщо модель продовжує планувати без дії
|
||||
- Показує явний заблокований стан, якщо модель продовжує планувати без дій
|
||||
|
||||
<Note>
|
||||
Обмежено лише запуском OpenAI і Codex сімейства GPT-5. Інші постачальники й старіші сімейства моделей зберігають типову поведінку.
|
||||
Обмежено лише запуском сімейства GPT-5 OpenAI і Codex. Інші постачальники та старіші сімейства моделей зберігають типову поведінку.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні маршрути та OpenAI-сумісні маршрути">
|
||||
OpenClaw по-різному обробляє прямі endpoint OpenAI, Codex і Azure OpenAI порівняно із загальними OpenAI-сумісними проксі `/v1`:
|
||||
<Accordion title="Нативні та OpenAI-сумісні маршрути">
|
||||
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-поведінку, але не отримує прихованих заголовків атрибуції.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -779,15 +790,15 @@ Azure OpenAI використовує нативний транспорт і п
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Вибір моделі" href="/uk/concepts/model-providers" icon="layers">
|
||||
Вибір постачальників, посилань на моделі та поведінки failover.
|
||||
Вибір постачальників, посилань на моделі та поведінки резервного перемикання.
|
||||
</Card>
|
||||
<Card title="Генерація зображень" href="/uk/tools/image-generation" icon="image">
|
||||
Спільні параметри інструмента зображень і вибір постачальника.
|
||||
</Card>
|
||||
<Card title="Генерація відео" href="/uk/tools/video-generation" icon="video">
|
||||
Спільні параметри інструмента відео та вибір постачальника.
|
||||
Спільні параметри інструмента відео і вибір постачальника.
|
||||
</Card>
|
||||
<Card title="OAuth та автентифікація" href="/uk/gateway/authentication" icon="key">
|
||||
Докладніше про автентифікацію та правила повторного використання облікових даних.
|
||||
<Card title="OAuth і автентифікація" href="/uk/gateway/authentication" icon="key">
|
||||
Подробиці автентифікації та правила повторного використання облікових даних.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -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).
|
||||
|
||||
## Швидкий старт
|
||||
## Швидкий початок
|
||||
|
||||
<Steps>
|
||||
<Step title="Подивіться, що завантажено">
|
||||
@ -30,12 +30,12 @@ search тощо. Деякі plugins є **core** (постачаються раз
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Установіть Plugin">
|
||||
<Step title="Встановіть плагін">
|
||||
```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** (постачаються раз
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо вам зручніше керувати через чат, увімкніть `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:<pkg>` або звичайний package spec (спочатку ClawHub, потім fallback до npm).
|
||||
Шлях встановлення використовує той самий механізм визначення, що й CLI: локальний
|
||||
шлях/архів, явний `clawhub:<pkg>` або специфікація пакета без префікса
|
||||
(спочатку 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)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Model providers (увімкнено типово)">
|
||||
<Accordion title="Постачальники моделей (увімкнені за замовчуванням)">
|
||||
`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`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory plugins">
|
||||
- `memory-core` — вбудований memory search (типово через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — memory довгого зберігання з install-on-demand та auto-recall/capture (установіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
<Accordion title="Плагіни пам’яті">
|
||||
- `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довготривала пам’ять зі встановленням на вимогу з автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Speech providers (увімкнено типово)">
|
||||
<Accordion title="Постачальники мовлення (увімкнені за замовчуванням)">
|
||||
`elevenlabs`, `microsoft`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Інше">
|
||||
- `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 (вимкнений за замовчуванням)
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Шукаєте сторонні 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.\<id\>` | Перемикачі для окремого Plugin + config |
|
||||
| `allow` | Список дозволених плагінів (необов’язково) |
|
||||
| `deny` | Список заборонених плагінів (необов’язково; deny має пріоритет) |
|
||||
| `load.paths` | Додаткові файли/каталоги плагінів |
|
||||
| `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) |
|
||||
| `entries.\<id\>` | Перемикачі та конфігурація для окремого плагіна |
|
||||
|
||||
Зміни конфігурації **вимагають перезапуску gateway**. Якщо Gateway працює з config
|
||||
watch + in-process restart enabled (типовий шлях `openclaw gateway`), цей
|
||||
перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації.
|
||||
Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з увімкненими
|
||||
відстеженням конфігурації та внутрішньопроцесним перезапуском (типовий шлях `openclaw gateway`),
|
||||
цей перезапуск зазвичай виконується автоматично невдовзі після запису змін у конфігурацію.
|
||||
|
||||
<Accordion title="Стани Plugin-ів: disabled vs missing vs invalid">
|
||||
- **Disabled**: plugin існує, але правила enablement його вимкнули. Config зберігається.
|
||||
- **Missing**: config посилається на plugin id, якого виявлення не знайшло.
|
||||
- **Invalid**: plugin існує, але його config не відповідає задекларованій schema.
|
||||
<Accordion title="Стани плагінів: вимкнений, відсутній, недійсний">
|
||||
- **Вимкнений**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
|
||||
- **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення.
|
||||
- **Недійсний**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
|
||||
</Accordion>
|
||||
|
||||
## Discovery і precedence
|
||||
## Виявлення та пріоритет
|
||||
|
||||
OpenClaw сканує plugins у такому порядку (перше співпадіння перемагає):
|
||||
OpenClaw сканує плагіни в такому порядку (перше співпадіння перемагає):
|
||||
|
||||
<Steps>
|
||||
<Step title="Шляхи з config">
|
||||
<Step title="Шляхи з конфігурації">
|
||||
`plugins.load.paths` — явні шляхи до файлів або каталогів.
|
||||
</Step>
|
||||
|
||||
<Step title="Workspace plugins">
|
||||
<Step title="Плагіни робочого простору">
|
||||
`\<workspace\>/.openclaw/<plugin-root>/*.ts` і `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Global plugins">
|
||||
<Step title="Глобальні плагіни">
|
||||
`~/.openclaw/<plugin-root>/*.ts` і `~/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Bundled plugins">
|
||||
Постачаються з OpenClaw. Багато з них увімкнені типово (model providers, speech).
|
||||
<Step title="Вбудовані плагіни">
|
||||
Постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (постачальники моделей, мовлення).
|
||||
Інші потребують явного ввімкнення.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Правила enablement
|
||||
### Правила ввімкнення
|
||||
|
||||
- `plugins.enabled: false` вимикає всі plugins
|
||||
- `plugins.enabled: false` вимикає всі плагіни
|
||||
- `plugins.deny` завжди має пріоритет над allow
|
||||
- `plugins.entries.\<id\>.enabled: false` вимикає цей plugin
|
||||
- Plugins, що походять із workspace, **типово вимкнені** (їх потрібно явно ввімкнути)
|
||||
- Bundled plugins дотримуються вбудованого набору default-on, якщо не перевизначено
|
||||
- Exclusive slots можуть примусово ввімкнути plugin, вибраний для цього slot
|
||||
- `plugins.entries.\<id\>.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 <id> # глибокі деталі
|
||||
openclaw plugins inspect <id> --json # машиночитаний формат
|
||||
openclaw plugins list # стислий перелік
|
||||
openclaw plugins list --enabled # лише завантажені плагіни
|
||||
openclaw plugins list --verbose # детальні рядки для кожного плагіна
|
||||
openclaw plugins list --json # перелік у машиночитному форматі
|
||||
openclaw plugins inspect <id> # докладна інформація
|
||||
openclaw plugins inspect <id> --json # машиночитний формат
|
||||
openclaw plugins inspect --all # таблиця для всього набору
|
||||
openclaw plugins info <id> # псевдонім inspect
|
||||
openclaw plugins info <id> # псевдонім для inspect
|
||||
openclaw plugins doctor # діагностика
|
||||
|
||||
openclaw plugins install <package> # установлення (спочатку ClawHub, потім npm)
|
||||
openclaw plugins install clawhub:<pkg> # установлення лише з ClawHub
|
||||
openclaw plugins install <package> # встановити (спочатку ClawHub, потім npm)
|
||||
openclaw plugins install clawhub:<pkg> # встановити лише з ClawHub
|
||||
openclaw plugins install <spec> --force # перезаписати наявне встановлення
|
||||
openclaw plugins install <path> # установлення з локального шляху
|
||||
openclaw plugins install -l <path> # link (без копіювання) для dev
|
||||
openclaw plugins install <path> # встановити з локального шляху
|
||||
openclaw plugins install -l <path> # підключити (без копіювання) для розробки
|
||||
openclaw plugins install <plugin> --marketplace <source>
|
||||
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
|
||||
openclaw plugins install <spec> --pin # записати точний resolved npm spec
|
||||
openclaw plugins install <spec> --pin # зберегти точну розв’язану npm-специфікацію
|
||||
openclaw plugins install <spec> --dangerously-force-unsafe-install
|
||||
openclaw plugins update <id-or-npm-spec> # оновити один plugin
|
||||
openclaw plugins update <id-or-npm-spec> # оновити один плагін
|
||||
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
|
||||
openclaw plugins update --all # оновити всі
|
||||
openclaw plugins uninstall <id> # прибрати записи config/install
|
||||
openclaw plugins uninstall <id> # видалити записи конфігурації/встановлення
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
@ -250,54 +259,59 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
Bundled plugins постачаються з OpenClaw. Багато з них увімкнені типово (наприклад
|
||||
bundled model providers, bundled speech providers і bundled browser
|
||||
plugin). Інші bundled plugins однаково потребують `openclaw plugins enable <id>`.
|
||||
Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад,
|
||||
вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser-плагін).
|
||||
Інші вбудовані плагіни все одно потребують `openclaw plugins enable <id>`.
|
||||
|
||||
`--force` перезаписує наявний встановлений plugin або hook pack на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm
|
||||
plugins. Він не підтримується разом із `--link`, який повторно використовує шлях до source
|
||||
замість копіювання до керованої цілі встановлення.
|
||||
`--force` перезаписує наявний встановлений плагін або пакет хуків на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm-плагінів.
|
||||
Він не підтримується з `--link`, який повторно використовує шлях до джерела замість
|
||||
копіювання в кероване місце встановлення.
|
||||
|
||||
Коли `plugins.allow` уже задано, `openclaw plugins install` додає
|
||||
id встановленого plugin до цього allowlist перед його ввімкненням, тож після перезапуску встановлення
|
||||
одразу можна буде завантажити.
|
||||
ідентифікатор встановленого плагіна до цього списку allow перед його ввімкненням, щоб установлені
|
||||
плагіни можна було одразу завантажити після перезапуску.
|
||||
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних встановлень. Передавання
|
||||
npm package spec з dist-tag або точною версією розв’язує ім’я пакета
|
||||
назад до запису відстежуваного plugin і записує новий spec для майбутніх оновлень.
|
||||
Передавання імені пакета без версії переводить exact pinned install назад на
|
||||
типову release line registry. Якщо встановлений npm plugin уже відповідає
|
||||
розв’язаній версії й записаній artifact identity, OpenClaw пропускає оновлення
|
||||
без завантаження, перевстановлення або переписування config.
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних установлень. Передача
|
||||
специфікації 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 <id>` також повідомляє про виявлені можливості bundle плюс
|
||||
підтримувані або непідтримувані записи MCP і LSP server для plugin-ів на основі bundle.
|
||||
`openclaw plugins inspect <id>` також повідомляє про виявлені можливості пакета, а також
|
||||
підтримувані чи непідтримувані записи серверів 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) — сторонні каталоги
|
||||
|
||||
Loading…
Reference in New Issue
Block a user