Настройка Slack

Подключите Hermes Agent к Slack как боту, используя Socket Mode. В режиме сокета используется WebSocket вместо общедоступных HTTP-конечных точек, поэтому ваш экземпляр Hermes не должен быть общедоступным — он работает за брандмауэрами, на вашем ноутбуке или в частном режиме.

Обзор

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

Самый быстрый путь — вставить манифест, который Hermes пришёл к вам. Он объявляет все встроенные слэш-команды (/btw, /stop, /model, …), все необходимые области OAuth, все подписки на события и включает режим сокета — всё сразу.

Вариант A: Из манифеста, сгенерированного Hermesа (рекомендуется)

1. Сгенерируйте манифест: bash hermes slack manifest --write Это запишет ~/.hermes/slack-manifest.json и выведет инструкции по вставке.
2. Перейдите на https://api.slack.com/apps → Create New App → From an app manifest
3. Выберите свою рабочую область, вставьте содержимое JSON, просмотрите, нажмите Next → Create
4. Перейдите к Шагу 6: Установите приложение в рабочую область. Манифест обработал области, события и слеш-команды за вас.

Вариант B: С нуля (вручную)

1. Перейдите на https://api.slack.com/apps
2. Нажмите Create New App
3. Выберите From scratch
4. Введите имя приложения (например, "Hermes Agent") и выберите свою рабочую область
5. Нажмите Create App

Вы попадёте на страницу Basic Information приложения. Продолжите с шагов 2–6 ниже.

Шаг 2: Настройте области токена бота

Перейдите в Features → OAuth & Permissions на боковой панели. Прокрутите до Scopes → Bot Token Scopes и добавьте следующее:

Шаг 3: Включите Socket Mode

Socket Mode позволяет боту подключаться через WebSocket вместо необходимости публичного URL.

1. На боковой панели перейдите в Settings → Socket Mode
2. Переключите Enable Socket Mode в положение ON
3. Вам будет предложено создать App-Level Token:
4. Назовите его, например, hermes-socket (имя не имеет значения)
5. Добавьте область connections:write
6. Нажмите Generate
7. Скопируйте токен — он начинается с xapp-. Это ваш SLACK_APP_TOKEN

   💡 Tip

   Вы всегда можете найти или перегенерировать токены уровня приложения в Settings → Basic Information → App-Level Tokens.

Шаг 4: Подпишитесь на события

Этот шаг критически важен — он определяет, какие сообщения бот может видеть.

1. На боковой панели перейдите в Features → Event Subscriptions
2. Переключите Enable Events в положение ON
3. Разверните Subscribe to bot events и добавьте:

1. Нажмите Save Changes внизу страницы

   🚨 Danger

   Отсутствие подписок на события — проблема №1 при настройке Если бот работает в ЛС, но не в каналах, вы почти наверняка забыли добавить message.channels (для публичных каналов) и/или message.groups (для приватных каналов). Без этих событий Slack просто никогда не доставляет сообщения каналов боту.

Шаг 5: Включите вкладку сообщений

Этот шаг включает личные сообщения боту. Без него пользователи видят "Sending messages to this app has been turned off" при попытке написать боту в ЛС.

1. На боковой панели перейдите в Features → App Home
2. Прокрутите до Show Tabs
3. Переключите Messages Tab в положение ON
4. Отметьте "Allow users to send Slash commands and messages from the messages tab"

   🚨 Danger

   Без этого шага ЛС полностью заблокированы Даже со всеми правильными областями и подписками на события Slack не позволит пользователям отправлять личные сообщения боту, если не включена вкладка сообщений. Это требование платформы Slack, а не проблема конфигурации Hermes.

Шаг 6: Установите приложение в рабочую область

1. На боковой панели перейдите в Settings → Install App
2. Нажмите Install to Workspace
3. Просмотрите разрешения и нажмите Allow
4. После авторизации вы увидите Bot User OAuth Token, начинающийся с xoxb-
5. Скопируйте этот токен — это ваш SLACK_BOT_TOKEN

   💡 Tip

   Если вы позже измените области или подписки на события, вы должны переустановить приложение, чтобы изменения вступили в силу. Страница Install App покажет баннер с предложением сделать это.

Шаг 7: Найдите ID пользователей для белого списка

Hermes использует Slack Member IDs (не имена пользователей или отображаемые имена) для белого списка.

Чтобы найти Member ID:

1. В Slack нажмите на имя или аватар пользователя
2. Нажмите View full profile
3. Нажмите кнопку ⋮ (ещё)
4. Выберите Copy member ID

Member IDs выглядят как U01ABC2DEF3. Вам нужен как минимум ваш собственный Member ID.

