Jak skonfigurować Hermes Slack w systemie ZimaOS i naprawić błędy bramy sieciowej

Agent Hermes może łączyć się ze Slackiem bez udostępniania publicznego punktu końcowego webhooka, ponieważ jego bieżąca integracja ze Slackiem korzysta z trybu Socket Mode. Raport społecznościowy będący podstawą tej strony obejmował większość konfiguracji: użytkownik utworzył nową aplikację Slack, uzyskał xoxb- token bota oraz xapp- token na poziomie aplikacji, uruchomił hermes gateway setup wewnątrz kontenera ZimaOS Hermes i zaprosił bota na kanał Slacka.

Awaria nastąpiła, gdy Hermes próbował ponownie uruchomić swoją bramę. Interfejs CLI zwrócił PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock', i chociaż aplikacja była widoczna w Slacku, @Hermes wzmianka nie wywołała odpowiedzi. Aktualna dokumentacja ZimaSpace wyraźnie wskazuje teraz /opt/data błędy uprawnień jako problem z własnością plików Hermes, który może wystąpić po wcześniejszym uruchamianiu operacji bramy jako root. Aktualna dokumentacja Hermes dotycząca Slacka dodaje również kilka wymagań konfiguracyjnych, które bezpieczniej jest zweryfikować, niż ręcznie zgadywać zakresy.

Co wydarzyło się w raporcie społeczności dotyczącym Slacka w ZimaOS Hermes

Wpis społecznościowy z maja 2026 roku dotyczył świeżej instalacji ZimaOS Hermes i nowego obszaru roboczego Slack. Użytkownik utworzył aplikację Slack z włączonym trybem Socket Mode, skopiował oba wymagane typy tokenów i skonfigurował Slacka za pomocą kreatora bramy Hermes.

Kluczowa sekwencja wyglądała następująco:

1. Utwórz aplikację Slack i włącz tryb Socket Mode.
2. Uzyskaj token OAuth użytkownika-bota rozpoczynający się od xoxb-.
3. Uzyskaj token na poziomie aplikacji rozpoczynający się od xapp-.
4. Uruchom hermes gateway setup wewnątrz kontenera Hermes.
5. Wybierz Slack i wprowadź oba tokeny.
6. Zaakceptuj monit o ponowne uruchomienie bramy.

Ponowne uruchomienie nie powiodło się z błędem:

PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock'

Następnie użytkownik ponownie uruchomił bramę z interfejsu Hermes Web UI, zaprosił @Hermes na kanale Slacka i zobaczył potwierdzenie Slacka, że aplikacja została dodana. Jednak wzmianka na kanale nadal nie wywołała odpowiedzi. Oznaczało to, że do rozwiązania mogły pozostać dwie warstwy problemu: proces bramy po stronie ZimaOS oraz konfiguracja zdarzeń po stronie Slacka.

Użyj aktualnego manifestu Slack Hermes zamiast ręcznie odtwarzać wszystkie zakresy

Aktualna dokumentacja Hermes zaleca wygenerowanie manifestu aplikacji Slack. Jest to bezpieczniejsze niż ręczne odtwarzanie z pamięci wszystkich zakresów OAuth, poleceń z ukośnikiem, subskrypcji zdarzeń i ustawień trybu Socket Mode.

W aktualnym środowisku Hermes wygeneruj manifest za pomocą:

hermes slack manifest --agent-view --write

Wygenerowany plik jest zapisywany w:

~/.hermes/slack-manifest.json

Następnie utwórz nową aplikację Slack na podstawie tego manifestu w interfejsie administracyjnym aplikacji Slacka. Aktualna dokumentacja Hermes wyjaśnia, że manifest deklaruje jednocześnie wbudowane polecenia, wymagane zakresy uprawnień, subskrypcje zdarzeń i konfigurację trybu Socket Mode.

Aktualną procedurę dostępną w upstreamie znajdziesz w przewodniku konfiguracji Hermes Agent ze Slackiem.

Dwa tokeny Slacka wymagane przez Hermes

Hermes korzysta z dwóch różnych danych uwierzytelniających Slacka i nie można ich stosować zamiennie:

• Token bota: zaczyna się od xoxb- i jest przypisywany do SLACK_BOT_TOKEN.
• Token na poziomie aplikacji: zaczyna się od xapp-, musi obsługiwać tryb Socket Mode i jest przypisywany do SLACK_APP_TOKEN.

Aktualny plik środowiskowy Hermes może zawierać:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_ALLOWED_USERS=U01ABC2DEF3

