Hermes Agent: przewodnik konfiguracji na własnym serwerze dla użytkowników serwerów domowych

Eva Wong jest redaktorką techniczną i rezydentką majsterkowania w ZimaSpace. Jest geekiem od zawsze, z pasją do domowych laboratoriów i oprogramowania open source, a jej specjalnością jest przekładanie złożonych zagadnień technicznych na przystępne, praktyczne poradniki. Eva wierzy, że samodzielne hostowanie powinno sprawiać radość, a nie onieśmielać. Dzięki swoim samouczkom pomaga społeczności oswoić konfigurację sprzętu, od budowy pierwszego serwera NAS po opanowanie kontenerów Docker.

Krótka odpowiedź

Hermes Agent można hostować samodzielnie na serwerze domowym, jeśli potrzebujesz agenta AI, który łączy się z dostawcą modelu, korzysta z narzędzi i komunikuje się przez bramę komunikatora, taką jak Telegram. Dla większości początkujących największym wyzwaniem nie jest samo uruchomienie aplikacji. Chodzi o zrozumienie, gdzie odbywa się każda czynność: na serwerze hosta, wewnątrz kontenera, w środowisku aplikacji czy za pośrednictwem platformy komunikacyjnej.

Bezpieczna konfiguracja hostowana samodzielnie powinna odpowiadać na sześć pytań, zanim zaczniesz rozwiązywać jakiekolwiek problemy:

  • Czy pracuję na serwerze hosta, czy wewnątrz kontenera?
  • Gdzie znajdują się konfiguracja aplikacji, logi, pobrane pliki i dane środowiska uruchomieniowego?
  • Kto jest właścicielem plików i uruchamia aplikację?
  • Czy aplikacja może połączyć się z dostawcą modelu i interfejsem API komunikatora?
  • Czy klucze API, tokeny botów i listy dozwolonych są chronione?
  • Jak sprawdzić, czy agent nadal działa po ponownym uruchomieniu?

Jeśli te granice są jasno określone, konfigurację Hermes Agent znacznie łatwiej zrozumieć, zweryfikować i naprawić.

Czym jest Hermes Agent w konfiguracji samodzielnie obsługiwanego serwera domowego?

Hermes Agent to obsługiwany samodzielnie proces pracy agenta AI, który może łączyć się z dostawcą modelu, korzystać z narzędzi i komunikować się przez terminal lub kanały komunikacyjne. Na serwerze domowym często pełni funkcję pośrednika między modelem AI, środowiskiem serwera a interfejsem komunikacyjnym, takim jak panel WWW lub brama bota.

Warto pamiętać, że agent hostowany samodzielnie to nie tylko chatbot. W zależności od konfiguracji może korzystać z plików, narzędzi terminalowych, interfejsów API modeli, platform komunikacyjnych i danych środowiska uruchomieniowego. Dlatego tak ważne są granice ścieżek dostępu, uprawnień i dostępu.

Do czego służy Hermes Agent: interakcje z AI i komunikacja

Hermes Agent można skonfigurować tak, aby łączył się z dostawcą modelu, rozpoczynał rozmowy, korzystał z narzędzi i łączył się z bramami komunikatorów. W krótkim przewodniku po Hermes Agent wyjaśniono, jak zainstalować Hermes, skonfigurować dostawcę modelu, rozpocząć pierwszą rozmowę, korzystać z narzędzi terminalowych, a później połączyć platformy komunikacyjne za pośrednictwem bramy.

Dla użytkownika serwera domowego oznacza to, że Hermes może stać się stale działającym asystentem AI na urządzeniu, nad którym masz kontrolę. Konfiguracja może też obejmować dodatkowe warstwy: dane uwierzytelniające modelu, środowisko uruchomieniowe aplikacji, ustawienia bramy i uprawnienia dostępu.

Kiedy konfiguracja przez WebUI wystarcza

Konfiguracja przez WebUI zwykle wystarcza, gdy aplikacja udostępnia wszystkie potrzebne ustawienia bezpośrednio w panelu. To najbezpieczniejsza ścieżka dla większości użytkowników, ponieważ pozwala uniknąć korzystania z terminala kontenera, chyba że czegoś brakuje lub coś nie działa.

podejście oparte przede wszystkim na WebUI jest odpowiednie, gdy:

  • aplikacja instaluje się bez problemów;
  • dostawcę modelu można skonfigurować z poziomu interfejsu;
  • bramę komunikatora można połączyć bez dostępu do powłoki;
  • pulpit nawigacyjny wyraźnie pokazuje stan;
  • w dziennikach nie ma błędów uprawnień ani sieciowych.

Jeśli panel udostępnia potrzebną opcję, najpierw z niej skorzystaj. Konfigurację terminala kontenera należy traktować jako rozwiązanie awaryjne lub zaawansowaną metodę, a nie domyślny pierwszy krok dla każdego użytkownika.

Kiedy potrzebna jest konfiguracja terminala kontenera