Шаг 8: Настройте Hermes

Добавьте следующее в ваш файл ~/.hermes/.env:

# Обязательно
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3              # Разделённые запятыми Member IDs

# Опционально
SLACK_HOME_CHANNEL=C01234567890              # Канал по умолчанию для cron/плановых сообщений
SLACK_HOME_CHANNEL_NAME=general              # Человекочитаемое имя для домашнего канала (опционально)

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

hermes gateway setup    # Выберите Slack при запросе

Затем запустите шлюз:

hermes gateway              # На переднем плане
hermes gateway install      # Установить как пользовательский сервис
sudo hermes gateway install --system   # Только Linux: системный сервис при загрузке

Шаг 9: Пригласите боту в сети

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

/invite @Hermes Agent

Бот не будет автоматически присоединяться к каналам. Вы должны пригласить его в каждый канал индивидуально.

Слеш-команды

каждый Hermes (/btw, /stop, /new, /model, /help,...) является нативной слэш-командой Slack — точно так же, как они работают в Telegram и Discord. Введите / в Slack, и средство автозаполнения покажет все команды Hermes с их описаниями.

Под капотом: Hermes подключается со сгенерированным манифестом приложения Slack (см. Шаг 1, Вариант A), который объявляет каждую команду из COMMAND_REGISTRY как слеш-команду. В режиме Socket Slack маршрутизирует события команды через WebSocket независимо от полей url манифеста.

Обновление слеш-команды после обновлений

Когда Hermes добавляет новые команды (например, после hermes update), перегенерируйте манифест и обновите свое приложение Slack:

hermes slack manifest --write

Затем в Slack: 1. Откройте https://api.slack.com/apps → ваше приложение Hermes 2. Функции → Манифест приложения → Редактировать 3. Вставьте новые бутылки ~/.hermes/slack-manifest.json 4. Сохранить. Slack предлагает переустановить приложение, если изменились области или слэш-команды.

Устаревшая /hermes <подкоманда> всё ещё работает

Для обратной совместимости со старыми манифестами вы всё ещё можете ввести /hermes, кстати, запустить тесты — Hermes маршрутизирует это так же, как /btw запустить тесты. Свободные вопросы также работают: /Hermes, какая погода? обрабатывается как обычное сообщение.

Использование команды внутри тредов (префикс !cmd)

Slack сам блокирует нативные слэш-команды внутри тредов — формирует /queue в треде, и Slack отвечает "/queue не поддерживается в тредах. Извините!" Нет никаких настроек на стороне приложения, которая бы их снова включила; Slack никогда не доставляет им Hermes.

В качестве обходного пути Hermes распознаёт ведущего ! как альтернативный префикс команды, который работает в тредах (и везде). Используйте !queue, !stop, !model gpt-5.4 и т.д. как обычный ответ в треде — Hermes обрабатывает это так же, как слэш-форму, и отвечает в той же треде.

Проверяется только первый токен соответствия известному списку команды, поэтому случайные сообщения типа «!nice work» передаются агенту без изменений.

Продвинутый: вывести только массив слэш-команд

Если вы поддерживаете манифест Slack вручную и хотите составить список только слеш-командой:

hermes slack manifest --slashes-only > /tmp/slashes.json

Вставьте этот массив в ключ features.slash_commands вашего существующего манифеста.

Как отвечает бот

Понимание поведения Hermesа в разных контекстах:

Параметры конфигурации

Помимо обязательных условий окружения из шага 8, вы можете настроить работу бота Slack через ~/.hermes/config.yaml.

Поведение тредов и атак

platforms:
  slack:
    # Управляет тем, как многокомпонентные ответы помещаются в треды
    # "off"   — никогда не помещать ответы в тред к исходному сообщению
    # "first" — первый фрагмент помещается в тред к сообщению пользователя (по умолчанию)
    # "all"   — все фрагменты помещаются в тред к сообщению пользователя
    reply_to_mode: "first"

    extra:
      # Отвечать ли в треде (по умолчанию: true).
      # Если false, сообщения в канале получают прямые ответы в канале вместо тредов.
      # Сообщения внутри существующих тредов всё равно отвечают в треде.
      reply_in_thread: true

      # Также публиковать ответы в треде в основной канал
      # (функция Slack "Also send to channel").
      # Только первый фрагмент первого ответа транслируется.
      reply_broadcast: false

Изоляция сессий

# Глобальная настройка — применяется к Slack и всем другим платформам
group_sessions_per_user: true

Если true (по умолчанию), каждый пользователь в общем канале получает свою собственную изолированную сессию в беседке. Два человека, общающиеся с Hermesом в #general, смогут разработать историю и контексты.

