Справочник по Onboarding CLI

Эта страница представляет собой полный справочник по команде openclaw onboard. Для краткого руководства см. Мастер Onboarding (CLI).

Что делает мастер

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

• Настройку модели и аутентификации (OAuth подписки OpenAI Code, ключ API или токен настройки Anthropic, а также опции MiniMax, GLM, Moonshot и AI Gateway)
• Расположение рабочего пространства и начальные файлы
• Настройки шлюза (порт, привязка, аутентификация, tailscale)
• Каналы и провайдеры (Telegram, WhatsApp, Discord, Google Chat, плагин Mattermost, Signal)
• Установку демона (LaunchAgent или пользовательский юнит systemd)
• Проверку работоспособности
• Настройку навыков

Удаленный режим настраивает этот компьютер для подключения к шлюзу в другом месте. Он не устанавливает и не изменяет ничего на удаленном хосте.

Детали локального процесса

Шаг 1: Обнаружение существующей конфигурации

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

Шаг 2: Модель и аутентификация

• Полная матрица опций приведена в разделе Опции аутентификации и модели.

Шаг 3: Рабочее пространство

• По умолчанию ~/.openclaw/workspace (настраивается).
• Заполняет файлы рабочего пространства, необходимые для начальной процедуры начальной загрузки.
• Структура рабочего пространства: Рабочее пространство агента.

Шаг 4: Шлюз

• Запрашивает порт, привязку, режим аутентификации и доступ через tailscale.
• Рекомендуется: оставить аутентификацию по токену включенной даже для loopback, чтобы локальные WS-клиенты должны были проходить аутентификацию.
• В режиме токена интерактивный onboarding предлагает:
  • Сгенерировать/сохранить токен в открытом виде (по умолчанию)
  • Использовать SecretRef (опционально)
• В режиме пароля интерактивный onboarding также поддерживает хранение в открытом виде или через SecretRef.
• Путь к SecretRef токена в неинтерактивном режиме: --gateway-token-ref-env <ENV_VAR>.
  • Требует наличия непустой переменной окружения в среде процесса onboarding.
  • Нельзя комбинировать с --gateway-token.
• Отключайте аутентификацию только если вы полностью доверяете каждому локальному процессу.
• Привязки не к loopback все равно требуют аутентификации.

Шаг 5: Каналы

• WhatsApp: опциональный вход по QR-коду
• Telegram: токен бота
• Discord: токен бота
• Google Chat: JSON сервисного аккаунта + аудитория вебхука
• Плагин Mattermost: токен бота + базовый URL
• Signal: опциональная установка signal-cli + настройка аккаунта
• BlueBubbles: рекомендуется для iMessage; URL сервера + пароль + вебхук
• iMessage: устаревший путь CLI imsg + доступ к БД
• Безопасность личных сообщений: по умолчанию используется сопряжение. Первое ЛС отправляет код; подтвердите через openclaw pairing approve <channel> <code> или используйте списки разрешений.

Шаг 6: Установка демона

• macOS: LaunchAgent
  • Требует сеанс вошедшего в систему пользователя; для headless используйте пользовательский LaunchDaemon (не поставляется).
• Linux и Windows через WSL2: пользовательский юнит systemd
  • Мастер пытается выполнить loginctl enable-linger <user>, чтобы шлюз оставался активным после выхода из системы.
  • Может запросить sudo (записывает в /var/lib/systemd/linger); сначала пытается без sudo.
• Выбор среды выполнения: Node (рекомендуется; требуется для WhatsApp и Telegram). Bun не рекомендуется.

Шаг 7: Проверка работоспособности

• Запускает шлюз (если нужно) и выполняет openclaw health.
• openclaw status --deep добавляет проверки работоспособности шлюза в вывод статуса.

Шаг 8: Навыки

• Читает доступные навыки и проверяет требования.
• Позволяет выбрать менеджер пакетов: npm или pnpm (bun не рекомендуется).
• Устанавливает опциональные зависимости (некоторые используют Homebrew на macOS).

Шаг 9: Завершение

• Сводка и следующие шаги, включая опции для iOS, Android и macOS приложений.

ℹ️ Если GUI не обнаружен, мастер выводит инструкции по SSH port-forward для Control UI вместо открытия браузера. Если ресурсы Control UI отсутствуют, мастер пытается их собрать; запасной вариант — pnpm ui:build (автоматически устанавливает зависимости UI).

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

