Перейти к основному содержимому

Руководства

Справочник по 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 или используйте списки разрешений.

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

  • macOS: LaunchAgent
    • Требует сеанс вошедшего в систему пользователя; для headless используйте пользовательский LaunchDaemon (не поставляется).
  • Linux и Windows через WSL2: пользовательский юнит systemd
    • Мастер пытается выполнить loginctl enable-linger , чтобы шлюз оставался активным после выхода из системы.
    • Может запросить 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)

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

Использует ANTHROPIC_API_KEY, если присутствует, или запрашивает ключ, затем сохраняет его для использования демоном.

  • macOS: проверяет элемент Keychain “Claude Code-credentials”
  • Linux и Windows: повторно использует ~/.claude/.credentials.json, если присутствует

На macOS выберите “Always Allow”, чтобы запуски через launchd не блокировались.

Запустите claude setup-token на любой машине, затем вставьте токен. Вы можете дать ему имя; пустое значение использует значение по умолчанию.

Если существует ~/.codex/auth.json, мастер может повторно использовать его.

Браузерный процесс; вставьте code#state. Устанавливает agents.defaults.model в openai-codex/gpt-5.4, когда модель не задана или имеет значение openai/*.

Использует OPENAI_API_KEY, если присутствует, или запрашивает ключ, затем сохраняет учетные данные в профилях аутентификации. Устанавливает agents.defaults.model в openai/gpt-5.1-codex, когда модель не задана, имеет значение openai/* или openai-codex/*.

Запрашивает XAI_API_KEY и настраивает xAI как провайдера моделей.

Запрашивает OPENCODE_API_KEY (или OPENCODE_ZEN_API_KEY). URL настройки: opencode.ai/auth.

Сохраняет ключ для вас.

Запрашивает AI_GATEWAY_API_KEY. Подробнее: Vercel AI Gateway.

Запрашивает ID аккаунта, ID шлюза и CLOUDFLARE_AI_GATEWAY_API_KEY. Подробнее: Cloudflare AI Gateway.

Конфигурация записывается автоматически. Подробнее: MiniMax.

Запрашивает SYNTHETIC_API_KEY. Подробнее: Synthetic.

Конфигурации Moonshot (Kimi K2) и Kimi Coding записываются автоматически. Подробнее: Moonshot AI (Kimi + Kimi Coding).

Работает с конечными точками, совместимыми с OpenAI и Anthropic. Интерактивный onboarding поддерживает те же варианты хранения ключей API, что и другие потоки ключей API провайдеров:

  • Вставить ключ API сейчас (открытый текст)
  • Использовать ссылку на секрет (ссылка на переменную окружения или настроенная ссылка на провайдера, с предварительной проверкой)

Неинтерактивные флаги:

  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key (опционально; переходит на CUSTOM_API_KEY)
  • --custom-provider-id (опционально)
  • --custom-compatibility <openai|anthropic> (опционально; по умолчанию openai)

Оставляет аутентификацию ненастроенной.

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

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

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

  • Учетные данные OAuth: ~/.openclaw/credentials/oauth.json
  • Профили аутентификации (ключи API + OAuth): ~/.openclaw/agents//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..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//. Сессии хранятся в ~/.openclaw/agents//sessions/.

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

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

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

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

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

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

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