Настроить интеграцию Slack

В этом руководстве описано, как подключить Slack к рабочему пространству Control Center — либо позволив Control Center создать приложение, либо собрав его самостоятельно.

Для первого запуска под руководством см. Подключите Slack к рабочему пространству.

Предварительные требования

Роль owner или admin в рабочем пространстве Control Center — подключение приложения чата меняет настройки рабочего пространства
Право создавать и устанавливать приложения в рабочем пространстве Slack
Ничего доступного публично: соединение исходящее (Socket Mode), поэтому серверу не нужны входящий порт, туннель или домен

Три способа получить приложение

Способ	Что предоставляете вы	Что делает Control Center
Под руководством	Токен конфигурации приложения (`xoxe-…`)	Создаёт приложение с нужными разрешениями, событиями, Socket Mode и слэш-командой; передаёт вам два шага, для которых у Slack нет API
Создать в Slack	Ничего	Открывает Slack с той же конфигурацией, уже заполненной; вы выбираете рабочее пространство и подтверждаете
Вручную	Токены готового приложения	Проверяет их и подключает

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

Кнопки «установить приложение Slack от Control Center» намеренно нет. Установка распределённого приложения Slack требует общего клиентского секрета (в Slack нет PKCE), а Socket Mode распределяет события приложения случайным образом между его соединениями — поэтому одно общее приложение доставляло бы сообщения вашего рабочего пространства на серверы других людей. Так что каждое рабочее пространство владеет собственным приложением, а эти три пути — о том, как мало работы это от вас требует.

Вариант A: позволить Control Center создать приложение

Создайте пару токенов конфигурации приложения на api.slack.com/apps и скопируйте токен обновления (xoxe-…)
В Control Center перейдите в Настройки → Рабочее пространство → Основные и прокрутите до карточки Чат-мосты
В блоке Slack нажмите Создать приложение за меня
Вставьте токен, настройте имя приложения, имя бота, описания и слэш-команду, затем нажмите Создать приложение
Выполните два оставшихся шага, которые показывает диалог, — каждый в виде ссылки в Slack:
- Basic Information → App-Level Tokens: создайте токен с разрешением connections:write (xapp-…)
- Install App: установите в рабочее пространство и скопируйте Bot User OAuth Token (xoxb-…)
Нажмите Вставить учётные данные и продолжите с раздела Подключение

Токен конфигурации обновляется при каждом использовании. Control Center сохраняет обновлённое значение по ходу дела, поэтому вставлять его снова не придётся.

Вариант B: создать приложение в Slack, с заполненной конфигурацией

То же приложение, без токена конфигурации — Slack открывает собственный экран создания со всем манифестом, уже заполненным.

В Control Center перейдите в Настройки → Рабочее пространство → Основные и прокрутите до карточки Чат-мосты
В блоке Slack нажмите Создать приложение за меня
Настройте имя приложения, имя бота, описания и слэш-команду — они передаются вместе со ссылкой
Нажмите Создать в Slack. Браузер откроет страницу создания приложения Slack с уже заполненной конфигурацией
Выберите рабочее пространство Slack и подтвердите. Разрешения, события, Socket Mode и слэш-команда уже верны
Вернувшись в Control Center, выполните два оставшихся шага, которые показывает диалог:
- Basic Information → App-Level Tokens: создайте токен с разрешением connections:write (xapp-…)
- Install App: установите в рабочее пространство и скопируйте Bot User OAuth Token (xoxb-…)
Нажмите Вставить учётные данные и продолжите с раздела Подключение

Slack не сообщает, какое приложение он создал, поэтому Control Center не узнаёт идентификатор приложения, и ссылки на шаге 6 ведут к списку ваших приложений, а не прямо к этому приложению. Для Настроить бота нужен токен конфигурации.

Вариант C: собрать приложение самостоятельно

Создайте приложение на api.slack.com/apps, затем настройте его следующим образом.

Socket Mode: включите его и оставьте пустыми все request URL. Slack отклоняет манифест, который запрашивает одновременно Socket Mode и доставку через вебхуки.

Разрешения токена бота (OAuth & Permissions):

app_mentions:read
assistant:write
channels:history
chat:write
commands
groups:history
im:history
users:read
users:read.email

Подписки на события (события бота):

app_home_opened
app_mention
message.channels
message.groups
message.im

Именно message.channels и message.groups обеспечивают работу ответов внутри уже подключённого треда Slack. Без них доходит только первое упоминание.

