Как установить OpenClaw: пошаговый запуск, Gateway и проверка ошибок

Установка OpenClaw состоит не из одной команды, а из проверяемой цепочки: Node.js, CLI, onboarding, Gateway, Control UI и первый ответ в WebChat. Я бы не считал OpenClaw установленным, пока `openclaw gateway status` не показывает рабочий Gateway, а `openclaw dashboard` не открывает локальный интерфейс.

Что должно получиться после установки

После нормального запуска у вас есть команда `openclaw`, настроенный Gateway, локальная конфигурация, Control UI, WebChat и рабочий agent. Gateway обычно слушает порт `18789`, а dashboard открывает браузер с интерфейсом управления. Через него удобно проверить состояние, отправить первое сообщение и уже потом подключать Telegram, WhatsApp, Docker или skills.

Главная ошибка новичка — остановиться на `openclaw —version`. Версия CLI показывает только то, что команда установлена. Она не доказывает, что Gateway запущен, провайдер модели настроен, токен Control UI актуален, а WebChat отвечает. Поэтому в этой инструкции каждая стадия заканчивается проверкой.

Требования перед стартом

• Node.js: официальные docs указывают Node 24 как основной вариант; Node 22.14+ поддерживается, но для новой установки спокойнее ставить Node 24.
• Операционная система: macOS, Linux, Windows или WSL2. Для dev-сценариев на Windows WSL2 обычно проще, чем чистый PowerShell.
• Терминал: нужен доступ к shell, потому что установка и диагностика идут через CLI.
• Ключ провайдера модели: onboarding попросит настроить доступ к OpenAI, Anthropic, Google или другому совместимому провайдеру.
• Сеть: установщик должен скачать пакеты, а Gateway должен иметь доступ к API выбранной модели.
• Права пользователя: ставьте от обычного пользователя, если в вашем сценарии нет отдельной серверной политики.

node --version
npm --version

Если Node старый, сначала обновите runtime. Не надо лечить ошибки OpenClaw, пока `node —version` показывает неподдерживаемую версию: сообщения будут выглядеть как сбой CLI, хотя причина лежит ниже.

Установка через официальный install script

Для первого запуска на macOS, Linux или WSL2 самый короткий маршрут — официальный install script. Он определяет окружение, ставит нужные компоненты и запускает onboarding. После команды откройте новый терминал, если shell не видит `openclaw` сразу.

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw --version

Если вы хотите поставить CLI без автоматического onboarding, используйте флаг `—no-onboard`, а мастер настройки запустите позже. Это удобно для серверов, CI-подготовки или случаев, когда ключи провайдера еще не готовы.

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
openclaw onboard --install-daemon

Установка через npm, pnpm или bun

Если Node.js уже настроен, можно поставить OpenClaw как глобальный пакет. Этот путь понятнее разработчикам, которые знают, где находится global bin directory и как устроен `PATH`. Для обычного пользователя install script чаще быстрее, но npm-маршрут хорош тем, что прозрачно показывает пакет и версию.

npm install -g openclaw@latest
openclaw --version
openclaw onboard --install-daemon

Через pnpm порядок немного отличается: после глобальной установки может потребоваться одобрение build scripts. Это не ошибка OpenClaw, а защитная модель pnpm.

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

Bun подходит для глобального CLI, но для Gateway runtime официальные docs по-прежнему ориентируют на Node. Поэтому мой рабочий выбор для постоянной установки — Node 24 и обычный установщик.

Windows: PowerShell или WSL2

На Windows поддерживаются и native Windows, и WSL2. Для человека, который собирается работать с кодом, SSH, Docker, локальными проектами и shell-инструментами, WSL2 обычно дает меньше сюрпризов. Native PowerShell-маршрут подходит, если OpenClaw нужен как личный ассистент без плотной dev-среды.

iwr -useb https://openclaw.ai/install.ps1 | iex

Если установка идет в WSL2, работайте внутри Linux-дистрибутива и не смешивайте пути Windows и Linux в одном workspace без необходимости. Например, проект в `/home/user/project` будет предсказуемее для CLI, чем папка на диске `C:` с пробелами и правами Windows.

Onboarding: что делает мастер настройки

`openclaw onboard —install-daemon` — ключевой этап. Он проводит через выбор провайдера модели, настройку ключа, подготовку Gateway и установку фонового запуска. На macOS это LaunchAgent, на Linux и WSL2 — user service через systemd, на Windows — Scheduled Task или fallback через Startup folder.

openclaw onboard --install-daemon

Если вы не хотите сразу ставить daemon, можно запустить Gateway в обычном режиме и смотреть логи в терминале. Я использую такой режим для диагностики: если что-то падает, причина видна сразу, а не спрятана в системном сервисе.

openclaw gateway --port 18789 --verbose

Проверка Gateway и Control UI

После onboarding проверьте три вещи: CLI доступен, Gateway запущен, dashboard открывается. Не пропускайте `doctor`: он быстро показывает проблемы с конфигом, путями, токенами и окружением.

openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

Если браузер не открылся автоматически, напечатайте ссылку без открытия и вставьте ее вручную. Обычно локальный интерфейс живет рядом с `http://127.0.0.1:18789/`. Если Control UI просит shared secret или token, берите его только из доверенного вывода CLI или конфигурации Gateway.

openclaw dashboard --no-open

Первый тест в WebChat

