sidebar_position: 4 title: "Slack" description: "Set up Hermes Agent as a Slack bot using Socket Mode" lang: ru

Слабая настройка

Подключите агента Hermes к Slack в качестве бота, используя режим сокета. Режим сокетов использует WebSockets вместо общедоступные конечные точки HTTP, поэтому ваш экземпляр Hermes не обязательно должен быть общедоступным — это работает за брандмауэрами, на вашем ноутбуке или на частном сервере.

:::предупреждение Классические приложения Slack устарели Классические приложения Slack (с использованием RTM API) полностью устарели в марте 2025 года. Гермес использует современную Bolt SDK с режимом сокета. Если у вас есть старое классическое приложение, вам необходимо создать новое, выполнив следующие действия. шаги ниже.

Обзор

Компонент	Значение
Библиотека	`slack-bolt` / `slack_sdk` для Python (режим сокета)
Соединение	WebSocket — общедоступный URL-адрес не требуется
Требуются токены аутентификации	Токен бота (`xoxb-`) + токен уровня приложения (`xapp-`)
Идентификация пользователя	Идентификаторы участников Slack (например, `U01ABC2DEF3`)

Шаг 1. Создайте приложение Slack

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

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

Создайте манифест: bash hermes slack manifest --write Это записывает ~/.hermes/slack-manifest.json и печатает вставку. инструкции.
Перейдите по адресу https://api.slack.com/apps → Создать новое приложение → Из манифеста приложения
Выберите рабочее пространство, вставьте содержимое JSON, проверьте его и нажмите Далее. → Создать
Перейдите к Шаг 6. Установка приложения в рабочую область. Манифест обрабатывал области видимости, события и команды косой черты для вас.

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

Перейдите по адресу https://api.slack.com/apps
Нажмите Создать новое приложение.
Выберите С нуля.
Введите название приложения (например, «Агент Гермес») и выберите рабочее пространство.
Нажмите Создать приложение.

Вы попадете на страницу Основная информация приложения. Продолжить с Шаги 2–6 ниже.

Шаг 2. Настройка областей действия токенов бота

Перейдите в раздел Функции → OAuth и разрешения на боковой панели. Прокрутите до Области действия → Области действия токенов ботов и добавьте следующее:

Область применения	Цель
`chat:write`	Отправляйте сообщения как бот
`app_mentions:read`	Обнаруживать, когда @упоминание в каналах
`channels:history`	Читать сообщения в публичных каналах, в которых находится бот
`channels:read`	Список и получение информации об общедоступных каналах
`groups:history`	Читать сообщения в приватных каналах, куда приглашен бот
`im:history`	Прочитать историю прямых сообщений
`im:read`	Просмотр основной информации DM
`im:write`	Открывайте личные сообщения и управляйте ими
`users:read`	Поиск информации о пользователе
`files:read`	Чтение и загрузка прикрепленных файлов, включая голосовые заметки/аудио
`files:write`	Загрузить файлы (изображения, аудио, документы)

:::осторожно. Отсутствующие области = отсутствующие функции. Без channels:history и groups:history бот не будет получать сообщения в каналах — это будет работать только в личных сообщениях. Без files:read Hermes может общаться в чате, но не может надежно читать вложения, загруженные пользователем. Это наиболее часто пропускаемые области. Дополнительные области действия:

Область применения	Цель
`groups:read`	Список и получение информации о частных каналах

Шаг 3. Включите режим сокета

Режим сокета позволяет боту подключаться через WebSocket вместо использования общедоступного URL-адреса.

На боковой панели выберите Настройки → Режим сокета.
Установите для параметра Включить режим сокета значение ВКЛ.
Вам будет предложено создать токен уровня приложения:
Назовите его примерно так: hermes-socket (имя не имеет значения)
Добавьте область действия connections:write. – Нажмите Создать.
Скопируйте токен — он начинается с xapp-. Это ваш SLACK_APP_TOKEN

:::совет Вы всегда можете найти или восстановить токены уровня приложения в разделе Настройки → Основная информация → Токены уровня приложения.

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

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

На боковой панели выберите Функции → Подписки на события.
Установите для параметра Включить события значение ВКЛ.
Разверните Подписаться на события ботов и добавьте:

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

Нажмите Сохранить изменения внизу страницы.

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

