> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Довідник із налаштування CLI

Ця сторінка є повним довідником для `openclaw onboard`.
Короткий посібник див. у [Онбординг (CLI)](/uk/start/wizard).

## Що робить майстер

Локальний режим (за замовчуванням) проводить вас через:

* Налаштування моделі й автентифікації (OAuth для підписки OpenAI Code, Anthropic Claude CLI або API-ключ, а також параметри MiniMax, GLM, Ollama, Moonshot, StepFun і AI Gateway)
* Розташування робочої області та файли початкового завантаження
* Налаштування Gateway (порт, прив’язка, автентифікація, tailscale)
* Канали та провайдери (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, iMessage та інші вбудовані Plugin каналів)
* Встановлення демона (LaunchAgent, користувацький модуль systemd або нативне заплановане завдання Windows із резервним варіантом через папку Startup)
* Перевірка стану
* Налаштування Skills

Віддалений режим налаштовує цей комп’ютер для підключення до gateway в іншому місці.
Він нічого не встановлює й не змінює на віддаленому хості.

## Деталі локального процесу

<Steps>
  <Step title="Виявлення наявної конфігурації">
    * Якщо `~/.openclaw/openclaw.json` існує, виберіть Keep, Modify або Reset.
    * Повторний запуск майстра нічого не стирає, якщо ви явно не виберете Reset (або не передасте `--reset`).
    * CLI `--reset` за замовчуванням відповідає `config+creds+sessions`; використовуйте `--reset-scope full`, щоб також видалити робочу область.
    * Якщо конфігурація недійсна або містить застарілі ключі, майстер зупиняється й просить запустити `openclaw doctor`, перш ніж продовжити.
    * Reset використовує `trash` і пропонує області:
      * Лише конфігурація
      * Конфігурація + облікові дані + сеанси
      * Повне скидання (також видаляє робочу область)
  </Step>

  <Step title="Модель і автентифікація">
    * Повна матриця варіантів наведена в [Параметри автентифікації та моделі](#auth-and-model-options).
  </Step>

  <Step title="Робоча область">
    * За замовчуванням `~/.openclaw/workspace` (можна налаштувати).
    * Додає початкові файли робочої області, потрібні для ритуалу початкового завантаження під час першого запуску.
    * Структура робочої області: [Робоча область агента](/uk/concepts/agent-workspace).
  </Step>

  <Step title="Gateway">
    * Запитує порт, прив’язку, режим автентифікації та експонування tailscale.
    * Рекомендовано: залишайте автентифікацію токеном увімкненою навіть для loopback, щоб локальні клієнти WS мусили автентифікуватися.
    * У режимі токена інтерактивне налаштування пропонує:
      * **Згенерувати/зберегти токен у відкритому тексті** (за замовчуванням)
      * **Використати 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): токен бота + базова URL-адреса
    * [Signal](/uk/channels/signal): необов’язкове встановлення `signal-cli` + конфігурація акаунта
    * [iMessage](/uk/channels/imessage): шлях до CLI `imsg` + доступ до БД Messages; використовуйте SSH-обгортку, коли Gateway працює не на Mac
    * Безпека DM: за замовчуванням використовується спарювання. Перший DM надсилає код; підтвердьте через
      `openclaw pairing approve <channel> <code>` або використовуйте списки дозволених.
  </Step>

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

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

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

  <Step title="Завершення">
    * Підсумок і наступні кроки, включно з варіантами застосунків для iOS, Android і macOS.
  </Step>
</Steps>

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

## Деталі віддаленого режиму

Віддалений режим налаштовує цей комп’ютер для підключення до gateway в іншому місці.

<Info>
  Віддалений режим нічого не встановлює й не змінює на віддаленому хості.
</Info>

Що ви задаєте:

* URL віддаленого gateway (`ws://...`)
* Токен, якщо для віддаленого gateway потрібна автентифікація (рекомендовано)

<Note>
  - Якщо gateway доступний лише через loopback, використовуйте SSH-тунелювання або tailnet.
  - Підказки для виявлення:
    * macOS: Bonjour (`dns-sd`)
    * Linux: Avahi (`avahi-browse`)
</Note>

## Параметри автентифікації та моделі