Установите значение «false», если вам нужен совместный режим, где весь канал использует одну сессию беседы. Имейте в виду, что это означает, что пользователи делят рост контекста и затраты на токены, а /reset один пользователь очищает сессию для всех.

Поведение упоминаний и триггеров

slack:
  # Требовать @упоминание в каналах (это поведение по умолчанию;
  # адаптер Slack принудительно требует @упоминание в каналах независимо,
  # но вы можете установить это явно для согласованности с другими платформами)
  require_mention: true

  # Предотвращать автоматическое вовлечение в тред: отвечать только на сообщения в канале,
  # которые содержат явное @упоминание. Если это ВЫКЛ (по умолчанию), Slack может
  # "автоматически вовлекаться" — запоминать прошлые упоминания в треде и
  # продолжать ответы на сообщения бота, а также возобновлять активные сессии без
  # нового упоминания. Если strict_mention ВКЛ, каждое новое сообщение в канале
  # должно @упоминать бота, прежде чем Hermes ответит.
  strict_mention: false

  # Пользовательские шаблоны упоминаний, которые активируют бота
  # (в дополнение к стандартному обнаружению @упоминаний)
  mention_patterns:
    - "hey hermes"
    - "hermes,"

  # Текст, добавляемый перед каждым исходящим сообщением
  reply_prefix: ""
```<div class="admonition admonition-tip"><p class="admonition-title">💡 Tip</p> Когда использовать `strict_mention`
Установите это в `true` на занятых рабочих местах, где поведение Slack по умолчанию "бот помнит этот тред" удивляет пользователей — например, длинный тред техподдержки, где бот вызывает в начале, и вы бы предпочли, чтобы он молчал, если он явно не пингует снова. ЛС и активные интерактивные сессии не затрагиваются.:::<div class="admonition admonition-info"><p class="admonition-title">ℹ️ Info</p>
Поддержка Slack для обоих шаблонов: @упоминание требуется для начала разговора по умолчанию, но вы можете изменить внешние каналы через `SLACK_FREE_RESPONSE_CHANNELS` (разделённые запятые идентификаторы каналов) или `slack.free_response_channels` в `config.yaml`. Как только у бота есть активная сессия в треде, ответы в треде не требуют упоминаний. В ЛС бот всегда отвечает без необходимости упоминаний.</div>
### Обработка неавторизованных пользователей
```yaml
slack:
  # Что происходит, когда неавторизованный пользователь (не в SLACK_ALLOWED_USERS) пишет боту в ЛС
  # "pair"   — предложить им код привязки (по умолчанию)
  # "ignore" — молча игнорировать сообщение
  unauthorized_dm_behavior: "pair"

Вы также можете установить это глобально для всех платформ:

unauthorized_dm_behavior: "pair"

Настройка, специфичная для платформы под slack:, имеет приоритет над глобальной настройкой.

Транскрипция голосов

# Глобальная настройка — включить/отключить автоматическую транскрипцию входящих голосовых сообщений
stt_enabled: true

Если true (по умолчанию), входящие аудиосообщения автоматически транскрибируются с помощью настроенного STT-провайдера перед обработкой агентом.

Полный пример

# Глобальные настройки шлюза
group_sessions_per_user: true
unauthorized_dm_behavior: "pair"
stt_enabled: true

# Настройки, специфичные для Slack
slack:
  require_mention: true
  unauthorized_dm_behavior: "pair"

# Конфигурация платформы
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

Домашний канал

Установите SLACK_HOME_CHANNEL в ID канала, куда Hermes будет отправлять плановые сообщения, результаты задач cron и другие проактивные уведомления. Чтобы найти идентификатор канала:

1. Щёлкните правую кнопку мыши по имени канала в Slack.
2. Нажмите Просмотреть сведения о канале.
3. Прокрутите вниз — там отображается идентификатор канала.

SLACK_HOME_CHANNEL=C01234567890

Убедитесь, что бот был приглашён на канал (/invite @Hermes Agent).

Поддержка нескольких рабочих областей

Hermes может подключаться к нескольким регионам Slack одновременно, используя один экземпляр шлюза. Аутентификация каждой рабочей области осуществляется независимо от собственного идентификатора пользователя бота.

Конфигурация

Укажите несколько токенов бота в виде разделённого запятыми списками в SLACK_BOT_TOKEN:

# Несколько токенов бота — по одному на рабочую область
SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token

# Один токен уровня приложения всё ещё используется для Socket Mode
SLACK_APP_TOKEN=xapp-your-app-token

Или в ~/.hermes/config.yaml:

platforms:
  slack:
    token: "xoxb-workspace1-token,xoxb-workspace2-token"

Файл токенов OAuth

В дополнение к токенам в процессе или конфигурации Hermes также загружает токены из файла токенов OAuth по адресу:

~/.hermes/slack_tokens.json

Этот файл представляет собой JSON-объект, сопоставляющий идентификатор команды с записями токенов:

{
  "T01ABC2DEF3": {
    "token": "xoxb-workspace-token-here",
    "team_name": "My Workspace"
  }
}

Токены из этого файла объединяются с любыми токенами, записываясь через SLACK_BOT_TOKEN. Дублирующиеся токены автоматически удаляются.

Как это работает

— Первый токен в списке является основным токеном, используемым для режима сокетов подключения (AsyncApp). - Каждый токен аутентифицируется через auth.test при запуске. Шлюз сопоставляет каждый team_id с собственным WebClient и bot_user_id. - Когда приходит сообщение, «Hermes» использует для ответа подходящего клиента, специфичного для рабочей области. - Основной bot_user_id (из первого токена) используется для обратной совместимости с возможностями, которые обеспечивают единую идентичность бота.

Голосовые сообщения

Hermes поддерживает голос в Slack:

• Входящие: Голосовые/аудиосообщения автоматически транскрибируются с помощью настроенного STT-провайдера: локальный faster-whisper, Groq Whisper (GROQ_API_KEY) или OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY)
• Исходящие: TTS-ответы отправляются как вложения аудиофайлов.

Промпты для каналов

Назначьте эфемерные системные запросы для конкретных каналов Slack. Подсказка применяется во время выполнения каждого оборота — никогда не сохраняется в истории транскрипции, поэтому изменения выполняются мгновенно.

slack:
  channel_prompts:
    "C01RESEARCH": |
      Вы — исследовательский ассистент. Сосредоточьтесь на академических источниках,
      цитированиях и кратком синтезе.
    "C02ENGINEERING": |
      Режим ревью кода. Будьте точны в отношении граничных случаев и
      последствий для производительности.

Ключи — это ID каналов Slack (найдите их детали через канал → «О программе» → прокрутите вниз). Все сообщения в соответствующем канале получают подсказку, внедрённую в качестве эфемерной системной инструкции.

Привязки функций для различных каналов

Автоматически загружайте навыки при запуске новой сессии в конкретном канале или ЛС. В отличие от подсказок для каналов (которые применяются на каждом из них), привязки функций включают строгие навыки, такие как сообщение пользователя при запуске сессии — они становятся частью истории бесед и не требуют перезагрузки на малых оборотах.

Этот вопрос идеально подходит для ЛС или каналов с выделенной Целью (флеш-карты, бот-ответы по конкретной области, канал триажа поддержки и т. д.), где вы не хотите, чтобы масштабный селектор функций модели решил, загрузите его на каждый короткий ответ.

slack:
  channel_skill_bindings:
    # ЛС канал — всегда работает в режиме "german-flashcards"
    - id: "D0ATH9TQ0G6"
      skills:
        - german-flashcards
    # Исследовательский канал — предзагрузить несколько навыков по порядку
    - id: "C01RESEARCH"
      skills:
        - arxiv
        - writing-plans
    # Краткая форма: один навык как строка
    - id: "C02SUPPORT"
      skill: hubspot-on-demand

Примечания: - Привязка сопоставляется по ID-каналу. Для сообщений в треде в судебном канале тред наследует привязку родительского канала. - Навык загружается только при запуске сессии (новая сессия или после автосброса). Если вы измените привязку, выполните /new или дождитесь автосброса сессии, чтобы она вступила в силу. - Комбинируйте с channel_prompts для тона/ограничений на канале уровня инструкции навыка.

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

Быстрый чек-лист

Если бот не работает в каналах, проверьте все следующее:

1. ✅ Событие подписано message.channels (для публичных каналов)
2. ✅ Событие подписано message.groups (для приватных каналов)
3. ✅ Событие подписано app_mention
4. ✅ Добавлена область channels:history (для публичных каналов)
5. ✅ Добавлена область groups:history (для приватных каналов)
6. ✅ Применение было переустановлено после смены регионов/событий.
7. ✅ Бот был приглашён в канале (/invite @Hermes Agent)
8. ✅ Вы @упоминаете боту в своей странице

Безопасность

⚠️ Warning

Всегда устанавливайте SLACK_ALLOWED_USERS с идентификаторами участников авторизованных пользователей. Без этой настройки шлюз будет отклонять все сообщения по умолчанию в качестве меры безопасности. Никогда не делитесь своими токенами бота — обращайтесь с ними как с записями.