chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
c8ed9a1fc5
commit
499eb0b1d4
@ -1,68 +1,69 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви обираєте між PI, Codex, ACP або іншим нативним середовищем виконання агента
|
||||
- Ви заплуталися в мітках провайдера/моделі/середовища виконання в status або config
|
||||
- Ви документуєте паритет підтримки для нативного harness
|
||||
summary: Як OpenClaw розділяє провайдерів моделей, моделі, канали та середовища виконання агентів
|
||||
- Ви обираєте між Pi, Codex, ACP або іншим нативним середовищем виконання агента
|
||||
- Вас плутають позначки постачальника/моделі/середовища виконання у статусі або конфігурації
|
||||
- Ви документуєте паритет підтримки для нативної обв'язки
|
||||
summary: Як OpenClaw розділяє постачальників моделей, моделі, канали та середовища виконання агентів
|
||||
title: Середовища виконання агентів
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T07:47:36Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-02T02:37:16Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f99e88a47a78c48b2f2408a3feedf15cde66a6bacc4e7bfadb9e47c74f7ce633
|
||||
source_hash: bae2dd55491e5411983da942b2bdc4868d3b2cb5a4eb5d94fbb5a779dc4d679a
|
||||
source_path: concepts/agent-runtimes.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
**Середовище виконання агента** — це компонент, який керує одним підготовленим циклом моделі: він
|
||||
отримує запит, керує виводом моделі, обробляє нативні виклики інструментів і повертає
|
||||
**Середовище виконання агента** — це компонент, який володіє одним підготовленим циклом моделі: він
|
||||
отримує промпт, керує виведенням моделі, обробляє нативні виклики інструментів і повертає
|
||||
завершений хід до OpenClaw.
|
||||
|
||||
Середовища виконання легко сплутати з провайдерами, оскільки обидва з’являються поруч із
|
||||
Середовища виконання легко сплутати з провайдерами, бо обидва з'являються поруч із
|
||||
конфігурацією моделі. Це різні рівні:
|
||||
|
||||
| Рівень | Приклади | Що це означає |
|
||||
| ------------- | ------------------------------------- | ------------------------------------------------------------------ |
|
||||
| Провайдер | `openai`, `anthropic`, `openai-codex` | Як OpenClaw автентифікується, знаходить моделі та називає посилання на моделі. |
|
||||
| Модель | `gpt-5.5`, `claude-opus-4-6` | Модель, вибрана для ходу агента. |
|
||||
| Середовище виконання агента | `pi`, `codex`, `claude-cli` | Низькорівневий цикл або бекенд, який виконує підготовлений хід. |
|
||||
| Канал | Telegram, Discord, Slack, WhatsApp | Звідки повідомлення надходять до OpenClaw і куди виходять. |
|
||||
| Рівень | Приклади | Що це означає |
|
||||
| ------------- | ------------------------------------- | ------------------------------------------------------------------- |
|
||||
| Провайдер | `openai`, `anthropic`, `openai-codex` | Як OpenClaw автентифікується, виявляє моделі та іменує посилання на моделі. |
|
||||
| Модель | `gpt-5.5`, `claude-opus-4-6` | Модель, вибрана для ходу агента. |
|
||||
| Середовище виконання агента | `pi`, `codex`, `claude-cli` | Низькорівневий цикл або бекенд, який виконує підготовлений хід. |
|
||||
| Канал | Telegram, Discord, Slack, WhatsApp | Де повідомлення входять в OpenClaw і виходять із нього. |
|
||||
|
||||
У коді ви також побачите слово **harness**. Harness — це реалізація,
|
||||
яка надає середовище виконання агента. Наприклад, вбудований Codex harness
|
||||
реалізує середовище виконання `codex`. У публічній конфігурації використовується `agentRuntime.id`; `openclaw
|
||||
doctor --fix` переписує старі ключі політики середовища виконання в цю форму.
|
||||
У коді ви також побачите слово **обв'язка**. Обв'язка — це реалізація,
|
||||
яка надає середовище виконання агента. Наприклад, вбудована обв'язка Codex
|
||||
реалізує середовище виконання `codex`. Публічна конфігурація використовує `agentRuntime.id`; `openclaw
|
||||
doctor --fix` переписує старіші ключі політики середовища виконання до цієї форми.
|
||||
|
||||
Є дві родини середовищ виконання:
|
||||
Є два сімейства середовищ виконання:
|
||||
|
||||
- **Вбудовані harness-и** працюють усередині підготовленого циклу агента OpenClaw. Наразі це
|
||||
вбудоване середовище виконання `pi`, а також зареєстровані harness-и Plugin, такі як
|
||||
- **Вбудовані обв'язки** працюють усередині підготовленого агентського циклу OpenClaw. Сьогодні це
|
||||
вбудоване середовище виконання `pi` плюс зареєстровані обв'язки plugin, як-от
|
||||
`codex`.
|
||||
- **CLI-бекенди** запускають локальний процес CLI, зберігаючи при цьому
|
||||
канонічне посилання на модель. Наприклад, `anthropic/claude-opus-4-7` з
|
||||
`agentRuntime.id: "claude-cli"` означає «вибрати модель Anthropic, виконати
|
||||
через Claude CLI». `claude-cli` не є ідентифікатором вбудованого harness-а і не повинен
|
||||
передаватися для вибору AgentHarness.
|
||||
- **CLI-бекенди** запускають локальний процес CLI, зберігаючи канонічне посилання на модель.
|
||||
Наприклад, `anthropic/claude-opus-4-7` з
|
||||
`agentRuntime.id: "claude-cli"` означає "вибрати модель Anthropic, виконати
|
||||
через Claude CLI." `claude-cli` не є id вбудованої обв'язки, і його не можна
|
||||
передавати до вибору AgentHarness.
|
||||
|
||||
## Три речі з назвою Codex
|
||||
## Поверхні Codex
|
||||
|
||||
Найбільше непорозумінь виникає через три різні поверхні з однаковою назвою Codex:
|
||||
Найбільше плутанини виникає через кілька різних поверхонь, які мають назву Codex:
|
||||
|
||||
| Поверхня | Назва/конфігурація в OpenClaw | Що вона робить |
|
||||
| --------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| Маршрут OAuth-провайдера Codex | посилання на моделі `openai-codex/*` | Використовує OAuth підписки ChatGPT/Codex через звичайний виконавець PI в OpenClaw. |
|
||||
| Нативне середовище виконання Codex app-server | `agentRuntime.id: "codex"` | Запускає вбудований хід агента через комплектний harness Codex app-server. |
|
||||
| ACP-адаптер Codex | `runtime: "acp"`, `agentId: "codex"` | Запускає Codex через зовнішню площину керування ACP/acpx. Використовуйте лише коли явно запитано ACP/acpx. |
|
||||
| Нативний набір команд керування чатом Codex | `/codex ...` | Прив’язує, відновлює, спрямовує, зупиняє та перевіряє потоки Codex app-server із чату. |
|
||||
| Маршрут OpenAI Platform API для моделей у стилі GPT/Codex | посилання на моделі `openai/*` | Використовує автентифікацію OpenAI API key, якщо лише перевизначення середовища виконання, наприклад `runtime: "codex"`, не запускає хід. |
|
||||
| Поверхня | Назва/конфігурація OpenClaw | Що вона робить |
|
||||
| ---------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
|
||||
| Нативне середовище виконання app-server Codex | `openai/*` плюс `agentRuntime.id: "codex"` | Запускає вбудований агентський хід через app-server Codex. Це звичайне налаштування підписки ChatGPT/Codex. |
|
||||
| Маршрут провайдера Codex OAuth | Посилання на моделі `openai-codex/*` | Використовує OAuth підписки ChatGPT/Codex через звичайний раннер OpenClaw PI. |
|
||||
| Адаптер Codex ACP | `runtime: "acp"`, `agentId: "codex"` | Запускає Codex через зовнішню площину керування ACP/acpx. Використовуйте лише тоді, коли ACP/acpx явно запитано. |
|
||||
| Нативний набір команд керування чатом Codex | `/codex ...` | Прив'язує, відновлює, спрямовує, зупиняє та інспектує потоки app-server Codex із чату. |
|
||||
| Маршрут OpenAI Platform API для моделей у стилі GPT/Codex | Посилання на моделі `openai/*` | Використовує автентифікацію OpenAI API-ключем, якщо перевизначення середовища виконання, як-от `agentRuntime.id: "codex"`, не запускає хід. |
|
||||
|
||||
Ці поверхні навмисно незалежні. Увімкнення Plugin `codex` робить
|
||||
доступними нативні можливості app-server; воно не переписує
|
||||
`openai-codex/*` у `openai/*`, не змінює наявні сесії й не робить
|
||||
ACP типовим варіантом для Codex. Вибір `openai-codex/*` означає «використовувати маршрут
|
||||
OAuth-провайдера Codex», якщо ви окремо не примусите інше середовище виконання.
|
||||
Ці поверхні навмисно незалежні. Увімкнення plugin `codex` робить
|
||||
нативні можливості app-server доступними; воно не переписує
|
||||
`openai-codex/*` на `openai/*`, не змінює наявні сесії та не
|
||||
робить ACP типовим варіантом Codex. Вибір `openai-codex/*` означає "використовувати маршрут
|
||||
провайдера Codex OAuth", якщо окремо не примусити середовище виконання.
|
||||
|
||||
Типове налаштування Codex використовує провайдера `openai` із середовищем виконання `codex`:
|
||||
Поширене налаштування підписки ChatGPT/Codex використовує Codex OAuth для автентифікації, але зберігає
|
||||
посилання на модель як `openai/*` і вибирає середовище виконання `codex`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -77,85 +78,87 @@ OAuth-провайдера Codex», якщо ви окремо не примус
|
||||
}
|
||||
```
|
||||
|
||||
Це означає, що OpenClaw вибирає посилання на модель OpenAI, а потім просить середовище виконання
|
||||
Codex app-server запустити вбудований хід агента. Це не означає, що канал,
|
||||
каталог провайдерів моделей або сховище сесій OpenClaw стає Codex.
|
||||
Це означає, що OpenClaw вибирає посилання на модель OpenAI, а потім просить середовище виконання app-server
|
||||
Codex запустити вбудований агентський хід. Це не означає "використовувати API-білінг",
|
||||
і не означає, що канал, каталог провайдера моделей або сховище сесій OpenClaw
|
||||
стає Codex.
|
||||
|
||||
Коли комплектний Plugin `codex` увімкнено, для природномовного керування Codex
|
||||
слід використовувати нативну поверхню команд `/codex` (`/codex bind`, `/codex threads`,
|
||||
Коли вбудований plugin `codex` увімкнено, керування Codex природною мовою
|
||||
має використовувати нативну командну поверхню `/codex` (`/codex bind`, `/codex threads`,
|
||||
`/codex resume`, `/codex steer`, `/codex stop`) замість ACP. Використовуйте ACP для
|
||||
Codex лише коли користувач явно просить ACP/acpx або тестує шлях ACP-адаптера.
|
||||
Claude Code, Gemini CLI, OpenCode, Cursor та подібні зовнішні
|
||||
harness-и й далі використовують ACP.
|
||||
Codex лише тоді, коли користувач явно просить ACP/acpx або тестує шлях адаптера ACP.
|
||||
Claude Code, Gemini CLI, OpenCode, Cursor та подібні зовнішні обв'язки
|
||||
далі використовують ACP.
|
||||
|
||||
Ось дерево рішень для агента:
|
||||
Це дерево рішень для агента:
|
||||
|
||||
1. Якщо користувач просить **Codex bind/control/thread/resume/steer/stop**, використовуйте
|
||||
нативну поверхню команд `/codex`, коли комплектний Plugin `codex` увімкнено.
|
||||
2. Якщо користувач просить **Codex як вбудоване середовище виконання**, використовуйте
|
||||
1. Якщо користувач просить **прив'язати/керувати/потік/відновити/спрямувати/зупинити Codex**, використовуйте
|
||||
нативну командну поверхню `/codex`, коли вбудований plugin `codex` увімкнено.
|
||||
2. Якщо користувач просить **Codex як вбудоване середовище виконання** або хоче звичайний
|
||||
агентський досвід Codex із підтримкою підписки, використовуйте
|
||||
`openai/<model>` з `agentRuntime.id: "codex"`.
|
||||
3. Якщо користувач просить **Codex OAuth/автентифікацію за підпискою у звичайному виконавці OpenClaw**,
|
||||
використовуйте `openai-codex/<model>` і залишайте середовище виконання як PI.
|
||||
4. Якщо користувач явно каже **ACP**, **acpx** або **ACP-адаптер Codex**, використовуйте
|
||||
3. Якщо користувач просить **Codex OAuth/автентифікацію підписки на звичайному раннері OpenClaw**,
|
||||
використовуйте `openai-codex/<model>` і залиште середовище виконання як PI.
|
||||
4. Якщо користувач явно каже **ACP**, **acpx** або **адаптер Codex ACP**, використовуйте
|
||||
ACP з `runtime: "acp"` і `agentId: "codex"`.
|
||||
5. Якщо запит стосується **Claude Code, Gemini CLI, OpenCode, Cursor, Droid або
|
||||
іншого зовнішнього harness-а**, використовуйте ACP/acpx, а не нативне середовище виконання субагента.
|
||||
іншої зовнішньої обв'язки**, використовуйте ACP/acpx, а не нативне середовище виконання під-агента.
|
||||
|
||||
| Ви маєте на увазі... | Використовуйте... |
|
||||
| -------------------------------------- | ---------------------------------------------- |
|
||||
| Керування чатом/потоками Codex app-server | `/codex ...` із комплектного Plugin `codex` |
|
||||
| Вбудоване середовище виконання агента Codex app-server | `agentRuntime.id: "codex"` |
|
||||
| OpenAI Codex OAuth у виконавці PI | посилання на моделі `openai-codex/*` |
|
||||
| Claude Code або інший зовнішній harness | ACP/acpx |
|
||||
| Ви маєте на увазі... | Використовуйте... |
|
||||
| --------------------------------------- | -------------------------------------------- |
|
||||
| Керування чатом/потоками app-server Codex | `/codex ...` з вбудованого plugin `codex` |
|
||||
| Вбудоване середовище виконання агента app-server Codex | `agentRuntime.id: "codex"` |
|
||||
| OpenAI Codex OAuth на раннері PI | Посилання на моделі `openai-codex/*` |
|
||||
| Claude Code або інша зовнішня обв'язка | ACP/acpx |
|
||||
|
||||
Щодо поділу префіксів родини OpenAI див. [OpenAI](/uk/providers/openai) і
|
||||
[Провайдери моделей](/uk/concepts/model-providers). Щодо контракту підтримки середовища виконання Codex
|
||||
див. [Codex harness](/uk/plugins/codex-harness#v1-support-contract).
|
||||
Про розділення префіксів сімейства OpenAI див. [OpenAI](/uk/providers/openai) і
|
||||
[Провайдери моделей](/uk/concepts/model-providers). Про контракт підтримки середовища виконання Codex
|
||||
див. [Обв'язка Codex](/uk/plugins/codex-harness#v1-support-contract).
|
||||
|
||||
## Володіння середовищем виконання
|
||||
## Відповідальність середовища виконання
|
||||
|
||||
Різні середовища виконання керують різними частинами циклу.
|
||||
Різні середовища виконання володіють різними частинами циклу.
|
||||
|
||||
| Поверхня | Вбудований PI OpenClaw | Codex app-server |
|
||||
| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| Хто керує циклом моделі | OpenClaw через вбудований виконавець PI | Codex app-server |
|
||||
| Канонічний стан потоку | транскрипт OpenClaw | потік Codex плюс дзеркало транскрипту OpenClaw |
|
||||
| Динамічні інструменти OpenClaw | нативний цикл інструментів OpenClaw | Мостом через адаптер Codex |
|
||||
| Нативні shell- та файлові інструменти | шлях PI/OpenClaw | Нативні інструменти Codex, передані через нативні hooks, де це підтримується |
|
||||
| Рушій контексту | нативне збирання контексту OpenClaw | контекст проєктів OpenClaw, зібраний у хід Codex |
|
||||
| Compaction | OpenClaw або вибраний рушій контексту | нативний Compaction Codex із сповіщеннями OpenClaw і підтримкою дзеркала |
|
||||
| Доставка через канал | OpenClaw | OpenClaw |
|
||||
| Поверхня | Вбудований PI OpenClaw | app-server Codex |
|
||||
| --------------------------- | --------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| Власник циклу моделі | OpenClaw через вбудований раннер PI | app-server Codex |
|
||||
| Канонічний стан потоку | Транскрипт OpenClaw | Потік Codex, плюс дзеркало транскрипту OpenClaw |
|
||||
| Динамічні інструменти OpenClaw | Нативний цикл інструментів OpenClaw | Передаються через адаптер Codex |
|
||||
| Нативні інструменти оболонки та файлів | Шлях PI/OpenClaw | Нативні інструменти Codex, передані через нативні хуки там, де підтримується |
|
||||
| Контекстний рушій | Нативне складання контексту OpenClaw | OpenClaw проєктує зібраний контекст у хід Codex |
|
||||
| Compaction | OpenClaw або вибраний контекстний рушій | Нативна Compaction Codex, зі сповіщеннями OpenClaw і підтримкою дзеркала |
|
||||
| Доставка каналом | OpenClaw | OpenClaw |
|
||||
|
||||
Цей поділ володіння є головним правилом проєктування:
|
||||
Цей розподіл відповідальності є головним правилом проєктування:
|
||||
|
||||
- Якщо поверхнею керує OpenClaw, OpenClaw може надавати звичайну поведінку hooks Plugin.
|
||||
- Якщо поверхнею керує нативне середовище виконання, OpenClaw потребує подій середовища виконання або нативних hooks.
|
||||
- Якщо нативне середовище виконання керує канонічним станом потоку, OpenClaw має дзеркалити й проєктувати контекст, а не переписувати непідтримувані внутрішні механізми.
|
||||
- Якщо OpenClaw володіє поверхнею, OpenClaw може надати звичайну поведінку хуків plugin.
|
||||
- Якщо нативне середовище виконання володіє поверхнею, OpenClaw потребує подій середовища виконання або нативних хуків.
|
||||
- Якщо нативне середовище виконання володіє канонічним станом потоку, OpenClaw має дзеркалити і проєктувати контекст, а не переписувати непідтримувані внутрішні механізми.
|
||||
|
||||
## Вибір середовища виконання
|
||||
|
||||
OpenClaw вибирає вбудоване середовище виконання після визначення провайдера та моделі:
|
||||
|
||||
1. Пріоритет має записане для сесії середовище виконання. Зміни конфігурації не перемикають
|
||||
існуючий транскрипт «на гарячу» на іншу нативну систему потоків.
|
||||
1. Записане середовище виконання сесії має пріоритет. Зміни конфігурації не перемикають на льоту
|
||||
наявний транскрипт на іншу нативну систему потоків.
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` примусово встановлює це середовище виконання для нових або скинутих сесій.
|
||||
3. `agents.defaults.agentRuntime.id` або `agents.list[].agentRuntime.id` можуть встановлювати
|
||||
`auto`, `pi`, ідентифікатор зареєстрованого вбудованого harness-а, наприклад `codex`, або
|
||||
підтримуваний псевдонім CLI-бекенда, наприклад `claude-cli`.
|
||||
4. У режимі `auto` зареєстровані середовища виконання Plugin можуть заявляти підтримувані
|
||||
пари провайдер/модель.
|
||||
5. Якщо жодне середовище виконання не бере хід у режимі `auto`, а встановлено
|
||||
`fallback: "pi"` (типове значення), OpenClaw використовує PI як сумісний резервний варіант. Установіть
|
||||
`fallback: "none"`, щоб вибір у режимі `auto` завершувався помилкою, якщо немає відповідності.
|
||||
3. `agents.defaults.agentRuntime.id` або `agents.list[].agentRuntime.id` може встановити
|
||||
`auto`, `pi`, зареєстрований id вбудованої обв'язки, як-от `codex`, або
|
||||
підтримуваний псевдонім CLI-бекенду, як-от `claude-cli`.
|
||||
4. У режимі `auto` зареєстровані середовища виконання plugin можуть заявляти підтримувані пари
|
||||
провайдер/модель.
|
||||
5. Якщо жодне середовище виконання не заявляє хід у режимі `auto` і встановлено `fallback: "pi"`
|
||||
(типово), OpenClaw використовує PI як резерв сумісності. Установіть
|
||||
`fallback: "none"`, щоб натомість зробити невідповідний вибір у режимі `auto` помилкою.
|
||||
|
||||
Явно задані середовища виконання Plugin типово працюють у закритому режимі. Наприклад,
|
||||
`runtime: "codex"` означає Codex або чітку помилку вибору, якщо лише ви не встановите
|
||||
Явні середовища виконання plugin типово завершуються закритою помилкою. Наприклад,
|
||||
`agentRuntime.id: "codex"` означає Codex або зрозумілу помилку вибору, якщо ви не встановите
|
||||
`fallback: "pi"` у тій самій області перевизначення. Перевизначення середовища виконання не успадковує
|
||||
ширше налаштування fallback, тому `runtime: "codex"` на рівні агента не буде мовчки
|
||||
спрямовано назад до PI лише тому, що в значеннях за замовчуванням було `fallback: "pi"`.
|
||||
ширше резервне налаштування, тому `agentRuntime.id: "codex"` на рівні агента не буде
|
||||
непомітно перенаправлено назад до PI лише тому, що типові значення використовували `fallback: "pi"`.
|
||||
|
||||
Псевдоніми CLI-бекендів відрізняються від ідентифікаторів вбудованих harness-ів. Бажана
|
||||
форма для Claude CLI така:
|
||||
Псевдоніми CLI-бекендів відрізняються від id вбудованих обв'язок. Бажана
|
||||
форма Claude CLI така:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -168,60 +171,60 @@ OpenClaw вибирає вбудоване середовище виконанн
|
||||
}
|
||||
```
|
||||
|
||||
Застарілі посилання на кшталт `claude-cli/claude-opus-4-7` і далі підтримуються для
|
||||
сумісності, але в новій конфігурації слід зберігати канонічну форму провайдера/моделі, а
|
||||
бекенд виконання вказувати в `agentRuntime.id`.
|
||||
Застарілі посилання, як-от `claude-cli/claude-opus-4-7`, залишаються підтримуваними для
|
||||
сумісності, але нова конфігурація має зберігати провайдера/модель канонічними і розміщувати
|
||||
бекенд виконання в `agentRuntime.id`.
|
||||
|
||||
Режим `auto` навмисно консервативний. Середовища виконання Plugin можуть заявляти
|
||||
пари провайдер/модель, які вони розуміють, але Plugin Codex не заявляє
|
||||
Режим `auto` навмисно консервативний. Середовища виконання plugin можуть заявляти
|
||||
пари провайдер/модель, які вони розуміють, але plugin Codex не заявляє
|
||||
провайдера `openai-codex` у режимі `auto`. Це зберігає
|
||||
`openai-codex/*` як явний маршрут PI Codex OAuth і не дає мовчки
|
||||
перемістити конфігурації з автентифікацією за підпискою на нативний harness app-server.
|
||||
`openai-codex/*` як явний маршрут PI Codex OAuth і не дає непомітно
|
||||
перемістити конфігурації автентифікації підписки на нативну обв'язку app-server.
|
||||
|
||||
Якщо `openclaw doctor` попереджає, що Plugin `codex` увімкнено, але
|
||||
`openai-codex/*` усе ще маршрутизується через PI, сприймайте це як діагностику, а не
|
||||
міграцію. Залишайте конфігурацію без змін, якщо вам потрібен саме PI Codex OAuth.
|
||||
Переходьте на `openai/<model>` плюс `agentRuntime.id: "codex"` лише коли вам потрібне нативне
|
||||
виконання через Codex app-server.
|
||||
Якщо `openclaw doctor` попереджає, що plugin `codex` увімкнено, тоді як
|
||||
`openai-codex/*` усе ще маршрутизується через PI, сприймайте це як діагностику, а не як
|
||||
міграцію. Залиште конфігурацію без змін, коли PI Codex OAuth — це те, що вам потрібно.
|
||||
Перемикайтеся на `openai/<model>` плюс `agentRuntime.id: "codex"` лише тоді, коли вам потрібне нативне
|
||||
виконання app-server Codex.
|
||||
|
||||
## Контракт сумісності
|
||||
|
||||
Коли середовище виконання — не PI, воно має документувати, які поверхні OpenClaw воно підтримує.
|
||||
Для документації середовищ виконання використовуйте таку форму:
|
||||
Коли середовище виконання не є PI, воно має документувати, які поверхні OpenClaw підтримує.
|
||||
Використовуйте цю форму для документації середовищ виконання:
|
||||
|
||||
| Питання | Чому це важливо |
|
||||
| ------------------------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| Хто керує циклом моделі? | Визначає, де відбуваються повторні спроби, продовження інструментів і рішення щодо фінальної відповіді. |
|
||||
| Хто керує канонічною історією потоку? | Визначає, чи може OpenClaw редагувати історію, чи лише дзеркалити її. |
|
||||
| Чи працюють динамічні інструменти OpenClaw? | На це спираються повідомлення, сесії, Cron та інструменти, що належать OpenClaw. |
|
||||
| Чи працюють hooks динамічних інструментів? | Plugins очікують `before_tool_call`, `after_tool_call` і middleware навколо інструментів, що належать OpenClaw. |
|
||||
| Чи працюють hooks нативних інструментів? | Інструментам shell, patch та інструментам, що належать середовищу виконання, потрібна підтримка нативних hooks для політик і спостереження. |
|
||||
| Чи виконується життєвий цикл рушія контексту? | Plugins пам’яті та контексту залежать від життєвого циклу assemble, ingest, after-turn і Compaction. |
|
||||
| Які дані Compaction відкриті? | Деяким Plugins потрібні лише сповіщення, а іншим — метадані про збережене/відкинуте. |
|
||||
| Що навмисно не підтримується? | Користувачі не повинні припускати еквівалентність із PI там, де нативне середовище виконання керує більшою частиною стану. |
|
||||
| Запитання | Чому це важливо |
|
||||
| -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| Хто керує циклом моделі? | Визначає, де відбуваються повторні спроби, продовження інструментів і рішення щодо фінальної відповіді. |
|
||||
| Хто керує канонічною історією потоку? | Визначає, чи OpenClaw може редагувати історію, чи лише віддзеркалювати її. |
|
||||
| Чи працюють динамічні інструменти OpenClaw? | Обмін повідомленнями, сеанси, cron і інструменти, що належать OpenClaw, залежать від цього. |
|
||||
| Чи працюють хуки динамічних інструментів? | Plugins очікують `before_tool_call`, `after_tool_call` і middleware навколо інструментів, що належать OpenClaw. |
|
||||
| Чи працюють хуки нативних інструментів? | Shell, patch та інструментам, що належать runtime, потрібна нативна підтримка хуків для політик і спостереження. |
|
||||
| Чи запускається життєвий цикл контекстного рушія? | Plugins пам’яті й контексту залежать від життєвого циклу assemble, ingest, after-turn і compaction. |
|
||||
| Які дані compaction відкриваються? | Деяким plugins потрібні лише сповіщення, тоді як іншим потрібні метадані збереженого/відкинутого. |
|
||||
| Що навмисно не підтримується? | Користувачі не повинні припускати еквівалентність PI там, де нативний runtime керує більшою кількістю стану. |
|
||||
|
||||
Контракт підтримки середовища виконання Codex задокументовано в
|
||||
Контракт підтримки runtime Codex задокументовано в
|
||||
[Codex harness](/uk/plugins/codex-harness#v1-support-contract).
|
||||
|
||||
## Мітки status
|
||||
## Мітки стану
|
||||
|
||||
У виводі status можуть показуватися мітки `Execution` і `Runtime`. Сприймайте їх як
|
||||
Вивід стану може показувати обидві мітки: `Execution` і `Runtime`. Сприймайте їх як
|
||||
діагностику, а не як назви провайдерів.
|
||||
|
||||
- Посилання на модель, наприклад `openai/gpt-5.5`, повідомляє про вибраного провайдера/модель.
|
||||
- Ідентифікатор середовища виконання, наприклад `codex`, повідомляє, який цикл виконує цей хід.
|
||||
- Мітка каналу, наприклад Telegram або Discord, повідомляє, де відбувається розмова.
|
||||
- Посилання на модель, як-от `openai/gpt-5.5`, показує вибраного провайдера/модель.
|
||||
- Ідентифікатор runtime, як-от `codex`, показує, який цикл виконує хід.
|
||||
- Мітка каналу, як-от Telegram або Discord, показує, де відбувається розмова.
|
||||
|
||||
Якщо після зміни конфігурації середовища виконання сесія все ще показує PI, почніть нову сесію
|
||||
через `/new` або очистьте поточну через `/reset`. Наявні сесії зберігають своє
|
||||
записане середовище виконання, щоб транскрипт не відтворювався через дві несумісні нативні
|
||||
системи сесій.
|
||||
Якщо сеанс усе ще показує PI після зміни конфігурації runtime, почніть новий сеанс
|
||||
за допомогою `/new` або очистьте поточний за допомогою `/reset`. Наявні сеанси зберігають свій
|
||||
записаний runtime, щоб transcript не відтворювався через дві несумісні нативні
|
||||
системи сеансів.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Codex harness](/uk/plugins/codex-harness)
|
||||
- [OpenAI](/uk/providers/openai)
|
||||
- [Plugins harness агента](/uk/plugins/sdk-agent-harness)
|
||||
- [Agent harness plugins](/uk/plugins/sdk-agent-harness)
|
||||
- [Цикл агента](/uk/concepts/agent-loop)
|
||||
- [Моделі](/uk/concepts/models)
|
||||
- [Status](/uk/cli/status)
|
||||
- [Стан](/uk/cli/status)
|
||||
|
||||
@ -1,68 +1,68 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен довідник із налаштування моделей для кожного провайдера
|
||||
- Вам потрібен довідник з налаштування моделей для кожного постачальника
|
||||
- Вам потрібні приклади конфігурацій або команди CLI для початкового налаштування постачальників моделей
|
||||
sidebarTitle: Model providers
|
||||
summary: Огляд постачальників моделей із прикладами конфігурацій + робочими процесами CLI
|
||||
title: Постачальники моделей
|
||||
summary: Огляд постачальників моделей із прикладами конфігурацій + сценаріями CLI
|
||||
title: Провайдери моделей
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T02:28:51Z"
|
||||
generated_at: "2026-05-02T02:37:10Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6b1523616a846b2bf0cad46f9f4a713fbb5e8bd7327108ab593eea8c841d5eef
|
||||
source_hash: 34e6a6b691b447a66a94f69a7b609f26c587eaa5bc55c5ed62460ce14cc288fd
|
||||
source_path: concepts/model-providers.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Довідка для **постачальників LLM/моделей** (не каналів чату на кшталт WhatsApp/Telegram). Правила вибору моделей див. у [Моделі](/uk/concepts/models).
|
||||
Довідка для **постачальників LLM/моделей** (не каналів чату, як-от WhatsApp/Telegram). Правила вибору моделей див. у [Моделі](/uk/concepts/models).
|
||||
|
||||
## Швидкі правила
|
||||
## Короткі правила
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Посилання на моделі та помічники CLI">
|
||||
<Accordion title="Посилання на моделі та CLI-помічники">
|
||||
- Посилання на моделі використовують `provider/model` (приклад: `opencode/claude-opus-4-6`).
|
||||
- `agents.defaults.models` діє як список дозволених моделей, якщо задано.
|
||||
- Помічники CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
|
||||
- `agents.defaults.models` діє як список дозволених, коли його задано.
|
||||
- CLI-помічники: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
|
||||
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` задають типові значення на рівні постачальника; `models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` перевизначають їх для окремої моделі.
|
||||
- Правила резервного перемикання, проби після періоду охолодження та збереження перевизначень сеансу: [Резервне перемикання моделей](/uk/concepts/model-failover).
|
||||
- Правила резервного перемикання, проби після cooldown і збереження перевизначень сеансу: [Резервне перемикання моделей](/uk/concepts/model-failover).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Додавання автентифікації постачальника не змінює вашу основну модель">
|
||||
`openclaw configure` зберігає наявне значення `agents.defaults.model.primary`, коли ви додаєте або повторно автентифікуєте постачальника. Plugin постачальника все ще може повернути рекомендовану типову модель у своєму патчі конфігурації автентифікації, але configure трактує це як "зробити цю модель доступною", якщо основна модель уже існує, а не як "замінити поточну основну модель".
|
||||
`openclaw configure` зберігає наявний `agents.defaults.model.primary`, коли ви додаєте або повторно автентифікуєте постачальника. Plugin-и постачальників усе ще можуть повертати рекомендовану типову модель у своєму патчі конфігурації автентифікації, але configure трактує це як "зробити цю модель доступною", якщо основна модель уже існує, а не як "замінити поточну основну модель."
|
||||
|
||||
Щоб навмисно перемкнути типову модель, скористайтеся `openclaw models set <provider/model>` або `openclaw models auth login --provider <id> --set-default`.
|
||||
Щоб навмисно змінити типову модель, використайте `openclaw models set <provider/model>` або `openclaw models auth login --provider <id> --set-default`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Розділення постачальника OpenAI та середовища виконання">
|
||||
Маршрути сімейства OpenAI залежать від префікса:
|
||||
<Accordion title="Розділення постачальника/середовища виконання OpenAI">
|
||||
Маршрути родини OpenAI залежать від префікса:
|
||||
|
||||
- `openai/<model>` використовує прямого постачальника OpenAI з API-ключем у PI.
|
||||
- `openai/<model>` разом із `agents.defaults.agentRuntime.id: "codex"` використовує нативний harness сервера застосунку Codex. Це звичайне налаштування для підписки ChatGPT/Codex.
|
||||
- `openai-codex/<model>` використовує Codex OAuth у PI.
|
||||
- `openai/<model>` разом із `agents.defaults.agentRuntime.id: "codex"` використовує нативну обгортку сервера застосунку Codex.
|
||||
- `openai/<model>` без перевизначення середовища виконання Codex використовує прямого постачальника OpenAI з API-ключем у PI.
|
||||
|
||||
Див. [OpenAI](/uk/providers/openai) і [обгортку Codex](/uk/plugins/codex-harness). Якщо розділення постачальника та середовища виконання незрозуміле, спочатку прочитайте [Середовища виконання агентів](/uk/concepts/agent-runtimes).
|
||||
Див. [OpenAI](/uk/providers/openai) і [harness Codex](/uk/plugins/codex-harness). Якщо розділення постачальника/середовища виконання незрозуміле, спершу прочитайте [Середовища виконання агентів](/uk/concepts/agent-runtimes).
|
||||
|
||||
Автоматичне ввімкнення Plugin дотримується тієї самої межі: `openai-codex/<model>` належить до OpenAI plugin, тоді як Codex plugin вмикається через `agentRuntime.id: "codex"` або застарілі посилання `codex/<model>`.
|
||||
Автоматичне вмикання Plugin дотримується тієї самої межі: `openai-codex/<model>` належить до Plugin OpenAI, тоді як Plugin Codex вмикається через `agentRuntime.id: "codex"` або застарілі посилання `codex/<model>`.
|
||||
|
||||
GPT-5.5 доступна через `openai/gpt-5.5` для прямого трафіку з API-ключем, `openai-codex/gpt-5.5` у PI для Codex OAuth і нативну обгортку сервера застосунку Codex, коли задано `agentRuntime.id: "codex"`.
|
||||
GPT-5.5 доступна через нативний harness сервера застосунку Codex, коли задано `agentRuntime.id: "codex"`, через `openai-codex/gpt-5.5` у PI для Codex OAuth і через `openai/gpt-5.5` у PI для прямого трафіку з API-ключем, коли ваш обліковий запис це надає.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Середовища виконання CLI">
|
||||
Середовища виконання CLI використовують те саме розділення: виберіть канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задайте `agents.defaults.agentRuntime.id` як `claude-cli`, `google-gemini-cli` або `codex-cli`, коли потрібен локальний бекенд CLI.
|
||||
<Accordion title="CLI-середовища виконання">
|
||||
CLI-середовища виконання використовують те саме розділення: виберіть канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задайте `agents.defaults.agentRuntime.id` як `claude-cli`, `google-gemini-cli` або `codex-cli`, коли потрібен локальний CLI-бекенд.
|
||||
|
||||
Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальника, а середовище виконання записується окремо.
|
||||
Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальників, а середовище виконання записується окремо.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Поведінка постачальника, якою володіє Plugin
|
||||
## Поведінка постачальника, керована Plugin
|
||||
|
||||
Більшість логіки, специфічної для постачальників, міститься у plugins постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл inference. Plugins володіють onboarding, каталогами моделей, зіставленням env var автентифікації, нормалізацією транспорту/конфігурації, очищенням схем інструментів, класифікацією резервного перемикання, оновленням OAuth, звітуванням про використання, профілями thinking/reasoning тощо.
|
||||
Більшість специфічної для постачальника логіки живе в Plugin-ах постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає універсальний цикл інференсу. Plugin-и відповідають за onboarding, каталоги моделей, зіставлення env-var для автентифікації, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію резервного перемикання, оновлення OAuth, звітування про використання, профілі thinking/reasoning тощо.
|
||||
|
||||
Повний список хуків provider-SDK і прикладів bundled-plugin міститься в [Plugins постачальників](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю власний виконавець запитів, є окремою, глибшою поверхнею розширення.
|
||||
Повний список хуків provider-SDK і прикладів вбудованих Plugin-ів міститься в [Plugin-и постачальників](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю власний виконавець запитів, є окремою, глибшою поверхнею розширення.
|
||||
|
||||
<Note>
|
||||
Поведінка runner, якою володіє постачальник, розміщена на явних хуках постачальника, як-от політика відтворення, нормалізація схем інструментів, обгортання stream і помічники транспорту/запитів. Застарілий статичний набір `ProviderPlugin.capabilities` призначений лише для сумісності й більше не читається спільною логікою runner.
|
||||
Поведінка runner, що належить постачальнику, живе в явних хуках постачальника, як-от політика replay, нормалізація схем інструментів, обгортання потоку та помічники транспорту/запитів. Застарілий статичний набір `ProviderPlugin.capabilities` існує лише для сумісності й більше не читається спільною логікою runner.
|
||||
</Note>
|
||||
|
||||
## Ротація API-ключів
|
||||
@ -71,43 +71,43 @@ x-i18n:
|
||||
<Accordion title="Джерела ключів і пріоритет">
|
||||
Налаштуйте кілька ключів через:
|
||||
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (одне live-перевизначення, найвищий пріоритет)
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (єдине live-перевизначення, найвищий пріоритет)
|
||||
- `<PROVIDER>_API_KEYS` (список через кому або крапку з комою)
|
||||
- `<PROVIDER>_API_KEY` (основний ключ)
|
||||
- `<PROVIDER>_API_KEY_*` (нумерований список, наприклад `<PROVIDER>_API_KEY_1`)
|
||||
|
||||
Для постачальників Google `GOOGLE_API_KEY` також включено як резервний варіант. Порядок вибору ключів зберігає пріоритет і видаляє дублікати значень.
|
||||
Для постачальників Google `GOOGLE_API_KEY` також включено як fallback. Порядок вибору ключів зберігає пріоритет і усуває дублікати значень.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Коли вмикається ротація">
|
||||
- Запити повторюються з наступним ключем лише для відповідей про rate limit (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання).
|
||||
- Помилки, не пов'язані з rate limit, одразу завершуються невдачею; ротація ключів не виконується.
|
||||
- Коли всі ключі-кандидати не спрацьовують, фінальна помилка повертається з останньої спроби.
|
||||
- Запити повторюються з наступним ключем лише для відповідей про обмеження швидкості (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання).
|
||||
- Помилки, не пов'язані з обмеженням швидкості, завершуються одразу; ротація ключів не виконується.
|
||||
- Коли всі ключі-кандидати зазнають невдачі, повертається фінальна помилка з останньої спроби.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Вбудовані постачальники (каталог pi-ai)
|
||||
|
||||
OpenClaw постачається з каталогом pi-ai. Ці постачальники **не** потребують конфігурації `models.providers`; просто задайте автентифікацію та виберіть модель.
|
||||
OpenClaw постачається з каталогом pi‑ai. Ці постачальники **не** потребують конфігурації `models.providers`; просто задайте автентифікацію й виберіть модель.
|
||||
|
||||
### OpenAI
|
||||
|
||||
- Постачальник: `openai`
|
||||
- Автентифікація: `OPENAI_API_KEY`
|
||||
- Необов'язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, плюс `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення)
|
||||
- Необов'язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, плюс `OPENCLAW_LIVE_OPENAI_KEY` (єдине перевизначення)
|
||||
- Приклади моделей: `openai/gpt-5.5`, `openai/gpt-5.4-mini`
|
||||
- Перевірте доступність облікового запису/моделі за допомогою `openclaw models list --provider openai`, якщо конкретне встановлення або API-ключ поводиться інакше.
|
||||
- CLI: `openclaw onboard --auth-choice openai-api-key`
|
||||
- Типовий транспорт: `auto` (спочатку WebSocket, резервно SSE)
|
||||
- Типовий транспорт — `auto` (спочатку WebSocket, fallback на SSE)
|
||||
- Перевизначайте для окремої моделі через `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Прогрів OpenAI Responses WebSocket типово ввімкнено через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Розігрів 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-сумісних проксі
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) застосовуються лише до нативного трафіку OpenAI до `api.openai.com`, а не до універсальних OpenAI-сумісних проксі
|
||||
- Нативні маршрути OpenAI також зберігають Responses `store`, підказки prompt-cache і формування payload для сумісності з reasoning OpenAI; проксі-маршрути цього не роблять
|
||||
- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити OpenAI API відхиляють його, а поточний каталог Codex його не експонує
|
||||
- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити OpenAI API його відхиляють, а поточний каталог Codex його не надає
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -119,17 +119,17 @@ OpenClaw постачається з каталогом pi-ai. Ці постач
|
||||
|
||||
- Постачальник: `anthropic`
|
||||
- Автентифікація: `ANTHROPIC_API_KEY`
|
||||
- Необов'язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, плюс `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення)
|
||||
- Необов'язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, плюс `OPENCLAW_LIVE_ANTHROPIC_KEY` (єдине перевизначення)
|
||||
- Приклад моделі: `anthropic/claude-opus-4-6`
|
||||
- CLI: `openclaw onboard --auth-choice apiKey`
|
||||
- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком з API-ключем і OAuth-автентифікацією, надісланим до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`)
|
||||
- Бажана конфігурація Claude CLI зберігає посилання на модель канонічним і вибирає бекенд CLI
|
||||
окремо: `anthropic/claude-opus-4-7` з
|
||||
`agents.defaults.agentRuntime.id: "claude-cli"`. Застарілі посилання
|
||||
`claude-cli/claude-opus-4-7` усе ще працюють для сумісності.
|
||||
- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком з API-ключем і OAuth-автентифікацією, що надсилається до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`)
|
||||
- Бажана конфігурація Claude CLI зберігає посилання на модель канонічним і вибирає CLI
|
||||
бекенд окремо: `anthropic/claude-opus-4-7` з
|
||||
`agents.defaults.agentRuntime.id: "claude-cli"`. Застарілі
|
||||
посилання `claude-cli/claude-opus-4-7` усе ще працюють для сумісності.
|
||||
|
||||
<Note>
|
||||
Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, доки Anthropic не опублікує нову політику. Setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але OpenClaw тепер надає перевагу повторному використанню Claude CLI та `claude -p`, коли вони доступні.
|
||||
Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволено, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. Anthropic setup-token залишається доступним як підтримуваний шлях токена OpenClaw, але OpenClaw тепер надає перевагу повторному використанню Claude CLI і `claude -p`, коли вони доступні.
|
||||
</Note>
|
||||
|
||||
```json5
|
||||
@ -143,23 +143,30 @@ OpenClaw постачається з каталогом pi-ai. Ці постач
|
||||
- Постачальник: `openai-codex`
|
||||
- Автентифікація: OAuth (ChatGPT)
|
||||
- Посилання на модель PI: `openai-codex/gpt-5.5`
|
||||
- Посилання на нативну обгортку сервера застосунку Codex: `openai/gpt-5.5` з `agents.defaults.agentRuntime.id: "codex"`
|
||||
- Документація нативної обгортки сервера застосунку Codex: [Обгортка Codex](/uk/plugins/codex-harness)
|
||||
- Посилання на нативний harness сервера застосунку Codex: `openai/gpt-5.5` з `agents.defaults.agentRuntime.id: "codex"`
|
||||
- Документація нативного harness сервера застосунку Codex: [harness Codex](/uk/plugins/codex-harness)
|
||||
- Застарілі посилання на моделі: `codex/gpt-*`
|
||||
- Межа Plugin: `openai-codex/*` завантажує OpenAI plugin; нативний plugin сервера застосунку Codex вибирається лише середовищем виконання обгортки Codex або застарілими посиланнями `codex/*`.
|
||||
- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin сервера застосунку Codex вибирається лише середовищем виконання harness Codex або застарілими посиланнями `codex/*`.
|
||||
- CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex`
|
||||
- Типовий транспорт: `auto` (спочатку WebSocket, резервно SSE)
|
||||
- Перевизначайте для окремої PI-моделі через `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- `params.serviceTier` також передається в нативних запитах Codex Responses (`chatgpt.com/backend-api`)
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex до `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі
|
||||
- Має той самий спільний перемикач `/fast` і конфігурацію `params.fastMode`, що й прямі `openai/*`; OpenClaw зіставляє це з `service_tier=priority`
|
||||
- `openai-codex/gpt-5.5` використовує нативні для каталогу Codex `contextWindow = 400000` і типове runtime `contextTokens = 272000`; перевизначте обмеження runtime через `models.providers.openai-codex.models[].contextTokens`
|
||||
- Типовий транспорт — `auto` (спочатку WebSocket, fallback на SSE)
|
||||
- Перевизначайте для окремої моделі PI через `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- `params.serviceTier` також передається у нативних запитах Codex Responses (`chatgpt.com/backend-api`)
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex до `chatgpt.com/backend-api`, а не до універсальних OpenAI-сумісних проксі
|
||||
- Має ту саму конфігурацію спільного перемикача `/fast` і `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority`
|
||||
- `openai-codex/gpt-5.5` використовує нативний для каталогу Codex `contextWindow = 400000` і типове середовище виконання `contextTokens = 272000`; перевизначте ліміт середовища виконання через `models.providers.openai-codex.models[].contextTokens`
|
||||
- Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/робочих процесів на кшталт OpenClaw.
|
||||
- Використовуйте `openai-codex/gpt-5.5`, коли потрібен маршрут Codex OAuth/підписки; використовуйте `openai/gpt-5.5`, коли ваше налаштування API-ключа та локальний каталог експонують публічний API-маршрут.
|
||||
- Для поширеного маршруту з підпискою плюс нативним середовищем виконання Codex увійдіть через автентифікацію `openai-codex`, але налаштуйте `openai/gpt-5.5` плюс `agents.defaults.agentRuntime.id: "codex"`.
|
||||
- Використовуйте `openai-codex/gpt-5.5` лише коли потрібен маршрут Codex OAuth/підписки через PI; використовуйте `openai/gpt-5.5` без перевизначення середовища виконання Codex, коли ваше налаштування API-ключа й локальний каталог надають маршрут публічного API.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } },
|
||||
plugins: { entries: { codex: { enabled: true } } },
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "openai/gpt-5.5" },
|
||||
agentRuntime: { id: "codex", fallback: "none" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
@ -179,13 +186,13 @@ OpenClaw постачається з каталогом pi-ai. Ці постач
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Моделі GLM" href="/uk/providers/glm">
|
||||
Z.AI Coding Plan або загальні API endpoint.
|
||||
Z.AI Coding Plan або загальні API-ендпоїнти.
|
||||
</Card>
|
||||
<Card title="MiniMax" href="/uk/providers/minimax">
|
||||
MiniMax Coding Plan OAuth або доступ за API-ключем.
|
||||
</Card>
|
||||
<Card title="Qwen Cloud" href="/uk/providers/qwen">
|
||||
Поверхня постачальника Qwen Cloud плюс зіставлення endpoint Alibaba DashScope і Coding Plan.
|
||||
Поверхня постачальника Qwen Cloud плюс зіставлення ендпоїнтів Alibaba DashScope і Coding Plan.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -205,23 +212,23 @@ OpenClaw постачається з каталогом pi-ai. Ці постач
|
||||
|
||||
### Google Gemini (API-ключ)
|
||||
|
||||
- Постачальник: `google`
|
||||
- Провайдер: `google`
|
||||
- Автентифікація: `GEMINI_API_KEY`
|
||||
- Необов'язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення)
|
||||
- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, запасний варіант `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одинарне перевизначення)
|
||||
- Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview`
|
||||
- Сумісність: застаріла конфігурація OpenClaw, що використовує `google/gemini-3.1-flash-preview`, нормалізується до `google/gemini-3-flash-preview`
|
||||
- Псевдонім: `google/gemini-3.1-pro` приймається та нормалізується до live-ID Gemini API від Google, `google/gemini-3.1-pro-preview`
|
||||
- Псевдонім: `google/gemini-3.1-pro` приймається та нормалізується до ідентифікатора поточного Gemini API від Google, `google/gemini-3.1-pro-preview`
|
||||
- CLI: `openclaw onboard --auth-choice gemini-api-key`
|
||||
- Thinking: `/think adaptive` використовує динамічне thinking Google. Gemini 3/3.1 пропускають фіксований `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`.
|
||||
- Прямі запуски Gemini також приймають `agents.defaults.models["google/<model>"].params.cachedContent` (або застаріле `cached_content`) для пересилання нативного для постачальника handle `cachedContents/...`; cache hits Gemini відображаються як OpenClaw `cacheRead`
|
||||
- Мислення: `/think adaptive` використовує динамічне мислення Google. Gemini 3/3.1 не вказує фіксований `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`.
|
||||
- Прямі запуски Gemini також приймають `agents.defaults.models["google/<model>"].params.cachedContent` (або застарілий `cached_content`), щоб передати власний для провайдера дескриптор `cachedContents/...`; влучання в кеш Gemini відображаються як OpenClaw `cacheRead`
|
||||
|
||||
### Google Vertex і Gemini CLI
|
||||
|
||||
- Постачальники: `google-vertex`, `google-gemini-cli`
|
||||
- Провайдери: `google-vertex`, `google-gemini-cli`
|
||||
- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує свій потік OAuth
|
||||
|
||||
<Warning>
|
||||
Gemini CLI OAuth в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження облікових записів Google після використання сторонніх клієнтів. Перегляньте умови Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити.
|
||||
Gemini CLI OAuth в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Перегляньте умови Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити.
|
||||
</Warning>
|
||||
|
||||
Gemini CLI OAuth постачається як частина вбудованого Plugin `google`.
|
||||
@ -251,7 +258,7 @@ Gemini CLI OAuth постачається як частина вбудовано
|
||||
openclaw models auth login --provider google-gemini-cli --set-default
|
||||
```
|
||||
|
||||
Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview`. Ви **не** вставляєте ідентифікатор клієнта або секрет у `openclaw.json`. Процес входу через CLI зберігає токени в профілях автентифікації на хості Gateway.
|
||||
Стандартна модель: `google-gemini-cli/gemini-3-flash-preview`. Ви **не** вставляєте ідентифікатор клієнта чи секрет у `openclaw.json`. Потік входу CLI зберігає токени в профілях автентифікації на хості Gateway.
|
||||
|
||||
</Step>
|
||||
<Step title="Налаштуйте проєкт (за потреби)">
|
||||
@ -259,7 +266,7 @@ Gemini CLI OAuth постачається як частина вбудовано
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
JSON-відповіді Gemini CLI розбираються з `response`; використання повертається до `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`.
|
||||
JSON-відповіді Gemini CLI розбираються з `response`; usage використовує запасний варіант `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`.
|
||||
|
||||
### Z.AI (GLM)
|
||||
|
||||
@ -283,15 +290,15 @@ JSON-відповіді Gemini CLI розбираються з `response`; ви
|
||||
- Автентифікація: `KILOCODE_API_KEY`
|
||||
- Приклад моделі: `kilocode/kilo/auto`
|
||||
- CLI: `openclaw onboard --auth-choice kilocode-api-key`
|
||||
- Базовий URL: `https://api.kilo.ai/api/gateway/`
|
||||
- Статичний резервний каталог постачає `kilocode/kilo/auto`; живе виявлення `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог виконання.
|
||||
- Базова URL-адреса: `https://api.kilo.ai/api/gateway/`
|
||||
- Статичний запасний каталог постачає `kilocode/kilo/auto`; поточне виявлення `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог середовища виконання.
|
||||
- Точна висхідна маршрутизація за `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw.
|
||||
|
||||
Докладні відомості про налаштування див. у [/providers/kilocode](/uk/providers/kilocode).
|
||||
Див. [/providers/kilocode](/uk/providers/kilocode) для подробиць налаштування.
|
||||
|
||||
### Інші вбудовані Plugin провайдерів
|
||||
|
||||
| Провайдер | Ідентифікатор | Змінна середовища автентифікації | Приклад моделі |
|
||||
| Провайдер | Ідентифікатор | Змінна середовища автентифікації | Приклад моделі |
|
||||
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
|
||||
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
|
||||
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
|
||||
@ -322,38 +329,38 @@ JSON-відповіді Gemini CLI розбираються з `response`; ви
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="OpenRouter">
|
||||
Застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Посилання DeepSeek, Moonshot і ZAI придатні для cache-TTL у керованому OpenRouter кешуванні підказок, але не отримують кеш-маркерів Anthropic. Як проксі-шлях, сумісний з OpenAI, він пропускає формування, призначене лише для нативного OpenAI (`serviceTier`, Responses `store`, підказки кешу підказок, сумісність міркування OpenAI). Посилання на базі Gemini зберігають лише санітизацію thought-signature проксі-Gemini.
|
||||
Застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Посилання DeepSeek, Moonshot і ZAI придатні для cache-TTL у керованому OpenRouter кешуванні промптів, але не отримують маркерів кешу Anthropic. Як proxy-стиль OpenAI-сумісного шляху, він пропускає формування, властиве лише нативному OpenAI (`serviceTier`, Responses `store`, підказки prompt-cache, сумісність reasoning OpenAI). Посилання на базі Gemini зберігають лише proxy-Gemini очищення thought-signature.
|
||||
</Accordion>
|
||||
<Accordion title="Kilo Gateway">
|
||||
Посилання на базі Gemini використовують той самий шлях санітизації проксі-Gemini; `kilocode/kilo/auto` та інші посилання проксі, що не підтримують міркування, пропускають ін’єкцію проксі-міркування.
|
||||
Посилання на базі Gemini проходять той самий шлях очищення proxy-Gemini; `kilocode/kilo/auto` та інші посилання, що не підтримують proxy reasoning, пропускають інʼєкцію proxy reasoning.
|
||||
</Accordion>
|
||||
<Accordion title="MiniMax">
|
||||
Онбординг через API-ключ записує явні текстові визначення чат-моделей M2.7; розуміння зображень лишається на медіапровайдері `MiniMax-VL-01`, що належить Plugin.
|
||||
Онбординг з API-ключем записує явні текстові визначення чат-моделей M2.7; розуміння зображень залишається на медіапровайдері `MiniMax-VL-01`, що належить Plugin.
|
||||
</Accordion>
|
||||
<Accordion title="NVIDIA">
|
||||
Ідентифікатори моделей використовують простір імен `nvidia/<vendor>/<model>` (наприклад, `nvidia/nvidia/nemotron-...` поряд із `nvidia/moonshotai/kimi-k2.5`); засоби вибору зберігають буквальну композицію `<provider>/<model-id>`, тоді як канонічний ключ, що надсилається до API, лишається з одним префіксом.
|
||||
Ідентифікатори моделей використовують простір імен `nvidia/<vendor>/<model>` (наприклад, `nvidia/nvidia/nemotron-...` поряд із `nvidia/moonshotai/kimi-k2.5`); вибирачі зберігають буквальну композицію `<provider>/<model-id>`, тоді як канонічний ключ, надісланий до API, залишається з одним префіксом.
|
||||
</Accordion>
|
||||
<Accordion title="xAI">
|
||||
Використовує шлях xAI Responses. `grok-4.3` є вбудованою чат-моделлю за замовчуванням. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` увімкнено за замовчуванням; вимкніть через `agents.defaults.models["xai/<model>"].params.tool_stream=false`.
|
||||
Використовує шлях xAI Responses. `grok-4.3` є вбудованою типовою чат-моделлю. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` увімкнено за замовчуванням; вимкніть через `agents.defaults.models["xai/<model>"].params.tool_stream=false`.
|
||||
</Accordion>
|
||||
<Accordion title="Cerebras">
|
||||
Постачається як вбудований Plugin провайдера `cerebras`. GLM використовує `zai-glm-4.7`; базовий URL, сумісний з OpenAI, — `https://api.cerebras.ai/v1`.
|
||||
Постачається як вбудований Plugin провайдера `cerebras`. GLM використовує `zai-glm-4.7`; OpenAI-сумісний базовий URL: `https://api.cerebras.ai/v1`.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Провайдери через `models.providers` (користувацький/базовий URL)
|
||||
|
||||
Використовуйте `models.providers` (або `models.json`), щоб додати **користувацьких** провайдерів або проксі, сумісні з OpenAI/Anthropic.
|
||||
Використовуйте `models.providers` (або `models.json`), щоб додати **користувацьких** провайдерів або OpenAI/Anthropic‑сумісні проксі.
|
||||
|
||||
Багато з наведених нижче вбудованих Plugin провайдерів уже публікують каталог за замовчуванням. Використовуйте явні записи `models.providers.<id>` лише тоді, коли хочете перевизначити базовий URL, заголовки або список моделей.
|
||||
Багато наведених нижче вбудованих Plugin провайдерів уже публікують типовий каталог. Використовуйте явні записи `models.providers.<id>` лише тоді, коли потрібно перевизначити типовий базовий URL, заголовки або список моделей.
|
||||
|
||||
Перевірки можливостей моделей Gateway також читають явні метадані `models.providers.<id>.models[]`. Якщо користувацька або проксі-модель приймає зображення, задайте `input: ["text", "image"]` для цієї моделі, щоб WebChat і шляхи вкладень із походженням від вузла передавали зображення як нативні вхідні дані моделі, а не як медіа-посилання лише для тексту.
|
||||
Перевірки можливостей моделей Gateway також читають явні метадані `models.providers.<id>.models[]`. Якщо користувацька або проксі-модель приймає зображення, установіть `input: ["text", "image"]` для цієї моделі, щоб WebChat і шляхи вкладень із джерелом у вузлі передавали зображення як нативні входи моделі, а не як текстові медіапосилання.
|
||||
|
||||
### Moonshot AI (Kimi)
|
||||
|
||||
Moonshot постачається як вбудований Plugin постачальника. За замовчуванням використовуйте вбудований постачальник і додавайте явний запис `models.providers.moonshot` лише тоді, коли потрібно перевизначити базову URL-адресу або метадані моделі:
|
||||
Moonshot постачається як вбудований Plugin провайдера. Використовуйте вбудованого провайдера за замовчуванням і додавайте явний запис `models.providers.moonshot` лише тоді, коли потрібно перевизначити базовий URL або метадані моделі:
|
||||
|
||||
- Постачальник: `moonshot`
|
||||
- Провайдер: `moonshot`
|
||||
- Автентифікація: `MOONSHOT_API_KEY`
|
||||
- Приклад моделі: `moonshot/kimi-k2.6`
|
||||
- CLI: `openclaw onboard --auth-choice moonshot-api-key` або `openclaw onboard --auth-choice moonshot-api-key-cn`
|
||||
@ -389,11 +396,11 @@ Moonshot постачається як вбудований Plugin постач
|
||||
}
|
||||
```
|
||||
|
||||
### Кодування Kimi
|
||||
### Kimi для програмування
|
||||
|
||||
Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI:
|
||||
Kimi Coding використовує Anthropic-сумісний кінцевий пункт Moonshot AI:
|
||||
|
||||
- Постачальник: `kimi`
|
||||
- Провайдер: `kimi`
|
||||
- Автентифікація: `KIMI_API_KEY`
|
||||
- Приклад моделі: `kimi/kimi-code`
|
||||
|
||||
@ -406,13 +413,13 @@ Kimi Coding використовує Anthropic-сумісну кінцеву т
|
||||
}
|
||||
```
|
||||
|
||||
Застарілий `kimi/k2p5` і надалі приймається як ідентифікатор моделі для сумісності.
|
||||
Застарілий `kimi/k2p5` і надалі приймається як сумісний ідентифікатор моделі.
|
||||
|
||||
### Volcano Engine (Doubao)
|
||||
|
||||
Volcano Engine (火山引擎) надає доступ до Doubao та інших моделей у Китаї.
|
||||
|
||||
- Постачальник: `volcengine` (кодування: `volcengine-plan`)
|
||||
- Провайдер: `volcengine` (кодування: `volcengine-plan`)
|
||||
- Автентифікація: `VOLCANO_ENGINE_API_KEY`
|
||||
- Приклад моделі: `volcengine-plan/ark-code-latest`
|
||||
- CLI: `openclaw onboard --auth-choice volcengine-api-key`
|
||||
@ -425,9 +432,9 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши
|
||||
}
|
||||
```
|
||||
|
||||
Onboarding за замовчуванням використовує поверхню для кодування, але загальний каталог `volcengine/*` реєструється водночас.
|
||||
Під час онбордингу за замовчуванням використовується поверхня для кодування, але загальний каталог `volcengine/*` реєструється одночасно.
|
||||
|
||||
У засобах вибору моделі під час onboarding/configure варіант автентифікації Volcengine надає перевагу рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній засіб вибору, обмежений постачальником.
|
||||
У засобах вибору моделей під час онбордингу/налаштування варіант автентифікації Volcengine віддає перевагу рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажено, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього засобу вибору, обмеженого провайдером.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Стандартні моделі">
|
||||
@ -438,7 +445,7 @@ Onboarding за замовчуванням використовує поверх
|
||||
- `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K)
|
||||
|
||||
</Tab>
|
||||
<Tab title="Моделі для програмування (volcengine-plan)">
|
||||
<Tab title="Моделі для кодування (volcengine-plan)">
|
||||
- `volcengine-plan/ark-code-latest`
|
||||
- `volcengine-plan/doubao-seed-code`
|
||||
- `volcengine-plan/kimi-k2.5`
|
||||
@ -452,7 +459,7 @@ Onboarding за замовчуванням використовує поверх
|
||||
|
||||
BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine.
|
||||
|
||||
- Провайдер: `byteplus` (для програмування: `byteplus-plan`)
|
||||
- Провайдер: `byteplus` (кодування: `byteplus-plan`)
|
||||
- Автентифікація: `BYTEPLUS_API_KEY`
|
||||
- Приклад моделі: `byteplus-plan/ark-code-latest`
|
||||
- CLI: `openclaw onboard --auth-choice byteplus-api-key`
|
||||
@ -465,9 +472,9 @@ BytePlus ARK надає міжнародним користувачам дост
|
||||
}
|
||||
```
|
||||
|
||||
Onboarding типово використовує поверхню для програмування, але загальний каталог `byteplus/*` реєструється одночасно.
|
||||
Під час онбордингу за замовчуванням використовується поверхня для кодування, але загальний каталог `byteplus/*` реєструється одночасно.
|
||||
|
||||
У засобах вибору моделі під час onboarding/configure варіант автентифікації BytePlus віддає перевагу рядкам і `byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, OpenClaw натомість повертається до нефільтрованого каталогу, а не показує порожній засіб вибору, обмежений провайдером.
|
||||
У засобах вибору моделей під час онбордингу/налаштування варіант автентифікації BytePlus віддає перевагу рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього засобу вибору, обмеженого провайдером.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Стандартні моделі">
|
||||
@ -476,7 +483,7 @@ Onboarding типово використовує поверхню для про
|
||||
- `byteplus/glm-4-7-251222` (GLM 4.7)
|
||||
|
||||
</Tab>
|
||||
<Tab title="Моделі для програмування (byteplus-plan)">
|
||||
<Tab title="Моделі для кодування (byteplus-plan)">
|
||||
- `byteplus-plan/ark-code-latest`
|
||||
- `byteplus-plan/doubao-seed-code`
|
||||
- `byteplus-plan/kimi-k2.5`
|
||||
@ -520,30 +527,30 @@ MiniMax налаштовується через `models.providers`, оскіль
|
||||
|
||||
- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth`
|
||||
- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth`
|
||||
- MiniMax API key (Global): `--auth-choice minimax-global-api`
|
||||
- MiniMax API key (CN): `--auth-choice minimax-cn-api`
|
||||
- Ключ API MiniMax (Global): `--auth-choice minimax-global-api`
|
||||
- Ключ API MiniMax (CN): `--auth-choice minimax-cn-api`
|
||||
- Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal`
|
||||
|
||||
Див. [/providers/minimax](/uk/providers/minimax), щоб дізнатися подробиці налаштування, варіанти моделей і фрагменти конфігурації.
|
||||
|
||||
<Note>
|
||||
На Anthropic-сумісному шляху потокового передавання MiniMax OpenClaw типово вимикає мислення, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`.
|
||||
На Anthropic-сумісному шляху потокового передавання MiniMax OpenClaw за замовчуванням вимикає мислення, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`.
|
||||
</Note>
|
||||
|
||||
Розділення можливостей, якими володіє Plugin:
|
||||
Розподіл можливостей, якими володіє Plugin:
|
||||
|
||||
- Типові налаштування тексту/чату залишаються на `minimax/MiniMax-M2.7`
|
||||
- Стандартні значення для тексту/чату залишаються на `minimax/MiniMax-M2.7`
|
||||
- Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01`
|
||||
- Розуміння зображень належить Plugin: `MiniMax-VL-01` на обох шляхах автентифікації MiniMax
|
||||
- Розуміння зображень належить Plugin: `MiniMax-VL-01` в обох шляхах автентифікації MiniMax
|
||||
- Вебпошук залишається на ідентифікаторі провайдера `minimax`
|
||||
|
||||
### LM Studio
|
||||
|
||||
LM Studio постачається як вбудований Plugin провайдера, який використовує нативний API:
|
||||
LM Studio постачається як вбудований Plugin провайдера, що використовує нативний API:
|
||||
|
||||
- Провайдер: `lmstudio`
|
||||
- Автентифікація: `LM_API_TOKEN`
|
||||
- Типова базова URL-адреса інференсу: `http://localhost:1234/v1`
|
||||
- Базова URL-адреса інференсу за замовчуванням: `http://localhost:1234/v1`
|
||||
|
||||
Потім задайте модель (замініть на один з ідентифікаторів, повернених `http://localhost:1234/api/v1/models`):
|
||||
|
||||
@ -555,11 +562,11 @@ LM Studio постачається як вбудований Plugin провай
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw використовує нативні `/api/v1/models` і `/api/v1/models/load` LM Studio для виявлення й автозавантаження, а `/v1/chat/completions` типово для інференсу. Див. [/providers/lmstudio](/uk/providers/lmstudio), щоб дізнатися про налаштування та усунення несправностей.
|
||||
OpenClaw використовує нативні `/api/v1/models` і `/api/v1/models/load` LM Studio для виявлення й автоматичного завантаження, а `/v1/chat/completions` — для інференсу за замовчуванням. Див. [/providers/lmstudio](/uk/providers/lmstudio) для налаштування й усунення несправностей.
|
||||
|
||||
### Ollama
|
||||
|
||||
Ollama постачається як вбудований Plugin провайдера й використовує нативний API Ollama:
|
||||
Ollama постачається як вбудований Plugin провайдера та використовує нативний API Ollama:
|
||||
|
||||
- Провайдер: `ollama`
|
||||
- Автентифікація: не потрібна (локальний сервер)
|
||||
@ -579,17 +586,17 @@ ollama pull llama3.3
|
||||
}
|
||||
```
|
||||
|
||||
Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви вмикаєте її через `OLLAMA_API_KEY`, а вбудований Plugin провайдера додає Ollama безпосередньо до `openclaw onboard` і засобу вибору моделі. Див. [/providers/ollama](/uk/providers/ollama), щоб дізнатися про onboarding, хмарний/локальний режим і власну конфігурацію.
|
||||
Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте це через `OLLAMA_API_KEY`, а вбудований Plugin провайдера додає Ollama безпосередньо до `openclaw onboard` і засобу вибору моделей. Див. [/providers/ollama](/uk/providers/ollama) для онбордингу, хмарного/локального режиму та власної конфігурації.
|
||||
|
||||
### vLLM
|
||||
|
||||
vLLM постачається як вбудований Plugin провайдера для локальних/самостійно розміщених серверів, сумісних з OpenAI:
|
||||
vLLM постачається як вбудований Plugin провайдера для локальних/самостійно розгорнутих серверів, сумісних з OpenAI:
|
||||
|
||||
- Провайдер: `vllm`
|
||||
- Автентифікація: необов’язкова (залежить від вашого сервера)
|
||||
- Типова базова URL-адреса: `http://127.0.0.1:8000/v1`
|
||||
- Базова URL-адреса за замовчуванням: `http://127.0.0.1:8000/v1`
|
||||
|
||||
Щоб увімкнути локальне автоматичне виявлення (будь-яке значення працює, якщо ваш сервер не вимагає автентифікації):
|
||||
Щоб явно ввімкнути локальне автоматичне виявлення (працює будь-яке значення, якщо ваш сервер не вимагає автентифікації):
|
||||
|
||||
```bash
|
||||
export VLLM_API_KEY="vllm-local"
|
||||
@ -605,17 +612,17 @@ export VLLM_API_KEY="vllm-local"
|
||||
}
|
||||
```
|
||||
|
||||
Див. [/providers/vllm](/uk/providers/vllm), щоб дізнатися подробиці.
|
||||
Див. [/providers/vllm](/uk/providers/vllm) для подробиць.
|
||||
|
||||
### SGLang
|
||||
|
||||
SGLang постачається як вбудований Plugin провайдера для швидких самостійно розміщених серверів, сумісних з OpenAI:
|
||||
SGLang постачається як вбудований Plugin провайдера для швидких самостійно розгорнутих серверів, сумісних з OpenAI:
|
||||
|
||||
- Провайдер: `sglang`
|
||||
- Автентифікація: необов’язкова (залежить від вашого сервера)
|
||||
- Типова базова URL-адреса: `http://127.0.0.1:30000/v1`
|
||||
- Базова URL-адреса за замовчуванням: `http://127.0.0.1:30000/v1`
|
||||
|
||||
Щоб увімкнути локальне автоматичне виявлення (будь-яке значення працює, якщо ваш сервер не вимагає автентифікації):
|
||||
Щоб явно ввімкнути локальне автоматичне виявлення (працює будь-яке значення, якщо ваш сервер не вимагає автентифікації):
|
||||
|
||||
```bash
|
||||
export SGLANG_API_KEY="sglang-local"
|
||||
@ -631,7 +638,7 @@ export SGLANG_API_KEY="sglang-local"
|
||||
}
|
||||
```
|
||||
|
||||
Див. [/providers/sglang](/uk/providers/sglang), щоб дізнатися подробиці.
|
||||
Див. [/providers/sglang](/uk/providers/sglang) для подробиць.
|
||||
|
||||
### Локальні проксі (LM Studio, vLLM, LiteLLM тощо)
|
||||
|
||||
@ -670,8 +677,8 @@ export SGLANG_API_KEY="sglang-local"
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Типові необов’язкові поля">
|
||||
Для власних провайдерів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. Якщо їх пропущено, OpenClaw типово використовує:
|
||||
<Accordion title="Стандартні необов’язкові поля">
|
||||
Для власних провайдерів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. Якщо їх пропущено, OpenClaw використовує такі стандартні значення:
|
||||
|
||||
- `reasoning: false`
|
||||
- `input: ["text"]`
|
||||
@ -679,18 +686,18 @@ export SGLANG_API_KEY="sglang-local"
|
||||
- `contextWindow: 200000`
|
||||
- `maxTokens: 8192`
|
||||
|
||||
Рекомендовано: задавайте явні значення, які відповідають обмеженням вашого проксі/моделі.
|
||||
Рекомендовано: задайте явні значення, що відповідають обмеженням вашого проксі/моделі.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Правила формування маршрутів проксі">
|
||||
- Для `api: "openai-completions"` на ненативних кінцевих точках (будь-яка непорожня `baseUrl`, хост якої не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок провайдера 400 для непідтримуваних ролей `developer`.
|
||||
- Проксі-стиль маршрутів, сумісних з OpenAI, також пропускає нативне формування запитів, властиве лише OpenAI: без `service_tier`, без Responses `store`, без Completions `store`, без підказок prompt-cache, без формування payload сумісності OpenAI reasoning і без прихованих заголовків атрибуції OpenClaw.
|
||||
- Для OpenAI-сумісних проксі Completions, яким потрібні поля, специфічні для постачальника, задайте `agents.defaults.models["provider/model"].params.extra_body` (або `extraBody`), щоб об’єднати додатковий JSON з тілом вихідного запиту.
|
||||
<Accordion title="Правила формування маршруту проксі">
|
||||
- Для `api: "openai-completions"` на ненативних кінцевих точках (будь-яка непорожня `baseUrl`, хост якої не є `api.openai.com`) OpenClaw примусово задає `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від провайдера для непідтримуваних ролей `developer`.
|
||||
- Проксі-маршрути, сумісні з OpenAI, також пропускають формування запитів, специфічне лише для нативного OpenAI: без `service_tier`, без Responses `store`, без Completions `store`, без підказок кешу промптів, без формування payload сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw.
|
||||
- Для проксі OpenAI-сумісних Completions, яким потрібні поля, специфічні для постачальника, задайте `agents.defaults.models["provider/model"].params.extra_body` (або `extraBody`), щоб об’єднати додатковий JSON у вихідне тіло запиту.
|
||||
- Для елементів керування chat-template vLLM задайте `agents.defaults.models["provider/model"].params.chat_template_kwargs`. Вбудований Plugin vLLM автоматично надсилає `enable_thinking: false` і `force_nonempty_content: true` для `vllm/nemotron-3-*`, коли рівень мислення сесії вимкнено.
|
||||
- Для повільних локальних моделей або віддалених хостів LAN/tailnet задайте `models.providers.<id>.timeoutSeconds`. Це розширює обробку HTTP-запиту моделі провайдера, включно з підключенням, заголовками, потоковою передачею тіла й загальним перериванням guarded-fetch, не збільшуючи загальний тайм-аут виконання агента.
|
||||
- Якщо `baseUrl` порожній/пропущений, OpenClaw зберігає типову поведінку OpenAI (яка розв’язується в `api.openai.com`).
|
||||
- З міркувань безпеки явний `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних кінцевих точках `openai-completions`.
|
||||
- Для `api: "anthropic-messages"` на непрямих кінцевих точках (будь-який провайдер, крім канонічного `anthropic`, або власний `models.providers.anthropic.baseUrl`, хост якого не є публічною кінцевою точкою `api.anthropic.com`) OpenClaw пригнічує неявні бета-заголовки Anthropic, як-от `claude-code-20250219`, `interleaved-thinking-2025-05-14` і маркери OAuth, щоб власні Anthropic-сумісні проксі не відхиляли непідтримувані бета-прапорці. Явно задайте `models.providers.<id>.headers["anthropic-beta"]`, якщо вашому проксі потрібні конкретні бета-функції.
|
||||
- Для повільних локальних моделей або віддалених хостів LAN/tailnet задайте `models.providers.<id>.timeoutSeconds`. Це розширює обробку HTTP-запитів до моделей провайдера, включно з підключенням, заголовками, потоковим передаванням тіла та повним guarded-fetch abort, не збільшуючи загальний тайм-аут виконання агента.
|
||||
- Якщо `baseUrl` порожній/пропущений, OpenClaw зберігає стандартну поведінку OpenAI (яка розв’язується до `api.openai.com`).
|
||||
- З міркувань безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних кінцевих точках `openai-completions`.
|
||||
- Для `api: "anthropic-messages"` на непрямих кінцевих точках (будь-який провайдер, окрім канонічного `anthropic`, або власний `models.providers.anthropic.baseUrl`, хост якого не є публічною кінцевою точкою `api.anthropic.com`) OpenClaw пригнічує неявні бета-заголовки Anthropic, як-от `claude-code-20250219`, `interleaved-thinking-2025-05-14` і маркери OAuth, щоб власні Anthropic-сумісні проксі не відхиляли непідтримувані бета-прапорці. Явно задайте `models.providers.<id>.headers["anthropic-beta"]`, якщо вашому проксі потрібні певні бета-функції.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -707,7 +714,7 @@ openclaw models list
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей
|
||||
- [Відмовостійке перемикання моделей](/uk/concepts/model-failover) — ланцюжки резервування та поведінка повторних спроб
|
||||
- [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделі
|
||||
- [Відмовостійкість моделей](/uk/concepts/model-failover) — ланцюжки резервування та поведінка повторних спроб
|
||||
- [Моделі](/uk/concepts/models) — конфігурація моделей і псевдоніми
|
||||
- [Провайдери](/uk/providers) — посібники з налаштування для кожного провайдера
|
||||
|
||||
@ -1,36 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання або змінення CLI для моделей (models list/set/scan/aliases/fallbacks)
|
||||
- Зміна поведінки резервного перемикання моделі або користувацького досвіду вибору
|
||||
- Зміна поведінки резервного переходу моделі або UX вибору
|
||||
- Оновлення зондів сканування моделей (інструменти/зображення)
|
||||
sidebarTitle: Models CLI
|
||||
summary: 'CLI моделей: список, задання, псевдоніми, резервні варіанти, сканування, статус'
|
||||
summary: 'CLI моделей: список, встановлення, псевдоніми, резервні варіанти, сканування, статус'
|
||||
title: CLI моделей
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T17:09:53Z"
|
||||
generated_at: "2026-05-02T02:37:24Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 64b97ddfcc6f804044580dfc9a441d426f737e9e7d007d78b0b045a52068b34f
|
||||
source_hash: 620df60ee1117a32f0232bf4b56fbc5a9558be5cc3b73a31336f8ab64fd29ebb
|
||||
source_path: concepts/models.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Аварійне перемикання моделей" href="/uk/concepts/model-failover">
|
||||
Ротація профілів автентифікації, періоди охолодження та їхня взаємодія з резервними варіантами.
|
||||
<Card title="Відмовостійке перемикання моделей" href="/uk/concepts/model-failover">
|
||||
Ротація профілів автентифікації, періоди очікування та як це взаємодіє з резервними варіантами.
|
||||
</Card>
|
||||
<Card title="Постачальники моделей" href="/uk/concepts/model-providers">
|
||||
Короткий огляд постачальників і приклади.
|
||||
<Card title="Провайдери моделей" href="/uk/concepts/model-providers">
|
||||
Короткий огляд провайдерів і приклади.
|
||||
</Card>
|
||||
<Card title="Середовища виконання агентів" href="/uk/concepts/agent-runtimes">
|
||||
PI, Codex та інші середовища виконання циклу агента.
|
||||
</Card>
|
||||
<Card title="Довідник конфігурації" href="/uk/gateway/config-agents#agent-defaults">
|
||||
Ключі конфігурації моделей.
|
||||
Ключі конфігурації моделі.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Посилання на моделі вибирають постачальника й модель. Зазвичай вони не вибирають низькорівневе середовище виконання агента. Наприклад, `openai/gpt-5.5` може працювати через звичайний шлях постачальника OpenAI або через середовище виконання app-server Codex, залежно від `agents.defaults.agentRuntime.id`. Див. [Середовища виконання агентів](/uk/concepts/agent-runtimes).
|
||||
Посилання на моделі вибирають провайдера й модель. Зазвичай вони не вибирають низькорівневе середовище виконання агента. Наприклад, `openai/gpt-5.5` може запускатися через звичайний шлях провайдера OpenAI або через середовище виконання app-server Codex, залежно від `agents.defaults.agentRuntime.id`. У режимі середовища виконання Codex посилання `openai/gpt-*` не означає оплату за API-ключем; автентифікація може надходити з облікового запису Codex або профілю автентифікації `openai-codex`. Див. [Середовища виконання агентів](/uk/concepts/agent-runtimes).
|
||||
|
||||
## Як працює вибір моделі
|
||||
|
||||
@ -43,8 +43,8 @@ OpenClaw вибирає моделі в такому порядку:
|
||||
<Step title="Резервні варіанти">
|
||||
`agents.defaults.model.fallbacks` (за порядком).
|
||||
</Step>
|
||||
<Step title="Аварійне перемикання автентифікації постачальника">
|
||||
Аварійне перемикання автентифікації відбувається всередині постачальника перед переходом до наступної моделі.
|
||||
<Step title="Відмовостійке перемикання автентифікації провайдера">
|
||||
Відмовостійке перемикання автентифікації відбувається всередині провайдера перед переходом до наступної моделі.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -52,41 +52,41 @@ OpenClaw вибирає моделі в такому порядку:
|
||||
<Accordion title="Пов’язані поверхні моделей">
|
||||
- `agents.defaults.models` — це allowlist/каталог моделей, які OpenClaw може використовувати (плюс псевдоніми).
|
||||
- `agents.defaults.imageModel` використовується **лише коли** основна модель не може приймати зображення.
|
||||
- `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо його пропущено, інструмент переходить до `agents.defaults.imageModel`, а потім до визначеної моделі сеансу/типової моделі.
|
||||
- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо його пропущено, `image_generate` усе ще може визначити типове значення постачальника з підтримкою автентифікації. Спочатку він пробує поточного типового постачальника, потім решту зареєстрованих постачальників генерації зображень у порядку provider-id. Якщо ви задаєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника.
|
||||
- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його пропущено, `music_generate` усе ще може визначити типове значення постачальника з підтримкою автентифікації. Спочатку він пробує поточного типового постачальника, потім решту зареєстрованих постачальників генерації музики в порядку provider-id. Якщо ви задаєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника.
|
||||
- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його пропущено, `video_generate` усе ще може визначити типове значення постачальника з підтримкою автентифікації. Спочатку він пробує поточного типового постачальника, потім решту зареєстрованих постачальників генерації відео в порядку provider-id. Якщо ви задаєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника.
|
||||
- Типові значення для окремих агентів можуть перевизначати `agents.defaults.model` через `agents.list[].model` плюс прив’язки (див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent)).
|
||||
- `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо його не вказано, інструмент переходить до `agents.defaults.imageModel`, а потім до розв’язаної моделі сесії/моделі за замовчуванням.
|
||||
- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо його не вказано, `image_generate` усе ще може вивести стандартного провайдера, підкріпленого автентифікацією. Спершу він пробує поточного стандартного провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
|
||||
- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його не вказано, `music_generate` усе ще може вивести стандартного провайдера, підкріпленого автентифікацією. Спершу він пробує поточного стандартного провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
|
||||
- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його не вказано, `video_generate` усе ще може вивести стандартного провайдера, підкріпленого автентифікацією. Спершу він пробує поточного стандартного провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
|
||||
- Стандартні значення для окремого агента можуть перевизначати `agents.defaults.model` через `agents.list[].model` плюс прив’язки (див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent)).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Джерело вибору та поведінка резервних варіантів
|
||||
## Джерело вибору й поведінка резервного переходу
|
||||
|
||||
Один і той самий `provider/model` може означати різні речі залежно від того, звідки він узявся:
|
||||
Однакове `provider/model` може означати різні речі залежно від того, звідки воно походить:
|
||||
|
||||
- Налаштовані типові значення (`agents.defaults.model.primary` і основні моделі для конкретних агентів) є звичайною початковою точкою та використовують `agents.defaults.model.fallbacks`.
|
||||
- Автоматичні резервні вибори — це тимчасовий стан відновлення. Вони зберігаються з `modelOverrideSource: "auto"`, щоб наступні ходи могли й надалі використовувати ланцюжок резервних варіантів без початкової перевірки відомо несправної основної моделі.
|
||||
- Вибори користувача в сеансі є точними. `/model`, вибір моделі, `session_status(model=...)` і `sessions.patch` зберігають `modelOverrideSource: "user"`; якщо вибраний постачальник/модель недоступні, OpenClaw завершується з видимою помилкою замість переходу до іншої налаштованої моделі.
|
||||
- Cron `--model` / payload `model` — це основна модель для окремого завдання. Вона все одно використовує налаштовані резервні варіанти, якщо завдання не надає явні payload `fallbacks` (використовуйте `fallbacks: []` для строгого запуску cron).
|
||||
- Засоби вибору типової моделі CLI та allowlist поважають `models.mode: "replace"`, показуючи явні `models.providers.*.models` замість завантаження повного вбудованого каталогу.
|
||||
- Засіб вибору моделей Control UI запитує в Gateway налаштований перегляд моделей: `agents.defaults.models`, якщо він наявний, інакше явні `models.providers.*.models` плюс постачальники з придатною автентифікацією. Повний вбудований каталог зарезервовано для явних переглядів огляду, таких як `models.list` з `view: "all"` або `openclaw models list --all`.
|
||||
- Налаштовані стандартні значення (`agents.defaults.model.primary` та специфічні для агента основні моделі) є звичайною відправною точкою й використовують `agents.defaults.model.fallbacks`.
|
||||
- Автоматичні резервні вибори — це тимчасовий стан відновлення. Вони зберігаються з `modelOverrideSource: "auto"`, щоб наступні ходи могли далі використовувати резервний ланцюжок без попереднього зондування відомої проблемної основної моделі.
|
||||
- Вибори користувача для сесії є точними. `/model`, засіб вибору моделі, `session_status(model=...)` і `sessions.patch` зберігають `modelOverrideSource: "user"`; якщо вибраний provider/model недоступний, OpenClaw завершується видимою помилкою замість переходу до іншої налаштованої моделі.
|
||||
- Cron `--model` / payload `model` — це основна модель для окремого завдання. Вона все одно використовує налаштовані резервні варіанти, якщо завдання не надає явні payload `fallbacks` (використовуйте `fallbacks: []` для суворого запуску cron).
|
||||
- CLI default-model і засоби вибору allowlist поважають `models.mode: "replace"`, показуючи явні `models.providers.*.models` замість завантаження повного вбудованого каталогу.
|
||||
- Засіб вибору моделі в Control UI запитує в Gateway налаштоване подання моделей: `agents.defaults.models`, якщо воно наявне, інакше явні `models.providers.*.models` плюс провайдери з придатною автентифікацією. Повний вбудований каталог зарезервований для явних подань перегляду, таких як `models.list` з `view: "all"` або `openclaw models list --all`.
|
||||
|
||||
## Коротка політика моделей
|
||||
|
||||
- Установіть основною найсильнішу модель найновішого покоління, доступну вам.
|
||||
- Використовуйте резервні варіанти для завдань, чутливих до вартості/затримки, і менш критичного чату.
|
||||
- Для агентів із підтримкою інструментів або недовірених вхідних даних уникайте старіших/слабших рівнів моделей.
|
||||
- Задайте основною найпотужнішу доступну вам модель останнього покоління.
|
||||
- Використовуйте резервні варіанти для завдань, чутливих до вартості/затримки, і чатів із нижчими ризиками.
|
||||
- Для агентів з увімкненими інструментами або недовірених вхідних даних уникайте старіших/слабших рівнів моделей.
|
||||
|
||||
## Початкове налаштування (рекомендовано)
|
||||
## Онбординг (рекомендовано)
|
||||
|
||||
Якщо ви не хочете редагувати конфігурацію вручну, запустіть початкове налаштування:
|
||||
Якщо ви не хочете редагувати конфігурацію вручну, запустіть онбординг:
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
Воно може налаштувати модель + автентифікацію для поширених постачальників, зокрема **підписку OpenAI Code (Codex)** (OAuth) і **Anthropic** (API key або Claude CLI).
|
||||
Він може налаштувати модель + автентифікацію для поширених провайдерів, зокрема **підписку OpenAI Code (Codex)** (OAuth) і **Anthropic** (API-ключ або Claude CLI).
|
||||
|
||||
## Ключі конфігурації (огляд)
|
||||
|
||||
@ -95,18 +95,18 @@ openclaw onboard
|
||||
- `agents.defaults.pdfModel.primary` і `agents.defaults.pdfModel.fallbacks`
|
||||
- `agents.defaults.imageGenerationModel.primary` і `agents.defaults.imageGenerationModel.fallbacks`
|
||||
- `agents.defaults.videoGenerationModel.primary` і `agents.defaults.videoGenerationModel.fallbacks`
|
||||
- `agents.defaults.models` (allowlist + псевдоніми + параметри постачальника)
|
||||
- `models.providers` (користувацькі постачальники, записані в `models.json`)
|
||||
- `agents.defaults.models` (allowlist + псевдоніми + параметри провайдера)
|
||||
- `models.providers` (користувацькі провайдери, записані в `models.json`)
|
||||
|
||||
<Note>
|
||||
Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми постачальників, як-от `z.ai/*`, нормалізуються до `zai/*`.
|
||||
Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів на кшталт `z.ai/*` нормалізуються до `zai/*`.
|
||||
|
||||
Приклади конфігурації постачальників (включно з OpenCode) розміщені в [OpenCode](/uk/providers/opencode).
|
||||
Приклади конфігурації провайдерів (включно з OpenCode) містяться в [OpenCode](/uk/providers/opencode).
|
||||
</Note>
|
||||
|
||||
### Безпечні редагування allowlist
|
||||
|
||||
Використовуйте адитивні записи під час ручного оновлення `agents.defaults.models`:
|
||||
Використовуйте адитивні записи, коли оновлюєте `agents.defaults.models` вручну:
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
|
||||
@ -114,23 +114,23 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Правила захисту від перезапису">
|
||||
`openclaw config set` захищає мапи моделей/постачальників від випадкових перезаписів. Просте присвоєння об’єкта до `agents.defaults.models`, `models.providers` або `models.providers.<id>.models` відхиляється, якщо воно видалило б наявні записи. Використовуйте `--merge` для адитивних змін; використовуйте `--replace` лише тоді, коли надане значення має стати повним цільовим значенням.
|
||||
`openclaw config set` захищає мапи моделей/провайдерів від випадкових перезаписів. Звичайне присвоєння об’єкта до `agents.defaults.models`, `models.providers` або `models.providers.<id>.models` відхиляється, якщо воно вилучило б наявні записи. Використовуйте `--merge` для адитивних змін; використовуйте `--replace` лише тоді, коли надане значення має стати повним цільовим значенням.
|
||||
|
||||
Інтерактивне налаштування постачальника й `openclaw configure --section model` також об’єднують вибори в межах постачальника з наявним allowlist, тому додавання Codex, Ollama або іншого постачальника не видаляє непов’язані записи моделей. Configure зберігає наявний `agents.defaults.model.primary`, коли автентифікацію постачальника застосовують повторно. Явні команди встановлення типового значення, такі як `openclaw models auth login --provider <id> --set-default` і `openclaw models set <model>`, усе ще замінюють `agents.defaults.model.primary`.
|
||||
Інтерактивне налаштування провайдера й `openclaw configure --section model` також зливають вибори в межах провайдера з наявним allowlist, тож додавання Codex, Ollama або іншого провайдера не видаляє непов’язані записи моделей. Configure зберігає наявний `agents.defaults.model.primary`, коли автентифікацію провайдера застосовують повторно. Явні команди встановлення стандартного значення, такі як `openclaw models auth login --provider <id> --set-default` і `openclaw models set <model>`, усе ще замінюють `agents.defaults.model.primary`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## «Модель не дозволена» (і чому відповіді зупиняються)
|
||||
## "Модель не дозволена" (і чому відповіді зупиняються)
|
||||
|
||||
Якщо `agents.defaults.models` задано, він стає **allowlist** для `/model` і для перевизначень сеансу. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає:
|
||||
Якщо `agents.defaults.models` задано, він стає **allowlist** для `/model` і перевизначень сесії. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає:
|
||||
|
||||
```
|
||||
Model "provider/model" is not allowed. Use /model to list available models.
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Це відбувається **до** генерації звичайної відповіді, тому може здаватися, що повідомлення «не відповіло». Виправлення таке:
|
||||
Це відбувається **до** створення звичайної відповіді, тому може здаватися, що повідомлення "не відповіло". Виправлення: зробіть одне з такого:
|
||||
|
||||
- Додайте модель до `agents.defaults.models`, або
|
||||
- Очистьте allowlist (видаліть `agents.defaults.models`), або
|
||||
@ -138,7 +138,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
|
||||
|
||||
</Warning>
|
||||
|
||||
Для локальних/GGUF моделей зберігайте повне посилання з префіксом постачальника в allowlist,
|
||||
Для локальних/GGUF-моделей зберігайте повне посилання з префіксом провайдера в allowlist,
|
||||
наприклад `ollama/gemma4:26b`, `lmstudio/Gemma4-26b-a4-it-gguf` або
|
||||
точний provider/model, показаний `openclaw models list --provider <provider>`.
|
||||
Самих локальних імен файлів або відображуваних назв недостатньо, коли allowlist
|
||||
@ -160,7 +160,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
|
||||
|
||||
## Перемикання моделей у чаті (`/model`)
|
||||
|
||||
Ви можете перемикати моделі для поточного сеансу без перезапуску:
|
||||
Ви можете перемикати моделі для поточної сесії без перезапуску:
|
||||
|
||||
```
|
||||
/model
|
||||
@ -172,28 +172,28 @@ Model "provider/model" is not allowed. Use /model to list available models.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поведінка засобу вибору">
|
||||
- `/model` (і `/model list`) — це компактний нумерований засіб вибору (родина моделей + доступні постачальники).
|
||||
- У Discord `/model` і `/models` відкривають інтерактивний засіб вибору з розкривними списками постачальника й моделі плюс кроком Submit.
|
||||
- `/models add` застарів і тепер повертає повідомлення про застарілість замість реєстрації моделей із чату.
|
||||
- `/model` (і `/model list`) — це компактний нумерований засіб вибору (родина моделі + доступні провайдери).
|
||||
- У Discord `/model` і `/models` відкривають інтерактивний засіб вибору з випадаючими списками провайдера й моделі та кроком Submit.
|
||||
- `/models add` застарілий і тепер повертає повідомлення про застарілість замість реєстрації моделей із чату.
|
||||
- `/model <#>` вибирає з цього засобу вибору.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Збереження та живе перемикання">
|
||||
- `/model` негайно зберігає новий вибір сеансу.
|
||||
- Якщо агент бездіяльний, наступний запуск одразу використовує нову модель.
|
||||
- Якщо запуск уже активний, OpenClaw позначає живе перемикання як очікуване й перезапускає в нову модель лише в чистій точці повтору.
|
||||
- Якщо активність інструментів або виведення відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повтору або наступного ходу користувача.
|
||||
- Вибране користувачем посилання `/model` є строгим для цього сеансу: якщо вибраний постачальник/модель недоступні, відповідь завершується з видимою помилкою замість тихої відповіді з `agents.defaults.model.fallbacks`. Це відрізняється від налаштованих типових значень і основних моделей завдань cron, які все ще можуть використовувати ланцюжки резервних варіантів.
|
||||
- `/model status` — це докладний перегляд (кандидати автентифікації та, якщо налаштовано, endpoint постачальника `baseUrl` + режим `api`).
|
||||
- `/model` одразу зберігає новий вибір сесії.
|
||||
- Якщо агент бездіє, наступний запуск одразу використовує нову модель.
|
||||
- Якщо запуск уже активний, OpenClaw позначає живе перемикання як очікуване й перезапускає в нову модель лише в чистій точці повторної спроби.
|
||||
- Якщо активність інструментів або виведення відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача.
|
||||
- Вибране користувачем посилання `/model` є суворим для цієї сесії: якщо вибраний provider/model недоступний, відповідь завершується видимою помилкою замість тихого використання `agents.defaults.model.fallbacks`. Це відрізняється від налаштованих стандартних значень і основних моделей cron-завдань, які все ще можуть використовувати резервні ланцюжки.
|
||||
- `/model status` — це детальне подання (кандидати автентифікації та, коли налаштовано, endpoint провайдера `baseUrl` + режим `api`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Розбір посилань">
|
||||
- Посилання на моделі розбираються поділом за **першим** `/`. Використовуйте `provider/model`, коли вводите `/model <ref>`.
|
||||
- Якщо ID моделі сам містить `/` (у стилі OpenRouter), потрібно включити префікс постачальника (приклад: `/model openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви пропустите постачальника, OpenClaw визначає введення в такому порядку:
|
||||
- Якщо сам ID моделі містить `/` (у стилі OpenRouter), потрібно включити префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви пропускаєте провайдера, OpenClaw розв’язує введення в такому порядку:
|
||||
1. збіг псевдоніма
|
||||
2. унікальний збіг налаштованого постачальника для цього точного ID моделі без префікса
|
||||
3. застарілий перехід до налаштованого типового постачальника — якщо цей постачальник більше не надає налаштовану типову модель, OpenClaw натомість переходить до першого налаштованого постачальника/моделі, щоб уникнути показу застарілого типового значення видаленого постачальника.
|
||||
2. унікальний збіг налаштованого провайдера для цього точного id моделі без префікса
|
||||
3. застарілий резервний перехід до налаштованого стандартного провайдера — якщо цей провайдер більше не надає налаштовану стандартну модель, OpenClaw натомість переходить до першого налаштованого provider/model, щоб не показувати застаріле стандартне значення вилученого провайдера.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -229,13 +229,13 @@ openclaw models image-fallbacks clear
|
||||
За замовчуванням показує налаштовані/доступні через автентифікацію моделі. Корисні прапорці:
|
||||
|
||||
<ParamField path="--all" type="boolean">
|
||||
Повний каталог. Містить рядки вбудованого статичного каталогу, що належать постачальникам, до налаштування автентифікації, тому перегляди лише для виявлення можуть показувати моделі, недоступні, доки ви не додасте відповідні облікові дані постачальника.
|
||||
Повний каталог. Містить статичні рядки каталогу вбудованих моделей, що належать провайдерам, ще до налаштування автентифікації, тому подання лише для виявлення можуть показувати моделі, недоступні, доки ви не додасте відповідні облікові дані провайдера.
|
||||
</ParamField>
|
||||
<ParamField path="--local" type="boolean">
|
||||
Лише локальні постачальники.
|
||||
Лише локальні провайдери.
|
||||
</ParamField>
|
||||
<ParamField path="--provider <id>" type="string">
|
||||
Фільтрувати за ID постачальника, наприклад `moonshot`. Відображувані мітки з інтерактивних засобів вибору не приймаються.
|
||||
Фільтрувати за ідентифікатором провайдера, наприклад `moonshot`. Відображувані мітки з інтерактивних вибирачів не приймаються.
|
||||
</ParamField>
|
||||
<ParamField path="--plain" type="boolean">
|
||||
Одна модель на рядок.
|
||||
@ -246,21 +246,21 @@ openclaw models image-fallbacks clear
|
||||
|
||||
### `models status`
|
||||
|
||||
Показує визначену основну модель, резервні варіанти, модель зображень і огляд автентифікації налаштованих провайдерів. Також показує статус завершення терміну дії OAuth для профілів, знайдених у сховищі автентифікації (за замовчуванням попереджає протягом 24 год). `--plain` друкує лише визначену основну модель.
|
||||
Показує визначену основну модель, резервні варіанти, модель зображень і огляд автентифікації налаштованих провайдерів. Також показує статус завершення терміну дії OAuth для профілів, знайдених у сховищі автентифікації (за замовчуванням попереджає за 24 год). `--plain` друкує лише визначену основну модель.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поведінка автентифікації та перевірки">
|
||||
<Accordion title="Поведінка автентифікації та перевірок">
|
||||
- Статус OAuth показується завжди (і включається у вивід `--json`). Якщо налаштований провайдер не має облікових даних, `models status` друкує розділ **Відсутня автентифікація**.
|
||||
- JSON містить `auth.oauth` (вікно попередження + профілі) і `auth.providers` (ефективна автентифікація для кожного провайдера, включно з обліковими даними з env). `auth.oauth` відображає лише стан профілів у сховищі автентифікації; провайдери лише з env там не з'являються.
|
||||
- Використовуйте `--check` для автоматизації (код виходу `1`, якщо відсутньо або прострочено, `2`, якщо термін дії незабаром завершується).
|
||||
- Використовуйте `--probe` для живих перевірок автентифікації; рядки перевірки можуть походити з профілів автентифікації, облікових даних env або `models.json`.
|
||||
- Якщо явний `auth.order.<provider>` пропускає збережений профіль, перевірка повідомляє `excluded_by_auth_order` замість спроби його використати. Якщо автентифікація існує, але для цього провайдера неможливо визначити модель для перевірки, перевірка повідомляє `status: no_model`.
|
||||
- JSON містить `auth.oauth` (вікно попередження + профілі) і `auth.providers` (ефективна автентифікація для кожного провайдера, включно з обліковими даними з env). `auth.oauth` показує лише стан профілів зі сховища автентифікації; провайдери лише з env там не з'являються.
|
||||
- Використовуйте `--check` для автоматизації (код виходу `1`, коли бракує або завершився термін дії, `2`, коли термін дії скоро завершиться).
|
||||
- Використовуйте `--probe` для live-перевірок автентифікації; рядки перевірок можуть надходити з профілів автентифікації, облікових даних env або `models.json`.
|
||||
- Якщо явний `auth.order.<provider>` пропускає збережений профіль, перевірка повідомляє `excluded_by_auth_order` замість спроби використати його. Якщо автентифікація існує, але для цього провайдера не можна визначити модель, придатну до перевірки, перевірка повідомляє `status: no_model`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
Вибір автентифікації залежить від провайдера й облікового запису. Для постійно активних хостів Gateway API-ключі зазвичай є найпередбачуванішими; також підтримуються повторне використання Claude CLI та наявні профілі Anthropic OAuth/токенів.
|
||||
Вибір автентифікації залежить від провайдера й облікового запису. Для постійно ввімкнених хостів Gateway ключі API зазвичай найпередбачуваніші; також підтримується повторне використання Claude CLI та наявні профілі Anthropic OAuth/token.
|
||||
</Note>
|
||||
|
||||
Приклад (Claude CLI):
|
||||
@ -275,7 +275,7 @@ openclaw models status
|
||||
`openclaw models scan` перевіряє **каталог безкоштовних моделей** OpenRouter і може додатково перевіряти моделі на підтримку інструментів і зображень.
|
||||
|
||||
<ParamField path="--no-probe" type="boolean">
|
||||
Пропустити живі перевірки (лише метадані).
|
||||
Пропустити live-перевірки (лише метадані).
|
||||
</ParamField>
|
||||
<ParamField path="--min-params <b>" type="number">
|
||||
Мінімальний розмір параметрів (у мільярдах).
|
||||
@ -290,14 +290,14 @@ openclaw models status
|
||||
Розмір списку резервних варіантів.
|
||||
</ParamField>
|
||||
<ParamField path="--set-default" type="boolean">
|
||||
Встановити `agents.defaults.model.primary` на перший вибраний варіант.
|
||||
Установити `agents.defaults.model.primary` на перший вибраний варіант.
|
||||
</ParamField>
|
||||
<ParamField path="--set-image" type="boolean">
|
||||
Встановити `agents.defaults.imageModel.primary` на перший вибраний варіант зображень.
|
||||
Установити `agents.defaults.imageModel.primary` на перший вибраний варіант зображень.
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
Каталог OpenRouter `/models` є публічним, тому сканування лише метаданих може показувати безкоштовних кандидатів без ключа. Перевірка та інференс усе одно потребують API-ключа OpenRouter (із профілів автентифікації або `OPENROUTER_API_KEY`). Якщо ключ недоступний, `openclaw models scan` повертається до виводу лише метаданих і залишає конфігурацію без змін. Використовуйте `--no-probe`, щоб явно запросити режим лише метаданих.
|
||||
Каталог OpenRouter `/models` є публічним, тому сканування лише метаданих може показувати безкоштовних кандидатів без ключа. Перевірки й інференс усе одно потребують ключа API OpenRouter (з профілів автентифікації або `OPENROUTER_API_KEY`). Якщо ключ недоступний, `openclaw models scan` повертається до виводу лише метаданих і залишає конфігурацію без змін. Використовуйте `--no-probe`, щоб явно запросити режим лише метаданих.
|
||||
</Note>
|
||||
|
||||
Результати сканування ранжуються за:
|
||||
@ -310,24 +310,24 @@ openclaw models status
|
||||
Вхідні дані:
|
||||
|
||||
- Список OpenRouter `/models` (фільтр `:free`)
|
||||
- Живі перевірки потребують API-ключа OpenRouter із профілів автентифікації або `OPENROUTER_API_KEY` (див. [Змінні середовища](/uk/help/environment))
|
||||
- Live-перевірки потребують ключа API OpenRouter з профілів автентифікації або `OPENROUTER_API_KEY` (див. [Змінні середовища](/uk/help/environment))
|
||||
- Необов'язкові фільтри: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
|
||||
- Елементи керування запитами/перевірками: `--timeout`, `--concurrency`
|
||||
|
||||
Коли живі перевірки виконуються в TUI, ви можете інтерактивно вибирати резервні варіанти. У неінтерактивному режимі передайте `--yes`, щоб прийняти типові значення. Результати лише метаданих є інформаційними; `--set-default` і `--set-image` потребують живих перевірок, щоб OpenClaw не налаштував непридатну до використання модель OpenRouter без ключа.
|
||||
Коли live-перевірки виконуються в TTY, ви можете інтерактивно вибирати резервні варіанти. У неінтерактивному режимі передайте `--yes`, щоб прийняти значення за замовчуванням. Результати лише за метаданими є інформаційними; `--set-default` і `--set-image` потребують live-перевірок, щоб OpenClaw не налаштував непридатну до використання модель OpenRouter без ключа.
|
||||
|
||||
## Реєстр моделей (`models.json`)
|
||||
|
||||
Користувацькі провайдери в `models.providers` записуються в `models.json` у каталозі агента (за замовчуванням `~/.openclaw/agents/<agentId>/agent/models.json`). Цей файл за замовчуванням об'єднується, якщо `models.mode` не встановлено на `replace`.
|
||||
Користувацькі провайдери в `models.providers` записуються в `models.json` у каталозі агента (за замовчуванням `~/.openclaw/agents/<agentId>/agent/models.json`). Цей файл за замовчуванням об'єднується, якщо `models.mode` не встановлено в `replace`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Пріоритет режиму об'єднання">
|
||||
Пріоритет режиму об'єднання для відповідних ID провайдерів:
|
||||
Пріоритет режиму об'єднання для відповідних ідентифікаторів провайдерів:
|
||||
|
||||
- Непорожній `baseUrl`, уже наявний в агентському `models.json`, має пріоритет.
|
||||
- Непорожній `apiKey` в агентському `models.json` має пріоритет лише тоді, коли цей провайдер не керується SecretRef у поточному контексті конфігурації/профілю автентифікації.
|
||||
- Значення `apiKey` провайдера, керованого SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів.
|
||||
- Значення заголовків провайдера, керованого SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань).
|
||||
- Непорожній `baseUrl`, уже наявний в агентському `models.json`, має перевагу.
|
||||
- Непорожній `apiKey` в агентському `models.json` має перевагу лише тоді, коли цей провайдер не керується SecretRef у поточному контексті конфігурації/профілю автентифікації.
|
||||
- Значення `apiKey` провайдера, керованого SecretRef, оновлюються з вихідних маркерів (`ENV_VAR_NAME` для посилань env, `secretref-managed` для посилань file/exec) замість збереження визначених секретів.
|
||||
- Значення заголовків провайдера, керованого SecretRef, оновлюються з вихідних маркерів (`secretref-env:ENV_VAR_NAME` для посилань env, `secretref-managed` для посилань file/exec).
|
||||
- Порожні або відсутні агентські `apiKey`/`baseUrl` повертаються до `models.providers` з конфігурації.
|
||||
- Інші поля провайдера оновлюються з конфігурації та нормалізованих даних каталогу.
|
||||
|
||||
@ -335,15 +335,15 @@ openclaw models status
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
Збереження маркерів спирається на джерело як авторитетне: OpenClaw записує маркери з активного знімка конфігурації джерела (до визначення), а не з визначених значень runtime-секретів. Це застосовується щоразу, коли OpenClaw регенерує `models.json`, зокрема в шляхах, керованих командами, як-от `openclaw agent`.
|
||||
Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка вихідної конфігурації (до визначення), а не з визначених значень runtime-секретів. Це застосовується щоразу, коли OpenClaw регенерує `models.json`, зокрема для шляхів, керованих командами, як-от `openclaw agent`.
|
||||
</Note>
|
||||
|
||||
## Пов'язане
|
||||
|
||||
- [Runtime агента](/uk/concepts/agent-runtimes) — PI, Codex та інші runtime циклу агента
|
||||
- [Середовища виконання агентів](/uk/concepts/agent-runtimes) — PI, Codex та інші середовища виконання агентського циклу
|
||||
- [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей
|
||||
- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделі зображень
|
||||
- [Відмовостійкість моделей](/uk/concepts/model-failover) — ланцюжки резервних варіантів
|
||||
- [Провайдери моделей](/uk/concepts/model-providers) — маршрутизація й автентифікація провайдерів
|
||||
- [Генерація музики](/uk/tools/music-generation) — конфігурація моделі музики
|
||||
- [Генерація відео](/uk/tools/video-generation) — конфігурація моделі відео
|
||||
- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделей зображень
|
||||
- [Відмовостійке перемикання моделей](/uk/concepts/model-failover) — ланцюжки резервних варіантів
|
||||
- [Провайдери моделей](/uk/concepts/model-providers) — маршрутизація провайдерів і автентифікація
|
||||
- [Генерація музики](/uk/tools/music-generation) — конфігурація моделей музики
|
||||
- [Генерація відео](/uk/tools/video-generation) — конфігурація моделей відео
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання або змінення міграцій doctor
|
||||
- Запровадження змін конфігурації, що порушують сумісність
|
||||
- Додавання або змінення діагностичних міграцій
|
||||
- Впровадження несумісних змін конфігурації
|
||||
sidebarTitle: Doctor
|
||||
summary: 'Команда doctor: перевірки справності, міграції конфігурації та кроки відновлення'
|
||||
summary: 'Команда doctor: перевірки працездатності, міграції конфігурації та кроки відновлення'
|
||||
title: Діагностика
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T21:50:52Z"
|
||||
generated_at: "2026-05-02T02:37:09Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: bbcac6787b25db196dfc6bf7afc44afc26e9b19d219106c407e32e1d090c2344
|
||||
source_hash: ff4ab00fd6a11588abe790350fe139bc49f61e688bcd741389dd63732aa4430c
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє справність і надає практичні кроки для відновлення.
|
||||
`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє справність і надає дієві кроки з відновлення.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -22,7 +22,7 @@ x-i18n:
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
### Безголові режими та режими автоматизації
|
||||
### Режими без інтерфейсу та автоматизації
|
||||
|
||||
<Tabs>
|
||||
<Tab title="--yes">
|
||||
@ -30,7 +30,7 @@ openclaw doctor
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Прийняти типові значення без запитів (зокрема кроки відновлення перезапуску/служби/пісочниці, коли це застосовно).
|
||||
Приймати типові значення без запитів (зокрема кроки перезапуску/служби/відновлення sandbox, коли застосовно).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair">
|
||||
@ -38,7 +38,7 @@ openclaw doctor
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски там, де це безпечно).
|
||||
Застосувати рекомендовані відновлення без запитів (відновлення + перезапуски там, де це безпечно).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair --force">
|
||||
@ -46,7 +46,7 @@ openclaw doctor
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
Також застосувати агресивні виправлення (перезаписує користувацькі конфігурації супервізора).
|
||||
Також застосувати агресивні відновлення (перезаписує власні конфігурації supervisor).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--non-interactive">
|
||||
@ -54,7 +54,7 @@ openclaw doctor
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
Запустити без запитів і застосувати лише безпечні міграції (нормалізацію конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службою/пісочницею, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично після виявлення.
|
||||
Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/служби/sandbox, які потребують підтвердження людини. Застарілі міграції стану запускаються автоматично, коли їх виявлено.
|
||||
|
||||
</Tab>
|
||||
<Tab title="--deep">
|
||||
@ -62,7 +62,7 @@ openclaw doctor
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
Сканувати системні служби на наявність додаткових інсталяцій gateway (launchd/systemd/schtasks).
|
||||
Сканувати системні служби на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -76,118 +76,118 @@ cat ~/.openclaw/openclaw.json
|
||||
## Що він робить (коротко)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Справність, UI та оновлення">
|
||||
<Accordion title="Справність, інтерфейс і оновлення">
|
||||
- Необов’язкове попереднє оновлення для git-інсталяцій (лише інтерактивно).
|
||||
- Перевірка актуальності протоколу UI (перезбирає Control UI, коли схема протоколу новіша).
|
||||
- Перевірка актуальності протоколу інтерфейсу (перезбирає інтерфейс керування, коли схема протоколу новіша).
|
||||
- Перевірка справності + запит на перезапуск.
|
||||
- Підсумок стану Skills (придатні/відсутні/заблоковані) і стан Plugin.
|
||||
- Зведення стану Skills (придатні/відсутні/заблоковані) і стан Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Конфігурація та міграції">
|
||||
- Нормалізація конфігурації для застарілих значень.
|
||||
- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
|
||||
- Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
|
||||
- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP.
|
||||
- Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Попередження про затінення Codex OAuth (`models.providers.openai-codex`).
|
||||
- Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth.
|
||||
- Попередження allowlist Plugin/інструментів, коли `plugins.allow` є обмежувальним, але політика інструментів усе ще запитує wildcard або інструменти, що належать Plugin.
|
||||
- Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp).
|
||||
- Міграція застарілого стану на диску (сеанси/каталог агента/автентифікація WhatsApp).
|
||||
- Міграція застарілих ключів контракту маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля доставки/корисного навантаження верхнього рівня, `provider` у корисному навантаженні, прості fallback-завдання Webhook `notify: true`).
|
||||
- Міграція застарілої політики runtime агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`.
|
||||
- Очищення застарілої конфігурації Plugin, коли плагіни увімкнені; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною конфігурацією ізоляції та зберігаються.
|
||||
- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля доставки/payload верхнього рівня, payload `provider`, прості резервні завдання Webhook `notify: true`).
|
||||
- Міграція застарілої політики виконання агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`.
|
||||
- Очищення застарілої конфігурації Plugin, коли plugins увімкнені; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною конфігурацією стримування та зберігаються.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Стан і цілісність">
|
||||
- Перевірка файлів блокування сесій і очищення застарілих блокувань.
|
||||
- Відновлення транскриптів сесій для дубльованих гілок переписування промптів, створених ураженими збірками 2026.4.24.
|
||||
- Виявлення tombstone для відновлення після перезапуску завислого субагента з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб запуск не продовжував трактувати дочірній процес як перерваний перезапуском.
|
||||
- Перевірки цілісності стану та дозволів (сесії, транскрипти, каталог стану).
|
||||
- Перевірка файлів блокування сеансів і очищення застарілих блокувань.
|
||||
- Відновлення транскриптів сеансів для дубльованих гілок переписування prompt, створених ураженими збірками 2026.4.24.
|
||||
- Виявлення tombstone для відновлення після перезапуску завислого subagent, з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб запуск не продовжував вважати дочірній процес перерваним під час перезапуску.
|
||||
- Перевірки цілісності стану та дозволів (сеанси, транскрипти, каталог стану).
|
||||
- Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску.
|
||||
- Справність автентифікації моделі: перевіряє завершення строку дії OAuth, може оновлювати токени, що скоро спливають, і повідомляє про cooldown/вимкнені стани auth-profile.
|
||||
- Справність автентифікації моделей: перевіряє завершення терміну дії OAuth, може оновлювати токени, що скоро завершаться, і повідомляє про стани cooldown/вимкнення auth-profile.
|
||||
- Виявлення додаткового каталогу робочого простору (`~/openclaw`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Gateway, служби та супервізори">
|
||||
- Відновлення образу пісочниці, коли пісочницю увімкнено.
|
||||
- Міграція застарілої служби та виявлення додаткових gateway.
|
||||
<Accordion title="Gateway, служби та supervisors">
|
||||
- Відновлення образу sandbox, коли sandboxing увімкнено.
|
||||
- Міграція застарілої служби та виявлення додаткових Gateway.
|
||||
- Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`).
|
||||
- Перевірки runtime Gateway (службу встановлено, але вона не запущена; кешована мітка launchd).
|
||||
- Попередження стану каналів (перевіряються з запущеного gateway).
|
||||
- Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим відновленням.
|
||||
- Очищення середовища вбудованого проксі для служб gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час інсталяції або оновлення.
|
||||
- Перевірки виконання Gateway (службу встановлено, але не запущено; кешована мітка launchd).
|
||||
- Попередження стану каналів (перевіряються з запущеного Gateway).
|
||||
- Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням.
|
||||
- Очищення середовища вбудованого proxy для служб Gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення.
|
||||
- Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи менеджера версій).
|
||||
- Діагностика конфлікту порту Gateway (типово `18789`).
|
||||
- Діагностика конфліктів портів Gateway (типово `18789`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Автентифікація, безпека та спарювання">
|
||||
- Попередження безпеки для відкритих політик DM.
|
||||
- Перевірки автентифікації Gateway для режиму локального токена (пропонує згенерувати токен, коли джерела токена немає; не перезаписує конфігурації токена SecretRef).
|
||||
- Виявлення проблем зі спарюванням пристрою (очікувані запити першого спарювання, очікувані підвищення ролі/обсягу, застаріле розходження кешу локального device-token і розходження автентифікації paired-record).
|
||||
- Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена немає; не перезаписує конфігурації SecretRef токена).
|
||||
- Виявлення проблем зі спарюванням пристроїв (очікувані запити першого спарювання, очікувані підвищення ролі/обсягу, дрейф застарілого локального кешу device-token і дрейф автентифікації paired-record).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Робочий простір і shell">
|
||||
- Перевірка systemd linger у Linux.
|
||||
- Перевірка розміру bootstrap-файлу робочого простору (попередження про усічення/наближення до ліміту для контекстних файлів).
|
||||
- Перевірка стану shell completion і автоінсталяція/оновлення.
|
||||
- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, ключ віддаленого API або бінарний файл QMD).
|
||||
- Перевірки інсталяції з вихідного коду (невідповідність pnpm workspace, відсутні UI-активи, відсутній бінарний файл tsx).
|
||||
- Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів).
|
||||
- Перевірка стану shell completion і автоматичне встановлення/оновлення.
|
||||
- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, ключ віддаленого API або binary QMD).
|
||||
- Перевірки інсталяції з вихідного коду (невідповідність робочого простору pnpm, відсутні UI assets, відсутній binary tsx).
|
||||
- Записує оновлену конфігурацію + метадані майстра.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Зворотне заповнення та скидання UI Dreams
|
||||
## Зворотне заповнення та скидання інтерфейсу Dreams
|
||||
|
||||
Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи gateway у стилі doctor, але вони **не** є частиною CLI-відновлення/міграції `openclaw doctor`.
|
||||
Сцена Dreams в інтерфейсі керування містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи Gateway у стилі doctor, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`.
|
||||
|
||||
Що вони роблять:
|
||||
|
||||
- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує оборотні записи зворотного заповнення в `DREAMS.md`.
|
||||
- **Reset** видаляє лише ці позначені diary-записи зворотного заповнення з `DREAMS.md`.
|
||||
- **Clear Grounded** видаляє лише підготовлені короткострокові записи only-grounded, які надійшли з історичного відтворення й ще не накопичили live recall або daily support.
|
||||
- **Reset** видаляє лише ці позначені записи щоденника зворотного заповнення з `DREAMS.md`.
|
||||
- **Clear Grounded** видаляє лише staged короткострокові записи тільки grounded, які походять з історичного replay і ще не накопичили live recall або daily support.
|
||||
|
||||
Що вони **не** роблять самі по собі:
|
||||
Чого вони **не** роблять самі по собі:
|
||||
|
||||
- вони не редагують `MEMORY.md`
|
||||
- вони не запускають повні міграції doctor
|
||||
- вони не готують grounded-кандидатів автоматично в live short-term promotion store, якщо ви явно не запустите staged CLI path спочатку
|
||||
- вони не додають grounded candidates автоматично в live short-term promotion store, якщо ви спочатку явно не запустите staged CLI path
|
||||
|
||||
Якщо ви хочете, щоб grounded historical replay впливав на звичайний deep promotion lane, натомість використовуйте CLI-потік:
|
||||
Якщо ви хочете, щоб grounded historical replay впливав на звичайну deep promotion lane, натомість використовуйте потік CLI:
|
||||
|
||||
```bash
|
||||
openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
```
|
||||
|
||||
Це готує grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду.
|
||||
Це додає grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду.
|
||||
|
||||
## Детальна поведінка та обґрунтування
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="0. Необов’язкове оновлення (git-інсталяції)">
|
||||
Якщо це git checkout і doctor запускається інтерактивно, він пропонує оновитися (fetch/rebase/build) перед запуском doctor.
|
||||
Якщо це git checkout і doctor працює інтерактивно, він пропонує оновити (fetch/rebase/build) перед запуском doctor.
|
||||
</Accordion>
|
||||
<Accordion title="1. Нормалізація конфігурації">
|
||||
Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх у поточну схему.
|
||||
Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми.
|
||||
|
||||
Це охоплює застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдера.
|
||||
Це включає застарілі пласкі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдерів.
|
||||
|
||||
Doctor також попереджає, коли `plugins.allow` не порожній, а політика інструментів використовує
|
||||
wildcard або записи інструментів, що належать Plugin. `tools.allow: ["*"]` відповідає лише інструментам
|
||||
із Plugin, які фактично завантажуються; це не обходить ексклюзивний
|
||||
із plugins, які фактично завантажуються; він не обходить ексклюзивний
|
||||
allowlist Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Міграції застарілих ключів конфігурації">
|
||||
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися й просять вас запустити `openclaw doctor`.
|
||||
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися та просять виконати `openclaw doctor`.
|
||||
|
||||
Doctor:
|
||||
|
||||
- Пояснить, які застарілі ключі знайдено.
|
||||
- Покаже застосовану міграцію.
|
||||
- Перепише `~/.openclaw/openclaw.json` з оновленою схемою.
|
||||
- Перезапише `~/.openclaw/openclaw.json` оновленою схемою.
|
||||
|
||||
Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. Міграції сховища завдань Cron обробляються через `openclaw doctor --fix`.
|
||||
Gateway також автоматично запускає міграції doctor під час запуску, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації відновлюються без ручного втручання. Міграції сховища cron-завдань обробляє `openclaw doctor --fix`.
|
||||
|
||||
Поточні міграції:
|
||||
|
||||
@ -196,7 +196,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
|
||||
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
|
||||
- `routing.queue` → `messages.queue`
|
||||
- `routing.bindings` → верхньорівневий `bindings`
|
||||
- `routing.bindings` → верхньорівневі `bindings`
|
||||
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
|
||||
- застарілі `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
|
||||
- `routing.agentToAgent` → `tools.agentToAgent`
|
||||
@ -212,87 +212,87 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
|
||||
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- Для каналів із іменованими `accounts`, але залишковими верхньорівневими значеннями каналу для одного облікового запису, перемістіть ці значення в межах облікового запису до підвищеного облікового запису, вибраного для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/стандартну ціль)
|
||||
- Для каналів з іменованими `accounts`, але залишковими верхньорівневими значеннями каналу для одного облікового запису, перемістіть ці значення з областю дії облікового запису в підвищений обліковий запис, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль)
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- видаліть `agents.defaults.llm`; використовуйте `models.providers.<id>.timeoutSeconds` для тайм-аутів повільних провайдерів/моделей
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- видаліть `browser.relayBindHost` (застаріле налаштування реле розширення)
|
||||
- застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск Gateway також пропускає провайдерів, у яких `api` встановлено на майбутнє або невідоме значення enum, замість аварійного завершення в закритому режимі)
|
||||
- видаліть `browser.relayBindHost` (застаріле налаштування ретрансляції розширення)
|
||||
- застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (під час запуску Gateway також пропускає провайдерів, у яких `api` задано майбутнім або невідомим значенням enum, замість аварійно завершуватися у закритому режимі)
|
||||
|
||||
Попередження doctor також містять настанови щодо стандартного облікового запису для каналів із кількома обліковими записами:
|
||||
Попередження doctor також містять настанови щодо типового облікового запису для багатооблікових каналів:
|
||||
|
||||
- Якщо налаштовано два або більше записів `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис.
|
||||
- Якщо `channels.<channel>.defaultAccount` задано як невідомий ID облікового запису, doctor попереджає про це й перелічує налаштовані ID облікових записів.
|
||||
- Якщо `channels.<channel>.defaultAccount` задано як невідомий ID облікового запису, doctor попереджає і перелічує налаштовані ID облікових записів.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2b. Перевизначення провайдерів OpenCode">
|
||||
<Accordion title="2b. OpenCode provider overrides">
|
||||
Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі до неправильного API або обнулити витрати. Doctor попереджає, щоб ви могли видалити перевизначення й відновити маршрутизацію API та витрати для кожної моделі.
|
||||
</Accordion>
|
||||
<Accordion title="2c. Міграція браузера та готовність Chrome MCP">
|
||||
Якщо ваша конфігурація браузера досі вказує на видалений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості:
|
||||
<Accordion title="2c. Browser migration and Chrome MCP readiness">
|
||||
Якщо ваша конфігурація браузера все ще вказує на видалений шлях розширення Chrome, doctor нормалізує її до поточної моделі локального для хоста підключення Chrome MCP:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` стає `"existing-session"`
|
||||
- `browser.relayBindHost` видаляється
|
||||
|
||||
Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`:
|
||||
Doctor також перевіряє локальний для хоста шлях Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`:
|
||||
|
||||
- перевіряє, чи встановлено Google Chrome на тому самому хості для стандартних профілів автоматичного підключення
|
||||
- перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
|
||||
- перевіряє, чи Google Chrome встановлено на тому самому хості для типових профілів автоматичного підключення
|
||||
- перевіряє виявлену версію Chrome і попереджає, коли вона нижча за Chrome 144
|
||||
- нагадує ввімкнути віддалене налагодження на сторінці інспектування браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`)
|
||||
|
||||
Doctor не може ввімкнути налаштування на боці Chrome замість вас. Chrome MCP на локальному хості все ще потребує:
|
||||
Doctor не може ввімкнути налаштування на боці Chrome за вас. Локальний для хоста Chrome MCP все ще потребує:
|
||||
|
||||
- браузер на основі Chromium 144+ на хості Gateway/Node
|
||||
- браузер, запущений локально
|
||||
- віддалене налагодження, увімкнене в цьому браузері
|
||||
- схвалення першого запиту згоди на підключення в браузері
|
||||
- браузера на базі Chromium 144+ на хості gateway/node
|
||||
- локально запущеного браузера
|
||||
- увімкненого віддаленого налагодження в цьому браузері
|
||||
- підтвердження першого запиту згоди на підключення в браузері
|
||||
|
||||
Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або профілю raw CDP.
|
||||
Готовність тут стосується лише локальних передумов підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або raw CDP-профілю.
|
||||
|
||||
Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2d. Передумови OAuth TLS">
|
||||
Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку авторизації OpenAI, щоб переконатися, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить настанови з виправлення для конкретної платформи. На macOS із Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний.
|
||||
<Accordion title="2d. OAuth TLS prerequisites">
|
||||
Коли налаштовано OAuth-профіль OpenAI Codex, doctor перевіряє кінцеву точку авторизації OpenAI, щоб переконатися, що локальний TLS-стек Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить настанови з виправлення для конкретної платформи. На macOS із Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний.
|
||||
</Accordion>
|
||||
<Accordion title="2e. Перевизначення провайдера Codex OAuth">
|
||||
Якщо ви раніше додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту поряд із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не викликають цього попередження.
|
||||
<Accordion title="2e. Codex OAuth provider overrides">
|
||||
Якщо раніше ви додали застарілі транспортні налаштування OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування разом із Codex OAuth, щоб ви могли видалити або переписати застаріле транспортне перевизначення й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не спричиняють це попередження.
|
||||
</Accordion>
|
||||
<Accordion title="2f. Попередження маршрутів Plugin Codex">
|
||||
Коли ввімкнено вбудований Plugin Codex, doctor також перевіряє, чи основні посилання на моделі `openai-codex/*` досі вирішуються через стандартний runner PI. Ця комбінація чинна, коли вам потрібна автентифікація Codex OAuth/підписки через PI, але її легко сплутати з нативним app-server harness Codex. Doctor попереджає й вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
<Accordion title="2f. Codex plugin route warnings">
|
||||
Коли ввімкнено вбудований Codex Plugin, doctor також перевіряє, чи основні посилання на моделі `openai-codex/*` досі розв’язуються через типовий PI runner. Ця комбінація коректна, коли ви хочете автентифікацію Codex OAuth/передплати через PI, але її легко сплутати з нативним harness сервера застосунку Codex. Doctor попереджає і вказує на явну форму сервера застосунку: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
|
||||
Doctor не виправляє це автоматично, оскільки обидва маршрути чинні:
|
||||
Doctor не виправляє це автоматично, бо обидва маршрути коректні:
|
||||
|
||||
- `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw."
|
||||
- `openai/*` + `runtime: "codex"` означає "запустити вбудований хід через нативний Codex app-server."
|
||||
- `/codex ...` означає "керувати нативною розмовою Codex або прив'язати її з чату."
|
||||
- `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx."
|
||||
- `openai-codex/*` + PI означає «використовувати автентифікацію Codex OAuth/передплати через звичайний runner OpenClaw».
|
||||
- `openai/*` + `agentRuntime.id: "codex"` означає «виконати вбудований turn через нативний сервер застосунку Codex».
|
||||
- `/codex ...` означає «керувати нативною розмовою Codex із чату або прив’язати її».
|
||||
- `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx».
|
||||
|
||||
Якщо з'являється попередження, виберіть потрібний маршрут і вручну відредагуйте конфігурацію. Залиште попередження без змін, коли PI Codex OAuth є навмисним.
|
||||
Якщо попередження з’являється, виберіть задуманий маршрут і відредагуйте конфігурацію вручну. Залиште попередження без змін, коли PI Codex OAuth є навмисним.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. Міграції застарілого стану (структура диска)">
|
||||
Doctor може мігрувати старіші структури на диску до поточної структури:
|
||||
<Accordion title="3. Legacy state migrations (disk layout)">
|
||||
Doctor може мігрувати старіші дискові структури до поточної структури:
|
||||
|
||||
- Сховище сеансів + транскрипти:
|
||||
- з `~/.openclaw/sessions/` до `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Каталог агента:
|
||||
- з `~/.openclaw/agent/` до `~/.openclaw/agents/<agentId>/agent/`
|
||||
- Стан автентифікації WhatsApp (Baileys):
|
||||
- із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`)
|
||||
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (стандартний ID облікового запису: `default`)
|
||||
- із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`)
|
||||
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (типовий ID облікового запису: `default`)
|
||||
|
||||
Ці міграції виконуються за принципом найкращого зусилля та є ідемпотентними; doctor виводитиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапляли в шлях для кожного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера/карти провайдерів Talk тепер порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють повторні no-op зміни `doctor --fix`.
|
||||
Ці міграції виконуються за принципом best-effort і є ідемпотентними; doctor виводитиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапили в шлях для відповідного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера talk/карти провайдерів тепер порівнює за структурною рівністю, тому diff лише через порядок ключів більше не спричиняє повторних no-op змін `doctor --fix`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3a. Міграції застарілих маніфестів Plugin">
|
||||
Doctor сканує всі встановлені маніфести plugin на наявність застарілих верхньорівневих ключів можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх в об'єкт `contracts` і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже має такі самі значення, застарілий ключ видаляється без дублювання даних.
|
||||
<Accordion title="3a. Legacy plugin manifest migrations">
|
||||
Doctor сканує всі встановлені маніфести plugin на наявність застарілих верхньорівневих ключів можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх в об’єкт `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже має ті самі значення, застарілий ключ видаляється без дублювання даних.
|
||||
</Accordion>
|
||||
<Accordion title="3b. Міграції застарілого сховища Cron">
|
||||
Doctor також перевіряє сховище завдань cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо перевизначено) на старі форми завдань, які планувальник усе ще приймає для сумісності.
|
||||
<Accordion title="3b. Legacy cron store migrations">
|
||||
Doctor також перевіряє сховище cron-завдань (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які scheduler досі приймає для сумісності.
|
||||
|
||||
Поточні очищення cron включають:
|
||||
|
||||
@ -300,201 +300,201 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- `schedule.cron` → `schedule.expr`
|
||||
- верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- верхньорівневі поля доставки (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- псевдоніми доставки payload `provider` → явний `delivery.channel`
|
||||
- прості застарілі резервні webhook-завдання `notify: true` → явний `delivery.mode="webhook"` із `delivery.to=cron.webhook`
|
||||
- псевдоніми доставки `provider` у payload → явний `delivery.channel`
|
||||
- прості застарілі fallback-завдання webhook `notify: true` → явне `delivery.mode="webhook"` з `delivery.to=cron.webhook`
|
||||
|
||||
Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом доставки, відмінним від webhook, doctor попереджає й залишає це завдання для ручного перегляду.
|
||||
Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий fallback notify з наявним режимом доставки не через webhook, doctor попереджає і залишає це завдання для ручного перегляду.
|
||||
|
||||
На Linux doctor також попереджає, коли crontab користувача досі викликає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`. Цей скрипт локального хоста не підтримується поточним OpenClaw і може записувати хибні повідомлення `Gateway inactive` до `~/.openclaw/logs/whatsapp-health.log`, коли cron не може досягти користувацької шини systemd. Видаліть застарілий запис crontab за допомогою `crontab -e`; використовуйте `openclaw channels status --probe`, `openclaw doctor` і `openclaw gateway status` для поточних перевірок справності.
|
||||
На Linux doctor також попереджає, коли crontab користувача досі викликає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`. Цей локальний для хоста скрипт не підтримується поточним OpenClaw і може записувати хибні повідомлення `Gateway inactive` у `~/.openclaw/logs/whatsapp-health.log`, коли cron не може дістатися до шини користувача systemd. Видаліть застарілий запис crontab за допомогою `crontab -e`; використовуйте `openclaw channels status --probe`, `openclaw doctor` і `openclaw gateway status` для поточних перевірок справності.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3c. Очищення блокувань сеансів">
|
||||
Лікар сканує кожен каталог сеансів агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старіше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку та вказує повторно запустити з `--fix`.
|
||||
Doctor сканує кожен каталог сеансу агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку та вказує повторно запустити з `--fix`.
|
||||
</Accordion>
|
||||
<Accordion title="3d. Виправлення гілки транскрипту сеансу">
|
||||
Лікар сканує JSONL-файли сеансів агента на дубльовану форму гілки, створену помилкою переписування транскрипту підказки 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw плюс активний сусідній хід із тією самою видимою підказкою користувача. У режимі `--fix` / `--repair` лікар створює резервну копію кожного ураженого файла поруч з оригіналом і переписує транскрипт на активну гілку, щоб історія Gateway і читачі пам’яті більше не бачили дубльовані ходи.
|
||||
<Accordion title="3d. Виправлення гілки транскрипта сеансу">
|
||||
Doctor сканує JSONL-файли сеансів агентів на дубльовану форму гілки, створену помилкою переписування транскрипта промпта 2026.4.24: покинутий хід користувача з внутрішнім контекстом виконання OpenClaw плюс активний сусідній елемент із тим самим видимим промптом користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного зачепленого файлу поруч з оригіналом і переписує транскрипт на активну гілку, щоб історія gateway і читачі пам’яті більше не бачили дубльованих ходів.
|
||||
</Accordion>
|
||||
<Accordion title="4. Перевірки цілісності стану (збереження сеансів, маршрутизація та безпека)">
|
||||
Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій деінде).
|
||||
Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій деінде).
|
||||
|
||||
Лікар перевіряє:
|
||||
Doctor перевіряє:
|
||||
|
||||
- **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані.
|
||||
- **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку `chown`, коли виявлено невідповідність власника/групи).
|
||||
- **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розв’язується всередині iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи з синхронізацією можуть спричиняти повільніше I/O та перегони блокувань/синхронізації.
|
||||
- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розв’язується до джерела монтування `mmcblk*`, оскільки випадкове I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів та облікових даних.
|
||||
- **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення збоїв `ENOENT`.
|
||||
- **Невідповідність транскрипту**: попереджає, коли в недавніх записах сеансів бракує файлів транскрипту.
|
||||
- **Основний сеанс "1-line JSONL"**: позначає випадки, коли основний транскрипт має лише один рядок (історія не накопичується).
|
||||
- **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує деінде (історія може розділитися між інсталяціями).
|
||||
- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, лікар нагадує запустити його на віддаленому хості (стан живе там).
|
||||
- **Дозволи конфігураційного файла**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує посилити дозволи до `600`.
|
||||
- **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розміщується під iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, тому що шляхи, підтримувані синхронізацією, можуть спричиняти повільніший I/O і перегони блокувань/синхронізації.
|
||||
- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розміщується на джерелі монтування `mmcblk*`, тому що випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів та облікових даних.
|
||||
- **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення аварій `ENOENT`.
|
||||
- **Невідповідність транскрипта**: попереджає, коли нещодавні записи сеансів мають відсутні файли транскриптів.
|
||||
- **Головний сеанс "1-line JSONL"**: позначає випадок, коли головний транскрипт має лише один рядок (історія не накопичується).
|
||||
- **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділятися між інсталяціями).
|
||||
- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (стан живе там).
|
||||
- **Дозволи конфігураційного файлу**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує обмежити до `600`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. Стан автентифікації моделі (закінчення OAuth)">
|
||||
Лікар перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли токени скоро закінчаться або вже закінчилися, і може оновити їх, коли це безпечно. Якщо OAuth/токен-профіль Anthropic застарів, він пропонує ключ API Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення.
|
||||
<Accordion title="5. Стан авторизації моделей (закінчення терміну OAuth)">
|
||||
Doctor перевіряє профілі OAuth у сховищі авторизації, попереджає, коли термін дії токенів скоро спливає або вже сплив, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/токена застарів, він пропонує ключ Anthropic API або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення.
|
||||
|
||||
Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або провайдер каже увійти знову), лікар повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати.
|
||||
Коли оновлення OAuth остаточно не вдається (наприклад `refresh_token_reused`, `invalid_grant` або провайдер просить увійти знову), doctor повідомляє, що потрібна повторна авторизація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати.
|
||||
|
||||
Лікар також повідомляє про профілі автентифікації, які тимчасово непридатні через:
|
||||
Doctor також повідомляє про профілі авторизації, які тимчасово непридатні через:
|
||||
|
||||
- короткі періоди очікування (ліміти швидкості/тайм-аути/збої автентифікації)
|
||||
- триваліші вимкнення (збої білінгу/кредитів)
|
||||
- короткі періоди очікування (ліміти частоти/таймаути/збої авторизації)
|
||||
- довші вимкнення (збої білінгу/кредитів)
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="6. Перевірка моделі hooks">
|
||||
Якщо `hooks.gmail.model` задано, лікар перевіряє посилання на модель за каталогом і списком дозволених та попереджає, коли його неможливо розв’язати або воно заборонене.
|
||||
<Accordion title="6. Перевірка моделі хуків">
|
||||
Якщо `hooks.gmail.model` задано, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли його не вдасться розв’язати або воно заборонене.
|
||||
</Accordion>
|
||||
<Accordion title="7. Виправлення образу пісочниці">
|
||||
Коли пісочницю ввімкнено, лікар перевіряє Docker-образи та пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній.
|
||||
Коли пісочницю ввімкнено, doctor перевіряє образи Docker і пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній.
|
||||
</Accordion>
|
||||
<Accordion title="7b. Очищення встановлення Plugin">
|
||||
Лікар видаляє застарілий створений OpenClaw проміжний стан залежностей Plugin у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення та локальні для пакета залишки від попереднього коду виправлення залежностей вбудованих Plugin.
|
||||
<Accordion title="7b. Очищення інсталяції Plugin">
|
||||
Doctor видаляє застарілий згенерований OpenClaw проміжний стан залежностей Plugin у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу інсталяції та локальне сміття пакета з попереднього коду виправлення залежностей bundled-plugin.
|
||||
|
||||
Лікар також може повторно встановити налаштовані завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр plugin не може їх знайти. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; установлення plugin лишається явною роботою doctor/install/update.
|
||||
Doctor також може перевстановити налаштовані завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр Plugin не може їх знайти. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; інсталяції Plugin залишаються явною роботою doctor/install/update.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8. Міграції сервісу Gateway і підказки з очищення">
|
||||
Лікар виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw з використанням поточного порту gateway. Він також може сканувати додаткові сервіси, схожі на gateway, і друкувати підказки з очищення. Сервіси OpenClaw gateway, названі за профілем, вважаються повноцінними і не позначаються як "додаткові".
|
||||
Doctor виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw з використанням поточного порту gateway. Він також може сканувати додаткові gateway-подібні сервіси та друкувати підказки з очищення. Сервіси OpenClaw gateway з іменами профілів вважаються повноцінними й не позначаються як "extra."
|
||||
|
||||
У Linux, якщо сервіс gateway рівня користувача відсутній, але сервіс OpenClaw gateway системного рівня існує, лікар не встановлює другий сервіс рівня користувача автоматично. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, а потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний супервізор керує життєвим циклом gateway.
|
||||
На Linux, якщо сервіс gateway рівня користувача відсутній, але існує системний сервіс OpenClaw gateway, doctor не встановлює автоматично другий сервіс рівня користувача. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний супервізор керує життєвим циклом gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8b. Міграція Startup Matrix">
|
||||
Коли обліковий запис каналу Matrix має очікувану або придатну до дії міграцію застарілого стану, лікар (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує міграційні кроки з найкращим зусиллям: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, і запуск продовжується. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається.
|
||||
Коли обліковий запис каналу Matrix має очікувану або придатну до дії міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім запускає кроки міграції best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається.
|
||||
</Accordion>
|
||||
<Accordion title="8c. Сполучення пристроїв і дрейф автентифікації">
|
||||
Тепер лікар перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки стану.
|
||||
<Accordion title="8c. Спарювання пристроїв і дрейф авторизації">
|
||||
Doctor тепер перевіряє стан спарювання пристроїв як частину звичайної перевірки справності.
|
||||
|
||||
Що він повідомляє:
|
||||
|
||||
- очікувані запити першого сполучення
|
||||
- очікувані підвищення ролей для вже сполучених пристроїв
|
||||
- очікувані підвищення scope для вже сполучених пристроїв
|
||||
- виправлення невідповідності публічного ключа, коли ідентифікатор пристрою все ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом
|
||||
- сполучені записи, у яких відсутній активний токен для затвердженої ролі
|
||||
- сполучені токени, чиї scopes відхиляються за межі затвердженої базової лінії сполучення
|
||||
- локально кешовані записи device-token для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope
|
||||
- очікувані запити на перше спарювання
|
||||
- очікувані підвищення ролі для вже спарених пристроїв
|
||||
- очікувані підвищення scope для вже спарених пристроїв
|
||||
- виправлення невідповідності публічного ключа, коли id пристрою все ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом
|
||||
- спарені записи, яким бракує активного токена для затвердженої ролі
|
||||
- спарені токени, чиї scopes відхиляються від затвердженої базової лінії спарювання
|
||||
- локальні кешовані записи токенів пристроїв для поточної машини, що передують ротації токена на боці gateway або містять застарілі метадані scope
|
||||
|
||||
Лікар не затверджує запити на сполучення автоматично і не обертає токени пристроїв автоматично. Натомість він друкує точні наступні кроки:
|
||||
Doctor не схвалює автоматично запити на спарювання й не ротує автоматично токени пристроїв. Натомість він друкує точні наступні кроки:
|
||||
|
||||
- перегляньте очікувані запити за допомогою `openclaw devices list`
|
||||
- затвердьте точний запит за допомогою `openclaw devices approve <requestId>`
|
||||
- оберніть свіжий токен за допомогою `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- видаліть і повторно затвердьте застарілий запис за допомогою `openclaw devices remove <deviceId>`
|
||||
- перевірте очікувані запити за допомогою `openclaw devices list`
|
||||
- схваліть точний запит за допомогою `openclaw devices approve <requestId>`
|
||||
- згенеруйте свіжий токен ротацією за допомогою `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- видаліть і повторно схваліть застарілий запис за допомогою `openclaw devices remove <deviceId>`
|
||||
|
||||
Це закриває поширену прогалину "already paired but still getting pairing required": тепер лікар відрізняє перше сполучення від очікуваних підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою.
|
||||
Це закриває поширену прогалину "already paired but still getting pairing required": doctor тепер відрізняє перше спарювання від очікуваних підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="9. Попередження безпеки">
|
||||
Лікар видає попередження, коли провайдер відкритий для DM без списку дозволених або коли політику налаштовано небезпечно.
|
||||
Doctor виводить попередження, коли провайдер відкритий для DM без allowlist або коли політику налаштовано небезпечним способом.
|
||||
</Accordion>
|
||||
<Accordion title="10. systemd linger (Linux)">
|
||||
Якщо запущено як користувацький сервіс systemd, лікар гарантує, що lingering увімкнено, щоб gateway залишався активним після виходу з системи.
|
||||
Якщо запущено як користувацький сервіс systemd, doctor переконується, що linger увімкнено, щоб gateway залишався активним після виходу з системи.
|
||||
</Accordion>
|
||||
<Accordion title="11. Стан робочого простору (skills, plugins і застарілі каталоги)">
|
||||
Лікар друкує підсумок стану робочого простору для агента за замовчуванням:
|
||||
Doctor друкує підсумок стану робочого простору для стандартного агента:
|
||||
|
||||
- **Стан Skills**: рахує skills, які відповідають вимогам, мають відсутні вимоги та заблоковані списком дозволених.
|
||||
- **Стан Skills**: рахує придатні, з відсутніми вимогами та заблоковані allowlist skills.
|
||||
- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поруч із поточним робочим простором.
|
||||
- **Стан Plugin**: рахує ввімкнені/вимкнені/помилкові plugins; перелічує ідентифікатори plugin для будь-яких помилок; повідомляє можливості bundle plugin.
|
||||
- **Стан Plugin**: рахує ввімкнені/вимкнені/помилкові plugins; перелічує ID Plugin для будь-яких помилок; повідомляє можливості bundle plugin.
|
||||
- **Попередження сумісності Plugin**: позначає plugins, які мають проблеми сумісності з поточним runtime.
|
||||
- **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, видані реєстром plugin.
|
||||
- **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, виведені реєстром Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="11b. Розмір bootstrap-файла">
|
||||
Лікар перевіряє, чи bootstrap-файли робочого простору (наприклад, `AGENTS.md`, `CLAUDE.md` або інші вставлені контекстні файли) наближаються до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файла сирі та вставлені кількості символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість вставлених символів як частку загального бюджету. Коли файли обрізано або вони наближаються до ліміту, лікар друкує поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`.
|
||||
<Accordion title="11b. Розмір файлу bootstrap">
|
||||
Doctor перевіряє, чи файли bootstrap робочого простору (наприклад `AGENTS.md`, `CLAUDE.md` або інші вставлені контекстні файли) близькі до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу необроблену кількість символів проти вставленої, відсоток усічення, причину усічення (`max/file` або `max/total`) і загальну кількість вставлених символів як частку від загального бюджету. Коли файли усічено або вони близькі до ліміту, doctor друкує поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`.
|
||||
</Accordion>
|
||||
<Accordion title="11d. Очищення застарілого channel plugin">
|
||||
Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє висячу конфігурацію в області каналу, яка посилалася на цей plugin: записи `channels.<id>`, цілі heartbeat, що називали канал, і перевизначення `agents.*.models["<channel>/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив’язатися до нього.
|
||||
<Accordion title="11d. Очищення застарілого Plugin каналу">
|
||||
Коли `openclaw doctor --fix` видаляє відсутній Plugin каналу, він також видаляє завислу конфігурацію в області каналу, яка посилалася на цей Plugin: записи `channels.<id>`, цілі heartbeat, що називали канал, і перевизначення `agents.*.models["<channel>/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив’язатися до нього.
|
||||
</Accordion>
|
||||
<Accordion title="11c. Автодоповнення оболонки">
|
||||
Лікар перевіряє, чи встановлено автодоповнення табуляцією для поточної оболонки (zsh, bash, fish або PowerShell):
|
||||
Doctor перевіряє, чи встановлено автодоповнення клавішею Tab для поточної оболонки (zsh, bash, fish або PowerShell):
|
||||
|
||||
- Якщо профіль оболонки використовує повільний динамічний шаблон автодоповнення (`source <(openclaw completion ...)`), лікар оновлює його до швидшого варіанта з кешованим файлом.
|
||||
- Якщо автодоповнення налаштовано в профілі, але файл кешу відсутній, лікар автоматично повторно генерує кеш.
|
||||
- Якщо автодоповнення взагалі не налаштовано, лікар пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`).
|
||||
- Якщо профіль оболонки використовує повільний динамічний шаблон доповнення (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта кешованого файлу.
|
||||
- Якщо доповнення налаштовано в профілі, але файл кешу відсутній, doctor автоматично регенерує кеш.
|
||||
- Якщо доповнення взагалі не налаштовано, doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`).
|
||||
|
||||
Запустіть `openclaw completion --write-state`, щоб повторно згенерувати кеш вручну.
|
||||
Запустіть `openclaw completion --write-state`, щоб вручну регенерувати кеш.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12. Перевірки автентифікації Gateway (локальний токен)">
|
||||
Лікар перевіряє готовність автентифікації локального gateway токеном.
|
||||
<Accordion title="12. Перевірки авторизації Gateway (локальний токен)">
|
||||
Doctor перевіряє готовність авторизації локального gateway за токеном.
|
||||
|
||||
- Якщо режим токена потребує токен, а джерела токена немає, лікар пропонує згенерувати його.
|
||||
- Якщо `gateway.auth.token` керується SecretRef, але недоступний, лікар попереджає і не перезаписує його відкритим текстом.
|
||||
- `openclaw doctor --generate-gateway-token` примусово генерує лише тоді, коли не налаштовано SecretRef для токена.
|
||||
- Якщо режим токена потребує токена, а джерела токена немає, doctor пропонує згенерувати його.
|
||||
- Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом.
|
||||
- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12b. Виправлення з урахуванням SecretRef лише для читання">
|
||||
Деякі потоки виправлення мають перевіряти налаштовані облікові дані без послаблення runtime-поведінки швидкого збою.
|
||||
<Accordion title="12b. Виправлення з урахуванням SecretRef у режимі лише читання">
|
||||
Деякі потоки виправлення мають перевіряти налаштовані облікові дані, не послаблюючи поведінку швидкого збою runtime.
|
||||
|
||||
- `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації.
|
||||
- Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, коли вони доступні.
|
||||
- Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, лікар повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або помилкового повідомлення про відсутній токен.
|
||||
- `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації.
|
||||
- Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані bot, коли вони доступні.
|
||||
- Якщо токен bot Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або помилкового повідомлення, що токен відсутній.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="13. Перевірка стану Gateway + перезапуск">
|
||||
Лікар виконує перевірку стану і пропонує перезапустити gateway, коли він виглядає несправним.
|
||||
<Accordion title="13. Перевірка справності Gateway + перезапуск">
|
||||
Doctor запускає перевірку справності та пропонує перезапустити gateway, коли він виглядає несправним.
|
||||
</Accordion>
|
||||
<Accordion title="13b. Готовність пошуку в пам’яті">
|
||||
Лікар перевіряє, чи налаштований провайдер embedding для пошуку в пам’яті готовий для агента за замовчуванням. Поведінка залежить від налаштованого backend і провайдера:
|
||||
<Accordion title="13b. Готовність пошуку пам’яті">
|
||||
Doctor перевіряє, чи налаштований провайдер embedding для пошуку пам’яті готовий для стандартного агента. Поведінка залежить від налаштованого backend і провайдера:
|
||||
|
||||
- **Бекенд QMD**: перевіряє, чи доступний і чи може запускатися виконуваний файл `qmd`. Якщо ні, виводить інструкції з виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файлу.
|
||||
- **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаної URL-адреси віддаленої/завантажуваної моделі. Якщо відсутній, пропонує перейти на віддаленого провайдера.
|
||||
- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє наявність API-ключа в середовищі або сховищі автентифікації. Якщо ключ відсутній, виводить дієві підказки для виправлення.
|
||||
- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, потім пробує кожного віддаленого провайдера в порядку автоматичного вибору.
|
||||
- **Бекенд QMD**: перевіряє, чи доступний і чи може запускатися двійковий файл `qmd`. Якщо ні, виводить інструкції з виправлення, зокрема npm-пакет і варіант ручного шляху до двійкового файла.
|
||||
- **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаної віддаленої/завантажуваної URL-адреси моделі. Якщо її немає, пропонує перейти на віддаленого провайдера.
|
||||
- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки для виправлення.
|
||||
- **Автопровайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого провайдера в порядку автовибору.
|
||||
|
||||
Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-які розбіжності. Doctor не запускає новий ping вбудовувань на типовому шляху; використовуйте команду глибокого статусу пам’яті, коли потрібна жива перевірка провайдера.
|
||||
Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-які розбіжності. Doctor не запускає нову перевірку embedding за стандартним шляхом; використовуйте команду глибокого статусу пам’яті, коли потрібна жива перевірка провайдера.
|
||||
|
||||
Використовуйте `openclaw memory status --deep`, щоб перевірити готовність вбудовувань під час виконання.
|
||||
Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="14. Попередження про статус каналів">
|
||||
Якщо Gateway справний, doctor запускає перевірку статусу каналів і повідомляє попередження із запропонованими виправленнями.
|
||||
<Accordion title="14. Попередження про стан каналів">
|
||||
Якщо Gateway справний, doctor запускає перевірку стану каналів і повідомляє попередження із запропонованими виправленнями.
|
||||
</Accordion>
|
||||
<Accordion title="15. Аудит і відновлення конфігурації супервізора">
|
||||
Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі типові значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, рекомендує оновлення й може переписати файл служби/завдання до поточних типових значень.
|
||||
Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі стандартні значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, рекомендує оновлення і може переписати файл служби/завдання до поточних стандартних значень.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `openclaw doctor` запитує підтвердження перед переписуванням конфігурації супервізора.
|
||||
- `openclaw doctor --yes` приймає типові запити на відновлення.
|
||||
- `openclaw doctor --yes` приймає стандартні запити на відновлення.
|
||||
- `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів.
|
||||
- `openclaw doctor --repair --force` перезаписує користувацькі конфігурації супервізора.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби Gateway. Він усе ще повідомляє про стан служби й виконує відновлення, не пов’язані зі службою, але пропускає install/start/restart/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній супервізор.
|
||||
- У Linux doctor не переписує метадані команди/точки входу, доки відповідний systemd-модуль Gateway активний. Він також ігнорує неактивні додаткові модулі, схожі на Gateway і не застарілі, під час пошуку дубльованих служб, щоб супутні файли служб не створювали зайвий шум очищення.
|
||||
- `openclaw doctor --repair --force` перезаписує власні конфігурації супервізора.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби Gateway. Він усе ще повідомляє про стан служби й запускає відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, бо цим життєвим циклом керує зовнішній супервізор.
|
||||
- У Linux doctor не переписує метадані команди/точки входу, доки відповідний systemd-модуль Gateway активний. Він також ігнорує неактивні додаткові модулі, схожі на Gateway і не застарілі, під час пошуку дубльованих служб, щоб супровідні файли служб не створювали шум очищення.
|
||||
- Якщо автентифікація токеном вимагає токен і `gateway.auth.token` керується SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища служби супервізора.
|
||||
- Doctor виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела виконання, а не з визначення супервізора.
|
||||
- Doctor виявляє, коли команда служби досі фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт.
|
||||
- Якщо автентифікація токеном вимагає токен, а налаштований SecretRef токена не розв’язано, doctor блокує шлях встановлення/відновлення з дієвими інструкціями.
|
||||
- Doctor виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела runtime, а не з визначення супервізора.
|
||||
- Doctor виявляє, коли команда служби все ще фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт.
|
||||
- Якщо автентифікація токеном вимагає токен, а налаштований SecretRef токена не розв’язується, doctor блокує шлях встановлення/відновлення з практичними вказівками.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде задано явно.
|
||||
- Для користувацьких systemd-модулів Linux перевірки дрейфу токена doctor тепер враховують як джерела `Environment=`, так і `EnvironmentFile=` під час порівняння метаданих автентифікації служби.
|
||||
- Відновлення служби doctor відмовляються переписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файла OpenClaw, коли конфігурацію востаннє було записано новішою версією. Див. [усунення неполадок Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- Для користувацьких systemd-модулів Linux перевірки розбіжності токенів у doctor тепер враховують джерела `Environment=` і `EnvironmentFile=` під час порівняння метаданих автентифікації служби.
|
||||
- Відновлення служби doctor відмовляються переписувати, зупиняти або перезапускати службу Gateway зі старішого двійкового файла OpenClaw, якщо конфігурацію востаннє записала новіша версія. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="16. Діагностика середовища виконання Gateway і порту">
|
||||
Doctor перевіряє середовище виконання служби (PID, останній статус виходу) і попереджає, коли служба встановлена, але фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже працює, SSH-тунель).
|
||||
<Accordion title="16. Діагностика runtime Gateway і портів">
|
||||
Doctor перевіряє runtime служби (PID, останній статус виходу) і попереджає, коли службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти портів на порту Gateway (стандартно `18789`) і повідомляє ймовірні причини (Gateway уже запущено, SSH-тунель).
|
||||
</Accordion>
|
||||
<Accordion title="17. Найкращі практики середовища виконання Gateway">
|
||||
Doctor попереджає, коли служба Gateway працює на Bun або шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, оскільки служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує мігрувати на системне встановлення Node, коли воно доступне (Homebrew/apt/choco).
|
||||
<Accordion title="17. Найкращі практики runtime Gateway">
|
||||
Doctor попереджає, коли служба Gateway працює на Bun або на шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, бо служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, коли воно доступне (Homebrew/apt/choco).
|
||||
|
||||
Нововстановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні користувацькі каталоги bin, але припущені резервні каталоги менеджерів версій записуються в PATH служби лише тоді, коли ці каталоги існують на диску. Це узгоджує згенерований PATH супервізора з тим самим аудитом мінімального PATH, який doctor запускає пізніше.
|
||||
Нововстановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але припущені резервні каталоги менеджерів версій записуються в PATH служби лише тоді, коли ці каталоги існують на диску. Це узгоджує згенерований PATH супервізора з тим самим аудитом мінімального PATH, який doctor запускає пізніше.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="18. Запис конфігурації та метадані майстра">
|
||||
Doctor зберігає будь-які зміни конфігурації та ставить позначку в метаданих майстра, щоб зафіксувати запуск doctor.
|
||||
Doctor зберігає всі зміни конфігурації та ставить мітку метаданих майстра, щоб зафіксувати запуск doctor.
|
||||
</Accordion>
|
||||
<Accordion title="19. Поради щодо робочого простору (резервна копія + система пам’яті)">
|
||||
Doctor пропонує систему пам’яті робочого простору, коли її бракує, і виводить пораду щодо резервної копії, якщо робочий простір ще не перебуває під керуванням git.
|
||||
<Accordion title="19. Поради щодо робочої області (резервне копіювання + система пам’яті)">
|
||||
Doctor пропонує систему пам’яті робочої області, коли її немає, і виводить пораду щодо резервного копіювання, якщо робоча область ще не перебуває під git.
|
||||
|
||||
Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури робочого простору та резервного копіювання в git (рекомендовано приватний GitHub або GitLab).
|
||||
Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника зі структури робочої області та резервного копіювання git (рекомендовано приватний GitHub або GitLab).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Runbook Gateway](/uk/gateway)
|
||||
- [Усунення неполадок Gateway](/uk/gateway/troubleshooting)
|
||||
- [Регламент Gateway](/uk/gateway)
|
||||
- [Усунення несправностей Gateway](/uk/gateway/troubleshooting)
|
||||
|
||||
@ -1,54 +1,54 @@
|
||||
---
|
||||
read_when:
|
||||
- Нове встановлення, зависання під час первинного налаштування або помилки першого запуску
|
||||
- Вибір автентифікації та підписок провайдерів
|
||||
- Не вдається отримати доступ до docs.openclaw.ai, не вдається відкрити панель керування, встановлення зависло
|
||||
- Нове встановлення, зависання онбордингу або помилки першого запуску
|
||||
- Вибір автентифікації та підписок провайдера
|
||||
- Немає доступу до docs.openclaw.ai, не вдається відкрити панель керування, встановлення зависло
|
||||
sidebarTitle: First-run FAQ
|
||||
summary: 'Поширені запитання: швидкий старт і налаштування першого запуску — встановлення, підключення, автентифікація, підписки, початкові збої'
|
||||
title: 'Поширені запитання: початкове налаштування'
|
||||
summary: 'Поширені запитання: швидкий старт і налаштування першого запуску — встановлення, онбординг, автентифікація, підписки, початкові збої'
|
||||
title: 'Поширені запитання: налаштування під час першого запуску'
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:15:32Z"
|
||||
generated_at: "2026-05-02T02:37:15Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 959e5c8a94cce6369af84d3d1e252dbfb22acb5891ac1d8b64722c4c40679e65
|
||||
source_hash: 469fbd24fea69d91c5b0408dff9c7d7b2382f9c59430a1d5331cb5dcabdce295
|
||||
source_path: help/faq-first-run.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Q&A для швидкого старту й першого запуску. Для повсякденних операцій, моделей, автентифікації, сесій
|
||||
Швидкий старт і Q&A для першого запуску. Для щоденних операцій, моделей, автентифікації, сесій
|
||||
і усунення несправностей див. основний [FAQ](/uk/help/faq).
|
||||
|
||||
## Швидкий старт і налаштування першого запуску
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Я застряг, найшвидший спосіб розблокуватися">
|
||||
Використовуйте локального AI-агента, який може **бачити вашу машину**. Це значно ефективніше, ніж питати
|
||||
в Discord, бо більшість випадків "я застряг" є **проблемами локальної конфігурації або середовища**,
|
||||
Використайте локального AI-агента, який може **бачити вашу машину**. Це значно ефективніше, ніж питати
|
||||
в Discord, бо більшість випадків "я застряг" є **локальними проблемами конфігурації або середовища**,
|
||||
які віддалені помічники не можуть перевірити.
|
||||
|
||||
- **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)
|
||||
- **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/)
|
||||
|
||||
Ці інструменти можуть читати репозиторій, запускати команди, переглядати журнали й допомагати виправляти
|
||||
налаштування на рівні машини (PATH, сервіси, дозволи, файли автентифікації). Дайте їм **повний checkout вихідного коду** через
|
||||
hackable (git) install:
|
||||
налаштування на рівні машини (PATH, служби, дозволи, файли автентифікації). Надайте їм **повний checkout вихідного коду** через
|
||||
встановлення hackable (git):
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
|
||||
```
|
||||
|
||||
Це встановлює OpenClaw **з git checkout**, тож агент може читати код і документацію та
|
||||
міркувати про саме ту версію, яку ви запускаєте. Пізніше ви завжди можете повернутися до стабільної версії,
|
||||
Це встановлює OpenClaw **з git checkout**, тож агент може читати код + документацію і
|
||||
міркувати про точну версію, яку ви запускаєте. Пізніше завжди можна повернутися до stable,
|
||||
повторно запустивши інсталятор без `--install-method git`.
|
||||
|
||||
Порада: попросіть агента **спланувати й проконтролювати** виправлення (крок за кроком), а потім виконати лише
|
||||
необхідні команди. Так зміни залишаються невеликими й простішими для аудиту.
|
||||
Порада: попросіть агента **спланувати й супроводжувати** виправлення (крок за кроком), а потім виконати лише
|
||||
необхідні команди. Так зміни лишаються невеликими й простішими для аудиту.
|
||||
|
||||
Якщо ви знайдете справжню помилку або виправлення, будь ласка, створіть GitHub issue або надішліть PR:
|
||||
Якщо ви виявили справжню помилку або виправлення, будь ласка, створіть GitHub issue або надішліть PR:
|
||||
[https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues)
|
||||
[https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls)
|
||||
|
||||
Почніть із цих команд (діліться виводом, коли просите допомоги):
|
||||
Почніть із цих команд (діліться виводом, коли просите про допомогу):
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -58,34 +58,34 @@ x-i18n:
|
||||
|
||||
Що вони роблять:
|
||||
|
||||
- `openclaw status`: швидкий знімок стану Gateway/агента + базова конфігурація.
|
||||
- `openclaw status`: короткий знімок стану gateway/агента + базова конфігурація.
|
||||
- `openclaw models status`: перевіряє автентифікацію провайдера + доступність моделей.
|
||||
- `openclaw doctor`: перевіряє й виправляє поширені проблеми конфігурації/стану.
|
||||
- `openclaw doctor`: перевіряє і виправляє типові проблеми конфігурації/стану.
|
||||
|
||||
Інші корисні CLI-перевірки: `openclaw status --all`, `openclaw logs --follow`,
|
||||
Інші корисні перевірки CLI: `openclaw status --all`, `openclaw logs --follow`,
|
||||
`openclaw gateway status`, `openclaw health --verbose`.
|
||||
|
||||
Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламано](#first-60-seconds-if-something-is-broken).
|
||||
Документація встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating).
|
||||
Документація зі встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Heartbeat постійно пропускається. Що означають причини пропуску?">
|
||||
Поширені причини пропуску Heartbeat:
|
||||
Типові причини пропуску Heartbeat:
|
||||
|
||||
- `quiet-hours`: поза налаштованим вікном активних годин
|
||||
- `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожній/тільки заголовковий каркас
|
||||
- `no-tasks-due`: режим завдань `HEARTBEAT.md` активний, але жоден з інтервалів завдань ще не настав
|
||||
- `alerts-disabled`: уся видимість heartbeat вимкнена (`showOk`, `showAlerts` і `useIndicator` усі вимкнені)
|
||||
- `no-tasks-due`: режим завдань `HEARTBEAT.md` активний, але інтервали жодного завдання ще не настали
|
||||
- `alerts-disabled`: усю видимість Heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені)
|
||||
|
||||
У режимі завдань часові мітки виконання просуваються лише після завершення справжнього запуску Heartbeat.
|
||||
Пропущені запуски не позначають завдання як завершені.
|
||||
У режимі завдань часові позначки настання просуваються лише після завершення
|
||||
справжнього запуску Heartbeat. Пропущені запуски не позначають завдання як виконані.
|
||||
|
||||
Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація та завдання](/uk/automation).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Рекомендований спосіб установити й налаштувати OpenClaw">
|
||||
<Accordion title="Рекомендований спосіб встановити й налаштувати OpenClaw">
|
||||
Репозиторій рекомендує запуск із вихідного коду та використання onboarding:
|
||||
|
||||
```bash
|
||||
@ -93,9 +93,9 @@ x-i18n:
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
Майстер також може автоматично зібрати UI-ресурси. Після onboarding ви зазвичай запускаєте Gateway на порту **18789**.
|
||||
Майстер також може автоматично зібрати ресурси UI. Після onboarding ви зазвичай запускаєте Gateway на порту **18789**.
|
||||
|
||||
З вихідного коду (для контриб'юторів/розробників):
|
||||
З вихідного коду (контриб'ютори/розробка):
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
@ -106,90 +106,90 @@ x-i18n:
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
Якщо глобального встановлення ще немає, запустіть це через `pnpm openclaw onboard`.
|
||||
Якщо у вас ще немає глобального встановлення, запустіть це через `pnpm openclaw onboard`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як відкрити dashboard після onboarding?">
|
||||
Майстер відкриває ваш браузер із чистою (без токена) URL-адресою dashboard одразу після onboarding, а також друкує посилання в підсумку. Тримайте цю вкладку відкритою; якщо вона не запустилася, скопіюйте/вставте надруковану URL-адресу на тій самій машині.
|
||||
<Accordion title="Як відкрити панель керування після onboarding?">
|
||||
Майстер відкриває ваш браузер із чистою (нетокенізованою) URL-адресою панелі керування одразу після onboarding, а також друкує посилання в підсумку. Тримайте цю вкладку відкритою; якщо вона не запустилася, скопіюйте/вставте надруковану URL-адресу на тій самій машині.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як автентифікувати dashboard на localhost і віддалено?">
|
||||
<Accordion title="Як автентифікувати панель керування на localhost і віддалено?">
|
||||
**Localhost (та сама машина):**
|
||||
|
||||
- Відкрийте `http://127.0.0.1:18789/`.
|
||||
- Якщо запитується автентифікація shared-secret, вставте налаштований токен або пароль у налаштування Control UI.
|
||||
- Якщо запитується автентифікація через shared-secret, вставте налаштований токен або пароль у налаштування Control UI.
|
||||
- Джерело токена: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`).
|
||||
- Джерело пароля: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`).
|
||||
- Якщо shared secret ще не налаштовано, згенеруйте токен за допомогою `openclaw doctor --generate-gateway-token`.
|
||||
|
||||
**Не на localhost:**
|
||||
|
||||
- **Tailscale Serve** (рекомендовано): залиште bind loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https://<magicdns>/`. Якщо `gateway.auth.allowTailscale` має значення `true`, identity headers задовольняють автентифікацію Control UI/WebSocket (без вставленого shared secret, передбачається довірений хост gateway); HTTP API все ще потребують автентифікації shared-secret, якщо ви навмисно не використовуєте private-ingress `none` або HTTP-автентифікацію trusted-proxy.
|
||||
Невдалі одночасні спроби автентифікації Serve від того самого клієнта серіалізуються перед тим, як обмежувач failed-auth їх записує, тож друга невдала повторна спроба вже може показати `retry later`.
|
||||
- **Tailnet bind**: запустіть `openclaw gateway --bind tailnet --token "<token>"` (або налаштуйте автентифікацію паролем), відкрийте `http://<tailscale-ip>:18789/`, потім вставте відповідний shared secret у налаштування dashboard.
|
||||
- **Identity-aware reverse proxy**: тримайте Gateway за trusted proxy, налаштуйте `gateway.auth.mode: "trusted-proxy"`, потім відкрийте URL проксі. Same-host loopback proxies потребують явного `gateway.auth.trustedProxy.allowLoopback = true`.
|
||||
- **SSH-тунель**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, потім відкрийте `http://127.0.0.1:18789/`. Автентифікація shared-secret усе ще застосовується через тунель; вставте налаштований токен або пароль, якщо буде запит.
|
||||
- **Tailscale Serve** (рекомендовано): лишайте прив'язку до loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https://<magicdns>/`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентичності задовольняють автентифікацію Control UI/WebSocket (без вставленого shared secret, передбачається довірений хост Gateway); HTTP API все одно потребують автентифікації через shared-secret, якщо ви свідомо не використовуєте private-ingress `none` або HTTP-автентифікацію trusted-proxy.
|
||||
Невдалі паралельні спроби автентифікації Serve від одного клієнта серіалізуються до того, як лімітатор failed-auth їх записує, тому друга невдала повторна спроба вже може показати `retry later`.
|
||||
- **Прив'язка Tailnet**: запустіть `openclaw gateway --bind tailnet --token "<token>"` (або налаштуйте автентифікацію паролем), відкрийте `http://<tailscale-ip>:18789/`, а потім вставте відповідний shared secret у налаштуваннях панелі керування.
|
||||
- **Identity-aware reverse proxy**: тримайте Gateway за довіреним проксі, налаштуйте `gateway.auth.mode: "trusted-proxy"`, потім відкрийте URL проксі. Проксі same-host loopback потребують явного `gateway.auth.trustedProxy.allowLoopback = true`.
|
||||
- **SSH-тунель**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, потім відкрийте `http://127.0.0.1:18789/`. Автентифікація через shared-secret усе одно застосовується через тунель; вставте налаштований токен або пароль, якщо буде запит.
|
||||
|
||||
Див. [Dashboard](/uk/web/dashboard) і [Вебповерхні](/uk/web) щодо режимів bind та деталей автентифікації.
|
||||
Див. [Панель керування](/uk/web/dashboard) і [Вебповерхні](/uk/web) щодо режимів прив'язки й деталей автентифікації.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чому є дві конфігурації exec approval для chat approvals?">
|
||||
Вони керують різними рівнями:
|
||||
<Accordion title="Чому є дві конфігурації підтвердження exec для підтверджень у чаті?">
|
||||
Вони керують різними шарами:
|
||||
|
||||
- `approvals.exec`: пересилає запити approval до chat destinations
|
||||
- `channels.<channel>.execApprovals`: змушує цей канал діяти як native approval client для exec approvals
|
||||
- `approvals.exec`: пересилає запити підтвердження до чат-призначень
|
||||
- `channels.<channel>.execApprovals`: змушує цей канал діяти як нативний клієнт підтвердження для exec-підтверджень
|
||||
|
||||
Host exec policy усе ще є справжнім шлюзом approval. Chat config лише керує тим, де
|
||||
з'являються запити approval і як люди можуть на них відповідати.
|
||||
Політика host exec усе одно є справжнім шлюзом підтвердження. Конфігурація чату лише керує тим, де
|
||||
з'являються запити підтвердження і як люди можуть на них відповідати.
|
||||
|
||||
У більшості налаштувань вам **не** потрібні обидві:
|
||||
У більшості налаштувань вам **не** потрібні обидва:
|
||||
|
||||
- Якщо chat уже підтримує команди й відповіді, same-chat `/approve` працює через спільний шлях.
|
||||
- Якщо підтримуваний native channel може безпечно визначити approvers, OpenClaw тепер автоматично вмикає DM-first native approvals, коли `channels.<channel>.execApprovals.enabled` не задано або має значення `"auto"`.
|
||||
- Коли доступні native approval cards/buttons, цей native UI є основним шляхом; агент має включати ручну команду `/approve` лише якщо результат інструмента каже, що chat approvals недоступні або ручний approval є єдиним шляхом.
|
||||
- Використовуйте `approvals.exec` лише коли запити також потрібно пересилати в інші чати або явні ops rooms.
|
||||
- Використовуйте `channels.<channel>.execApprovals.target: "channel"` або `"both"` лише коли ви явно хочете, щоб запити approval публікувалися назад у вихідну кімнату/тему.
|
||||
- Plugin approvals знову окремі: вони за замовчуванням використовують same-chat `/approve`, необов'язкове пересилання `approvals.plugin`, і лише деякі native channels додатково зберігають plugin-approval-native handling.
|
||||
- Якщо чат уже підтримує команди й відповіді, same-chat `/approve` працює через спільний шлях.
|
||||
- Якщо підтримуваний нативний канал може безпечно визначати approvers, OpenClaw тепер автоматично вмикає DM-first нативні підтвердження, коли `channels.<channel>.execApprovals.enabled` не задано або має значення `"auto"`.
|
||||
- Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve` лише якщо результат інструмента каже, що чат-підтвердження недоступні або ручне підтвердження є єдиним шляхом.
|
||||
- Використовуйте `approvals.exec` лише коли запити також потрібно пересилати в інші чати або явні ops-кімнати.
|
||||
- Використовуйте `channels.<channel>.execApprovals.target: "channel"` або `"both"` лише коли ви явно хочете, щоб запити підтвердження публікувалися назад у початкову кімнату/тему.
|
||||
- Plugin-підтвердження знову окремі: вони використовують same-chat `/approve` за замовчуванням, необов'язкове пересилання `approvals.plugin`, і лише деякі нативні канали зберігають plugin-approval-native обробку поверх цього.
|
||||
|
||||
Коротко: forwarding призначений для маршрутизації, native client config — для багатшого channel-specific UX.
|
||||
Коротко: пересилання потрібне для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу.
|
||||
Див. [Exec Approvals](/uk/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Який runtime мені потрібен?">
|
||||
Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендовано** для Gateway.
|
||||
<Accordion title="Яке середовище виконання потрібне?">
|
||||
Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендований** для Gateway.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи працює це на Raspberry Pi?">
|
||||
Так. Gateway легкий - документація вказує **512MB-1GB RAM**, **1 core** і приблизно **500MB**
|
||||
Так. Gateway легковаговий - документація вказує **512MB-1GB RAM**, **1 ядро** і приблизно **500MB**
|
||||
диска як достатні для особистого використання, а також зазначає, що **Raspberry Pi 4 може його запускати**.
|
||||
|
||||
Якщо вам потрібен додатковий запас (журнали, медіа, інші сервіси), **рекомендовано 2GB**, але це
|
||||
Якщо потрібен додатковий запас (журнали, медіа, інші служби), **рекомендовано 2GB**, але це
|
||||
не жорсткий мінімум.
|
||||
|
||||
Порада: невеликий Pi/VPS може хостити Gateway, а ви можете спарити **nodes** на ноутбуці/телефоні для
|
||||
локального екрана/камери/canvas або виконання команд. Див. [Nodes](/uk/nodes).
|
||||
Порада: невеликий Pi/VPS може розміщувати Gateway, а ви можете під'єднати **вузли** на ноутбуці/телефоні для
|
||||
локального екрана/камери/canvas або виконання команд. Див. [Вузли](/uk/nodes).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Є поради для встановлення на Raspberry Pi?">
|
||||
Коротко: це працює, але очікуйте шорсткостей.
|
||||
Коротко: це працює, але очікуйте шорсткі місця.
|
||||
|
||||
- Використовуйте **64-bit** OS і тримайте Node >= 22.
|
||||
- Віддавайте перевагу **hackable (git) install**, щоб бачити журнали й швидко оновлюватися.
|
||||
- Почніть без channels/skills, потім додавайте їх по одному.
|
||||
- Якщо натрапите на дивні проблеми з binary, зазвичай це проблема **ARM compatibility**.
|
||||
- Почніть без каналів/Skills, потім додавайте їх по одному.
|
||||
- Якщо натрапите на дивні проблеми з бінарними файлами, зазвичай це проблема **ARM-сумісності**.
|
||||
|
||||
Документація: [Linux](/uk/platforms/linux), [Встановлення](/uk/install).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Застрягло на wake up my friend / onboarding не hatch. Що робити?">
|
||||
Цей екран залежить від того, чи Gateway доступний і автентифікований. TUI також надсилає
|
||||
"Wake up, my friend!" автоматично під час першого hatch. Якщо ви бачите цей рядок **без відповіді**
|
||||
й tokens залишаються на 0, агент ніколи не запускався.
|
||||
<Accordion title="Застрягло на wake up my friend / onboarding не вилуплюється. Що тепер?">
|
||||
Цей екран залежить від того, чи Gateway доступний і автентифікований. TUI також автоматично надсилає
|
||||
"Wake up, my friend!" під час першого hatch. Якщо ви бачите цей рядок **без відповіді**
|
||||
і токени лишаються на 0, агент ніколи не запускався.
|
||||
|
||||
1. Перезапустіть Gateway:
|
||||
|
||||
@ -212,74 +212,74 @@ x-i18n:
|
||||
```
|
||||
|
||||
Якщо Gateway віддалений, переконайтеся, що тунель/з'єднання Tailscale активне і що UI
|
||||
спрямований на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote).
|
||||
вказує на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можу я перенести своє налаштування на нову машину (Mac mini), не проходячи onboarding заново?">
|
||||
Так. Скопіюйте **каталог стану** й **робочу область**, потім один раз запустіть Doctor. Це
|
||||
збереже вашого бота "точно таким самим" (пам'ять, історію сесій, автентифікацію та стан каналу),
|
||||
якщо ви скопіюєте **обидва** розташування:
|
||||
Так. Скопіюйте **каталог стану** і **робочий простір**, потім один раз запустіть Doctor. Це
|
||||
збереже вашого бота "точно таким самим" (memory, історія сесій, автентифікація і стан каналів),
|
||||
якщо скопіювати **обидві** локації:
|
||||
|
||||
1. Установіть OpenClaw на новій машині.
|
||||
1. Встановіть OpenClaw на новій машині.
|
||||
2. Скопіюйте `$OPENCLAW_STATE_DIR` (за замовчуванням: `~/.openclaw`) зі старої машини.
|
||||
3. Скопіюйте свою робочу область (за замовчуванням: `~/.openclaw/workspace`).
|
||||
4. Запустіть `openclaw doctor` і перезапустіть сервіс Gateway.
|
||||
3. Скопіюйте свій робочий простір (за замовчуванням: `~/.openclaw/workspace`).
|
||||
4. Запустіть `openclaw doctor` і перезапустіть службу Gateway.
|
||||
|
||||
Це зберігає конфігурацію, профілі автентифікації, облікові дані WhatsApp, сесії та пам'ять. Якщо ви в
|
||||
remote mode, пам'ятайте, що gateway host володіє session store і workspace.
|
||||
Це зберігає конфігурацію, профілі автентифікації, облікові дані WhatsApp, сесії та memory. Якщо ви в
|
||||
віддаленому режимі, пам'ятайте, що хост gateway володіє сховищем сесій і робочим простором.
|
||||
|
||||
**Важливо:** якщо ви лише commit/push свою робочу область на GitHub, ви створюєте резервну копію
|
||||
**memory + bootstrap files**, але **не** історії сесій або автентифікації. Вони живуть
|
||||
у `~/.openclaw/` (наприклад, `~/.openclaw/agents/<agentId>/sessions/`).
|
||||
**Важливо:** якщо ви лише commit/push свій робочий простір у GitHub, ви створюєте резервну копію
|
||||
**memory + bootstrap-файлів**, але **не** історії сесій або автентифікації. Вони живуть
|
||||
у `~/.openclaw/` (наприклад `~/.openclaw/agents/<agentId>/sessions/`).
|
||||
|
||||
Дотичне: [Міграція](/uk/install/migrating), [Де речі зберігаються на диску](#where-things-live-on-disk),
|
||||
[Робоча область агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor),
|
||||
[Remote mode](/uk/gateway/remote).
|
||||
Пов'язане: [Міграція](/uk/install/migrating), [Де речі живуть на диску](#where-things-live-on-disk),
|
||||
[Робочий простір агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor),
|
||||
[Віддалений режим](/uk/gateway/remote).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Де подивитися, що нового в останній версії?">
|
||||
Перевірте changelog на GitHub:
|
||||
Перевірте GitHub changelog:
|
||||
[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
|
||||
|
||||
Найновіші записи розташовані вгорі. Якщо верхній розділ позначено **Unreleased**, наступний датований
|
||||
розділ є останньою випущеною версією. Записи згруповані за **Highlights**, **Changes** і
|
||||
**Fixes** (плюс розділи документації/іншого, коли потрібно).
|
||||
Найновіші записи зверху. Якщо верхній розділ позначено **Unreleased**, наступний датований
|
||||
розділ є останньою випущеною версією. Записи згруповано за **Highlights**, **Changes** і
|
||||
**Fixes** (плюс розділи docs/other, коли потрібно).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Немає доступу до docs.openclaw.ai (помилка SSL)">
|
||||
Деякі з'єднання Comcast/Xfinity неправильно блокують `docs.openclaw.ai` через Xfinity
|
||||
Advanced Security. Вимкніть це або додайте `docs.openclaw.ai` до allowlist, потім повторіть спробу.
|
||||
<Accordion title="Немає доступу до docs.openclaw.ai (SSL-помилка)">
|
||||
Деякі підключення Comcast/Xfinity некоректно блокують `docs.openclaw.ai` через Xfinity
|
||||
Advanced Security. Вимкніть це або додайте `docs.openclaw.ai` до allowlist, потім спробуйте знову.
|
||||
Будь ласка, допоможіть нам розблокувати це, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status).
|
||||
|
||||
Якщо ви все ще не можете відкрити сайт, документація дзеркалиться на GitHub:
|
||||
Якщо ви все ще не можете дістатися сайту, документація дзеркалиться на GitHub:
|
||||
[https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Різниця між стабільною версією та бета-версією">
|
||||
**Стабільна версія** і **бета-версія** — це **npm dist-tags**, а не окремі гілки коду:
|
||||
<Accordion title="Різниця між стабільною та бета-версією">
|
||||
**Стабільна** і **бета** — це **npm dist-tags**, а не окремі гілки коду:
|
||||
|
||||
- `latest` = стабільна версія
|
||||
- `latest` = стабільна
|
||||
- `beta` = рання збірка для тестування
|
||||
|
||||
Зазвичай стабільний реліз спершу потрапляє в **бета-версію**, а потім окремий
|
||||
крок просування переміщує ту саму версію до `latest`. Супровідники також можуть
|
||||
публікувати одразу в `latest`, коли це потрібно. Саме тому бета-версія і стабільна версія можуть
|
||||
Зазвичай стабільний реліз спочатку потрапляє в **beta**, а потім явний
|
||||
крок просування переносить ту саму версію в `latest`. Супровідники також можуть
|
||||
публікувати напряму в `latest`, коли це потрібно. Саме тому бета й стабільна версія можуть
|
||||
вказувати на **ту саму версію** після просування.
|
||||
|
||||
Перегляньте, що змінилося:
|
||||
Подивіться, що змінилося:
|
||||
[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
|
||||
|
||||
Однорядкові команди встановлення та різницю між бета-версією і dev дивіться в акордеоні нижче.
|
||||
Однорядкові команди встановлення та різницю між бета й dev дивіться в акордеоні нижче.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як установити бета-версію і яка різниця між beta та dev?">
|
||||
**Бета-версія** — це npm dist-tag `beta` (після просування може збігатися з `latest`).
|
||||
**Dev** — це рухома вершина `main` (git); після публікації вона використовує npm dist-tag `dev`.
|
||||
**Бета** — це npm dist-tag `beta` (може збігатися з `latest` після просування).
|
||||
**Dev** — це рухома вершина `main` (git); під час публікації вона використовує npm dist-tag `dev`.
|
||||
|
||||
Однорядкові команди (macOS/Linux):
|
||||
|
||||
@ -291,7 +291,7 @@ x-i18n:
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
|
||||
```
|
||||
|
||||
Інсталятор для Windows (PowerShell):
|
||||
Інсталятор Windows (PowerShell):
|
||||
[https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1)
|
||||
|
||||
Докладніше: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer).
|
||||
@ -309,15 +309,15 @@ x-i18n:
|
||||
|
||||
Це перемикає на гілку `main` і оновлює з вихідного коду.
|
||||
|
||||
2. **Встановлення з можливістю редагування (із сайту інсталятора):**
|
||||
2. **Встановлення з можливістю змін (із сайту інсталятора):**
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
|
||||
```
|
||||
|
||||
Це дає вам локальний репозиторій, який можна редагувати, а потім оновлювати через git.
|
||||
Це дає локальний репозиторій, який можна редагувати, а потім оновлювати через git.
|
||||
|
||||
Якщо ви віддаєте перевагу чистому клонуванню вручну, використовуйте:
|
||||
Якщо віддаєте перевагу чистому ручному клонуванню, використайте:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
@ -331,31 +331,31 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Скільки зазвичай тривають встановлення та onboarding?">
|
||||
<Accordion title="Скільки зазвичай тривають встановлення й онбординг?">
|
||||
Орієнтовно:
|
||||
|
||||
- **Встановлення:** 2-5 хвилин
|
||||
- **Onboarding:** 5-15 хвилин залежно від кількості каналів/моделей, які ви налаштовуєте
|
||||
- **Онбординг:** 5-15 хвилин залежно від кількості каналів/моделей, які ви налаштовуєте
|
||||
|
||||
Якщо процес зависає, скористайтеся [Інсталятор завис](#quick-start-and-first-run-setup)
|
||||
Якщо процес зависає, скористайтеся [Інсталятор застряг](#quick-start-and-first-run-setup)
|
||||
і швидким циклом налагодження в [Я застряг](#quick-start-and-first-run-setup).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Інсталятор завис? Як отримати більше зворотного зв'язку?">
|
||||
<Accordion title="Інсталятор застряг? Як отримати більше зворотного зв’язку?">
|
||||
Повторно запустіть інсталятор із **докладним виводом**:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
|
||||
```
|
||||
|
||||
Встановлення бета-версії з докладним виводом:
|
||||
Встановлення бета з докладним виводом:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
|
||||
```
|
||||
|
||||
Для встановлення з можливістю редагування (git):
|
||||
Для встановлення з можливістю змін (git):
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
|
||||
@ -370,31 +370,31 @@ x-i18n:
|
||||
Set-PSDebug -Trace 0
|
||||
```
|
||||
|
||||
Більше параметрів: [Прапорці інсталятора](/uk/install/installer).
|
||||
Більше варіантів: [Прапорці інсталятора](/uk/install/installer).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Встановлення у Windows повідомляє, що git не знайдено або openclaw не розпізнано">
|
||||
<Accordion title="Під час встановлення у Windows написано, що git не знайдено або openclaw не розпізнано">
|
||||
Дві поширені проблеми Windows:
|
||||
|
||||
**1) помилка npm spawn git / git не знайдено**
|
||||
**1) Помилка npm spawn git / git не знайдено**
|
||||
|
||||
- Установіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH.
|
||||
- Закрийте й знову відкрийте PowerShell, потім повторно запустіть інсталятор.
|
||||
- Закрийте й знову відкрийте PowerShell, а потім повторно запустіть інсталятор.
|
||||
|
||||
**2) openclaw не розпізнано після встановлення**
|
||||
**2) openclaw не розпізнається після встановлення**
|
||||
|
||||
- Глобальна папка npm bin не додана до PATH.
|
||||
- Ваша глобальна папка bin для npm не додана до PATH.
|
||||
- Перевірте шлях:
|
||||
|
||||
```powershell
|
||||
npm config get prefix
|
||||
```
|
||||
|
||||
- Додайте цей каталог до свого користувацького PATH (у Windows суфікс `\bin` не потрібен; у більшості систем це `%AppData%\npm`).
|
||||
- Закрийте й знову відкрийте PowerShell після оновлення PATH.
|
||||
- Додайте цей каталог до PATH користувача (у Windows суфікс `\bin` не потрібен; у більшості систем це `%AppData%\npm`).
|
||||
- Після оновлення PATH закрийте й знову відкрийте PowerShell.
|
||||
|
||||
Якщо вам потрібне найзручніше налаштування Windows, використовуйте **WSL2** замість нативної Windows.
|
||||
Якщо хочете найзручніше налаштування Windows, використовуйте **WSL2** замість нативного Windows.
|
||||
Документація: [Windows](/uk/platforms/windows).
|
||||
|
||||
</Accordion>
|
||||
@ -404,8 +404,8 @@ x-i18n:
|
||||
|
||||
Симптоми:
|
||||
|
||||
- вивід `system.run`/`exec` відображає китайський текст як mojibake
|
||||
- та сама команда виглядає нормально в іншому профілі термінала
|
||||
- Вивід `system.run`/`exec` показує китайський текст як mojibake
|
||||
- Та сама команда виглядає нормально в іншому профілі термінала
|
||||
|
||||
Швидкий обхідний шлях у PowerShell:
|
||||
|
||||
@ -422,14 +422,14 @@ x-i18n:
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Якщо ви все ще відтворюєте це в найновішому OpenClaw, відстежуйте/повідомте про це тут:
|
||||
Якщо це все ще відтворюється в найновішому OpenClaw, відстежуйте/повідомте про це тут:
|
||||
|
||||
- [Issue #30640](https://github.com/openclaw/openclaw/issues/30640)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Документація не відповіла на моє запитання — як отримати кращу відповідь?">
|
||||
Використайте **встановлення з можливістю редагування (git)**, щоб мати повний вихідний код і документацію локально, а потім запитайте
|
||||
Використайте **встановлення з можливістю змін (git)**, щоб мати повний вихідний код і документацію локально, а потім запитайте
|
||||
свого бота (або Claude/Codex) _з цієї папки_, щоб він міг прочитати репозиторій і відповісти точно.
|
||||
|
||||
```bash
|
||||
@ -441,23 +441,23 @@ x-i18n:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як установити OpenClaw на Linux?">
|
||||
Коротка відповідь: дотримуйтесь посібника для Linux, а потім запустіть onboarding.
|
||||
Коротка відповідь: дотримуйтесь посібника для Linux, а потім запустіть онбординг.
|
||||
|
||||
- Швидкий шлях для Linux + встановлення служби: [Linux](/uk/platforms/linux).
|
||||
- Швидкий шлях для Linux + встановлення сервісу: [Linux](/uk/platforms/linux).
|
||||
- Повний покроковий посібник: [Початок роботи](/uk/start/getting-started).
|
||||
- Інсталятор + оновлення: [Встановлення й оновлення](/uk/install/updating).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як установити OpenClaw на VPS?">
|
||||
Підійде будь-який Linux VPS. Установіть на сервері, а потім використовуйте SSH/Tailscale, щоб дістатися до Gateway.
|
||||
Підійде будь-який Linux VPS. Установіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway.
|
||||
|
||||
Посібники: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly).
|
||||
Віддалений доступ: [Gateway віддалено](/uk/gateway/remote).
|
||||
Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Де посібники зі встановлення в хмарі/VPS?">
|
||||
<Accordion title="Де посібники з установлення в хмарі/VPS?">
|
||||
Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Виберіть один і дотримуйтесь посібника:
|
||||
|
||||
- [VPS-хостинг](/uk/vps) (усі провайдери в одному місці)
|
||||
@ -466,22 +466,22 @@ x-i18n:
|
||||
- [exe.dev](/uk/install/exe-dev)
|
||||
|
||||
Як це працює в хмарі: **Gateway працює на сервері**, а ви отримуєте до нього доступ
|
||||
зі свого ноутбука/телефона через Control UI (або Tailscale/SSH). Ваш стан + робочий простір
|
||||
зберігаються на сервері, тому вважайте хост джерелом істини й створюйте його резервні копії.
|
||||
із ноутбука/телефона через Control UI (або Tailscale/SSH). Ваш стан + робочий простір
|
||||
зберігаються на сервері, тож вважайте хост джерелом істини й створюйте його резервні копії.
|
||||
|
||||
Ви можете поєднати **вузли** (Mac/iOS/Android/headless) із цим хмарним Gateway, щоб отримувати доступ
|
||||
до локального екрана/камери/canvas або запускати команди на своєму ноутбуці, залишаючи
|
||||
Ви можете прив’язати **вузли** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримувати доступ
|
||||
до локального екрана/камери/canvas або запускати команди на ноутбуці, залишаючи
|
||||
Gateway у хмарі.
|
||||
|
||||
Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Gateway віддалено](/uk/gateway/remote).
|
||||
Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote).
|
||||
Вузли: [Вузли](/uk/nodes), [CLI вузлів](/uk/cli/nodes).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можу я попросити OpenClaw оновити себе?">
|
||||
Коротка відповідь: **можливо, але не рекомендовано**. Потік оновлення може перезапустити
|
||||
Gateway (що обірве активну сесію), може потребувати чистого git checkout і
|
||||
може запитувати підтвердження. Безпечніше: запускати оновлення з оболонки як оператор.
|
||||
Коротка відповідь: **можливо, але не рекомендовано**. Процес оновлення може перезапустити
|
||||
Gateway (що перерве активний сеанс), може потребувати чистого git checkout і
|
||||
може запитати підтвердження. Безпечніше: запускати оновлення з оболонки як оператор.
|
||||
|
||||
Використовуйте CLI:
|
||||
|
||||
@ -493,7 +493,7 @@ x-i18n:
|
||||
openclaw update --no-restart
|
||||
```
|
||||
|
||||
Якщо вам потрібно автоматизувати з агента:
|
||||
Якщо потрібно автоматизувати з агента:
|
||||
|
||||
```bash
|
||||
openclaw update --yes --no-restart
|
||||
@ -504,35 +504,35 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Що насправді робить onboarding?">
|
||||
`openclaw onboard` — це рекомендований шлях налаштування. У **локальному режимі** він проводить вас через:
|
||||
<Accordion title="Що насправді робить онбординг?">
|
||||
`openclaw onboard` — рекомендований шлях налаштування. У **локальному режимі** він проводить вас через:
|
||||
|
||||
- **Налаштування моделі/автентифікації** (OAuth провайдера, API-ключі, Anthropic setup-token, а також параметри локальних моделей, як-от LM Studio)
|
||||
- **Налаштування моделі/автентифікації** (OAuth провайдера, API-ключі, setup-token Anthropic, а також локальні варіанти моделей, як-от LM Studio)
|
||||
- Розташування **робочого простору** + початкові файли
|
||||
- **Налаштування Gateway** (bind/port/auth/tailscale)
|
||||
- **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також вбудовані Plugin каналів, як-от QQ Bot)
|
||||
- **Встановлення демона** (LaunchAgent на macOS; користувацький systemd unit у Linux/WSL2)
|
||||
- **Перевірки стану** і вибір **skills**
|
||||
- **Встановлення демона** (LaunchAgent на macOS; користувацький systemd unit на Linux/WSL2)
|
||||
- **Перевірки стану** і вибір **Skills**
|
||||
|
||||
Він також попереджає, якщо налаштована модель невідома або в неї бракує автентифікації.
|
||||
Він також попереджає, якщо налаштована модель невідома або їй бракує автентифікації.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи потрібна підписка Claude або OpenAI, щоб це запустити?">
|
||||
Ні. Ви можете запускати OpenClaw з **API-ключами** (Anthropic/OpenAI/інші) або з
|
||||
**моделями лише локально**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude
|
||||
Pro/Max або OpenAI Codex) — це необов'язкові способи автентифікації в цих провайдерів.
|
||||
**суто локальними моделями**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude
|
||||
Pro/Max або OpenAI Codex) — необов’язкові способи автентифікації цих провайдерів.
|
||||
|
||||
Для Anthropic в OpenClaw практичний поділ такий:
|
||||
|
||||
- **API-ключ Anthropic**: звичайний білінг Anthropic API
|
||||
- **API-ключ Anthropic**: звичайна оплата Anthropic API
|
||||
- **Claude CLI / автентифікація підписки Claude в OpenClaw**: співробітники Anthropic
|
||||
повідомили нам, що це використання знову дозволене, і OpenClaw розглядає використання `claude -p`
|
||||
як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову
|
||||
повідомили нам, що це використання знову дозволене, і OpenClaw вважає використання `claude -p`
|
||||
санкціонованим для цієї інтеграції, доки Anthropic не опублікує нову
|
||||
політику
|
||||
|
||||
Для довготривалих хостів gateway API-ключі Anthropic усе ще є більш
|
||||
передбачуваним налаштуванням. OpenAI Codex OAuth явно підтримується для зовнішніх
|
||||
Для довготривалих хостів gateway API-ключі Anthropic усе ще є
|
||||
передбачуванішим налаштуванням. OAuth OpenAI Codex явно підтримується для зовнішніх
|
||||
інструментів, як-от OpenClaw.
|
||||
|
||||
OpenClaw також підтримує інші розміщені варіанти в стилі підписки, зокрема
|
||||
@ -550,24 +550,25 @@ x-i18n:
|
||||
Так.
|
||||
|
||||
Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому
|
||||
OpenClaw розглядає автентифікацію підписки Claude і використання `claude -p` як санкціоновані
|
||||
для цієї інтеграції, якщо Anthropic не опублікує нову політику. Якщо вам потрібне
|
||||
найбільш передбачуване серверне налаштування, натомість використовуйте API-ключ Anthropic.
|
||||
OpenClaw вважає автентифікацію підписки Claude і використання `claude -p` санкціонованими
|
||||
для цієї інтеграції, доки Anthropic не опублікує нову політику. Якщо ви хочете
|
||||
найпередбачуваніше серверне налаштування, натомість використовуйте API-ключ Anthropic.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи підтримується автентифікація підписки Claude (Claude Pro або Max)?">
|
||||
Так.
|
||||
|
||||
Співробітники Anthropic повідомили нам, що це використання знову дозволене, тому OpenClaw розглядає
|
||||
повторне використання Claude CLI і використання `claude -p` як санкціоновані для цієї інтеграції,
|
||||
якщо Anthropic не опублікує нову політику.
|
||||
Співробітники Anthropic повідомили нам, що це використання знову дозволене, тому OpenClaw вважає
|
||||
повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції,
|
||||
доки Anthropic не опублікує нову політику.
|
||||
|
||||
Anthropic setup-token усе ще доступний як підтримуваний шлях токена OpenClaw, але OpenClaw тепер віддає перевагу повторному використанню Claude CLI і `claude -p`, коли вони доступні.
|
||||
Для продакшну або багатокористувацьких навантажень автентифікація API-ключем Anthropic усе ще є
|
||||
Для продакшн або багатокористувацьких навантажень автентифікація API-ключем Anthropic усе ще є
|
||||
безпечнішим і передбачуванішим вибором. Якщо вам потрібні інші розміщені
|
||||
варіанти в стилі підписки в OpenClaw, дивіться [OpenAI](/uk/providers/openai), [Qwen / Model
|
||||
Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [Моделі GLM](/uk/providers/glm).
|
||||
Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [GLM
|
||||
Models](/uk/providers/glm).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -577,58 +578,60 @@ x-i18n:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Чому я бачу HTTP 429 rate_limit_error від Anthropic?">
|
||||
Це означає, що вашу **квоту/ліміт частоти Anthropic** вичерпано для поточного вікна. Якщо ви
|
||||
використовуєте **Claude CLI**, дочекайтеся скидання вікна або оновіть свій план. Якщо ви
|
||||
Це означає, що ваша **квота/ліміт швидкості Anthropic** вичерпані для поточного вікна. Якщо ви
|
||||
використовуєте **Claude CLI**, зачекайте скидання вікна або оновіть свій план. Якщо ви
|
||||
використовуєте **API-ключ Anthropic**, перевірте Anthropic Console
|
||||
щодо використання/білінгу та за потреби підніміть ліміти.
|
||||
щодо використання/оплати й підвищте ліміти за потреби.
|
||||
|
||||
Якщо повідомлення саме таке:
|
||||
`Extra usage is required for long context requests`, запит намагається використати
|
||||
бета-версію контексту 1M від Anthropic (`context1m: true`). Це працює лише тоді, коли ваші
|
||||
облікові дані придатні для білінгу довгого контексту (білінг API-ключа або
|
||||
облікові дані придатні для оплати довгого контексту (оплата API-ключем або
|
||||
шлях входу Claude в OpenClaw з увімкненим Extra Usage).
|
||||
|
||||
Порада: задайте **резервну модель**, щоб OpenClaw міг продовжувати відповідати, поки провайдер обмежений лімітом запитів.
|
||||
Порада: налаштуйте **резервну модель**, щоб OpenClaw міг продовжувати відповідати, коли провайдер має обмеження частоти.
|
||||
Див. [Моделі](/uk/cli/models), [OAuth](/uk/concepts/oauth) і
|
||||
[/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи підтримується AWS Bedrock?">
|
||||
Так. OpenClaw має вбудованого провайдера **Amazon Bedrock (Converse)**. За наявності маркерів середовища AWS OpenClaw може автоматично виявити потоковий/текстовий каталог Bedrock і об’єднати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-сумісний проксі перед Bedrock також залишається припустимим варіантом.
|
||||
Так. OpenClaw має вбудованого провайдера **Amazon Bedrock (Converse)**. За наявності маркерів середовища AWS OpenClaw може автоматично виявляти потоковий/текстовий каталог Bedrock і об’єднувати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо вам зручніший керований потік ключів, OpenAI-сумісний проксі перед Bedrock також залишається коректним варіантом.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як працює автентифікація Codex?">
|
||||
OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Використовуйте
|
||||
`openai-codex/gpt-5.5` для Codex OAuth через типовий раннер PI. Використовуйте
|
||||
`openai/gpt-5.5` для прямого доступу за API-ключем OpenAI. GPT-5.5 також може використовувати
|
||||
підписку/OAuth через `openai-codex/gpt-5.5` або нативні запуски Codex app-server
|
||||
з `openai/gpt-5.5` і `agentRuntime.id: "codex"`.
|
||||
Див. [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard).
|
||||
OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід ChatGPT). Використовуйте
|
||||
`openai/gpt-5.5` з `agentRuntime.id: "codex"` для типового налаштування:
|
||||
автентифікація підписки ChatGPT/Codex плюс нативне виконання на сервері застосунку Codex. Використовуйте
|
||||
`openai-codex/gpt-5.5` лише тоді, коли потрібен Codex OAuth через стандартний
|
||||
раннер PI. Використовуйте `openai/gpt-5.5` без перевизначення середовища виконання Codex для
|
||||
прямого доступу з API-ключем OpenAI.
|
||||
Див. [Провайдери моделей](/uk/concepts/model-providers) і [Початкове налаштування (CLI)](/uk/start/wizard).
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чому OpenClaw досі згадує openai-codex?">
|
||||
`openai-codex` — це ідентифікатор провайдера та профілю автентифікації для ChatGPT/Codex OAuth.
|
||||
Це також явний префікс моделі PI для Codex OAuth:
|
||||
|
||||
- `openai/gpt-5.5` = поточний прямий маршрут OpenAI API-ключа в PI
|
||||
- `openai-codex/gpt-5.5` = маршрут Codex OAuth в PI
|
||||
- `openai/gpt-5.5` + `agentRuntime.id: "codex"` = нативний маршрут Codex app-server
|
||||
- `openai/gpt-5.5` + `agentRuntime.id: "codex"` = автентифікація підписки ChatGPT/Codex з нативним середовищем виконання Codex
|
||||
- `openai-codex/gpt-5.5` = маршрут Codex OAuth у PI
|
||||
- `openai/gpt-5.5` без перевизначення середовища виконання Codex = прямий маршрут з API-ключем OpenAI у PI
|
||||
- `openai-codex:...` = ідентифікатор профілю автентифікації, а не посилання на модель
|
||||
|
||||
Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, задайте
|
||||
`OPENAI_API_KEY`. Якщо вам потрібна автентифікація підписки ChatGPT/Codex, увійдіть через
|
||||
`openclaw models auth login --provider openai-codex` і використовуйте
|
||||
посилання на моделі `openai-codex/*` для запусків PI.
|
||||
`OPENAI_API_KEY`. Якщо потрібна автентифікація підписки ChatGPT/Codex, увійдіть через
|
||||
`openclaw models auth login --provider openai-codex`. Для нативного середовища виконання Codex
|
||||
залиште посилання на модель як `openai/gpt-5.5` і задайте
|
||||
`agentRuntime.id: "codex"`. Використовуйте посилання на моделі `openai-codex/*` лише для запусків PI.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чому ліміти Codex OAuth можуть відрізнятися від ChatGPT web?">
|
||||
Codex OAuth використовує керовані OpenAI квотні вікна, що залежать від плану. На практиці
|
||||
ці ліміти можуть відрізнятися від досвіду на сайті/в застосунку ChatGPT, навіть коли
|
||||
обидва прив’язані до одного облікового запису.
|
||||
обидва прив’язані до того самого облікового запису.
|
||||
|
||||
OpenClaw може показати поточно видимі вікна використання/квот провайдера в
|
||||
OpenClaw може показувати поточно видимі вікна використання/квот провайдера в
|
||||
`openclaw models status`, але він не вигадує й не нормалізує права ChatGPT-web
|
||||
у прямий доступ до API. Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform,
|
||||
використовуйте `openai/*` з API-ключем.
|
||||
@ -636,11 +639,11 @@ x-i18n:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи підтримуєте ви автентифікацію підписки OpenAI (Codex OAuth)?">
|
||||
Так. OpenClaw повністю підтримує **підписку OpenAI Code (Codex) через OAuth**.
|
||||
OpenAI явно дозволяє використання OAuth підписки в зовнішніх інструментах/робочих процесах,
|
||||
таких як OpenClaw. Онбординг може виконати OAuth-потік за вас.
|
||||
Так. OpenClaw повністю підтримує **OpenAI Code (Codex) subscription OAuth**.
|
||||
OpenAI явно дозволяє використання subscription OAuth у зовнішніх інструментах/робочих процесах,
|
||||
таких як OpenClaw. Початкове налаштування може виконати OAuth-потік за вас.
|
||||
|
||||
Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard).
|
||||
Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Початкове налаштування (CLI)](/uk/start/wizard).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -654,49 +657,49 @@ x-i18n:
|
||||
- npm: `npm install -g @google/gemini-cli`
|
||||
2. Увімкніть Plugin: `openclaw plugins enable google`
|
||||
3. Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default`
|
||||
4. Типова модель після входу: `google-gemini-cli/gemini-3-flash-preview`
|
||||
5. Якщо запити не виконуються, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway
|
||||
4. Стандартна модель після входу: `google-gemini-cli/gemini-3-flash-preview`
|
||||
5. Якщо запити не виконуються, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway
|
||||
|
||||
Це зберігає OAuth-токени в профілях автентифікації на хості Gateway. Докладніше: [Провайдери моделей](/uk/concepts/model-providers).
|
||||
Це зберігає OAuth-токени в профілях автентифікації на хості gateway. Докладніше: [Провайдери моделей](/uk/concepts/model-providers).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи підходить локальна модель для невимушених чатів?">
|
||||
Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі карти обрізають і пропускають дані. Якщо необхідно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантовані моделі підвищують ризик prompt-injection — див. [Безпека](/uk/gateway/security).
|
||||
<Accordion title="Чи підходить локальна модель для звичайних чатів?">
|
||||
Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі карти обрізають і пропускають дані. Якщо все ж потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt-injection — див. [Безпека](/uk/gateway/security).
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як утримувати трафік хостингових моделей у конкретному регіоні?">
|
||||
Обирайте ендпоїнти, прив’язані до регіону. OpenRouter надає варіанти, розміщені в США, для MiniMax, Kimi і GLM; оберіть варіант, розміщений у США, щоб дані залишалися в регіоні. Ви все одно можете перелічити Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними з дотриманням обраного регіонального провайдера.
|
||||
<Accordion title="Як утримувати трафік розміщених моделей у конкретному регіоні?">
|
||||
Вибирайте кінцеві точки, прив’язані до регіону. OpenRouter надає варіанти, розміщені у США, для MiniMax, Kimi та GLM; виберіть варіант, розміщений у США, щоб утримувати дані в регіоні. Ви все ще можете перелічувати Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними з дотриманням вибраного регіонального провайдера.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи потрібно купувати Mac Mini, щоб це встановити?">
|
||||
<Accordion title="Чи потрібно купувати Mac Mini, щоб установити це?">
|
||||
Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini необов’язковий — деякі люди
|
||||
купують його як постійно ввімкнений хост, але невеликий VPS, домашній сервер або пристрій класу Raspberry Pi також підійдуть.
|
||||
купують його як постійно ввімкнений хост, але невеликий VPS, домашній сервер або пристрій класу Raspberry Pi також підійде.
|
||||
|
||||
Mac потрібен лише **для інструментів, доступних тільки на macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або під’єднайте вузол macOS.
|
||||
Mac потрібен лише **для інструментів, доступних тільки на macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або спарюйте вузол macOS.
|
||||
|
||||
Документація: [BlueBubbles](/uk/channels/bluebubbles), [Вузли](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи потрібен Mac mini для підтримки iMessage?">
|
||||
Вам потрібен **будь-який пристрій macOS**, на якому виконано вхід у Messages. Це **не** обов’язково має бути Mac mini —
|
||||
Вам потрібен **якийсь пристрій macOS**, на якому виконано вхід у Messages. Це **не** обов’язково має бути Mac mini —
|
||||
підійде будь-який Mac. **Використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) для iMessage — сервер BlueBubbles працює на macOS, тоді як Gateway може працювати на Linux або деінде.
|
||||
|
||||
Типові налаштування:
|
||||
|
||||
- Запустіть Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, де виконано вхід у Messages.
|
||||
- Запустіть усе на Mac, якщо хочете найпростіше налаштування на одній машині.
|
||||
- Запустіть усе на Mac, якщо хочете найпростіше налаштування на одному комп’ютері.
|
||||
|
||||
Документація: [BlueBubbles](/uk/channels/bluebubbles), [Вузли](/uk/nodes),
|
||||
[Віддалений режим Mac](/uk/platforms/mac/remote).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Якщо я куплю Mac mini для запуску OpenClaw, чи можу я підключити його до свого MacBook Pro?">
|
||||
<Accordion title="Якщо я куплю Mac mini для запуску OpenClaw, чи можу підключити його до свого MacBook Pro?">
|
||||
Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключатися як
|
||||
**вузол** (супровідний пристрій). Вузли не запускають Gateway — вони надають додаткові
|
||||
можливості, як-от екран/камера/полотно і `system.run` на цьому пристрої.
|
||||
можливості, як-от екран/камера/полотно та `system.run` на цьому пристрої.
|
||||
|
||||
Типовий шаблон:
|
||||
|
||||
@ -708,19 +711,19 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можна використовувати Bun?">
|
||||
Bun **не рекомендовано**. Ми бачимо помилки виконання, особливо з WhatsApp і Telegram.
|
||||
Використовуйте **Node** для стабільних Gateway.
|
||||
<Accordion title="Чи можу я використовувати Bun?">
|
||||
Bun **не рекомендовано**. Ми бачимо помилки середовища виконання, особливо з WhatsApp і Telegram.
|
||||
Використовуйте **Node** для стабільних gateway.
|
||||
|
||||
Якщо ви все ж хочете поекспериментувати з Bun, робіть це на не продукційному Gateway
|
||||
Якщо все ж хочете експериментувати з Bun, робіть це на не production gateway
|
||||
без WhatsApp/Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Telegram: що вказувати в allowFrom?">
|
||||
`channels.telegram.allowFrom` — це **ідентифікатор користувача Telegram людини-відправника** (числовий). Це не ім’я користувача бота.
|
||||
`channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не ім’я користувача бота.
|
||||
|
||||
Налаштування просить лише числові ідентифікатори користувачів. Якщо у вас уже є застарілі записи `@username` у конфігурації, `openclaw doctor --fix` може спробувати їх розв’язати.
|
||||
Налаштування запитує лише числові ідентифікатори користувачів. Якщо у вас уже є застарілі записи `@username` у конфігурації, `openclaw doctor --fix` може спробувати їх розпізнати.
|
||||
|
||||
Безпечніше (без стороннього бота):
|
||||
|
||||
@ -730,7 +733,7 @@ x-i18n:
|
||||
|
||||
- Напишіть своєму боту в DM, потім викличте `https://api.telegram.org/bot<bot_token>/getUpdates` і прочитайте `message.from.id`.
|
||||
|
||||
Сторонні сервіси (менш приватно):
|
||||
Сторонній варіант (менш приватний):
|
||||
|
||||
- Напишіть у DM `@userinfobot` або `@getidsbot`.
|
||||
|
||||
@ -738,12 +741,12 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можуть кілька людей використовувати один номер WhatsApp з різними інстансами OpenClaw?">
|
||||
Так, через **маршрутизацію кількох агентів**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, відправник E.164 на кшталт `+15551234567`) до іншого `agentId`, щоб кожна людина отримала власний робочий простір і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp).
|
||||
<Accordion title="Чи можуть кілька людей використовувати один номер WhatsApp з різними екземплярами OpenClaw?">
|
||||
Так, через **маршрутизацію кількох агентів**. Прив’яжіть **DM** кожного відправника WhatsApp (peer `kind: "direct"`, відправник E.164 на кшталт `+15551234567`) до іншого `agentId`, щоб кожна людина мала власний робочий простір і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp).
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Чи можу я запустити агента "fast chat" і агента "Opus for coding"?'>
|
||||
Так. Використовуйте маршрутизацію кількох агентів: задайте кожному агенту власну типову модель, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретних peer) до кожного агента. Приклад конфігурації наведено в [Маршрутизація кількох агентів](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration).
|
||||
<Accordion title='Чи можу я запустити агента "швидкого чату" й агента "Opus для кодування"?'>
|
||||
Так. Використовуйте маршрутизацію кількох агентів: задайте кожному агенту власну стандартну модель, потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретних peers) до кожного агента. Приклад конфігурації наведено в [Маршрутизація кількох агентів](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration).
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи працює Homebrew на Linux?">
|
||||
@ -756,24 +759,24 @@ x-i18n:
|
||||
brew install <formula>
|
||||
```
|
||||
|
||||
Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH служби містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб установлені через `brew` інструменти знаходилися в не login-оболонках.
|
||||
Останні збірки також додають на початок поширені користувацькі bin-каталоги в службах Linux systemd (наприклад, `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, коли вони задані.
|
||||
Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу містить `/home/linuxbrew/.linuxbrew/bin` (або ваш brew-префікс), щоб інструменти, встановлені через `brew`, знаходилися в non-login shells.
|
||||
Останні збірки також додають на початок поширені користувацькі bin-каталоги в сервісах Linux systemd (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, коли їх задано.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Різниця між hackable git-інсталяцією та npm install">
|
||||
- **Hackable (git) install:** повний checkout вихідного коду, придатний для редагування, найкраще для контриб’юторів.
|
||||
<Accordion title="Різниця між hackable git install і npm install">
|
||||
- **Hackable (git) install:** повний checkout вихідного коду, редагований, найкращий для контриб’юторів.
|
||||
Ви запускаєте збірки локально й можете виправляти код/документацію.
|
||||
- **npm install:** глобальна інсталяція CLI, без репозиторію, найкраще для "просто запустити".
|
||||
- **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для варіанту "просто запустити".
|
||||
Оновлення надходять із npm dist-tags.
|
||||
|
||||
Документація: [Початок роботи](/uk/start/getting-started), [Оновлення](/uk/install/updating).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можу я пізніше перемикатися між npm- і git-інсталяціями?">
|
||||
<Accordion title="Чи можу я пізніше перемикатися між npm і git installs?">
|
||||
Так. Використовуйте `openclaw update --channel ...`, коли OpenClaw уже встановлено.
|
||||
Це **не видаляє ваші дані** — воно лише змінює інсталяцію коду OpenClaw.
|
||||
Це **не видаляє ваші дані** — це лише змінює встановлення коду OpenClaw.
|
||||
Ваш стан (`~/.openclaw`) і робочий простір (`~/.openclaw/workspace`) залишаються недоторканими.
|
||||
|
||||
З npm на git:
|
||||
@ -789,8 +792,8 @@ x-i18n:
|
||||
```
|
||||
|
||||
Додайте `--dry-run`, щоб спочатку переглянути заплановане перемикання режиму. Оновлювач запускає
|
||||
подальші дії Doctor, оновлює джерела Plugin для цільового каналу й
|
||||
перезапускає Gateway, якщо ви не передасте `--no-restart`.
|
||||
подальші дії Doctor, оновлює джерела Plugin для цільового каналу та
|
||||
перезапускає gateway, якщо ви не передасте `--no-restart`.
|
||||
|
||||
Інсталятор також може примусово вибрати будь-який режим:
|
||||
|
||||
@ -803,60 +806,60 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи запускати Gateway на ноутбуці чи VPS?">
|
||||
<Accordion title="Чи варто запускати Gateway на моєму ноутбуці чи на VPS?">
|
||||
Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібне
|
||||
мінімальне тертя й вас влаштовують сон/перезапуски, запускайте локально.
|
||||
|
||||
**Ноутбук (локальний Gateway)**
|
||||
|
||||
- **Переваги:** немає вартості сервера, прямий доступ до локальних файлів, живе вікно браузера.
|
||||
- **Недоліки:** сон/мережеві збої = роз’єднання, оновлення ОС/перезавантаження переривають роботу, має залишатися ввімкненим.
|
||||
- **Переваги:** немає витрат на сервер, прямий доступ до локальних файлів, живе вікно браузера.
|
||||
- **Недоліки:** сон/розриви мережі = відключення, оновлення/перезавантаження ОС переривають роботу, має залишатися ввімкненим.
|
||||
|
||||
**VPS / хмара**
|
||||
|
||||
- **Переваги:** завжди ввімкнений, стабільна мережа, немає проблем зі сном ноутбука, легше підтримувати роботу.
|
||||
- **Недоліки:** часто працює без дисплея (використовуйте знімки екрана), лише віддалений доступ до файлів, потрібно використовувати SSH для оновлень.
|
||||
- **Переваги:** завжди ввімкнено, стабільна мережа, немає проблем зі сном ноутбука, легше підтримувати роботу.
|
||||
- **Недоліки:** часто працює без графічного інтерфейсу (використовуйте знімки екрана), лише віддалений доступ до файлів, для оновлень потрібно підключатися через SSH.
|
||||
|
||||
**Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord нормально працюють із VPS. Єдиний справжній компроміс — **headless browser** проти видимого вікна. Див. [Браузер](/uk/tools/browser).
|
||||
**Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord добре працюють із VPS. Єдиний справжній компроміс — **headless browser** проти видимого вікна. Див. [Браузер](/uk/tools/browser).
|
||||
|
||||
**Рекомендовано за замовчуванням:** VPS, якщо раніше у вас були розриви з’єднання Gateway. Локальний запуск чудово підходить, коли ви активно користуєтеся Mac і хочете мати локальний доступ до файлів або автоматизацію UI з видимим браузером.
|
||||
**Рекомендований варіант за замовчуванням:** VPS, якщо раніше у вас були розриви з’єднання Gateway. Локальний запуск чудово підходить, коли ви активно використовуєте Mac і хочете локальний доступ до файлів або автоматизацію UI з видимим браузером.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Наскільки важливо запускати OpenClaw на виділеній машині?">
|
||||
Не обов’язково, але **рекомендовано для надійності та ізоляції**.
|
||||
|
||||
- **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, простіше підтримувати роботу.
|
||||
- **Спільний ноутбук/настільний комп’ютер:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина переходить у сон або оновлюється.
|
||||
- **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон або перезавантаження, чистіші дозволи, легше підтримувати роботу.
|
||||
- **Спільний ноутбук/настільний комп’ютер:** цілком підходить для тестування та активного використання, але очікуйте пауз, коли машина переходить у сон або оновлюється.
|
||||
|
||||
Якщо хочете найкраще з обох варіантів, тримайте Gateway на виділеному хості й під’єднайте ноутбук як **Node** для локальних інструментів екрана/камери/виконання команд. Див. [Nodes](/uk/nodes).
|
||||
Якщо хочете отримати переваги обох підходів, тримайте Gateway на виділеному хості та спаруйте ноутбук як **вузол** для локальних інструментів екрана/камери/exec. Див. [Вузли](/uk/nodes).
|
||||
Рекомендації з безпеки див. у [Безпека](/uk/gateway/security).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Які мінімальні вимоги до VPS і рекомендована ОС?">
|
||||
OpenClaw легкий. Для базового Gateway + одного каналу чату:
|
||||
OpenClaw легковаговий. Для базового Gateway + одного каналу чату:
|
||||
|
||||
- **Абсолютний мінімум:** 1 vCPU, 1 ГБ RAM, ~500 МБ диска.
|
||||
- **Рекомендовано:** 1–2 vCPU, 2 ГБ RAM або більше для запасу (журнали, медіа, кілька каналів). Інструменти Node та автоматизація браузера можуть вимагати багато ресурсів.
|
||||
- **Абсолютний мінімум:** 1 vCPU, 1GB RAM, ~500MB диска.
|
||||
- **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше для запасу (журнали, медіа, кілька каналів). Інструменти Node та автоматизація браузера можуть потребувати багато ресурсів.
|
||||
|
||||
ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення Linux найкраще протестований саме там.
|
||||
ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення Linux найкраще протестовано там.
|
||||
|
||||
Документація: [Linux](/uk/platforms/linux), [VPS-хостинг](/uk/vps).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можу я запускати OpenClaw у VM і які вимоги?">
|
||||
Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкнена, доступна й мати достатньо
|
||||
RAM для Gateway та будь-яких каналів, які ви ввімкнете.
|
||||
<Accordion title="Чи можна запускати OpenClaw у VM і які вимоги?">
|
||||
Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкнена, доступна та мати достатньо
|
||||
RAM для Gateway і всіх каналів, які ви вмикаєте.
|
||||
|
||||
Базові рекомендації:
|
||||
|
||||
- **Абсолютний мінімум:** 1 vCPU, 1 ГБ RAM.
|
||||
- **Рекомендовано:** 2 ГБ RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера або медіаінструменти.
|
||||
- **Абсолютний мінімум:** 1 vCPU, 1GB RAM.
|
||||
- **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера або медіаінструменти.
|
||||
- **ОС:** Ubuntu LTS або інший сучасний Debian/Ubuntu.
|
||||
|
||||
Якщо ви на Windows, **WSL2 — найпростіший варіант налаштування у стилі VM** і має найкращу сумісність
|
||||
Якщо ви на Windows, **WSL2 — найпростіший варіант налаштування в стилі VM** і має найкращу сумісність
|
||||
з інструментами. Див. [Windows](/uk/platforms/windows), [VPS-хостинг](/uk/vps).
|
||||
Якщо ви запускаєте macOS у VM, див. [macOS VM](/uk/install/macos-vm).
|
||||
|
||||
@ -865,7 +868,7 @@ x-i18n:
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [FAQ](/uk/help/faq) — основний FAQ (моделі, сесії, Gateway, безпека тощо)
|
||||
- [FAQ](/uk/help/faq) — основний FAQ (моделі, сесії, gateway, безпека тощо)
|
||||
- [Огляд встановлення](/uk/install)
|
||||
- [Початок роботи](/uk/start/getting-started)
|
||||
- [Усунення несправностей](/uk/help/troubleshooting)
|
||||
|
||||
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Вибір або перемикання моделей, налаштування псевдонімів
|
||||
- Налагодження резервного перемикання моделей / "Усі моделі завершилися помилкою"
|
||||
- Розуміння профілів автентифікації та керування ними
|
||||
- Налагодження аварійного перемикання моделей / "Усі моделі не спрацювали"
|
||||
- Що таке профілі автентифікації та як ними керувати
|
||||
sidebarTitle: Models FAQ
|
||||
summary: 'Поширені запитання: типові налаштування моделей, вибір, псевдоніми, перемикання, аварійне перемикання та профілі автентифікації'
|
||||
summary: 'Поширені запитання: типові налаштування моделей, вибір, псевдоніми, перемикання, резервне перемикання та профілі автентифікації'
|
||||
title: 'Поширені запитання: моделі та автентифікація'
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T11:04:02Z"
|
||||
generated_at: "2026-05-02T02:37:18Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: eaa72bf66d3f1528f95762e2a2763bc2f6bfddbc1d4c24a9ec2df7f943ebc14b
|
||||
source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884
|
||||
source_path: help/faq-models.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Модельні та автентифікаційно-профільні запитання й відповіді. Щодо налаштування, сеансів, Gateway, каналів і
|
||||
Запитання й відповіді щодо моделей і профілів автентифікації. Щодо налаштування, сеансів, gateway, каналів і
|
||||
усунення несправностей див. основний [FAQ](/uk/help/faq).
|
||||
|
||||
## Моделі: типові значення, вибір, псевдоніми, перемикання
|
||||
@ -28,24 +28,24 @@ x-i18n:
|
||||
agents.defaults.model.primary
|
||||
```
|
||||
|
||||
Моделі вказуються як `provider/model` (приклад: `openai/gpt-5.5` або `openai-codex/gpt-5.5`). Якщо ви не вкажете провайдера, OpenClaw спочатку спробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього повернеться до налаштованого типового провайдера як застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повернеться до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. Вам усе одно слід **явно** задавати `provider/model`.
|
||||
Моделі задаються як `provider/model` (приклад: `openai/gpt-5.5` або `openai-codex/gpt-5.5`). Якщо ви не вкажете провайдера, OpenClaw спершу спробує псевдонім, потім унікальний збіг налаштованого провайдера для саме цього ідентифікатора моделі, і лише після цього повернеться до налаштованого типового провайдера як застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повернеться до першої налаштованої пари провайдер/модель замість показу застарілого типового значення для вилученого провайдера. Все одно варто **явно** задавати `provider/model`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Яку модель ви рекомендуєте?">
|
||||
**Рекомендоване типове значення:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів.
|
||||
**Для агентів із підтримкою інструментів або недовіреним введенням:** віддавайте перевагу потужності моделі, а не вартості.
|
||||
**Для звичайного/низькоризикового чату:** використовуйте дешевші резервні моделі й маршрутизуйте за роллю агента.
|
||||
**Рекомендовано за замовчуванням:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів.
|
||||
**Для агентів з інструментами або недовіреним введенням:** надавайте пріоритет потужності моделі, а не вартості.
|
||||
**Для звичайного чату з низькими ризиками:** використовуйте дешевші резервні моделі й маршрутизуйте за роллю агента.
|
||||
|
||||
MiniMax має власну документацію: [MiniMax](/uk/providers/minimax) і
|
||||
[Локальні моделі](/uk/gateway/local-models).
|
||||
[локальні моделі](/uk/gateway/local-models).
|
||||
|
||||
Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити**, для роботи з високими ставками, і дешевшу
|
||||
модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі для кожного агента й використовувати субагентів, щоб
|
||||
паралелізувати довгі завдання (кожен субагент споживає токени). Див. [Моделі](/uk/concepts/models) і
|
||||
Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити** для роботи з високими ризиками, і дешевшу
|
||||
модель для звичайного чату або підсумків. Можна маршрутизувати моделі для кожного агента й використовувати субагентів для
|
||||
паралельного виконання довгих завдань (кожен субагент споживає токени). Див. [Моделі](/uk/concepts/models) і
|
||||
[Субагенти](/uk/tools/subagents).
|
||||
|
||||
Серйозне попередження: слабші/надмірно квантовані моделі вразливіші до prompt
|
||||
Суворе попередження: слабші або надмірно квантизовані моделі вразливіші до prompt
|
||||
injection і небезпечної поведінки. Див. [Безпека](/uk/gateway/security).
|
||||
|
||||
Більше контексту: [Моделі](/uk/concepts/models).
|
||||
@ -60,18 +60,18 @@ x-i18n:
|
||||
- `/model` у чаті (швидко, для окремого сеансу)
|
||||
- `openclaw models set ...` (оновлює лише конфігурацію моделі)
|
||||
- `openclaw configure --section model` (інтерактивно)
|
||||
- редагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json`
|
||||
- редагувати `agents.defaults.model` у `~/.openclaw/openclaw.json`
|
||||
|
||||
Уникайте `config.apply` із частковим об'єктом, якщо не маєте наміру замінити всю конфігурацію.
|
||||
Для RPC-редагувань спочатку перевірте через `config.schema.lookup` і надавайте перевагу `config.patch`. Корисне навантаження lookup дає нормалізований шлях, поверхневу документацію/обмеження схеми й короткі описи безпосередніх дочірніх елементів.
|
||||
Уникайте `config.apply` з частковим обʼєктом, якщо не маєте наміру замінити всю конфігурацію.
|
||||
Для RPC-редагувань спершу перевірте через `config.schema.lookup` і надавайте перевагу `config.patch`. Корисне навантаження lookup дає нормалізований шлях, стислі документи/обмеження схеми й підсумки безпосередніх дочірніх елементів
|
||||
для часткових оновлень.
|
||||
Якщо ви перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення.
|
||||
Якщо ви перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для відновлення.
|
||||
|
||||
Документація: [Моделі](/uk/concepts/models), [Налаштування](/uk/cli/configure), [Конфігурація](/uk/cli/config), [Doctor](/uk/gateway/doctor).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можна використовувати самостійно розгорнуті моделі (llama.cpp, vLLM, Ollama)?">
|
||||
<Accordion title="Чи можу я використовувати самостійно розміщені моделі (llama.cpp, vLLM, Ollama)?">
|
||||
Так. Ollama — найпростіший шлях для локальних моделей.
|
||||
|
||||
Найшвидше налаштування:
|
||||
@ -82,15 +82,15 @@ x-i18n:
|
||||
4. Запустіть `openclaw onboard` і виберіть `Ollama`
|
||||
5. Виберіть `Local` або `Cloud + Local`
|
||||
|
||||
Примітки:
|
||||
Нотатки:
|
||||
|
||||
- `Cloud + Local` дає вам хмарні моделі плюс ваші локальні моделі Ollama
|
||||
- хмарні моделі, як-от `kimi-k2.5:cloud`, не потребують локального завантаження
|
||||
- `Cloud + Local` дає хмарні моделі разом із вашими локальними моделями Ollama
|
||||
- хмарні моделі на кшталт `kimi-k2.5:cloud` не потребують локального завантаження
|
||||
- для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/<model>`
|
||||
|
||||
Примітка щодо безпеки: менші або сильно квантовані моделі вразливіші до prompt
|
||||
injection. Ми настійно рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти.
|
||||
Якщо ви все ж хочете малі моделі, увімкніть sandboxing і суворі списки дозволених інструментів.
|
||||
Примітка щодо безпеки: менші або сильно квантизовані моделі вразливіші до prompt
|
||||
injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти.
|
||||
Якщо ви все одно хочете малі моделі, увімкніть sandboxing і суворі списки дозволених інструментів.
|
||||
|
||||
Документація: [Ollama](/uk/providers/ollama), [Локальні моделі](/uk/gateway/local-models),
|
||||
[Провайдери моделей](/uk/concepts/model-providers), [Безпека](/uk/gateway/security),
|
||||
@ -99,9 +99,9 @@ x-i18n:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Які моделі використовують OpenClaw, Flawd і Krill?">
|
||||
- Ці розгортання можуть відрізнятися й змінюватися з часом; сталої рекомендації щодо провайдера немає.
|
||||
- Ці розгортання можуть відрізнятися й змінюватися з часом; фіксованої рекомендації щодо провайдера немає.
|
||||
- Перевірте поточне runtime-налаштування на кожному gateway за допомогою `openclaw models status`.
|
||||
- Для чутливих до безпеки агентів або агентів із підтримкою інструментів використовуйте найсильнішу модель останнього покоління, доступну вам.
|
||||
- Для агентів, чутливих до безпеки або з інструментами, використовуйте найсильнішу модель останнього покоління з доступних.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -118,9 +118,9 @@ x-i18n:
|
||||
/model gemini-flash-lite
|
||||
```
|
||||
|
||||
Це вбудовані псевдоніми. Користувацькі псевдоніми можна додати через `agents.defaults.models`.
|
||||
Це вбудовані псевдоніми. Власні псевдоніми можна додати через `agents.defaults.models`.
|
||||
|
||||
Ви можете переглянути доступні моделі за допомогою `/model`, `/model list` або `/model status`.
|
||||
Доступні моделі можна переглянути за допомогою `/model`, `/model list` або `/model status`.
|
||||
|
||||
`/model` (і `/model list`) показує компактний нумерований вибір. Виберіть за номером:
|
||||
|
||||
@ -128,17 +128,17 @@ x-i18n:
|
||||
/model 3
|
||||
```
|
||||
|
||||
Ви також можете примусово задати конкретний профіль автентифікації для провайдера (для окремого сеансу):
|
||||
Також можна примусово задати конкретний профіль автентифікації для провайдера (для окремого сеансу):
|
||||
|
||||
```
|
||||
/model opus@anthropic:default
|
||||
/model opus@anthropic:work
|
||||
```
|
||||
|
||||
Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробовано далі.
|
||||
Він також показує налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли вони доступні.
|
||||
Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробувано далі.
|
||||
Також показує налаштовану endpoint-адресу провайдера (`baseUrl`) і режим API (`api`), коли вони доступні.
|
||||
|
||||
**Як відкріпити профіль, який я встановив через @profile?**
|
||||
**Як відкріпити профіль, який я задав через @profile?**
|
||||
|
||||
Повторно запустіть `/model` **без** суфікса `@profile`:
|
||||
|
||||
@ -151,22 +151,23 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можна використовувати GPT 5.5 для щоденних завдань і Codex 5.5 для кодування?">
|
||||
Так. Встановіть одну модель типовою й перемикайтеся за потреби:
|
||||
<Accordion title="Чи можу я використовувати GPT 5.5 для щоденних завдань і Codex 5.5 для програмування?">
|
||||
Так. Розглядайте вибір моделі й вибір runtime окремо:
|
||||
|
||||
- **Швидке перемикання (для окремого сеансу):** `/model openai/gpt-5.5` для поточних завдань із прямим ключем OpenAI API або `/model openai-codex/gpt-5.5` для завдань GPT-5.5 Codex OAuth.
|
||||
- **Типове значення:** встановіть `agents.defaults.model.primary` на `openai/gpt-5.5` для використання API-ключа або `openai-codex/gpt-5.5` для використання GPT-5.5 Codex OAuth.
|
||||
- **Субагенти:** маршрутизуйте завдання кодування до субагентів з іншою типовою моделлю.
|
||||
- **Нативний агент програмування Codex:** установіть `agents.defaults.model.primary` на `openai/gpt-5.5`, а `agents.defaults.agentRuntime.id` на `"codex"`. Увійдіть через `openclaw models auth login --provider openai-codex`, коли хочете автентифікацію підписки ChatGPT/Codex.
|
||||
- **Прямі завдання OpenAI API через PI:** використовуйте `/model openai/gpt-5.5` без перевизначення runtime Codex і налаштуйте `OPENAI_API_KEY`.
|
||||
- **Codex OAuth через PI:** використовуйте `/model openai-codex/gpt-5.5` лише тоді, коли свідомо хочете звичайний PI runner із Codex OAuth.
|
||||
- **Субагенти:** маршрутизуйте завдання програмування до агента лише для Codex з власною моделлю і типовим `agentRuntime`.
|
||||
|
||||
Див. [Моделі](/uk/concepts/models) і [Slash-команди](/uk/tools/slash-commands).
|
||||
Див. [Моделі](/uk/concepts/models) і [Slash commands](/uk/tools/slash-commands).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як налаштувати швидкий режим для GPT 5.5?">
|
||||
<Accordion title="Як налаштувати fast mode для GPT 5.5?">
|
||||
Використовуйте перемикач сеансу або типове значення конфігурації:
|
||||
|
||||
- **Для окремого сеансу:** надішліть `/fast on`, поки сеанс використовує `openai/gpt-5.5` або `openai-codex/gpt-5.5`.
|
||||
- **Типове значення для моделі:** встановіть `agents.defaults.models["openai/gpt-5.5"].params.fastMode` або `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` у `true`.
|
||||
- **Типове значення для моделі:** установіть `agents.defaults.models["openai/gpt-5.5"].params.fastMode` або `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` на `true`.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -186,40 +187,39 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Для OpenAI швидкий режим відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Перевизначення сеансу `/fast` мають пріоритет над типовими значеннями конфігурації.
|
||||
Для OpenAI fast mode відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Сеансові перевизначення `/fast` мають пріоритет над типовими значеннями конфігурації.
|
||||
|
||||
Див. [Мислення і швидкий режим](/uk/tools/thinking) і [Швидкий режим OpenAI](/uk/providers/openai#fast-mode).
|
||||
Див. [Thinking і fast mode](/uk/tools/thinking) та [OpenAI fast mode](/uk/providers/openai#fast-mode).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Чому я бачу "Model ... is not allowed", а потім немає відповіді?'>
|
||||
Якщо `agents.defaults.models` встановлено, це стає **списком дозволених** для `/model` і будь-яких
|
||||
перевизначень сеансу. Вибір моделі, якої немає в цьому списку, повертає:
|
||||
Якщо встановлено `agents.defaults.models`, це стає **списком дозволених** для `/model` і будь-яких
|
||||
сеансових перевизначень. Вибір моделі, якої немає в цьому списку, повертає:
|
||||
|
||||
```
|
||||
Model "provider/model" is not allowed. Use /model to list available models.
|
||||
```
|
||||
|
||||
Ця помилка повертається **замість** звичайної відповіді. Виправлення: додайте модель до
|
||||
`agents.defaults.models`, видаліть список дозволених або виберіть модель із `/model list`.
|
||||
`agents.defaults.models`, вилучіть список дозволених або виберіть модель з `/model list`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Чому я бачу "Unknown model: minimax/MiniMax-M2.7"?'>
|
||||
Це означає, що **провайдера не налаштовано** (не знайдено конфігурації провайдера MiniMax або профілю
|
||||
автентифікації), тому модель неможливо розв'язати.
|
||||
Це означає, що **провайдера не налаштовано** (не знайдено конфігурацію провайдера MiniMax або профіль автентифікації), тож модель не можна розвʼязати.
|
||||
|
||||
Контрольний список виправлення:
|
||||
|
||||
1. Оновіться до поточного випуску OpenClaw (або запустіть із вихідного коду `main`), потім перезапустіть gateway.
|
||||
2. Переконайтеся, що MiniMax налаштовано (майстер або JSON), або що автентифікація MiniMax
|
||||
існує в env/профілях автентифікації, щоб відповідний провайдер можна було ін'єктувати
|
||||
1. Оновіться до поточного випуску OpenClaw (або запустіть із source `main`), потім перезапустіть gateway.
|
||||
2. Переконайтеся, що MiniMax налаштовано (майстром або JSON), або що автентифікація MiniMax
|
||||
існує в env/профілях автентифікації, щоб відповідний провайдер можна було інʼєктувати
|
||||
(`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений MiniMax
|
||||
OAuth для `minimax-portal`).
|
||||
3. Використовуйте точний ідентифікатор моделі (з урахуванням регістру) для вашого шляху автентифікації:
|
||||
`minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування з API-ключем,
|
||||
`minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування з API-key,
|
||||
або `minimax-portal/MiniMax-M2.7` /
|
||||
`minimax-portal/MiniMax-M2.7-highspeed` для налаштування OAuth.
|
||||
`minimax-portal/MiniMax-M2.7-highspeed` для налаштування з OAuth.
|
||||
4. Запустіть:
|
||||
|
||||
```bash
|
||||
@ -232,8 +232,8 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можна використовувати MiniMax як типову модель, а OpenAI — для складних завдань?">
|
||||
Так. Використовуйте **MiniMax як типову модель** і перемикайте моделі **для окремого сеансу**, коли потрібно.
|
||||
<Accordion title="Чи можу я використовувати MiniMax як типовий варіант, а OpenAI для складних завдань?">
|
||||
Так. Використовуйте **MiniMax як типовий варіант** і перемикайте моделі **для окремого сеансу**, коли потрібно.
|
||||
Резервні варіанти призначені для **помилок**, а не для "складних завдань", тому використовуйте `/model` або окремого агента.
|
||||
|
||||
**Варіант A: перемикання для окремого сеансу**
|
||||
@ -261,31 +261,31 @@ x-i18n:
|
||||
|
||||
**Варіант B: окремі агенти**
|
||||
|
||||
- Типова модель агента A: MiniMax
|
||||
- Типова модель агента B: OpenAI
|
||||
- Типове значення агента A: MiniMax
|
||||
- Типове значення агента B: OpenAI
|
||||
- Маршрутизуйте за агентом або використовуйте `/agent` для перемикання
|
||||
|
||||
Документація: [Моделі](/uk/concepts/models), [Маршрутизація кількох агентів](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai).
|
||||
Документація: [Моделі](/uk/concepts/models), [Multi-Agent Routing](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи є opus / sonnet / gpt вбудованими скороченнями?">
|
||||
Так. OpenClaw постачається з кількома типовими скороченнями (застосовуються лише тоді, коли модель існує в `agents.defaults.models`):
|
||||
Так. OpenClaw постачається з кількома типовими скороченнями (застосовуються лише коли модель існує в `agents.defaults.models`):
|
||||
|
||||
- `opus` → `anthropic/claude-opus-4-6`
|
||||
- `sonnet` → `anthropic/claude-sonnet-4-6`
|
||||
- `gpt` → `openai/gpt-5.5` для налаштувань з API-ключем або `openai-codex/gpt-5.5`, коли налаштовано Codex OAuth
|
||||
- `gpt` → `openai/gpt-5.5` для налаштувань з API-key або `openai-codex/gpt-5.5`, коли налаштовано Codex OAuth
|
||||
- `gpt-mini` → `openai/gpt-5.4-mini`
|
||||
- `gpt-nano` → `openai/gpt-5.4-nano`
|
||||
- `gemini` → `google/gemini-3.1-pro-preview`
|
||||
- `gemini-flash` → `google/gemini-3-flash-preview`
|
||||
- `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
|
||||
|
||||
Якщо ви задасте власний псевдонім із такою самою назвою, ваше значення матиме пріоритет.
|
||||
Якщо ви задасте власний псевдонім із тією самою назвою, ваше значення матиме пріоритет.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як визначити/перевизначити скорочення моделей (псевдоніми)?">
|
||||
<Accordion title="Як визначити або перевизначити скорочення моделей (псевдоніми)?">
|
||||
Псевдоніми беруться з `agents.defaults.models.<modelId>.alias`. Приклад:
|
||||
|
||||
```json5
|
||||
@ -303,12 +303,12 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Тоді `/model sonnet` (або `/<alias>`, коли підтримується) розв'язується в цей ідентифікатор моделі.
|
||||
Потім `/model sonnet` (або `/<alias>`, коли підтримується) розвʼязується в цей ідентифікатор моделі.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Як додати моделі від інших провайдерів, наприклад OpenRouter або Z.AI?">
|
||||
OpenRouter (оплата за токени; багато моделей):
|
||||
<Accordion title="Як додати моделі від інших провайдерів, як-от OpenRouter або Z.AI?">
|
||||
OpenRouter (оплата за токен; багато моделей):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -338,9 +338,9 @@ x-i18n:
|
||||
|
||||
Якщо ви посилаєтеся на постачальника/модель, але потрібний ключ постачальника відсутній, ви отримаєте помилку автентифікації під час виконання (наприклад, `No API key found for provider "zai"`).
|
||||
|
||||
**Ключ API для постачальника не знайдено після додавання нового агента**
|
||||
**Не знайдено API-ключ для постачальника після додавання нового агента**
|
||||
|
||||
Зазвичай це означає, що **новий агент** має порожнє сховище автентифікації. Автентифікація прив’язана до агента й
|
||||
Зазвичай це означає, що **новий агент** має порожнє сховище автентифікації. Автентифікація є окремою для кожного агента й
|
||||
зберігається в:
|
||||
|
||||
```
|
||||
@ -350,8 +350,8 @@ x-i18n:
|
||||
Варіанти виправлення:
|
||||
|
||||
- Запустіть `openclaw agents add <id>` і налаштуйте автентифікацію під час роботи майстра.
|
||||
- Або скопіюйте лише переносні статичні профілі `api_key` / `token` зі сховища автентифікації основного агента до сховища автентифікації нового агента.
|
||||
- Для профілів OAuth увійдіть із нового агента, коли йому потрібен власний обліковий запис; інакше OpenClaw може читати через стандартного/основного агента без клонування токенів оновлення.
|
||||
- Або скопіюйте лише портативні статичні профілі `api_key` / `token` зі сховища автентифікації основного агента до сховища автентифікації нового агента.
|
||||
- Для профілів OAuth увійдіть із нового агента, коли йому потрібен власний обліковий запис; інакше OpenClaw може читати з агента за замовчуванням/основного агента без клонування refresh-токенів.
|
||||
|
||||
**Не** використовуйте повторно `agentDir` для різних агентів; це спричиняє конфлікти автентифікації/сеансів.
|
||||
|
||||
@ -365,94 +365,94 @@ x-i18n:
|
||||
Резервне перемикання відбувається у два етапи:
|
||||
|
||||
1. **Ротація профілів автентифікації** у межах того самого постачальника.
|
||||
2. **Резервний перехід моделі** до наступної моделі в `agents.defaults.model.fallbacks`.
|
||||
2. **Резервне перемикання моделі** на наступну модель у `agents.defaults.model.fallbacks`.
|
||||
|
||||
Періоди охолодження застосовуються до профілів, що зазнають помилок (експоненційне відтермінування), тому OpenClaw може продовжувати відповідати, навіть коли постачальник обмежує частоту запитів або тимчасово не працює.
|
||||
Для проблемних профілів застосовуються періоди очікування (експоненційна затримка), тож OpenClaw може продовжувати відповідати, навіть коли постачальник обмежує частоту запитів або тимчасово не працює.
|
||||
|
||||
Сегмент обмеження частоти містить більше, ніж звичайні відповіді `429`. OpenClaw
|
||||
також розглядає повідомлення на кшталт `Too many concurrent requests`,
|
||||
Бакет обмеження частоти містить не лише звичайні відповіді `429`. OpenClaw
|
||||
також трактує повідомлення на кшталт `Too many concurrent requests`,
|
||||
`ThrottlingException`, `concurrency limit reached`,
|
||||
`workers_ai ... quota limit exceeded`, `resource exhausted` і періодичні
|
||||
обмеження вікна використання (`weekly/monthly limit reached`) як обмеження частоти,
|
||||
достатні для резервного перемикання.
|
||||
ліміти вікна використання (`weekly/monthly limit reached`) як обмеження
|
||||
частоти, що потребують резервного перемикання.
|
||||
|
||||
Деякі відповіді, схожі на білінгові, не є `402`, а деякі HTTP-відповіді `402`
|
||||
також залишаються в цьому тимчасовому сегменті. Якщо постачальник повертає
|
||||
явний білінговий текст для `401` або `403`, OpenClaw усе ще може залишити це
|
||||
в білінговій гілці, але специфічні для постачальника зіставлення тексту залишаються обмеженими
|
||||
постачальником, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402`
|
||||
натомість виглядає як придатне до повтору вікно використання або
|
||||
також залишаються в цьому тимчасовому бакеті. Якщо постачальник повертає
|
||||
явний білінговий текст на `401` або `403`, OpenClaw усе одно може залишити це
|
||||
в білінговій смузі, але специфічні для постачальника текстові збіги залишаються
|
||||
обмеженими постачальником, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402`
|
||||
натомість виглядає як повторюване вікно використання або
|
||||
ліміт витрат організації/робочого простору (`daily limit reached, resets tomorrow`,
|
||||
`organization spending limit exceeded`), OpenClaw розглядає його як
|
||||
`rate_limit`, а не як тривале вимкнення через білінг.
|
||||
`organization spending limit exceeded`), OpenClaw трактує його як
|
||||
`rate_limit`, а не як довге білінгове вимкнення.
|
||||
|
||||
Помилки переповнення контексту відрізняються: сигнатури на кшталт
|
||||
Помилки переповнення контексту інші: сигнатури на кшталт
|
||||
`request_too_large`, `input exceeds the maximum number of tokens`,
|
||||
`input token count exceeds the maximum number of input tokens`,
|
||||
`input is too long for the model` або `ollama error: context length
|
||||
exceeded` залишаються на шляху Compaction/повторної спроби, а не просувають
|
||||
резервний перехід моделі.
|
||||
exceeded` залишаються на шляху Compaction/повторної спроби замість просування до
|
||||
резервного перемикання моделі.
|
||||
|
||||
Загальний текст помилки сервера навмисно вужчий, ніж "будь-що з
|
||||
unknown/error у ньому". OpenClaw справді розглядає тимчасові форми, обмежені постачальником,
|
||||
як-от Anthropic bare `An unknown error occurred`, OpenRouter bare
|
||||
Універсальний текст серверної помилки навмисно вужчий, ніж "будь-що з
|
||||
unknown/error у ньому". OpenClaw справді трактує прив’язані до постачальника тимчасові форми,
|
||||
як-от Anthropic без додаткових даних `An unknown error occurred`, OpenRouter без додаткових даних
|
||||
`Provider returned error`, помилки причини зупинки на кшталт `Unhandled stop reason:
|
||||
error`, корисні навантаження JSON `api_error` із тимчасовим серверним текстом
|
||||
error`, JSON-навантаження `api_error` з тимчасовим серверним текстом
|
||||
(`internal server error`, `unknown error, 520`, `upstream error`, `backend
|
||||
error`) і помилки зайнятості постачальника, як-от `ModelNotReadyException`, як
|
||||
сигнали таймауту/перевантаження, достатні для резервного перемикання, коли контекст постачальника
|
||||
сигнали тайм-ауту/перевантаження, що потребують резервного перемикання, коли контекст постачальника
|
||||
збігається.
|
||||
Загальний внутрішній текст резервної помилки на кшталт `LLM request failed with an unknown
|
||||
error.` залишається консервативним і сам по собі не запускає резервний перехід моделі.
|
||||
Універсальний внутрішній текст резервного шляху, як-от `LLM request failed with an unknown
|
||||
error.`, залишається консервативним і сам по собі не запускає резервне перемикання моделі.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Що означає "No credentials found for profile anthropic:default"?'>
|
||||
Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації.
|
||||
Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти облікові дані для нього в очікуваному сховищі автентифікації.
|
||||
|
||||
**Контрольний список виправлення:**
|
||||
|
||||
- **Підтвердьте, де зберігаються профілі автентифікації** (нові та застарілі шляхи)
|
||||
- **Підтвердьте, де зберігаються профілі автентифікації** (нові й застарілі шляхи)
|
||||
- Поточний: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- Застарілий: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`)
|
||||
- **Підтвердьте, що ваша змінна середовища завантажується Gateway**
|
||||
- Якщо ви задали `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або ввімкніть `env.shellEnv`.
|
||||
- **Переконайтеся, що редагуєте правильного агента**
|
||||
- У конфігураціях із кількома агентами може бути кілька файлів `auth-profiles.json`.
|
||||
- **Підтвердьте, що ваша змінна середовища завантажена Gateway**
|
||||
- Якщо ви встановили `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або увімкніть `env.shellEnv`.
|
||||
- **Переконайтеся, що ви редагуєте правильного агента**
|
||||
- У налаштуваннях із кількома агентами може бути кілька файлів `auth-profiles.json`.
|
||||
- **Перевірте стан моделі/автентифікації**
|
||||
- Використайте `openclaw models status`, щоб побачити налаштовані моделі та чи автентифіковані постачальники.
|
||||
- Використайте `openclaw models status`, щоб побачити налаштовані моделі й чи автентифіковані постачальники.
|
||||
|
||||
**Контрольний список виправлення для "No credentials found for profile anthropic"**
|
||||
|
||||
Це означає, що запуск прив’язано до профілю автентифікації Anthropic, але Gateway
|
||||
Це означає, що запуск закріплено за профілем автентифікації Anthropic, але Gateway
|
||||
не може знайти його у своєму сховищі автентифікації.
|
||||
|
||||
- **Використайте Claude CLI**
|
||||
- Запустіть `openclaw models auth login --provider anthropic --method cli --set-default` на хості Gateway.
|
||||
- **Якщо натомість хочете використати ключ API**
|
||||
- Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості Gateway**.
|
||||
- Очистьте будь-який закріплений порядок, який примусово вимагає відсутній профіль:
|
||||
- Запустіть `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway.
|
||||
- **Якщо натомість ви хочете використати API-ключ**
|
||||
- Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**.
|
||||
- Очистьте будь-який закріплений порядок, який примусово використовує відсутній профіль:
|
||||
|
||||
```bash
|
||||
openclaw models auth order clear --provider anthropic
|
||||
```
|
||||
|
||||
- **Підтвердьте, що виконуєте команди на хості Gateway**
|
||||
- У віддаленому режимі профілі автентифікації зберігаються на машині Gateway, а не на вашому ноутбуці.
|
||||
- **Підтвердьте, що ви виконуєте команди на хості gateway**
|
||||
- У віддаленому режимі профілі автентифікації зберігаються на машині gateway, а не на вашому ноутбуці.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чому він також спробував Google Gemini і зазнав помилки?">
|
||||
Якщо ваша конфігурація моделі містить Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного переходу моделі. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`.
|
||||
<Accordion title="Чому він також спробував Google Gemini і зазнав невдачі?">
|
||||
Якщо ваша конфігурація моделі містить Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного перемикання моделі. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`.
|
||||
|
||||
Виправлення: або надайте автентифікацію Google, або вилучіть/уникайте моделей Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервний перехід не маршрутизував туди.
|
||||
Виправлення: або надайте автентифікацію Google, або видаліть/уникайте моделей Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервне перемикання не маршрутизувало туди.
|
||||
|
||||
**Запит LLM відхилено: потрібна сигнатура thinking (Google Antigravity)**
|
||||
**Запит LLM відхилено: потрібен підпис thinking (Google Antigravity)**
|
||||
|
||||
Причина: історія сеансу містить **блоки thinking без сигнатур** (часто з
|
||||
перерваного/часткового потоку). Google Antigravity вимагає сигнатури для блоків thinking.
|
||||
Причина: історія сеансу містить **блоки thinking без підписів** (часто з
|
||||
перерваного/часткового потоку). Google Antigravity вимагає підписів для блоків thinking.
|
||||
|
||||
Виправлення: OpenClaw тепер вилучає непідписані блоки thinking для Google Antigravity Claude. Якщо це все ще з’являється, почніть **новий сеанс** або встановіть `/thinking off` для цього агента.
|
||||
Виправлення: OpenClaw тепер видаляє непідписані блоки thinking для Google Antigravity Claude. Якщо це все ще з’являється, почніть **новий сеанс** або встановіть `/thinking off` для цього агента.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -463,7 +463,7 @@ x-i18n:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Що таке профіль автентифікації?">
|
||||
Профіль автентифікації — це іменований запис облікових даних (OAuth або ключ API), прив’язаний до постачальника. Профілі зберігаються в:
|
||||
Профіль автентифікації — це іменований запис облікових даних (OAuth або API-ключ), прив’язаний до постачальника. Профілі зберігаються в:
|
||||
|
||||
```
|
||||
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
|
||||
@ -471,25 +471,25 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Які типові ID профілів?">
|
||||
OpenClaw використовує ID із префіксом постачальника, як-от:
|
||||
<Accordion title="Які ID профілів типові?">
|
||||
OpenClaw використовує ID з префіксом постачальника, наприклад:
|
||||
|
||||
- `anthropic:default` (поширено, коли немає ідентичності електронної пошти)
|
||||
- `anthropic:default` (типово, коли немає ідентичності електронної пошти)
|
||||
- `anthropic:<email>` для ідентичностей OAuth
|
||||
- власні ID, які ви вибираєте (наприклад, `anthropic:work`)
|
||||
- власні ID, які ви обираєте (наприклад, `anthropic:work`)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Чи можу я керувати тим, який профіль автентифікації пробується першим?">
|
||||
<Accordion title="Чи можу я керувати тим, який профіль автентифікації буде спробовано першим?">
|
||||
Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного постачальника (`auth.order.<provider>`). Це **не** зберігає секрети; це зіставляє ID з постачальником/режимом і задає порядок ротації.
|
||||
|
||||
OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **періоді охолодження** (обмеження частоти/таймаути/помилки автентифікації) або в тривалішому **вимкненому** стані (білінг/недостатньо кредитів). Щоб це перевірити, запустіть `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`.
|
||||
OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **періоді очікування** (обмеження частоти/тайм-аути/збої автентифікації) або в довшому стані **вимкнено** (білінг/недостатньо кредитів). Щоб перевірити це, запустіть `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`.
|
||||
|
||||
Періоди охолодження через обмеження частоти можуть бути обмежені моделлю. Профіль, який охолоджується
|
||||
Періоди очікування через обмеження частоти можуть бути прив’язані до моделі. Профіль, який охолоджується
|
||||
для однієї моделі, усе ще може бути придатним для спорідненої моделі в того самого постачальника,
|
||||
тоді як білінгові/вимкнені вікна все одно блокують увесь профіль.
|
||||
|
||||
Ви також можете задати перевизначення порядку **для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI:
|
||||
Ви також можете встановити перевизначення порядку **для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI:
|
||||
|
||||
```bash
|
||||
# Defaults to the configured default agent (omit --agent)
|
||||
@ -511,31 +511,31 @@ x-i18n:
|
||||
openclaw models auth order set --provider anthropic --agent main anthropic:default
|
||||
```
|
||||
|
||||
Щоб перевірити, що фактично пробуватиметься, використайте:
|
||||
Щоб перевірити, що насправді буде спробовано, використайте:
|
||||
|
||||
```bash
|
||||
openclaw models status --probe
|
||||
```
|
||||
|
||||
Якщо збережений профіль пропущено в явному порядку, probe повідомляє
|
||||
`excluded_by_auth_order` для цього профілю замість того, щоб мовчки пробувати його.
|
||||
`excluded_by_auth_order` для цього профілю замість того, щоб непомітно спробувати його.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="OAuth чи ключ API — у чому різниця?">
|
||||
<Accordion title="OAuth чи API-ключ - у чому різниця?">
|
||||
OpenClaw підтримує обидва варіанти:
|
||||
|
||||
- **OAuth** часто використовує доступ за підпискою (де це застосовно).
|
||||
- **Ключі API** використовують оплату за токени.
|
||||
- **API-ключі** використовують оплату за токени.
|
||||
|
||||
Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і ключі API.
|
||||
Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API-ключі.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Пов’язано
|
||||
## Пов’язане
|
||||
|
||||
- [FAQ](/uk/help/faq) — основний FAQ
|
||||
- [FAQ — швидкий старт і початкове налаштування](/uk/help/faq-first-run)
|
||||
- [FAQ — швидкий старт і перше налаштування](/uk/help/faq-first-run)
|
||||
- [Вибір моделі](/uk/concepts/model-providers)
|
||||
- [Резервне перемикання моделей](/uk/concepts/model-failover)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,72 +1,62 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви змінюєте вбудоване середовище виконання агента або реєстр середовища агента
|
||||
- Ви реєструєте середовище агента з вбудованого або довіреного плагіна
|
||||
- Вам потрібно зрозуміти, як Plugin Codex пов’язаний із постачальниками моделей
|
||||
- Ви змінюєте вбудоване середовище виконання агента або реєстр обв'язок
|
||||
- Ви реєструєте обв’язку агента з вбудованого або довіреного Plugin
|
||||
- Потрібно розуміти, як плагін Codex пов’язаний із постачальниками моделей
|
||||
sidebarTitle: Agent Harness
|
||||
summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий виконавець вбудованого агента
|
||||
title: Плагіни середовища агента
|
||||
summary: Експериментальна поверхня SDK для Plugin, які замінюють низькорівневого вбудованого виконавця агента
|
||||
title: Плагіни обв’язки агента
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T07:50:15Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-02T02:37:22Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 340fc6207dabc6ffe7ffb9c07ca9e80e76f1034d4978c41279dc826468302181
|
||||
source_hash: b6e55d2df09c3965e1397be72f19dec2a6ed941ac8b7b01be8eee0f9713400dc
|
||||
source_path: plugins/sdk-agent-harness.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
**Середовище агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів.
|
||||
Для користувацької ментальної моделі див. [Середовища виконання агента](/uk/concepts/agent-runtimes).
|
||||
**Обв’язка агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделі, не канал і не реєстр інструментів. Для користувацької ментальної моделі див. [Середовища виконання агентів](/uk/concepts/agent-runtimes).
|
||||
|
||||
Використовуйте цю поверхню лише для вбудованих або довірених native-плагінів. Контракт
|
||||
досі є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний
|
||||
вбудований виконавець.
|
||||
Використовуйте цю поверхню лише для вбудованих або довірених нативних Plugin. Контракт досі експериментальний, бо типи параметрів навмисно віддзеркалюють поточний вбудований runner.
|
||||
|
||||
## Коли використовувати harness
|
||||
## Коли використовувати обв’язку
|
||||
|
||||
Реєструйте середовище агента, коли сімейство моделей має власне native-сеансове
|
||||
середовище виконання і звичайний транспорт постачальника OpenClaw є хибною абстракцією.
|
||||
Зареєструйте обв’язку агента, коли сімейство моделей має власне нативне середовище виконання сесій, а звичайний транспорт постачальника OpenClaw є неправильною абстракцією.
|
||||
|
||||
Приклади:
|
||||
|
||||
- native-сервер coding-agent, який володіє тредами та Compaction
|
||||
- локальний CLI або демон, який має стримити native-події plan/reasoning/tool
|
||||
- середовище виконання моделі, якому потрібен власний resume id на додачу до
|
||||
стенограми сеансу OpenClaw
|
||||
- нативний сервер агента для кодування, який володіє потоками й compaction
|
||||
- локальний CLI або daemon, який має транслювати нативні події плану/міркування/інструментів
|
||||
- середовище виконання моделі, якому потрібен власний ідентифікатор відновлення на додачу до стенограми сесії OpenClaw
|
||||
|
||||
**Не** реєструйте harness лише для додавання нового LLM API. Для звичайних HTTP або
|
||||
WebSocket API моделей створюйте [плагін постачальника](/uk/plugins/sdk-provider-plugins).
|
||||
Не реєструйте обв’язку лише для додавання нового LLM API. Для звичайних HTTP- або WebSocket-API моделей створіть [Plugin постачальника](/uk/plugins/sdk-provider-plugins).
|
||||
|
||||
## Чим усе ще володіє ядро
|
||||
## Чим досі володіє ядро
|
||||
|
||||
Перш ніж буде вибрано harness, OpenClaw уже розв’язав:
|
||||
Перш ніж буде вибрано обв’язку, OpenClaw уже розв’язав:
|
||||
|
||||
- постачальника і модель
|
||||
- стан автентифікації середовища виконання
|
||||
- рівень thinking і бюджет контексту
|
||||
- файл стенограми/сеансу OpenClaw
|
||||
- робочий простір, sandbox і політику інструментів
|
||||
- зворотні виклики відповіді каналу та зворотні виклики стримінгу
|
||||
- політику fallback моделі та live-перемикання моделей
|
||||
- стан авторизації середовища виконання
|
||||
- рівень мислення і бюджет контексту
|
||||
- файл стенограми/сесії OpenClaw
|
||||
- робочу область, sandbox і політику інструментів
|
||||
- callback-и відповіді каналу та callback-и streaming
|
||||
- політику fallback моделі й live перемикання моделей
|
||||
|
||||
Такий поділ навмисний. Harness виконує підготовлену спробу; він не вибирає
|
||||
постачальників, не замінює доставку каналу і не перемикає моделі непомітно.
|
||||
Цей поділ навмисний. Обв’язка виконує підготовлену спробу; вона не вибирає постачальників, не замінює доставлення каналом і не перемикає моделі непомітно.
|
||||
|
||||
Підготовлена спроба також містить `params.runtimePlan` — пакет політик, що належить OpenClaw, для рішень середовища виконання, які мають залишатися спільними між PI та native-harness:
|
||||
Підготовлена спроба також містить `params.runtimePlan`, пакет політик, яким володіє OpenClaw, для рішень середовища виконання, що мають залишатися спільними для PI та нативних обв’язок:
|
||||
|
||||
- `runtimePlan.tools.normalize(...)` і
|
||||
`runtimePlan.tools.logDiagnostics(...)` для політики схеми інструментів з урахуванням постачальника
|
||||
- `runtimePlan.transcript.resolvePolicy(...)` для політики санітизації стенограми та
|
||||
відновлення викликів інструментів
|
||||
- `runtimePlan.delivery.isSilentPayload(...)` для спільного приглушення доставки `NO_REPLY` і медіа
|
||||
`runtimePlan.tools.logDiagnostics(...)` для політики схем інструментів з урахуванням постачальника
|
||||
- `runtimePlan.transcript.resolvePolicy(...)` для санітизації стенограми й політики відновлення викликів інструментів
|
||||
- `runtimePlan.delivery.isSilentPayload(...)` для спільного `NO_REPLY` і приглушення доставлення медіа
|
||||
- `runtimePlan.outcome.classifyRunResult(...)` для класифікації fallback моделі
|
||||
- `runtimePlan.observability` для розв’язаних метаданих постачальника/моделі/harness
|
||||
- `runtimePlan.observability` для розв’язаних метаданих постачальника/моделі/обв’язки
|
||||
|
||||
Harness можуть використовувати план для рішень, які мають збігатися з поведінкою PI, але
|
||||
все одно повинні трактувати його як стан спроби, що належить хосту. Не змінюйте його і не використовуйте для
|
||||
перемикання постачальників/моделей усередині ходу.
|
||||
Обв’язки можуть використовувати план для рішень, які мають відповідати поведінці PI, але все одно повинні трактувати його як стан спроби, яким володіє host. Не змінюйте його й не використовуйте для перемикання постачальників/моделей усередині ходу.
|
||||
|
||||
## Зареєструвати harness
|
||||
## Зареєструвати обв’язку
|
||||
|
||||
**Імпорт:** `openclaw/plugin-sdk/agent-harness`
|
||||
|
||||
@ -76,7 +66,7 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
|
||||
const myHarness: AgentHarness = {
|
||||
id: "my-harness",
|
||||
label: "Моє native-середовище агента",
|
||||
label: "My native agent harness",
|
||||
|
||||
supports(ctx) {
|
||||
return ctx.provider === "my-provider"
|
||||
@ -85,17 +75,17 @@ const myHarness: AgentHarness = {
|
||||
},
|
||||
|
||||
async runAttempt(params) {
|
||||
// Запустіть або відновіть ваш native-тред.
|
||||
// Використовуйте params.prompt, params.tools, params.images, params.onPartialReply,
|
||||
// params.onAgentEvent та інші поля підготовленої спроби.
|
||||
// Start or resume your native thread.
|
||||
// Use params.prompt, params.tools, params.images, params.onPartialReply,
|
||||
// params.onAgentEvent, and the other prepared attempt fields.
|
||||
return await runMyNativeTurn(params);
|
||||
},
|
||||
};
|
||||
|
||||
export default definePluginEntry({
|
||||
id: "my-native-agent",
|
||||
name: "Мій Native Agent",
|
||||
description: "Запускає вибрані моделі через native-демон агента.",
|
||||
name: "My Native Agent",
|
||||
description: "Runs selected models through a native agent daemon.",
|
||||
register(api) {
|
||||
api.registerAgentHarness(myHarness);
|
||||
},
|
||||
@ -104,127 +94,62 @@ export default definePluginEntry({
|
||||
|
||||
## Політика вибору
|
||||
|
||||
OpenClaw вибирає harness після розв’язання постачальника/моделі:
|
||||
OpenClaw вибирає обв’язку після розв’язання постачальника/моделі:
|
||||
|
||||
1. Записаний id harness наявного сеансу має перевагу, тож зміни config/env не
|
||||
перемикають цю стенограму на інше середовище виконання «на гарячу».
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` примусово вибирає зареєстрований harness з цим id для
|
||||
сеансів, які ще не закріплені.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудований harness PI.
|
||||
4. `OPENCLAW_AGENT_RUNTIME=auto` запитує в зареєстрованих harness, чи підтримують вони розв’язану
|
||||
пару постачальник/модель.
|
||||
5. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо fallback PI
|
||||
не вимкнено.
|
||||
1. Перемагає записаний ідентифікатор обв’язки наявної сесії, тому зміни config/env не перемикають цю стенограму гаряче на інше середовище виконання.
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` примусово вибирає зареєстровану обв’язку з цим ідентифікатором для сесій, які ще не закріплено.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудовану обв’язку PI.
|
||||
4. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані обв’язки, чи підтримують вони розв’язаного постачальника/модель.
|
||||
5. Якщо жодна зареєстрована обв’язка не підходить, OpenClaw використовує PI, якщо fallback PI не вимкнено.
|
||||
|
||||
Помилки harness плагіна відображаються як помилки виконання. У режимі `auto` fallback на PI
|
||||
використовується лише тоді, коли жоден зареєстрований harness плагіна не підтримує розв’язану
|
||||
пару постачальник/модель. Щойно harness плагіна заявив про виконання, OpenClaw не
|
||||
повторює той самий хід через PI, оскільки це може змінити семантику автентифікації/середовища виконання
|
||||
або дублювати побічні ефекти.
|
||||
Збої обв’язок Plugin відображаються як збої запуску. У режимі `auto` fallback PI використовується лише тоді, коли жодна зареєстрована обв’язка Plugin не підтримує розв’язаного постачальника/модель. Щойно обв’язка Plugin заявила запуск, OpenClaw не відтворює той самий хід через PI, бо це може змінити семантику авторизації/середовища виконання або дублювати побічні ефекти.
|
||||
|
||||
Вибраний id harness зберігається разом з id сеансу після вбудованого запуску.
|
||||
Застарілі сеанси, створені до появи закріплення harness, вважаються закріпленими за PI, щойно в них
|
||||
з’являється історія стенограми. Використовуйте новий/скинутий сеанс, коли перемикаєтеся між PI та
|
||||
native-harness плагіна. `/status` показує нестандартні id harness, як-от `codex`,
|
||||
поруч із `Fast`; PI приховано, оскільки це типовий шлях сумісності.
|
||||
Якщо вибраний harness виглядає несподіваним, увімкніть журналювання налагодження `agents/harness` і
|
||||
перегляньте структурований запис gateway `agent harness selected`. Він містить
|
||||
вибраний id harness, причину вибору, політику runtime/fallback і, у режимі
|
||||
`auto`, результат підтримки для кожного кандидата-плагіна.
|
||||
Ідентифікатор вибраної обв’язки зберігається разом з ідентифікатором сесії після вбудованого запуску. Застарілі сесії, створені до закріплення обв’язок, вважаються закріпленими за PI, щойно вони мають історію стенограми. Використовуйте нову/скинуту сесію під час перемикання між PI і нативною обв’язкою Plugin. `/status` показує ідентифікатори обв’язок, відмінні від типових, наприклад `codex`, поруч із `Fast`; PI приховано, бо це типовий шлях сумісності. Якщо вибрана обв’язка несподівана, увімкніть debug-логування `agents/harness` і перегляньте структурований запис Gateway `agent harness selected`. Він містить ідентифікатор вибраної обв’язки, причину вибору, політику середовища виконання/fallback і, у режимі `auto`, результат підтримки кожного кандидата Plugin.
|
||||
|
||||
Вбудований плагін Codex реєструє `codex` як свій id harness. Ядро трактує це як
|
||||
звичайний id harness плагіна; специфічні для Codex аліаси мають належати плагіну
|
||||
або конфігурації оператора, а не спільному селектору середовища виконання.
|
||||
Вбудований Plugin Codex реєструє `codex` як свій ідентифікатор обв’язки. Ядро трактує це як звичайний ідентифікатор обв’язки Plugin; специфічні для Codex alias-и належать до Plugin або операторського config, а не до спільного селектора середовища виконання.
|
||||
|
||||
## Поєднання постачальника й harness
|
||||
## Пара постачальника й обв’язки
|
||||
|
||||
Більшість harness також мають реєструвати постачальника. Постачальник робить посилання на моделі,
|
||||
статус автентифікації, метадані моделі та вибір `/model` видимими для решти
|
||||
OpenClaw. Потім harness заявляє цей постачальник у `supports(...)`.
|
||||
Більшість обв’язок також мають реєструвати постачальника. Постачальник робить посилання моделей, стан авторизації, метадані моделей і вибір `/model` видимими для решти OpenClaw. Потім обв’язка заявляє цього постачальника в `supports(...)`.
|
||||
|
||||
Вбудований плагін Codex дотримується цієї схеми:
|
||||
Вбудований Plugin Codex дотримується цього шаблону:
|
||||
|
||||
- бажані користувацькі посилання на моделі: `openai/gpt-5.5` плюс
|
||||
- бажані користувацькі посилання моделей: `openai/gpt-5.5` плюс
|
||||
`agentRuntime.id: "codex"`
|
||||
- посилання сумісності: застарілі посилання `codex/gpt-*` усе ще приймаються, але нові
|
||||
конфігурації не повинні використовувати їх як звичайні посилання постачальник/модель
|
||||
- id harness: `codex`
|
||||
- auth: синтетична доступність постачальника, оскільки harness Codex володіє
|
||||
native-входом/сеансом Codex
|
||||
- запит app-server: OpenClaw надсилає до Codex чистий id моделі і дозволяє
|
||||
harness спілкуватися з native-протоколом app-server
|
||||
- посилання сумісності: застарілі посилання `codex/gpt-*` залишаються прийнятними, але нові config не повинні використовувати їх як звичайні посилання постачальника/моделі
|
||||
- ідентифікатор обв’язки: `codex`
|
||||
- авторизація: синтетична доступність постачальника, бо обв’язка Codex володіє нативним login/сесією Codex
|
||||
- запит app-server: OpenClaw надсилає Codex чистий ідентифікатор моделі й дозволяє обв’язці говорити нативним протоколом app-server
|
||||
|
||||
Плагін Codex є адитивним. Звичайні посилання `openai/gpt-*` і далі використовують
|
||||
звичайний шлях постачальника OpenClaw, якщо ви не примусите harness Codex через
|
||||
`agentRuntime.id: "codex"`. Старіші посилання `codex/gpt-*` для сумісності все ще вибирають
|
||||
постачальника і harness Codex.
|
||||
Plugin Codex є додатковим. Звичайні посилання `openai/gpt-*` продовжують використовувати нормальний шлях постачальника OpenClaw, якщо ви не примусите обв’язку Codex через `agentRuntime.id: "codex"`. Старіші посилання `codex/gpt-*` досі вибирають постачальника й обв’язку Codex для сумісності.
|
||||
|
||||
Для налаштування оператором, прикладів префіксів моделей і конфігурацій лише для Codex див.
|
||||
[Harness Codex](/uk/plugins/codex-harness).
|
||||
Для операторського налаштування, прикладів префіксів моделей і config лише для Codex див. [Обв’язка Codex](/uk/plugins/codex-harness).
|
||||
|
||||
OpenClaw вимагає Codex app-server версії `0.125.0` або новішої. Плагін Codex перевіряє
|
||||
initialize-handshake app-server і блокує старіші або неверсіоновані сервери, щоб
|
||||
OpenClaw працював лише з тією поверхнею протоколу, на якій його було протестовано. Поріг
|
||||
`0.125.0` включає підтримку native payload hook MCP, що з’явилася в Codex `0.124.0`,
|
||||
водночас прив’язуючи OpenClaw до новішої протестованої стабільної гілки.
|
||||
OpenClaw потребує Codex app-server `0.125.0` або новішого. Plugin Codex перевіряє initialize handshake app-server і блокує старіші або неверсійовані сервери, щоб OpenClaw запускався лише проти тієї поверхні протоколу, з якою його протестовано. Мінімальна версія `0.125.0` містить підтримку нативного payload MCP hook, що з’явилася в Codex `0.124.0`, водночас закріплюючи OpenClaw за новішою протестованою стабільною лінією.
|
||||
|
||||
### Проміжний шар результатів інструментів
|
||||
### Middleware результатів інструментів
|
||||
|
||||
Вбудовані плагіни можуть підключати нейтральний до середовища виконання проміжний шар результатів інструментів через
|
||||
`api.registerAgentToolResultMiddleware(...)`, коли їхній маніфест оголошує
|
||||
цільові id середовищ виконання в `contracts.agentToolResultMiddleware`. Цей довірений
|
||||
шов призначено для асинхронних перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex подадуть
|
||||
вивід інструмента назад у модель.
|
||||
Вбудовані Plugin можуть під’єднувати runtime-neutral middleware результатів інструментів через `api.registerAgentToolResultMiddleware(...)`, коли їхній manifest оголошує цільові ідентифікатори середовища виконання в `contracts.agentToolResultMiddleware`. Ця довірена точка розширення призначена для async-перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex передає вихід інструмента назад у модель.
|
||||
|
||||
Застарілі вбудовані плагіни все ще можуть використовувати
|
||||
`api.registerCodexAppServerExtensionFactory(...)` для проміжного шару лише для Codex app-server,
|
||||
але нові перетворення результатів мають використовувати нейтральний до середовища виконання API.
|
||||
Хук лише для Pi `api.registerEmbeddedExtensionFactory(...)` було видалено;
|
||||
перетворення результатів інструментів Pi мають використовувати нейтральний проміжний шар.
|
||||
Застарілі вбудовані Plugin досі можуть використовувати `api.registerCodexAppServerExtensionFactory(...)` для middleware лише Codex app-server, але нові перетворення результатів повинні використовувати runtime-neutral API. Hook лише для Pi `api.registerEmbeddedExtensionFactory(...)` вилучено; перетворення результатів інструментів Pi мають використовувати runtime-neutral middleware.
|
||||
|
||||
### Класифікація термінального результату
|
||||
### Класифікація кінцевого результату
|
||||
|
||||
Native-harness, які володіють власною проєкцією протоколу, можуть використовувати
|
||||
`classifyAgentHarnessTerminalOutcome(...)` з
|
||||
`openclaw/plugin-sdk/agent-harness-runtime`, коли завершений хід не породив
|
||||
видимого тексту помічника. Допоміжна функція повертає `empty`, `reasoning-only` або
|
||||
`planning-only`, щоб політика fallback OpenClaw могла вирішити, чи повторювати спробу на
|
||||
іншій моделі. Вона навмисно залишає некласифікованими помилки prompt, ходи в процесі виконання
|
||||
та навмисно тихі відповіді, такі як `NO_REPLY`.
|
||||
Нативні обв’язки, які володіють власною проєкцією протоколу, можуть використовувати `classifyAgentHarnessTerminalOutcome(...)` з `openclaw/plugin-sdk/agent-harness-runtime`, коли завершений хід не створив видимого тексту assistant. Помічник повертає `empty`, `reasoning-only` або `planning-only`, щоб політика fallback OpenClaw могла вирішити, чи повторювати спробу на іншій моделі. Він навмисно не класифікує помилки prompt, ходи в процесі та навмисні тихі відповіді, як-от `NO_REPLY`.
|
||||
|
||||
### Режим native-harness Codex
|
||||
### Нативний режим обв’язки Codex
|
||||
|
||||
Вбудований harness `codex` — це native-режим Codex для вбудованих ходів
|
||||
агента OpenClaw. Спочатку увімкніть вбудований плагін `codex` і додайте `codex` до
|
||||
`plugins.allow`, якщо у вашій конфігурації використовується обмежувальний allowlist. Конфігурації native app-server
|
||||
мають використовувати `openai/gpt-*` з `agentRuntime.id: "codex"`.
|
||||
Натомість використовуйте `openai-codex/*` для Codex OAuth через PI. Застарілі посилання моделей `codex/*`
|
||||
залишаються аліасами сумісності для native-harness.
|
||||
Вбудована обв’язка `codex` — це нативний режим Codex для вбудованих ходів агента OpenClaw. Спочатку увімкніть вбудований Plugin `codex` і додайте `codex` до `plugins.allow`, якщо ваш config використовує обмежувальний allowlist. Нативні config app-server повинні використовувати `openai/gpt-*` з `agentRuntime.id: "codex"`. Використовуйте `openai-codex/*` для Codex OAuth через PI натомість. Застарілі посилання моделей `codex/*` залишаються alias-ами сумісності для нативної обв’язки.
|
||||
|
||||
Коли цей режим працює, Codex володіє native id треду, поведінкою resume,
|
||||
Compaction і виконанням app-server. OpenClaw і далі володіє chat-каналом,
|
||||
дзеркалом видимої стенограми, політикою інструментів, погодженнями, доставкою медіа та
|
||||
вибором сеансу. Використовуйте `agentRuntime.id: "codex"` без перевизначення `fallback`,
|
||||
коли вам потрібно довести, що лише шлях app-server Codex може заявити це виконання.
|
||||
Явні runtime плагінів уже типово завершуються fail-closed. Установлюйте `fallback: "pi"`
|
||||
лише тоді, коли ви навмисно хочете, щоб PI обробляв відсутність вибору harness. Помилки Codex
|
||||
app-server уже завершуються безпосередньо, а не повторюються через PI.
|
||||
Коли цей режим виконується, Codex володіє нативним ідентифікатором потоку, поведінкою відновлення, compaction і виконанням app-server. OpenClaw досі володіє чат-каналом, видимим дзеркалом стенограми, політикою інструментів, approvals, доставленням медіа та вибором сесії. Використовуйте `agentRuntime.id: "codex"` без override `fallback`, коли потрібно довести, що лише шлях Codex app-server може заявити запуск. Явні середовища виконання Plugin уже типово fail closed. Установлюйте `fallback: "pi"` лише тоді, коли навмисно хочете, щоб PI обробляв відсутній вибір обв’язки. Збої Codex app-server уже завершуються напряму, а не повторюються через PI.
|
||||
|
||||
## Вимкнення fallback на PI
|
||||
## Вимкнути fallback PI
|
||||
|
||||
Типово OpenClaw запускає вбудованих агентів з `agents.defaults.agentRuntime`,
|
||||
встановленим у `{ id: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані harness
|
||||
плагінів можуть заявляти пару постачальник/модель. Якщо жоден не підходить, OpenClaw
|
||||
повертається до PI.
|
||||
Типово OpenClaw запускає вбудованих агентів з `agents.defaults.agentRuntime`, установленим на `{ id: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані обв’язки Plugin можуть заявити пару постачальник/модель. Якщо жодна не підходить, OpenClaw fallback-иться до PI.
|
||||
|
||||
У режимі `auto` встановлюйте `fallback: "none"`, коли вам потрібно, щоб відсутність вибору harness плагіна
|
||||
призводила до помилки, а не до використання PI. Явні runtime плагінів, як-от
|
||||
`runtime: "codex"`, уже типово завершуються fail-closed, якщо лише `fallback: "pi"` не
|
||||
задано в тій самій конфігурації або області перевизначення середовища. Помилки вибраного harness плагіна
|
||||
завжди є жорсткими збоями. Це не блокує явний `runtime: "pi"` або
|
||||
`OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
У режимі `auto` установіть `fallback: "none"`, коли потрібно, щоб відсутній вибір обв’язки Plugin завершувався збоєм замість використання PI. Явні середовища виконання Plugin, як-от `agentRuntime.id: "codex"`, уже типово fail closed, якщо `fallback: "pi"` не встановлено в тому самому config або області env override. Збої вибраних обв’язок Plugin завжди завершуються жорстким збоєм. Це не блокує явний `agentRuntime.id: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
|
||||
Для вбудованих запусків лише з Codex:
|
||||
Для вбудованих запусків лише Codex:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -239,9 +164,7 @@ app-server уже завершуються безпосередньо, а не
|
||||
}
|
||||
```
|
||||
|
||||
Якщо ви хочете, щоб будь-який зареєстрований harness плагіна заявляв відповідні моделі, але ніколи
|
||||
не хочете, щоб OpenClaw непомітно повертався до PI, залишайте `runtime: "auto"` і вимикайте
|
||||
fallback:
|
||||
Якщо ви хочете, щоб будь-яка зареєстрована обв’язка Plugin заявляла відповідні моделі, але не хочете, щоб OpenClaw непомітно fallback-ився до PI, залиште `runtime: "auto"` і вимкніть fallback:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -256,7 +179,7 @@ fallback:
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначення для окремих агентів використовують ту саму форму:
|
||||
Per-agent override-и використовують ту саму форму:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -281,9 +204,7 @@ fallback:
|
||||
}
|
||||
```
|
||||
|
||||
`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштоване середовище виконання. Використовуйте
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback на PI з
|
||||
середовища.
|
||||
`OPENCLAW_AGENT_RUNTIME` досі override-ить налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback PI із середовища.
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex \
|
||||
@ -291,51 +212,45 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
Коли fallback вимкнено, сеанс завершується рано з помилкою, якщо запитаний harness не
|
||||
зареєстровано, він не підтримує розв’язану пару постачальник/модель або завершується помилкою до
|
||||
породження побічних ефектів ходу. Це навмисно для розгортань лише з Codex і
|
||||
для live-тестів, які мають довести, що шлях app-server Codex справді використовується.
|
||||
Коли fallback вимкнено, сесія завершується рано збоєм, якщо запитану обв’язку не зареєстровано, вона не підтримує розв’язаного постачальника/модель або завершується збоєм до створення побічних ефектів ходу. Це навмисно для розгортань лише Codex і для live-тестів, які мають довести, що шлях Codex app-server справді використовується.
|
||||
|
||||
Це налаштування керує лише вбудованим harness агента. Воно не вимикає
|
||||
маршрутизацію зображень, відео, музики, TTS, PDF або іншого маршрутизування моделей, специфічного для постачальника.
|
||||
Це налаштування керує лише обв’язкою вбудованого агента. Воно не вимикає маршрутизацію моделей для зображень, відео, музики, TTS, PDF або інших можливостей, специфічних для постачальника.
|
||||
|
||||
## Native-сеанси та дзеркало стенограми
|
||||
## Нативні сесії та дзеркало стенограми
|
||||
|
||||
Harness може зберігати native id сеансу, id треду або daemon-side токен відновлення.
|
||||
Явно зберігайте цей зв’язок асоційованим із сеансом OpenClaw і продовжуйте
|
||||
дзеркалити видимий користувачу вивід помічника/інструментів у стенограму OpenClaw.
|
||||
Обв’язка може зберігати нативний ідентифікатор сесії, ідентифікатор потоку або resume token на боці daemon. Тримайте цю прив’язку явно пов’язаною із сесією OpenClaw і продовжуйте дзеркалити видимий для користувача вихід assistant/інструментів у стенограму OpenClaw.
|
||||
|
||||
Стенограма OpenClaw залишається шаром сумісності для:
|
||||
|
||||
- видимої в каналі історії сеансу
|
||||
- пошуку та індексації стенограми
|
||||
- перемикання назад до вбудованого harness PI на пізнішому ході
|
||||
- загальної поведінки `/new`, `/reset` і видалення сеансу
|
||||
- видимої в каналі історії сесії
|
||||
- пошуку й індексації стенограм
|
||||
- перемикання назад на вбудовану обв’язку PI в пізнішому ході
|
||||
- загальної поведінки `/new`, `/reset` і видалення сесій
|
||||
|
||||
Якщо ваш harness зберігає sidecar-зв’язування, реалізуйте `reset(...)`, щоб OpenClaw міг
|
||||
очистити його, коли пов’язаний сеанс OpenClaw скидається.
|
||||
Якщо ваша обв’язка зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її під час скидання власної сесії OpenClaw.
|
||||
|
||||
## Результати інструментів і медіа
|
||||
|
||||
Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу.
|
||||
Коли harness виконує динамічний виклик інструмента, повертайте результат інструмента
|
||||
назад через форму результату harness замість того, щоб самостійно надсилати медіа в канал.
|
||||
Core формує список інструментів OpenClaw і передає його в підготовлену спробу.
|
||||
Коли тестовий середовищний виконувач запускає динамічний виклик інструмента, повертайте результат інструмента через
|
||||
форму результату цього середовищного виконувача, а не надсилайте медіа каналу самостійно.
|
||||
|
||||
Це зберігає текст, зображення, відео, музику, TTS, погодження та виводи
|
||||
інструментів обміну повідомленнями на тому самому шляху доставки, що й у запусків на основі PI.
|
||||
Це зберігає текстові, графічні, відео-, музичні, TTS-, approval- та messaging-tool-виводи
|
||||
на тому самому шляху доставки, що й запуски на базі PI.
|
||||
|
||||
## Поточні обмеження
|
||||
|
||||
- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів досі
|
||||
- Публічний шлях імпорту є узагальненим, але деякі псевдоніми типів спроби/результату досі
|
||||
містять назви `Pi` для сумісності.
|
||||
- Установлення сторонніх harness є експериментальним. Віддавайте перевагу плагінам постачальників,
|
||||
доки вам не знадобиться native-сеансове середовище виконання.
|
||||
- Перемикання harness підтримується між ходами. Не перемикайте harness посеред ходу після того, як уже почалися native-інструменти, погодження, текст помічника або надсилання повідомлень.
|
||||
- Встановлення сторонніх середовищних виконувачів є експериментальним. Надавайте перевагу provider plugins,
|
||||
доки вам не знадобиться нативний runtime сеансу.
|
||||
- Перемикання середовищних виконувачів підтримується між ходами. Не перемикайте середовищні виконувачі
|
||||
посеред ходу після того, як уже почалися native tools, approvals, текст асистента або надсилання повідомлень.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview)
|
||||
- [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime)
|
||||
- [Плагіни постачальників](/uk/plugins/sdk-provider-plugins)
|
||||
- [Harness Codex](/uk/plugins/codex-harness)
|
||||
- [Допоміжні засоби Runtime](/uk/plugins/sdk-runtime)
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins)
|
||||
- [Codex Harness](/uk/plugins/codex-harness)
|
||||
- [Постачальники моделей](/uk/concepts/model-providers)
|
||||
|
||||
@ -1,84 +1,103 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете використовувати моделі OpenAI в OpenClaw
|
||||
- Вам потрібна автентифікація через передплату Codex замість API-ключів
|
||||
- Вам потрібна автентифікація через підписку Codex замість API-ключів
|
||||
- Вам потрібна суворіша поведінка виконання агента GPT-5
|
||||
summary: Використовуйте OpenAI через ключі API або передплату Codex в OpenClaw
|
||||
summary: Використовуйте OpenAI в OpenClaw за допомогою API-ключів або підписки Codex
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T22:03:36Z"
|
||||
generated_at: "2026-05-02T02:38:33Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: bd9a8f05d31800354307c6fd7beb8cd1eed3d234e5c1e939e895cd99658b540b
|
||||
source_hash: d7e98179f5a7d90289ed6cdad1c4dd03834f42e3fcc747d24c7d29a47e103392
|
||||
source_path: providers/openai.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenAI надає developer API для моделей GPT, а Codex також доступний як агент для програмування в плані ChatGPT через клієнти Codex від OpenAI. OpenClaw тримає ці поверхні окремо, щоб конфігурація залишалася передбачуваною.
|
||||
OpenAI надає API для розробників для моделей GPT, а Codex також доступний як
|
||||
агент для кодування в межах плану ChatGPT через клієнти Codex від OpenAI. OpenClaw тримає ці
|
||||
поверхні окремими, щоб конфігурація лишалася передбачуваною.
|
||||
|
||||
OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі вибирає маршрут провайдера/автентифікації; окреме налаштування runtime вибирає, хто виконує вбудований цикл агента:
|
||||
OpenClaw підтримує три маршрути родини OpenAI. Більшості підписників ChatGPT/Codex,
|
||||
яким потрібна поведінка Codex, слід використовувати нативне середовище виконання сервера застосунку Codex. Префікс
|
||||
моделі вибирає провайдера/назву моделі; окреме налаштування середовища виконання вибирає,
|
||||
хто виконує вбудований цикл агента:
|
||||
|
||||
- **Ключ API** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`)
|
||||
- **Підписка Codex через PI** — вхід ChatGPT/Codex з доступом за підпискою (моделі `openai-codex/*`)
|
||||
- **Обв’язка Codex app-server** — нативне виконання Codex app-server (моделі `openai/*` плюс `agents.defaults.agentRuntime.id: "codex"`)
|
||||
- **Ключ API** - прямий доступ до OpenAI Platform з оплатою за використання (`openai/*` models)
|
||||
- **Підписка Codex з нативним середовищем виконання Codex** - вхід через ChatGPT/Codex плюс виконання сервером застосунку Codex (`openai/*` models plus `agents.defaults.agentRuntime.id: "codex"`)
|
||||
- **Підписка Codex через PI** - вхід через ChatGPT/Codex зі звичайним раннером OpenClaw PI (`openai-codex/*` models)
|
||||
|
||||
OpenAI явно підтримує використання OAuth за підпискою в зовнішніх інструментах і робочих процесах на кшталт OpenClaw.
|
||||
OpenAI явно підтримує використання OAuth підписки в зовнішніх інструментах і робочих процесах на кшталт OpenClaw.
|
||||
|
||||
Провайдер, модель, runtime і канал — це окремі шари. Якщо ці мітки змішуються між собою, прочитайте [runtime агентів](/uk/concepts/agent-runtimes), перш ніж змінювати конфігурацію.
|
||||
Провайдер, модель, середовище виконання та канал є окремими шарами. Якщо ці мітки
|
||||
змішуються, прочитайте [середовища виконання агентів](/uk/concepts/agent-runtimes), перш ніж
|
||||
змінювати конфігурацію.
|
||||
|
||||
## Швидкий вибір
|
||||
|
||||
| Ціль | Використовуйте | Примітки |
|
||||
| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
|
||||
| Пряма оплата за ключем API | `openai/gpt-5.5` | Установіть `OPENAI_API_KEY` або запустіть onboarding ключа API OpenAI. |
|
||||
| GPT-5.5 з автентифікацією підписки ChatGPT/Codex | `openai-codex/gpt-5.5` | Стандартний маршрут PI для OAuth Codex. Найкращий перший вибір для налаштувань із підпискою. |
|
||||
| GPT-5.5 з нативною поведінкою Codex app-server | `openai/gpt-5.5` плюс `agentRuntime.id: "codex"` | Примусово вмикає обв’язку Codex app-server для цього посилання на модель. |
|
||||
| Генерація або редагування зображень | `openai/gpt-image-2` | Працює з `OPENAI_API_KEY` або OAuth OpenAI Codex. |
|
||||
| Зображення з прозорим фоном | `openai/gpt-image-1.5` | Використовуйте `outputFormat=png` або `webp` і `openai.background=transparent`. |
|
||||
| Ціль | Використовуйте | Примітки |
|
||||
| ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- |
|
||||
| Підписка ChatGPT/Codex з нативним середовищем виконання Codex | `openai/gpt-5.5` plus `agentRuntime.id: "codex"` | Рекомендоване налаштування Codex для більшості користувачів. Увійдіть за допомогою автентифікації `openai-codex`. |
|
||||
| Пряма оплата за ключем API | `openai/gpt-5.5` | Установіть `OPENAI_API_KEY` або запустіть онбординг ключа API OpenAI. |
|
||||
| Автентифікація підписки ChatGPT/Codex через PI | `openai-codex/gpt-5.5` | Використовуйте лише тоді, коли свідомо хочете звичайний раннер PI. |
|
||||
| Генерування або редагування зображень | `openai/gpt-image-2` | Працює з `OPENAI_API_KEY` або OpenAI Codex OAuth. |
|
||||
| Зображення з прозорим тлом | `openai/gpt-image-1.5` | Використовуйте `outputFormat=png` або `webp` і `openai.background=transparent`. |
|
||||
|
||||
## Мапа назв
|
||||
|
||||
Назви схожі, але не взаємозамінні:
|
||||
|
||||
| Назва, яку ви бачите | Шар | Значення |
|
||||
| Назва, яку ви бачите | Шар | Значення |
|
||||
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| `openai` | Префікс провайдера | Прямий маршрут API OpenAI Platform. |
|
||||
| `openai-codex` | Префікс провайдера | Маршрут OAuth/підписки OpenAI Codex через звичайний runner OpenClaw PI. |
|
||||
| Plugin `codex` | Plugin | Вбудований Plugin OpenClaw, який надає нативний runtime Codex app-server і керування чатом `/codex`. |
|
||||
| `agentRuntime.id: codex` | Runtime агента | Примусово використовує нативну обв’язку Codex app-server для вбудованих ходів. |
|
||||
| `/codex ...` | Набір команд чату | Прив’язує/керує потоками Codex app-server з розмови. |
|
||||
| `runtime: "acp", agentId: "codex"` | Маршрут сесії ACP | Явний fallback-шлях, який запускає Codex через ACP/acpx. |
|
||||
| `openai` | Префікс провайдера | Прямий маршрут API OpenAI Platform. |
|
||||
| `openai-codex` | Префікс провайдера | Маршрут OpenAI Codex OAuth/підписки через звичайний раннер OpenClaw PI. |
|
||||
| `codex` plugin | Plugin | Вбудований Plugin OpenClaw, який надає нативне середовище виконання сервера застосунку Codex і керування чатом `/codex`. |
|
||||
| `agentRuntime.id: codex` | Середовище виконання агента | Примусово використовувати нативну обв’язку сервера застосунку Codex для вбудованих ходів. |
|
||||
| `/codex ...` | Набір чат-команд | Прив’язувати/керувати потоками сервера застосунку Codex із розмови. |
|
||||
| `runtime: "acp", agentId: "codex"` | Маршрут сесії ACP | Явний резервний шлях, який запускає Codex через ACP/acpx. |
|
||||
|
||||
Це означає, що конфігурація може навмисно містити і `openai-codex/*`, і Plugin `codex`. Це коректно, коли потрібен OAuth Codex через PI, а також доступне нативне керування чатом `/codex`. `openclaw doctor` попереджає про таку комбінацію, щоб ви могли підтвердити, що вона навмисна; він не переписує її.
|
||||
Це означає, що конфігурація може навмисно містити і `openai-codex/*`, і
|
||||
`codex` plugin. Це коректно, коли вам потрібен Codex OAuth через PI і також потрібні
|
||||
доступні нативні елементи керування чатом `/codex`. `openclaw doctor` попереджає про цю
|
||||
комбінацію, щоб ви могли підтвердити, що вона навмисна; він не переписує її.
|
||||
|
||||
<Note>
|
||||
GPT-5.5 доступна як через прямий доступ за ключем API OpenAI Platform, так і через маршрути підписки/OAuth. Використовуйте `openai/gpt-5.5` для прямого трафіку `OPENAI_API_KEY`, `openai-codex/gpt-5.5` для OAuth Codex через PI або `openai/gpt-5.5` з `agentRuntime.id: "codex"` для нативної обв’язки Codex app-server.
|
||||
GPT-5.5 доступна як через прямий доступ ключем API OpenAI Platform, так і через
|
||||
маршрути підписки/OAuth. Для підписки ChatGPT/Codex плюс нативного виконання Codex
|
||||
використовуйте `openai/gpt-5.5` з `agentRuntime.id: "codex"`. Використовуйте
|
||||
`openai-codex/gpt-5.5` лише для Codex OAuth через PI, або `openai/gpt-5.5`
|
||||
без перевизначення середовища виконання Codex для прямого трафіку `OPENAI_API_KEY`.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не вмикає вбудований Plugin Codex app-server. OpenClaw вмикає цей Plugin лише тоді, коли ви явно вибираєте нативну обв’язку Codex за допомогою `agentRuntime.id: "codex"` або використовуєте застаріле посилання на модель `codex/*`.
|
||||
Якщо вбудований Plugin `codex` увімкнено, але `openai-codex/*` усе ще визначається через PI, `openclaw doctor` попереджає і залишає маршрут без змін.
|
||||
Увімкнення OpenAI plugin або вибір моделі `openai-codex/*` не
|
||||
вмикає вбудований plugin сервера застосунку Codex. OpenClaw вмикає цей plugin лише
|
||||
коли ви явно вибираєте нативну обв’язку Codex за допомогою
|
||||
`agentRuntime.id: "codex"` або використовуєте застаріле посилання на модель `codex/*`.
|
||||
Якщо вбудований `codex` plugin увімкнено, але `openai-codex/*` усе ще обробляється
|
||||
через PI, `openclaw doctor` попереджає і залишає маршрут без змін.
|
||||
</Note>
|
||||
|
||||
## Покриття можливостей OpenClaw
|
||||
|
||||
| Можливість OpenAI | Поверхня OpenClaw | Статус |
|
||||
| Можливість OpenAI | Поверхня OpenClaw | Статус |
|
||||
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| Чат / Responses | Провайдер моделей `openai/<model>` | Так |
|
||||
| Моделі підписки Codex | `openai-codex/<model>` з OAuth `openai-codex` | Так |
|
||||
| Обв’язка Codex app-server | `openai/<model>` з `agentRuntime.id: codex` | Так |
|
||||
| Серверний вебпошук | Нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і провайдер не закріплено |
|
||||
| Зображення | `image_generate` | Так |
|
||||
| Відео | `video_generate` | Так |
|
||||
| Text-to-speech | `messages.tts.provider: "openai"` / `tts` | Так |
|
||||
| Пакетне speech-to-text | `tools.media.audio` / розуміння медіа | Так |
|
||||
| Потокове speech-to-text | Voice Call `streaming.provider: "openai"` | Так |
|
||||
| Голос у реальному часі | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так |
|
||||
| Embeddings | Провайдер embedding для пам’яті | Так |
|
||||
| Чат / Responses | Провайдер моделі `openai/<model>` | Так |
|
||||
| Моделі підписки Codex | `openai-codex/<model>` з `openai-codex` OAuth | Так |
|
||||
| Обв’язка сервера застосунку Codex | `openai/<model>` з `agentRuntime.id: codex` | Так |
|
||||
| Серверний вебпошук | Нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і провайдера не закріплено |
|
||||
| Зображення | `image_generate` | Так |
|
||||
| Відео | `video_generate` | Так |
|
||||
| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так |
|
||||
| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так |
|
||||
| Потокове перетворення мовлення на текст | Голосовий виклик `streaming.provider: "openai"` | Так |
|
||||
| Голос у реальному часі | Голосовий виклик `realtime.provider: "openai"` / Control UI Talk | Так |
|
||||
| Ембеддинги | Провайдер ембеддингів пам’яті | Так |
|
||||
|
||||
## Embeddings пам’яті
|
||||
## Ембеддинги пам’яті
|
||||
|
||||
OpenClaw може використовувати OpenAI або сумісний з OpenAI endpoint embeddings для індексації `memory_search` і embeddings запитів:
|
||||
OpenClaw може використовувати OpenAI або OpenAI-сумісну кінцеву точку ембеддингів для
|
||||
індексації `memory_search` і ембеддингів запитів:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -93,7 +112,11 @@ OpenClaw може використовувати OpenAI або сумісний
|
||||
}
|
||||
```
|
||||
|
||||
Для сумісних з OpenAI endpoint, які потребують асиметричних міток embeddings, задайте `queryInputType` і `documentInputType` у `memorySearch`. OpenClaw передає їх як специфічні для провайдера поля запиту `input_type`: embeddings запитів використовують `queryInputType`; проіндексовані фрагменти пам’яті та пакетна індексація використовують `documentInputType`. Повний приклад див. у [довіднику конфігурації пам’яті](/uk/reference/memory-config#provider-specific-config).
|
||||
Для OpenAI-сумісних кінцевих точок, яким потрібні асиметричні мітки ембеддингів, установіть
|
||||
`queryInputType` і `documentInputType` у `memorySearch`. OpenClaw передає
|
||||
їх як специфічні для провайдера поля запиту `input_type`: ембеддинги запитів використовують
|
||||
`queryInputType`; індексовані фрагменти пам’яті та пакетна індексація використовують
|
||||
`documentInputType`. Див. повний приклад у [довіднику конфігурації пам’яті](/uk/reference/memory-config#provider-specific-config).
|
||||
|
||||
## Початок роботи
|
||||
|
||||
@ -104,10 +127,10 @@ OpenClaw може використовувати OpenAI або сумісний
|
||||
**Найкраще для:** прямого доступу до API та оплати за використання.
|
||||
|
||||
<Steps>
|
||||
<Step title="Отримайте ключ API">
|
||||
<Step title="Отримайте свій ключ API">
|
||||
Створіть або скопіюйте ключ API з [панелі OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
</Step>
|
||||
<Step title="Запустіть onboarding">
|
||||
<Step title="Запустіть онбординг">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-api-key
|
||||
```
|
||||
@ -127,14 +150,17 @@ OpenClaw може використовувати OpenAI або сумісний
|
||||
|
||||
### Підсумок маршруту
|
||||
|
||||
| Посилання на модель | Конфігурація runtime | Маршрут | Автентифікація |
|
||||
| Посилання на модель | Конфігурація середовища виконання | Маршрут | Автентифікація |
|
||||
| ---------------------- | -------------------------- | --------------------------- | ---------------- |
|
||||
| `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Обв’язка Codex app-server | Codex app-server |
|
||||
| `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Обв’язка сервера застосунку Codex | Сервер застосунку Codex |
|
||||
|
||||
<Note>
|
||||
`openai/*` — це прямий маршрут ключа API OpenAI, якщо ви явно не примусите використання обв’язки Codex app-server. Використовуйте `openai-codex/*` для OAuth Codex через стандартний runner PI або `openai/gpt-5.5` з `agentRuntime.id: "codex"` для нативного виконання Codex app-server.
|
||||
`openai/*` є прямим маршрутом ключа API OpenAI, якщо ви явно не примусите
|
||||
обв’язку сервера застосунку Codex. Використовуйте `openai-codex/*` для Codex OAuth через
|
||||
стандартний раннер PI або використовуйте `openai/gpt-5.5` з
|
||||
`agentRuntime.id: "codex"` для нативного виконання сервером застосунку Codex.
|
||||
</Note>
|
||||
|
||||
### Приклад конфігурації
|
||||
@ -153,10 +179,10 @@ OpenClaw може використовувати OpenAI або сумісний
|
||||
</Tab>
|
||||
|
||||
<Tab title="Підписка Codex">
|
||||
**Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого ключа API. Codex cloud потребує входу ChatGPT.
|
||||
**Найкраще для:** використання вашої підписки ChatGPT/Codex з нативним виконанням сервером застосунку Codex замість окремого ключа API. Хмара Codex потребує входу в ChatGPT.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть OAuth Codex">
|
||||
<Step title="Запустіть Codex OAuth">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-codex
|
||||
```
|
||||
@ -167,77 +193,95 @@ OpenClaw може використовувати OpenAI або сумісний
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
Для headless-середовищ або налаштувань, де callback незручний, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість callback браузера localhost:
|
||||
Для безголових налаштувань або середовищ, ворожих до callback, додайте `--device-code`, щоб увійти через потік коду пристрою ChatGPT замість callback браузера localhost:
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --device-code
|
||||
```
|
||||
</Step>
|
||||
<Step title="Установіть стандартну модель">
|
||||
<Step title="Використайте нативне середовище виконання Codex">
|
||||
```bash
|
||||
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
|
||||
openclaw config set plugins.entries.codex '{ enabled: true }' --strict-json --merge
|
||||
openclaw config set agents.defaults.model.primary openai/gpt-5.5
|
||||
openclaw config set agents.defaults.agentRuntime '{ id: "codex", fallback: "none" }' --strict-json
|
||||
```
|
||||
</Step>
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
<Step title="Перевірте, що автентифікація Codex доступна">
|
||||
```bash
|
||||
openclaw models list --provider openai-codex
|
||||
```
|
||||
|
||||
Після запуску gateway надішліть `/codex status` або `/codex models`
|
||||
у чаті, щоб перевірити нативне середовище виконання сервера застосунку.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Підсумок маршруту
|
||||
|
||||
| Посилання на модель | Конфігурація runtime | Маршрут | Автентифікація |
|
||||
| Посилання на модель | Конфігурація середовища виконання | Маршрут | Автентифікація |
|
||||
|-----------|----------------|-------|------|
|
||||
| `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | OAuth ChatGPT/Codex через PI | Вхід Codex |
|
||||
| `openai-codex/gpt-5.4-mini` | omitted / `runtime: "pi"` | OAuth ChatGPT/Codex через PI | Вхід Codex |
|
||||
| `openai-codex/gpt-5.5` | `runtime: "auto"` | Усе ще PI, якщо Plugin явно не оголошує `openai-codex` | Вхід Codex |
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Обв’язка Codex app-server | Автентифікація Codex app-server |
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Нативна обв’язка сервера застосунку Codex | Вхід Codex або вибраний профіль `openai-codex` |
|
||||
| `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | ChatGPT/Codex OAuth через PI | Вхід Codex |
|
||||
| `openai-codex/gpt-5.4-mini` | omitted / `runtime: "pi"` | ChatGPT/Codex OAuth через PI | Вхід Codex |
|
||||
| `openai-codex/gpt-5.5` | `runtime: "auto"` | Усе ще PI, якщо plugin явно не заявляє `openai-codex` | Вхід Codex |
|
||||
|
||||
<Note>
|
||||
Продовжуйте використовувати id провайдера `openai-codex` для команд автентифікації/профілю. Префікс моделі `openai-codex/*` також є явним маршрутом PI для OAuth Codex. Він не вибирає і не вмикає автоматично вбудовану обв’язку Codex app-server.
|
||||
Продовжуйте використовувати ідентифікатор провайдера `openai-codex` для команд автентифікації/профілю. Префікс моделі
|
||||
`openai-codex/*` також є явним маршрутом PI для Codex OAuth.
|
||||
Він не вибирає й не вмикає автоматично вбудовану обв’язку app-server Codex. Для
|
||||
поширеного налаштування з підпискою і native runtime увійдіть через
|
||||
`openai-codex`, але залиште посилання на модель як `openai/gpt-5.5` і задайте
|
||||
`agentRuntime.id: "codex"`.
|
||||
</Note>
|
||||
|
||||
### Приклад конфігурації
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } },
|
||||
plugins: { entries: { codex: { enabled: true } } },
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "openai/gpt-5.5" },
|
||||
agentRuntime: { id: "codex", fallback: "none" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Щоб натомість залишити Codex OAuth на звичайному runner PI, використовуйте
|
||||
`openai-codex/gpt-5.5` і опустіть перевизначення runtime Codex.
|
||||
|
||||
<Note>
|
||||
Onboarding більше не імпортує матеріал OAuth з `~/.codex`. Увійдіть через OAuth у браузері (стандартно) або через потік device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента.
|
||||
Onboarding більше не імпортує матеріали OAuth із `~/.codex`. Увійдіть через browser OAuth (типово) або через flow device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агентів.
|
||||
</Note>
|
||||
|
||||
### Індикатор статусу
|
||||
### Індикатор стану
|
||||
|
||||
Chat `/status` показує, яке середовище виконання моделі активне для поточного сеансу.
|
||||
Стандартна обв’язка PI відображається як `Runtime: OpenClaw Pi Default`. Коли вибрано
|
||||
вбудовану обв’язку Codex app-server, `/status` показує
|
||||
`Runtime: OpenAI Codex`. Наявні сеанси зберігають записаний ідентифікатор обв’язки, тому використовуйте
|
||||
Chat `/status` показує, який runtime моделі активний для поточної сесії.
|
||||
Типова обв’язка PI відображається як `Runtime: OpenClaw Pi Default`. Коли
|
||||
вибрано вбудовану обв’язку app-server Codex, `/status` показує
|
||||
`Runtime: OpenAI Codex`. Наявні сесії зберігають записаний ідентифікатор обв’язки, тому використовуйте
|
||||
`/new` або `/reset` після зміни `agentRuntime`, якщо хочете, щоб `/status`
|
||||
відображав новий вибір PI/Codex.
|
||||
|
||||
### Попередження Doctor
|
||||
### Попередження doctor
|
||||
|
||||
Якщо вбудований Plugin `codex` увімкнено, коли вибрано маршрут
|
||||
`openai-codex/*` цієї вкладки, `openclaw doctor` попереджає, що модель
|
||||
досі визначається через PI. Залиште конфігурацію без змін, якщо це
|
||||
очікуваний маршрут автентифікації за підпискою. Перемикайтеся на `openai/<model>` плюс
|
||||
`agentRuntime.id: "codex"` лише тоді, коли потрібне нативне виконання
|
||||
Codex app-server.
|
||||
Якщо вбудований plugin `codex` увімкнено, коли вибрано маршрут `openai-codex/*`,
|
||||
`openclaw doctor` попереджає, що модель усе ще resolve через PI.
|
||||
Залишайте конфігурацію без змін лише тоді, коли цей маршрут автентифікації підписки PI
|
||||
є навмисним. Перейдіть на `openai/<model>` плюс `agentRuntime.id: "codex"`, коли
|
||||
потрібне native виконання app-server Codex.
|
||||
|
||||
### Обмеження контекстного вікна
|
||||
### Ліміт контекстного вікна
|
||||
|
||||
OpenClaw розглядає метадані моделі та обмеження контексту середовища виконання як окремі значення.
|
||||
OpenClaw розглядає metadata моделі й ліміт runtime context як окремі значення.
|
||||
|
||||
Для `openai-codex/gpt-5.5` через Codex OAuth:
|
||||
|
||||
- Нативний `contextWindow`: `1000000`
|
||||
- Стандартне обмеження `contextTokens` середовища виконання: `272000`
|
||||
- Native `contextWindow`: `1000000`
|
||||
- Типовий ліміт runtime `contextTokens`: `272000`
|
||||
|
||||
Менше стандартне обмеження на практиці має кращі характеристики затримки та якості. Перевизначте його за допомогою `contextTokens`:
|
||||
Менший типовий ліміт на практиці має кращі характеристики затримки та якості. Перевизначте його за допомогою `contextTokens`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -252,24 +296,24 @@ OpenClaw може використовувати OpenAI або сумісний
|
||||
```
|
||||
|
||||
<Note>
|
||||
Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту середовища виконання.
|
||||
Використовуйте `contextWindow`, щоб оголошувати native metadata моделі. Використовуйте `contextTokens`, щоб обмежувати бюджет runtime context.
|
||||
</Note>
|
||||
|
||||
### Відновлення каталогу
|
||||
|
||||
OpenClaw використовує метадані upstream-каталогу Codex для `gpt-5.5`, коли вони
|
||||
наявні. Якщо live-виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, коли
|
||||
OpenClaw використовує upstream metadata каталогу Codex для `gpt-5.5`, коли вона
|
||||
присутня. Якщо live discovery Codex пропускає рядок `openai-codex/gpt-5.5`, коли
|
||||
обліковий запис автентифіковано, OpenClaw синтезує цей рядок моделі OAuth, щоб
|
||||
cron, субагент і запуски зі сконфігурованою стандартною моделлю не завершувалися помилкою
|
||||
cron, sub-agent і запуски з налаштованою типовою моделлю не завершувалися помилкою
|
||||
`Unknown model`.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Нативна автентифікація Codex app-server
|
||||
## Native автентифікація app-server Codex
|
||||
|
||||
Нативна обв’язка Codex app-server використовує посилання на моделі `openai/*` плюс
|
||||
`agentRuntime.id: "codex"`, але її автентифікація все одно прив’язана до облікового запису. OpenClaw
|
||||
Native обв’язка app-server Codex використовує посилання на моделі `openai/*` плюс
|
||||
`agentRuntime.id: "codex"`, але її автентифікація все одно базується на обліковому записі. OpenClaw
|
||||
вибирає автентифікацію в такому порядку:
|
||||
|
||||
1. Явний профіль автентифікації OpenClaw `openai-codex`, прив’язаний до агента.
|
||||
@ -278,29 +322,29 @@ OpenClaw може використовувати OpenAI або сумісний
|
||||
`OPENAI_API_KEY`, коли app-server повідомляє, що облікового запису немає, але все ще потребує
|
||||
автентифікації OpenAI.
|
||||
|
||||
Це означає, що локальний вхід за підпискою ChatGPT/Codex не замінюється лише
|
||||
через те, що процес Gateway також має `OPENAI_API_KEY` для прямих моделей OpenAI
|
||||
або embeddings. Резервний env API-ключ використовується лише для локального stdio-шляху без облікового запису; він
|
||||
не надсилається до WebSocket-з’єднань app-server. Коли вибрано профіль Codex
|
||||
підпискового типу, OpenClaw також не передає `CODEX_API_KEY` і `OPENAI_API_KEY`
|
||||
Це означає, що локальний вхід із підпискою ChatGPT/Codex не замінюється лише
|
||||
через те, що процес gateway також має `OPENAI_API_KEY` для прямих моделей OpenAI
|
||||
або embeddings. Fallback через env API-key — це лише локальний шлях stdio без облікового запису; його
|
||||
не надсилають до WebSocket-з’єднань app-server. Коли вибрано профіль Codex
|
||||
у стилі підписки, OpenClaw також не передає `CODEX_API_KEY` і `OPENAI_API_KEY`
|
||||
у породжений дочірній процес stdio app-server і надсилає вибрані облікові дані
|
||||
через RPC входу app-server.
|
||||
через login RPC app-server.
|
||||
|
||||
## Генерування зображень
|
||||
## Генерація зображень
|
||||
|
||||
Вбудований Plugin `openai` реєструє генерування зображень через інструмент `image_generate`.
|
||||
Він підтримує як генерування зображень за API-ключем OpenAI, так і генерування зображень через Codex OAuth
|
||||
Вбудований plugin `openai` реєструє генерацію зображень через інструмент `image_generate`.
|
||||
Він підтримує як генерацію зображень за OpenAI API-key, так і генерацію зображень через Codex OAuth
|
||||
через те саме посилання на модель `openai/gpt-image-2`.
|
||||
|
||||
| Можливість | API-ключ OpenAI | Codex OAuth |
|
||||
| Можливість | OpenAI API key | Codex OAuth |
|
||||
| ------------------------ | ---------------------------------- | ------------------------------------ |
|
||||
| Посилання на модель | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||||
| Автентифікація | `OPENAI_API_KEY` | Вхід через OpenAI Codex OAuth |
|
||||
| Автентифікація | `OPENAI_API_KEY` | Вхід OpenAI Codex OAuth |
|
||||
| Транспорт | OpenAI Images API | Backend Codex Responses |
|
||||
| Макс. зображень на запит | 4 | 4 |
|
||||
| Режим редагування | Увімкнено (до 5 референсних зображень) | Увімкнено (до 5 референсних зображень) |
|
||||
| Перевизначення розміру | Підтримується, зокрема розміри 2K/4K | Підтримується, зокрема розміри 2K/4K |
|
||||
| Співвідношення сторін / роздільна здатність | Не передається до OpenAI Images API | Зіставляється з підтримуваним розміром, коли це безпечно |
|
||||
| Режим редагування | Увімкнено (до 5 reference images) | Увімкнено (до 5 reference images) |
|
||||
| Перевизначення розміру | Підтримуються, включно з розмірами 2K/4K | Підтримуються, включно з розмірами 2K/4K |
|
||||
| Aspect ratio / resolution | Не передається до OpenAI Images API | Зіставляється з підтримуваним розміром, коли це безпечно |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -313,24 +357,24 @@ OpenClaw може використовувати OpenAI або сумісний
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерування зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
Див. [Генерація зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
</Note>
|
||||
|
||||
`gpt-image-2` є стандартним для генерування зображень із тексту OpenAI і для редагування зображень.
|
||||
`gpt-image-1.5`, `gpt-image-1` і `gpt-image-1-mini` лишаються доступними як
|
||||
явні перевизначення моделі. Використовуйте `openai/gpt-image-1.5` для виводу
|
||||
PNG/WebP із прозорим фоном; поточний API `gpt-image-2` відхиляє
|
||||
`gpt-image-2` є типовим для генерації OpenAI text-to-image і редагування зображень.
|
||||
`gpt-image-1.5`, `gpt-image-1` і `gpt-image-1-mini` залишаються придатними як
|
||||
явні перевизначення моделі. Використовуйте `openai/gpt-image-1.5` для виводу PNG/WebP
|
||||
із прозорим фоном; поточний API `gpt-image-2` відхиляє
|
||||
`background: "transparent"`.
|
||||
|
||||
Для запиту з прозорим фоном агенти мають викликати `image_generate` з
|
||||
`model: "openai/gpt-image-1.5"`, `outputFormat: "png"` або `"webp"` і
|
||||
`background: "transparent"`; старіший параметр провайдера `openai.background`
|
||||
досі приймається. OpenClaw також захищає публічні маршрути OpenAI та
|
||||
OpenAI Codex OAuth, переписуючи стандартні прозорі запити `openai/gpt-image-2`
|
||||
на `gpt-image-1.5`; Azure і власні OpenAI-сумісні endpoints зберігають
|
||||
сконфігуровані назви deployment/моделей.
|
||||
досі приймається. OpenClaw також захищає публічні маршрути OpenAI і
|
||||
OpenAI Codex OAuth, переписуючи типові прозорі запити `openai/gpt-image-2`
|
||||
на `gpt-image-1.5`; Azure і користувацькі OpenAI-сумісні endpoints зберігають
|
||||
свої налаштовані deployment/model names.
|
||||
|
||||
Той самий параметр доступний для headless-запусків CLI:
|
||||
Те саме налаштування доступне для headless запусків CLI:
|
||||
|
||||
```bash
|
||||
openclaw infer image generate \
|
||||
@ -342,19 +386,18 @@ openclaw infer image generate \
|
||||
```
|
||||
|
||||
Використовуйте ті самі прапорці `--output-format` і `--background` з
|
||||
`openclaw infer image edit`, коли починаєте з вхідного файлу.
|
||||
`--openai-background` лишається доступним як специфічний для OpenAI псевдонім.
|
||||
`openclaw infer image edit`, коли починаєте з input file.
|
||||
`--openai-background` залишається доступним як alias, специфічний для OpenAI.
|
||||
|
||||
Для встановлень Codex OAuth залишайте те саме посилання `openai/gpt-image-2`. Коли
|
||||
налаштовано OAuth-профіль `openai-codex`, OpenClaw визначає збережений access token OAuth
|
||||
налаштовано профіль OAuth `openai-codex`, OpenClaw resolve збережений access token OAuth
|
||||
і надсилає запити зображень через backend Codex Responses. Він
|
||||
спершу не пробує `OPENAI_API_KEY` і не виконує тихий fallback до API-ключа для цього
|
||||
запиту. Налаштуйте `models.providers.openai` явно з API-ключем,
|
||||
власною базовою URL-адресою або endpoint Azure, коли потрібен прямий маршрут OpenAI Images API
|
||||
натомість.
|
||||
Якщо цей власний endpoint зображень розташований у довіреній LAN/приватній адресі, також задайте
|
||||
не пробує спершу `OPENAI_API_KEY` і не виконує тихий fallback до API key для цього
|
||||
запиту. Явно налаштуйте `models.providers.openai` з API key,
|
||||
користувацьким base URL або Azure endpoint, коли натомість потрібен прямий маршрут OpenAI Images API.
|
||||
Якщо цей користувацький image endpoint розташований у довіреній LAN/приватній адресі, також задайте
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw залишає
|
||||
приватні/внутрішні OpenAI-сумісні endpoints зображень заблокованими, якщо цього opt-in
|
||||
приватні/внутрішні OpenAI-сумісні image endpoints заблокованими, якщо цього opt-in
|
||||
немає.
|
||||
|
||||
Згенерувати:
|
||||
@ -375,16 +418,16 @@ openclaw infer image generate \
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
## Генерування відео
|
||||
## Генерація відео
|
||||
|
||||
Вбудований Plugin `openai` реєструє генерування відео через інструмент `video_generate`.
|
||||
Вбудований plugin `openai` реєструє генерацію відео через інструмент `video_generate`.
|
||||
|
||||
| Можливість | Значення |
|
||||
| ---------------- | --------------------------------------------------------------------------------- |
|
||||
| Стандартна модель | `openai/sora-2` |
|
||||
| Режими | Текст-у-відео, зображення-у-відео, редагування одного відео |
|
||||
| Референсні вхідні дані | 1 зображення або 1 відео |
|
||||
| Перевизначення розміру | Підтримується |
|
||||
| Типова модель | `openai/sora-2` |
|
||||
| Режими | Text-to-video, image-to-video, single-video edit |
|
||||
| Reference inputs | 1 зображення або 1 відео |
|
||||
| Перевизначення розміру | Підтримуються |
|
||||
| Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента |
|
||||
|
||||
```json5
|
||||
@ -398,22 +441,22 @@ openclaw infer image generate \
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Генерування відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
Див. [Генерація відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
</Note>
|
||||
|
||||
## Внесок GPT-5 у prompt
|
||||
## Внесок промпта GPT-5
|
||||
|
||||
OpenClaw додає спільний внесок GPT-5 у prompt для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x не отримують.
|
||||
OpenClaw додає спільний внесок промпта GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за model id, тому `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x — ні.
|
||||
|
||||
Вбудована нативна обв’язка Codex використовує ту саму поведінку GPT-5 і overlay Heartbeat через інструкції розробника Codex app-server, тому сеанси `openai/gpt-5.x`, примусово спрямовані через `agentRuntime.id: "codex"`, зберігають ті самі настанови щодо доведення справ до кінця й проактивного Heartbeat, хоча рештою prompt обв’язки керує Codex.
|
||||
Вбудована native обв’язка Codex використовує ту саму поведінку GPT-5 і overlay heartbeat через developer instructions app-server Codex, тому сесії `openai/gpt-5.x`, примусово спрямовані через `agentRuntime.id: "codex"`, зберігають ті самі настанови follow-through і проактивного heartbeat, хоча Codex володіє рештою промпта обв’язки.
|
||||
|
||||
Внесок GPT-5 додає тегований контракт поведінки для збереження persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей, специфічна для каналу, і поведінка silent-message лишаються у спільному системному prompt OpenClaw і політиці вихідної доставки. Настанови GPT-5 завжди увімкнені для відповідних моделей. Дружній шар стилю взаємодії є окремим і налаштовуваним.
|
||||
Внесок GPT-5 додає tagged behavior contract для збереження persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Channel-specific поведінка відповідей і silent-message залишається у спільному system prompt OpenClaw і outbound delivery policy. Настанови GPT-5 завжди увімкнені для відповідних моделей. Friendly interaction-style layer є окремим і налаштовуваним.
|
||||
|
||||
| Значення | Ефект |
|
||||
| --------------------- | ------------------------------------------ |
|
||||
| `"friendly"` (стандартно) | Увімкнути дружній шар стилю взаємодії |
|
||||
| `"on"` | Псевдонім для `"friendly"` |
|
||||
| `"off"` | Вимкнути лише дружній шар стилю |
|
||||
| Значення | Ефект |
|
||||
| ---------------------- | ------------------------------------------ |
|
||||
| `"friendly"` (типово) | Увімкнути friendly interaction-style layer |
|
||||
| `"on"` | Alias для `"friendly"` |
|
||||
| `"off"` | Вимкнути лише friendly style layer |
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Конфігурація">
|
||||
@ -437,33 +480,33 @@ OpenClaw додає спільний внесок GPT-5 у prompt для зап
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
Значення не чутливі до регістру під час виконання, тому `"Off"` і `"off"` обидва вимикають дружній шар стилю.
|
||||
Під час runtime значення не залежать від регістру, тому `"Off"` і `"off"` обидва вимикають friendly style layer.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Застарілий `plugins.entries.openai.config.personality` досі читається як fallback сумісності, коли спільний параметр `agents.defaults.promptOverlays.gpt5.personality` не задано.
|
||||
Застарілий `plugins.entries.openai.config.personality` досі читається як compatibility fallback, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано.
|
||||
</Note>
|
||||
|
||||
## Голос і мовлення
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Синтез мовлення (TTS)">
|
||||
Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`.
|
||||
Вбудований plugin `openai` реєструє синтез мовлення для surface `messages.tts`.
|
||||
|
||||
| Параметр | Шлях конфігурації | Стандартно |
|
||||
| Налаштування | Шлях конфігурації | Типово |
|
||||
|---------|------------|---------|
|
||||
| Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
|
||||
| Голос | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| Швидкість | `messages.tts.providers.openai.speed` | (не задано) |
|
||||
| Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) |
|
||||
| Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів |
|
||||
| API-ключ | `messages.tts.providers.openai.apiKey` | fallback до `OPENAI_API_KEY` |
|
||||
| Базова URL-адреса | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
| API-ключ | `messages.tts.providers.openai.apiKey` | Резервно використовує `OPENAI_API_KEY` |
|
||||
| Базовий URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
| Додаткове тіло | `messages.tts.providers.openai.extraBody` / `extra_body` | (не задано) |
|
||||
|
||||
Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
|
||||
|
||||
`extraBody` об’єднується з JSON запиту `/audio/speech` після згенерованих OpenClaw полів, тому використовуйте його для OpenAI-сумісних endpoints, які потребують додаткових ключів, як-от `lang`. Prototype-ключі ігноруються.
|
||||
`extraBody` об’єднується з JSON запиту `/audio/speech` після полів, згенерованих OpenClaw, тому використовуйте його для OpenAI-сумісних кінцевих точок, які потребують додаткових ключів, як-от `lang`. Ключі прототипу ігноруються.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -478,23 +521,23 @@ OpenClaw додає спільний внесок GPT-5 у prompt для зап
|
||||
```
|
||||
|
||||
<Note>
|
||||
Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базову URL-адресу TTS, не впливаючи на endpoint chat API.
|
||||
Задайте `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на кінцеву точку API чату.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Мовлення в текст">
|
||||
Вбудований Plugin `openai` реєструє пакетне перетворення мовлення в текст через
|
||||
поверхню транскрипції media-understanding OpenClaw.
|
||||
Вбудований plugin `openai` реєструє пакетне перетворення мовлення в текст через
|
||||
поверхню транскрипції для розуміння медіа в OpenClaw.
|
||||
|
||||
- Стандартна модель: `gpt-4o-transcribe`
|
||||
- Типова модель: `gpt-4o-transcribe`
|
||||
- Кінцева точка: OpenAI REST `/v1/audio/transcriptions`
|
||||
- Шлях введення: завантаження аудіофайлу multipart
|
||||
- Підтримується OpenClaw усюди, де транскрибування вхідного аудіо використовує
|
||||
`tools.media.audio`, зокрема сегменти голосових каналів Discord і
|
||||
аудіовкладення каналів
|
||||
- Підтримується OpenClaw всюди, де вхідна аудіотранскрипція використовує
|
||||
`tools.media.audio`, зокрема сегменти голосових каналів Discord і аудіовкладення
|
||||
каналів
|
||||
|
||||
Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо:
|
||||
Щоб примусово використовувати OpenAI для транскрипції вхідного аудіо:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -514,53 +557,53 @@ OpenClaw додає спільний внесок GPT-5 у prompt для зап
|
||||
}
|
||||
```
|
||||
|
||||
Підказки щодо мови та промпта передаються до OpenAI, коли їх надає
|
||||
спільна конфігурація аудіомедіа або запит транскрибування окремого виклику.
|
||||
Підказки мови та промпта передаються в OpenAI, коли їх надано через
|
||||
спільну конфігурацію аудіомедіа або запит транскрипції для окремого виклику.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Транскрибування в реальному часі">
|
||||
Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call.
|
||||
<Accordion title="Транскрипція в реальному часі">
|
||||
Вбудований plugin `openai` реєструє транскрипцію в реальному часі для Voice Call plugin.
|
||||
|
||||
| Налаштування | Шлях конфігурації | Стандартне значення |
|
||||
| Налаштування | Шлях конфігурації | Типово |
|
||||
|---------|------------|---------|
|
||||
| Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
|
||||
| Мова | `...openai.language` | (не встановлено) |
|
||||
| Промпт | `...openai.prompt` | (не встановлено) |
|
||||
| Мова | `...openai.language` | (не задано) |
|
||||
| Промпт | `...openai.prompt` | (не задано) |
|
||||
| Тривалість тиші | `...openai.silenceDurationMs` | `800` |
|
||||
| Поріг VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| Ключ API | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант |
|
||||
| API-ключ | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` |
|
||||
|
||||
<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>
|
||||
|
||||
<Accordion title="Голос у реальному часі">
|
||||
Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call.
|
||||
Вбудований plugin `openai` реєструє голос у реальному часі для Voice Call plugin.
|
||||
|
||||
| Налаштування | Шлях конфігурації | Стандартне значення |
|
||||
| Налаштування | Шлях конфігурації | Типово |
|
||||
|---------|------------|---------|
|
||||
| Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
|
||||
| Голос | `...openai.voice` | `alloy` |
|
||||
| Температура | `...openai.temperature` | `0.8` |
|
||||
| Поріг VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| Тривалість тиші | `...openai.silenceDurationMs` | `500` |
|
||||
| Ключ API | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант |
|
||||
| API-ключ | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment` для серверних мостів реального часу. Підтримує двоспрямовані виклики інструментів. Використовує аудіоформат G.711 u-law.
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment` для бекенд-мостів реального часу. Підтримує двонапрямлені виклики інструментів. Використовує аудіоформат G.711 u-law.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Control UI Talk використовує браузерні сесії OpenAI у реальному часі з
|
||||
ефемерним клієнтським секретом, створеним Gateway, і прямим браузерним обміном WebRTC SDP з
|
||||
OpenAI Realtime API. Жива перевірка для супровідників доступна через
|
||||
ефемерним клієнтським секретом, виданим Gateway, і прямим браузерним обміном WebRTC SDP з
|
||||
OpenAI Realtime API. Жива перевірка супровідником доступна через
|
||||
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`;
|
||||
гілка OpenAI створює клієнтський секрет у Node, генерує браузерну пропозицію SDP
|
||||
з фейковим мікрофонним медіа, надсилає її до OpenAI і застосовує відповідь SDP
|
||||
без логування секретів.
|
||||
гілка OpenAI створює клієнтський секрет у Node, генерує браузерну SDP-пропозицію
|
||||
з фіктивним медіа мікрофона, надсилає її в OpenAI і застосовує SDP-відповідь
|
||||
без журналювання секретів.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -569,27 +612,27 @@ OpenClaw додає спільний внесок GPT-5 у prompt для зап
|
||||
## Кінцеві точки Azure OpenAI
|
||||
|
||||
Вбудований провайдер `openai` може націлюватися на ресурс Azure OpenAI для генерації
|
||||
зображень через перевизначення базової URL-адреси. На шляху генерації зображень OpenClaw
|
||||
зображень шляхом перевизначення базового 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.
|
||||
і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у реальному часі**
|
||||
у розділі [Голос і мовлення](#voice-and-speech) для його налаштувань Azure.
|
||||
</Note>
|
||||
|
||||
Використовуйте Azure OpenAI, коли:
|
||||
|
||||
- У вас уже є підписка Azure OpenAI, квота або корпоративна угода
|
||||
- У вас уже є передплата Azure OpenAI, квота або корпоративна угода
|
||||
- Вам потрібні регіональне розміщення даних або засоби контролю відповідності, які надає Azure
|
||||
- Ви хочете залишити трафік усередині наявного тенанта Azure
|
||||
- Ви хочете утримувати трафік у межах наявного тенанту Azure
|
||||
|
||||
### Конфігурація
|
||||
|
||||
Для генерації зображень Azure через вбудований провайдер `openai` спрямуйте
|
||||
`models.providers.openai.baseUrl` на свій ресурс Azure і встановіть `apiKey` як
|
||||
Для генерації зображень Azure через вбудований провайдер `openai` вкажіть
|
||||
`models.providers.openai.baseUrl` на ваш ресурс Azure і задайте `apiKey` як
|
||||
ключ Azure OpenAI (не ключ OpenAI Platform):
|
||||
|
||||
```json5
|
||||
@ -605,8 +648,7 @@ OpenClaw додає спільний внесок GPT-5 у prompt для зап
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw розпізнає ці суфікси хостів Azure для маршруту генерації зображень
|
||||
Azure:
|
||||
OpenClaw розпізнає ці суфікси хостів Azure для маршруту генерації зображень Azure:
|
||||
|
||||
- `*.openai.azure.com`
|
||||
- `*.services.ai.azure.com`
|
||||
@ -615,73 +657,73 @@ Azure:
|
||||
Для запитів генерації зображень на розпізнаному хості Azure OpenClaw:
|
||||
|
||||
- Надсилає заголовок `api-key` замість `Authorization: Bearer`
|
||||
- Використовує шляхи з областю deployment (`/openai/deployments/{deployment}/...`)
|
||||
- Використовує шляхи з областю розгортання (`/openai/deployments/{deployment}/...`)
|
||||
- Додає `?api-version=...` до кожного запиту
|
||||
- Використовує стандартний тайм-аут запиту 600 с для викликів генерації зображень Azure.
|
||||
Значення `timeoutMs` для окремого виклику й далі перевизначають це стандартне значення.
|
||||
- Використовує типовий тайм-аут запиту 600 с для викликів генерації зображень Azure.
|
||||
Значення `timeoutMs` для окремого виклику все одно перевизначають це типове значення.
|
||||
|
||||
Інші базові URL-адреси (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартну
|
||||
Інші базові URL (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартну
|
||||
форму запиту зображень OpenAI.
|
||||
|
||||
<Note>
|
||||
Маршрутизація Azure для шляху генерації зображень провайдера `openai` потребує
|
||||
OpenClaw 2026.4.22 або новішої версії. Раніші версії обробляють будь-який користувацький
|
||||
`openai.baseUrl` як публічну кінцеву точку OpenAI і завершаться помилкою з
|
||||
deployment зображень Azure.
|
||||
`openai.baseUrl` як публічну кінцеву точку OpenAI і зазнають помилки з розгортаннями
|
||||
зображень Azure.
|
||||
</Note>
|
||||
|
||||
### Версія API
|
||||
|
||||
Встановіть `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview- або GA-версію Azure
|
||||
Задайте `AZURE_OPENAI_API_VERSION`, щоб закріпити конкретну preview- або GA-версію Azure
|
||||
для шляху генерації зображень Azure:
|
||||
|
||||
```bash
|
||||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
|
||||
Стандартне значення — `2024-12-01-preview`, коли змінну не встановлено.
|
||||
Типове значення — `2024-12-01-preview`, коли змінну не задано.
|
||||
|
||||
### Назви моделей є назвами deployment
|
||||
### Імена моделей є іменами розгортань
|
||||
|
||||
Azure OpenAI прив'язує моделі до deployment. Для запитів генерації зображень Azure,
|
||||
Azure OpenAI прив’язує моделі до розгортань. Для запитів генерації зображень Azure,
|
||||
маршрутизованих через вбудований провайдер `openai`, поле `model` в OpenClaw
|
||||
має бути **назвою deployment Azure**, яку ви налаштували на порталі Azure, а не
|
||||
ідентифікатором публічної моделі OpenAI.
|
||||
має бути **іменем розгортання Azure**, яке ви налаштували на порталі Azure, а не
|
||||
публічним id моделі OpenAI.
|
||||
|
||||
Якщо ви створюєте deployment із назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`:
|
||||
Якщо ви створюєте розгортання з назвою `gpt-image-2-prod`, яке обслуговує `gpt-image-2`:
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
|
||||
```
|
||||
|
||||
Те саме правило назви deployment застосовується до викликів генерації зображень,
|
||||
маршрутизованих через вбудований провайдер `openai`.
|
||||
Те саме правило імені розгортання застосовується до викликів генерації зображень, маршрутизованих через
|
||||
вбудований провайдер `openai`.
|
||||
|
||||
### Регіональна доступність
|
||||
|
||||
Генерація зображень Azure наразі доступна лише в частині регіонів
|
||||
Генерація зображень Azure наразі доступна лише в підмножині регіонів
|
||||
(наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
|
||||
`uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням
|
||||
deployment і підтвердьте, що конкретна модель пропонується у вашому регіоні.
|
||||
`uaenorth`). Перевірте поточний список регіонів Microsoft перед створенням
|
||||
розгортання та підтвердьте, що конкретна модель пропонується у вашому регіоні.
|
||||
|
||||
### Відмінності параметрів
|
||||
|
||||
Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень.
|
||||
Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні
|
||||
значення `background` для `gpt-image-2`), або надавати їх лише для конкретних версій
|
||||
моделі. Ці відмінності походять від Azure і базової моделі, а не від
|
||||
OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте
|
||||
набір параметрів, який підтримують ваш конкретний deployment і версія API на
|
||||
значення `background` на `gpt-image-2`), або надавати їх лише в окремих версіях
|
||||
моделей. Ці відмінності походять від Azure і базової моделі, а не від
|
||||
OpenClaw. Якщо запит Azure зазнає помилки перевірки, перевірте
|
||||
набір параметрів, підтримуваний вашим конкретним розгортанням і версією API, на
|
||||
порталі Azure.
|
||||
|
||||
<Note>
|
||||
Azure OpenAI використовує нативний транспорт і compat-поведінку, але не отримує
|
||||
Azure OpenAI використовує нативний транспорт і сумісну поведінку, але не отримує
|
||||
прихованих заголовків атрибуції OpenClaw — див. акордеон **Нативні та OpenAI-сумісні
|
||||
маршрути** в розділі [Розширена конфігурація](#advanced-configuration).
|
||||
маршрути** у розділі [Розширена конфігурація](#advanced-configuration).
|
||||
|
||||
Для трафіку chat або Responses в Azure (поза генерацією зображень) використовуйте
|
||||
процес onboarding або спеціальну конфігурацію провайдера Azure — самого лише
|
||||
`openai.baseUrl` недостатньо, щоб застосувати форму Azure API/auth. Існує окремий
|
||||
Для трафіку чату або Responses в Azure (поза генерацією зображень) використовуйте
|
||||
процес онбордингу або спеціальну конфігурацію провайдера Azure — одного лише `openai.baseUrl`
|
||||
недостатньо, щоб підхопити форму API/автентифікації Azure. Існує окремий
|
||||
провайдер `azure-openai-responses/*`; див. акордеон Server-side compaction нижче.
|
||||
</Note>
|
||||
|
||||
@ -689,17 +731,17 @@ Azure OpenAI використовує нативний транспорт і com
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Транспорт (WebSocket проти SSE)">
|
||||
OpenClaw використовує WebSocket як пріоритетний варіант із запасним SSE (`"auto"`) для `openai/*` і `openai-codex/*`.
|
||||
OpenClaw використовує підхід WebSocket-first із резервним SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`.
|
||||
|
||||
У режимі `"auto"` OpenClaw:
|
||||
- Повторює одну ранню невдалу спробу WebSocket перед переходом на SSE
|
||||
- Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження
|
||||
- Додає стабільні заголовки ідентичності сесії та turn для повторних спроб і повторних підключень
|
||||
- Повторює одну ранню помилку WebSocket перед переходом на SSE
|
||||
- Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час періоду охолодження
|
||||
- Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і повторних підключень
|
||||
- Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту
|
||||
|
||||
| Значення | Поведінка |
|
||||
|-------|----------|
|
||||
| `"auto"` (стандартно) | Спочатку WebSocket, SSE як запасний варіант |
|
||||
| `"auto"` (типово) | Спочатку WebSocket, резервно SSE |
|
||||
| `"sse"` | Примусово лише SSE |
|
||||
| `"websocket"` | Примусово лише WebSocket |
|
||||
|
||||
@ -720,14 +762,14 @@ Azure OpenAI використовує нативний транспорт і com
|
||||
}
|
||||
```
|
||||
|
||||
Пов'язані документи OpenAI:
|
||||
Пов’язані документи OpenAI:
|
||||
- [Realtime API з WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Потокові відповіді API (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Прогрівання WebSocket">
|
||||
OpenClaw стандартно вмикає прогрівання WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого turn.
|
||||
<Accordion title="Прогрів WebSocket">
|
||||
OpenClaw вмикає прогрів WebSocket типово для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу.
|
||||
|
||||
```json5
|
||||
// Disable warm-up
|
||||
@ -749,10 +791,10 @@ Azure OpenAI використовує нативний транспорт і com
|
||||
<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
|
||||
{
|
||||
@ -767,13 +809,13 @@ Azure OpenAI використовує нативний транспорт і com
|
||||
```
|
||||
|
||||
<Note>
|
||||
Перевизначення сесії мають перевагу над конфігурацією. Очищення перевизначення сесії в Sessions UI повертає сесію до налаштованого стандартного значення.
|
||||
Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого типового значення.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Пріоритетна обробка (service_tier)">
|
||||
API OpenAI надає пріоритетну обробку через `service_tier`. Встановіть її для кожної моделі в OpenClaw:
|
||||
API OpenAI надає пріоритетну обробку через `service_tier`. Задайте її для кожної моделі в OpenClaw:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -790,19 +832,19 @@ Azure OpenAI використовує нативний транспорт і com
|
||||
Підтримувані значення: `auto`, `default`, `flex`, `priority`.
|
||||
|
||||
<Warning>
|
||||
`serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з провайдерів через проксі, OpenClaw залишає `service_tier` без змін.
|
||||
`serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви спрямовуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Серверна Compaction (Responses API)">
|
||||
Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) потокова обгортка Pi-harness Plugin OpenAI автоматично вмикає серверну Compaction:
|
||||
Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) обгортка потоку Pi-harness Plugin OpenAI автоматично вмикає серверну Compaction:
|
||||
|
||||
- Примусово встановлює `store: true` (якщо model compat не встановлює `supportsStore: false`)
|
||||
- Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- Стандартне значення `compact_threshold`: 70% від `contextWindow` (або `80000`, коли недоступно)
|
||||
- Примусово встановлює `store: true` (якщо сумісність моделі не встановлює `supportsStore: false`)
|
||||
- Додає `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- Типове значення `compact_threshold`: 70% від `contextWindow` (або `80000`, коли недоступно)
|
||||
|
||||
Це застосовується до вбудованого шляху Pi harness і до hooks провайдера OpenAI, які використовують вбудовані запуски. Нативний app-server harness Codex керує власним контекстом через Codex і налаштовується окремо за допомогою `agents.defaults.agentRuntime.id`.
|
||||
Це застосовується до вбудованого шляху Pi harness і до хуків провайдера OpenAI, які використовуються вбудованими запусками. Нативний harness сервера застосунку Codex керує власним контекстом через Codex і налаштовується окремо за допомогою `agents.defaults.agentRuntime.id`.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Увімкнути явно">
|
||||
@ -858,13 +900,13 @@ Azure OpenAI використовує нативний транспорт і com
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` керує лише інʼєкцією `context_management`. Прямі моделі OpenAI Responses усе одно примусово використовують `store: true`, якщо шар сумісності не встановлює `supportsStore: false`.
|
||||
`responsesServerCompaction` керує лише додаванням `context_management`. Прямі моделі OpenAI Responses все одно примусово встановлюють `store: true`, якщо сумісність не встановлює `supportsStore: false`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Строгий агентний режим GPT">
|
||||
Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати строгіший вбудований контракт виконання:
|
||||
<Accordion title="Суворий агентний режим GPT">
|
||||
Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший контракт вбудованого виконання:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -878,32 +920,32 @@ Azure OpenAI використовує нативний транспорт і com
|
||||
|
||||
З `strict-agentic` OpenClaw:
|
||||
- Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента
|
||||
- Повторює хід зі скеровуванням діяти зараз
|
||||
- Повторює хід із вказівкою діяти зараз
|
||||
- Автоматично вмикає `update_plan` для суттєвої роботи
|
||||
- Показує явний заблокований стан, якщо модель продовжує планувати без дій
|
||||
|
||||
<Note>
|
||||
Обмежено лише запусками сімейства OpenAI і Codex GPT-5. Інші провайдери та старіші сімейства моделей зберігають типову поведінку.
|
||||
Застосовується лише до запусків OpenAI і Codex сімейства GPT-5. Інші провайдери та старіші сімейства моделей зберігають типову поведінку.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні та OpenAI-сумісні маршрути">
|
||||
OpenClaw обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI інакше, ніж універсальні OpenAI-сумісні проксі `/v1`:
|
||||
<Accordion title="Нативні маршрути та маршрути, сумісні з OpenAI">
|
||||
OpenClaw обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI інакше, ніж загальні OpenAI-сумісні проксі `/v1`:
|
||||
|
||||
**Нативні маршрути** (`openai/*`, Azure OpenAI):
|
||||
- Зберігають `reasoning: { effort: "none" }` лише для моделей, що підтримують рівень зусиль OpenAI `none`
|
||||
- Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують зусилля OpenAI `none`
|
||||
- Пропускають вимкнене міркування для моделей або проксі, які відхиляють `reasoning.effort: "none"`
|
||||
- Типово використовують строгий режим для схем інструментів
|
||||
- За замовчуванням переводять схеми інструментів у суворий режим
|
||||
- Додають приховані заголовки атрибуції лише на перевірених нативних хостах
|
||||
- Зберігають формування запитів, специфічне лише для OpenAI (`service_tier`, `store`, сумісність міркування, підказки кешу промптів)
|
||||
- Зберігають формування запитів лише для OpenAI (`service_tier`, `store`, сумісність reasoning, підказки кешу промптів)
|
||||
|
||||
**Проксі/сумісні маршрути:**
|
||||
- Використовують вільнішу поведінку сумісності
|
||||
- Вилучають Completions `store` з ненативних корисних навантажень `openai-completions`
|
||||
- Використовують менш сувору поведінку сумісності
|
||||
- Видаляють Completions `store` з ненативних payload `openai-completions`
|
||||
- Приймають розширений наскрізний JSON `params.extra_body`/`params.extraBody` для OpenAI-сумісних проксі Completions
|
||||
- Приймають `params.chat_template_kwargs` для OpenAI-сумісних проксі Completions, таких як vLLM
|
||||
- Не примушують строгі схеми інструментів або лише нативні заголовки
|
||||
- Приймають `params.chat_template_kwargs` для OpenAI-сумісних проксі Completions, як-от vLLM
|
||||
- Не примушують суворі схеми інструментів або заголовки лише для нативних маршрутів
|
||||
|
||||
Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує приховані заголовки атрибуції.
|
||||
|
||||
@ -914,7 +956,7 @@ Azure OpenAI використовує нативний транспорт і com
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Вибір моделі" href="/uk/concepts/model-providers" icon="layers">
|
||||
Вибір провайдерів, посилань на моделі та поведінки відновлення після збою.
|
||||
Вибір провайдерів, посилань на моделі та поведінки відмовостійкого перемикання.
|
||||
</Card>
|
||||
<Card title="Генерація зображень" href="/uk/tools/image-generation" icon="image">
|
||||
Спільні параметри інструмента зображень і вибір провайдера.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user