Jak zainstalować OpenCode na VPS krok po kroku

Czym jest OpenCode i co konfigurujesz

OpenCode to otwartoźródłowy agent AI do programowania, przeznaczony do pracy w terminalu. Uruchamia się go wewnątrz katalogu projektu, gdzie narzędzie analizuje kod, proponuje zmiany, edytuje pliki i wykonuje polecenia, a wszystko to z poziomu interfejsu terminalowego (TUI). Projekt jest objęty licencją MIT, łączy się z ponad 75 dostawcami modeli i z liczbą około 219 000 gwiazdek w serwisie GitHub (stan na październik 2026 r.) jest najpopularniejszym otwartoźródłowym agentem programistycznym. Aby uruchomić OpenCode na serwerze VPS, należy zainstalować go na dedykowanym koncie użytkownika bez uprawnień roota, umieścić klucz API modelu w prywatnym pliku i uruchomić narzędzie wewnątrz tmux, aby sesja była aktywna po rozłączeniu. Ten przewodnik opisuje właśnie ten proces, krok po kroku.

Warto wyjaśnić kwestię nazewnictwa, aby uniknąć nieporozumień. Kanoniczne repozytorium to anomalyco/opencode, utrzymywane przez zespół Anomaly (wcześniej znany jako SST), a projekt był wcześniej dostępny pod adresem sst/opencode. Istnieje również starsze, niezwiązane z tym projektem repozytorium o nazwie opencode-ai/opencode, które jest obecnie zarchiwizowane, dlatego należy upewnić się, że korzystasz z dokumentacji właściwego projektu. Oficjalna strona to opencode.ai.

Dlaczego warto uruchamiać OpenCode na VPS

Sesja agenta programistycznego trwa długo. OpenCode może poświęcić wiele minut na refaktoryzację lub uruchomienie zestawu testów. Jeśli proces działa na laptopie, zamknięcie pokrywy lub zerwanie połączenia Wi-Fi przerywa sesję w trakcie zadania. Na VPS wewnątrz tmux agent kontynuuje pracę po rozłączeniu, a użytkownik może później powrócić do sesji, aby sprawdzić wyniki. Jest to ten sam schemat, co w przypadku uruchamiania Claude Code na VPS z użyciem tmux, i stanowi najważniejszą poprawę komfortu pracy wynikającą z przeniesienia agenta z laptopa.

Drugim powodem jest lokalizacja. VPS znajduje się blisko wdrażanego kodu: repozytorium, narzędzia budowania, baza testowa oraz środowisko stagingowe często działają na tym samym serwerze lub w jego bezpośrednim sąsiedztwie. Agent, który edytuje kod i uruchamia testy, działa najefektywniej na maszynie, na której te testy są faktycznie wykonywane. Ponieważ jest to serwer pod pełną kontrolą administratora, można celowo zapewnić agentowi odizolowane środowisko, co opisano w kolejnej sekcji.

Jeśli wybór narzędzia jest nadal w toku, uruchamianie agenta AI do programowania na VPS zawiera porównanie szerszego spektrum rozwiązań, w tym Aider oraz Goose.

Nadanie OpenCode własnego użytkownika

Punktem wyjścia jest założenie, że agent programistyczny edytuje pliki i wykonuje polecenia. Jest to jego zadanie, ale stanowi również ryzyko. OpenCode uruchamia procesy budowania, testy oraz dowolne polecenia powłoki wymagane przez zadanie, a ocena modelu jest wysoka, lecz nie bezbłędna. Konto, na którym działa agent, wyznacza zakres uprawnień, do których może sięgnąć błędne polecenie, dlatego nie należy uruchamiać go jako root ani jako użytkownik administrujący serwerem.

W przeciwieństwie do agenta działającego w tle, OpenCode jest interaktywny, więc jego użytkownik wymaga poprawnej powłoki oraz katalogu domowego:

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

Projekty, nad którymi ma pracować agent, należy przechowywać w /home/opencode i klonować z poziomu tego użytkownika. Nie należy nadawać temu kontu żadnych uprawnień sudo. Jeśli agent wykona destrukcyjne polecenie, może uszkodzić jedynie zasoby należące do tego konta, co jest zgodne z zasadą uruchamiania usług jako użytkownik bez uprawnień. Należy również pracować wewnątrz repozytorium git i wykonywać commit przed przekazaniem agentowi zadania, ponieważ błędna edycja zatwierdzonej pracy jest wtedy możliwa do cofnięcia za pomocą git revert lub git restore, zamiast prowadzić do utraty danych. Zmiany, które nie zostały zatwierdzone, nie podlegają ochronie.

