---
read_when:
- Вы хотите настроить инференс, а затем завершить настройку с помощью Crestodian
summary: Справочник CLI для `openclaw onboard` (интерактивная первоначальная настройка)
title: Первоначальная настройка
x-i18n:
generated_at: "2026-07-13T17:59:42Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 24
provider: openai
source_hash: 04933b7ec65ae82ff93629a16c33ab8d5fa7bf91b2a6ebbf10fc2f6a63fdce14
source_path: cli/onboard.md
workflow: 16
---
# `openclaw onboard`
Пошаговая настройка, которая сначала обеспечивает инференс: она обнаруживает существующий доступ к ИИ,
требует успешного выполнения реального запроса, сохраняет только рабочий маршрут, а затем запускает
Crestodian для настройки остального. `openclaw setup` — та же точка входа;
`openclaw setup --baseline` записывает только базовую конфигурацию и рабочее пространство.
Пошаговое описание интерактивного процесса CLI.
Как устроен процесс первоначальной настройки OpenClaw.
Результаты, внутреннее устройство и поведение на каждом шаге.
Флаги неинтерактивного режима и сценарии автоматической настройки.
Процесс первоначальной настройки приложения в строке меню macOS.
## Примеры
```bash
openclaw onboard
openclaw onboard --classic
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
- `--classic`: открывает полный пошаговый мастер. Его нельзя сочетать с
`--non-interactive`; для автоматической настройки не указывайте `--classic`.
- `--flow quickstart`: открывает классический мастер с минимальным количеством запросов и
автоматически создаёт токен Gateway.
- `--flow manual` (псевдоним `advanced`): открывает классический мастер с полным набором запросов
для порта, привязки и аутентификации.
- `--flow import`: запускает обнаруженного поставщика миграции (например, Hermes через `--import-from hermes`), показывает предварительный план, а после подтверждения применяет его. Импорт выполняется только для новой установки OpenClaw — если уже существуют конфигурация, учётные данные, сеансы или состояние рабочего пространства, сначала сбросьте их. Используйте [`openclaw migrate`](/ru/cli/migrate) для планов пробного запуска, режима перезаписи, отчётов и точных сопоставлений.
- `--modern` — псевдоним для совместимости, обозначающий диалогового помощника
настройки Crestodian. Он использует ту же проверку реального инференса, что и `openclaw crestodian`, и
принимает только `--workspace`, `--accept-risk`,
`--non-interactive` и `--json`. Остальные флаги настройки отклоняются, а не
игнорируются без предупреждения.
## Пошаговый процесс
Команда `openclaw onboard` без дополнительных параметров запускает пошаговый процесс. Она показывает уведомление о безопасности,
обнаруживает уже доступный доступ к ИИ через настроенные модели, переменные среды
с API-ключами и поддерживаемые локальные CLI, а затем проверяет рекомендуемого
кандидата реальным запросом. Если проверка кандидата завершается ошибкой, первоначальная настройка показывает
причину и автоматически проверяет следующего подходящего кандидата.
Если автоматическое обнаружение исчерпало все варианты, выберите другого обнаруженного кандидата или введите
API-ключ поставщика в поле с маскированным вводом. Введённый вручную ключ проверяется тем же
реальным запросом. Пошаговая первоначальная настройка
не предлагает запустить Crestodian или выйти без настройки ИИ, пока кандидат не пройдёт проверку. OpenClaw
сохраняет проверенный маршрут модели и его учётные данные только после успешного
завершения проверки; кандидат, не прошедший проверку, не заменяет настроенную модель и не сохраняет
проверяемые учётные данные. Настройки рабочего пространства и Gateway остаются без изменений до
запуска Crestodian.
В пошаговом режиме `--workspace ` передаёт Crestodian предлагаемое рабочее пространство
и изолированный контекст инференса. Они не сохраняются, пока вы не одобрите
предложение Crestodian по настройке. Классическая и неинтерактивная первоначальная настройка сохраняют
рабочее пространство в рамках обычного процесса настройки.
После успешной проверки инференса пошаговая первоначальная настройка немедленно запускает Crestodian с
проверенной моделью. Затем Crestodian может настроить рабочее пространство, Gateway,
каналы, агентов, плагины и другие необязательные функции. В Crestodian используйте
`open channel wizard for `, чтобы передать сбор учётных данных канала
терминальному мастеру с маскированным вводом. Чтобы изменить поставщика модели или способ его аутентификации,
выйдите из Crestodian и выполните `openclaw onboard`; Crestodian не открывает пошаговые
или классические процессы выбора поставщика.
Если установка уже настроена, повторный запуск `openclaw onboard` сначала проверяет текущую
модель по умолчанию, поэтому тот же процесс служит для проверки и восстановления.
Если проверка завершается ошибкой, настроенная модель никогда не заменяется автоматически —
первоначальная настройка останавливается и предлагает выбрать дальнейшее действие. Проверка выполняется вне
рабочего пространства, поэтому модель, предоставляемая плагином рабочего пространства, может не пройти её, хотя
продолжит работать в агенте.
Используйте `openclaw onboard --classic` для аутентификации конкретного поставщика, каналов, навыков,
настройки удалённого Gateway, импорта или полного управления Gateway. Для диалоговой
настройки и восстановления, не связанных с инференсом, выполните `openclaw crestodian`; `openclaw onboard
--modern` — псевдоним для совместимости, использующий ту же проверку инференса. Классический
мастер может дополнительно проверить модель по умолчанию реальным запросом, но
Crestodian не запустится, пока не пройдёт собственную проверку реального инференса.
В интерактивном терминале команда `openclaw` без подкоманды выбирает маршрут в зависимости от состояния
конфигурации:
- Если активный файл конфигурации отсутствует или не содержит заданных пользователем настроек (пуст либо
содержит только метаданные), запускается пошаговая первоначальная настройка.
- Если файл конфигурации существует, но не проходит проверку, запускается классический
процесс первоначальной настройки с указаниями `openclaw doctor`. Crestodian требует рабочего
инференса и не используется для восстановления этого состояния до настройки инференса.
- Если файл конфигурации корректен, открывается обычный TUI агента. Доступный
настроенный Gateway с агентом и моделью открывает этот интерфейс напрямую, без
первоначальной настройки или Crestodian. В настроенной установке открыть Crestodian можно с помощью
`/crestodian` в TUI или `openclaw crestodian`.
Незашифрованный протокол `ws://` допускается для адреса обратной петли, литералов частных IP-адресов, `.local` и URL-адресов Gateway в Tailnet `*.ts.net`. Для других доверенных имён в частной DNS задайте `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` в среде процесса первоначальной настройки.
## Сброс
```bash
openclaw onboard --reset
openclaw onboard --reset --reset-scope full
```
`--reset` очищает состояние перед запуском настройки. `--reset-scope` определяет объём очистки: `config` (только конфигурация), `config+creds+sessions` (значение по умолчанию, когда `--reset` передан без области действия) или `full` (также сбрасывает рабочее пространство). Сброс рабочего пространства выполняется только с `--reset-scope full`.
## Локаль
Интерактивная первоначальная настройка использует локаль мастера CLI для стандартных текстов настройки. Порядок определения:
1. `OPENCLAW_LOCALE`
2. `LC_ALL`
3. `LC_MESSAGES`
4. `LANG`
5. Английский язык в качестве резервного варианта
Поддерживаемые локали мастера: `en`, `zh-CN` и `zh-TW`. Значения локали могут использовать форму с подчёркиванием или суффиксом POSIX, например `zh_CN.UTF-8`. Названия продуктов и команд, ключи конфигурации, URL-адреса, идентификаторы поставщиков и моделей, а также метки плагинов и каналов остаются без изменений.
```bash
OPENCLAW_LOCALE=zh-CN openclaw onboard
```
## Неинтерактивная настройка
`--non-interactive` требует `--accept-risk` (подтверждает, что агенты обладают широкими возможностями и полный доступ к системе связан с риском). Значение `--mode` по умолчанию — `local`.
```bash
openclaw onboard --non-interactive \
--auth-choice custom-api-key \
--custom-base-url "https://llm.example.com/v1" \
--custom-model-id "foo-large" \
--custom-api-key "$CUSTOM_API_KEY" \
--secret-input-mode plaintext \
--custom-compatibility openai \
--custom-image-input
```
`--custom-api-key` необязателен; если он не указан, первоначальная настройка проверяет `CUSTOM_API_KEY` в среде. OpenClaw автоматически помечает распространённые идентификаторы моделей с поддержкой зрения (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral и аналогичные) как поддерживающие изображения. Передайте `--custom-image-input` для неизвестных пользовательских идентификаторов моделей с поддержкой зрения или `--custom-text-input`, чтобы принудительно задать метаданные только для текста. Используйте `--custom-compatibility openai-responses` для совместимых с OpenAI конечных точек, которые поддерживают `/v1/responses`, но не `/v1/chat/completions`; допустимые значения: `openai` (по умолчанию), `openai-responses`, `anthropic`.
Для LM Studio также предусмотрен отдельный флаг ключа поставщика:
```bash
openclaw onboard --non-interactive \
--auth-choice lmstudio \
--custom-base-url "http://localhost:1234/v1" \
--custom-model-id "qwen/qwen3.5-9b" \
--lmstudio-api-key "$LM_API_TOKEN" \
--accept-risk
```
Неинтерактивная настройка Ollama:
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
Значение `--custom-base-url` по умолчанию — `http://127.0.0.1:11434`. `--custom-model-id` необязателен; если он не указан, первоначальная настройка использует рекомендуемые значения Ollama по умолчанию. Здесь также работают идентификаторы облачных моделей, например `kimi-k2.5:cloud`.
Храните ключи поставщика в виде ссылок, а не открытого текста:
```bash
openclaw onboard --non-interactive \
--auth-choice openai-api-key \
--secret-input-mode ref \
--accept-risk
```
При использовании `--secret-input-mode ref` первоначальная настройка записывает ссылки на значения из среды вместо ключей в открытом виде: для поставщиков с профилями аутентификации записывается `keyRef: { source: "env", provider: "default", id: }`; для пользовательских поставщиков таким же образом записывается `models.providers..apiKey` (например, `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`). Условие: задайте переменную среды поставщика в среде процесса первоначальной настройки (например, `OPENAI_API_KEY`) и не передавайте одновременно флаг с ключом, если эта переменная среды не задана — значение флага без соответствующей переменной среды немедленно приводит к ошибке с указаниями по исправлению.
### Аутентификация Gateway (неинтерактивный режим)
- `--gateway-auth token --gateway-token ` сохраняет токен в открытом виде. `token` — режим аутентификации по умолчанию.
- `--gateway-auth token --gateway-token-ref-env ` сохраняет `gateway.auth.token` как SecretRef на переменную среды. В среде процесса первоначальной настройки должна быть задана непустая переменная среды с таким именем.
- `--gateway-token` и `--gateway-token-ref-env` являются взаимоисключающими.
- При использовании `--install-daemon`: управляемый через SecretRef параметр `gateway.auth.token` проверяется, но его разрешённое значение в открытом виде не сохраняется в метаданных среды службы-супервизора; если ссылку невозможно разрешить, установка завершается отказом с указаниями по исправлению. Если настроены и `gateway.auth.token`, и `gateway.auth.password`, а `gateway.auth.mode` не задан, установка блокируется до явного выбора режима.
- Локальная первоначальная настройка записывает `gateway.mode="local"` в конфигурацию. Если позднее в файле конфигурации отсутствует `gateway.mode`, это указывает на повреждение конфигурации или незавершённое ручное редактирование, а не на допустимый способ быстрого включения локального режима.
- Локальная первоначальная настройка устанавливает загружаемые плагины, необходимые для выбранного способа настройки (например, плагин среды выполнения Codex или Copilot для соответствующих вариантов аутентификации). Удалённая первоначальная настройка записывает только сведения о подключении к удалённому Gateway — она никогда не устанавливает локальные пакеты плагинов.
- `--allow-unconfigured` — отдельный аварийный механизм `openclaw gateway run`; он не позволяет первоначальной настройке пропустить `gateway.mode`.
```bash
export OPENAI_API_KEY="your-provider-key"
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
--mode local \
--auth-choice openai-api-key \
--secret-input-mode ref \
--gateway-auth token \
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
--accept-risk
```
### Работоспособность локального Gateway
- Если не передать `--skip-health`, мастер первоначальной настройки перед успешным завершением будет ожидать доступности локального Gateway.
- `--install-daemon` сначала запускает установку управляемого Gateway. Без этого параметра локальный Gateway уже должен быть запущен (например, с помощью `openclaw gateway run`).
- `--skip-health` пропускает ожидание, если при автоматизации требуется только записать конфигурацию, рабочее пространство и данные начальной настройки.
- `--skip-bootstrap` задаёт `agents.defaults.skipBootstrap: true` и пропускает создание `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` и `BOOTSTRAP.md`.
- В нативной Windows `--install-daemon` сначала пытается использовать Scheduled Tasks, а если создание задачи запрещено, добавляет для текущего пользователя элемент входа в папку Startup.
### Интерактивный режим ссылок
- При появлении запроса выберите **Использовать ссылку на секрет**, а затем — **Переменная среды** или настроенный поставщик секретов (`file` либо `exec`).
- Перед сохранением ссылки мастер первоначальной настройки выполняет быструю предварительную проверку и в случае ошибки позволяет повторить попытку.
### Варианты конечных точек Z.AI
`--auth-choice zai-api-key` автоматически определяет оптимальную конечную точку и модель Z.AI для вашего ключа: для конечных точек Coding Plan предпочтительна `zai/glm-5.2` (с переходом на `glm-5.1`, если она недоступна), а для конечных точек общего API по умолчанию используется `zai/glm-5.1`. Чтобы принудительно использовать конечную точку Coding Plan, напрямую выберите `zai-coding-global` или `zai-coding-cn`.
```bash
# Выбор конечной точки без запросов
openclaw onboard --non-interactive \
--auth-choice zai-coding-global \
--zai-api-key "$ZAI_API_KEY"
# Другие варианты конечных точек Z.AI: zai-coding-cn, zai-global, zai-cn
```
Mistral:
```bash
openclaw onboard --non-interactive \
--auth-choice mistral-api-key \
--mistral-api-key "$MISTRAL_API_KEY"
```
## Дополнительные флаги неинтерактивного режима
Аутентификация модели на основе токена (используется с `--auth-choice token`):
| Флаг | Описание |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--token-provider ` | Идентификатор поставщика токена, выпустившего токен |
| `--token ` | Значение токена для аутентификации модели |
| `--token-profile-id ` | Идентификатор профиля аутентификации (по умолчанию `:manual`; некоторые процессы, принадлежащие поставщикам, используют собственное значение по умолчанию, например `anthropic:default`) |
| `--token-expires-in ` | Необязательный срок действия токена (например, `365d`, `12h`) |
Cloudflare AI Gateway: `--cloudflare-ai-gateway-account-id `, `--cloudflare-ai-gateway-gateway-id `.
Управление установкой демона: `--no-install-daemon` / `--skip-daemon` (псевдонимы; пропускают установку службы Gateway), `--daemon-runtime `.
Skills: `--node-manager ` (по умолчанию `npm`), `--skip-skills`.
Настройка пользовательского интерфейса и хуков: `--skip-ui` (пропускает запросы Control UI/TUI), `--skip-hooks` (пропускает настройку webhook/хуков), `--skip-channels`, `--skip-search`.
Вывод: `--suppress-gateway-token-output` скрывает содержащий токены вывод Gateway/UI (подсказки о токенах, URL автоматического входа со встроенным токеном и автоматический запуск Control UI) — это полезно в общих терминалах и CI.
`--json` не включает неинтерактивный режим при пошаговой или классической первоначальной настройке.
При использовании `--modern` JSON представляет собой одноразовый обзор Crestodian, после которого выполнение завершается.
Для других скриптов используйте `--non-interactive`.
## Предварительная фильтрация поставщиков
Когда вариант аутентификации подразумевает предпочтительного поставщика, мастер первоначальной настройки предварительно фильтрует списки выбора модели по умолчанию и разрешённых моделей, оставляя модели этого поставщика. Фильтр также сопоставляет других поставщиков, принадлежащих тому же плагину, включая варианты Coding Plan, такие как `volcengine`/`volcengine-plan` и `byteplus`/`byteplus-plan`. Если фильтр предпочтительного поставщика не находит загруженных моделей, мастер первоначальной настройки возвращается к нефильтрованному каталогу, а не оставляет список выбора пустым.
## Дополнительные запросы для веб-поиска
Некоторые поставщики веб-поиска запускают дополнительные запросы, специфичные для поставщика, во время первоначальной настройки:
- **Grok** может предложить необязательную настройку `x_search` с той же аутентификацией xAI и выбором модели `x_search`.
- **Kimi** может запросить регион Moonshot API (`api.moonshot.ai` или `api.moonshot.cn`) и модель веб-поиска Kimi по умолчанию.
## Другие особенности поведения
- Поведение области личных сообщений при локальной первоначальной настройке: [справочник по настройке через CLI](/ru/start/wizard-cli-reference#outputs-and-internals).
- Самый быстрый способ начать первый чат: `openclaw dashboard` (Control UI, без настройки канала).
- Пользовательский поставщик: подключите любую конечную точку, совместимую с OpenAI или Anthropic, включая поставщиков размещённых сервисов, отсутствующих в списке. Используйте совместимость **Unknown** для автоматического определения с помощью проверки в реальном времени.
- Если обнаружено состояние Hermes, мастер первоначальной настройки предлагает процесс миграции (см. `--flow import` выше).
## Распространённые последующие команды
Позднее используйте `openclaw configure` для целевых изменений, не связанных с инференсом, и `openclaw
channels add` для настройки только каналов. Для изменения поставщика модели или маршрута аутентификации
вместо этого выполните `openclaw onboard`.
```bash
openclaw channels add
openclaw configure
openclaw agents add
```