Урок 3. Быстрый старт#

Зачем это нужно#

Вы установили HAPI — пора его запустить! В этом уроке мы за 5 минут поднимем HAPI, получим QR-код и подключимся с телефона. Всего две команды.

Шаг 1. Запускаем Hub#

Откройте терминал и введите:

npx @twsxtd/hapi hub --relay

Или, если вы установили HAPI глобально:

hapi hub --relay

💡 hapi server тоже работает — это альтернативное название той же команды.

Что происходит:

• Запускается hub (центр управления) на вашем компьютере
• Флаг --relay подключает ретранслятор для доступа через интернет
• Трафик шифруется с помощью WireGuard + TLS

Что вы увидите в терминале:

🚀 Hub started on http://localhost:3006
🔗 Remote URL: https://xxxx.relay.example.com
📱 Scan QR code to connect:

█████████████████████████
█████████████████████████
████ ▄▄▄▄▄ █▄█▄█ ▄▄▄▄▄ ████
████ █   █ █▀▀▀█ █   █ ████
...

🔑 Access token: abc123def456...

Здесь:

• Remote URL — адрес для подключения с телефона
• QR-код — тот же адрес, но в виде картинки для сканирования
• Access token — пароль для входа (сохраните его!)

⚠️ Не закрывайте этот терминал! Hub должен работать постоянно. Откройте новый терминал для следующего шага.

Шаг 2. Запускаем AI-агента#

Откройте второй терминал и введите:

npx @twsxtd/hapi

Или:

hapi

Что происходит:

• Запускается Claude Code (AI-агент по умолчанию) с обёрткой HAPI
• Сессия автоматически регистрируется в hub
• Вы можете работать с Claude Code как обычно

💡 Для других AI-агентов используйте:

hapi codex      # OpenAI Codex
hapi gemini     # Google Gemini
hapi opencode   # OpenCode

Шаг 3. Подключаемся с телефона#

Теперь самое интересное!

Вариант A: Сканируем QR-код#

1. Откройте камеру телефона (или любой сканер QR-кодов)
2. Наведите на QR-код в терминале
3. Перейдите по ссылке

Вариант B: Открываем URL вручную#

1. Скопируйте Remote URL из терминала
2. Откройте его в браузере на телефоне

Вводим токен#

При первом подключении HAPI попросит Access token — тот самый пароль, который появился в терминале. Введите его и нажмите «Войти».

💡 Токен нужно ввести только один раз — браузер его запомнит.

Шаг 4. Проверяем подключение#

После входа вы увидите веб-интерфейс HAPI с:

• Списком сессий — ваша сессия Claude Code уже там
• Чатом — можно отправить сообщение AI-агенту
• Статусом подключения — зелёный индикатор означает, что всё работает

Попробуйте отправить сообщение с телефона! Вы увидите, как AI-агент отвечает и на телефоне, и в терминале.

Что значит каждая команда#

Типичная схема работы#

Терминал 1 (hub):          Терминал 2 (агент):        Телефон:
                            
hapi hub --relay            hapi                       Сканируем QR
    │                          │                           │
    │◄─── подключение ────────►│                           │
    │                          │                           │
    │◄──────────── просмотр / управление ─────────────────►│

Устранение проблем#

«Connection refused»#

Hub не запущен. Убедитесь, что первый терминал с hapi hub --relay всё ещё работает.

QR-код не сканируется#

Попробуйте увеличить окно терминала, чтобы QR-код отображался целиком. Или скопируйте URL вручную.

«Invalid token»#

Проверьте, что вводите правильный токен. Его можно найти в файле ~/.hapi/settings.json:

cat ~/.hapi/settings.json

Relay не подключается#

Если у вас проблемы с UDP-соединением (в некоторых сетях UDP заблокирован), попробуйте TCP-режим:

HAPI_RELAY_FORCE_TCP=true hapi hub --relay

Итоги урока#

• Две команды — это всё, что нужно для старта: hapi hub --relay и hapi
• QR-код позволяет мгновенно подключиться с телефона
• Access token — ваш пароль для входа, вводится один раз
• Hub должен работать постоянно в отдельном терминале
• Всё соединение зашифровано — relay не видит ваших данных

В следующем уроке мы превратим веб-интерфейс HAPI в полноценное приложение на телефоне.