Instalacja OpenCode

Dokumentacja projektu opisuje kilka metod instalacji, z których dwie są odpowiednie dla serwera. Skrypt instalacyjny jest najszybszą metodą, a uruchomienie go jako użytkownik opencode pozwala zachować wszystkie pliki wewnątrz katalogu domowego tego użytkownika:

curl -fsSL https://opencode.ai/install | bash

Obowiązuje tu standardowa zasada curl | bash, tak jak w każdym innym przypadku: na serwerze, na którym Ci zależy, najpierw pobierz skrypt, przeczytaj go, a dopiero potem uruchom. Po instalacji otwórz nową powłokę, aby zmiany w zmiennej PATH wprowadzone przez instalator zostały uwzględnione, a następnie sprawdź działanie pliku binarnego:

opencode --version

Jeśli preferujesz menedżer pakietów, a na serwerze zainstalowano już Node.js, metoda npm zainstaluje to samo narzędzie w globalnym prefiksie npm:

sudo npm install -g opencode-ai

W przypadku systemowego Node.js prefiks ten to zazwyczaj /usr/local lub /usr, którego katalog bin znajduje się w zmiennej PATH każdego użytkownika. Menedżer wersji lub niestandardowy prefiks umieszcza plik binarny w innej lokalizacji, więc jeśli potrzebujesz, aby opencode było widoczne dla użytkownika opencode, najpierw uruchom npm prefix -g.

W obu przypadkach weryfikacja jest taka sama: opencode --version wyświetla numer wersji. Błąd command not found po instalacji skryptem oznacza, że bieżąca powłoka nie odczytała jeszcze zaktualizowanej zmiennej PATH, więc wyloguj się i zaloguj ponownie jako użytkownik opencode.

Oba polecenia instalują linię OpenCode 1.x, która nadal otrzymuje wydania (1.19.3 w dniu 16 października 2026 r.), i to właśnie tę linię opisuje niniejszy przewodnik. OpenCode 2 jest już dostępny jako osobna instalacja, z https://opencode.ai/v2/install lub pakietu npm @opencode/cli, i działa inaczej: współdzielony serwer działający w tle dla każdego konta użytkownika zarządza sesjami, uprawnieniami i wykonywaniem narzędzi, a terminal łączy się z nim. Przewodnik migracji zaleca usunięcie instalacji 1.x zarządzanej przez pakiet przed instalacją wersji 2, ponieważ obie używają polecenia opencode.

Umieszczenie klucza API w prywatnym pliku

OpenCode wymaga klucza dla wybranego dostawcy modelu, a ponieważ klucz ten umożliwia generowanie kosztów, należy traktować go jak hasło. Utwórz plik, który może odczytać wyłącznie użytkownik opencode, ustawiając uprawnienia 600. Przechowuj w nim klucz zamiast wpisywać go bezpośrednio w poleceniach, co spowodowałoby zapisanie go w historii powłoki:

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

Umieść w pliku zmienną swojego dostawcy, na przykład ANTHROPIC_API_KEY=... lub jej odpowiednik, ponieważ OpenCode automatycznie odczytuje standardowe zmienne środowiskowe dostawców. Przed uruchomieniem agenta załaduj plik do powłoki:

set -a; source ~/opencode.env; set +a

OpenCode oferuje również interaktywną alternatywę: polecenie /connect wewnątrz TUI przeprowadza użytkownika przez proces dodawania dostawcy i zapisuje poświadczenia w pliku ~/.local/share/opencode/auth.json w katalogu domowym użytkownika. Jeśli wybierzesz tę metodę, upewnij się za pomocą polecenia chmod 600 ~/.local/share/opencode/auth.json, że plik jest prywatny. Obie metody chronią klucz przed zapisaniem w historii poleceń; wybierz jedną z nich i stosuj ją konsekwentnie.

Uruchamianie OpenCode wewnątrz tmux

Narzędzie tmux sprawia, że konfiguracja VPS staje się użyteczna, ponieważ sesja tmux pozostaje aktywna po zakończeniu połączenia SSH. Należy uruchomić sesję, przejść do katalogu projektu i uruchomić agenta:

tmux new -s opencode
cd ~/my-project
opencode

Powinien pojawić się interfejs TUI z wierszem poleceń na dole oraz nazwą projektu w interfejsie. Należy wprowadzić zadanie w języku naturalnym, a agent rozpocznie analizę plików i zaproponuje zmiany. Aby opuścić sesję, należy ją odłączyć za pomocą kombinacji Ctrl-b, a następnie d; agent będzie kontynuował pracę nawet po zamknięciu laptopa. Ponowne podłączenie odbywa się za pomocą:

tmux attach -t opencode

Sesja, konwersacja oraz wszelkie uruchomione zadania pozostają w dokładnie tym samym stanie. Sesja przetrwa rozłączenia, ale nie restart serwera; po restarcie należy uruchomić nową sesję tmux w ten sam sposób. Nic nie stoi na przeszkodzie, aby otworzyć drugie okno tmux i uruchomić kolejnego agenta obok pierwszego, jednak sesje OpenCode pozostają od siebie niezależne, podczas gdy sesje Claude Code na tym samym serwerze mogą przesyłać sobie wiadomości, co stanowi inny sposób podziału pracy na części.

Wskazanie modelu

OpenCode jest niezależny od dostawcy. Wykorzystuje AI SDK oraz katalog Models.dev do obsługi ponad 75 dostawców, dzięki czemu to samo narzędzie współpracuje z Anthropic, OpenAI, Google i dziesiątkami innych, w tym z serwerami lokalnymi. Szybką metodą jest polecenie /connect wewnątrz TUI, które wyświetla listę dostawców i obsługuje poświadczenia. W celu uzyskania konfiguracji, którą można zatwierdzić i odtworzyć, umieść plik opencode.json w katalogu głównym projektu i ustaw model jako provider/model-id:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5"
}

Wybierz model, który jest nadal obsługiwany przez Twojego dostawcę: Anthropic wycofał claude-sonnet-4-20250514 w dniu 15 czerwca 2026 r., więc konfiguracje, które nadal go wskazują, zakończą się błędem.

Model lokalny działa za pośrednictwem tego samego pliku, ponieważ każdy serwer zgodny z OpenAI można zadeklarować jako dostawcę. Jeśli udostępniasz model za pomocą Ollama na tym samym VPS, konfiguracja wskazuje na jego lokalne API, a nazwa modelu jest taka, jaką wyświetla ollama list na Twoim serwerze:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

Warto od samego początku przyjąć jeden wbudowany nawyk. OpenCode dostarcza dwóch agentów, między którymi przełączasz się klawiszem Tab: Build, domyślny agent z pełnym dostępem, oraz Plan, ograniczony agent do analizy, który odmawia edycji plików poza własnym katalogiem planu bez pytania o zgodę. Plan nie jest jednak ściśle tylko do odczytu, ponieważ nadal może uruchamiać polecenia powłoki, a polecenie powłoki może zmieniać pliki. Rozpocznij nowe zadanie w trybie Plan, pozwól mu odczytać kod i zaproponować podejście, a na Build przełącz się dopiero wtedy, gdy zaakceptujesz plan. Jeśli chcesz, aby pierwszy etap był w pełni tylko do odczytu, zablokuj edycję i polecenia powłoki dla Plan w opencode.json, ponieważ OpenCode traktuje deny jako blokadę akcji, podczas gdy ask jedynie prosi o zatwierdzenie:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

Na serwerze pierwszy etap, który nie może niczego zmienić, stanowi tanie zabezpieczenie. Claude Code definiuje tę samą decyzję jako tryby uprawnień, a nie jako agentów, i warto przeczytać o jego przejściu na tryb automatyczny jako domyślny, jeśli używasz obu narzędzi, ponieważ tryb, w którym uruchamia się sesja, decyduje o tym, jak wiele może zmienić nieobserwowany agent.

Promień rażenia, szczerze mówiąc

Agent programistyczny nie jest pasywny, dlatego należy jasno określić, co ta konfiguracja zawiera, a czego nie. Zawiera ryzyko uszkodzenia plików: użytkownik opencode jest właścicielem własnego katalogu domowego i niczego więcej, więc edycja i usuwanie plików kończą się na tej granicy. Zawiera ryzyko ujawnienia poświadczeń: klucz znajduje się w jednym pliku z uprawnieniami 600, w jednym koncie. Nie zawiera natomiast ograniczeń tego, co konto może legalnie wykonać, więc jeśli katalog projektu zawiera poświadczenia wdrożeniowe dla środowiska produkcyjnego, agent może z nich skorzystać; należy trzymać je całkowicie poza kontem agenta.

W przeciwieństwie do agenta bramy, takiego jak OpenClaw, OpenCode 1.x jest interaktywnym programem terminalowym, a nie daemonem. Domyślnie nie otwiera żadnego portu nasłuchującego (tylko flagi --port, --hostname lub --mdns sprawiają, że TUI nasłuchuje) i nie posiada długo działającej usługi, więc nie ma jednostki systemd do utworzenia ani portu do zabezpieczenia firewallem dla samego agenta. OpenCode 2 zmienia to za sprawą współdzielonego serwera działającego w tle, dlatego należy ponownie sprawdzić ten punkt przed migracją. Kontenerem jest konto użytkownika oraz katalog projektu, dlatego pierwsza sekcja tego przewodnika jest najważniejsza.