Шаг 5. Включите вкладку «Сообщения»

Этот шаг позволяет отправлять прямые сообщения боту. Без него пользователи увидят "Отправка сообщений в это приложение отключена" при попытке отправить боту личное сообщение.

На боковой панели выберите Функции → Главная страница приложения.
Прокрутите до пункта Показать вкладки.
Установите для параметра **Вкладка «Сообщения» значение «ВКЛ.».
Установите флажок Разрешить пользователям отправлять слэш-команды и сообщения с вкладки сообщений.

🚨 Danger

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

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

На боковой панели выберите Настройки → Установить приложение.
Нажмите Установить в рабочую область.
Проверьте разрешения и нажмите Разрешить.
После авторизации вы увидите Токен OAuth пользователя бота, начинающийся с xoxb-.
Скопируйте этот токен — это ваш SLACK_BOT_TOKEN.

:::совет Если вы позже измените области действия или подписки на события, вам необходимо переустановить приложение для внесения изменений. чтобы вступило в силу. На странице установки приложения появится баннер с предложением сделать это.

Шаг 7. Найдите идентификаторы пользователей для белого списка

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

Чтобы найти идентификатор участника:

В Slack щелкните имя пользователя или аватар.
Нажмите Просмотреть полный профиль.
Нажмите кнопку ⋮ (подробнее).
Выберите Копировать идентификатор участника.

Идентификаторы участников выглядят как U01ABC2DEF3. Вам нужен как минимум собственный идентификатор участника.

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

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

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3              # Comma-separated Member IDs

# Optional
SLACK_HOME_CHANNEL=C01234567890              # Default channel for cron/scheduled messages
SLACK_HOME_CHANNEL_NAME=general              # Human-readable name for the home channel (optional)

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

hermes gateway setup    # Select Slack when prompted

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

hermes gateway              # Foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

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

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

/invite @Hermes Agent

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

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

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

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

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

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

hermes slack manifest --write

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

Legacy `/hermes <subcommand>` все еще работает

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

Дополнительно: выдавать только массив слэш-команд

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

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

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

Как реагирует бот

Понимание того, как Гермес ведет себя в разных контекстах:

Контекст	Поведение
DM	Бот отвечает на каждое сообщение — @упоминание не требуется
Каналы	Бот отвечает только при @упоминании (например, `@Hermes Agent what time is it?`). В каналах Гермес отвечает в ветке, прикрепленной к этому сообщению.
Темы	Если вы @упомяните Гермеса в существующей теме, он ответит в той же теме. Как только у бота появится активный сеанс в ветке, последующие ответы в этой ветке не требуют @mention — бот естественным образом следит за беседой.

:::совет В каналах всегда @упоминайте бота, чтобы начать разговор. Как только бот станет активным в теме, вы сможете ответить в этой теме, не упоминая его. Вне потоков сообщения без @mention игнорируются, чтобы предотвратить шум в занятых каналах.

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

Помимо обязательных переменных среды из шага 8, вы можете настроить поведение бота Slack с помощью ~/.hermes/config.yaml.

Поведение темы и ответа

platforms:
  slack:
    # Controls how multi-part responses are threaded
    # "off"   — never thread replies to the original message
    # "first" — first chunk threads to user's message (default)
    # "all"   — all chunks thread to user's message
    reply_to_mode: "first"

    extra:
      # Whether to reply in a thread (default: true).
      # When false, channel messages get direct channel replies instead
      # of threads. Messages inside existing threads still reply in-thread.
      reply_in_thread: true

      # Also post thread replies to the main channel
      # (Slack's "Also send to channel" feature).
      # Only the first chunk of the first reply is broadcast.
      reply_broadcast: false

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

Изоляция сеанса

# Global setting — applies to Slack and all other platforms
group_sessions_per_user: true

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

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

Упоминание и триггерное поведение

slack:
  # Require @mention in channels (this is the default behavior;
  # the Slack adapter enforces @mention gating in channels regardless,
  # but you can set this explicitly for consistency with other platforms)
  require_mention: true

  # Prevent thread auto-engagement: only reply to channel messages that
  # contain an explicit @mention. With this OFF (default), Slack can
  # "auto-engage" — remembering past mentions in a thread and following
  # up on bot-message replies, and resuming active sessions without a
  # fresh mention. With strict_mention ON, every new channel message
  # must @mention the bot before Hermes will respond.
  strict_mention: false

  # Custom mention patterns that trigger the bot
  # (in addition to the default @mention detection)
  mention_patterns:
    - "hey hermes"
    - "hermes,"

  # Text prepended to every outgoing message
  reply_prefix: ""