SLACK_ALLOWED_USERS używa identyfikatorów członków Slacka, a nie nazw wyświetlanych. Jeśli tokeny są prawidłowe, ale użytkownik wysyłający żądanie nie ma uprawnień, Hermes może nadal wyglądać na połączony, jednocześnie odmawiając przetwarzania wiadomości tego użytkownika.

Nigdy nie publikuj prawdziwych xoxb- lub xapp- wartości w poście społeczności, zrzucie ekranu, repozytorium Git lub dzienniku pomocy technicznej. Unieważnij token i wygeneruj go ponownie, jeśli został ujawniony.

Wspomnienia na kanałach wymagają właściwych zdarzeń Slacka

Widoczność bota na kanale nie oznacza, że Slack dostarcza Hermesowi zdarzenia dotyczące wiadomości. Aktualna dokumentacja Hermes wskazuje subskrypcje zdarzeń jako częstą przyczynę problemów.

W przypadku ręcznie skonfigurowanej aplikacji Slack sprawdź zdarzenia wymagane przez bieżącą wersję Hermes. Aktualna dokumentacja obejmuje między innymi takie zdarzenia:

• app_mention w przypadku wiadomości bezpośrednich @Hermes wspomnienia.
• message.channels w przypadku wiadomości na kanałach publicznych, na których bot jest członkiem.
• message.groups gdy potrzebna jest obsługa kanałów prywatnych.
• message.im w przypadku wiadomości bezpośrednich.

Jeśli po zainstalowaniu aplikacji Slack zmienisz zakresy uprawnień lub subskrypcje zdarzeń, ponownie zainstaluj aplikację w obszarze roboczym, gdy Slack wyświetli taki monit. W przeciwnym razie wyświetlane ustawienia i uprawnienia faktycznie przyznane zainstalowanemu botowi mogą się różnić.

Zaproś Hermes do kanału przed testowaniem

Hermes nie dołącza automatycznie do każdego kanału Slacka. Zaproś go jawnie:

/invite @Hermes

Następnie przetestuj proste wspomnienie od użytkownika Slacka, którego identyfikator członka znajduje się na liście dozwolonych Hermes. Jeśli wiadomości bezpośrednie działają, ale wspomnienia na kanałach publicznych nie, skup się na app_mention, message.channels, członkostwo w kanale i uprawnienia zainstalowanej aplikacji przed zmianą konfiguracji sieciowej ZimaOS.

Dlaczego /opt/data/gateway.lock może zwracać błąd odmowy dostępu

Aktualny przewodnik ZimaSpace dotyczący Hermes Agent opisuje teraz problem z uprawnieniami do /opt/data. Zgodnie z nim jest on zwykle spowodowany wcześniejszym uruchomieniem Hermes Gateway jako root, co pozostawiło pliki należące do roota wewnątrz $HERMES_HOME.

Udokumentowany przez ZimaSpace sposób pracy z kontenerem polega na wejściu do niego jako dedykowany hermes użytkownika:

docker exec -it -u hermes hermes bash

Następnie aktywuj wirtualne środowisko Hermesa:

source /opt/hermes/.venv/bin/activate

Konfigurację wiadomości można następnie otworzyć za pomocą:

hermes gateway setup

Jeśli brama natychmiast kończy działanie po /opt/data/gateway.lock, nie uruchamiaj też wielokrotnie całej bramy jako root. Najpierw potwierdź tożsamość i właściciela:

id
ls -ld /opt/data
ls -l /opt/data/gateway.lock 2>/dev/null

Aktualny przewodnik ZimaSpace zaleca sprawdzanie logów Hermesa w pulpicie ZimaOS i tymczasowe używanie powłoki roota wyłącznie wtedy, gdy trzeba naprawić właściciela plików. Nie stosuj bezmyślnej rekurencyjnej zmiany właściciela do /opt/data chyba że sprawdzono, które pliki należą do Hermesa oraz jakiego użytkownika/grupy oczekuje zainstalowany pakiet ZimaOS.

Zrestartuj bramę dopiero wtedy, gdy Hermes może zapisywać swoje pliki środowiska uruchomieniowego

W raporcie społeczności kliknięcie Restart Gateway w interfejsie internetowym nie wystarczyło, aby potwierdzić poprawne działanie bramy. Jeśli proces bazowy nie może utworzyć ani zaktualizować pliku blokady, działanie interfejsu może nadal pozostawić integrację ze Slackiem niedostępną.

Po naprawieniu problemu z faktycznym właścicielem wejdź do kontenera jako hermes użytkownika, aktywuj środowisko i uruchom lub zrestartuj bramę, korzystając z poleceń obsługiwanych przez zainstalowaną wersję Hermesa. Obserwuj logi Hermesa w ZimaOS podczas wysyłania testowej wiadomości na Slacku.

