OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Technical reference

Довідник із початкового налаштування

Це повний довідник для openclaw onboard. Загальний огляд див. у розділі Початкове налаштування (CLI). Покрокову поведінку та результати див. у довіднику з налаштування CLI.

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

  • Скидання (необов’язково)

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

  • Підтвердження усвідомлення ризиків

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

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

    • Ключ 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
    • Ключ API: зберігає ключ.
    • Vercel AI Gateway (багатомодельний проксі-сервер): запитує AI_GATEWAY_API_KEY.
    • Докладніше: Vercel AI Gateway
    • Cloudflare AI Gateway: запитує ідентифікатор облікового запису, ідентифікатор Gateway і CLOUDFLARE_AI_GATEWAY_API_KEY.
    • Докладніше: Cloudflare AI Gateway
    • MiniMax: конфігурація записується автоматично; типове значення для розміщеної версії — MiniMax-M3. Для налаштування за допомогою ключа API використовується minimax/..., а для налаштування OAuth — minimax-portal/....
    • Докладніше: MiniMax
    • StepFun: конфігурація записується автоматично для стандартного StepFun або Step Plan на кінцевих точках у Китаї чи глобальних кінцевих точках.
    • Наразі типовим значенням стандартного варіанта є 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)
    • Власний постачальник: працює з кінцевими точками, сумісними з 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

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

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

  • Gateway

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

  • Канали

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

  • Вебпошук

    • Виберіть підтримуваного постачальника, наприклад 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.

  • Встановлення фонової служби

    • 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 не встановлено, встановлення фонової служби блокується, доки режим не буде задано явно.

  • Перевірка працездатності

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

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

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

  • Завершення

    • Підсумок і подальші кроки, зокрема запит Як потрібно запустити вашого агента? з варіантами «Термінал», «Браузер» або «Пізніше».

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

    Використовуйте --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 є взаємовиключними.

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

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

    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)
    • 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 або локального шляху), перш ніж його можна буде налаштувати.

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

    Was this useful?
    On this page

    On this page