Kluczowe wnioski

• Wiele ścieżek instalacji: npm, Homebrew, skrypt curl, Go install, Docker oraz budowanie ze źródła — wybierz tę, która pasuje do Twojego zestawu narzędzi.
• Pięć minut do pierwszego uruchomienia: Najszybsza ścieżka (skrypt instalacyjny curl) pozwala uruchomić OpenCode w mniej niż pięć minut na dowolnym systemie Unix.
• Niezależność od dostawcy: OpenCode współpracuje z OpenAI, Google Gemini, lokalnymi modelami Ollama i innymi — nie jesteś ograniczony do jednego dostawcy AI.
• Minimalna konfiguracja: Pojedynczy plik config.toml i jedna zmienna środowiskowa to wszystko, czego potrzebujesz, aby zacząć kodować z AI w swoim terminalu.

Jak zainstalować OpenCode: Przewodnik konfiguracji krok po kroku (2026)

OpenCode to otwartoźródłowy agent AI do kodowania zbudowany dla terminala. Przenosi on moc dużych modeli językowych bezpośrednio do Twojego wiersza poleceń, umożliwiając pisanie, refaktoryzację, debugowanie i rozumienie kodu bez opuszczania edytora lub przepływu pracy w terminalu.

Niezależnie od tego, czy konfigurujesz OpenCode po raz pierwszy, czy migrujesz z innego narzędzia AI do kodowania, ten przewodnik przeprowadzi Cię przez każdą metodę instalacji, wstępną konfigurację, ustawienia dostawcy i kroki rozwiązywania problemów, których będziesz potrzebować.

---

Wymagania wstępne

Przed instalacją OpenCode upewnij się, że Twój system spełnia następujące wymagania.

System operacyjny

OpenCode działa na macOS, Linux i Windows. Dla użytkowników Windows zdecydowanie zalecane jest WSL (Windows Subsystem for Linux). Dostępne jest również natywne wsparcie dla Windows poprzez Scoop.

Wymagania środowiskowe (zależą od metody instalacji)

Metoda instalacji	Wymaganie
npm	Node.js 18 lub nowszy
Homebrew	macOS lub Linux z zainstalowanym Homebrew
Skrypt curl	bash, curl
Go install	Go 1.22 lub nowszy
Docker	Docker Engine 20+
Budowanie ze źródła	Go 1.22+, Git

Wymagania terminala

OpenCode oferuje TUI (Terminal User Interface), więc Twój emulator terminala musi obsługiwać true color oraz poprawne renderowanie Unicode. Większość nowoczesnych terminali (iTerm2, Alacritty, WezTerm, Windows Terminal, Ghostty) działa bez dodatkowej konfiguracji. Starsze terminale, takie jak domyślny macOS Terminal.app, mogą mieć problemy z renderowaniem.

Sprawdź wersję Node.js:

node --version

Sprawdź wersję Go (jeśli używasz metody Go install):

go version

---

Metoda 1: Skrypt instalacyjny (Najszybsza)

Oficjalny skrypt instalacyjny to najszybszy sposób na uruchomienie OpenCode. Wykrywa on Twój system operacyjny i architekturę, pobiera odpowiedni plik binarny i umieszcza go w Twojej ścieżce PATH.

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

To jedno polecenie zajmuje się wszystkim. Po jego zakończeniu zweryfikuj instalację:

opencode --version

Ta metoda działa na macOS i Linux. Nie wymaga Node.js ani Go.

---

Metoda 2: Instalacja przez npm

Jeśli masz już Node.js w swoim przepływie pracy, npm jest najbardziej znaną opcją.

npm install -g opencode-ai@latest

Nazwa pakietu w npm to opencode-ai, a nie opencode. Jest to częste źródło nieporozumień.

Aby zweryfikować:

opencode --version

Jeśli napotkasz błędy uprawnień, napraw uprawnienia swojego globalnego katalogu npm lub użyj npx, aby uruchomić go bez globalnej instalacji:

npx opencode-ai@latest

---