Удаленный режим настраивает этот компьютер для подключения к шлюзу в другом месте.

ℹ️ Удаленный режим не устанавливает и не изменяет ничего на удаленном хосте.

Что вы настраиваете:

• URL удаленного шлюза (ws://...)
• Токен, если удаленный шлюз требует аутентификации (рекомендуется)

ℹ️ - Если шлюз доступен только через loopback, используйте SSH туннелирование или tailnet.

• Подсказки по обнаружению:
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

Опции аутентификации и модели

Поведение модели:

• Выберите модель по умолчанию из обнаруженных опций или введите провайдера и модель вручную.
• Мастер выполняет проверку модели и предупреждает, если настроенная модель неизвестна или отсутствует аутентификация.

Пути учетных данных и профилей:

• Учетные данные OAuth: ~/.openclaw/credentials/oauth.json
• Профили аутентификации (ключи API + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Режим хранения учетных данных:

• Поведение onboarding по умолчанию сохраняет ключи API как значения в открытом виде в профилях аутентификации.
• --secret-input-mode ref включает режим ссылок вместо хранения ключей в открытом виде. В интерактивном onboarding вы можете выбрать:
  • ссылку на переменную окружения (например, keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • настроенную ссылку на провайдера (file или exec) с псевдонимом провайдера + id
• Интерактивный режим ссылок выполняет быструю предварительную проверку перед сохранением.
  • Ссылки на переменные окружения: проверяет имя переменной + непустое значение в текущей среде onboarding.
  • Ссылки на провайдеров: проверяет конфигурацию провайдера и разрешает запрошенный id.
  • Если предварительная проверка не удалась, onboarding показывает ошибку и позволяет повторить.
• В неинтерактивном режиме --secret-input-mode ref поддерживает только ссылки на переменные окружения.
  • Установите переменную окружения провайдера в среде процесса onboarding.
  • Встроенные флаги ключей (например, --openai-api-key) требуют, чтобы эта переменная окружения была установлена; иначе onboarding быстро завершится с ошибкой.
  • Для пользовательских провайдеров неинтерактивный режим ref сохраняет models.providers.<id>.apiKey как { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • В этом случае с пользовательским провайдером --custom-api-key требует, чтобы CUSTOM_API_KEY был установлен; иначе onboarding быстро завершится с ошибкой.
• Учетные данные аутентификации шлюза поддерживают выбор открытого текста и SecretRef в интерактивном onboarding:
  • Режим токена: Сгенерировать/сохранить токен в открытом виде (по умолчанию) или Использовать SecretRef.
  • Режим пароля: открытый текст или SecretRef.
• Путь к SecretRef токена в неинтерактивном режиме: --gateway-token-ref-env <ENV_VAR>.
• Существующие настройки с открытым текстом продолжают работать без изменений.

ℹ️ Совет для headless и серверов: завершите OAuth на машине с браузером, затем скопируйте ~/.openclaw/credentials/oauth.json (или $OPENCLAW_STATE_DIR/credentials/oauth.json) на хост шлюза.

Результаты и внутреннее устройство

Типичные поля в ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.model / models.providers (если выбран Minimax)
• tools.profile (локальный onboarding по умолчанию устанавливает "coding", если не задано; существующие явные значения сохраняются)
• gateway.* (режим, привязка, аутентификация, tailscale)
• session.dmScope (локальный onboarding по умолчанию устанавливает это в per-channel-peer, если не задано; существующие явные значения сохраняются)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Списки разрешений каналов (Slack, Discord, Matrix, Microsoft Teams), когда вы соглашаетесь во время запросов (имена разрешаются в ID, когда возможно)
• 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/.

ℹ️ Некоторые каналы поставляются в виде плагинов. При выборе во время onboarding мастер запрашивает установку плагина (npm или локальный путь) перед настройкой канала.

RPC мастера шлюза:

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

Клиенты (приложение для macOS и Control UI) могут отображать шаги без повторной реализации логики onboarding. Поведение настройки Signal:

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

Связанная документация

• Центр onboarding: Мастер Onboarding (CLI)
• Автоматизация и скрипты: Автоматизация CLI
• Справочник команд: openclaw onboard

Настройка персонального помощникаАвтоматизация CLI