💡 Tip

Когда использовать `strict_mention` Установите для этого параметра значение `true` в загруженных рабочих пространствах, где поведение Slack по умолчанию «бот запоминает эту ветку» удивляет пользователей — например, длинная ветка технической поддержки, в которой бот помогал с самого начала, и вы бы предпочли, чтобы он молчал, пока явно не будет отправлен повторный запрос. DM и активные интерактивные сеансы не затрагиваются.

:::информация Slack поддерживает оба шаблона: @mention требуется для начала разговора по умолчанию, но вы можете отключить определенные каналы через SLACK_FREE_RESPONSE_CHANNELS (идентификаторы каналов, разделенные запятыми) или slack.free_response_channels в config.yaml. Если у бота есть активный сеанс в потоке, последующие ответы в потоке не требуют упоминания. В личных сообщениях бот всегда отвечает без упоминания.

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

slack:
  # What happens when an unauthorized user (not in SLACK_ALLOWED_USERS) DMs the bot
  # "pair"   — prompt them for a pairing code (default)
  # "ignore" — silently drop the message
  unauthorized_dm_behavior: "pair"

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

unauthorized_dm_behavior: "pair"

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

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

# Global setting — enable/disable automatic transcription of incoming voice messages
stt_enabled: true

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

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

# Global gateway settings
group_sessions_per_user: true
unauthorized_dm_behavior: "pair"
stt_enabled: true

# Slack-specific settings
slack:
  require_mention: true
  unauthorized_dm_behavior: "pair"

# Platform config
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

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

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

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

SLACK_HOME_CHANNEL=C01234567890

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

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

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

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

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

# Multiple bot tokens — one per workspace
SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token

# A single app-level token is still used for 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": |
      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.

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

Привязки навыков для каждого канала

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

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

slack:
  channel_skill_bindings:
    # DM channel — always runs in "german-flashcards" mode
    - id: "D0ATH9TQ0G6"
      skills:
        - german-flashcards
    # Research channel — preload multiple skills in order
    - id: "C01RESEARCH"
      skills:
        - arxiv
        - writing-plans
    # Short form: single skill as a string
    - id: "C02SUPPORT"
      skill: hubspot-on-demand

Примечания: - Привязка соответствует идентификатору канала. Для связанных сообщений в связанном канале поток наследует привязку родительского канала. - Навык загружается только при запуске сессии (новая сессия или после автосброса). Если вы измените привязку, запустите /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` бот
«Отправка сообщений в это приложение отключена» в личных сообщениях	Включите вкладку Сообщения в настройках App Home (см. шаг 5)
Ошибки «not_authed» или «invalid_auth»	Восстановите свой токен бота и токен приложения, обновите `.env`
Бот отвечает, но не может опубликовать сообщение в канале	Пригласить бота на канал с помощью `/invite @Hermes Agent`
Бот может общаться, но не может читать загруженные изображения/файлы	Добавьте `files:read`, затем переустановите приложение. Hermes теперь отображает диагностику доступа к вложениям в чате, когда Slack возвращает ошибки области/авторизации/разрешения.
`missing_scope` ошибка	Добавьте необходимую область в OAuth & Permissions, затем переустановите приложение
Розетка часто отключается	Проверьте свою сеть; Bolt автоматически переподключается, но нестабильные соединения вызывают задержку
Изменены области/события, но ничего не изменилось	Вы необходимо переустановить приложение в своем рабочем пространстве после любого изменения объема или подписки на событие

Быстрый контрольный список

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

✅ Подписано событие message.channels (для публичных каналов)
✅ Подписано событие message.groups (для частных каналов)
✅ на мероприятие app_mention оформлена подписка
✅ Добавлена область действия channels:history (для публичных каналов)
✅ Добавлена область действия groups:history (для частных каналов)
✅ Приложение было переустановлено после добавления областей/событий.
✅ Бот приглашен на канал (/invite @Hermes Agent)
✅ Вы @упоминаете бота в своем сообщении.

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

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