Перейти к содержанию

Slack

На этой странице Подключите Hermes Agent к Slack в качестве бота через Socket Mode. Socket Mode использует WebSocket вместо публичных HTTP-эндпоинтов, поэтому вашему экземпляру Hermes не нужен публичный доступ — он работает за файрволами, на вашем ноутбуке или на приватном сервере. Классические Slack-приложения устарели Классические Slack-приложения (с использованием RTM API) были полностью упразднены в марте 2025. Hermes использует современный Bolt SDK с Socket Mode. Если у вас есть старое классическое приложение, создайте новое, следуя инструкциям ниже.

Обзор​

Компонент Значение
Библиотека slack-bolt / slack_sdk для Python (Socket Mode)
Подключение WebSocket — публичный URL не требуется
Необходимые токены Bot Token (xoxb-) + App-Level Token (xapp-)
Идентификация пользователей Slack Member ID (напр., U01ABC2DEF3)
* * *
## Шаг 1: Создайте Slack-приложение​
Самый быстрый способ — вставить манифест, который генерирует Hermes. Он объявляет все встроенные слэш-команды (/btw, /stop, /model, …), все необходимые OAuth-области, все подписки на события и включает Socket Mode — всё сразу.
### Вариант A: Из манифеста, сгенерированного Hermes (рекомендуется)​
1. Сгенерируйте манифест:
[code] hermes slack manifest --write

[/code] Эта команда записывает ~/.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: Настройте области Bot Token​

Перейдите в Features → OAuth & Permissions на боковой панели. Прокрутите до Scopes → Bot Token Scopes и добавьте следующее: | Область | Назначение | |---|---| | chat:write | Отправка сообщений от имени бота | | app_mentions:read | Обнаружение упоминаний @ в каналах | | channels:history | Чтение сообщений в публичных каналах, где находится бот | | channels:read | Список и информация о публичных каналах | | groups:history | Чтение сообщений в приватных каналах, куда приглашён бот | | im:history | Чтение истории личных сообщений | | im:read | Просмотр базовой информации о ЛС | | im:write | Открытие и управление ЛС | | users:read | Поиск информации о пользователях | | files:read | Чтение и скачивание вложенных файлов, включая голосовые заметки/аудио | | files:write | Загрузка файлов (изображений, аудио, документов) | Отсутствующие области = отсутствующие функции Без channels:history и groups:history бот не будет получать сообщения в каналах — он будет работать только в ЛС. Без files:read Hermes может общаться, но не сможет надёжно читать загруженные пользователем вложения. Это наиболее часто пропускаемые области. Дополнительные области: | Область | Назначение | |---|---| | groups:read | Список и информация о приватных каналах |

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

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

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

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

Этот шаг критически важен — он определяет, какие сообщения бот может видеть. 1. На боковой панели перейдите в Features → Event Subscriptions 2. Включите тумблер Enable Events 3. Разверните Subscribe to bot events и добавьте:

Событие Обязательно? Назначение
message.im Да Бот получает личные сообщения
message.channels Да Бот получает сообщения в публичных каналах, куда его добавили
message.groups Рекомендуется Бот получает сообщения в приватных каналах, куда его пригласили
app_mention Да Предотвращает ошибки Bolt SDK при упоминании бота через @
4. Нажмите Save Changes внизу страницы

Отсутствие подписок на события — проблема №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 4. Отметьте «Allow users to send Slash commands and messages from the messages tab»

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

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

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

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

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

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

Member ID выглядят как U01ABC2DEF3. Как минимум, вам понадобится ваш собственный Member ID.

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

Добавьте следующее в файл ~/.hermes/.env: [code] # Обязательно SLACK_BOT_TOKEN=xoxb-your-bot-token-here SLACK_APP_TOKEN=xapp-your-app-token-here SLACK_ALLOWED_USERS=U01ABC2DEF3 # Member ID через запятую

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

[/code] Или запустите интерактивную настройку: [code] hermes gateway setup # Выберите Slack при запросе

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

[/code]

Шаг 9: Пригласите бота в каналы​

После запуска шлюза вам нужно пригласить бота в каждый канал, где вы хотите, чтобы он отвечал: [code] /invite @Hermes Agent

[/code] Бот не присоединяется к каналам автоматически. Вы должны приглашать его в каждый канал отдельно.

Слэш-команды​

Каждая команда Hermes (/btw, /stop, /new, /model, /help, ...) является родной слэш-командой Slack — точно так же, как они работают в Telegram и Discord. Введите / в Slack, и автодополнение покажет каждую команду Hermes с её описанием. Под капотом: Hermes поставляется со сгенерированным манифестом Slack-приложения (см. Шаг 1, Вариант A), который объявляет каждую команду из COMMAND_REGISTRY как слэш-команду. В Socket Mode Slack маршрутизирует событие команды через WebSocket независимо от поля url в манифесте.

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

Когда Hermes добавляет новые команды (например, после hermes update), перегенерируйте манифест и обновите своё Slack-приложение: [code] hermes slack manifest --write

