Варианты развёртывания

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

Прочитав этот урок, вы сможете:

Выбрать наиболее подходящий способ развёртывания в зависимости от потребностей (локально, Docker, Nix, облачные сервисы)
Установить и запустить Clawdbot в локальной среде
Развернуть Gateway с использованием контейнеризации Docker
Управлять Clawdbot декларативно через Nix
Развернуть Gateway на Fly.io, Hetzner VPS или exe.dev
Настроить удалённый доступ и применить лучшие практики безопасности

Ваша текущая ситуация

Вы хотите использовать Clawdbot, но не уверены, какой способ развёртывания выбрать:

Локальная установка — самая простая, но при выключении компьютера перестаёт работать
Хотите запустить в облаке 24/7, но не знаете, какой облачный сервис подходит
Боитесь ошибок в конфигурации, ищете самый надёжный вариант развёртывания
Нужен доступ к одному Gateway с нескольких устройств, но не знаете, как это реализовать

Когда использовать этот подход

Способ развёртывания	Сценарии применения
Локальная установка	Персональный компьютер, разработка и тестирование, быстрое начало работы
Docker	Изолированная среда, развёртывание на сервере, быстрое пересоздание
Nix	Воспроизводимое развёртывание, использование NixOS/Home Manager, необходимость отката версий
Fly.io	Работа в облаке 24/7, автоматический HTTPS, упрощённая эксплуатация
Hetzner VPS	Собственный VPS, полный контроль, низкая стоимость 24/7
exe.dev	Недорогой Linux-хостинг, не требует самостоятельной настройки VPS

🎒 Подготовка к началу

Перед началом убедитесь:

Требования к окружению

Node.js ≥ 22 (обязательно для локальной установки)
Docker Desktop + Docker Compose v2 (обязательно для развёртывания Docker)
Nix flakes + Home Manager (обязательно для развёртывания Nix)
SSH-клиент (обязательно для доступа к облачному развёртыванию)
Базовые навыки работы с терминалом (копирование, вставка, выполнение команд)

Рекомендуемые инструменты

Если вы впервые знакомитесь с Clawdbot, рекомендуется начать с Быстрого старта
Использование AI-ассистента (например, Claude, Cursor) может ускорить процесс настройки
Сохраните ваши API-ключи (Anthropic, OpenAI и др.) и учётные данные каналов

Сравнение способов развёртывания

Локальная установка

Подходит для: персональный компьютер, разработка и тестирование, быстрое начало работы

Преимущества:

✅ Самый простой и прямой способ, не требует дополнительной инфраструктуры
✅ Быстрый запуск, удобная отладка
✅ Изменения конфигурации вступают в силу немедленно

Недостатки:

❌ Не работает при выключении компьютера
❌ Не подходит для сервиса 24/7
❌ Синхронизация между устройствами требует дополнительной настройки

Развёртывание Docker

Подходит для: развёртывание на сервере, изолированная среда, CI/CD

Преимущества:

✅ Изоляция окружения, лёгкая очистка и пересоздание
✅ Единообразное развёртывание на разных платформах
✅ Поддержка изолированного выполнения инструментов в песочнице
✅ Конфигурация может быть под контролем версий

Недостатки:

❌ Требуются знания Docker
❌ Первоначальная настройка немного сложнее

Развёртывание Nix

Подходит для: пользователи NixOS, пользователи Home Manager, необходимость воспроизводимого развёртывания

Преимущества:

✅ Декларативная конфигурация, воспроизводимость
✅ Быстрый откат (home-manager switch --rollback)
✅ Все версии компонентов зафиксированы
✅ Полное управление Gateway + приложение macOS + инструменты

Недостатки:

❌ Крутая кривая обучения
❌ Требуется знакомство с экосистемой Nix

Облачное развёртывание (Fly.io / Hetzner / exe.dev)

Подходит для: работа 24/7 онлайн, удалённый доступ, командная работа

Преимущества:

✅ Работа 24/7 онлайн, не зависит от локального компьютера
✅ Автоматический HTTPS, не требуется ручная настройка сертификатов
✅ Быстрое масштабирование
✅ Поддержка удалённого доступа с нескольких устройств

Недостатки:

❌ Требуется оплата облачных сервисов
❌ Требуются базовые знания эксплуатации
❌ Данные хранятся у третьей стороны

Локальная установка

Глобальная установка npm/pnpm/bun (рекомендуется)

Самый простой способ — установка из официального репозитория npm:

npmpnpmbun

bash

# Установка с помощью npm
npm install -g clawdbot@latest

bash

# Установка с помощью pnpm (рекомендуется)
pnpm add -g clawdbot@latest

bash

# Установка с помощью bun (самый быстрый)
bun add -g clawdbot@latest

После завершения установки запустите мастер настройки:

bash

clawdbot onboard --install-daemon

Эта команда:

Проведёт вас через настройку Gateway, каналов и моделей
Установит демон Gateway (macOS launchd / Linux systemd)
Создаст файл конфигурации по умолчанию ~/.clawdbot/clawdbot.json

Сборка из исходного кода

Если вам нужна сборка из исходного кода (разработка, кастомизация):

macOS/LinuxWindows (WSL2)

bash

# Клонирование репозитория
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

