OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Technical reference

Справочник по первоначальной настройке

Это полный справочник по openclaw onboard. Общий обзор см. в разделе Первоначальная настройка (CLI). Пошаговое описание поведения и результатов см. в справочнике по настройке через CLI.

Подробное описание процесса (локальный режим)

  • Сброс (необязательно)

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

  • Подтверждение рисков

    • При первом запуске (или любом запуске до установки wizard.securityAcknowledgedAt) требуется подтвердить, что вы понимаете: агенты обладают широкими возможностями, а полный доступ к системе сопряжён с риском.
    • --non-interactive требует явно указать --accept-risk; без него первоначальная настройка завершается с ошибкой, не запрашивая подтверждение.
    • При интерактивном запуске вместо флага отображается запрос подтверждения; отказ отменяет настройку.

  • Модель и аутентификация

    • Ключ API Anthropic: использует ANTHROPIC_API_KEY, если он задан, либо запрашивает ключ, а затем сохраняет его для использования демоном.
    • Anthropic Claude CLI: предпочтительный локальный вариант, если вход через Claude CLI уже выполнен; в качестве альтернативы OpenClaw также поддерживает аутентификацию Anthropic с помощью токена настройки.
    • Подписка OpenAI Code (Codex) (OAuth): процесс в браузере; вставьте code#state.
      • При новой настройке без основной модели задаёт для agents.defaults.model значение openai/gpt-5.6-sol через среду выполнения Codex.
    • Подписка OpenAI Code (Codex) (сопряжение устройства): процесс сопряжения в браузере с краткосрочным кодом устройства.
      • При новой настройке без основной модели задаёт для 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: вход в браузере по коду устройства без обратного вызова на localhost, поэтому он также работает через SSH/Docker/VPS (--auth-choice xai-oauth).
    • Ключ API xAI: запрашивает XAI_API_KEY (--auth-choice xai-api-key).
    • --auth-choice xai-device-code по-прежнему работает как доступный только вручную псевдоним совместимости для того же процесса OAuth xAI по коду устройства; в новых скриптах используйте xai-oauth.
    • OpenCode: запрашивает OPENCODE_API_KEY (или OPENCODE_ZEN_API_KEY, получить его можно на https://opencode.ai/auth) и позволяет выбрать каталог Zen или Go.
    • Ollama: сначала предлагает варианты Облако + локально, Только облако или Только локально. Cloud only запрашивает OLLAMA_API_KEY и использует https://ollama.com; режимы с собственным хостом запрашивают базовый URL Ollama (по умолчанию http://127.0.0.1:11434), обнаруживают доступные модели и при необходимости автоматически загружают выбранную локальную модель; Cloud + Local также проверяет, выполнен ли на этом хосте Ollama вход для облачного доступа.
    • Подробнее: Ollama
    • Ключ API: сохраняет ключ за вас.
    • Vercel AI Gateway (прокси для нескольких моделей): запрашивает AI_GATEWAY_API_KEY.
    • Подробнее: Vercel AI Gateway
    • Cloudflare AI Gateway: запрашивает идентификатор учётной записи, идентификатор 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
    • Moonshot (Kimi K2): конфигурация записывается автоматически.
    • Kimi Coding: конфигурация записывается автоматически.
    • Подробнее: Moonshot AI (Kimi + Kimi Coding)
    • Пользовательский провайдер: работает с конечными точками, совместимыми с OpenAI, OpenAI Responses или Anthropic. Флаги неинтерактивного режима: --auth-choice custom-api-key, --custom-base-url, --custom-model-id, --custom-api-key (необязательно; при отсутствии используется CUSTOM_API_KEY), --custom-provider-id (необязательно; автоматически определяется из базового URL), --custom-compatibility openai|openai-responses|anthropic (по умолчанию openai), --custom-image-input / --custom-text-input (переопределяют автоматически определённую поддержку изображений моделью).
    • Пропустить: аутентификация пока не настроена.
    • Выберите модель по умолчанию из обнаруженных вариантов (либо введите провайдера и модель вручную). Для наилучшего качества и снижения риска внедрения инструкций выбирайте наиболее мощную доступную модель последнего поколения в стеке вашего провайдера.
    • Первоначальная настройка проверяет модель и предупреждает, если настроенная модель неизвестна или для неё отсутствует аутентификация.
    • По умолчанию ключи API хранятся как значения профиля аутентификации в виде открытого текста. Используйте --secret-input-mode ref, чтобы вместо этого хранить ссылки на переменные окружения (например, keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }); указанная переменная окружения уже должна быть задана, иначе первоначальная настройка немедленно завершится с ошибкой.
    • Профили аутентификации находятся в ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (ключи API и OAuth). ~/.openclaw/credentials/oauth.json используется только для импорта устаревших данных.
    • Подробнее: OAuth

  • Рабочее пространство

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

  • Gateway

    • Порт (по умолчанию 18789), привязка, режим аутентификации, доступ через Tailscale.
    • Рекомендация по аутентификации: оставьте Токен даже для loopback, чтобы локальным клиентам WS требовалась аутентификация.
    • В режиме токена интерактивная настройка предлагает:
      • Создать и сохранить токен в виде открытого текста (по умолчанию)
      • Использовать SecretRef (по желанию)
      • Быстрая настройка повторно использует существующие ссылки SecretRef из gateway.auth.token у провайдеров env, file и exec для проверки во время первоначальной настройки и начальной загрузки панели управления.
      • Если ссылка SecretRef настроена, но не может быть разрешена, первоначальная настройка завершается на раннем этапе с понятным сообщением об исправлении, а не незаметно ослабляет аутентификацию среды выполнения.
    • В режиме пароля интерактивная настройка также поддерживает хранение в виде открытого текста или SecretRef.
    • Путь SecretRef для токена в неинтерактивном режиме: --gateway-token-ref-env &lt;ENV_VAR&gt;.
      • Требуется непустая переменная окружения в среде процесса первоначальной настройки.
      • Нельзя использовать вместе с --gateway-token.
    • Отключайте аутентификацию только при полном доверии ко всем локальным процессам.
    • Для привязок не к loopback по-прежнему требуется аутентификация.

  • Каналы

    • WhatsApp: необязательный вход по QR-коду.
    • Telegram: токен бота.
    • Discord: токен бота.
    • Google Chat: JSON служебной учётной записи и аудитория Webhook.
    • Mattermost (плагин): токен бота и базовый URL.
    • Signal (плагин): необязательная установка signal-cli и настройка учётной записи.
    • iMessage: путь к CLI imsg и доступ к базе данных Messages; если Gateway работает не на Mac, используйте обёртку SSH.
    • Discord, Feishu, Microsoft Teams, QQ Bot, Slack и другие каналы поставляются как плагины, которые первоначальная настройка может установить за вас. Полный каталог: Каналы.
    • Безопасность личных сообщений: по умолчанию используется сопряжение. При первом личном сообщении отправляется код; подтвердите его с помощью openclaw pairing approve <channel> <code> или используйте списки разрешений.

  • Веб-поиск

    • Выберите поддерживаемого провайдера, например Brave, Codex (размещённый поиск), DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Parallel, Perplexity, SearXNG или Tavily (либо пропустите этот шаг).
    • Для быстрой настройки провайдеры с API могут использовать переменные окружения или существующую конфигурацию; провайдеры без ключей вместо этого используют собственные предварительные требования.
    • Пропустить с помощью --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, поскольку каноническое хранилище состояния среды выполнения использует node:sqlite. Устаревшие службы Bun при восстановлении переносятся на Node.
    • Если для аутентификации по токену требуется токен и gateway.auth.token управляется через SecretRef, установка демона проверяет его, но не сохраняет разрешённое значение токена в виде открытого текста в метаданных окружения службы супервизора.
    • Если для аутентификации по токену требуется токен, но настроенная ссылка SecretRef токена не разрешается, установка демона блокируется с практическими рекомендациями по устранению проблемы.
    • Если настроены и gateway.auth.token, и gateway.auth.password, а gateway.auth.mode не задан, установка демона блокируется до явного выбора режима.

  • Проверка работоспособности

    • Запускает Gateway (при необходимости) и выполняет openclaw health.
    • Совет: openclaw status --deep добавляет в вывод состояния проверку работоспособности активного Gateway, включая проверки каналов, если они поддерживаются (требуется доступный Gateway).

  • Skills (рекомендуется)

    • Считывает доступные навыки и проверяет требования.
    • Позволяет выбрать менеджер Node: npm / pnpm / bun.
    • Автоматически устанавливает необязательные зависимости для доверенных встроенных навыков (некоторые используют Homebrew в macOS).
    • Пропускает навыки, для которых недоступен необходимый установщик Homebrew, uv или Go, группирует их вместе с инструкциями по ручной настройке и указывает на openclaw doctor после установки предварительного требования.

  • Завершение

    • Сводка и дальнейшие действия, включая запрос Как вы хотите запустить своего агента? с вариантами: терминал, браузер или позже.

    • Неинтерактивный режим

    Используйте --non-interactive --accept-risk для автоматизации первоначальной настройки или её выполнения из скрипта (этот флаг является обязательным подтверждением принятия риска; без него мастер первоначальной настройки завершается с ошибкой):

    bash
    openclaw onboard --non-interactive --accept-risk \  --mode local \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY" \  --gateway-port 18789 \  --gateway-bind loopback \  --install-daemon \  --daemon-runtime node \  --skip-skills

    Добавьте --json, чтобы получить сводку в машиночитаемом формате.

    SecretRef токена Gateway в неинтерактивном режиме:

    bash
    export OPENCLAW_GATEWAY_TOKEN="your-token"openclaw onboard --non-interactive --accept-risk \  --mode local \  --auth-choice skip \  --gateway-auth token \  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

    --gateway-token и --gateway-token-ref-env являются взаимоисключающими.

    Примеры команд для отдельных провайдеров приведены в разделе Автоматизация CLI. Описание семантики флагов и порядка шагов см. на этой справочной странице.

    Добавление агента (неинтерактивно)

    bash
    openclaw agents add work \  --workspace ~/.openclaw/workspace-work \  --model openai/gpt-5.6-sol \  --bind whatsapp:biz \  --non-interactive \  --json

    main — зарезервированный идентификатор агента, который нельзя использовать для openclaw agents add.

    RPC мастера Gateway

    Gateway предоставляет процесс первоначальной настройки через RPC (wizard.start, wizard.next, wizard.cancel, wizard.status). Клиенты (приложение macOS, интерфейс управления) могут отображать шаги без повторной реализации логики первоначальной настройки.

    Настройка Signal (signal-cli)

    Мастер первоначальной настройки проверяет наличие signal-cli в PATH и, если компонент отсутствует, предлагает установить его:

    • Linux x86-64: загружает официальную нативную сборку GraalVM из выпусков signal-cli на GitHub и сохраняет её в ~/.openclaw/tools/signal-cli/<version>/.
    • macOS и другие архитектуры: вместо этого выполняет установку через Homebrew.
    • Нативная Windows: пока не поддерживается; запустите первоначальную настройку в WSL2, чтобы использовать путь установки для Linux.
    • В любом случае записывает channels.signal.cliPath в конфигурацию.

    Что записывает мастер

    Типичные поля в ~/.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", если значение не задано; существующие явно заданные значения сохраняются. Подробнее: Справочник по настройке CLI)
    • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
    • Списки разрешённых личных сообщений для каналов, если вы включили их при настройке каналов. Discord, Matrix, Microsoft Teams и Slack по возможности преобразуют имена в идентификаторы; для остальных каналов идентификаторы указываются напрямую (например, числовые идентификаторы отправителей Telegram или номера телефонов WhatsApp).
    • skills.install.nodeManager
      • setup --node-manager принимает npm, pnpm или bun.
      • При ручной настройке по-прежнему можно использовать yarn, задав skills.install.nodeManager напрямую.
    • 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/ используется для входных данных миграции из устаревших версий, а также для архивных материалов и материалов поддержки.

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

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

    Was this useful?
    On this page

    On this page