Урок 4. Конфигурация HAPI#

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

HAPI работает «из коробки» с настройками по умолчанию. Но иногда нужно что-то изменить: поменять порт, задать публичный адрес, подключить Telegram-бота. В этом уроке разберём, как настроить CLI и Hub под свои нужды.

Где хранятся настройки#

Все файлы HAPI лежат в одной папке:

~/.hapi/
├── settings.json       # Главный файл настроек
├── hapi.db            # База данных (сессии, сообщения)
├── access.key         # Ключ доступа CLI
├── runner.state.json  # Состояние Runner
└── logs/              # Логи (журналы работы)

~ — это сокращение для вашей домашней папки. На macOS это /Users/ваше_имя, на Linux — /home/ваше_имя.

Чтобы изменить расположение этой папки:

export HAPI_HOME="~/my-custom-hapi-folder"

Три способа задать настройки#

HAPI читает настройки из трёх источников. Если одна настройка задана в нескольких местах, побеждает тот источник, который выше в списке:

1. Переменные окружения (высший приоритет) — export HAPI_LISTEN_PORT=4000
2. Файл settings.json — ~/.hapi/settings.json
3. Значения по умолчанию (низший приоритет)

💡 Если вы задали настройку через переменную окружения, и её ещё нет в settings.json — HAPI автоматически сохранит её в файл для будущих запусков.

Настройки Hub#

Hub — это серверная часть HAPI. Вот основные настройки:

Сеть и доступ#

Порт — это как номер квартиры в доме. IP-адрес — это адрес дома, а порт указывает, к какой конкретно программе обращаться. По умолчанию Hub «живёт» на порту 3006.

127.0.0.1 (localhost) означает, что Hub принимает подключения только с вашего компьютера. Если вы хотите, чтобы Hub был доступен из локальной сети, измените на 0.0.0.0.

Пример: сменить порт на 8080

export HAPI_LISTEN_PORT=8080
hapi hub

Или в settings.json:

{
  "listenPort": 8080
}

Пример: открыть доступ из локальной сети

{
  "listenHost": "0.0.0.0",
  "listenPort": 3006
}

Аутентификация#

Этот токен генерируется автоматически при первом запуске. Он нужен, чтобы только ваш CLI мог подключаться к Hub.

⚠️ Если токен стал известен посторонним — удалите его из settings.json и перезапустите Hub. Будет создан новый.

Telegram#

Relay#

Голосовой ассистент#

База данных#

Настройки CLI#

CLI — это клиентская часть, которая запускает AI-агента. У неё меньше настроек:

Пример: подключение CLI к удалённому Hub

export HAPI_API_URL="https://мой-сервер.com"
export CLI_API_TOKEN="мой-секретный-токен"
hapi

Или используйте интерактивную авторизацию:

hapi auth login     # Войти
hapi auth status    # Проверить статус
hapi auth logout    # Выйти

Пример файла settings.json#

Вот полный пример с комментариями:

{
  "$schema": "https://hapi.run/docs/schemas/settings.schema.json",
  "listenHost": "0.0.0.0",
  "listenPort": 3006,
  "publicUrl": "https://hapi.example.com",
  "telegramBotToken": "123456:ABC-DEF...",
  "telegramNotification": true,
  "corsOrigins": "https://hapi.example.com"
}

💡 Поле $schema необязательно, но если ваш редактор поддерживает JSON Schema, он будет подсказывать доступные настройки и проверять ошибки.

Практические сценарии#

Сценарий 1: Работа только локально#

Ничего менять не нужно! Настройки по умолчанию подходят:

hapi hub    # Hub на localhost:3006
hapi        # CLI подключается автоматически

Сценарий 2: Доступ через Relay + Telegram#

export TELEGRAM_BOT_TOKEN="ваш-токен-бота"
export ELEVENLABS_API_KEY="ваш-ключ"
hapi hub --relay

Сценарий 3: Несколько компьютеров подключены к одному Hub#

На сервере:

hapi hub

На каждом рабочем компьютере:

export HAPI_API_URL="http://адрес-сервера:3006"
export CLI_API_TOKEN="общий-токен"
hapi

Каждый компьютер получает уникальный ID — так Hub различает машины.

Итоги урока#

• Настройки хранятся в папке ~/.hapi/, главный файл — settings.json
• Три источника настроек: переменные окружения > settings.json > значения по умолчанию
• Основные настройки Hub: порт (3006), адрес (127.0.0.1), токен, Telegram
• CLI настраивается через HAPI_API_URL и CLI_API_TOKEN
• Для большинства задач настройки по умолчанию подходят — менять что-то нужно только при особых сценариях