Справочник CLI-онбординга

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

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

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

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

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

Подробности локального режима

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

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

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

- Полная матрица вариантов — в разделе [Варианты аутентификации и моделей](#варианты-аутентификации-и-моделей).

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

- По умолчанию `~/.openclaw/workspace` (настраивается).
- Создаёт файлы рабочего пространства для ритуала первого запуска.
- Структура: [Рабочее пространство агента](/docs/concepts/agent-workspace).

Шаг 4: Gateway

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

Шаг 5: Каналы

- [WhatsApp](/docs/channels/whatsapp): опциональный QR-логин
- [Telegram](/docs/channels/telegram): токен бота
- [Discord](/docs/channels/discord): токен бота
- [Google Chat](/docs/channels/googlechat): JSON сервисного аккаунта + webhook audience
- Плагин [Mattermost](/docs/channels/mattermost): токен бота + базовый URL
- [Signal](/docs/channels/signal): опциональная установка `signal-cli` + настройка аккаунта
- [BlueBubbles](/docs/channels/bluebubbles): рекомендуется для iMessage; URL сервера + пароль + webhook
- [iMessage](/docs/channels/imessage): legacy — путь к CLI `imsg` + доступ к БД
- Безопасность DM: по умолчанию — привязка. Первое DM-сообщение отправляет код; подтверждение через
  `openclaw pairing approve <channel> <code>` или списки разрешённых.

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

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

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

- Запускает Gateway (при необходимости) и выполняет `openclaw health`.
- `openclaw status --deep` добавляет проверки состояния Gateway к выводу статуса.

Шаг 8: Skills

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

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

- Итог и дальнейшие шаги, включая приложения iOS, Android и macOS.

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

Подробности удалённого режима

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

Совет: Удалённый режим не устанавливает и не изменяет ничего на удалённой машине.

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

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

Примечание:

• Если Gateway доступен только через 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 выберите «Всегда разрешать», чтобы запуски через 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`) и позволяет выбрать каталог Zen или Go.
URL настройки: [opencode.ai/auth](https://opencode.ai/auth).

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

Запрашивает `AI_GATEWAY_API_KEY`.
Подробнее: [Vercel AI Gateway](/docs/providers/vercel-ai-gateway).

Запрашивает account ID, gateway ID и `CLOUDFLARE_AI_GATEWAY_API_KEY`.
Подробнее: [Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway).

Конфигурация записывается автоматически.
Подробнее: [MiniMax](/docs/providers/minimax).

Запрашивает `SYNTHETIC_API_KEY`.
Подробнее: [Synthetic](/docs/providers/synthetic).

Запрашивает базовый URL (по умолчанию `http://127.0.0.1:11434`), затем предлагает режим Cloud + Local или только Local.
Обнаруживает доступные модели и предлагает значения по умолчанию.
Подробнее: [Ollama](/docs/providers/ollama).

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

Работает с OpenAI-compatible и Anthropic-compatible эндпоинтами.

В интерактивном онбординге доступны те же варианты хранения API-ключей, что и для других провайдеров:
- **Вставить API-ключ сейчас** (открытый текст)
- **Использовать ссылку на секрет** (env ref или настроенная ссылка на провайдера, с предварительной проверкой)

Неинтерактивные флаги:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (опционально; fallback на `CUSTOM_API_KEY`)
- `--custom-provider-id` (опционально)
- `--custom-compatibility <openai|anthropic>` (опционально; по умолчанию `openai`)

Аутентификация остаётся ненастроенной.

Поведение выбора модели:

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

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

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

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

• По умолчанию онбординг сохраняет API-ключи открытым текстом в профилях аутентификации.
• --secret-input-mode ref включает режим ссылок вместо хранения ключей открытым текстом. В интерактивном онбординге доступен выбор:
  • ссылка на переменную окружения (например, keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • ссылка на настроенного провайдера (file или exec) с алиасом провайдера + id
• В интерактивном режиме ссылок выполняется быстрая предварительная проверка перед сохранением.
  • Ссылки на env: проверяется имя переменной и наличие непустого значения в текущей среде онбординга.
  • Ссылки на провайдеров: проверяется конфигурация провайдера и разрешается запрошенный id.
  • При неудаче проверки онбординг показывает ошибку и позволяет повторить попытку.
• В неинтерактивном режиме --secret-input-mode ref работает только с env-ссылками.
  • Установите переменную окружения провайдера в среде процесса онбординга.
  • Инлайн-флаги ключей (например, --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 <ENV_VAR>.
• Существующие конфигурации с открытым текстом продолжают работать без изменений.

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

Выходные данные и внутренние механизмы

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

• agents.defaults.workspace
• agents.defaults.model / models.providers (при выборе Minimax)
• tools.profile (локальный онбординг по умолчанию устанавливает "coding", если значение не задано; существующие явные значения сохраняются)
• gateway.* (режим, привязка, аутентификация, Tailscale)
• session.dmScope (локальный онбординг по умолчанию устанавливает 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/.

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

RPC мастера Gateway:

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

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

Поведение настройки Signal:

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

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

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