# Установка зависимостей и сборка
pnpm install
pnpm ui:build
pnpm build

# Установка и запуск
pnpm clawdbot onboard --install-daemon

bash

# Сборка в WSL2 (рекомендуется)
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

wsl.exe -d Ubuntu bash -c "pnpm install && pnpm ui:build && pnpm build"

Цикл разработки

Запустите pnpm gateway:watch для автоматической перезагрузки Gateway при изменении кода.

Развёртывание Docker

Быстрый старт (рекомендуется)

Используйте предоставленный скрипт для развёртывания одной командой:

bash

./docker-setup.sh

Этот скрипт:

Соберёт образ Gateway
Запустит мастер настройки (onboarding)
Выведет подсказки по настройке провайдеров
Запустит Gateway через Docker Compose
Сгенерирует токен Gateway и запишет его в .env

После завершения:

Откройте в браузере http://127.0.0.1:18789/
Вставьте токен в настройках Control UI

Скрипт создаст на хосте:

~/.clawdbot/ (директория конфигурации)
~/clawd (директория рабочей области)

Ручной процесс

Если требуется кастомизация конфигурации Docker Compose:

bash

# Сборка образа
docker build -t clawdbot:local -f Dockerfile .

# Запуск CLI-контейнера для завершения настройки
docker compose run --rm clawdbot-cli onboard

# Запуск Gateway
docker compose up -d clawdbot-gateway

Дополнительные монтирования (опционально)

Если вы хотите смонтировать дополнительные директории хоста в контейнер, установите переменную окружения перед запуском docker-setup.sh:

bash

export CLAWDBOT_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

Примечания:

Пути должны быть разрешены в Docker Desktop (macOS/Windows)
При изменении CLAWDBOT_EXTRA_MOUNTS необходимо перезапустить docker-setup.sh для регенерации compose-файла

Персистентность домашней директории контейнера (опционально)

Если вы хотите сохранить /home/node при пересоздании контейнера:

bash

export CLAWDBOT_HOME_VOLUME="clawdbot_home"
./docker-setup.sh

Примечания:

Именованный том сохраняется до удаления через docker volume rm
Можно комбинировать с CLAWDBOT_EXTRA_MOUNTS

Установка дополнительных системных пакетов (опционально)

Если требуется установить дополнительные системные пакеты в образ (например, инструменты сборки, медиабиблиотеки):

bash

export CLAWDBOT_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

Настройка каналов (опционально)

Используйте CLI-контейнер для настройки каналов:

WhatsAppTelegramDiscord

bash

# Вход в WhatsApp (отобразится QR-код)
docker compose run --rm clawdbot-cli channels login

bash

# Добавление Telegram-бота
docker compose run --rm clawdbot-cli channels add --channel telegram --token "<token>"

bash

# Добавление Discord-бота
docker compose run --rm clawdbot-cli channels add --channel discord --token "<token>"

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

bash

docker compose exec clawdbot-gateway node dist/index.js health --token "$CLAWDBOT_GATEWAY_TOKEN"

Agent Sandbox (Gateway на хосте + инструменты Docker)

Docker также может использоваться для изолированного выполнения инструментов в песочнице для сессий, отличных от main. Подробнее: Sandboxing

Установка Nix

Рекомендуемый способ: использование модуля Home Manager nix-clawdbot

Быстрый старт

Вставьте этот текст в ваш AI-ассистент (Claude, Cursor и др.):

text

I want to set up nix-clawdbot on my Mac.
Repository: github:clawdbot/nix-clawdbot

What I need you to do:
1. Check if Determinate Nix is installed (if not, install it)
2. Create a local flake at ~/code/clawdbot-local using templates/agent-first/flake.nix
3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
5. Fill in the template placeholders and run home-manager switch
6. Verify: launchd running, bot responds to messages

Reference nix-clawdbot README for module options.

📦 Полное руководство: github.com/clawdbot/nix-clawdbot

Поведение в режиме Nix

При установке CLAWDBOT_NIX_MODE=1 (nix-clawdbot устанавливает автоматически):

Конфигурация становится детерминированной, автоматическая установка отключается
При отсутствии зависимостей отображаются специфичные для Nix инструкции по исправлению
В UI отображается баннер режима Nix (только для чтения)

На macOS GUI-приложения не наследуют автоматически переменные окружения shell. Вы также можете включить режим Nix через defaults:

bash

defaults write com.clawdbot.mac clawdbot.nixMode -bool true

Пути конфигурации и состояния

В режиме Nix явно устанавливаются эти переменные окружения:

CLAWDBOT_STATE_DIR (по умолчанию: ~/.clawdbot)
CLAWDBOT_CONFIG_PATH (по умолчанию: $CLAWDBOT_STATE_DIR/clawdbot.json)

Таким образом, состояние и конфигурация во время выполнения остаются вне неизменяемого хранилища, управляемого Nix.

Облачное развёртывание Fly.io

Подходит для: необходимость работы в облаке 24/7, упрощённая эксплуатация, автоматический HTTPS

Что вам понадобится

flyctl CLI
Учётная запись Fly.io (доступен бесплатный уровень)
Аутентификация модели: Anthropic API Key (или ключи других провайдеров)
Учётные данные каналов: Discord bot token, Telegram token и т.д.

