2026: самое полное руководство по установке и настройке OpenClaw — пошаговый tutorial от нуля до запуска

2. Типичные проблемы

1. Ограничение: руководства обрываются на «успешно запущено». Приветственный баннер в терминале не означает, что модель подключена, файловые инструменты работают или шлюз принимает сообщения. OpenClaw действительно готов, когда пройдены зависимости и версии Node, onboard + связь с моделью, Gateway на 18789, доступ к Dashboard, границы прав, отслеживаемые логи и низкорисковый кейс.
2. Скрытые издержки: ключи и пути разбросаны. API Key только в заметках, openclaw.json5 не синхронен с .env, workspace указывает на весь домашний каталог — одна ошибка может перезаписать SSH-ключи или production-репозиторий.
3. Стабильность и аудит: непонятно, где логи. Слепая переустановка стирает подсказки в ~/.openclaw/logs/errors.log; без бэкапа нельзя откатить конфигурацию после обновления.

3. Подготовка перед установкой: чек-лист Mac и окружения

Цель: не обнаруживать проблемы сети, Git или диска посреди установки. Прохождение: все пункты ниже отмечены до запуска install.sh.

• ОС: macOS 12+ (Intel или Apple Silicon; Apple Silicon удобнее для локальной инференции, облачные модели — по документации провайдера).
• Git: официальный установщик ожидает стабильную сеть и аккаунт провайдера модели; рекомендуется git --version ≥ 2.30. Без Git: Xcode Command Line Tools или brew install git.
• Сеть: доступ к GitHub raw (скрипт установки) и API LLM-провайдера; за корпоративным прокси заранее задайте HTTPS_PROXY.
• Диск: установщик может подтянуть Python 3.11, Node v22, ripgrep, ffmpeg и репозитории — резервируйте ≥ 2 ГБ (с кэшем Skills ближе к 1,5–3 ГБ; сверьте с актуальной документацией).
• Права: личная установка без sudo; при root может использоваться /root/.openclaw вместо путей ниже.
• Бэкап: если есть ~/.openclaw, сначала cp -a ~/.openclaw ~/.openclaw.bak-$(date +%F).
• Тестовый каталог: изолированный workspace ~/openclaw-lab — не ~/Documents, production git и секретные папки.

# Быстрая предпроверка (одним блоком)
git --version
sw_vers
df -h ~
mkdir -p ~/openclaw-lab/{inbox,outbox,archive}
echo "OpenClaw lab sample: Q2 planning notes." > ~/openclaw-lab/inbox/sample.txt

При сбое: ошибки Git → CLT/Главнаяbrew; диск заполнен → освободить место; таймауты → сеть/прокси — не переустанавливайте трижды без сохранения логов.

4. Официальная установка OpenClaw

Цель: использовать поддерживаемый install.sh для Node и CLI. Источник: официальная документация по установке (перед публикацией перепроверьте флаги версий).

4.1 Рекомендуется: официальный install.sh (macOS / Linux)

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

# Только установка, onboard позже:
# curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Установщик определяет систему, при необходимости ставит Node (в документации Node 24 или Node 22.19+) и CLI OpenClaw. Типичные пути (сверьте перед публикацией):

• Конфиг пользователя: ~/.openclaw/ (openclaw.json5, secrets/, state, logs)
• Порт шлюза по умолчанию: 18789 (Control UI / WebSocket)
• Фон macOS: openclaw onboard --install-daemon регистрирует LaunchAgent

4.2 Инициализация: мастер onboard

openclaw onboard --install-daemon

# Официальная тройка проверки:
openclaw --version
openclaw doctor
openclaw gateway status

Мастер проводит через провайдера модели, API Key и настройку Gateway. Никогда не запускайте неизвестные скрипты; никогда не коммитьте ключи в git и не публикуйте скриншоты с секретами.

4.3 Запись после установки

source ~/.zshrc          # или новое окно терминала
openclaw --version         # зафиксируйте версию для диагностики
openclaw doctor            # авто-диагностика; при необходимости --fix

Прохождение: which openclaw находит команду; в openclaw doctor нет блокирующего FAIL. При сбое сначала: последние 20 строк лога установки → PATH → Node ниже минимума или npm global bin не в PATH.

Не удаляйте сразу ~/.openclaw при ошибке — сначала сохраните вывод терминала и openclaw doctor.

5. Настройка моделей и API Key

Цель: чтобы Agent OpenClaw вызывал выбранную LLM. Прохождение: неинтерактивный smoke даёт осмысленный ответ; в openclaw auth list или .env есть запись, ключ не в истории shell.

5.1 Интерактивная настройка (первый раз)

openclaw onboard        # модели, секреты, gateway (с --install-daemon)
# Ключи также через auth-profiles / env — см. официальную Authentication

5.2 Переменные окружения и конфигурационные файлы

Основной конфиг: ~/.openclaw/openclaw.json5; секреты часто в ~/.openclaw/.env (подтвердите openclaw config path и openclaw config env-path). Пример — имена переменных по вашему провайдеру; не копируйте устаревшие имена:

# Пример: OpenRouter (замените ключ; не коммитьте)
openclaw config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# Или правка .env (chmod 600 ~/.openclaw/.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.openclaw/.env

Граница: цены, квоты, региональная доступность и условия приватности меняются — перед production читайте актуальные условия. Статья не привязывает к одному имени модели.

6. Рабочая область, права и логи

Цель: после установки — отслеживаемость, ограниченность и возможность отката. Принцип: минимальные привилегии — сначала только тестовый каталог.

