Skonfiguruj integrację Slack

Ten poradnik pokazuje, jak połączyć Slacka z obszarem roboczym Control Center — albo pozwalając Control Center utworzyć aplikację, albo budując ją samodzielnie.

Aby przejść przez pierwsze uruchomienie z przewodnikiem, zobacz Połącz Slack z obszarem roboczym.

Wymagania wstępne

Rola owner lub admin w obszarze roboczym Control Center — połączenie aplikacji czatu zmienia ustawienia obszaru roboczego
Uprawnienie do tworzenia i instalowania aplikacji w obszarze roboczym Slack
Nic nie musi być publicznie osiągalne: połączenie jest wychodzące (Socket Mode), więc serwer nie potrzebuje portu przychodzącego, tunelu ani domeny

Trzy sposoby na uzyskanie aplikacji

Ścieżka	Co dostarczasz	Co robi Control Center
Z przewodnikiem	Token konfiguracji aplikacji (`xoxe-…`)	Tworzy aplikację z właściwymi zakresami, zdarzeniami, Socket Mode i poleceniem z ukośnikiem; przekazuje Ci dwa kroki, dla których Slack nie ma API
Utwórz w Slack	Nic	Otwiera Slacka z tą samą konfiguracją wypełnioną wstępnie; wybierasz obszar roboczy i potwierdzasz
Ręcznie	Tokeny gotowej aplikacji	Weryfikuje je i łączy

Tylko ścieżka z przewodnikiem pozostawia dodatkowo aplikację zarządzalną z poziomu Control Center, i to ona umożliwia Dostosuj bota czatu. Aplikację utworzoną przez Utwórz w Slack można później awansować do zarządzanej, wklejając token konfiguracji w oknie połączenia.

Celowo nie ma przycisku „zainstaluj aplikację Slack Control Center”. Zainstalowanie rozproszonej aplikacji Slack wymaga współdzielonego sekretu klienta (Slack nie ma PKCE), a Socket Mode rozdziela zdarzenia aplikacji losowo między jej połączenia — jedna wspólna aplikacja dostarczałaby więc wiadomości z Twojego obszaru roboczego na serwery innych osób. Każdy obszar roboczy ma zatem własną aplikację, a te trzy ścieżki dotyczą tego, jak niewiele pracy Cię to kosztuje.

Opcja A: pozwól Control Center utworzyć aplikację

Wygeneruj parę tokenów konfiguracji aplikacji na api.slack.com/apps i skopiuj token odświeżania (xoxe-…)
W Control Center przejdź do Ustawienia → Obszar roboczy → Ogólne i przewiń do karty Mostki czatu
W bloku Slack kliknij Utwórz aplikację za mnie
Wklej token, dostosuj nazwę aplikacji, nazwę bota, opisy i polecenie z ukośnikiem, a następnie kliknij Utwórz aplikację
Wykonaj dwa pozostałe kroki pokazane w oknie, każdy jako link do Slacka:
- Basic Information → App-Level Tokens: wygeneruj token z zakresem connections:write (xapp-…)
- Install App: zainstaluj aplikację w obszarze roboczym i skopiuj Bot User OAuth Token (xoxb-…)
Kliknij Wklej dane uwierzytelniające i przejdź dalej z sekcją Połącz

Token konfiguracji rotuje przy każdym użyciu. Control Center zapisuje zrotowaną wartość na bieżąco, więc nigdy nie musisz wklejać go ponownie.

Opcja B: utwórz ją w Slacku, wypełnioną wstępnie

Ta sama aplikacja, bez tokenu konfiguracji — Slack otwiera własny ekran tworzenia z całym manifestem już wypełnionym.

W Control Center przejdź do Ustawienia → Obszar roboczy → Ogólne i przewiń do karty Mostki czatu
W bloku Slack kliknij Utwórz aplikację za mnie
Dostosuj nazwę aplikacji, nazwę bota, opisy i polecenie z ukośnikiem — te ustawienia podróżują z linkiem
Kliknij Utwórz w Slack. Przeglądarka otworzy stronę tworzenia aplikacji w Slacku z wypełnioną wstępnie konfiguracją
Wybierz obszar roboczy Slack i potwierdź. Zakresy, zdarzenia, Socket Mode i polecenie z ukośnikiem są już poprawne
Z powrotem w Control Center wykonaj dwa pozostałe kroki pokazane w oknie:
- Basic Information → App-Level Tokens: wygeneruj token z zakresem connections:write (xapp-…)
- Install App: zainstaluj aplikację w obszarze roboczym i skopiuj Bot User OAuth Token (xoxb-…)
Kliknij Wklej dane uwierzytelniające i przejdź dalej z sekcją Połącz