Konfiguracja terminala kontenera może być potrzebna, gdy panel nie udostępnia wymaganej opcji, aplikacja wymaga uruchomienia kreatora konfiguracji wewnątrz kontenera lub rozwiązywanie problemów wymaga dostępu do dzienników, środowiska uruchomieniowego albo poleceń właściwych dla aplikacji.

To właśnie tutaj wielu użytkowników się gubi. Polecenie uruchomione w powłoce hosta może nie mieć wpływu na aplikację wewnątrz kontenera. Plik widoczny w kontenerze może nie istnieć pod tą samą ścieżką na hoście. Błąd uprawnień może wynikać z użytkownika uruchamiającego aplikację, a nie z dostawcy modelu czy tokenu bota.

Przed użyciem terminala kontenera sprawdź, w której powłoce dokładnie się znajdujesz i jako który użytkownik działasz.

Czego potrzebujesz przed rozpoczęciem

Konfiguracja agenta hostowanego samodzielnie wymaga czegoś więcej niż działającego serwera. Potrzebujesz sprawnego połączenia sieciowego, dostępu do modelu, danych uwierzytelniających komunikatora oraz uprawnień wystarczających do zarządzania aplikacją bez przypadkowej zmiany niewłaściwych plików.

Serwer domowy z dostępem do internetu

Serwer domowy powinien mieć dostęp do internetu, jeśli planujesz korzystać z dostawcy modelu w chmurze lub API komunikatora. Jeśli używasz lokalnego punktu końcowego modelu, serwer nadal musi mieć do niego dostęp przez sieć lokalną lub sieć kontenera.

Dostęp do sieci ma znaczenie, ponieważ agent może wyglądać na poprawnie zainstalowanego, a mimo to nie odpowiadać. Na przykład połączenie z dostawcą modelu, bramka komunikatora i panel mogą korzystać z różnych ścieżek sieciowych.

Zacznij od sprawdzenia, czy:

  • serwer ma stabilne połączenie z siecią LAN;
  • serwer może połączyć się z punktem końcowym modelu lub dostawcą;
  • serwer może połączyć się z API komunikatora;
  • port panelu jest dostępny z poziomu przeglądarki;
  • żadna reguła zapory nie blokuje bramki.

Dostawca modelu lub lokalny punkt końcowy modelu

Hermes wymaga połączenia z modelem, aby generować przydatne odpowiedzi. Może to być dostawca usług chmurowych, klucz API lub punkt końcowy zgodny z OpenAI. Niektórzy użytkownicy mogą podłączyć lokalną usługę modelu, jeśli pozwalają na to ich sprzęt i stos modelu.

Ważne jest to, że konfiguracja modelu jest oddzielona od konfiguracji komunikatora. Bot może być prawidłowo podłączony, a dostawca modelu może być niewłaściwy; dostawca modelu może też działać, gdy bramka bota zawodzi.

Przed rozpoczęciem konfiguracji uporządkuj adres URL bazowy modelu, klucz API, nazwę modelu i ustawienia kontekstu.

Konto w usłudze komunikacyjnej i token bota

Jeśli chcesz rozmawiać z agentem przez Telegram lub inną platformę komunikacyjną, potrzebujesz konta w danej usłudze oraz danych uwierzytelniających bota lub bramki. W przypadku Telegrama zwykle oznacza to utworzenie bota i zapisanie jego tokenu.

Token bota należy traktować jak hasło. Telegram wyjaśnia, że każdy bot otrzymuje unikalny token służący do autoryzowania żądań do Bot API, a żądania zawierają token w ścieżce API, zgodnie z modelem autoryzacji za pomocą tokenu bota Telegram.

Nie wklejaj tokenu bota na publicznych czatach, na zrzutach ekranu, w logach, zgłoszeniach na GitHubie ani w udostępnianych dokumentach. Jeśli token zostanie ujawniony, wygeneruj nowy zgodnie z oficjalną procedurą platformy do obsługi wiadomości.

Adres IP hosta, dostęp do logowania i uprawnienia kontenera

Aby uzyskać dostęp do panelu serwera lub połączyć się przez SSH, potrzebujesz adresu IP hosta. Potrzebujesz też danych logowania, które umożliwiają bezpieczne zarządzanie aplikacją.

W konfiguracjach opartych na kontenerach uprawnienia są często rozdzielone na kilka warstw:

