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

  • Каналы

    • WhatsApp: необязательный вход по QR-коду
    • Telegram: токен бота
    • Discord: токен бота
    • Google Chat: JSON сервисного аккаунта + аудитория вебхука
    • 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

    Предпочтительный локальный способ при интерактивной первоначальной настройке или конфигурировании; повторно использует существующий вход в Claude CLI, если он доступен.

    Подписка 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 как поставщика моделей. Используйте этот вариант, если вместо OAuth по подписке нужен ключ API из xAI Console.

    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 и интерфейс управления) могут отображать шаги без повторной реализации логики первоначальной настройки.

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

    • Загружает подходящий ресурс выпуска из официальных выпусков signal-cli на GitHub (нативная сборка, только 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