Jak działa OpenCode
Architektura klient-serwer, sesje, wbudowani agenci, narzędzia i pętla pracy agenta.
Czym jest OpenCode
OpenCode to open-source'owy agent programistyczny (AI coding agent). Dostajesz interfejs — terminalowy (TUI), desktopowy albo webowy — a agent czyta kod w Twoim projekcie, edytuje pliki, uruchamia komendy, przeszukuje sieć i wykonuje wieloetapowe zadania. Ty opisujesz cel w języku naturalnym, agent sam dobiera narzędzia i prosi o zatwierdzenie tam, gdzie wymagają tego uprawnienia.
Kluczowa cecha: OpenCode nie jest związany z jednym modelem. Korzysta z ponad 75 dostawców (Anthropic, OpenAI, Google, lokalne modele itd.), a bieżący model możesz przełączyć w dowolnym momencie sesji.
Ten kurs dotyczy OpenCode V2 (opencode.ai/v2/docs). V1 ma inną składnię konfiguracji — jeśli migrujesz stare pliki, sprawdź przewodnik migracji V1 → V2.
Architektura: klient i usługa w tle
OpenCode działa w modelu klient–serwer. To, co widzisz w terminalu (TUI), jest klientem, który łączy się z działającą w tle usługą OpenCode. Usługa jest właścicielem stanu: sesji, konfiguracji, pluginów, reguł uprawnień i wykonania narzędzi.
Dzięki temu możesz mieć kilka klientów podłączonych do tej samej usługi (np. TUI i aplikację webową otwartą przez opencode pair), a sesje przeżywają zamknięcie terminala.
- opencode service status — sprawdź, czy usługa działa
- opencode service restart — zrestartuj usługę, gdy coś się zawiesi
- opencode --standalone — TUI z prywatną usługą, przydatne do debugowania
- Logi: ~/.local/share/opencode/log/opencode.log
opencode service status
opencode api get /api/infoSesje — podstawowa jednostka pracy
Wszystko, co robisz z agentem, dzieje się w sesjach. Sesja ma własną historię, wybrany agent, model i katalog roboczy. Możesz mieć wiele sesji naraz — jako zakładki w TUI — i przełączać się między nimi.
Sesje można: zmienić imię (session_rename), przenieść do innego katalogu (session_move), rozgałęzić od wybranego momentu (fork), a także cofnąć ostatnie zmiany agenta razem ze zmianami w plikach (undo/redo oparte na snapshotach systemu plików).
| Skrót | Działanie |
|---|---|
| ctrl+o | Otwórz listę ostatnich sesji i projektów |
| ctrl+x n (leader+n) | Nowa sesja |
| ctrl+x l (leader+l) | Lista wszystkich sesji |
| ctrl+tab | Następna zakładka sesji |
| ctrl+x u / ctrl+x r | Undo / redo ostatniej tury (zmiany w plikach wracają!) |
| escape | Przerwij bieżące działanie agenta |
| ctrl+x c | Ręczne kompaktowanie kontekstu |
| ctrl+p | Paleta komend — znajdź każdą akcję |
Zaczynasz nowe, niepowiązane zadanie? Otwórz nową sesję (leader+n). Krótka, skupiona historia = lepsze odpowiedzi i tańsze tokeny.
Wbudowani agenci
Agent to profil: prompt systemowy + model + uprawnienia + tryb pracy. OpenCode startuje z czwórką widocznych agentów. Przełączasz ich skrótem shift+tab (kolejny agent) albo ctrl+x a (lista).
Agenci primary prowadzą sesję; subagent odpala się w sesji podrzędnej, gdy poprosisz lub gdy użyjesz narzędzia subagent. Przykład: poproś „Użyj subagenta explore, żeby zmapować proces logowania i zwrócić kluczowe pliki”. Agent macierzysty dostanie podsumowanie, a jego kontekst pozostanie czysty.
| Agent | Tryb | Do czego służy |
|---|---|---|
| build | primary | Domyślny agent programistyczny — pełen dostęp do narzędzi, wrażliwe operacje pytają o zgodę |
| plan | primary | Eksploracja i planowanie bez edycji plików projektu (zapiski pisze tylko do ~/.opencode/plan) |
| general | subagent | Badania i wieloetapowe zadania w sesji dziecka; nie uruchamia kolejnych subagentów |
| explore | subagent | Szybkie przeszukiwanie kodu i sieci tylko do odczytu |
Są też agenci ukryci: compaction, title i summary — dbają o streszczanie kontekstu, tytuły sesji i podsumowania. Nie da się ich wybrać ręcznie.
Narzędzia, których używa agent
Agent nie „ klika ” w system — używa narzędzi (tools). Znasz je z komunikatu o uprawnieniach przy każdym użyciu. Nie musisz ich wywoływać ręcznie, ale warto wiedzieć, co agent może zrobić; możesz też wskazać narzędzie w prompcie („użyj grep, żeby znaleźć wszystkie odwołania do DEFAULT_TIMEOUT”).
| Narzędzie | Rola |
|---|---|
| read | Odczyt pliku (także obrazy i PDF) lub listing katalogu |
| glob | Szukanie plików po wzorcu, np. **/*.ts |
| grep | Przeszukiwanie zawartości plików (regex) |
| edit / write / patch | Celowa wymiana tekstu / utworzenie pliku / patch wieloplikowy |
| shell | Komendy w powłoce hosta (testy, git, buildy); tryb tła dla serwerów dew |
| webfetch / websearch | Pobranie URL-a / wyszukiwanie w sieci |
| question | Zadanie Ci pytania z opcjami odpowiedzi |
| skill | Doładowanie instrukcji skillu do rozmowy |
| subagent | Uruchomienie agenta podrzędnego (przód lub tło) |
| execute | Code Mode — skrypt JS łączący wiele wywołań narzędzi naraz |
| browser | Sterowanie przeglądarką (aplikacja desktopowa) |
shell działa z uprawnieniami Twojego użytkownika systemu. To najsilniejsze narzędzie — ogranicz je regułami uprawnień (rozdział 8).
Pętla pracy agenta
Każde zgłoszenie (prompt) przechodzi przez tę samą pętlę: tekst trafia do usługi → model dostaje kontekst (instrukcje AGENTS.md, lista skilli, historia) → model odpowiada tekstem lub żądaniem użycia narzędzia → OpenCode sprawdza uprawnienia (allow / ask / deny) → wynik narzędzia wraca do modelu → krok powtarza się, aż zadanie jest skończone.
Jeśli reguły dają effect: ask, agent staje i czeka na Twoją decyzję: raz / zawsze / odrzuć. Zatwierdzone „zawsze” zapisuje się jako regułę dla projektu — przeglądaj je co jakiś czas.
- Możesz dorzucić kolejny prompt w trakcie pracy — trafi do kolejki (leader+Enter) albo sterowania na żywo.
- escape przerywa bieżący krok bez utraty historii.
- Gdy kontekst modelu się zapełnia, OpenCode automatycznie kompaktuje historię (streszcza starsze tury). Parametry: compaction w opencode.jsonc.
Modele i warianty w locie
Model wybierasz na stałe w konfiguracji (pole model w formacie dostawca/model), ale w sesji przełączasz go od ręki: ctrl+x m (lista modeli), F2 (kolejny ostatnio używany), ctrl+t (warianty modelu, np. higher effort rozumowania). Ulubione oznaczasz ctrl+f w oknie modeli.
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5",
"default_agent": "build",
"compaction": { "auto": true }
}Podsumowanie rozdziału
- OpenCode = klient (TUI/desktop/web) + usługa w tle władająca sesjami i narzędziami.
- Pracujesz w sesjach; zakładki, undo/redo ze snapshotami, fork i przenoszenie są na wyciągnięcie skrótów.
- Agenci: build, plan (primary) oraz general, explore (subagent); narzędzia od read/grep po shell i browser.
- Model i agent to wybór „na teraz” — zmieniaj śmiało w trakcie sesji.
- Dalej: instrukcje projektowe w AGENTS.md (rozdział 2) i przećwiczone procedury w skillach (rozdział 3).