Warstwa uprawnień Co kontroluje Częsty błąd Bezpieczna kontrola
Użytkownik hosta / konto SSH Dostęp do systemu plików serwera domowego, poleceń Docker i panelu serwera. Zakładanie, że uprawnienia hosta automatycznie obowiązują wewnątrz kontenera. Sprawdź, które konto jest zalogowane i jakie działania na poziomie serwera może wykonywać.
Użytkownik kontenera Użytkownik uruchamiający proces aplikacji i zapisujący pliki aplikacji w kontenerze. Uruchamianie konfiguracji jako root, gdy aplikacja zwykle działa jako użytkownik bez uprawnień roota. Przed utworzeniem lub modyfikacją danych aplikacji sprawdź, który użytkownik ma korzystać z kontenera.
Zamontowany folder hosta Folder hosta lub wolumin Docker udostępniony kontenerowi. Modyfikowanie folderu na hoście, który nie jest zamontowany w ścieżce odczytywanej przez aplikację. Sprawdź źródłową ścieżkę hosta i docelową ścieżkę kontenera.
Ścieżka środowiska uruchomieniowego aplikacji Gdzie przechowywane są pliki konfiguracji, logi, pobrane pliki, sesje i dane tymczasowe. Modyfikowanie plików w niewłaściwej warstwie lub utrata ustawień po ponownym uruchomieniu. Potwierdź, że ścieżka jest zachowywana po ponownym uruchomieniu i że użytkownik aplikacji może w niej zapisywać.

Nie zakładaj, że root zawsze jest właściwym wyborem. Użycie roota w niewłaściwym momencie może utworzyć pliki należące do roota, których użytkownik aplikacji nie będzie mógł później modyfikować.

Ścieżka hosta a ścieżka kontenera a ścieżka danych aplikacji

To najważniejsza koncepcja w tym artykule. Wiele problemów z konfiguracją Hermes Agent wynika z mylenia ścieżek hosta i kontenera, ścieżek danych aplikacji, logów, pobranych plików i zamontowanych woluminów.

Przed uruchomieniem poleceń lub diagnozowaniem problemów skorzystaj z mapy kontroli kontenera Agenta.

Warstwa Pytanie, na które należy odpowiedzieć Sygnał weryfikacyjny Typowa awaria
System hosta Czy można uzyskać dostęp do serwera, panelu, sesji SSH i menedżera kontenerów? Otwiera się panel lub sesja SSH, a kontener jest widoczny jako uruchomiony. Aplikacja wydaje się zainstalowana, ale nie można uzyskać dostępu do serwera ani kontenera.
Środowisko uruchomieniowe kontenera Czy jestem we właściwym kontenerze i używam oczekiwanego użytkownika? Powłoka, katalog roboczy i użytkownik są zgodne ze ścieżką konfiguracji aplikacji. Polecenia są uruchamiane w powłoce hosta i nie wpływają na aplikację działającą wewnątrz kontenera.
Ścieżka danych aplikacji Gdzie znajdują się pliki konfiguracji, logi, pobrane pliki i pliki środowiska uruchomieniowego? Ustawienia i logi są zachowywane po ponownym uruchomieniu, a użytkownik aplikacji może je modyfikować. Ustawienia znikają po restarcie albo aplikacja wyświetla błędy odmowy dostępu.
Ścieżka sieciowa Czy kontener może połączyć się z dostawcą modelu, lokalnym punktem końcowym i API komunikatora? Testy dostawcy, wywołania bramy i dostęp do panelu działają z oczekiwanej warstwy. Model lub bot nie działa, mimo że aplikacja wygląda na poprawnie zainstalowaną.
Dane uwierzytelniające i dostęp Czy klucze API, tokeny botów i listy dozwolonych użytkowników są bezpiecznie skonfigurowane? Prywatne wiadomości testowe działają, a logi nie pokazują błędów tokenu ani dostępu. Token bota jest nieprawidłowy, ujawniony albo identyfikator dozwolonego użytkownika jest błędny.
Weryfikacja po restarcie Czy konfiguracja nadal działa po restarcie bramy lub usługi? Bot odpowiada, panel działa prawidłowo, a logi po restarcie pozostają czyste. Stara konfiguracja nadal obowiązuje albo nowe ustawienia nie są trwale zapisywane.

Co widzi system hosta

System hosta to właściwy system operacyjny serwera domowego. Widzi foldery hosta, kontenery Dockera, interfejsy sieciowe, urządzenia pamięci masowej i usługi systemowe.

Jeśli aplikacja działa w Dockerze, host może nie widzieć jej wewnętrznej ścieżki w taki sam sposób jak kontener. Host może widzieć wolumen Dockera, folder zamontowany przez bind mount albo metadane kontenera.

Dlatego ścieżka taka jak /opt/data lub /app/config może oznaczać coś innego na hoście i wewnątrz kontenera.

Co widzi kontener

Kontener widzi własny system plików. Może też widzieć foldery hosta zamontowane w kontenerze. Ścieżka kontenera to ścieżka z punktu widzenia aplikacji.

Docker wyjaśnia, że bind mount montuje plik lub katalog z komputera hosta w kontenerze, natomiast wolumen Dockera jest tworzony w katalogu przechowywania Dockera na hoście i zarządzany przez Dockera zgodnie z modelem przechowywania bind mountów Dockera.

To rozróżnienie ma znaczenie, ponieważ kontener może uzyskać dostęp tylko do ścieżek hosta, które zostały do niego zamontowane. Jeśli aplikacja nie może znaleźć pliku, przyczyną może być to, że plik istnieje na hoście, ale nie jest zamontowany pod oczekiwaną ścieżką kontenera.

