---
read_when:
    - Пошук конкретного кроку початкового налаштування або прапорця
    - Автоматизація початкового налаштування в неінтерактивному режимі
    - Налагодження поведінки під час початкового налаштування
sidebarTitle: Onboarding Reference
summary: 'Повний довідник із початкового налаштування через CLI: усі кроки, прапорці та поля конфігурації'
title: Довідник із початкового налаштування
x-i18n:
    generated_at: "2026-07-16T18:36:35Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 6c345887da0102c73f72623105d052ea9262006206dd70bae8f94aad1349423d
    source_path: reference/wizard.md
    workflow: 16
---

Це повний довідник для `openclaw onboard`.
Загальний огляд див. у розділі [Початкове налаштування (CLI)](/uk/start/wizard). Покрокову
поведінку та результати див. у [довіднику з налаштування CLI](/uk/start/wizard-cli-reference).

## Подробиці процесу (локальний режим)

<Steps>
  <Step title="Скидання (необов’язково)">
    - `--reset` скидає стан перед запуском налаштування; без нього повторний запуск початкового налаштування
      зберігає наявну конфігурацію та повторно використовує її як типові значення.
    - `--reset-scope` визначає, що видаляє `--reset`: `config` (лише файл
      конфігурації), `config+creds+sessions` (типово) або `full` (також видаляє
      робочий простір).
    - Якщо файл конфігурації недійсний, початкове налаштування зупиняється та повідомляє, що спочатку потрібно запустити
      `openclaw doctor`, а потім повторно запустити налаштування.
    - Скидання переміщує стан у кошик (ніколи не видаляє безпосередньо).

  </Step>
  <Step title="Підтвердження усвідомлення ризиків">
    - Під час першого запуску (або будь-якого запуску до встановлення `wizard.securityAcknowledgedAt`)
      потрібно підтвердити розуміння того, що агенти мають широкі можливості, а повний
      доступ до системи становить ризик.
    - `--non-interactive` явно вимагає `--accept-risk`; без нього
      початкове налаштування завершується з помилкою замість запиту підтвердження.
    - Під час інтерактивного запуску замість прапорця відображається запит підтвердження; відмова
      скасовує налаштування.

  </Step>
  <Step title="Модель/автентифікація">
    - **Ключ API Anthropic**: використовує `ANTHROPIC_API_KEY`, якщо він наявний, або запитує ключ, а потім зберігає його для використання фоновою службою.
    - **CLI Anthropic Claude**: рекомендований локальний шлях, якщо вхід через Claude CLI уже виконано; OpenClaw також підтримує автентифікацію Anthropic за допомогою токена налаштування як альтернативу.
    - **Підписка OpenAI Code (Codex) (OAuth)**: процес у браузері; вставте `code#state`.
      - Під час нового налаштування без основної моделі встановлює `agents.defaults.model` у значення `openai/gpt-5.6-sol` через середовище виконання Codex.
    - **Підписка OpenAI Code (Codex) (сполучення пристрою)**: процес сполучення в браузері з короткочасним кодом пристрою.
      - Під час нового налаштування без основної моделі встановлює `agents.defaults.model` у значення `openai/gpt-5.6-sol` через середовище виконання Codex.
    - **Ключ API OpenAI**: використовує `OPENAI_API_KEY`, якщо він наявний, або запитує ключ, а потім зберігає його у профілях автентифікації.
      - Під час нового налаштування без основної моделі встановлює `agents.defaults.model` у значення `openai/gpt-5.6`; ідентифікатор моделі безпосереднього API без префікса відповідає рівню Sol.
    - Додавання або повторна автентифікація OpenAI зберігає наявну явно задану основну модель, зокрема `openai/gpt-5.5`. Якщо обліковий запис не надає GPT-5.6, явно виберіть `openai/gpt-5.5`; OpenClaw не переходить на модель нижчого рівня без повідомлення.
    - **OAuth xAI**: вхід у браузері за кодом пристрою без потреби у зворотному виклику localhost, тому він також працює через SSH/Docker/VPS (`--auth-choice xai-oauth`).
    - **Ключ API xAI**: запитує `XAI_API_KEY` (`--auth-choice xai-api-key`).
    - `--auth-choice xai-device-code` усе ще працює як призначений лише для ручного використання псевдонім сумісності для того самого процесу OAuth xAI за кодом пристрою; для нових сценаріїв використовуйте `xai-oauth`.
    - **OpenCode**: запитує `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`, отримайте його на https://opencode.ai/auth) і дає змогу вибрати каталог Zen або Go.
    - **Ollama**: спочатку пропонує **хмарний і локальний**, **лише хмарний** або **лише локальний** режим. `Cloud only` запитує `OLLAMA_API_KEY` і використовує `https://ollama.com`; режими з власним хостом запитують базову URL-адресу Ollama (типово `http://127.0.0.1:11434`), виявляють доступні моделі й автоматично завантажують вибрану локальну модель за потреби; `Cloud + Local` також перевіряє, чи виконано вхід на цьому хості Ollama для доступу до хмарних ресурсів.
    - Докладніше: [Ollama](/uk/providers/ollama)
    - **Ключ API**: зберігає ключ.
    - **Vercel AI Gateway (багатомодельний проксі-сервер)**: запитує `AI_GATEWAY_API_KEY`.
    - Докладніше: [Vercel AI Gateway](/uk/providers/vercel-ai-gateway)
    - **Cloudflare AI Gateway**: запитує ідентифікатор облікового запису, ідентифікатор Gateway і `CLOUDFLARE_AI_GATEWAY_API_KEY`.
    - Докладніше: [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway)
    - **MiniMax**: конфігурація записується автоматично; типове значення для розміщеної версії — `MiniMax-M3`.
      Для налаштування за допомогою ключа API використовується `minimax/...`, а для налаштування OAuth —
      `minimax-portal/...`.
    - Докладніше: [MiniMax](/uk/providers/minimax)
    - **StepFun**: конфігурація записується автоматично для стандартного StepFun або Step Plan на кінцевих точках у Китаї чи глобальних кінцевих точках.
    - Наразі типовим значенням стандартного варіанта є `step-3.5-flash`; Step Plan також містить `step-3.5-flash-2603`.
    - Докладніше: [StepFun](/uk/providers/stepfun)
    - **Synthetic (сумісний з Anthropic)**: запитує `SYNTHETIC_API_KEY`.
    - Докладніше: [Synthetic](/uk/providers/synthetic)
    - **Moonshot (Kimi K2)**: конфігурація записується автоматично.
    - **Kimi Coding**: конфігурація записується автоматично.
    - Докладніше: [Moonshot AI (Kimi + Kimi Coding)](/uk/providers/moonshot)
    - **Власний постачальник**: працює з кінцевими точками, сумісними з OpenAI, OpenAI Responses або Anthropic. Прапорці для неінтерактивного режиму: `--auth-choice custom-api-key`, `--custom-base-url`, `--custom-model-id`, `--custom-api-key` (необов’язково; резервне значення — `CUSTOM_API_KEY`), `--custom-provider-id` (необов’язково; автоматично виводиться з базової URL-адреси), `--custom-compatibility openai|openai-responses|anthropic` (типово `openai`), `--custom-image-input` / `--custom-text-input` (перевизначають автоматичне визначення моделі з підтримкою зображень).
    - **Пропустити**: автентифікацію ще не налаштовано.
    - Виберіть типову модель із виявлених варіантів (або введіть постачальника/модель вручну). Для найкращої якості та зниження ризику ін’єкцій у підказки виберіть найпотужнішу доступну модель останнього покоління у вашому наборі постачальників.
    - Початкове налаштування перевіряє модель і попереджає, якщо налаштована модель невідома або для неї немає автентифікації.
    - Типовий режим зберігання ключа API — значення у профілі автентифікації у вигляді відкритого тексту. Використовуйте `--secret-input-mode ref`, щоб натомість зберігати посилання на змінні середовища (наприклад, `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`); відповідну змінну середовища має бути вже встановлено, інакше початкове налаштування негайно завершиться помилкою.
    - Профілі автентифікації зберігаються в `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (ключі API + OAuth). `~/.openclaw/credentials/oauth.json` використовується лише для імпорту застарілих даних.
    - Докладніше: [OAuth](/uk/concepts/oauth)
    <Note>
    Порада для безголового режиму/сервера: завершіть OAuth на комп’ютері з браузером, а потім скопіюйте
    `auth-profiles.json` цього агента (наприклад,
    `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` або відповідний
    шлях `$OPENCLAW_STATE_DIR/...`) на хост Gateway. `credentials/oauth.json`
    використовується лише як застаріле джерело імпорту.
    </Note>
  </Step>
  <Step title="Робочий простір">
    - Типово `~/.openclaw/workspace` (можна налаштувати).
    - Створює початкові файли робочого простору, потрібні для ритуалу початкового завантаження агента.
    - Повна структура робочого простору та посібник із резервного копіювання: [Робочий простір агента](/uk/concepts/agent-workspace)

  </Step>
  <Step title="Gateway">
    - Порт (типово **18789**), прив’язка, режим автентифікації, доступ через Tailscale.
    - Рекомендація щодо автентифікації: залиште **Токен** навіть для loopback, щоб локальні клієнти WS мали проходити автентифікацію.
    - У режимі токена інтерактивне налаштування пропонує:
      - **Згенерувати/зберегти токен як відкритий текст** (типово)
      - **Використовувати SecretRef** (за явним вибором)
      - Швидке налаштування повторно використовує наявні SecretRef `gateway.auth.token` у постачальниках `env`, `file` і `exec` для початкової перевірки та завантаження панелі керування.
      - Якщо SecretRef налаштовано, але його неможливо визначити, початкове налаштування завершується на ранньому етапі з чітким повідомленням про виправлення замість непомітного послаблення автентифікації середовища виконання.
    - У режимі пароля інтерактивне налаштування також підтримує зберігання відкритого тексту або SecretRef.
    - Шлях SecretRef токена для неінтерактивного режиму: `--gateway-token-ref-env <ENV_VAR>`.
      - Потрібна непорожня змінна середовища у середовищі процесу початкового налаштування.
      - Не можна поєднувати з `--gateway-token`.
    - Вимикайте автентифікацію лише за умови повної довіри до кожного локального процесу.
    - Прив’язки не до loopback усе одно потребують автентифікації.

  </Step>
  <Step title="Канали">
    - [WhatsApp](/uk/channels/whatsapp): необов’язковий вхід за QR-кодом.
    - [Telegram](/uk/channels/telegram): токен бота.
    - [Discord](/uk/channels/discord): токен бота.
    - [Google Chat](/uk/channels/googlechat): JSON облікового запису служби + аудиторія Webhook.
    - [Mattermost](/uk/channels/mattermost) (plugin): токен бота + базова URL-адреса.
    - [Signal](/uk/channels/signal) (plugin): необов’язкове встановлення `signal-cli` + конфігурація облікового запису.
    - [iMessage](/uk/channels/imessage): шлях до CLI `imsg` + доступ до бази даних Messages; використовуйте обгортку SSH, коли Gateway працює не на Mac.
    - Discord, Feishu, Microsoft Teams, QQ Bot, Slack та інші канали постачаються як
      plugins, які початкове налаштування може встановити. Повний каталог: [Канали](/uk/channels).
    - Безпека приватних повідомлень: типовим є сполучення. Перше приватне повідомлення надсилає код; підтвердьте його через `openclaw pairing approve <channel> <code>` або використовуйте списки дозволених користувачів.

  </Step>
  <Step title="Вебпошук">
    - Виберіть підтримуваного постачальника, наприклад Brave, Codex (Hosted Search), DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Parallel, Perplexity, SearXNG або Tavily (або пропустіть).
    - Постачальники на основі API можуть використовувати змінні середовища або наявну конфігурацію для швидкого налаштування; натомість постачальники без ключів використовують власні попередні вимоги.
    - Пропустіть за допомогою `--skip-search`.
    - Налаштувати пізніше: `openclaw configure --section web`.

  </Step>
  <Step title="Встановлення фонової служби">
    - macOS: LaunchAgent
      - Потрібен активний сеанс користувача; для безголового режиму використовуйте власний LaunchDaemon (не постачається).
    - Linux (і Windows через WSL2): користувацький модуль systemd
      - Початкове налаштування намагається ввімкнути збереження користувацького сеансу через `loginctl enable-linger <user>`, щоб Gateway продовжував працювати після виходу.
      - Може з’явитися запит sudo (записує `/var/lib/systemd/linger`); спочатку виконується спроба без sudo.
    - Нативна Windows: спочатку використовується заплановане завдання; якщо створення завдання заборонено, OpenClaw переходить на елемент входу для поточного користувача в папці автозавантаження та негайно запускає Gateway.
    - **Вибір середовища виконання:** Node є обов’язковим, оскільки канонічне сховище стану середовища виконання використовує `node:sqlite`. Застарілі служби Bun переносяться на Node під час виправлення.
    - Якщо автентифікація за токеном потребує токена, а `gateway.auth.token` керується через SecretRef, встановлення фонової служби перевіряє його, але не зберігає визначене значення токена у вигляді відкритого тексту в метаданих середовища служби супервізора.
    - Якщо автентифікація за токеном потребує токена, а налаштований SecretRef токена не вдається визначити, встановлення фонової служби блокується з практичними вказівками.
    - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, встановлення фонової служби блокується, доки режим не буде задано явно.

  </Step>
  <Step title="Перевірка працездатності">
    - Запускає Gateway (за потреби) та виконує `openclaw health`.
    - Порада: `openclaw status --deep` додає перевірку працездатності активного Gateway до виведення стану, зокрема перевірки каналів, якщо вони підтримуються (потрібен доступний Gateway).

  </Step>
  <Step title="Skills (рекомендовано)">
    - Зчитує доступні навички та перевіряє вимоги.
    - Дає змогу вибрати менеджер Node: **npm / pnpm / bun**.
    - Автоматично встановлює необов’язкові залежності для надійних вбудованих навичок (деякі використовують Homebrew у macOS).
    - Пропускає навички, якщо попередня вимога щодо інсталятора Homebrew, uv або Go недоступна, групує їх із вказівками щодо ручного налаштування та спрямовує до `openclaw doctor` після встановлення попередньої вимоги.

  </Step>
  <Step title="Завершення">
    - Підсумок і подальші кроки, зокрема запит **Як потрібно запустити вашого агента?** з варіантами «Термінал», «Браузер» або «Пізніше».

  </Step>
</Steps>

<Note>
Якщо графічний інтерфейс не виявлено, замість відкриття браузера майстер початкового налаштування виводить інструкції з перенаправлення порту SSH для Control UI.
Якщо ресурси Control UI відсутні, майстер початкового налаштування намагається зібрати їх; резервний варіант — `pnpm ui:build` (автоматично встановлює залежності UI).
</Note>

## Неінтерактивний режим

Використовуйте `--non-interactive --accept-risk` для автоматизації початкового налаштування або виконання його за допомогою сценарію (цей
прапорець є обов’язковим підтвердженням усвідомлення ризику; без нього початкове налаштування
завершується з помилкою):

```bash
openclaw onboard --non-interactive --accept-risk \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills
```

Додайте `--json`, щоб отримати придатне для машинного зчитування зведення.

SecretRef токена Gateway у неінтерактивному режимі:

```bash
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive --accept-risk \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN
```

`--gateway-token` і `--gateway-token-ref-env` є взаємовиключними.

<Note>
`--json` **не** передбачає неінтерактивний режим. Для сценаріїв використовуйте `--non-interactive --accept-risk` (і `--workspace`).
</Note>

Приклади команд для окремих постачальників наведено в розділі [Автоматизація CLI](/uk/start/wizard-cli-automation#provider-specific-examples).
Семантику прапорців і порядок кроків дивіться на цій довідковій сторінці.

### Додавання агента (неінтерактивно)

```bash
openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.6-sol \
  --bind whatsapp:biz \
  --non-interactive \
  --json
