Jak zainstalować OpenCode na VPS krok po kroku

Czym jest OpenCode i co konfigurujemy

OpenCode to otwartoźródłowy agent programistyczny AI 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 udostępniony na licencji MIT, łączy się z ponad 75 dostawcami modeli, a z liczbą około 165,000 gwiazdek w serwisie GitHub na połowę 2026 roku, jest najpopularniejszym otwartoźródłowym agentem programistycznym. Aby uruchomić OpenCode na serwerze VPS, należy zainstalować go na dedykowanym użytkowniku bez uprawnień roota, umieścić klucz API modelu w prywatnym pliku i uruchomić narzędzie wewnątrz tmux, aby sesja była podtrzymywana po zerwaniu połączenia. Niniejszy przewodnik opisuje dokładnie ten proces, w podanej kolejności.

Jedna uwaga dotycząca nazewnictwa pozwala 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. W serwisie GitHub istnieje również starsze, niezwiązane z tym projektem repozytorium o nazwie opencode-ai/opencode, dlatego należy upewnić się, że korzysta się 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

Oto uczciwy punkt wyjścia: agent programistyczny edytuje pliki i wykonuje polecenia. Jest to jego zadanie, ale stanowi również ryzyko. OpenCode będzie uruchamiać kompilacje, testy oraz wszelkie polecenia powłoki, które wydają się niezbędne do wykonania zadania, a ocena modelu jest dobra, lecz nie bezbłędna. Konto, na którym działa agent, stanowi górną granicę tego, do czego może dotrzeć 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 potrzebuje rzeczywistej 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, będzie mógł zniszczyć jedynie to, co należy 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, ponieważ repozytorium zamienia każdą błędną edycję w git revert, zamiast w trwałą utratę danych.

Instalacja OpenCode

Projekt dokumentuje dwie metody instalacji. Skrypt instalacyjny jest najszybszy, a uruchomienie go jako użytkownik opencode pozwala zachować wszystkie pliki w katalogu domowym tego użytkownika:

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

W tym przypadku, podobnie jak wszędzie indziej, obowiązuje standardowa zasada curl | bash: na serwerze, którego bezpieczeństwo jest istotne, należy najpierw pobrać skrypt, przeczytać go, a dopiero potem uruchomić. Po zakończeniu instalacji należy otworzyć nową powłokę, aby zmiany w zmiennej PATH wprowadzone przez instalator stały się aktywne, a następnie sprawdzić działanie pliku binarnego:

opencode --version

Jeśli preferowany jest menedżer pakietów, a środowisko Node.js jest już zainstalowane w systemie, metoda z użyciem npm zainstaluje to samo narzędzie globalnie, co udostępni plik binarny opencode w zmiennej PATH dla wszystkich użytkowników:

sudo npm install -g opencode-ai

Niezależnie od metody, 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 wczytała jeszcze zaktualizowanej zmiennej PATH, dlatego należy wylogować się i zalogować ponownie jako użytkownik 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. Najszybszą metodą jest użycie polecenia /connect wewnątrz TUI, które wyświetla listę dostawców i obsługuje poświadczenia. W przypadku konfiguracji, którą można zatwierdzić w repozytorium i odtworzyć, należy umieścić plik opencode.json w katalogu głównym projektu i ustawić model jako provider/model-id:

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

Model lokalny działa w oparciu o ten sam plik, ponieważ każdy serwer zgodny z OpenAI może zostać zadeklarowany jako dostawca. Jeśli model jest udostępniany przez Ollama na tym samym VPS, konfiguracja wskazuje na jego lokalne API, a nazwa modelu jest zgodna z tym, co wyświetla ollama list w Twoim systemie:

{
  "$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 pierwszego dnia przyjąć jeden wbudowany nawyk. OpenCode dostarcza dwa agenty, między którymi przełączasz się klawiszem Tab: Build, domyślny agent z pełnym dostępem, oraz Plan, który wyłącza możliwość wprowadzania zmian. Rozpocznij nowe zadanie w trybie Plan, pozwól agentowi odczytać kod i zaproponować podejście, a przełącz się na Build dopiero wtedy, gdy zaakceptujesz plan. Na serwerze pierwszy przebieg w trybie tylko do odczytu stanowi tanie zabezpieczenie. Claude Code definiuje tę samą decyzję jako tryby uprawnień, a nie agenty, i warto zapoznać się z informacjami 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 duże zmiany może wprowadzić nieobserwowany agent.

Zasięg potencjalnych szkód

Agent programistyczny nie jest narzędziem pasywnym, dlatego należy jasno określić zakres jego uprawnień. Narzędzie to może spowodować uszkodzenie plików: użytkownik opencode jest właścicielem swojego katalogu domowego i żadnych innych zasobów, więc edycja oraz usuwanie plików są ograniczone do tego obszaru. Istnieje ryzyko ujawnienia danych uwierzytelniających: klucz znajduje się w jednym pliku z uprawnieniami 600, przypisanym do jednego konta. Narzędzie nie ogranicza działań, do których konto jest uprawnione, więc jeśli w katalogu projektu znajdują się dane uwierzytelniające do wdrożeń produkcyjnych, agent może z nich skorzystać; należy przechowywać takie dane całkowicie poza kontem agenta.

W przeciwieństwie do agenta typu gateway, takiego jak OpenClaw, OpenCode jest interaktywnym programem terminalowym, a nie demonem. Nie otwiera portów nasłuchujących i nie działa jako usługa w tle, dlatego nie wymaga tworzenia jednostki systemd ani konfiguracji firewalla dla samego agenta. Izolacja opiera się na koncie użytkownika i katalogu projektu, dlatego pierwsza sekcja tego przewodnika jest najważniejsza.

Środowisko nadal wymaga standardowych zabezpieczeń, ponieważ VPS z agentem programistycznym pozostaje serwerem publicznym: należy stosować logowanie SSH wyłącznie przy użyciu kluczy z wyłączonym dostępem dla root, zgodnie z utwardzanie SSH na VPS, domyślnie odrzucającą polityką firewalla oraz regularnymi aktualizacjami. Należy również weryfikować działania agenta. Przed wypchnięciem zmian należy przejrzeć diffy, tak samo jak w przypadku pull requesta od nowego współpracownika, ponieważ to użytkownik odpowiada za wdrożenie efektów pracy agenta.

Na koniec należy dbać o aktualność samego narzędzia. OpenCode często publikuje nowe wersje, a aktualizacje zawierają poprawki istotne dla programu wykonującego polecenia na serwerze. Aktualizację przeprowadza się w ten sam sposób, co instalację: należy ponownie uruchomić skrypt instalacyjny jako użytkownik opencode lub wykonać sudo npm update -g opencode-ai, jeśli instalacja odbyła się przez npm, a następnie potwierdzić nową wersję za pomocą opencode --version. Chwila konserwacji jest mniej kosztowna niż debugowanie zachowań, które zostały już naprawione w nowszych wersjach oprogramowania.

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ł: zadeklaruj 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, więc przed pobraniem modelu należy odpowiednio dobrać parametry serwera.

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

Uruchom go wewnątrz tmux na serwerze VPS. Uruchom agenta w nazwanej sesji za pomocą tmux new -s opencode, odłącz się skrótem Ctrl-b, a następnie d; sesja będzie nadal działać na serwerze po zakończeniu połączenia SSH. W dowolnym momencie możesz powrócić do sesji za pomocą tmux attach -t opencode, gdzie konwersacja oraz wszelkie uruchomione zadania będą nadal dostępne. Restart serwera kończy sesję, więc po ponownym uruchomieniu należy rozpocząć nową.

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

Jest to możliwe do opanowania przy odpowiedniej izolacji. Przypisz OpenCode dedykowanego użytkownika bez uprawnień sudo, przechowuj projekty w git, aby każda edycja była odwracalna, przechowuj klucz API w pliku o uprawnieniach 600 i używaj agenta Plan do wstępnej analizy w trybie tylko do odczytu, zanim pozwolisz agentowi Build na wprowadzenie jakichkolwiek zmian. Agent może wtedy uszkodzić jedynie zasoby należące do jego konta, a reszta serwera pozostaje poza jego zasięgiem.

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 wokół modeli Anthropic. Jeśli potrzebujesz jednego narzędzia do obsługi wielu dostawców lub w pełni samodzielnie hostowanego stosu 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ń.