Gdzie zwykle znajdują się konfiguracja aplikacji i dane środowiska uruchomieniowego

Konfiguracja aplikacji, logi, pobrane pliki i dane środowiska uruchomieniowego mogą znajdować się w różnych miejscach, zależnie od sposobu przygotowania aplikacji. Część danych może znajdować się wewnątrz kontenera, część w wolumenie Dockera, a część być montowana z hosta.

W przypadku samodzielnie hostowanego agenta typowe rodzaje danych obejmują:

  • ustawienia dostawcy modelu;
  • konfiguracja bramy;
  • token bota lub ustawienia komunikatora;
  • logi i stan sesji;
  • pliki pobrane tymczasowo;
  • wyniki działania narzędzi;
  • dane środowiska uruchomieniowego aplikacji.

Ważne pytanie brzmi nie tylko „gdzie znajduje się plik?”, ale też „która warstwa jest właścicielem tego pliku i który użytkownik może go modyfikować?”

Ekran agenta Hermes służący do wyboru dostawcy modelu podczas konfiguracji

Dlaczego niejasność dotycząca ścieżek powoduje problemy z uprawnieniami i danymi

Niejasność dotycząca ścieżek powoduje dwa częste problemy. Po pierwsze, użytkownicy edytują plik na hoście, podczas gdy kontener odczytuje inny plik ze swojej ścieżki. Po drugie, użytkownicy uruchamiają konfigurację jako administrator i tworzą pliki, których użytkownik aplikacji nie może później modyfikować.

Podpięcie katalogu może również ukryć istniejące pliki kontenera, jeśli folder hosta zostanie podpięty w miejscu niepustego katalogu kontenera. W takiej sytuacji pliki mogą wydawać się brakujące, choć są jedynie zasłonięte przez podpięty katalog.

Zanim naprawisz problem z danymi aplikacji, sprawdź warstwę środowiska wykonawczego, podłączone ścieżki, właściciela pliku i użytkownika kontenera.

Jak krok po kroku skonfigurować samodzielnie hostowanego agenta

Konfigurację samodzielnie hostowanego agenta należy rozpocząć od kontroli wiążących się z niewielkim ryzykiem, następnie przejść do konfiguracji, a na końcu do weryfikacji. Nie zaczynaj od zmiany uprawnień ani ponownego uruchamiania usług, zanim nie ustalisz, która warstwa powoduje problem.

Krok 1: Zainstaluj aplikację lub otwórz ją z panelu serwera

Zacznij od najprostszej obsługiwanej metody instalacji lub uruchomienia aplikacji na serwerze domowym. Jeśli serwer udostępnia panel aplikacji, sprawdź w nim, czy Hermes Agent jest zainstalowany, widoczny i uruchomiony.

Na tym etapie nie wchodź do kontenera, chyba że wymaga tego aplikacja. Najpierw sprawdź status w panelu, wersję aplikacji, jeśli jest widoczna, oraz dostępność strony konfiguracji.

Jeśli aplikacja w ogóle nie może się uruchomić, przed zmianą plików konfiguracyjnych sprawdź dzienniki.

Krok 2: Sprawdź adres IP hosta i dostęp do sieci

Sprawdź adres IP hosta i upewnij się, że przeglądarka lub terminal może połączyć się z serwerem. W zależności od konfiguracji ten sam adres IP może służyć do dostępu do panelu, połączenia SSH lub dostępu do lokalnej bramy.

Następnie sprawdź dostęp do sieci zewnętrznej. Bot komunikatora nie odpowie, jeśli kontener nie może połączyć się z API komunikatora, a dostawca modelu nie zadziała, jeśli serwer nie może połączyć się z punktem końcowym modelu.

Ta kontrola pomaga odróżnić „niepowodzenie konfiguracji aplikacji” od „problemu z dostępem do sieci”.

Krok 3: Wejdź do kontenera jako właściwy użytkownik

Jeśli konfiguracja terminala kontenera jest wymagana, wejdź do kontenera jako użytkownik oczekiwany przez aplikację. To ważne, ponieważ pliki utworzone przez niewłaściwego użytkownika mogą później powodować błędy uprawnień.

Nie traktuj powłoki hosta i powłoki kontenera jako tego samego środowiska. Polecenie działające na hoście może nie być dostępne w kontenerze, a ścieżka do pliku wewnątrz kontenera może nie istnieć na hoście.

Przed uruchomieniem poleceń konfiguracyjnych upewnij się, że:

  1. Znajdujesz się we właściwym kontenerze.
  2. Korzystasz z konta użytkownika kontenera, którego należy używać.
  3. Znajdujesz się w oczekiwanym katalogu roboczym.
  4. Wymagane polecenie aplikacji jest dostępne.
  5. Wiesz, jak wyjść z kontenera i ponownie do niego wejść.

Krok 4: Aktywuj środowisko aplikacji przed uruchomieniem poleceń konfiguracyjnych