Слэш-команда: /cc (подойдёт любое имя — мост использует ту команду, которой его вызвали последней).

App Home: включите вкладку Messages и оставьте её доступной для записи, чтобы участники могли писать боту в личные сообщения.

Токены: создайте токен уровня приложения с разрешением connections:write, затем установите приложение и скопируйте токен OAuth пользователя-бота.

Подключение

Перейдите в Настройки → Рабочее пространство → Основные и прокрутите до карточки Чат-мосты
В блоке Slack нажмите Подключить Slack
Заполните поля:

Поле	Значение	Где это находится в Slack
Токен OAuth пользователя-бота	`xoxb-…`	OAuth & Permissions → Bot User OAuth Token
Токен уровня приложения	`xapp-…`	Basic Information → App-Level Tokens (`connections:write`)
Токен обновления конфигурации приложения (необязательно)	`xoxe-…`	Пара токенов конфигурации приложения на api.slack.com/apps

Префикс каждого значения проверяется с обеих сторон до того, как что-либо отправится, поэтому значение, вставленное не в то поле, отклоняется в любом случае с одной и той же фразой.

Нажмите Подключить

Control Center проверяет токен бота через auth.test Slack перед тем, как что-либо сохранить, поэтому опечатка сообщается вам, а не превращается в сокет, который тихо никогда не работает. Токен уровня приложения можно подтвердить только открытием сокета, поэтому неверный токен проявляется мгновением позже как ошибка подключения в той же строке.

Без необязательного токена конфигурации приложения соединение работает нормально — вы просто не можете редактировать бота из Control Center.

Что делает подключение

Сохраняет учётные данные в собственном каталоге рабочего пространства, рядом с его базой данных, с доступом только для владельца. Они никогда не возвращаются обратно клиенту
Открывает для этого рабочего пространства одно соединение Socket Mode и начинает получать упоминания, ответы в тредах Slack, личные сообщения и слэш-команды
Заново подготавливает каждый ранее подключённый тред Slack, поэтому переподключение продолжает существующие разговоры, а не оставляет их
Ничего не стоит для рабочих пространств без приложения чата: ни сокета, ни таймеров, ни трафика

Учётные данные бота — это один обычный JSON-файл на провайдера в <dataDir>/<workspaceId>/chat_credentials/, записываемый атомарно и с доступом только для владельца. Это сделано намеренно, а не по недосмотру: удаление рабочего пространства отвязывает этот каталог, так что его токены уходят вместе с ним, а workspace.export и резервные копии копируют workspace.db — не каталог — поэтому рабочее пространство, которое вы передаёте кому-то другому, никогда не несёт внутри действующие токены бота. Следствие: восстановление рабочего пространства в другом месте означает, что Slack там нужно подключить заново.

Доступ к мосту определяется членством в рабочем пространстве, а не владением токеном. Аккаунт Slack должен быть привязан к пользователю Control Center, который состоит в рабочем пространстве с ролью, дающей право записи. Подключение, отключение, настройка под руководством, ссылка настройки и настройка бота — всё это доступно только администраторам.

Проверка

В строке Slack отображается тег состояния: Онлайн, Подключение…, Ошибка подключения (рядом — собственная ошибка Slack) или Не подключено. Чтобы проверить всё целиком:

В Slack пригласите бота в канал: /invite @your-bot-name
Упомяните его с запросом
В треде Slack появляется ответ, а в Control Center — соответствующее пространство

Затем каждый участник, который хочет пользоваться мостом, привязывает свой аккаунт — см. Привязать аккаунт Slack.

Как выглядит ответ в Slack

Над словами, передаваемыми потоком, находится одна сгруппированная карточка со строкой на каждый шаг. Подготовка — это одна строка, заголовок которой меняется с Working on it… на Cloning …, а затем на Starting the agent…. Рассуждение добавляет строку Thinking…; когда этот шаг завершается, на ней может появиться короткая мысль. Каждый инструмент — отдельная строка (Read lib/main.dart). Ответ приходит как обычный текст под карточкой. Карточка становится завершённой, когда заканчивается ход, и ошибочной, когда запуск упал, был прерван или достиг предела ходов.