Шаг 1: Создание приложения Fly

bash

# Клонирование репозитория
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

# Создание нового приложения Fly (выберите своё имя)
fly apps create my-clawdbot

# Создание персистентного тома (обычно достаточно 1GB)
fly volumes create clawdbot_data --size 1 --region iad

Выбор региона

Выберите ближайший к вам регион. Распространённые варианты:

lhr (Лондон)
iad (Виргиния)
sjc (Сан-Хосе)

Шаг 2: Настройка fly.toml

Отредактируйте fly.toml в соответствии с именем вашего приложения и требованиями.

Примечание по безопасности

Конфигурация по умолчанию открывает публичный URL. Для защищённого развёртывания без публичного IP см. Приватное развёртывание или используйте fly.private.toml.

toml

app = "my-clawdbot"  # Имя вашего приложения
primary_region = "iad"

[build]
  dockerfile = "Dockerfile"

[env]
  NODE_ENV = "production"
  CLAWDBOT_PREFER_PNPM = "1"
  CLAWDBOT_STATE_DIR = "/data"
  NODE_OPTIONS = "--max-old-space-size=1536"

[processes]
  app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = false
  auto_start_machines = true
  min_machines_running = 1
  processes = ["app"]

[[vm]]
  size = "shared-cpu-2x"
  memory = "2048mb"

[mounts]
  source = "clawdbot_data"
  destination = "/data"

Пояснение ключевых настроек:

Настройка	Причина
`--bind lan`	Привязка к `0.0.0.0`, чтобы прокси Fly мог получить доступ к Gateway
`--allow-unconfigured`	Запуск без файла конфигурации (вы создадите его позже)
`internal_port = 3000`	Должен соответствовать `--port 3000` (или `CLAWDBOT_GATEWAY_PORT`) для проверки работоспособности Fly
`memory = "2048mb"`	512MB слишком мало; рекомендуется 2GB
`CLAWDBOT_STATE_DIR = "/data"`	Сохранение состояния на томе

Шаг 3: Установка секретов

bash

# Обязательно: токен Gateway (для привязки не к loopback)
fly secrets set CLAWDBOT_GATEWAY_TOKEN=$(openssl rand -hex 32)

# API-ключи провайдеров моделей
fly secrets set ANTHROPIC_API_KEY=sk-ant-...
fly secrets set OPENAI_API_KEY=sk-...
fly secrets set GOOGLE_API_KEY=...

# Токены каналов
fly secrets set DISCORD_BOT_TOKEN=MTQ...

Рекомендации по безопасности

Привязка не к loopback (--bind lan) требует CLAWDBOT_GATEWAY_TOKEN для обеспечения безопасности. Относитесь к этим токенам как к паролям. Для всех API-ключей и токенов предпочитайте переменные окружения вместо файлов конфигурации, чтобы предотвратить раскрытие учётных данных в clawdbot.json.

Шаг 4: Развёртывание

bash

fly deploy

Первое развёртывание соберёт Docker-образ (около 2-3 минут). Последующие развёртывания будут быстрее.

После развёртывания проверьте:

bash

fly status
fly logs

Вы должны увидеть:

[gateway] listening on ws://0.0.0.0:3000 (PID xxx)
[discord] logged in to discord as xxx

Шаг 5: Создание файла конфигурации

Подключитесь по SSH к машине для создания файла конфигурации:

bash

fly ssh console

Создайте директорию конфигурации и файл:

bash

mkdir -p /data
cat > /data/clawdbot.json << 'EOF'
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallbacks": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o"]
      },
      "maxConcurrent": 4
    },
    "list": [
      {
        "id": "main",
        "default": true
      }
    ]
  },
  "auth": {
    "profiles": {
      "anthropic:default": { "mode": "token", "provider": "anthropic" },
      "openai:default": { "mode": "token", "provider": "openai" }
    }
  },
  "bindings": [
    {
      "agentId": "main",
      "match": { "channel": "discord" }
    }
  ],
  "channels": {
    "discord": {
      "enabled": true,
      "groupPolicy": "allowlist",
      "guilds": {
        "YOUR_GUILD_ID": {
          "channels": { "general": { "allow": true } },
          "requireMention": false
        }
      }
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "auto"
  },
  "meta": {
    "lastTouchedVersion": "2026.1.25"
  }
}
EOF

Перезапустите для применения конфигурации:

bash

exit
fly machine restart <machine-id>

Шаг 6: Доступ к Gateway

Control UI:

bash

fly open

Или перейдите по адресу: https://my-clawdbot.fly.dev/

Вставьте ваш токен Gateway (из CLAWDBOT_GATEWAY_TOKEN) для аутентификации.

Логи:

bash

fly logs              # Логи в реальном времени
fly logs --no-tail    # Последние логи

SSH-консоль:

bash

fly ssh console

Устранение неполадок

"App is not listening on expected address":

Gateway привязывается к 127.0.0.1 вместо 0.0.0.0.

Исправление: Добавьте --bind lan в команду процесса в fly.toml.

Проверка работоспособности не прошла / Соединение отклонено:

Fly не может получить доступ к Gateway на настроенном порту.