Niektóre samodzielnie hostowane aplikacje korzystają ze środowiska wirtualnego lub konfiguracji powłoki właściwej dla aplikacji. Jeśli środowisko nie jest aktywowane, polecenie aplikacji może nie zostać znalezione lub może działać z niewłaściwymi zależnościami.

Ten krok nie jest tylko formalnością. Dzięki niemu kreator konfiguracji, polecenie bramki i polecenie konfiguracji modelu działają w tym samym kontekście środowiska uruchomieniowego co aplikacja.

Jeśli polecenie nieoczekiwanie kończy się niepowodzeniem, przed ponowną instalacją sprawdź, czy jesteś we właściwym kontenerze i czy środowisko aplikacji jest aktywne.

Krok 5: Połącz się z dostawcą modelu lub lokalną usługą modelu

Skonfiguruj dostawcę modelu, niestandardowy punkt końcowy lub lokalną usługę modelu. Upewnij się, że bazowy adres URL, klucz API, nazwa modelu i ustawienia dotyczące kontekstu są zgodne z używanym dostawcą.

Jeśli konfiguracja modelu nie działa, sprawdź kolejno:

  • Czy klucz API jest prawidłowy?
  • Czy bazowy adres URL jest osiągalny z kontenera?
  • Czy ten punkt końcowy obsługuje daną nazwę modelu?
  • Czy aplikacja wymaga modelu z długim kontekstem?
  • Czy w kontenerze występują problemy z siecią lub DNS?

Nie łącz błędów modelu z błędami komunikacji. Brak odpowiedzi bota Telegram i awaria dostawcy modelu są ze sobą powiązane tylko dlatego, że agent potrzebuje obu tych elementów, aby wykonać zadanie.

Krok 6: Skonfiguruj bramkę komunikacyjną

Bramka komunikacyjna łączy środowisko uruchomieniowe agenta z platformą komunikacyjną. W przypadku Telegrama zwykle wymaga to tokenu bota i określenia dozwolonej tożsamości użytkownika.

Dobra konfiguracja bramki powinna określać, kto może wysyłać wiadomości do agenta, którego tokenu bota używa oraz czy bot ma służyć do rozmów prywatnych, grupowych czy obu tych rodzajów.

Nigdy nie zakładaj, że bot komunikacyjny jest domyślnie interfejsem publicznym. Agent hostowany samodzielnie może mieć dostęp do narzędzi, lokalnych danych lub działań, które nie powinny być dostępne dla każdego, kto może skontaktować się z botem.

Krok 7: Uruchom ponownie bramkę i zastosuj nową konfigurację

Po zmianie modelu lub bramki komunikacyjnej może być konieczne ponowne uruchomienie bramki, zanim nowe ustawienia zaczną obowiązywać. Sposób ponownego uruchamiania ma znaczenie, ponieważ konfiguracja może wydawać się ukończona, mimo że nadal działają stare ustawienia.

Po ponownym uruchomieniu przeprowadź weryfikację zarówno z perspektywy użytkownika, jak i serwera. Wyślij wiadomość testową, sprawdź stan na pulpicie i przejrzyj logi pod kątem błędów uprawnień, tokenów lub sieci.

Jeśli zmiany konfiguracji nie są zachowywane po ponownym uruchomieniu, wróć do ścieżki danych i granic uprawnień.

Ekran sterowania botem Telegram agenta Hermes służący do weryfikacji bramki komunikacyjnej

Uprawnienia, tokeny i kontrola dostępu

Agenty hostowane samodzielnie łączą lokalne uprawnienia środowiska uruchomieniowego z danymi uwierzytelniającymi do usług zewnętrznych. Oznacza to, że konfiguracja może działać od strony technicznej, a mimo to być niebezpieczna, jeśli tokeny, listy dozwolonych użytkowników lub granice uprawnień użytkowników są ustawione nieprawidłowo.

Dlaczego użytkownik kontenera ma znaczenie

Użytkownik kontenera decyduje o tym, które pliki aplikacja może odczytywać i zapisywać w kontenerze. Jeśli polecenia konfiguracji są uruchamiane jako root, a później aplikacja działa jako użytkownik bez uprawnień root, dane aplikacji mogą stać się dla niej niedostępne.

Często pojawia się jako błąd uprawnień w ścieżce danych aplikacji. Rozwiązaniem nie zawsze jest dalsze korzystanie z konta root. W wielu przypadkach lepszym podejściem jest przywrócenie prawidłowego właściciela i uruchamianie aplikacji jako właściwy użytkownik.

Używaj uprawnień roota tylko wtedy, gdy są potrzebne do konkretnego kroku odzyskiwania, i unikaj tworzenia zwykłych plików aplikacji jako root.

Dlaczego klucze API i tokeny botów należy chronić

Klucze API i tokeny botów to dane uwierzytelniające. Klucz API modelu może zapewniać dostęp do dostawcy modelu. Token bota może upoważniać do wysyłania żądań w imieniu bota.