Карточка появляется в тот момент, когда бот принимает упоминание — Working on it… —, так что тред Slack не молчит, пока рабочее пространство ещё собирается. Ваше первое упоминание в канале Slack создаёт разговор, а тот клонирует репозитории, в которых работает агент, поэтому строка подготовки затем показывает Cloning acme/widgets…, потом Setting up Reviewer…, потом Starting the agent…, а затем строку Thinking…, как только агент действительно начинает рассуждать. В большом репозитории первая подготовка занимает время; карточка — это то, по чему видно, что он работает, а не игнорирует вас. Последующие упоминания в том же треде Slack всё ещё начинаются с Working on it…, а затем пропускают шаги клонирования, потому что рабочее пространство уже на месте.

Рассуждения в виде стены текста и вывод инструментов никогда не покидают Control Center — мысль в строке Thinking… это короткая строка, а не транскрипт. View in Control Center на карточке открывает полный разговор в приложении для компьютера — ссылка ведёт на ваш собственный сервер Control Center, который передаёт браузер приложению.

Если по нажатию ничего не происходит, значит сервер, отправивший сообщение, недоступен с машины, на которой вы нажали (например, сервер только с loopback-адресом, открытый с телефона), или Control Center там не запущен. Сервер без доступного адреса отправляет карточку без кнопки, а не кнопку, которая никуда не ведёт.

Обновить токен

Вставьте новое значение в диалоге подключения и нажмите Подключить. Подключение заменяет то соединение, что работало для этого рабочего пространства, поэтому сокет переустанавливается с новыми учётными данными.

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

Отключение

Нажмите Отключить в строке Slack (только для администраторов). Сокет закрывается, а учётные данные забываются.

Связи с пространствами и пользователями намеренно сохраняются: повторное подключение того же приложения восстанавливает все подключённые треды Slack. Это строки уровня рабочего пространства, поэтому удаление рабочего пространства всё равно их убирает.

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

В строке указано «Ошибка подключения»

Прочитайте ошибку рядом с тегом. Отклонённые учётные данные (invalid_auth, not_authed, token_revoked, account_inactive) — это окончательная ошибка: мост перестаёт повторять попытки и ждёт новых токенов, потому что бесконечные повторы с отозванным токеном лишь упираются в ограничение частоты. Вставьте токены заново в диалоге подключения.

Ошибка missing_scope означает, что приложение установлено с меньшим набором разрешений, чем нужно мосту. Добавьте недостающее разрешение, переустановите приложение в Slack, затем подключитесь заново.

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

Бот не отвечает на упоминание

Бот в канале? Slack доставляет сообщения канала только приложениям, которые являются его участниками. Выполните /invite @your-bot-name
Ваш аккаунт привязан? Непривязанный участник получает в этом треде Slack ответ с объяснением, как привязаться. См. Привязать аккаунт Slack
Вы участник рабочего пространства с ролью, дающей право записи? Участникам с viewer или guest сообщают, что их роль доступна только для чтения. Мост никогда не начинает работу от имени того, кому не может её приписать
В рабочем пространстве есть агенты? Если агентов нет, сообщение сохраняется, но отвечать на него некому

Отвечает в канале, но игнорирует обычные сообщения

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

Ответы приходят одним большим сообщением вместо потоковой передачи

В строке указано: «Потоковая передача для этого приложения Slack выключена — ответы приходят одним сообщением». Потоковые ответы Slack требуют функции Agents & AI Apps на платном тарифе; когда Slack отказывает, мост перестаёт запрашивать её до конца жизни этого соединения и вместо этого публикует ответы целиком. Ничего не теряется — полный транскрипт всегда есть в Control Center.

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

У ответа нет карточки над ним

Карточки задач Slack — часть той же новой поверхности Agents & AI Apps, что и потоковая передача, и Slack отказывает только во время вызова. Когда это происходит, Control Center сохраняет ответ и отбрасывает карточку до конца жизни этого соединения — ответ без строки состояния лучше строки состояния без ответа.

«Чтобы изменить бота, Control Center нужен токен конфигурации приложения»

Строка Настроить бота недоступна, потому что у подключения нет токена конфигурации приложения. Это ожидаемо для приложения, созданного вручную или через Создать в Slack: Slack так и не сообщил Control Center, что это за приложение. Создайте пару токенов на api.slack.com/apps и подключитесь заново, указав токен обновления.

Длинный ответ обрывается

Slack ограничивает одно сообщение 40 000 символами, поэтому мост обрезает на 39 000 и добавляет указатель на Control Center — сокращённый ответ лучше того, который Slack отклонит целиком. Полный текст всегда есть в транскрипте пространства.

Связанные руководства

Связанные понятия

Чат-мосты