Slack nie zgłasza, którą aplikację utworzył, więc Control Center nie poznaje identyfikatora aplikacji, a linki w kroku 6 prowadzą do Twojej listy aplikacji, a nie bezpośrednio do niej. Dostosuj bota wymaga tokenu konfiguracji.

Opcja C: zbuduj aplikację samodzielnie

Utwórz aplikację na api.slack.com/apps, a następnie skonfiguruj ją w poniższy sposób.

Socket Mode: włącz go i pozostaw każdy Request URL pusty. Slack odrzuca manifest, który wymaga jednocześnie Socket Mode i dostarczania przez webhooki.

Zakresy tokenu bota (OAuth & Permissions):

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

Subskrypcje zdarzeń (zdarzenia bota):

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels i message.groups sprawiają, że odpowiedź w już podłączonym wątku Slacka działa. Bez nich dotrze wyłącznie pierwsza wzmianka.

Polecenie z ukośnikiem: /cc (każda nazwa działa — most używa tego polecenia, którym został ostatnio wywołany).

App Home: włącz kartę Messages i pozostaw ją do zapisu, aby członkowie mogli wysyłać botowi wiadomości prywatne.

Tokeny: wygeneruj token na poziomie aplikacji z zakresem connections:write, następnie zainstaluj aplikację i skopiuj token OAuth użytkownika bota.

Połącz

Przejdź do Ustawienia → Obszar roboczy → Ogólne i przewiń do karty Mostki czatu
W bloku Slack kliknij Połącz Slack
Wypełnij pola:

Pole	Wartość	Gdzie to jest w Slacku
Token OAuth użytkownika bota	`xoxb-…`	OAuth & Permissions → Bot User OAuth Token
Token na poziomie aplikacji	`xapp-…`	Basic Information → App-Level Tokens (`connections:write`)
Token odświeżania konfiguracji aplikacji (opcjonalnie)	`xoxe-…`	Para tokenów konfiguracji aplikacji na api.slack.com/apps

Prefiks każdej wartości jest sprawdzany po obu stronach, zanim cokolwiek zostanie wysłane, więc wartość wklejona w niewłaściwe pole zostaje odrzucona tym samym zdaniem tak czy inaczej.

Kliknij Połącz

Control Center weryfikuje token bota za pomocą auth.test Slacka, zanim cokolwiek zapisze, więc literówka zostanie Ci zgłoszona, zamiast stać się socketem, który po cichu nigdy nie działa. Token na poziomie aplikacji można udowodnić tylko przez otwarcie socketu, więc błędny pojawi się chwilę później jako błąd połączenia w tym samym wierszu.

Bez opcjonalnego tokenu konfiguracji aplikacji połączenie działa dobrze — po prostu nie możesz edytować bota z Control Center.

Co daje połączenie

Zapisuje dane uwierzytelniające w katalogu samego obszaru roboczego, obok jego bazy danych, czytelne tylko dla właściciela. Nigdy nie wracają do klienta
Otwiera jedno połączenie Socket Mode dla tego obszaru roboczego i zaczyna odbierać wzmianki, odpowiedzi w wątkach Slacka, wiadomości prywatne i polecenia z ukośnikiem
Ponownie uzbraja każdy wątek Slacka podłączony wcześniej, więc ponowne połączenie kontynuuje istniejące rozmowy, zamiast je porzucać
Nie kosztuje nic w obszarach roboczych bez aplikacji czatu: żadnego socketu, żadnych timerów, żadnego ruchu

Dane uwierzytelniające bota to jeden zwykły plik JSON na dostawcę w <dataDir>/<workspaceId>/chat_credentials/, zapisywany atomowo i zawężony do właściciela. To celowe, nie przeoczenie: usunięcie obszaru roboczego odłącza ten katalog, więc tokeny znikają razem z nim, a workspace.export i kopie zapasowe kopiują workspace.db — nie katalog — więc obszar roboczy, który przekazujesz komuś innemu, nigdy nie przenosi w sobie aktywnych tokenów bota. Wynika z tego, że przywrócenie obszaru roboczego gdzie indziej oznacza ponowne połączenie tam Slacka.