• Workspace: укажите сессии или openclaw.json5 на ~/openclaw-lab; добавьте AGENTS.md для границ инструментов (см. Context Files).
• Права macOS: файловые/терминальные инструменты могут запросить Full Disk Access — при первой приёмке ограничьте тестовой папкой, не всем диском.
• Логи: по умолчанию ~/.openclaw/logs/ (agent.log, errors.log, gateway.log). openclaw logs list, openclaw logs errors --since 30m.
• Гигиена секретов: chmod 600 ~/.openclaw/.env; не синхронизируйте бэкапы в облако; блокируйте доступ к ~/.ssh, платежам, production kubeconfig.
• Фон (опционально): для шлюзов Telegram/Discord — openclaw gateway setup и openclaw gateway install; долгосрочная эксплуатация — в нашем руководстве по OpenClaw Gateway 7×24.

Прохождение: после указания «читать/писать только ~/openclaw-lab» попытки вне пути отклоняются или логируются.

7. Открыть Dashboard и проверить Gateway (порт 18789)

Цель: подтвердить Control UI и WebSocket Gateway. Прохождение: http://127.0.0.1:18789 открывается; openclaw gateway status показывает прослушивание 18789.

openclaw gateway status
openclaw dashboard
# Или в браузере:
# http://127.0.0.1:18789/

# Удалённый Mac (SSH forward — не открывайте 18789 в интернет):
# ssh -L 18789:127.0.0.1:18789 user@remote-mac

# Конфликт порта:
lsof -i :18789
openclaw gateway restart
openclaw doctor --fix

При сбое сначала: порт занят → lsof; UI пустой, status OK → кэш/прокси/WebSocket; удалённо не работает → только SSH local forward. launchd: с --install-daemon после перезагрузки openclaw gateway status должен быть running; иначе логи LaunchAgent (см. статью про переменные окружения launchd).

8. Первая приёмка: runbook из 7 шагов

Эти семь шагов переводят от «настройка завершена» к «готов к работе» — выполните дословно и сохраните фрагменты логов.

1. Диагностика: openclaw doctor --fix → нет необработанного FAIL.
2. Проверка модели: openclaw agent --message "Reply with exactly: OPENCLAW_OK" → в ответе OPENCLAW_OK.
3. Чтение файла: Agent читает ~/openclaw-lab/inbox/sample.txt и цитирует первую строку.
4. Запись файла: пишет ~/openclaw-lab/outbox/ping.txt → видно через cat.
5. Логи: openclaw logs errors --since 10m → нет новых необъяснённых ERROR.
6. Новый терминал: закройте окно, откройте новое, повторите шаг 2 → PATH не только в сессии.
7. Опционально перезагрузка: повторите шаг 2 после reboot; если установлен gateway — также openclaw gateway status.

Ориентиры для приёмки (личные, не официальный SLA): ответ smoke < 60 с; 0 необъяснённых ERROR в errors.log за 10 мин; новый файл в ~/openclaw-lab/outbox.

9. Первый практический кейс: резюме + todo + откат

Сценарий: прочитать тестовый текст, сделать краткое резюме и три todo в Markdown, сохранить бэкап — покрывает установку (CLI), настройку (модель) и workflow (чтение → рассуждение → запись → логи).

# 1. Ввод (пропустите, если раздел 3 уже создал)
cat > ~/openclaw-lab/inbox/weekly-notes.txt <<'EOF'
This week: drafted OpenClaw install doc.
Follow-up: set OpenRouter budget alert; evaluate Telegram gateway next week.
Risk: never commit API Keys to git.
EOF

# 2. Интерактивная сессия
openclaw
# Пример запроса в сессии:
# "Use only ~/openclaw-lab. Read inbox/weekly-notes.txt,
#  write a summary under 150 words plus 3 todos to outbox/summary-and-todos.md,
#  and copy the source file to archive/weekly-notes.bak"

# 3. Неинтерактивная проверка
ls -la ~/openclaw-lab/outbox/summary-and-todos.md
ls -la ~/openclaw-lab/archive/
openclaw logs agent -n 30 --since 15m

Прохождение:

• summary-and-todos.md содержит резюме + 3 todo по источнику.
• archive/ есть бэкап; diff работает.
• В логах видны вызовы инструментов; в панели провайдера виден вызов (проверка стоимости).

Откат: rm ~/openclaw-lab/outbox/summary-and-todos.md && cp ~/openclaw-lab/archive/weekly-notes.bak ~/openclaw-lab/inbox/weekly-notes.txt. При сбое сначала: обрезка контекста → права на outbox → ошибки инструментов в errors.log.

10. Диагностика: послойные исправления, без слепой переустановки

Чек-лист фактов перед публикацией (для редакторов): URL install.sh, минимальный macOS, пути по умолчанию, подкоманды CLI, имена env провайдеров, пути логов — обновите документацию перед релизом. Читателям: при ошибке openclaw doctor, затем errors.log; переустановка — в последнюю очередь.

11. Следующие шаги: тестовый каталог → реальный workflow

После успешной приёмки расширяйте в таком порядке — не подключайте production-репозитории или платежи в первый день:

1. Разрешите один реальный side-project каталог; по-прежнему блокируйте ~/.ssh и глобальный *.
2. Используйте openclaw cron для ежедневных задач с низким риском (например, инвентаризация папки загрузок — всё ещё в границах).
3. Добавьте один messaging-шлюз (Telegram/Discord) с pairing против посторонних (официальная Security).
4. Еженедельно openclaw backup --quick, затем отработайте upgrade/rollback по maintenance-документации.