# Podłącz agenta

> Palladin documentation · 1.0 · PL · 2026-10-25


## 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.

```sh
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](/pl/docs/developers/installation).

## 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](/pl/docs/agents/connect).
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:

```sh
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ę:

```sh
palladin agents create example-agent
```

3. Podłącz profil do API tego samego środowiska co panel. Zastąp `<api-origin>` właściwym adresem API:

```sh
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.

4. Potwierdź połączenie i sprawdź, czy agent pojawił się w panelu:

```sh
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](/pl/docs/developers/mcp). 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:

```sh
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):

```json
{"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`.