Metoda 3: Homebrew (macOS i Linux)

Użytkownicy Homebrew mogą zainstalować OpenCode z oficjalnego repozytorium (tap):

brew install anomalyco/tap/opencode

Zainstaluje to najnowszą stabilną wersję i umożliwi aktualizacje poprzez brew upgrade.

Aby zweryfikować:

opencode --version

---

Metoda 4: Go Install

Jeśli masz zainstalowane Go 1.22+, możesz zainstalować narzędzie bezpośrednio ze źródła za pomocą go install:

go install github.com/opencode-ai/opencode@latest

Upewnij się, że $GOPATH/bin (lub domyślnie $HOME/go/bin) znajduje się w Twojej ścieżce PATH. Dodaj go do profilu powłoki, jeśli jeszcze go tam nie ma:

export PATH="$PATH:$(go env GOPATH)/bin"

Zweryfikuj:

opencode --version

---

Metoda 5: Docker

Uruchamianie OpenCode w Docker jest przydatne w potokach CI/CD lub gdy chcesz mieć odizolowane środowisko.

docker pull ghcr.io/opencode-ai/opencode:latest

Uruchom go z zamontowanym katalogiem projektu:

docker run -it --rm \
  -v "$(pwd)":/workspace \
  -w /workspace \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  ghcr.io/opencode-ai/opencode:latest

Flagi -it są niezbędne, ponieważ OpenCode korzysta z interaktywnego TUI. Flaga -v montuje Twój aktualny katalog projektu, aby OpenCode mógł czytać i modyfikować Twoje pliki.

---

Metoda 6: Budowanie ze źródła

Dla współtwórców lub każdego, kto chce korzystać z najnowszej wersji rozwojowej:

git clone https://github.com/opencode-ai/opencode.git
cd opencode
go build -o opencode .

Przenieś plik binarny do katalogu w Twojej ścieżce PATH:

sudo mv opencode /usr/local/bin/

Budowanie ze źródła wymaga Go 1.22+ i Git. Daje to dostęp do niewydanych jeszcze funkcji i pozwala modyfikować narzędzie pod własne potrzeby.

---

Metoda 7: Scoop (Windows)

Użytkownicy Windows, którzy preferują natywne rozwiązania zamiast WSL, mogą użyć Scoop:

scoop install opencode

Scoop automatycznie zajmuje się konfiguracją PATH.

---

Pierwsze uruchomienie i konfiguracja

Po zainstalowaniu OpenCode przejdź do dowolnego katalogu projektu i uruchom go:

cd your-project
opencode

Przy pierwszym uruchomieniu OpenCode otwiera swoje TUI i prosi o połączenie z dostawcą AI. Możesz użyć interaktywnego polecenia /connect, aby dodać swój API key:

/connect

Przeprowadzi Cię to przez wybór dostawcy (OpenAI, Google, Anthropic itd.) i wprowadzanie API key. Dane uwierzytelniające są przechowywane w ~/.local/share/opencode/auth.json.

Dla szybszego startu możesz również zainicjować swój projekt za pomocą:

/init

Analizuje to strukturę Twojego repozytorium i tworzy plik agents.md z kontekstem Twojej bazy kodu, co pomaga AI udzielać dokładniejszych odpowiedzi od samego początku.

---

Konfiguracja dostawców AI

OpenCode wspiera wielu dostawców AI. Oto jak skonfigurować każdego z nich.

OpenAI (GPT-5.4, GPT-4.1, o3)

Ustaw API key jako zmienną środowiskową:

export OPENAI_API_KEY="sk-your-key-here"

Lub dodaj go do profilu powłoki (~/.zshrc, ~/.bashrc), aby zachować go na stałe.

Google Gemini (Gemini 2.5 Pro, Gemini 2.5 Flash)

export GOOGLE_API_KEY="your-google-api-key"

Możesz uzyskać Google API key w Google AI Studio.

Ollama (Modele lokalne — Darmowe, Prywatne)