[/code] Затем в Slack: 1. Откройте https://api.slack.com/apps → ваше приложение Hermes 2. Features → App Manifest → Edit 3. Вставьте новое содержимое ~/.hermes/slack-manifest.json 4. Save. Slack предложит переустановить приложение, если изменились области или слэш-команды.

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

Для обратной совместимости со старыми манифестами вы всё ещё можете ввести /hermes btw run the tests — Hermes обработает её так же, как /btw run the tests. Свободные вопросы также работают: /hermes what's the weather? воспринимается как обычное сообщение.

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

Если вы поддерживаете манифест Slack вручную и хотите только список слэш-команд: [code] hermes slack manifest --slashes-only > /tmp/slashes.json

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

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

Понимание того, как Hermes ведёт себя в разных контекстах: | Контекст | Поведение | |---|---| | ЛС | Бот отвечает на каждое сообщение — @упоминание не требуется | | Каналы | Бот отвечает только при @упоминании (напр., @Hermes Agent который час?). В каналах Hermes отвечает в ветке, прикреплённой к этому сообщению. | | Ветки | Если вы упомянете Hermes через @ в существующей ветке, он ответит в той же ветке. Как только у бота появится активная сессия в ветке, последующие ответы в этой ветке не требуют @упоминания — бот естественно продолжает разговор. | Подсказка В каналах всегда используйте @упоминание бота, чтобы начать разговор. Как только бот активен в ветке, вы можете отвечать в этой ветке без упоминания. Вне веток сообщения без @упоминания игнорируются, чтобы избежать шума в оживлённых каналах.

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

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

Поведение веток и ответов​

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

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

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

[/code] | Ключ | По умолчанию | Описание | |---|---|---| | platforms.slack.reply_to_mode | "first" | Режим ветвления для многочастных сообщений: "off", "first" или "all" | | platforms.slack.extra.reply_in_thread | true | При false сообщения в каналах получают прямые ответы вместо веток. Сообщения внутри существующих веток всё равно отвечают в той же ветке. | | platforms.slack.extra.reply_broadcast | false | При true ответы в ветках также публикуются в основной канал. Транслируется только первый фрагмент. |

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

[code] # Глобальная настройка — применяется к Slack и всем остальным платформам group_sessions_per_user: true

[/code] Если true (по умолчанию), каждый пользователь в общем канале получает свою изолированную сессию разговора. Два человека, общающиеся с Hermes в #general, будут иметь отдельные истории и контексты. Установите false, если хотите совместный режим, где весь канал использует одну сессию разговора. Имейте в виду, что это означает общий рост контекста и затраты на токены, а команда /reset одного пользователя очистит сессию для всех.

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

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

  # Предотвращать авто-вовлечение в ветки: отвечать только на сообщения в каналах,
  # которые содержат явное @упоминание. При выключенном режиме (по умолчанию) Slack
  # может «авто-вовлекаться» — запоминать прошлые упоминания в ветке и продолжать
  # диалог, отвечая на сообщения бота, а также возобновлять активные сессии без
  # нового упоминания. При включённом strict_mention каждое новое сообщение в канале
  # должно содержать @упоминание бота, чтобы Hermes ответил.
  strict_mention: false

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

  # Текст, добавляемый к каждому исходящему сообщению
  reply_prefix: ""

[/code] Когда использовать strict_mention Установите true в загруженных рабочих областях, где стандартное поведение Slack «бот помнит эту ветку» удивляет пользователей — например, в длинном техподдержном треде, где бот помог в начале, а вы предпочли бы, чтобы он оставался молчаливым, если его не пинговали снова. ЛС и активные интерактивные сессии не затрагиваются. Информация Slack поддерживает оба шаблона: по умолчанию @упоминание требуется для начала разговора, но вы можете отключить это для отдельных каналов через SLACK_FREE_RESPONSE_CHANNELS (ID каналов через запятую) или slack.free_response_channels в config.yaml. Как только у бота есть активная сессия в ветке, последующие ответы в ветке не требуют упоминания. В ЛС бот всегда отвечает без необходимости упоминания.

Обработка неавторизованных пользователей​

[code] slack: # Что происходит, когда неавторизованный пользователь (не в SLACK_ALLOWED_USERS) пишет боту в ЛС # "pair" — предложить ему код привязки (по умолчанию) # "ignore" — молча проигнорировать сообщение unauthorized_dm_behavior: "pair"

[/code] Вы также можете установить это глобально для всех платформ: [code] unauthorized_dm_behavior: "pair"

[/code] Настройка уровня платформы в разделе slack: имеет приоритет над глобальной настройкой.

Транскрибация голосовых сообщений​

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

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

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

[code] # Глобальные настройки шлюза 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

[/code]

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

Установите SLACK_HOME_CHANNEL — ID канала, куда Hermes будет доставлять плановые сообщения, результаты cron-задач и другие проактивные уведомления. Чтобы найти ID канала: 1. Кликните правой кнопкой мыши по названию канала в Slack 2. Нажмите View channel details 3. Прокрутите вниз — ID канала отображается там

[code] SLACK_HOME_CHANNEL=C01234567890

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

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