Nie umieszczaj tych wartości w publicznych repozytoriach, zrzutach ekranu, udostępnionych logach ani wiadomościach do pomocy technicznej. Podczas diagnozowania problemów zanonimizuj tokeny przed udostępnieniem konfiguracji lub logów.

Jeśli token został ujawniony, zmień go zamiast liczyć na to, że nikt go nie użyje.

Jak lista dozwolonych użytkowników kontroluje dostęp prywatny

Lista dozwolonych użytkowników ogranicza liczbę osób, które mogą wchodzić w interakcję z agentem za pośrednictwem bramy komunikatora. To ważne, ponieważ bot komunikatora może być dostępny dla większej liczby osób, niż się spodziewasz.

W przypadku prywatnego czatu z AI użyj możliwie krótkiej listy dozwolonych użytkowników. Sprawdź, czy identyfikator dozwolonego użytkownika jest prawidłowy i czy wiadomości testowe pochodzą z tego konta.

Jeśli dostęp ma mieć kilka osób, dodaj je celowo, zamiast pozostawiać bota otwartego dla wszystkich.

Dlaczego botów komunikatorów nie należy traktować jak interfejsów publicznych

Bot komunikatora może przypominać zwykły interfejs czatu, ale za nim może działać hostowany samodzielnie agent z dostępem do modeli, narzędzi, sesji i uprawnień lokalnego środowiska uruchomieniowego.

To odróżnia go od prostego bota powiadomień. Powinien mieć jasno określone reguły dostępu, chronione tokeny i kontrolowaną ścieżkę sieciową.

Na czatach grupowych zachowaj ostrożność. Uprawnienia grupy, tryb prywatności i status administratora bota mogą wpływać na to, jakie wiadomości bot widzi i na jakie może odpowiadać.

Typowe problemy z konfiguracją i sposoby ich rozwiązania

Większość problemów z konfiguracją można przypisać do jednej z sześciu warstw: środowiska uruchomieniowego, ścieżki danych, uprawnień, bramy, sekretu lub walidacji.

Błędy uprawnień w ścieżce danych aplikacji

Błąd uprawnień zazwyczaj oznacza, że bieżący użytkownik aplikacji nie może odczytać wymaganego pliku lub folderu albo zapisać w nim danych. Może się tak zdarzyć, gdy wcześniejsze polecenie konfiguracji utworzyło pliki jako root lub zamontowany folder ma niewłaściwego właściciela.

Najpierw sprawdź:

  • Czy pracujesz wewnątrz kontenera, czy na hoście?
  • Jaki użytkownik uruchamia aplikację?
  • Kto jest właścicielem folderu danych aplikacji?
  • Czy ścieżka danych aplikacji jest zamontowana z hosta?
  • Czy wcześniej uruchomiono polecenie konfiguracji jako root?

Nie zmieniaj uprawnień rekurencyjnie w szerokim zakresie folderów, jeśli nie wiesz, czego dotyczą. Napraw uprawnienia tylko w najmniejszej wymaganej ścieżce.

Bot nie odpowiada po konfiguracji

Bot może nie odpowiadać, nawet gdy sam Hermes Agent działa. Przyczyną może być token, lista dozwolonych użytkowników, brama komunikatora, dostęp do sieci lub uprawnienia w grupie.

Sprawdź w tej kolejności:

  1. Potwierdź, że token bota jest prawidłowy.
  2. Potwierdź, że identyfikator użytkownika znajduje się na liście dozwolonych.
  3. Potwierdź, że po zmianie konfiguracji uruchomiono ponownie bramę.
  4. Potwierdź, że kontener może połączyć się z API komunikatora.
  5. Sprawdź logi aplikacji pod kątem błędów związanych z tokenem, siecią lub uprawnieniami.
  6. Przetestuj czat prywatny, zanim zaczniesz diagnozować problemy z czatem grupowym.

Testowanie czatu prywatnego jest zwykle prostsze niż testowanie czatu grupowego, ponieważ uprawnienia grupowe wprowadzają dodatkowe zmienne.

Ustawienia dostawcy modelu są nieprawidłowe

Jeśli bot odpowiada na wiadomości, ale nie generuje odpowiedzi modelu, problem może dotyczyć dostawcy modelu. Sprawdź podstawowy adres URL, klucz API, nazwę modelu i zgodność punktu końcowego.

W przypadku lokalnych punktów końcowych modeli sprawdź też, czy usługa modelu działa i jest dostępna z kontenera. Usługa dostępna z hosta może nie być dostępna z wnętrza kontenera, jeśli konfiguracja sieci jest inna.

Problemy z dostawcą modelu sprawdzaj oddzielnie od problemów z komunikatorem. Dzięki temu unikniesz zmian w konfiguracji bota, jeśli problem dotyczy połączenia z modelem.

Kontener nie może połączyć się z API komunikatora

Jeśli kontener nie może połączyć się z API komunikatora, brama nie może prawidłowo odbierać ani wysyłać wiadomości. Przyczyną mogą być problemy z DNS, reguły zapory sieciowej, ustawienia serwera proxy lub brak wychodzącego dostępu do internetu.