Dostęp do mostu daje członkostwo w obszarze roboczym, nigdy posiadanie tokenu. Konto Slack musi być połączone z użytkownikiem Control Center, który jest członkiem z rolą z prawem zapisu. Łączenie, rozłączanie, konfiguracja z przewodnikiem, link konfiguracyjny i dostosowywanie bota wymagają uprawnień administratora.

Sprawdź

Wiersz Slack pokazuje znacznik stanu: Na żywo, Łączenie…, Błąd połączenia (obok niego błąd zwrócony przez samego Slacka) albo Nie połączono. Aby sprawdzić całą drogę:

W Slacku zaproś bota do kanału: /invite @your-bot-name
Wspomnij go z prośbą
Pojawia się odpowiedź w wątku Slacka, a w Control Center pojawia się pasująca przestrzeń

Każdy członek, który chce korzystać z mostu, łączy potem własne konto — zobacz Połącz swoje konto Slack.

Jak wygląda odpowiedź w Slacku

Nad strumieniowanymi słowami znajduje się jedna zgrupowana karta z wierszem na krok. Konfiguracja to jeden wiersz, którego tytuł przechodzi od Working on it… przez Cloning … do Starting the agent…. Rozumowanie dodaje wiersz Thinking…; gdy ten krok się kończy, może pojawić się na nim krótka myśl. Każde narzędzie to osobny wiersz (Read lib/main.dart). Odpowiedź przychodzi jako zwykły tekst pod kartą. Karta staje się ukończona, gdy tura się kończy, a błędna, gdy uruchomienie nie powiodło się, zostało przerwane albo osiągnęło limit tur.

Karta zaczyna się w momencie, w którym bot przyjmuje wzmiankę — Working on it… — więc wątek Slacka nie milczy, gdy obszar roboczy wciąż się buduje. Twoja pierwsza wzmianka w kanale Slack tworzy rozmowę, która klonuje repozytoria, w których pracuje agent, więc wiersz konfiguracji brzmi wtedy Cloning acme/widgets…, potem Setting up Reviewer…, potem Starting the agent…, a następnie pojawia się wiersz Thinking…, gdy agent naprawdę rozumuje. W dużym repozytorium ta pierwsza konfiguracja trochę trwa; karta pozwala poznać, że coś się dzieje, a nie że jesteś ignorowany. Późniejsze wzmianki w tym samym wątku Slacka nadal zaczynają się od Working on it…, a potem pomijają kroki klonowania, bo obszar roboczy już istnieje.

Rozumowanie pod postacią ściany tekstu i dane wyjściowe narzędzi nigdy nie opuszczają Control Center — myśl w wierszu Thinking… to krótka linia, nie transkrypcja. View in Control Center na karcie otwiera pełną rozmowę w aplikacji desktopowej — link prowadzi do Twojego własnego serwera Control Center, który przekazuje przeglądarkę aplikacji.

Jeśli po kliknięciu nic się nie dzieje, serwer, który wysłał wiadomość, jest nieosiągalny z maszyny, na której kliknąłeś (na przykład serwer działający tylko na loopbacku, kliknięty z telefonu), albo Control Center nie działa na tej maszynie. Serwer bez osiągalnego adresu wysyła kartę bez przycisku, a nie taką, która prowadzi donikąd.

Rotacja tokenu

Wklej ponownie nową wartość w oknie połączenia i kliknij Połącz. Połączenie zastępuje to, które działało dla tego obszaru roboczego, więc socket jest wybierany ponownie z nowymi danymi uwierzytelniającymi.

Te dwa wymagane tokeny muszą być obecne przy każdym połączeniu. Opcjonalny token konfiguracji aplikacji zachowuje zapisaną wartość, gdy pozostawisz pole puste, więc rotacja tokenu bota nigdy nie kosztuje Cię możliwości edycji aplikacji.

Rozłącz

Kliknij Rozłącz w wierszu Slack (tylko administratorzy). Socket zostaje zamknięty, a dane uwierzytelniające zapomniane.

Powiązania przestrzeni i użytkowników celowo przetrwają: ponowne połączenie tej samej aplikacji przywraca każdy podłączony wątek Slacka. To wiersze przypisane do obszaru roboczego, więc usunięcie obszaru roboczego i tak je usuwa.