Исправление: Убедитесь, что internal_port соответствует порту Gateway (установите --port 3000 или CLAWDBOT_GATEWAY_PORT=3000).

OOM / Проблемы с памятью:

Контейнер постоянно перезапускается или завершается. Признаки: SIGABRT, v8::internal::Runtime_AllocateInYoungGeneration или тихие перезапуски.

Исправление: Увеличьте память в fly.toml:

toml

[[vm]]
  memory = "2048mb"

Или обновите существующую машину:

bash

fly machine update <machine-id> --vm-memory 2048 -y

Примечание: 512MB слишком мало. 1GB может работать, но при нагрузке или подробных логах возможен OOM. Рекомендуется 2GB.

Проблема с блокировкой Gateway:

Gateway отказывается запускаться с ошибкой "already running".

Это происходит при перезапуске контейнера, когда файл блокировки PID сохраняется на томе.

Исправление: Удалите файл блокировки:

bash

fly ssh console --command "rm -f /data/gateway.*.lock"
fly machine restart <machine-id>

Файлы блокировки находятся в /data/gateway.*.lock (не в поддиректориях).

Приватное развёртывание (защита)

По умолчанию Fly.io назначает публичный IP, делая ваш Gateway доступным по адресу https://your-app.fly.dev. Это удобно, но также означает, что ваше развёртывание может быть обнаружено интернет-сканерами (Shodan, Censys и т.д.).

Используйте приватный шаблон для защищённого развёртывания без публичного доступа:

Сценарии приватного развёртывания

Вы выполняете только исходящие вызовы/сообщения (без входящих webhooks)
Вы используете туннели ngrok или Tailscale для любых обратных вызовов webhook
Вы получаете доступ к Gateway через SSH, прокси или WireGuard, а не через браузер
Вы хотите скрыть развёртывание от интернет-сканеров

Настройка:

Используйте fly.private.toml вместо стандартной конфигурации:

bash

# Развёртывание с приватной конфигурацией
fly deploy -c fly.private.toml

Или преобразуйте существующее развёртывание:

bash

# Список текущих IP
fly ips list -a my-clawdbot

# Освобождение публичных IP
fly ips release <public-ipv4> -a my-clawdbot
fly ips release <public-ipv6> -a my-clawdbot

# Переключение на приватную конфигурацию, чтобы будущие развёртывания не переназначали публичные IP
fly deploy -c fly.private.toml

# Выделение только приватного IPv6
fly ips allocate-v6 --private -a my-clawdbot

Доступ к приватному развёртыванию:

Поскольку нет публичного URL, используйте один из следующих методов:

Вариант 1: Локальный прокси (самый простой)

bash

# Перенаправление локального порта 3000 на приложение
fly proxy 3000:3000 -a my-clawdbot

# Затем откройте в браузере http://localhost:3000

Вариант 2: WireGuard VPN

bash

# Создание конфигурации WireGuard (однократно)
fly wireguard create

# Импорт в клиент WireGuard, затем доступ через внутренний IPv6
# Пример: http://[fdaa:x:x:x:x::x]:3000

Вариант 3: Только SSH

bash

fly ssh console -a my-clawdbot

Стоимость

При использовании рекомендуемой конфигурации (shared-cpu-2x, 2GB RAM):

Примерно $10-15/месяц в зависимости от использования
Бесплатный уровень включает некоторую квоту

Подробнее: Цены Fly.io

Развёртывание Hetzner VPS

Подходит для: собственный VPS, полный контроль, низкая стоимость работы 24/7

Цель

Запустить персистентный Clawdbot Gateway на Hetzner VPS с использованием Docker, с сохранением состояния, встроенными бинарными файлами и безопасным поведением при перезапуске.

Если вы хотите "Clawdbot 24/7 примерно за $5/месяц", это самая простая и надёжная настройка.

Что вам понадобится

Hetzner VPS с root-доступом
SSH-доступ с вашего ноутбука
Базовые навыки SSH + копирования/вставки
Примерно 20 минут
Docker и Docker Compose
Учётные данные аутентификации модели
Опциональные учётные данные провайдеров (WhatsApp QR, Telegram bot token, Gmail OAuth)

Шаг 1: Настройка VPS

Создайте Ubuntu или Debian VPS в Hetzner.

Подключитесь как root:

bash

ssh root@YOUR_VPS_IP

Это руководство предполагает, что VPS имеет состояние. Не рассматривайте его как одноразовую инфраструктуру.

Шаг 2: Установка Docker на VPS

bash

apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh

Проверка:

bash

docker --version
docker compose version

Шаг 3: Клонирование репозитория Clawdbot

bash

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

Это руководство предполагает, что вы будете собирать кастомный образ для обеспечения персистентности бинарных файлов.

Шаг 4: Создание персистентных директорий хоста

Docker-контейнеры эфемерны. Всё долгосрочное состояние должно находиться на хосте.

bash

mkdir -p /root/.clawdbot
mkdir -p /root/clawd

# Установка владельца для пользователя контейнера (uid 1000):
chown -R 1000:1000 /root/.clawdbot
chown -R 1000:1000 /root/clawd

Шаг 5: Настройка переменных окружения

Создайте .env в корне репозитория.

bash