Otoczenie nadal wymaga standardowej dbałości, ponieważ VPS z agentem programistycznym pozostaje serwerem publicznym: dostęp SSH wyłącznie przez klucze z wyłączonym logowaniem root, zgodnie z utwardzanie SSH na VPS, domyślnie odrzucający firewall oraz regularne aktualizacje. Należy również weryfikować to, co generuje agent. Czytaj jego diffy przed wypchnięciem zmian, w taki sam sposób, w jaki czytałbyś pull request od nowego kontrybutora, ponieważ to Ty wdrażasz wynik końcowy.

Na koniec, dbaj o aktualność samego narzędzia. OpenCode wydaje wersje często, a aktualizacje zawierają poprawki istotne dla programu, który wykonuje polecenia na Twoim serwerze. Aktualizacja odbywa się tą samą drogą, co instalacja: uruchom ponownie skrypt instalacyjny jako użytkownik opencode lub wykonaj sudo npm update -g opencode-ai, jeśli instalacja odbyła się przez npm, a następnie potwierdź nową wersję za pomocą opencode --version. Obie metody utrzymują Cię w linii 1.x; przejście na OpenCode 2 to osobna migracja. Minuta konserwacji od czasu do czasu jest tańsza niż debugowanie zachowania, które zostało już naprawione w kompilacji sprzed kilku miesięcy.

FAQ

Czy OpenCode może korzystać z modelu lokalnego zamiast płatnego API?

Tak. OpenCode traktuje każdy serwer zgodny z OpenAI jako dostawcę, więc model udostępniany przez Ollama na tym samym VPS będzie działał: należy zadeklarować dostawcę w opencode.json za pomocą lokalnego baseURL oraz nazwy modelu zgłaszanej przez Ollama. Ograniczeniem jest sprzęt, ponieważ model wystarczająco wydajny do pracy programistycznej wymaga znacznej ilości pamięci, dlatego przed pobraniem modelu należy odpowiednio dobrać parametry serwera.

Jak utrzymać działanie OpenCode po zamknięciu laptopa?

Należy uruchomić go wewnątrz tmux na serwerze VPS. Agent powinien zostać uruchomiony w nazwanej sesji za pomocą tmux new -s opencode, a następnie odłączony skrótem Ctrl-b, a po nim d. Dzięki temu sesja pozostanie aktywna na serwerze po zakończeniu połączenia SSH. Powrót do sesji w dowolnym momencie jest możliwy za pomocą tmux attach -t opencode, gdzie konwersacja oraz wszystkie uruchomione zadania będą nadal dostępne. Restart serwera kończy sesję, dlatego po ponownym uruchomieniu należy rozpocząć nową.

Czy zezwalanie OpenCode na wykonywanie poleceń na moim VPS jest bezpieczne?

Jest to bezpieczne, o ile zastosuje się odpowiednią izolację. Należy przydzielić OpenCode dedykowanego użytkownika bez uprawnień sudo, przechowywać projekty w git i wykonywać commit przed każdym zadaniem, aby umożliwić wycofanie błędnych zmian. Klucz API należy przechowywać w pliku o uprawnieniach 600, a przed zezwoleniem agentowi Build na wprowadzanie zmian, warto użyć agenta Plan do wstępnej weryfikacji. Jeśli faza planowania ma być wyłącznie do odczytu, należy ustawić edycję i polecenia powłoki na deny dla Plan. W ten sposób agent może uszkodzić jedynie zasoby należące do jego własnego konta, a reszta serwera pozostaje zabezpieczona.

Jaka jest różnica między OpenCode a Claude Code?

OpenCode jest oprogramowaniem typu open source (licencja MIT) i jest niezależny od dostawcy, łącząc się z ponad 75 dostawcami modeli, w tym lokalnymi, za pośrednictwem jednego interfejsu. Claude Code to terminalowy agent firmy Anthropic, zbudowany w oparciu o modele Anthropic. Jeśli celem jest używanie jednego narzędzia z wieloma dostawcami lub w pełni samodzielnie hostowany stos z modelem lokalnym, OpenCode będzie odpowiednim wyborem. Oba narzędzia działają poprawnie na VPS wewnątrz tmux przy zastosowaniu tej samej konfiguracji z użytkownikiem bez uprawnień.