Przejdź do treści
Palladin.ioDokumentacja
EN
Dokumentacja/Dla programistów

Podłącz agenta

Jedna procedura dla środowisk obsługujących CLI lub MCP.

1.025.10.2026Markdown ↗

1. Sprawdź wymagania

Potrzebujesz konta Palladin, możliwości zatwierdzenia Agenta oraz dostępu do środowiska, w którym będzie działał runtime. Instalacja programu, rejestracja Agenta i grant do wpisu to trzy oddzielne rzeczy.

palladin --version
palladin doctor
palladin agents list

doctor sprawdza lokalną granicę runtime bez otwierania tożsamości. Nie dowodzi aktywnego połączenia ani uprawnień do wpisu. Jeżeli CLI nie istnieje, przejdź do instalacji.

2. Utwórz i podłącz agenta

Zalecamy parowanie przez panel web. Panel przygotowuje konfigurację, a Ty zatwierdzasz połączenie w przeglądarce. Nie musisz ręcznie przekazywać API key do CLI.

Zalecane: panel web

  1. Otwórz Agenci i wybierz przycisk + („Dodaj agenta”) nad listą.
  2. Przekaż agentowi komunikat wygenerowany przez panel. Zawiera on konfigurację i instrukcję podłączenia.
  3. Agent uruchomi parowanie. Otwórz wskazaną stronę i zatwierdź połączenie.
  4. Sprawdź agenta na liście w panelu oraz jego status w CLI.

Jeżeli wykonujesz polecenia samodzielnie, użyj profilu i danych konfiguracji z panelu:

palladin --id <profile> pair-agent --host <api-origin> --setup-descriptor '<descriptor-from-panel>'
palladin --id <profile> status

Deskryptor konfiguracji nie jest API key. Nie przekazuj modelowi hasła do konta, API key ani klucza odzyskiwania.

Alternatywa: ręczne podłączenie przez API key

  1. W panelu otwórz Ustawienia → Klucze API, wybierz + („Wygeneruj klucz API”), podaj nazwę i zatwierdź formularz. Upewnij się, że pracujesz w odpowiedniej organizacji. Pełna wartość jest pokazywana tylko raz.
  2. Utwórz lokalny profil agenta. example-agent to przykładowa nazwa; wybierz własną, nieużywaną nazwę:
palladin agents create example-agent
  1. Podłącz profil do API tego samego środowiska co panel. Zastąp <api-origin> właściwym adresem API:
palladin --id example-agent connect --host <api-origin>

CLI poprosi o API key w ukrytym monicie. Wprowadź klucz bezpośrednio w terminalu — nie w rozmowie z agentem, argumencie polecenia ani zmiennej środowiskowej.

  1. Potwierdź połączenie i sprawdź, czy agent pojawił się w panelu:
palladin --id example-agent status

Profil przechowuje tożsamość agenta; klucz API uwierzytelnia połączenie z organizacją. Samo podłączenie nie nadaje dostępu do wpisów — wymaga on osobnego grantu.

W automatyzacji CLI przyjmuje klucz przez chronione standardowe wejście z connect --api-key-stdin. Dostarcza go zaufany magazyn sekretów; nie wpisuj wartości klucza do skryptu ani historii powłoki.

Jeżeli profil już istnieje, sprawdź palladin --id <profile> status. Nie twórz go ponownie ani nie usuwaj tożsamości w celu naprawienia błędu. Ten sam profil zachowaj w kolejnych krokach.

3. Korzystaj z CLI

CLI jest zalecaną metodą integracji. Agent wykonuje polecenia w terminalu, wskazując profil przez --id.

Jeśli aplikacja wymaga MCP, dodaj konfigurację serwera. MCP korzysta z zainstalowanego CLI; nie zastępuje jego instalacji ani parowania agenta.

4. Wykonaj test bez sekretu

Utwórz osobny wpis typu API Key z nazwą Palladin connection test i publiczną wartością palladin-connection-test. Nie używaj prawdziwego klucza. Znajdź wpis i użyj zwróconych identyfikatorów:

palladin --id <profile> search 'Palladin connection test' --json
palladin --id <profile> exec <vault-id> <entry-id> --reason 'Verify the connection using a non-secret test entry' --env PALLADIN_TEST=value --wait 2m -- node -e 'process.exit(process.env.PALLADIN_TEST === "palladin-connection-test" ? 0 : 1)'

Użytkownik zatwierdza wąski grant Exec do wpisu testowego, najlepiej na jedno użycie. Proces porównuje wartość i zwraca kod zakończenia; niczego nie wypisuje. W MCP użyj exec_with_credential z poniższymi argumentami (zamień profil i ID):

{"profile":"example-agent","vaultId":"<vault-id>","entryId":"<entry-id>","reason":"Verify the connection using a non-secret test entry","wait":"2m","command":["node","-e","process.exit(process.env.CLAW_SECRET === 'palladin-connection-test' ? 0 : 1)"]}

CLAW_SECRET jest obecną nazwą zmiennej dostarczanej przez runtime; nie zmieniaj jej na podstawie nazwy produktu.

5. Potwierdź wynik

Sukces oznacza aktywną tożsamość, właściwy profil, zatwierdzony dostęp i zakończoną powodzeniem operację testową. Sam widoczny serwer MCP nie wystarcza. Po teście cofnij pozostały grant lub usuń wpis testowy w panelu, jeśli użytkownik nie chce go zachować.

Ten test sprawdza Exec. Nie potwierdza gotowości przeglądarki ani działania Inject.