Hermes может подключаться к нескольким рабочим областям Slack одновременно, используя один экземпляр шлюза. Каждая рабочая область аутентифицируется независимо со своим собственным ID пользователя-бота.

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

Укажите несколько токенов бота в виде списка через запятую в SLACK_BOT_TOKEN: [code] # Несколько токенов бота — по одному на рабочую область SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token

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

[/code] Или в ~/.hermes/config.yaml: [code] platforms: slack: token: "xoxb-workspace1-token,xoxb-workspace2-token"

[/code]

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

Помимо токенов в окружении или конфигурации, Hermes также загружает токены из файла OAuth-токенов по пути: [code] ~/.hermes/slack_tokens.json

[/code] Этот файл представляет собой JSON-объект, сопоставляющий ID команд с записями токенов: [code] { "T01ABC2DEF3": { "token": "xoxb-workspace-token-here", "team_name": "My Workspace" } }

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

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

  • Первый токен в списке является основным, используется для подключения Socket Mode (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. Промпт внедряется во время выполнения на каждом шаге — никогда не сохраняется в истории переписки, поэтому изменения вступают в силу немедленно. [code] slack: channel_prompts: "C01RESEARCH": | You are a research assistant. Focus on academic sources, citations, and concise synthesis. "C02ENGINEERING": | Code review mode. Be precise about edge cases and performance implications.

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

Привязки навыков по каналам​

Автоматически загружать навык при запуске новой сессии в определённом канале или ЛС. В отличие от промптов по каналам (которые внедряются на каждом шаге), привязки навыков внедряют содержимое навыка как сообщение пользователя при запуске сессии — оно становится частью истории разговора и не требует перезагрузки на последующих шагах. Это идеально подходит для ЛС или каналов с выделенной целью (флеш-карты, специализированный Q&A-бот, канал поддержки и т.д.), где вы не хотите, чтобы собственный селектор навыков модели решал, загружать ли навык при каждом коротком ответе. [code] slack: channel_skill_bindings: # ЛС — всегда работает в режиме «german-flashcards» - id: "D0ATH9TQ0G6" skills: - german-flashcards # Исследовательский канал — предзагрузка нескольких навыков по порядку - id: "C01RESEARCH" skills: - arxiv - writing-plans # Краткая форма: один навык в виде строки - id: "C02SUPPORT" skill: hubspot-on-demand

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

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

Проблема Решение
Бот не отвечает в ЛС Проверьте, что message.im есть в подписках на события, и приложение переустановлено
Бот работает в ЛС, но не в каналах Самая частая проблема. Добавьте message.channels и message.groups в подписки на события, переустановите приложение и пригласите бота в канал командой /invite @Hermes Agent
Бот не отвечает на @упоминания в каналах 1) Проверьте, что событие message.channels подписано. 2) Бот должен быть приглашён в канал. 3) Убедитесь, что добавлена область channels:history. 4) Переустановите приложение после изменений областей/событий
Бот игнорирует сообщения в приватных каналах Добавьте подписку на событие message.groups и область groups:history, затем переустановите приложение и пригласите бота /invite
«Sending messages to this app has been turned off» в ЛС Включите Messages Tab в настройках App Home (см. Шаг 5)
Ошибки «not_authed» или «invalid_auth» Перегенерируйте Bot Token и App Token, обновите .env
Бот отвечает, но не может писать в канал Пригласите бота в канал командой /invite @Hermes Agent
Бот общается, но не может читать загруженные изображения/файлы Добавьте files:read, затем переустановите приложение. Hermes теперь выводит диагностику доступа к вложениям в чате, когда Slack возвращает ошибки области/авторизации/разрешений.
Ошибка missing_scope Добавьте необходимую область в OAuth & Permissions, затем переустановите приложение
Частые отключения Socket Проверьте вашу сеть; Bolt автоматически переподключается, но нестабильные соединения вызывают задержки
Изменил области/события, но ничего не изменилось Вы должны переустановить приложение в рабочую область после любого изменения областей или подписок на события
### Быстрый чек-лист​
Если бот не работает в каналах, проверьте все следующее:
1. ✅ Событие message.channels подписано (для публичных каналов)
2. ✅ Событие message.groups подписано (для приватных каналов)
3. ✅ Событие app_mention подписано
4. ✅ Область channels:history добавлена (для публичных каналов)
5. ✅ Область groups:history добавлена (для приватных каналов)
6. ✅ Приложение переустановлено после добавления областей/событий
7. ✅ Бот приглашён в канал (/invite @Hermes Agent)
8. ✅ Вы используете @упоминание бота в своём сообщении

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

Предупреждение Всегда указывайтеSLACK_ALLOWED_USERS с Member ID авторизованных пользователей. Без этой настройки шлюз будет отклонять все сообщения по умолчанию в целях безопасности. Никогда не делитесь своими токенами бота — обращайтесь с ними как с паролями. * Токены следует хранить в ~/.hermes/.env (права на файл 600) * Периодически меняйте токены через настройки Slack-приложения * Проверяйте, кто имеет доступ к вашей директории конфигурации Hermes * Socket Mode означает, что публичный эндпоинт не открыт — одной поверхностью атаки меньше