CLAWDBOT_IMAGE=clawdbot:latest
CLAWDBOT_GATEWAY_TOKEN=change-me-now
CLAWDBOT_GATEWAY_BIND=lan
CLAWDBOT_GATEWAY_PORT=18789
CLAWDBOT_CONFIG_DIR=/root/.clawdbot
CLAWDBOT_WORKSPACE_DIR=/root/clawd
GOG_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.clawdbot

Генерация надёжных секретов:

bash

openssl rand -hex 32

Не коммитьте этот файл

Добавьте .env в .gitignore.

Шаг 6: Конфигурация Docker Compose

Создайте или обновите docker-compose.yml.

yaml

services:
  clawdbot-gateway:
    image: ${CLAWDBOT_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - CLAWDBOT_GATEWAY_BIND=${CLAWDBOT_GATEWAY_BIND}
      - CLAWDBOT_GATEWAY_PORT=${CLAWDBOT_GATEWAY_PORT}
      - CLAWDBOT_GATEWAY_TOKEN=${CLAWDBOT_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${CLAWDBOT_CONFIG_DIR}:/home/node/.clawdbot
      - ${CLAWDBOT_WORKSPACE_DIR}:/home/node/clawd
    ports:
      # Рекомендуется: держать Gateway только на loopback на VPS; доступ через SSH-туннель.
      # Для публичного доступа удалите префикс `127.0.0.1:` и настройте файрвол соответственно.
      - "127.0.0.1:${CLAWDBOT_GATEWAY_PORT}:18789"
      # Опционально: только если вы запускаете iOS/Android-узлы против этого VPS и нужен Canvas-хост.
      # Если вы публично открываете этот порт, прочитайте /gateway/security и настройте файрвол соответственно.
      # - "18793:18793"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${CLAWDBOT_GATEWAY_BIND}",
        "--port",
        "${CLAWDBOT_GATEWAY_PORT}"
      ]

Шаг 7: Встраивание необходимых бинарных файлов в образ (критично)

Установка бинарных файлов в работающем контейнере — это ловушка. Всё, что установлено во время выполнения, теряется при перезапуске.

Все внешние бинарные файлы, необходимые для навыков, должны быть установлены во время сборки образа.

Следующий пример показывает только три распространённых бинарных файла:

gog для доступа к Gmail
goplaces для Google Places
wacli для WhatsApp

Это примеры, а не полный список. Вы можете установить столько бинарных файлов, сколько нужно, используя тот же паттерн.

Если вы позже добавите новые навыки, зависящие от дополнительных бинарных файлов, вы должны:

Обновить Dockerfile
Пересобрать образ
Перезапустить контейнер

Пример Dockerfile:

dockerfile

FROM node:22-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

# Пример бинарного файла 1: Gmail CLI
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin

# Пример бинарного файла 2: Google Places CLI
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin

# Пример бинарного файла 3: WhatsApp CLI
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin

# Добавьте больше бинарных файлов ниже, используя тот же паттерн

WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN corepack enable
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

Шаг 8: Сборка и запуск

bash

docker compose build
docker compose up -d clawdbot-gateway

Проверка бинарных файлов:

bash

docker compose exec clawdbot-gateway which gog
docker compose exec clawdbot-gateway which goplaces
docker compose exec clawdbot-gateway which wacli

Ожидаемый вывод:

/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli

Шаг 9: Проверка Gateway

bash

docker compose logs -f clawdbot-gateway

Успех:

[gateway] listening on ws://0.0.0.0:18789

С вашего ноутбука:

bash

ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP

Откройте:

http://127.0.0.1:18789/

Вставьте ваш токен Gateway.

Расположение персистентного состояния (источник истины)

Clawdbot работает в Docker, но Docker не является источником истины.

Всё долгосрочное состояние должно сохраняться при перезапусках, пересборках и перезагрузках.

Компонент	Расположение	Механизм персистентности	Примечания
Gateway config	`/home/node/.clawdbot/`	Монтирование тома хоста	Включает `clawdbot.json`, токены
Model auth profiles	`/home/node/.clawdbot/`	Монтирование тома хоста	OAuth-токены, API-ключи
Skill configs	`/home/node/.clawdbot/skills/`	Монтирование тома хоста	Состояние уровня навыков
Agent workspace	`/home/node/clawd/`	Монтирование тома хоста	Код и артефакты агента
WhatsApp session	`/home/node/.clawdbot/`	Монтирование тома хоста	Сохраняет QR-вход
Gmail keyring	`/home/node/.clawdbot/`	Том хоста + пароль	Требуется `GOG_KEYRING_PASSWORD`
External binaries	`/usr/local/bin/`	Docker-образ	Должны быть встроены при сборке
Node runtime	Файловая система контейнера	Docker-образ	Пересобирается при каждой сборке образа
OS packages	Файловая система контейнера	Docker-образ	Не устанавливайте во время выполнения
Docker container	Эфемерный	Можно перезапустить	Безопасно уничтожить

Развёртывание exe.dev

Подходит для: недорогой Linux-хостинг, удалённый доступ, не требует самостоятельной настройки VPS

Цель

Запустить Clawdbot Gateway на VM exe.dev с доступом с вашего ноутбука через:

HTTPS-прокси exe.dev (просто, без туннелирования)
SSH-туннель (наиболее безопасно; только loopback Gateway)

Это руководство предполагает Ubuntu/Debian. Если вы выбрали другой дистрибутив, адаптируйте пакеты соответственно. Если вы используете любой другой Linux VPS, те же шаги применимы — вы просто не будете использовать команды прокси exe.dev.

Что вам понадобится

Учётная запись exe.dev + возможность запустить ssh exe.dev на вашем ноутбуке
Настроенные SSH-ключи (ваш ноутбук → exe.dev)
Аутентификация модели, которую вы будете использовать (OAuth или API-ключ)
Опциональные учётные данные провайдеров (WhatsApp QR-сканирование, Telegram bot token, Discord bot token и т.д.)

Шаг 1: Создание VM

С вашего ноутбука:

bash

ssh exe.dev new --name=clawdbot

Затем подключитесь:

bash

ssh clawdbot.exe.xyz

Сохраняйте состояние VM

Держите эту VM с состоянием. Clawdbot хранит состояние в ~/.clawdbot/ и ~/clawd/.

Шаг 2: Установка предварительных требований на VM

bash

sudo apt-get update
sudo apt-get install -y git curl jq ca-certificates openssl

Node 22

Установите Node ≥ 22.12 (любым способом). Быстрая проверка:

bash

node -v

Если на VM ещё нет Node 22, используйте ваш предпочитаемый менеджер Node или источник пакетов дистрибутива, предоставляющий Node 22+.

Шаг 3: Установка Clawdbot

На сервере рекомендуется глобальная установка через npm:

bash

npm i -g clawdbot@latest
clawdbot --version

Если установка нативных зависимостей не удалась (редко; обычно sharp), добавьте инструменты сборки:

bash

sudo apt-get install -y build-essential python3

Шаг 4: Первоначальная настройка (мастер)

Запустите мастер настройки на VM:

bash

clawdbot onboard --install-daemon

Он может настроить:

Инициализацию рабочей области ~/clawd
Конфигурацию ~/.clawdbot/clawdbot.json
Профили аутентификации модели
Настройку/вход провайдера модели
Сервис systemd user для Linux

Если вы выполняете OAuth на безголовой VM, сначала выполните OAuth на обычной машине, затем скопируйте профиль аутентификации на VM (см. Справку).

Шаг 5: Варианты удалённого доступа

Вариант A (рекомендуется): SSH-туннель (только loopback)

Держите Gateway на loopback (по умолчанию) и туннелируйте его с вашего ноутбука:

bash

ssh -N -L 18789:127.0.0.1:18789 clawdbot.exe.xyz

Откройте локально:

http://127.0.0.1:18789/ (Control UI)

Подробнее: Удалённый доступ

Вариант B: HTTPS-прокси exe.dev (без туннелирования)

Чтобы exe.dev проксировал трафик на VM, привяжите Gateway к LAN-интерфейсу и установите токен:

bash

export CLAWDBOT_GATEWAY_TOKEN="$(openssl rand -hex 32)"
clawdbot gateway --bind lan --port 8080 --token "$CLAWDBOT_GATEWAY_TOKEN"

Для работы в качестве сервиса сохраните это в ~/.clawdbot/clawdbot.json:

json5

{
  "gateway": {
    "mode": "local",
    "port": 8080,
    "bind": "lan",
    "auth": { "mode": "token", "token": "YOUR_TOKEN" }
  }
}

Важное примечание

Привязка не к loopback требует gateway.auth.token (или CLAWDBOT_GATEWAY_TOKEN). gateway.remote.token используется только для удалённых CLI-вызовов; он не включает локальную аутентификацию.

Затем на exe.dev направьте прокси на выбранный вами порт (в этом примере 8080, или любой выбранный вами порт) и откройте HTTPS URL вашей VM:

bash

ssh exe.dev share port clawdbot 8080

Откройте:

https://clawdbot.exe.xyz/

В Control UI вставьте токен (UI → Настройки → токен). UI отправляет его как connect.params.auth.token.

Порт прокси

Если прокси ожидает порт приложения, предпочитайте нестандартный порт (например, 8080). Относитесь к токену как к паролю.

Шаг 6: Поддержание работы (сервис)

На Linux Clawdbot использует сервис systemd user. После --install-daemon проверьте:

bash

systemctl --user status clawdbot-gateway[-<profile>].service

Если сервис умирает после выхода из системы, включите lingering:

bash

sudo loginctl enable-linger "$USER"

Шаг 7: Обновление

bash

npm i -g clawdbot@latest
clawdbot doctor
clawdbot gateway restart
clawdbot health

Подробнее: Обновление

Сценарий	Рекомендуемое развёртывание	Причина
Личное использование, быстрое начало	Локальная установка	Самое простое, не требует инфраструктуры
Доступ с нескольких устройств, периодическое отключение	Fly.io	Работа 24/7 онлайн, доступ из любого места
Полный контроль, собственная инфраструктура	Hetzner VPS	Полный контроль, персистентное состояние, низкая стоимость
Низкая стоимость, не хочется управлять VPS	exe.dev	Недорогой хостинг, быстрая настройка
Необходимость воспроизводимости, быстрый откат	Nix	Декларативная конфигурация, фиксация версий
Тестирование, изолированная среда	Docker	Лёгкое пересоздание, изоляция тестов

Контрольная точка ✅

Проверка локальной установки:

bash

clawdbot --version
clawdbot health

Вы должны увидеть сообщение о том, что Gateway прослушивает.

Проверка Docker:

bash

docker compose ps
docker compose logs clawdbot-gateway

Состояние контейнера должно быть Up, логи должны показывать [gateway] listening on ws://....

Проверка Nix:

bash

# Проверка состояния сервиса
systemctl --user status clawdbot-gateway

# Проверка режима Nix
defaults read com.clawdbot.mac clawdbot.nixMode

Проверка облачного развёртывания:

bash

# Fly.io
fly status
fly logs

# Hetzner / exe.dev
ssh root@YOUR_VPS_IP "docker compose logs -f clawdbot-gateway"

Вы должны иметь возможность получить доступ к Control UI через браузер или через SSH-туннель.

Предупреждения о подводных камнях

Распространённые проблемы Docker

Неправильные пути монтирования: Убедитесь, что пути хоста разрешены в Docker Desktop
Конфликт портов: Проверьте, не занят ли порт 18789
Проблемы с правами: Пользователь контейнера (uid 1000) нуждается в правах чтения/записи на смонтированные тома

Проблемы облачного развёртывания

Ошибки OOM: Увеличьте выделение памяти (минимум 2GB)
Блокировка Gateway: Удалите файлы /data/gateway.*.lock и перезапустите контейнер
Сбой проверки работоспособности: Убедитесь, что internal_port соответствует порту Gateway

Персистентность бинарных файлов (Hetzner)

Не устанавливайте зависимости во время выполнения! Все бинарные файлы, необходимые для навыков, должны быть встроены в Docker-образ, иначе они будут потеряны после перезапуска контейнера.

Резюме урока

В этом уроке представлены различные способы развёртывания Clawdbot:

Локальная установка: Самый простой и быстрый, подходит для личного использования и разработки
Развёртывание Docker: Изолированная среда, лёгкое пересоздание, поддержка песочницы
Развёртывание Nix: Декларативная конфигурация, воспроизводимость, быстрый откат
Fly.io: Облачная платформа, автоматический HTTPS, работа 24/7 онлайн
Hetzner VPS: Собственный VPS, полный контроль, персистентное состояние
exe.dev: Недорогой хостинг, быстрая настройка, упрощённая эксплуатация

При выборе способа развёртывания учитывайте ваш сценарий использования, технические навыки и требования к эксплуатации. Обеспечение персистентности состояния и безопасной конфигурации — ключ к успешному развёртыванию.

Приложение: Справочник по исходному коду

Нажмите, чтобы развернуть расположение исходного кода

Дата обновления: 2026-01-27

Функция/Раздел	Путь к файлу	Строки
Скрипт развёртывания Docker	`docker-setup.sh`	Весь файл
Определение Docker-образа	`Dockerfile`	Весь файл
Конфигурация Docker Compose	`docker-compose.yml`	Весь файл
Конфигурация Fly.io	`fly.toml`	Весь файл
Приватная конфигурация Fly	`fly.private.toml`	Весь файл
Docker-образ песочницы	`Dockerfile.sandbox`	Весь файл
Интеграция Nix	`nix-clawdbot`	README
Скрипт установки	`scripts/package-mac-app.sh`	Весь файл

Ключевые файлы конфигурации:

~/.clawdbot/clawdbot.json: Основной файл конфигурации
~/.clawdbot/: Директория состояния (сессии, токены, профили аутентификации)
~/clawd/: Директория рабочей области

Ключевые переменные окружения:

CLAWDBOT_GATEWAY_TOKEN: Токен аутентификации Gateway
CLAWDBOT_STATE_DIR: Путь к директории состояния
CLAWDBOT_CONFIG_PATH: Путь к файлу конфигурации
CLAWDBOT_NIX_MODE: Включение режима Nix

Ключевые скрипты:

scripts/sandbox-setup.sh: Сборка образа песочницы по умолчанию
scripts/sandbox-common-setup.sh: Сборка общего образа песочницы
scripts/sandbox-browser-setup.sh: Сборка образа песочницы браузера

Переменные окружения Docker (.env):

CLAWDBOT_IMAGE: Имя используемого образа
CLAWDBOT_GATEWAY_BIND: Режим привязки (lan/auto)
CLAWDBOT_GATEWAY_PORT: Порт Gateway
CLAWDBOT_CONFIG_DIR: Монтирование директории конфигурации
CLAWDBOT_WORKSPACE_DIR: Монтирование рабочей области
GOG_KEYRING_PASSWORD: Пароль связки ключей Gmail
XDG_CONFIG_HOME: Директория конфигурации XDG

Переменные окружения Fly.io:

NODE_ENV: Среда выполнения (production)
CLAWDBOT_PREFER_PNPM: Использование pnpm
CLAWDBOT_STATE_DIR: Директория персистентного состояния
NODE_OPTIONS: Параметры среды выполнения Node.js

Варианты развёртывания ​

Что вы сможете делать после изучения ​

Ваша текущая ситуация ​

Когда использовать этот подход ​

🎒 Подготовка к началу ​

Сравнение способов развёртывания ​

Локальная установка ​

Развёртывание Docker ​

Развёртывание Nix ​

Облачное развёртывание (Fly.io / Hetzner / exe.dev) ​

Локальная установка ​

Глобальная установка npm/pnpm/bun (рекомендуется) ​

Сборка из исходного кода ​

Развёртывание Docker ​

Быстрый старт (рекомендуется) ​

Ручной процесс ​

Дополнительные монтирования (опционально) ​

Персистентность домашней директории контейнера (опционально) ​

Установка дополнительных системных пакетов (опционально) ​

Настройка каналов (опционально) ​

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

Agent Sandbox (Gateway на хосте + инструменты Docker) ​

Установка Nix ​

Быстрый старт ​

Поведение в режиме Nix ​

Пути конфигурации и состояния ​

Облачное развёртывание Fly.io ​

Что вам понадобится ​

Шаг 1: Создание приложения Fly ​

Шаг 2: Настройка fly.toml ​

Шаг 3: Установка секретов ​

Шаг 4: Развёртывание ​

Шаг 5: Создание файла конфигурации ​

Шаг 6: Доступ к Gateway ​

Устранение неполадок ​

Приватное развёртывание (защита) ​

Стоимость ​

Развёртывание Hetzner VPS ​

Цель ​

Что вам понадобится ​

Шаг 1: Настройка VPS ​

Шаг 2: Установка Docker на VPS ​

Шаг 3: Клонирование репозитория Clawdbot ​

Шаг 4: Создание персистентных директорий хоста ​

Шаг 5: Настройка переменных окружения ​

Шаг 6: Конфигурация Docker Compose ​

Шаг 7: Встраивание необходимых бинарных файлов в образ (критично) ​

Шаг 8: Сборка и запуск ​

Шаг 9: Проверка Gateway ​

Расположение персистентного состояния (источник истины) ​

Развёртывание exe.dev ​

Цель ​

Что вам понадобится ​

Шаг 1: Создание VM ​

Шаг 2: Установка предварительных требований на VM ​

Node 22 ​

Шаг 3: Установка Clawdbot ​

Шаг 4: Первоначальная настройка (мастер) ​

Шаг 5: Варианты удалённого доступа ​

Вариант A (рекомендуется): SSH-туннель (только loopback) ​

Вариант B: HTTPS-прокси exe.dev (без туннелирования) ​

Шаг 6: Поддержание работы (сервис) ​

Шаг 7: Обновление ​

Рекомендации по выбору ​

Выбор по сценарию использования ​

Лучшие практики безопасности ​

Мониторинг и логи ​

Контрольная точка ✅ ​

Предупреждения о подводных камнях ​

Резюме урока ​

Приложение: Справочник по исходному коду ​

Варианты развёртывания

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

Ваша текущая ситуация

Когда использовать этот подход

🎒 Подготовка к началу

Сравнение способов развёртывания

Локальная установка

Развёртывание Docker

Развёртывание Nix

Облачное развёртывание (Fly.io / Hetzner / exe.dev)

Локальная установка

Глобальная установка npm/pnpm/bun (рекомендуется)

Сборка из исходного кода

Развёртывание Docker

Быстрый старт (рекомендуется)

Ручной процесс

Дополнительные монтирования (опционально)

Персистентность домашней директории контейнера (опционально)

Установка дополнительных системных пакетов (опционально)

Настройка каналов (опционально)

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

Agent Sandbox (Gateway на хосте + инструменты Docker)

Установка Nix

Быстрый старт

Поведение в режиме Nix

Пути конфигурации и состояния

Облачное развёртывание Fly.io

Что вам понадобится

Шаг 1: Создание приложения Fly

Шаг 2: Настройка fly.toml

Шаг 3: Установка секретов

Шаг 4: Развёртывание

Шаг 5: Создание файла конфигурации

Шаг 6: Доступ к Gateway

Устранение неполадок

Приватное развёртывание (защита)

Стоимость

Развёртывание Hetzner VPS

Цель

Что вам понадобится

Шаг 1: Настройка VPS

Шаг 2: Установка Docker на VPS

Шаг 3: Клонирование репозитория Clawdbot

Шаг 4: Создание персистентных директорий хоста

Шаг 5: Настройка переменных окружения

Шаг 6: Конфигурация Docker Compose

Шаг 7: Встраивание необходимых бинарных файлов в образ (критично)

Шаг 8: Сборка и запуск

Шаг 9: Проверка Gateway

Расположение персистентного состояния (источник истины)

Развёртывание exe.dev

Цель

Что вам понадобится

Шаг 1: Создание VM

Шаг 2: Установка предварительных требований на VM

Node 22

Шаг 3: Установка Clawdbot

Шаг 4: Первоначальная настройка (мастер)

Шаг 5: Варианты удалённого доступа

Вариант A (рекомендуется): SSH-туннель (только loopback)

Вариант B: HTTPS-прокси exe.dev (без туннелирования)

Шаг 6: Поддержание работы (сервис)

Шаг 7: Обновление

Рекомендации по выбору

Выбор по сценарию использования

Лучшие практики безопасности

Мониторинг и логи

Контрольная точка ✅

Предупреждения о подводных камнях

Резюме урока

Приложение: Справочник по исходному коду