Sprawdź, czy host ma dostęp do internetu i czy kontener również go ma. To nie zawsze to samo.

Jeśli serwer domowy korzysta z VPN, serwera proxy lub ograniczonej sieci, sprawdź, czy kontener może nawiązywać wychodzące połączenia HTTPS.

Uprawnienia czatu grupowego lub tryb prywatności blokują odpowiedzi

Czat grupowy działa bardziej złożenie niż prywatny. Bot może odpowiadać na czacie prywatnym, ale nie na grupowym, ponieważ nie widzi wiadomości, nie ma odpowiednich uprawnień lub jego działanie ograniczają ustawienia prywatności.

Zacznij od testu czatu prywatnego. Następnie osobno przetestuj czat grupowy.

W przypadku użycia w grupie sprawdź, czy trzeba bezpośrednio oznaczyć bota, czy wymaga on uprawnień administratora i czy ustawienia prywatności pozwalają mu odbierać wymagane wiadomości.

Jak sprawdzić, czy Hermes Agent działa

Konfiguracja nie jest ukończona tylko dlatego, że instalacja dobiegła końca. Jest ukończona, gdy model, brama, uprawnienia, panel, logi i możliwość ponownej konfiguracji przejdą podstawowe testy.

Kreator konfiguracji kończy działanie bez błędów

Kreator konfiguracji powinien zakończyć działanie bez błędów dotyczących brakujących poleceń, dostawcy ani uprawnień. Jeśli wystąpi błąd, przed ponowną próbą sprawdź, która warstwa go spowodowała.

Błąd kreatora konfiguracji zwykle należy do jednej z tych kategorii:

  • dane uwierzytelniające dostawcy modelu;
  • środowisko uruchomieniowe;
  • uprawnienia kontenera;
  • brakujące polecenie aplikacji;
  • dostęp do sieci;
  • konfiguracja bramy.

Użyj tej kategorii, aby zdecydować, co sprawdzić w następnej kolejności.

Bot odpowiada na testową wiadomość prywatną

Najprostszy test komunikacji to wysłanie wiadomości prywatnej. Wyślij zwykłą wiadomość i sprawdź, czy bot odpowiada.

Jeśli czat prywatny działa, token, lista dozwolonych, brama i połączenie z modelem są prawdopodobnie skonfigurowane poprawnie. Jeśli czat grupowy nadal nie działa, skup się na uprawnieniach grupy i ustawieniach prywatności, zamiast ponownie instalować aplikację.

Prywatny czat powinien być pierwszym udanym testem komunikacji.

Pulpit nawigacyjny pokazuje, że agent działa

Pulpit nawigacyjny powinien wskazywać, że agent lub brama działa, zależnie od systemu. Informacja o stanie jest przydatna, ponieważ pokazuje sytuację po stronie serwera, zamiast polegać wyłącznie na aplikacji do komunikacji.

Jeśli pulpit nawigacyjny pokazuje stan zatrzymany lub nieprawidłowy, przed zmianą tokenów lub ustawień modelu sprawdź dzienniki.

Stan pulpitu nawigacyjnego i odpowiedź bota powinny być zgodne. Jeśli jedno działa, a drugie nie, rozbieżność wskazuje, która warstwa zawodzi.

Dzienniki nie zawierają błędów uprawnień ani sieci

Dzienniki nie powinny stale zawierać błędów takich jak odmowa dostępu, nieprawidłowy token, niedostępny dostawca, awaria bramy lub przekroczenie limitu czasu sieci.

Korzystaj z dzienników, aby ustalić następny krok. Błąd uprawnień wskazuje na problem z właścicielem pliku lub użytkownikiem kontenera. Błąd sieci wskazuje na problem z dostępnością API. Błąd tokena wskazuje na problem z konfiguracją danych uwierzytelniających.

Nie próbuj naprawiać wszystkich warstw naraz. Zmień jedną zmienną, w razie potrzeby uruchom usługę ponownie i ponów test.

Rekonfiguracja działa po ponownym uruchomieniu

Trwała konfiguracja powinna przetrwać ponowne uruchomienie lub rekonfigurację. Po zmianie ustawień modelu lub bramy uruchom ponownie wymaganą usługę albo bramę i sprawdź, czy nowe ustawienia nadal obowiązują.

Jeśli ustawienia znikają po ponownym uruchomieniu, sprawdź, gdzie są zapisane dane konfiguracyjne i czy ścieżka danych aplikacji jest trwała.

Właśnie wtedy wiedza o ścieżkach hosta i kontenera oraz zamontowanych woluminach staje się przydatna w praktyce.

Jak to działa w rzeczywistym środowisku domowego serwera

W rzeczywistym środowisku domowego serwera ogólny model konfiguracji pozostaje taki sam: potwierdź warstwę środowiska uruchomieniowego, sprawdź ścieżki danych, zabezpiecz dane uwierzytelniające, skonfiguruj dostęp do bramy i zweryfikuj ustawienia za pomocą dzienników oraz stanu pulpitu nawigacyjnego.