Ollama pozwala uruchamiać modele lokalnie bez żadnego API key. Najpierw zainstaluj Ollama, pobierz model, a następnie skonfiguruj OpenCode:

# Zainstaluj Ollama (jeśli jeszcze nie jest zainstalowana)
curl -fsSL https://ollama.com/install.sh | sh

# Pobierz model do kodowania
ollama pull qwen2.5-coder:32b

# OpenCode automatycznie wykrywa Ollama, gdy działa na localhost:11434

Dla Ollama nie jest wymagany żaden API key. OpenCode wykrywa ją automatycznie, gdy działa lokalnie.

Anthropic (Claude — Ograniczony dostęp)

Anthropic ograniczył dostęp do Claude w narzędziach zewnętrznych, w tym w OpenCode. Jeśli masz API key, który wciąż działa:

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

Jednak większość użytkowników w 2026 roku używa OpenAI lub Google Gemini jako głównego dostawcy w OpenCode z powodu tych ograniczeń.

---

Niezbędna konfiguracja: Przegląd config.toml

OpenCode używa pliku konfiguracyjnego TOML do precyzyjnej kontroli. Plik konfiguracyjny znajduje się w ~/.config/opencode/config.toml (lub w głównym katalogu projektu jako opencode.json dla ustawień specyficznych dla projektu).

Oto praktyczny przykład config.toml:

# Konfiguracja dostawcy
[provider.openai]
apiKey = "{env:OPENAI_API_KEY}"

[provider.openai.models.gpt]
id = "gpt-5.4"

[provider.google]
apiKey = "{env:GOOGLE_API_KEY}"

[provider.google.models.gemini]
id = "gemini-2.5-pro"

# Wyłącz dostawców, których nie używasz
disabled_providers = ["anthropic"]

Kluczowe kwestie:

• Podstawianie zmiennych: Użyj {env:VARIABLE_NAME}, aby odwołać się do zmiennych środowiskowych zamiast wpisywać klucze na sztywno.
• Wybór modelu: Możesz dokładnie określić, którego modelu używać u każdego dostawcy.
• Wyłączeni dostawcy: Zapobiega to ładowaniu przez OpenCode dostawców, do których nie masz danych uwierzytelniających, unikając ostrzeżeń przy starcie.
• Nadpisanie adresu URL: Jeśli używasz proxy lub niestandardowego punktu końcowego, dodaj baseURL = "https://your-proxy.com/v1" w sekcji dostawcy.

Dla konfiguracji na poziomie projektu utwórz plik opencode.json w głównym katalogu projektu:

{
  "provider": "openai",
  "model": "gpt-5.4"
}

To nadpisuje globalne ustawienia dla tego konkretnego projektu.

---

Weryfikacja instalacji

Przejrzyj tę listę kontrolną, aby upewnić się, że wszystko działa poprawnie.

1. Sprawdź wersję

opencode --version

Powinieneś zobaczyć wydrukowany numer wersji. Według stanu na marzec 2026, najnowsza stabilna wersja mieści się w zakresie 0.x.

2. Uruchom TUI

cd any-project-directory
opencode

Powinieneś zobaczyć interfejs terminalowy OpenCode z polem zachęty na dole.

3. Przetestuj proste zapytanie

W TUI OpenCode wpisz prostą prośbę:

Wyjaśnij, co robi ten projekt na podstawie struktury plików.

Jeśli otrzymasz odpowiedź od AI, Twoja konfiguracja dostawcy działa.

4. Przetestuj operacje na plikach

Poproś OpenCode o utworzenie małego pliku testowego:

Utwórz plik o nazwie test-opencode.txt z tekstem "OpenCode działa"

Sprawdź, czy plik został utworzony w katalogu projektu, a następnie go usuń.

---

Rozwiązywanie typowych problemów

"command not found: opencode"

Plik binarny nie znajduje się w Twojej ścieżce PATH. Rozwiązania zależą od metody instalacji:

• npm: Uruchom npm list -g opencode-ai, aby potwierdzić instalację. Jeśli jest zainstalowany, sprawdź, czy globalny katalog bin npm znajduje się w PATH: npm config get prefix i dodaj /bin do tej ścieżki.
• Go: Dodaj $(go env GOPATH)/bin do swojej ścieżki PATH.
• Skrypt curl: Uruchom ponownie skrypt instalacyjny lub ręcznie przenieś plik binarny do /usr/local/bin/.

Błędy uprawnień podczas instalacji npm

Nie używaj sudo npm install -g. Zamiast tego napraw domyślny katalog npm:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g opencode-ai@latest

"Error: Node.js version too old"

Pakiet npm OpenCode wymaga Node.js 18+. Sprawdź swoją wersję:

node --version

Jeśli masz starszą wersję, zaktualizuj ją za pomocą nvm:

nvm install 18
nvm use 18

Błędy sieciowe za korporacyjnym firewallem

Jeśli instalacja npm zawiesza się lub kończy niepowodzeniem z powodu ograniczeń sieciowych:

npm install -g opencode-ai@latest --registry https://registry.npmmirror.com

Lub pobierz plik binarny bezpośrednio ze strony wydań GitHub i umieść go ręcznie w swojej ścieżce PATH.

"API key not found" lub "No provider configured"

Upewnij się, że zmienna środowiskowa z API key jest wyeksportowana w tej samej sesji powłoki:

echo $OPENAI_API_KEY

Jeśli nic się nie wyświetla, ustaw ją ponownie:

export OPENAI_API_KEY="sk-your-key-here"

Aby zachować to na stałe, dodaj linię export do swojego ~/.zshrc lub ~/.bashrc i uruchom source ~/.zshrc.

Problemy z renderowaniem TUI (zniekształcony tekst, brak obramowań)

Przełącz się na nowoczesny emulator terminala obsługujący true color. Zalecane opcje: iTerm2 (macOS), Alacritty (wieloplatformowy), WezTerm (wieloplatformowy) lub Windows Terminal (Windows).

Go install: "go: command not found"

Go nie jest zainstalowane lub nie znajduje się w Twojej ścieżce PATH. Zainstaluj Go ze strony go.dev/dl i upewnij się, że jest w PATH:

export PATH="$PATH:/usr/local/go/bin"

---

Aktualizacja OpenCode

Dbaj o aktualność OpenCode, aby otrzymywać wsparcie dla najnowszych modeli i poprawki błędów.

npm:

npm update -g opencode-ai

Homebrew:

brew upgrade opencode

Skrypt curl: Uruchom ponownie polecenie instalacyjne:

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

Go install: Uruchom ponownie z @latest:

go install github.com/opencode-ai/opencode@latest

---

Następne kroki

Skoro OpenCode jest już zainstalowany i skonfigurowany, możesz zacząć używać go w codziennej pracy.

• Poznaj polecenia: Sprawdź nasz Tutorial OpenCode 2026, aby zapoznać się z pełnym przeglądem poleceń, przepływów pracy i zaawansowanych funkcji.
• Skonfiguruj integrację z GitHub: Zainstaluj aplikację OpenCode GitHub App, aby korzystać z opartego na AI przeglądu kodu i odpowiedzi na zgłoszenia bezpośrednio w swoich repozytoriach.
• Wypróbuj polecenie /init: Uruchom /init w swoim projekcie, aby wygenerować plik agents.md, który daje OpenCode głęboki kontekst na temat architektury Twojej bazy kodu.
• Wypróbuj wielu dostawców: Skonfiguruj dwóch lub trzech dostawców i przełączaj się między nimi, aby sprawdzić, który model najlepiej radzi sobie z Twoimi zadaniami programistycznymi.

OpenCode to jedno z najszybciej rozwijających się otwartoźródłowych narzędzi AI w 2026 roku, ponieważ spotyka programistów tam, gdzie już pracują: w terminalu. Dzięki instalacji trwającej poniżej pięciu minut i konfiguracji wymagającej tylko jednego API key, nie ma powodu, by nie wypróbować go już dziś.