Przydatny podział podczas rozwiązywania problemów to:

• Brak uruchomienia bramy: sprawdź uprawnienia do /opt/data oraz logi Hermesa.
• Brama działa, ale nie ma połączenia ze Slackiem: sprawdź token xapp- oraz tryb Socket Mode.
• Połączenie ze Slackiem istnieje, ale wzmianki na kanale pozostają bez odpowiedzi: sprawdź zdarzenia aplikacji, członkostwo w kanale, status ponownej instalacji oraz SLACK_ALLOWED_USERS.
• DM działa, ale kanał nie: skup się na zdarzeniach kanału i uprawnieniach, a nie na dostawcy modelu.

Korzystaj z Hermes Web Dashboard do sprawdzania stanu, ale nie jako jedynego sposobu kontroli kondycji

Przewodnik ZimaSpace udostępnia pulpit Hermes Web Dashboard pod adresem:

http://ZIMAOS_LAN_IP:9119

Panel może wyświetlać stan działania, sesje i ustawienia modelu. Jest przydatny do ponownego uruchamiania i obserwowania bramy, ale w przypadku błędu uprawnień na poziomie procesu należy korzystać z niego razem z dziennikami.

Lista kontrolna rozwiązywania problemów z Hermes Slack w ZimaOS

1. Przed dodaniem Slacka upewnij się, że sama konfiguracja modelu Hermesa działa.
2. Wejdź do kontenera ZimaOS jako hermes użytkownika, a nie jako root podczas zwykłej pracy bramy.
3. Jeśli to możliwe, użyj aktualnego manifestu Slack Hermesa zamiast ręcznie zgadywać wymagane zakresy uprawnień.
4. Upewnij się, że xoxb- token bota oraz xapp- token aplikacji należą do tej samej zamierzonej aplikacji Slack.
5. Upewnij się, że tryb Socket Mode jest włączony.
6. Upewnij się, że Twój identyfikator członka Slacka znajduje się w SLACK_ALLOWED_USERS.
7. Zaproś Hermesa na testowany kanał.
8. Sprawdź app_mention i zasubskrybowano wymagane zdarzenia wiadomości.
9. Po zmianie zakresów uprawnień lub subskrypcji zdarzeń zainstaluj aplikację Slack ponownie, jeśli Slack tego zażąda.
10. Jeśli /opt/data/gateway.lock nie powiedzie się, sprawdź własność plików i dzienniki Hermesa w ZimaOS przed kolejnym ponownym uruchomieniem.
11. Gdy brama działa poprawnie, przetestuj osobno wiadomość prywatną oraz wzmiankę na jednym kanale.

Najczęstsze pytania dotyczące Hermes Slack w ZimaOS

Co oznacza błąd uprawnień gateway.lock?

Oznacza to, że proces Hermesa nie może uzyskać dostępu do pliku blokady środowiska uruchomieniowego w oczekiwanej lokalizacji. Aktualna dokumentacja ZimaSpace wskazuje, że /opt/data Błąd uprawnień jest zwykle związany z plikami, których właścicielem root pozostał po uruchomieniu Hermes Gateway jako root.

Czy powinienem uruchomić Hermes Gateway jako root, aby to naprawić?

Nie jako standardowego rozwiązania. ZimaSpace opisuje wchodzenie do kontenera jako hermes użytkownika do zwykłych operacji Hermesa. Powłoki root należy używać tylko tymczasowo, gdy potwierdzono, że trzeba naprawić własność plików.

Dlaczego bot Hermesa jest widoczny w Slacku, ale nie odpowiada?

Samo zainstalowanie i zaproszenie aplikacji dowodzi jedynie, że Slack ją rozpoznaje. Hermes nadal potrzebuje sprawnie działającej bramy, prawidłowego połączenia Socket Mode, poprawnych subskrypcji zdarzeń, odpowiednich uprawnień w obszarze roboczym oraz dozwolonego identyfikatora członka Slacka.

Czy Hermes Slack wymaga publicznego adresu URL webhooka?

Nie. Obecna integracja Hermesa ze Slackiem korzysta z trybu Socket Mode przez WebSockets, więc instancja Hermesa może pozostać za zaporą sieciową bez publicznego przychodzącego endpointu webhooka Slacka.

Jaki jest obecnie najlepszy sposób konfiguracji aplikacji Slack?

Użyj aktualnego manifestu Slack generowanego przez Hermes, jeśli obsługuje go zainstalowana wersja Hermesa. Ogranicza to liczbę błędów powodowanych przez brakujące zakresy uprawnień, subskrypcje zdarzeń lub definicje poleceń slash.