```

`main` — зарезервований ідентифікатор агента, який не можна використовувати для `openclaw agents add`.

## RPC майстра Gateway

Gateway надає доступ до процесу початкового налаштування через RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
Клієнти (застосунок macOS, Control UI) можуть відтворювати кроки без повторної реалізації логіки початкового налаштування.

## Налаштування Signal (signal-cli)

Майстер початкового налаштування визначає, чи є `signal-cli` у `PATH`, і, якщо його немає, пропонує встановити:

- Linux x86-64: завантажує офіційну нативну збірку GraalVM із випусків `signal-cli` на GitHub і зберігає її в `~/.openclaw/tools/signal-cli/<version>/`.
- macOS та інші архітектури: натомість установлює через Homebrew.
- Нативна Windows: поки не підтримується; запустіть початкове налаштування у WSL2, щоб скористатися шляхом встановлення для Linux.
- У будь-якому разі записує `channels.signal.cliPath` до конфігурації.

## Що записує майстер

Типові поля в `~/.openclaw/openclaw.json`:

- `agents.defaults.workspace`
- `agents.defaults.skipBootstrap`, коли передано `--skip-bootstrap`
- `agents.defaults.model` / `models.providers` (якщо вибрано Minimax)
- `tools.profile` (якщо значення не задано, для локального початкового налаштування типовим є `"coding"`; наявні явно задані значення зберігаються)
- `gateway.*` (режим, прив’язка, автентифікація, Tailscale)
- `session.dmScope` (якщо значення не задано, локальне початкове налаштування встановлює для нього типове значення `"per-channel-peer"`; наявні явно задані значення зберігаються. Докладніше: [Довідник із налаштування CLI](/uk/start/wizard-cli-reference#outputs-and-internals))
- `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*`
- Списки дозволених особистих повідомлень каналів, якщо ви погоджуєтеся на це у відповідних запитах каналів. Discord, Matrix, Microsoft Teams і Slack за можливості перетворюють імена на ідентифікатори; інші канали приймають ідентифікатори безпосередньо (наприклад, числові ідентифікатори відправників Telegram або номери телефонів WhatsApp).
- `skills.install.nodeManager`
  - `setup --node-manager` приймає `npm`, `pnpm` або `bun`.
  - У разі ручного налаштування все ще можна використовувати `yarn`, безпосередньо задавши `skills.install.nodeManager`.
- `wizard.lastRunAt`
- `wizard.lastRunVersion`
- `wizard.lastRunCommit`
- `wizard.lastRunCommand`
- `wizard.lastRunMode`
- `wizard.securityAcknowledgedAt`

`openclaw agents add` записує `agents.list[]` і необов’язковий `bindings`.

Облікові дані WhatsApp зберігаються в `~/.openclaw/credentials/whatsapp/<accountId>/`.
Активні сеанси й розшифрування зберігаються в
`~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`. Каталог
`~/.openclaw/agents/<agentId>/sessions/` використовується для вхідних даних перенесення зі застарілих версій
і архівних матеріалів та матеріалів для підтримки.

Деякі канали постачаються як плагіни. Якщо вибрати такий канал під час налаштування, майстер початкового налаштування
запропонує встановити його (з npm або локального шляху), перш ніж його можна буде налаштувати.

## Пов’язана документація

- Огляд початкового налаштування: [Початкове налаштування (CLI)](/uk/start/wizard)
- Довідник із налаштування CLI: [Довідник із налаштування CLI](/uk/start/wizard-cli-reference)
- Початкове налаштування застосунку macOS: [Початкове налаштування](/uk/start/onboarding)
- Довідник із конфігурації: [Конфігурація Gateway](/uk/gateway/configuration)
- Постачальники: [WhatsApp](/uk/channels/whatsapp), [Telegram](/uk/channels/telegram), [Discord](/uk/channels/discord), [Google Chat](/uk/channels/googlechat), [Signal](/uk/channels/signal), [iMessage](/uk/channels/imessage)
- Skills: [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config)
