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

Guides

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

Ця сторінка покроково описує поведінку, результати та внутрішню реалізацію початкового налаштування. Покроковий посібник див. у розділі Початкове налаштування (CLI). Повний довідник прапорців CLI (усі --flag, приклади неінтерактивного використання, специфічні для провайдерів команди) див. у розділі openclaw onboard.

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

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

  • Налаштування моделі й автентифікації (Anthropic, OAuth підписки OpenAI Code, xAI, OpenCode, власні кінцеві точки та інші керовані провайдерами потоки автентифікації)
  • Розташування робочого простору та файли початкового завантаження
  • Налаштування Gateway (порт, прив’язка, автентифікація, Tailscale)
  • Канали та провайдери (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp та інші вбудовані канали або канали плагінів)
  • Провайдер вебпошуку (необов’язково)
  • Встановлення фонової служби (LaunchAgent, користувацький модуль systemd або власне заплановане завдання Windows із резервним використанням папки автозавантаження)
  • Перевірка працездатності
  • Налаштування Skills

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

Відомості про локальний процес

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

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

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

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

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

  • Gateway

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

  • Канали

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

  • Вебпошук

    • Виберіть провайдера (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily) або пропустіть цей крок.
    • Пропустіть цей крок за допомогою --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, оскільки канонічне сховище стану середовища виконання OpenClaw використовує node:sqlite.

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

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

  • Skills

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

  • Завершення

    • Підсумок і подальші кроки, зокрема варіанти застосунків для iOS, Android і macOS.

    • Відомості про віддалений режим

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

    Що налаштовується:

    • URL-адреса віддаленого Gateway (ws://... або wss://...)
    • Токен, пароль або відсутність автентифікації відповідно до конфігурації віддаленого Gateway

  • Виявлення (необов’язково)

    Якщо доступна dns-sd (macOS) або avahi-browse (Linux), початкове налаштування пропонує знайти маяки Gateway через Bonjour/mDNS, перш ніж перейти до ручного введення URL-адреси. Якщо налаштовано, також виконується виявлення DNS-SD у глобальній мережі. Документація: Виявлення Gateway, Bonjour.

  • Спосіб підключення

    Після вибору маяка виберіть пряме підключення WebSocket або тунель SSH:

    • Безпосередньо: підключається через wss:// і пропонує довіряти виявленому відбитку TLS (закріплення за принципом довіри під час першого використання; закріплюється лише після вашої згоди).
    • Тунель SSH: виводить команду ssh -N -L 18789:127.0.0.1:18789 <user>@<host>, яку потрібно спочатку виконати, а потім підключається до локальної кінцевої точки тунелю.

  • Автентифікація

    Виберіть токен (рекомендовано), пароль або відсутність автентифікації, а потім за бажанням збережіть ці дані як SecretRef замість звичайного тексту.

    • Варіанти автентифікації та моделей

    Якщо крок налаштування провайдера завершується помилкою під час інтерактивного початкового налаштування (наприклад, варіант повторного використання CLI без локального входу), майстер показує помилку й повертається до вибору провайдера, а не завершує роботу. Явні запуски --auth-choice усе одно негайно завершуються помилкою для автоматизації.

    Ключ API Anthropic

    Використовує ANTHROPIC_API_KEY, якщо він наявний, або запитує ключ, а потім зберігає його для використання фоновою службою.

    CLI Anthropic Claude

    Рекомендований локальний шлях під час інтерактивного початкового налаштування або конфігурування; повторно використовує наявний вхід у CLI Claude, якщо він доступний.

    Підписка OpenAI Code (OAuth)

    Процес у браузері; вставте code#state.

    Під час нового налаштування без основної моделі встановлює agents.defaults.model у openai/gpt-5.6-sol через середовище виконання Codex.

    Підписка OpenAI Code (сполучення пристрою)

    Процес сполучення у браузері з короткочасним кодом пристрою.

    Під час нового налаштування без основної моделі встановлює 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 (Grok)

    Вхід через браузер для відповідних облікових записів SuperGrok або X Premium. Це рекомендований спосіб використання xAI для більшості користувачів. OpenClaw зберігає отриманий профіль автентифікації для моделей Grok, Grok web_search, x_search і code_execution.

    Код пристрою xAI (Grok)

    Зручний для віддаленого використання вхід через браузер із коротким кодом замість зворотного виклику localhost. Використовуйте його на хостах SSH, Docker або VPS.

    Ключ API xAI (Grok)

    Запитує XAI_API_KEY і налаштовує xAI як постачальника моделей. Використовуйте цей варіант, якщо потрібен ключ API xAI Console замість OAuth за передплатою.

    OpenCode

    Запитує OPENCODE_API_KEY (або OPENCODE_ZEN_API_KEY) і дає змогу вибрати каталог Zen або Go (один ключ API охоплює обидва). URL налаштування: opencode.ai/auth.

    Ключ API (загальний)

    Зберігає ключ для вас.

    Vercel AI Gateway

    Запитує AI_GATEWAY_API_KEY. Докладніше: Vercel AI Gateway.

    Cloudflare AI 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.

    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.

    Moonshot і Kimi Coding

    Конфігурації Moonshot (Kimi K2) і Kimi Coding записуються автоматично. Докладніше: Moonshot AI (Kimi + Kimi Coding).

    Власний постачальник

    Працює з кінцевими точками, сумісними з OpenAI, OpenAI Responses і Anthropic.

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

    • Вставити ключ API зараз (відкритий текст)
    • Використати посилання на секрет (посилання на змінну середовища або налаштованого постачальника з попередньою перевіркою)

    Під час початкового налаштування підтримка зображень визначається для поширених ідентифікаторів моделей комп’ютерного зору (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral і подібних), а запит з’являється лише тоді, коли назва моделі невідома.

    Прапорці неінтерактивного режиму:

    • --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 (необов’язково; перевизначає визначену можливість введення моделі)
    Пропустити

    Залишає автентифікацію неналаштованою.

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

    • Виберіть стандартну модель із виявлених варіантів або введіть постачальника та модель вручну.
    • Якщо початкове налаштування запускається з вибору автентифікації постачальника, засіб вибору моделі автоматично надає перевагу цьому постачальнику. Для Volcengine і BytePlus ця сама перевага також поширюється на їхні варіанти планів для програмування (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) із псевдонімом та ідентифікатором постачальника
    • Інтерактивний режим посилань виконує швидку попередню перевірку перед збереженням.
      • Посилання на змінні середовища: перевіряє назву змінної та непорожнє значення в поточному середовищі початкового налаштування.
      • Посилання на постачальників: перевіряє конфігурацію постачальника та знаходить запитаний ідентифікатор.
      • Якщо попередня перевірка завершується невдало, початкове налаштування показує помилку та дає змогу повторити спробу.
    • У неінтерактивному режимі --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 &lt;ENV_VAR&gt;.
    • Наявні налаштування з відкритим текстом продовжують працювати без змін.

    Результати та внутрішня структура

    Типові поля в ~/.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.*
    • Списки дозволених каналів (Discord, iMessage, Signal, Slack, Telegram, WhatsApp), якщо ви погоджуєтеся під час запитів; Discord і Slack також зіставляють введені назви з ідентифікаторами
    • 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>/agent/openclaw-agent.sqlite. Каталог ~/.openclaw/agents/<agentId>/sessions/ використовується для вхідних даних застарілої міграції та артефактів архівування й підтримки.

    Неінтерактивне налаштування

    --non-interactive вимагає --accept-risk (підтверджує, що агенти мають широкі можливості, а повний доступ до системи становить ризик):

    bash
    openclaw onboard --non-interactive --accept-risk \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY"

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

    RPC майстра Gateway

    • wizard.start
    • wizard.next
    • wizard.cancel
    • wizard.status

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

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

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

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

    Was this useful?
    On this page

    On this page