---
read_when:
- Ви хочете налаштувати інференс, а потім завершити налаштування за допомогою Crestodian
summary: Довідник CLI для `openclaw onboard` (інтерактивне початкове налаштування)
title: Початкове налаштування
x-i18n:
generated_at: "2026-07-12T13:05:17Z"
model: gpt-5.6
postprocess_version: locale-links-v1
provider: openai
source_hash: 6e9dad7efda492e0d9ef01ef08a1fd8c81272a0d9b3aa3b945917b6878159a06
source_path: cli/onboard.md
workflow: 16
---
# `openclaw onboard`
Кероване налаштування, яке спочатку встановлює доступ до інференсу: виявляє наявний доступ до ШІ,
вимагає успішного виконання реального запиту, зберігає лише робочий маршрут, а потім запускає
Crestodian для налаштування решти. `openclaw setup` — та сама точка входу;
`openclaw setup --baseline` лише записує базову конфігурацію та робочий простір.
Покроковий опис інтерактивного процесу CLI.
Як узгоджуються між собою етапи початкового налаштування OpenClaw.
Результати, внутрішня робота та поведінка на кожному кроці.
Неінтерактивні прапорці та сценарії налаштування.
Процес початкового налаштування застосунку в смузі меню macOS.
## Приклади
```bash
openclaw onboard
openclaw onboard --classic
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
- `--classic`: відкриває повний покроковий майстер. Його не можна поєднувати з
`--non-interactive`; для автоматизованого налаштування не вказуйте `--classic`.
- `--flow quickstart`: відкриває класичний майстер із мінімальною кількістю запитів і
автоматично генерує токен Gateway.
- `--flow manual` (псевдонім `advanced`): відкриває класичний майстер із повним набором запитів
щодо порту, прив’язки та автентифікації.
- `--flow import`: запускає виявленого постачальника міграції (наприклад, Hermes через `--import-from hermes`), показує попередній перегляд плану, а потім застосовує його після підтвердження. Імпорт запускається лише для чистого налаштування OpenClaw — якщо вже існують конфігурація, облікові дані, сеанси або стан робочого простору, спочатку скиньте їх. Використовуйте [`openclaw migrate`](/uk/cli/migrate) для планів пробного запуску, режиму перезапису, звітів і точних зіставлень.
- `--modern` — це псевдонім сумісності для розмовного помічника налаштування Crestodian.
Він використовує ту саму перевірку реального інференсу, що й `openclaw crestodian`, і
приймає лише `--workspace`, `--accept-risk`,
`--non-interactive` та `--json`. Інші прапорці налаштування відхиляються, а не
мовчки ігноруються.
## Керований процес
Звичайна команда `openclaw onboard` запускає керований процес. Вона показує попередження про безпеку,
виявляє вже доступний доступ до ШІ через налаштовані моделі, змінні середовища
з ключами API та підтримувані локальні CLI, а потім перевіряє рекомендованого
кандидата за допомогою реального запиту. Якщо цей кандидат не проходить перевірку, початкове налаштування показує
причину й автоматично перевіряє наступного придатного кандидата.
Якщо автоматичне виявлення вичерпало всі варіанти, виберіть іншого виявленого кандидата або введіть
ключ API постачальника в замаскованому запиті. Вручну введений ключ перевіряється через той самий
шлях реального запиту. Кероване початкове налаштування
не пропонує Crestodian або вихід із пропуском ШІ, доки кандидат не пройде перевірку. OpenClaw
зберігає перевірений маршрут моделі та його облікові дані лише після успішного завершення
тесту; кандидат, що не пройшов перевірку, не замінює налаштовану модель і не зберігає
використані під час спроби облікові дані. Налаштування робочого простору та Gateway не змінюються, доки
не запуститься Crestodian.
У керованому режимі `--workspace ` задає запропонований для Crestodian робочий простір
та ізольований контекст інференсу. Він не зберігається, доки ви не схвалите
пропозицію налаштування Crestodian. Класичне та неінтерактивне початкове налаштування зберігають
робочий простір у межах свого звичайного процесу налаштування.
Після успішної перевірки інференсу кероване початкове налаштування негайно запускає Crestodian із
перевіреною моделлю. Після цього Crestodian може налаштувати робочий простір, Gateway,
канали, агентів, плагіни та інші необов’язкові функції. У Crestodian використовуйте
`open channel wizard for `, щоб передати збирання облікових даних каналу
замаскованому термінальному майстру. Щоб змінити постачальника моделі або спосіб його автентифікації,
вийдіть із Crestodian і виконайте `openclaw onboard`; Crestodian не відкриває керовані
або класичні процеси налаштування постачальника.
У налаштованій інсталяції повторний запуск `openclaw onboard` спочатку перевіряє поточну
модель за замовчуванням, тому той самий процес також виконує перевірку та відновлення.
Якщо ця перевірка не вдається, налаштована модель ніколи не замінюється автоматично —
початкове налаштування зупиняється й запитує, як продовжити. Перевірка виконується поза вашим
робочим простором, тому модель, надана плагіном робочого простору, може не пройти її, хоча й надалі
працюватиме в агенті.
Використовуйте `openclaw onboard --classic` для автентифікації, специфічної для постачальника, каналів, Skills,
віддаленого налаштування Gateway, імпорту або повного керування Gateway. Для розмовного
налаштування й відновлення, не пов’язаного з інференсом, виконайте `openclaw crestodian`; `openclaw onboard
--modern` — це псевдонім сумісності, що проходить через ту саму перевірку інференсу. Класичний
майстер може за бажанням перевірити модель за замовчуванням реальним запитом, але
Crestodian не запуститься, доки не пройде власну перевірку реального інференсу.
В інтерактивному терміналі звичайна команда `openclaw` (без підкоманди) вибирає шлях залежно від стану
конфігурації:
- Якщо активний файл конфігурації відсутній або не містить заданих користувачем параметрів (порожній чи
містить лише метадані), запускається кероване початкове налаштування.
- Якщо файл конфігурації існує, але не проходить перевірку, запускається класичний
шлях початкового налаштування з рекомендацією скористатися `openclaw doctor`. Crestodian потребує робочого
інференсу й не використовується для відновлення цього стану до налаштування інференсу.
- Якщо файл конфігурації дійсний, відкривається звичайний TUI агента. Доступний
налаштований Gateway з агентом і моделлю веде безпосередньо до цього інтерфейсу без
початкового налаштування чи Crestodian. У налаштованій інсталяції відкрийте Crestodian за допомогою
`/crestodian` у TUI або `openclaw crestodian`.
Незашифрований `ws://` дозволено для local loopback, приватних літеральних IP-адрес, `.local` і URL-адрес Gateway у Tailnet `*.ts.net`. Для інших довірених імен приватного DNS установіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у середовищі процесу початкового налаштування.
## Скидання
```bash
openclaw onboard --reset
openclaw onboard --reset --reset-scope full
```
`--reset` очищає стан перед запуском налаштування. `--reset-scope` визначає обсяг очищення: `config` (лише конфігурація), `config+creds+sessions` (за замовчуванням, якщо `--reset` передано без області) або `full` (також скидає робочий простір). Робочий простір скидається лише з `--reset-scope full`.
## Локаль
Інтерактивне початкове налаштування використовує локаль майстра CLI для фіксованих текстів налаштування. Порядок визначення:
1. `OPENCLAW_LOCALE`
2. `LC_ALL`
3. `LC_MESSAGES`
4. `LANG`
5. Резервний варіант — англійська
Майстер підтримує локалі `en`, `zh-CN` і `zh-TW`. Значення локалі можуть використовувати підкреслення або суфікси POSIX, наприклад `zh_CN.UTF-8`. Назви продуктів, команд, ключі конфігурації, URL-адреси, ідентифікатори постачальників, ідентифікатори моделей і мітки плагінів та каналів залишаються без змін.
```bash
OPENCLAW_LOCALE=zh-CN openclaw onboard
```
## Неінтерактивне налаштування
`--non-interactive` вимагає `--accept-risk` (підтвердження того, що агенти мають значні можливості, а повний доступ до системи несе ризики). Значення `--mode` за замовчуванням — `local`.
```bash
openclaw onboard --non-interactive \
--auth-choice custom-api-key \
--custom-base-url "https://llm.example.com/v1" \
--custom-model-id "foo-large" \
--custom-api-key "$CUSTOM_API_KEY" \
--secret-input-mode plaintext \
--custom-compatibility openai \
--custom-image-input
```
`--custom-api-key` необов’язковий; якщо його не вказано, початкове налаштування перевіряє `CUSTOM_API_KEY` у змінних середовища. OpenClaw автоматично позначає поширені ідентифікатори моделей із підтримкою зображень (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral і подібні) як здатні обробляти зображення. Передайте `--custom-image-input` для невідомих користувацьких ідентифікаторів моделей із підтримкою зображень або `--custom-text-input`, щоб примусово задати метадані лише для тексту. Використовуйте `--custom-compatibility openai-responses` для сумісних з OpenAI кінцевих точок, які підтримують `/v1/responses`, але не `/v1/chat/completions`; допустимі значення: `openai` (за замовчуванням), `openai-responses`, `anthropic`.
LM Studio також має окремий прапорець ключа для цього постачальника:
```bash
openclaw onboard --non-interactive \
--auth-choice lmstudio \
--custom-base-url "http://localhost:1234/v1" \
--custom-model-id "qwen/qwen3.5-9b" \
--lmstudio-api-key "$LM_API_TOKEN" \
--accept-risk
```
Неінтерактивне налаштування Ollama:
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
Значення `--custom-base-url` за замовчуванням — `http://127.0.0.1:11434`. `--custom-model-id` необов’язковий; якщо його не вказано, початкове налаштування використовує рекомендовані Ollama значення за замовчуванням. Тут також працюють ідентифікатори хмарних моделей, як-от `kimi-k2.5:cloud`.
Зберігайте ключі постачальника як посилання, а не відкритий текст:
```bash
openclaw onboard --non-interactive \
--auth-choice openai-api-key \
--secret-input-mode ref \
--accept-risk
```
З `--secret-input-mode ref` початкове налаштування записує посилання на змінні середовища замість значень ключів у відкритому тексті: для постачальників на основі профілів автентифікації записується `keyRef: { source: "env", provider: "default", id: }`; для користувацьких постачальників так само записується `models.providers..apiKey` (наприклад, `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`). Умова: задайте змінну середовища постачальника в середовищі процесу початкового налаштування (наприклад, `OPENAI_API_KEY`) і не передавайте одночасно вбудований прапорець ключа, якщо цю змінну середовища не задано — значення прапорця без відповідної змінної середовища спричиняє негайну помилку з рекомендаціями.
### Автентифікація Gateway (неінтерактивна)
- `--gateway-auth token --gateway-token ` зберігає токен у відкритому тексті. `token` — режим автентифікації за замовчуванням.
- `--gateway-auth token --gateway-token-ref-env ` зберігає `gateway.auth.token` як SecretRef на змінну середовища. Потребує непорожньої змінної середовища з таким ім’ям у середовищі процесу початкового налаштування.
- `--gateway-token` і `--gateway-token-ref-env` є взаємовиключними.
- З `--install-daemon`: керований через SecretRef `gateway.auth.token` перевіряється, але його розв’язане значення у відкритому тексті не зберігається в метаданих середовища служби супервізора; якщо посилання неможливо розв’язати, встановлення завершується безпечним блокуванням із рекомендаціями щодо виправлення. Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, встановлення блокується, доки режим не буде задано явно.
- Локальне початкове налаштування записує `gateway.mode="local"` у конфігурацію. Якщо в подальшому у файлі конфігурації відсутній `gateway.mode`, це вказує на пошкодження конфігурації або незавершене ручне редагування, а не на допустимий скорочений запис локального режиму.
- Локальне початкове налаштування встановлює завантажувані плагіни, потрібні для вибраного шляху налаштування (наприклад, плагін середовища виконання Codex або Copilot для відповідних варіантів автентифікації). Віддалене початкове налаштування лише записує дані підключення до віддаленого Gateway — воно ніколи не встановлює пакети локальних плагінів.
- `--allow-unconfigured` — це окремий аварійний параметр `openclaw gateway run`; він не дає змоги початковому налаштуванню пропустити `gateway.mode`.
```bash
export OPENAI_API_KEY="your-provider-key"
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
--mode local \
--auth-choice openai-api-key \
--secret-input-mode ref \
--gateway-auth token \
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
--accept-risk
```
### Стан локального Gateway
- Якщо не передано `--skip-health`, початкове налаштування очікує доступності локального Gateway перед успішним завершенням.
- `--install-daemon` спочатку запускає шлях установлення керованого Gateway. Без нього локальний Gateway уже має працювати (наприклад, через `openclaw gateway run`).
- `--skip-health` пропускає очікування, якщо в автоматизації потрібен лише запис конфігурації, робочого простору та початкових файлів.
- `--skip-bootstrap` задає `agents.defaults.skipBootstrap: true` і пропускає створення `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` та `BOOTSTRAP.md`.
- У нативній Windows `--install-daemon` спочатку намагається використати Scheduled Tasks, а якщо створення завдання заборонено, переходить до елемента входу в папці Startup для поточного користувача.
### Інтерактивний режим посилань
- Коли з’явиться запит, виберіть **Use secret reference**, а потім — **Environment variable** або налаштованого постачальника секретів (`file` чи `exec`).
- Перед збереженням посилання початкове налаштування виконує швидку попередню перевірку та дає змогу повторити спробу в разі помилки.
### Варіанти кінцевої точки Z.AI
`--auth-choice zai-api-key` автоматично визначає найкращу кінцеву точку Z.AI та модель для вашого ключа: кінцеві точки Coding Plan надають перевагу `zai/glm-5.2` (із переходом на `glm-5.1`, якщо вона недоступна); кінцеві точки загального API типово використовують `zai/glm-5.1`. Щоб примусово використати кінцеву точку Coding Plan, виберіть безпосередньо `zai-coding-global` або `zai-coding-cn`.
```bash
# Вибір кінцевої точки без запитів
openclaw onboard --non-interactive \
--auth-choice zai-coding-global \
--zai-api-key "$ZAI_API_KEY"
# Інші варіанти кінцевих точок Z.AI: zai-coding-cn, zai-global, zai-cn
```
Mistral:
```bash
openclaw onboard --non-interactive \
--auth-choice mistral-api-key \
--mistral-api-key "$MISTRAL_API_KEY"
```
## Додаткові прапорці неінтерактивного режиму
Автентифікація моделі на основі токена (використовується з `--auth-choice token`):
| Прапорець | Опис |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--token-provider ` | Ідентифікатор постачальника токена, який видав токен |
| `--token ` | Значення токена для автентифікації моделі |
| `--token-profile-id ` | Ідентифікатор профілю автентифікації (типово `:manual`; деякі процеси, якими керує постачальник, використовують власне типове значення, як-от `anthropic:default`) |
| `--token-expires-in ` | Необов’язковий строк дії токена (наприклад, `365d`, `12h`) |
Cloudflare AI Gateway: `--cloudflare-ai-gateway-account-id `, `--cloudflare-ai-gateway-gateway-id `.
Керування встановленням фонової служби: `--no-install-daemon` / `--skip-daemon` (псевдоніми; пропускають встановлення служби Gateway), `--daemon-runtime `.
Skills: `--node-manager ` (типово `npm`), `--skip-skills`.
Налаштування інтерфейсу та хуків: `--skip-ui` (пропускає запити Control UI/TUI), `--skip-hooks` (пропускає налаштування вебхуків/хуків), `--skip-channels`, `--skip-search`.
Виведення: `--suppress-gateway-token-output` приховує виведення Gateway/UI, що містить токен (підказки щодо токена, URL автоматичного входу із вбудованим токеном та автоматичний запуск Control UI) — корисно у спільних терміналах і CI.
`--json` не вмикає неінтерактивний режим під час керованого або класичного початкового налаштування.
З `--modern` JSON надає одноразовий огляд Crestodian і завершує роботу після цього
єдиного результату. Для інших сценаріїв використовуйте `--non-interactive`.
## Попереднє фільтрування постачальників
Якщо вибір автентифікації передбачає бажаного постачальника, початкове налаштування попередньо фільтрує засоби вибору типової моделі та списку дозволених моделей, залишаючи моделі цього постачальника. Фільтр також знаходить інших постачальників, що належать тому самому плагіну, охоплюючи варіанти планів для програмування, як-от `volcengine`/`volcengine-plan` і `byteplus`/`byteplus-plan`. Якщо фільтр бажаного постачальника не повертає жодної завантаженої моделі, початкове налаштування використовує нефільтрований каталог, а не залишає засіб вибору порожнім.
## Додаткові запити вебпошуку
Деякі постачальники вебпошуку запускають специфічні для постачальника додаткові запити під час початкового налаштування:
- **Grok** може запропонувати необов’язкове налаштування `x_search` із тією самою автентифікацією xAI та вибором моделі `x_search`.
- **Kimi** може запитати регіон Moonshot API (`api.moonshot.ai` або `api.moonshot.cn`) і типову модель вебпошуку Kimi.
## Інші особливості поведінки
- Поведінка області особистих повідомлень під час локального початкового налаштування: [довідник із налаштування CLI](/uk/start/wizard-cli-reference#outputs-and-internals).
- Найшвидший спосіб розпочати перший чат: `openclaw dashboard` (Control UI, без налаштування каналів).
- Власний постачальник: підключіть будь-яку кінцеву точку, сумісну з OpenAI або Anthropic, включно з розміщеними постачальниками, яких немає у списку. Використовуйте сумісність **Невідома**, щоб автоматично визначити її за допомогою перевірки в реальному часі.
- Якщо виявлено стан Hermes, початкове налаштування пропонує процес міграції (див. `--flow import` вище).
## Поширені подальші команди
Згодом використовуйте `openclaw configure` для цільових змін, не пов’язаних із виведенням моделі, а `openclaw
channels add` — для налаштування лише каналів. Для змін постачальника моделей або способу автентифікації
натомість запускайте `openclaw onboard`.
```bash
openclaw channels add
openclaw configure
openclaw agents add
```