Настройка Slack
Подключите VibeOS к Slack в качестве бота через Socket Mode. Socket Mode использует WebSocket вместо публичных HTTP-эндпоинтов, поэтому вашему экземпляру VibeOS не нужен публичный доступ — он работает за файрволами, на вашем ноутбуке или на частном сервере.
Классические 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 (рекомендуется)
- Сгенерируйте манифест:
Эта команда записывает
vibeos slack manifest --write~/.vibeos/slack-manifest.jsonи выводит инструкции по вставке. - Перейдите на https://api.slack.com/apps → Create New App → From an app manifest
- Выберите вашу рабочую область, вставьте содержимое JSON, проверьте, нажмите Next → Create
- Переходите сразу к Шагу 6: Установка приложения в рабочую область. Манифест уже настроил разрешения, события и слеш-команды.
Вариант B: С нуля (вручную)
- Перейдите на https://api.slack.com/apps
- Нажмите Create New App
- Выберите From scratch
- Введите имя приложения (например, «VibeOS») и выберите вашу рабочую область
- Нажмите 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.
- На боковой панели перейдите в Settings → Socket Mode
- Переключите Enable Socket Mode в положение ON
- Вам будет предложено создать App-Level Token:
- Назовите его, например,
vibeos-socket(название не имеет значения) - Добавьте разрешение
connections:write - Нажмите Generate
- Назовите его, например,
- Скопируйте токен — он начинается с
xapp-. Это вашSLACK_APP_TOKEN
Вы всегда можете найти или перегенерировать токены уровня приложения в Settings → Basic Information → App-Level Tokens.
Шаг 4: Подпишитесь на события
Этот шаг критически важен — он определяет, какие сообщения может видеть бот.
- На боковой панели перейдите в Features → Event Subscriptions
- Переключите Enable Events в положение ON
- Разверните Subscribe to bot events и добавьте:
| Событие | Обязательно? | Назначение |
|---|---|---|
message.im | Да | Бот получает личные сообщения |
message.channels | Да | Бот получает сообщения в публичных каналах, куда он добавлен |
message.groups | Рекомендуется | Бот получает сообщения в приватных каналах, куда он приглашён |
app_mention | Да | Предотвращает ошибки Bolt SDK при упоминании бота через @ |
- Нажмите Save Changes внизу страницы
Если бот работает в личных сообщениях, но не в каналах, вы почти наверняка забыли добавить
message.channels (для публичных каналов) и/или message.groups (для приватных каналов).
Без этих событий Slack просто не доставляет сообщения из каналов боту.
Шаг 5: Включите вкладку Messages
Этот шаг включает личные сообщения боту. Без него пользователи видят сообщение «Sending messages to this app has been turned off» при попытке написать боту в личку.
- На боковой панели перейдите в Features → App Home
- Прокрутите до Show Tabs
- Переключите Messages Tab в положение ON
- Отметьте «Allow users to send Slash commands and messages from the messages tab»
Даже со всеми правильными разрешениями и подписками на события Slack не позволит пользователям отправлять личные сообщения боту, пока не включена вкладка Messages. Это требование платформы Slack, а не проблема конфигурации VibeOS.
Шаг 6: Установите приложение в рабочую область
- На боковой панели перейдите в Settings → Install App
- Нажмите Install to Workspace
- Проверьте разрешения и нажмите Allow
- После авторизации вы увидите Bot User OAuth Token, начинающийся с
xoxb- - Скопируйте этот токен — это ваш
SLACK_BOT_TOKEN
Если вы позже измените разрешения или подписки на события, вы должны переустановить приложение, чтобы изменения вступили в силу. Страница Install App покажет баннер с предложением сделать это.
Шаг 7: Найдите ID пользователей для белого списка
VibeOS использует Slack Member IDs (не имена пользователей или отображаемые имена) для белого списка.
Чтобы найти Member ID:
- В Slack нажмите на имя пользователя или аватар
- Нажмите View full profile
- Нажмите кнопку ⋮ (ещё)
- Выберите 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:
- Откройте https://api.slack.com/apps → ваше приложение VibeOS
- Features → App Manifest → Edit
- Вставьте новое содержимое
~/.vibeos/slack-manifest.json - 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_thread | true | Если false, сообщения в канале получают прямые ответы вместо тредов. Сообщения внутри существующих тредов всё равно отвечают в треде. |
platforms.slack.extra.reply_broadcast | false | Если 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 канала:
- Щёлкните правой кнопкой мыши по названию канала в Slack
- Нажмите View channel details
- Прокрутите вниз — 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 автоматически переподключается, но нестабильные соединения вызывают задержки |
| Изменил разрешения/события, но ничего не изменилось | Вы должны переустановить приложение в вашу рабочую область после любого изменения разрешений или подписок на события |
Быстрый чек-лист
Если бот не работает в каналах, проверьте всё следующее:
- ✅ Событие
message.channelsподписано (для публичных каналов) - ✅ Событие
message.groupsподписано (для приватных каналов) - ✅ Событие
app_mentionподписано - ✅ Разрешение
channels:historyдобавлено (для публичных каналов) - ✅ Разрешение
groups:historyдобавлено (для приватных каналов) - ✅ Приложение переустановлено после добавления разрешений/событий
- ✅ Бот приглашён в канал (
/invite @VibeOS) - ✅ Вы упоминаете бота через @ в вашем сообщении
Безопасность
Всегда устанавливайте SLACK_ALLOWED_USERS с Member IDs авторизованных пользователей. Без этой настройки
шлюз будет отклонять все сообщения по умолчанию в целях безопасности. Никогда не делитесь своими токенами бота —
относитесь к ним как к паролям.
- Токены должны храниться в
~/.vibeos/.env(права доступа к файлу600) - Периоди