English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Technical reference

Довідник з онбордингу

Це повний довідник для openclaw onboard. Високорівневий огляд див. у Onboarding (CLI).

Деталі потоку (локальний режим)

  • Виявлення наявної конфігурації

    • Якщо ~/.openclaw/openclaw.json існує, виберіть Зберегти / Змінити / Скинути.
    • Повторний запуск onboarding не видаляє нічого, якщо ви явно не виберете Скинути (або не передасте --reset).
    • CLI --reset за замовчуванням має область config+creds+sessions; використовуйте --reset-scope full, щоб також видалити робочий простір.
    • Якщо конфігурація недійсна або містить застарілі ключі, майстер зупиняється й просить запустити openclaw doctor, перш ніж продовжити.
    • Скидання використовує trash (ніколи rm) і пропонує області:
      • Лише конфігурація
      • Конфігурація + облікові дані + сесії
      • Повне скидання (також видаляє робочий простір)

  • Модель/автентифікація

    • Ключ Anthropic API: використовує ANTHROPIC_API_KEY, якщо він наявний, або просить ввести ключ, а потім зберігає його для використання демоном.
    • Ключ Anthropic API: бажаний вибір асистента Anthropic в onboarding/configure.
    • setup-token Anthropic: досі доступний в onboarding/configure, хоча OpenClaw тепер надає перевагу повторному використанню Claude CLI, коли це доступно.
    • Підписка OpenAI Code (Codex) (OAuth): браузерний потік; вставте code#state.
      • Встановлює agents.defaults.model на openai-codex/gpt-5.5, коли модель не задана або вже належить до сімейства OpenAI.
    • Підписка OpenAI Code (Codex) (сполучення пристрою): браузерний потік сполучення з короткочасним кодом пристрою.
      • Встановлює agents.defaults.model на openai-codex/gpt-5.5, коли модель не задана або вже належить до сімейства OpenAI.
    • Ключ OpenAI API: використовує OPENAI_API_KEY, якщо він наявний, або просить ввести ключ, а потім зберігає його в профілях автентифікації.
      • Встановлює agents.defaults.model на openai/gpt-5.5, коли модель не задана, openai/* або openai-codex/*.
    • Ключ xAI (Grok) API: просить ввести XAI_API_KEY і налаштовує xAI як постачальника моделей.
    • 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, виявляють доступні моделі й автоматично завантажують вибрану локальну модель за потреби; Cloud + Local також перевіряє, чи цей хост Ollama увійшов у систему для хмарного доступу.
    • Докладніше: Ollama
    • Ключ API: зберігає ключ для вас.
    • Vercel AI Gateway (багатомодельний проксі): просить ввести AI_GATEWAY_API_KEY.
    • Докладніше: Vercel AI Gateway
    • Cloudflare AI Gateway: просить ввести Account ID, Gateway ID і CLOUDFLARE_AI_GATEWAY_API_KEY.
    • Докладніше: Cloudflare AI Gateway
    • MiniMax: конфігурація записується автоматично; розміщене значення за замовчуванням — MiniMax-M2.7. Налаштування з ключем API використовує minimax/..., а налаштування OAuth використовує minimax-portal/....
    • Докладніше: MiniMax
    • StepFun: конфігурація записується автоматично для StepFun standard або Step Plan на китайських чи глобальних кінцевих точках.
    • Standard наразі містить step-3.5-flash, а Step Plan також містить step-3.5-flash-2603.
    • Докладніше: StepFun
    • Synthetic (сумісний з Anthropic): просить ввести SYNTHETIC_API_KEY.
    • Докладніше: Synthetic
    • Moonshot (Kimi K2): конфігурація записується автоматично.
    • Kimi Coding: конфігурація записується автоматично.
    • Докладніше: Moonshot AI (Kimi + Kimi Coding)
    • Пропустити: автентифікацію ще не налаштовано.
    • Виберіть модель за замовчуванням із виявлених варіантів (або введіть provider/model вручну). Для найкращої якості та нижчого ризику prompt-injection виберіть найсильнішу модель останнього покоління, доступну у вашому стеку постачальників.
    • Onboarding запускає перевірку моделі й попереджає, якщо налаштована модель невідома або для неї бракує автентифікації.
    • Режим зберігання ключів API за замовчуванням використовує відкритий текст у значеннях auth-profile. Використовуйте --secret-input-mode ref, щоб натомість зберігати посилання на основі env (наприклад keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }).
    • Профілі автентифікації містяться в ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (ключі API + OAuth). ~/.openclaw/credentials/oauth.json — лише застаріле джерело імпорту.
    • Докладніше: /concepts/oauth

  • Робочий простір

    • Типово ~/.openclaw/workspace (можна налаштувати).
    • Заповнює робочий простір файлами, потрібними для ритуалу bootstrap агента.
    • Повна структура робочого простору + посібник із резервного копіювання: Робочий простір агента

  • Gateway

    • Порт, прив’язка, режим автентифікації, експозиція tailscale.
    • Рекомендація щодо автентифікації: залишайте Token навіть для loopback, щоб локальні WS-клієнти мусили автентифікуватися.
    • У режимі token інтерактивне налаштування пропонує:
      • Згенерувати/зберегти токен відкритим текстом (типово)
      • Використати SecretRef (за згодою)
      • Quickstart повторно використовує наявні SecretRef gateway.auth.token у постачальниках env, file і exec для onboarding probe/dashboard bootstrap.
      • Якщо цей SecretRef налаштовано, але його не вдається розв’язати, onboarding завершується рано з чітким повідомленням про виправлення, замість тихо погіршувати автентифікацію runtime.
    • У режимі password інтерактивне налаштування також підтримує зберігання відкритим текстом або SecretRef.
    • Неінтерактивний шлях token SecretRef: --gateway-token-ref-env &lt;ENV_VAR&gt;.
      • Потребує непорожньої env var у середовищі процесу onboarding.
      • Не можна поєднувати з --gateway-token.
    • Вимикайте автентифікацію лише якщо повністю довіряєте кожному локальному процесу.
    • Прив’язки не до loopback усе одно потребують автентифікації.

  • Канали

    • WhatsApp: необов’язковий вхід через QR.
    • Telegram: токен бота.
    • Discord: токен бота.
    • Google Chat: service account JSON + аудиторія webhook.
    • Mattermost (plugin): токен бота + базовий URL.
    • Signal: необов’язкове встановлення signal-cli + конфігурація облікового запису.
    • BlueBubbles: рекомендовано для iMessage; URL сервера + пароль + webhook.
    • iMessage: застарілий шлях CLI imsg + доступ до БД.
    • Безпека DM: за замовчуванням використовується сполучення. Перший DM надсилає код; підтвердьте через openclaw pairing approve <channel> <code> або використайте allowlists.

  • Вебпошук

    • Виберіть підтримуваного постачальника, наприклад Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG або Tavily (або пропустіть).
    • Постачальники з API можуть використовувати env vars або наявну конфігурацію для швидкого налаштування; постачальники без ключів натомість використовують свої специфічні передумови.
    • Пропустіть за допомогою --skip-search.
    • Налаштувати пізніше: openclaw configure --section web.

  • Встановлення демона

    • macOS: LaunchAgent
      • Потребує сесії користувача, що ввійшов у систему; для headless використовуйте власний LaunchDaemon (не постачається).
    • Linux (і Windows через WSL2): systemd user unit
      • Onboarding намагається ввімкнути lingering через loginctl enable-linger <user>, щоб Gateway залишався запущеним після виходу.
      • Може попросити sudo (записує /var/lib/systemd/linger); спочатку пробує без sudo.
    • Вибір runtime: Node (рекомендовано; потрібно для WhatsApp/Telegram). Bun не рекомендовано.
    • Якщо token auth потребує токена, а gateway.auth.token керується SecretRef, встановлення демона перевіряє його, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища supervisor service.
    • Якщо token auth потребує токена, а налаштований token SecretRef не розв’язано, встановлення демона блокується з практичними вказівками.
    • Якщо налаштовано і gateway.auth.token, і gateway.auth.password, а gateway.auth.mode не задано, встановлення демона блокується, доки режим не буде задано явно.

  • Перевірка стану

    • Запускає Gateway (за потреби) і виконує openclaw health.
    • Порада: openclaw status --deep додає live gateway health probe до виводу статусу, зокрема channel probes, коли вони підтримуються (потребує доступного gateway).

  • Skills (рекомендовано)

    • Зчитує доступні Skills і перевіряє вимоги.
    • Дає змогу вибрати node manager: npm / pnpm (bun не рекомендовано).
    • Встановлює необов’язкові залежності (деякі використовують Homebrew на macOS).

  • Завершення

    • Підсумок + наступні кроки, зокрема застосунки iOS/Android/macOS для додаткових функцій.

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

    Використовуйте --non-interactive, щоб автоматизувати або скриптувати onboarding:

    openclaw onboard --non-interactive \
  --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 для машинозчитуваного підсумку.

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

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

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

    Приклади команд для окремих постачальників містяться в CLI Automation. Використовуйте цю довідкову сторінку для семантики прапорців і порядку кроків.

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

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

    Gateway wizard RPC

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

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

    Onboarding може встановити signal-cli з GitHub releases:

    • Завантажує відповідний release asset.
    • Зберігає його в ~/.openclaw/tools/signal-cli/<version>/.
    • Записує channels.signal.cliPath у вашу конфігурацію.

    Примітки:

    • JVM-збірки потребують Java 21.
    • Native-збірки використовуються, коли доступні.
    • Windows використовує WSL2; встановлення signal-cli відбувається за потоком Linux усередині WSL.

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

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

    • agents.defaults.workspace
    • agents.defaults.model / models.providers (якщо вибрано Minimax)
    • tools.profile (локальна адаптація за замовчуванням використовує "coding", якщо не задано; наявні явно задані значення зберігаються)
    • gateway.* (режим, прив’язка, автентифікація, tailscale)
    • session.dmScope (деталі поведінки: Довідник налаштування CLI)
    • 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.
      • Ручна конфігурація все ще може використовувати yarn, якщо встановити skills.install.nodeManager напряму.
    • wizard.lastRunAt
    • wizard.lastRunVersion
    • wizard.lastRunCommit
    • wizard.lastRunCommand
    • wizard.lastRunMode

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

    Облікові дані WhatsApp зберігаються в ~/.openclaw/credentials/whatsapp/<accountId>/. Сеанси зберігаються в ~/.openclaw/agents/<agentId>/sessions/.

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

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