Перейти к основному содержимому

Настройка Slack

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

Классические Slack-приложения устарели

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

Обзор​

КомпонентЗначение
Библиотекаslack-bolt / slack_sdk для Python (Socket Mode)
ПодключениеWebSocket — публичный URL не требуется
Необходимые токены аутентификацииBot Token (xoxb-) + App-Level Token (xapp-)
Идентификация пользователейSlack Member IDs (например, U01ABC2DEF3)

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

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

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

  1. Сгенерируйте манифест:
    vibeos slack manifest --write
    Эта команда записывает ~/.vibeos/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. Введите имя приложения (например, «VibeOS») и выберите вашу рабочую область
  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 VibeOS может общаться, но не сможет надёжно читать загруженные пользователем вложения. Это наиболее часто пропускаемые разрешения.

Необязательные разрешения:

РазрешениеНазначение
groups:readПросмотр списка и информации о приватных каналах

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

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

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

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


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

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

  1. На боковой панели перейдите в Features → Event Subscriptions
  2. Переключите Enable Events в положение ON
  3. Разверните Subscribe to bot events и добавьте:
СобытиеОбязательно?Назначение
message.imДаБот получает личные сообщения
message.channelsДаБот получает сообщения в публичных каналах, куда он добавлен
message.groupsРекомендуетсяБот получает сообщения в приватных каналах, куда он приглашён
app_mentionДаПредотвращает ошибки Bolt SDK при упоминании бота через @
  1. Нажмите Save Changes внизу страницы
Отсутствие подписок на события — проблема №1 при настройке

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


Шаг 5: Включите вкладку Messages​

Этот шаг включает личные сообщения боту. Без него пользователи видят сообщение «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»
Без этого шага личные сообщения полностью заблокированы

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


Шаг 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 пользователей для белого списка​

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

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

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

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


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

Добавьте следующее в ваш файл ~/.vibeos/.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 # Человекочитаемое имя для домашнего канала (необязательно)

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

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

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

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

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

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

/invite @VibeOS

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


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

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

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

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

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

vibeos slack manifest --write

Затем в Slack:

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

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

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

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

Сам Slack блокирует родные слеш-команды внутри ответов в тредах — попробуйте /queue в треде, и Slack ответит «/queue is not supported in threads. Sorry!» Нет никакой настройки на стороне приложения, которая бы их включила; Slack никогда не доставляет их VibeOS.

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

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

Запросы на подтверждение (опасная команда / подтверждение execute_code) обычно отображаются в виде интерактивных кнопок. Когда кнопки не могут быть доставлены и VibeOS переключается на текстовый запрос, он предлагает вам ответить !approve / !deny — форма, которая работает внутри тредов.

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

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

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

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


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

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

КонтекстПоведение
Личные сообщенияБот отвечает на каждое сообщение — упоминание @ не требуется
КаналыБот отвечает только при упоминании через @ (например, @VibeOS what time is it?). В каналах VibeOS отвечает в треде, прикреплённом к этому сообщению.
ТредыЕсли вы упомянули VibeOS через @ внутри существующего треда, он отвечает в том же треде. Как только у бота есть активная сессия в треде, последующие ответы в этом треде не требуют упоминания @ — бот естественным образом продолжает разговор.
подсказка

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


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

Помимо обязательных переменных окружения из Шага 8, вы можете настроить поведение Slack-бота через ~/.vibeos/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
КлючПо умолчаниюОписание
platforms.slack.reply_to_mode"first"Режим тредов для многокомпонентных сообщений: "off", "first" или "all"
platforms.slack.extra.reply_in_threadtrueЕсли false, сообщения в канале получают прямые ответы вместо тредов. Сообщения внутри существующих тредов всё равно отвечают в треде.
platforms.slack.extra.reply_broadcastfalseЕсли true, ответы в тредах также публикуются в основной канал. Только первый фрагмент транслируется.

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

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

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

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

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

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

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

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

# Текст, добавляемый перед каждым исходящим сообщением
reply_prefix: ""
Когда использовать strict_mention

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

к сведению

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

Белый список каналов (allowed_channels)​

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

Личные сообщения освобождены от этого фильтра, поэтому авторизованные пользователи всегда могут связаться с ботом в личном сообщении.

slack:
allowed_channels:
- "C0123456789" # #ops
- "C0987654321" # #incident-response

Или через переменную окружения (через запятую):

SLACK_ALLOWED_CHANNELS="C0123456789,C0987654321"

Поведение:

  • Пусто / не установлено → без ограничений (полная обратная совместимость).
  • Не пусто → ID канала должен быть в списке, иначе сообщение отбрасывается до любой другой проверки (требование упоминания, free_response_channels и т.д.).
  • ID каналов Slack начинаются с C (публичные), G (приватные) или D (личные сообщения). Найдите их через интерфейс Slack: «Open channel details» → панель «About» или через API.

См. также: разделение команд администратора/пользователя.

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

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 канала, куда VibeOS будет доставлять запланированные сообщения, результаты cron-задач и другие проактивные уведомления. Чтобы найти ID канала:

  1. Щёлкните правой кнопкой мыши по названию канала в Slack
  2. Нажмите View channel details
  3. Прокрутите вниз — ID канала отображается там
SLACK_HOME_CHANNEL=C01234567890

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


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

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

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

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

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

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

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

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

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

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

~/.vibeos/slack_tokens.json

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

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

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

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

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

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

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

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

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

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

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

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

Привязки навыков для конкретных каналов​

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

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

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 для тона/ограничений на уровне канала поверх инструкций навыка.

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

ПроблемаРешение
Бот не отвечает в личных сообщенияхПроверьте, что message.im есть в подписках на события, и приложение переустановлено
Бот работает в личных сообщениях, но не в каналахСамая частая проблема. Добавьте message.channels и message.groups в подписки на события, переустановите приложение и пригласите бота в канал через /invite @VibeOS
Бот не отвечает на @упоминания в каналах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 @VibeOS
Бот может общаться, но не может читать загруженные изображения/файлыДобавьте files:read, затем переустановите приложение. VibeOS теперь отображает диагностику доступа к вложениям в чате, когда 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 @VibeOS)
  8. ✅ Вы упоминаете бота через @ в вашем сообщении

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

предупреждение

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

  • Токены должны храниться в ~/.vibeos/.env (права доступа к файлу 600)
  • Периоди