Rozwiązywanie problemów

Wiersz mówi „Błąd połączenia”

Przeczytaj błąd pokazany obok znacznika. Odrzucone dane uwierzytelniające (invalid_auth, not_authed, token_revoked, account_inactive) są ostateczne — most przestaje ponawiać i czeka na nowe tokeny, bo bez końca ponawianie unieważnionego tokenu kończy się tylko limitami szybkości. Wklej tokeny ponownie w oknie połączenia.

Błąd missing_scope oznacza, że aplikacja jest zainstalowana z mniejszą liczbą zakresów, niż potrzebuje most. Dodaj brakujący zakres, zainstaluj aplikację ponownie w Slacku i połącz się jeszcze raz.

Wszystko przejściowe (zerwany socket, chwilowa awaria Slacka) łączy się ponownie samo, z wykładniczym backoffem ograniczonym do 30 sekund, a rutynowa rotacja socketów po stronie Slacka nie zwiększa tego backoffu.

Bot nie odpowiada na wzmiankę

Czy bot jest na kanale? Slack dostarcza wiadomości z kanału tylko aplikacjom, które są członkami. Uruchom /invite @your-bot-name
Czy jesteś połączony? Niepołączony członek dostaje w tym wątku Slacka odpowiedź wyjaśniającą, jak się połączyć. Zobacz Połącz swoje konto Slack
Czy jesteś członkiem obszaru roboczego z rolą z prawem zapisu? Użytkownikowi viewer lub guest mówi się, że jego rola jest tylko do odczytu. Most nigdy nie zaczyna pracy w imieniu kogoś, kogo nie potrafi przypisać
Czy obszar roboczy ma jakichkolwiek agentów? Bez agentów wiadomość zostaje zapisana, ale nie ma kto na nią odpowiedzieć

Odpowiada na kanale, ale ignoruje zwykłe wiadomości

To zamierzone. Poza wiadomością prywatną most działa tylko na wiadomość, która wspomina bota, albo na odpowiedź w wątku Slacka, który już prowadzi. Wszystko inne to rozmowa innych osób.

Odpowiedzi przychodzą jako jedna duża wiadomość zamiast strumieniowania

Wiersz mówi: „Strumieniowanie na żywo jest wyłączone dla tej aplikacji Slack — odpowiedzi przychodzą jako jedna wiadomość.” Strumieniowe odpowiedzi Slacka wymagają funkcji Agents & AI Apps w płatnym planie; gdy Slack jej odmawia, most przestaje o nią prosić do końca życia tego połączenia i publikuje całe odpowiedzi. Nic nie ginie — pełny transkrypt zawsze znajduje się w Control Center.

Strumieniowanie wymaga też kotwicy w wątku Slacka, więc odpowiedź, która nie ma wątku, w którym mogłaby rosnąć, jest publikowana w całości. Karta zadania i tak się pojawia: przy całej odpowiedzi jedzie w tej samej wiadomości, już ukończona.

Nad odpowiedzią nie ma karty

Karty zadań Slacka są częścią tej samej nowej powierzchni Agents & AI Apps co strumieniowanie, a Slack odmawia dopiero w momencie wywołania. Gdy tak się stanie, Control Center zachowuje odpowiedź i porzuca kartę do końca życia tego połączenia — odpowiedź bez wiersza stanu jest lepsza niż wiersz stanu bez odpowiedzi.

„Do edycji bota Control Center potrzebuje tokenu konfiguracji aplikacji”

Wiersz Dostosuj bota jest wyłączony, bo połączenie nie ma tokenu konfiguracji aplikacji. To oczekiwane w przypadku aplikacji zrobionej ręcznie albo przez Utwórz w Slack — Slack nigdy nie powiedział Control Center, którą aplikacją jest. Wygeneruj parę tokenów na api.slack.com/apps i połącz się ponownie z wypełnionym tokenem odświeżania.

Długa odpowiedź jest ucięta

Slack ogranicza pojedynczą wiadomość do 40 000 znaków, więc most ucina na 39 000 i dopisuje wskaźnik do Control Center — skrócona odpowiedź jest lepsza niż taka, którą Slack odrzuci w całości. Pełny tekst zawsze znajduje się w transkrypcie przestrzeni.

Powiązane poradniki

Powiązane koncepcje

Mosty czatu