Instrukcja konfiguracji dla konkretnego urządzenia może podać dokładną kolejność poleceń. Na przykład procedura konfiguracji Hermes Agent w ZimaOS opisuje konfigurację Hermes Agent, która obejmuje ustawienia dostawcy modelu, połączenie z botem Telegrama, wejście do kontenera Hermes jako użytkownik aplikacji, aktywację środowiska aplikacji, uruchomienie poleceń konfiguracyjnych, sprawdzenie stanu pulpitu nawigacyjnego oraz rozwiązywanie problemów z uprawnieniami lub brakiem odpowiedzi bota.

Dla użytkowników, którzy uruchamiają samodzielnie hostowane aplikacje, bramy komunikacyjne i lekkie procesy agentów na niewielkim, stale włączonym serwerze, serwer AI do domu ZimaBoard 2 pasuje do środowiska, w którym trzeba rozumieć jednocześnie aplikacje Docker, dostęp do terminala, usługi lokalne i ścieżki danych właściwe dla poszczególnych aplikacji. To nie jedyny sposób na hostowanie agenta, ale trafny przykład domowego serwera i typowego przepływu pracy opisanego w tym artykule.

Najważniejsza wskazówka jest uniwersalna: nie zapamiętuj tylko jednego polecenia konfiguracji. Zrozum, na której warstwie pracujesz i jak zweryfikować rezultat.

Najczęściej zadawane pytania

Czy mogę skonfigurować Hermes Agent wyłącznie za pomocą panelu internetowego?

W wielu przypadkach do podstawowej konfiguracji wystarczy panel internetowy, zwłaszcza jeśli udostępnia ustawienia modelu i bramki. Konfiguracja w terminalu kontenera jest konieczna, gdy panel nie oferuje potrzebnej opcji lub gdy rozwiązywanie problemów wymaga poleceń na poziomie aplikacji. Jeśli to możliwe, zacznij od interfejsu WebUI, a z terminala kontenera korzystaj tylko wtedy, gdy wymaga tego proces konfiguracji.

Dlaczego muszę wejść do kontenera zamiast używać powłoki hosta?

Niektóre polecenia aplikacji są dostępne tylko wewnątrz kontenera, ponieważ właśnie tam znajdują się środowisko uruchomieniowe aplikacji i jej zależności. Uruchomienie tego samego polecenia na hoście może zakończyć się niepowodzeniem lub wpłynąć na niewłaściwe środowisko. Wejście do kontenera jako właściwy użytkownik pomaga upewnić się, że zmiany konfiguracji dotyczą samej aplikacji.

Czym różnią się dane hosta od danych aplikacji w kontenerze?

Dane hosta znajdują się w systemie plików serwera domowego. Dane aplikacji w kontenerze mogą znajdować się w samym kontenerze, w woluminie zarządzanym przez Docker lub w folderze hosta zamontowanym w kontenerze. Ta sama widoczna ścieżka folderu nie musi oznaczać tego samego w warstwie hosta i kontenera, dlatego przed edycją plików sprawdź punkty montowania i lokalizacje danych aplikacji.

Dlaczego Hermes Agent wyświetla błąd uprawnień?

Błąd uprawnień często oznacza, że użytkownik aplikacji nie może odczytać wymaganego pliku lub folderu ani zapisać w nim danych. Może się tak zdarzyć, jeśli pliki zostały utworzone przez użytkownika root, zamontowany folder ma niewłaściwego właściciela lub kontener działa jako inny użytkownik niż oczekiwano. Przed zmianą ogólnych ustawień uprawnień sprawdź warstwę środowiska uruchomieniowego, użytkownika kontenera, ścieżkę danych aplikacji i właściciela plików.

Dlaczego mój bot Telegram nie odpowiada?

Bot Telegram może nie odpowiadać, jeśli token jest nieprawidłowy, identyfikator użytkownika nie znajduje się na liście dozwolonych, bramka nie została uruchomiona ponownie, kontener nie może połączyć się z API Telegrama lub uprawnienia czatu grupowego blokują wiadomość. Najpierw przetestuj czat prywatny, ponieważ pozwala wyeliminować wiele zmiennych związanych z grupami. Następnie sprawdź w logach błędy dotyczące tokena, sieci lub uprawnień.

Czy należy bezpośrednio udostępniać Hermes Agent w internecie?

Bezpośrednie udostępnianie agenta samodzielnie hostowanego w publicznym internecie zwykle nie jest najlepszym rozwiązaniem domyślnym. Bot lub bramka komunikacyjna mogą łączyć się z narzędziami, modelami oraz potencjalnie lokalnymi akcjami środowiska uruchomieniowego, dlatego dostęp należy ograniczyć. Przed rozważeniem konfiguracji dostępnej publicznie zastosuj prywatne sposoby dostępu, silne dane uwierzytelniające, listy dozwolonych oraz restrykcyjne uprawnienia.

Wsparcie i porady

Więcej do przeczytania

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.