<AccordionGroup>
  <Accordion title="API-ключ Anthropic">
    Використовує `ANTHROPIC_API_KEY`, якщо він є, або запитує ключ, а потім зберігає його для використання демоном.
  </Accordion>

  <Accordion title="Підписка OpenAI Code (OAuth)">
    Браузерний процес; вставте `code#state`.

    Встановлює `agents.defaults.model` на `openai/gpt-5.5` через середовище виконання Codex, коли модель не задана або вже належить до сімейства OpenAI.
  </Accordion>

  <Accordion title="Підписка OpenAI Code (спарювання пристрою)">
    Браузерний процес спарювання з короткочасним кодом пристрою.

    Встановлює `agents.defaults.model` на `openai/gpt-5.5` через середовище виконання Codex, коли модель не задана або вже належить до сімейства OpenAI.
  </Accordion>

  <Accordion title="API-ключ OpenAI">
    Використовує `OPENAI_API_KEY`, якщо він є, або запитує ключ, а потім зберігає облікові дані в профілях автентифікації.

    Встановлює `agents.defaults.model` на `openai/gpt-5.5`, коли модель не задана, має вигляд `openai/*` або є застарілим посиланням на модель Codex.
  </Accordion>

  <Accordion title="xAI (Grok) OAuth">
    Вхід через браузер для відповідних акаунтів SuperGrok або X Premium. Це
    рекомендований шлях xAI для більшості користувачів. OpenClaw зберігає отриманий профіль
    автентифікації для моделей Grok, Grok `web_search`, `x_search` і `code_execution`.
  </Accordion>

  <Accordion title="Код пристрою xAI (Grok)">
    Дружній до віддалених середовищ браузерний вхід із коротким кодом замість callback
    localhost. Використовуйте це з хостів SSH, Docker або VPS.
  </Accordion>

  <Accordion title="API-ключ xAI (Grok)">
    Запитує `XAI_API_KEY` і налаштовує xAI як провайдера моделей. Використовуйте це,
    коли потрібен API-ключ xAI Console замість OAuth за підпискою.
  </Accordion>

  <Accordion title="OpenCode">
    Запитує `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) і дає змогу вибрати каталог Zen або Go.
    URL налаштування: [opencode.ai/auth](https://opencode.ai/auth).
  </Accordion>

  <Accordion title="API-ключ (загальний)">
    Зберігає ключ для вас.
  </Accordion>

  <Accordion title="Vercel AI Gateway">
    Запитує `AI_GATEWAY_API_KEY`.
    Докладніше: [Vercel AI Gateway](/uk/providers/vercel-ai-gateway).
  </Accordion>

  <Accordion title="Cloudflare AI Gateway">
    Запитує ID акаунта, ID gateway і `CLOUDFLARE_AI_GATEWAY_API_KEY`.
    Докладніше: [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway).
  </Accordion>

  <Accordion title="MiniMax">
    Конфігурація записується автоматично. Hosted-значення за замовчуванням — `MiniMax-M3`; налаштування з API-ключем використовує
    `minimax/...`, а налаштування OAuth використовує `minimax-portal/...`.
    Докладніше: [MiniMax](/uk/providers/minimax).
  </Accordion>

  <Accordion title="StepFun">
    Конфігурація записується автоматично для StepFun standard або Step Plan на китайських чи глобальних endpoints.
    Наразі Standard містить `step-3.5-flash`, а Step Plan також містить `step-3.5-flash-2603`.
    Докладніше: [StepFun](/uk/providers/stepfun).
  </Accordion>

  <Accordion title="Synthetic (сумісний з Anthropic)">
    Запитує `SYNTHETIC_API_KEY`.
    Докладніше: [Synthetic](/uk/providers/synthetic).
  </Accordion>

  <Accordion title="Ollama (хмарні та локальні відкриті моделі)">
    Спочатку запитує `Cloud + Local`, `Cloud only` або `Local only`.
    `Cloud only` використовує `OLLAMA_API_KEY` із `https://ollama.com`.
    Режими на базі хоста запитують базову URL-адресу (за замовчуванням `http://127.0.0.1:11434`), виявляють доступні моделі та пропонують значення за замовчуванням.
    `Cloud + Local` також перевіряє, чи цей хост Ollama увійшов у систему для хмарного доступу.
    Докладніше: [Ollama](/uk/providers/ollama).
  </Accordion>

  <Accordion title="Moonshot і Kimi Coding">
    Конфігурації Moonshot (Kimi K2) і Kimi Coding записуються автоматично.
    Докладніше: [Moonshot AI (Kimi + Kimi Coding)](/uk/providers/moonshot).
  </Accordion>

  <Accordion title="Власний провайдер">
    Працює з endpoints, сумісними з OpenAI та Anthropic.

    Інтерактивний онбординг підтримує ті самі варіанти зберігання API-ключа, що й інші процеси API-ключів провайдерів:

    * **Вставити API-ключ зараз** (відкритий текст)
    * **Використати посилання на секрет** (env ref або налаштований provider ref, із попередньою перевіркою)

    Неінтерактивні прапорці:

    * `--auth-choice custom-api-key`
    * `--custom-base-url`
    * `--custom-model-id`
    * `--custom-api-key` (необов’язково; повертається до `CUSTOM_API_KEY`)
    * `--custom-provider-id` (необов’язково)
    * `--custom-compatibility <openai|openai-responses|anthropic>` (необов’язково; за замовчуванням `openai`)
    * `--custom-image-input` / `--custom-text-input` (необов’язково; перевизначає виведену можливість введення моделі)
  </Accordion>

  <Accordion title="Пропустити">
    Залишає автентифікацію неналаштованою.
  </Accordion>
</AccordionGroup>

Поведінка моделі:

* Виберіть модель за замовчуванням із виявлених варіантів або введіть провайдера й модель вручну.
* Онбординг власного провайдера виводить підтримку зображень для поширених ID моделей і запитує лише тоді, коли назва моделі невідома.
* Коли онбординг починається з вибору автентифікації провайдера, засіб вибору моделі автоматично надає перевагу
  цьому провайдеру. Для Volcengine і BytePlus та сама перевага
  також зіставляється з їхніми варіантами coding-plan (`volcengine-plan/*`,
  `byteplus-plan/*`).
* Якщо фільтр бажаного провайдера був би порожнім, засіб вибору повертається до
  повного каталогу замість показу відсутності моделей.
* Майстер виконує перевірку моделі та попереджає, якщо налаштована модель невідома або автентифікація відсутня.

Шляхи до облікових даних і профілів:

* Профілі автентифікації (API-ключі + OAuth): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
* Імпорт застарілого OAuth: `~/.openclaw/credentials/oauth.json`

Режим зберігання облікових даних:

* Типова поведінка початкового налаштування зберігає API-ключі як відкриті текстові значення у профілях автентифікації.
* `--secret-input-mode ref` вмикає режим посилань замість зберігання ключів відкритим текстом.
  В інтерактивному налаштуванні можна вибрати:
  * посилання на змінну середовища (наприклад `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`)
  * посилання на налаштований провайдер (`file` або `exec`) з псевдонімом провайдера + id
* Інтерактивний режим посилань виконує швидку попередню перевірку перед збереженням.
  * Посилання на змінні середовища: перевіряє назву змінної + непорожнє значення в поточному середовищі початкового налаштування.
  * Посилання на провайдери: перевіряє конфігурацію провайдера та розв’язує запитаний id.
  * Якщо попередня перевірка не вдається, початкове налаштування показує помилку й дає змогу повторити спробу.
* У неінтерактивному режимі `--secret-input-mode ref` підтримується лише через змінні середовища.
  * Установіть змінну середовища провайдера в середовищі процесу початкового налаштування.
  * Вбудовані прапорці ключів (наприклад `--openai-api-key`) вимагають, щоб цю змінну середовища було встановлено; інакше початкове налаштування швидко завершується з помилкою.
  * Для користувацьких провайдерів неінтерактивний режим `ref` зберігає `models.providers.<id>.apiKey` як `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
  * У цьому випадку користувацького провайдера `--custom-api-key` вимагає, щоб `CUSTOM_API_KEY` було встановлено; інакше початкове налаштування швидко завершується з помилкою.
* Облікові дані автентифікації Gateway підтримують вибір між відкритим текстом і SecretRef в інтерактивному налаштуванні:
  * Режим токена: **Згенерувати/зберегти токен відкритим текстом** (типово) або **Використати SecretRef**.
  * Режим пароля: відкритий текст або SecretRef.
* Неінтерактивний шлях SecretRef для токена: `--gateway-token-ref-env <ENV_VAR>`.
* Наявні налаштування з відкритим текстом і далі працюють без змін.

<Note>
  Порада для headless- і серверних середовищ: завершіть OAuth на машині з браузером, а потім скопіюйте
  `auth-profiles.json` цього агента (наприклад
  `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` або відповідний
  шлях `$OPENCLAW_STATE_DIR/...`) на хост Gateway. `credentials/oauth.json`
  є лише застарілим джерелом імпорту.
</Note>

## Виводи та внутрішні дані

Типові поля в `~/.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`, якщо значення не задано; наявні явні значення зберігаються)
* `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*`
* Списки дозволених каналів (Slack, Discord, Matrix, Microsoft Teams), коли ви вмикаєте їх під час підказок (назви за можливості розв’язуються в ID)
* `skills.install.nodeManager`
  * Прапорець `setup --node-manager` приймає `npm`, `pnpm` або `bun`.
  * Ручна конфігурація все ще може пізніше встановити `skills.install.nodeManager: "yarn"`.
* `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>/sessions/`.

<Note>
  Деякі канали постачаються як plugins. Якщо їх вибрано під час налаштування, майстер
  пропонує встановити plugin (npm або локальний шлях) перед конфігурацією каналу.
</Note>

RPC майстра Gateway:

* `wizard.start`
* `wizard.next`
* `wizard.cancel`
* `wizard.status`

Клієнти (застосунок macOS і Control UI) можуть відображати кроки без повторної реалізації логіки початкового налаштування.

Поведінка налаштування Signal:

* Завантажує відповідний артефакт релізу
* Зберігає його в `~/.openclaw/tools/signal-cli/<version>/`
* Записує `channels.signal.cliPath` у конфігурацію
* Збірки JVM потребують Java 21
* Нативні збірки використовуються, коли доступні
* Windows використовує WSL2 і дотримується Linux-потоку signal-cli всередині WSL

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

* Центр початкового налаштування: [Початкове налаштування (CLI)](/uk/start/wizard)
* Автоматизація та скрипти: [Автоматизація CLI](/uk/start/wizard-cli-automation)
* Довідник команд: [`openclaw onboard`](/uk/cli/onboard)