WebChat нужен, чтобы отделить проблемы OpenClaw от проблем внешних мессенджеров. Откройте dashboard, перейдите в chat и отправьте короткую задачу: “Ответь одним предложением, что Gateway работает”. Если ответ пришел, базовая цепочка Gateway — agent — model работает.

Если ответа нет, смотрим не Telegram и не WhatsApp, а базу: статус Gateway, ключ провайдера, логи, сеть до API, выбранную модель и конфигурацию агента. Мой критерий готовности к каналам такой: WebChat отвечает 3 раза подряд, `openclaw doctor` не показывает критичных проблем, dashboard открывается после перезапуска терминала.

Где лежат конфигурация и рабочие файлы

OpenClaw хранит состояние в домашней директории пользователя, если вы не переопределяли пути через переменные окружения. Важные ориентиры: `~/.openclaw/`, конфигурационный файл, workspace, credentials и папки skills. Конкретные пути зависят от версии и режима установки, поэтому проверяйте их через dashboard, docs и вывод CLI.

Для переносимой настройки полезны переменные `OPENCLAW_HOME`, `OPENCLAW_STATE_DIR` и `OPENCLAW_CONFIG_PATH`. Они нужны не каждому, но на VPS, в Docker или под отдельным service user помогают не смешивать личные файлы, рабочие проекты и состояние Gateway.

OPENCLAW_HOME="$HOME/.openclaw"
OPENCLAW_STATE_DIR="$HOME/.openclaw/state"
OPENCLAW_CONFIG_PATH="$HOME/.openclaw/openclaw.json"

Типичные ошибки установки и быстрые проверки

Симптом	Чаще всего причина	Что проверить
`openclaw` не найден	Global npm bin не попал в `PATH`	`npm prefix -g`, новый терминал, shell profile
Gateway не стартует	Старый Node, занятый порт, сломанный config	`node —version`, `openclaw doctor`, порт `18789`
Dashboard просит токен	Открыта старая ссылка или сменился shared secret	`openclaw dashboard —no-open`
WebChat молчит	Нет ключа модели, сеть до API недоступна, agent не настроен	Логи Gateway и настройки провайдера
Telegram не отвечает	Сначала не проверен WebChat или не одобрен pairing	`openclaw pairing list telegram` и channel config
WhatsApp не подключается	QR-сессия не создана или слетела авторизация	`openclaw channels login —channel whatsapp`

Если `openclaw` не найден после npm-установки, официальная диагностика начинается с трех команд: Node, npm prefix и `PATH`. Часто достаточно добавить global bin directory в `~/.zshrc` или `~/.bashrc`, затем открыть новый терминал.

node -v
npm prefix -g
echo "$PATH"

Что делать после успешной установки

Дальше не надо сразу включать все возможности. Нормальный порядок такой: один внешний channel, один workspace, один набор правил, один тестовый skill. После каждого изменения запускайте проверку: WebChat отвечает, внешний канал принимает только разрешенного отправителя, `doctor` не ругается, секреты не попали в текстовые файлы.

• Telegram: создать bot token, настроить `channels.telegram`, проверить pairing или allowlist.
• WhatsApp: подключить отдельный номер через QR и настроить `dmPolicy`.
• Skills: установить один skill, прочитать `SKILL.md`, проверить `openclaw skills list`.
• Docker/VPS: переносить только после того, как локальная установка стабильно отвечает.
• Мобильные nodes: подключать после понимания pairing и Gateway URL.

Контрольный лист после установки

Перед тем как считать установку законченной, пройдите короткий контрольный лист. Он нужен не для красоты, а чтобы не переносить скрытую проблему в следующие шаги. Если в WebChat нет ответа, Telegram не надо трогать. Если dashboard открывается только по старой ссылке, сначала разберитесь с token. Если `doctor` показывает ошибку конфигурации, не ставьте skills поверх неисправного Gateway.

• `openclaw —version` показывает установленный CLI.
• `openclaw doctor` не показывает критичных ошибок.
• `openclaw gateway status` видит запущенный Gateway.
• `openclaw dashboard —no-open` печатает актуальную ссылку.
• WebChat отвечает на 3 коротких запроса подряд.
• Workspace понятен: вы знаете, где лежат инструкции и какие файлы agent может читать.
• Секреты модели не лежат в Markdown-файлах и не попали в историю shell.

Если все пункты сходятся, OpenClaw готов к следующему уровню: один внешний channel, один проверенный skill или перенос на сервер. Не делайте все три действия за один раз: после каждого шага повторяйте проверку Gateway и WebChat.

Источники для сверки

• Официальная установка OpenClaw
• Getting Started OpenClaw
• Docker-установка OpenClaw
• GitHub-репозиторий OpenClaw

Ответы на эти вопросы могут быть для вас полезными

Можно ли установить OpenClaw без Node.js?

Для обычной CLI-установки Node.js нужен. Docker-сценарий упаковывает окружение иначе, но для первого локального запуска проще идти через install script или npm.

Нужно ли сразу подключать Telegram?

Нет. Сначала dashboard и WebChat. Если WebChat не отвечает, Telegram добавит новый слой ошибок и не поможет найти причину.

Что делать, если onboarding завершился с ошибкой?

Проверьте Node, сеть, права пользователя и `openclaw doctor`. Затем запустите Gateway в foreground-режиме с verbose-логами, чтобы увидеть конкретное место падения.