Przejdź do głównej treści

Jak zainstalować i używać OpenCode: Kompletny przewodnik

BlogsOpenCodeAITerminalCLIOkoło 8 minut

Jak zainstalować i używać OpenCode: Kompletny przewodnik

OpenCode to otwartoźródłowy agent kodowania oparty na sztucznej inteligencji, który przenosi moc AI bezpośrednio do Twojego terminala. W przeciwieństwie do tradycyjnych narzędzi AI do kodowania działających w edytorach lub przeglądarkach, OpenCode oferuje interfejs terminalowy, aplikację desktopową oraz rozszerzenie IDE — wszystko zaprojektowane, aby zwiększyć Twoją produktywność jako programisty. Ten kompleksowy przewodnik przeprowadzi Cię przez wszystko, co musisz wiedzieć, aby skutecznie zainstalować, skonfigurować i używać OpenCode.

Czym jest OpenCode?

OpenCode to asystent kodowania oparty na AI, który pomaga Ci:

  • Pisać kod szybciej dzięki inteligentnej generacji i uzupełnianiu kodu
  • Skutecznie debugować analizując błędy i sugerując poprawki
  • Rozumieć bazy kodu poprzez zapytania w języku naturalnym
  • Dodawać funkcje za pomocą automatycznego planowania i implementacji
  • Przeglądać kod z analizą i sugestiami wspieranymi przez AI
  • Automatyzować przepływy pracy wykorzystując agentów AI i niestandardowe narzędzia

Obsługuje wielu dostawców LLM, w tym Anthropic, OpenAI, Google i innych, dając Ci elastyczność wyboru modeli najlepiej dopasowanych do Twoich potrzeb.

Wymagania systemowe

Wymagania wstępne

Przed instalacją OpenCode upewnij się, że masz:

  1. Nowoczesny emulator terminala (do użycia TUI):

  2. Node.js (do instalacji przez npm/bun/pnpm/yarn):

    • Zalecana wersja Node.js v18 lub wyższa

  3. Klucze API dla dostawców LLM:

    • Klucz API Anthropic (dla modeli Claude)
    • Klucz API OpenAI (dla modeli GPT)
    • Lub klucze od innych wspieranych dostawców

Metody instalacji

Metoda 1: Skrypt instalacyjny (zalecane)

Najszybszy sposób instalacji OpenCode to użycie oficjalnego skryptu instalacyjnego:

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

Ta metoda działa na macOS, Linux i Windows (z Git Bashiem lub WSL).

Metoda 2: Menedżery pakietów Node.js

Przy użyciu npm:

npm install -g opencode-ai

Przy użyciu Bun:

bun install -g opencode-ai

Przy użyciu pnpm:

pnpm install -g opencode-ai

Przy użyciu Yarn:

yarn global add opencode-ai

Metoda 3: Użycie Homebrew (macOS i Linux)

brew install opencode

Metoda 4: Użycie Paru (Arch Linux)

paru -S opencode-bin

Metoda 5: Instalacje specyficzne dla Windows

Przy użyciu Chocolatey:

choco install opencode

Przy użyciu Scoop:

scoop bucket add extras
scoop install extras/opencode

Przy użyciu Mise:

mise use -g github:sst/opencode

Metoda 6: Docker

Do użycia w kontenerze:

docker run -it --rm ghcr.io/sst/opencode

Metoda 7: Pobranie binarki

Możesz pobrać skompilowaną binarkę bezpośrednio z GitHub Releases.

Sprawdzenie instalacji

Po instalacji sprawdź, czy działa:

opencode --version

Powinieneś zobaczyć numer wersji.

Podstawowa konfiguracja

Połączenie z OpenCode Zen (zalecane dla początkujących)

OpenCode Zen to wyselekcjonowana lista modeli przetestowanych i zweryfikowanych przez zespół OpenCode. To najprostszy sposób na start.

  1. Uruchom OpenCode:
cd /ścieżka/do/twojego/projektu
opencode
  1. Wykonaj polecenie connect w TUI:
/connect

  1. Wybierz „opencode” z listy dostawców

  2. Odwiedź adres uwierzytelniania: opencode.ai/auth

  3. Zaloguj się i dodaj dane rozliczeniowe (lub użyj dostępnych darmowych kredytów)

  4. Skopiuj swój klucz API i wklej go w terminalu, gdy pojawi się prośba

Połączenie z innymi dostawcami

Możesz także podłączyć OpenCode do innych dostawców LLM:

Używając polecenia /connect:

/connect

Wybierz preferowanego dostawcę (Anthropic, OpenAI, Google itp.) i postępuj zgodnie z przebiegiem uwierzytelniania.

Używając uwierzytelniania CLI:

opencode auth login

To przeprowadzi Cię przez konfigurację kluczy API dla dowolnego dostawcy dostępnego na Models.dev.

Lista skonfigurowanych dostawców:

opencode auth list

lub krócej:

opencode auth ls

Wylogowanie się od dostawcy:

opencode auth logout

Ustawianie kontekstu projektu

Po skonfigurowaniu dostawcy zainicjuj OpenCode dla swojego projektu:

  1. Przejdź do katalogu projektu:
cd /ścieżka/do/twojego/projektu
  1. Uruchom OpenCode:
opencode
  1. Wykonaj polecenie init:
/init

Analizuje to strukturę Twojego projektu i tworzy plik AGENTS.md w katalogu głównym projektu. Plik ten pomaga OpenCode lepiej rozumieć wzorce kodowania, frameworki i architekturę projektu.

Wskazówka: Zacommituj plik AGENTS.md do Gita. To pomaga utrzymać spójność w zespole i z czasem poprawia zrozumienie projektu przez OpenCode.

Korzystanie z Terminal User Interface (TUI)

TUI OpenCode zapewnia interaktywne doświadczenie w Twoim terminalu.

Uruchamianie TUI

Wystarczy wykonać:

opencode

Lub z dodatkowymi opcjami:

# Kontynuuj ostatnią sesję
opencode --continue

# Kontynuuj konkretną sesję
opencode --session <session-id>

# Uruchom z podpowiedzią
opencode --prompt "Wyjaśnij tę bazę kodu"

# Użyj konkretnego modelu
opencode --model anthropic/claude-sonnet-4-5

# Użyj określonego agenta
opencode --agent plan

Podstawowa nawigacja w TUI

  • Scrollowanie: używaj kółka myszy lub strzałek
  • Przełączanie trybów: naciśnij Tab, aby przełączyć między Trybem Planu a Trybem Budowy
  • Uruchamianie poleceń: wpisz /, aby uzyskać dostęp do palety poleceń
  • Wyszukiwanie plików: użyj @, aby nieprecyzyjnie wyszukiwać pliki w projekcie
  • Wyjście: naciśnij Ctrl+C lub wpisz /exit

Zadawanie pytań

Możesz zadawać OpenCode pytania dotyczące swojego kodu:

Jak obsługiwana jest autoryzacja w @packages/functions/src/api/index.ts

Użyj symbolu @, aby odwołać się do konkretnego pliku. OpenCode przeanalizuje te pliki i udzieli szczegółowych wyjaśnień.

Dodawanie funkcji

OpenCode świetnie radzi sobie z dodawaniem nowych funkcji poprzez dwuetapowy workflow:

Krok 1: Tryb Planu

  1. Przełącz się na Tryb Planu naciskając Tab
  2. Opisz, czego potrzebujesz:
Kiedy użytkownik usuwa notatkę, chcemy oznaczyć ją jako usuniętą w bazie danych.
Następnie utwórz ekran pokazujący wszystkie ostatnio usunięte notatki.
Z tego ekranu użytkownik może przywrócić notatkę lub usunąć ją na stałe.
  1. Przejrzyj zasugerowany plan
  2. Wprowadź uwagi:
Chcemy zaprojektować ten nowy ekran w oparciu o wzór, którego już wcześniej używałem.
[Obraz #1] Spójrz na ten obraz i użyj go jako odniesienia.

Wskazówka: Możesz przeciągać i upuszczać obrazy do terminala. OpenCode je zeskanuje i przeanalizuje.

Krok 2: Tryb Budowy

  1. Przełącz się na Tryb Budowy ponownie naciskając Tab
  2. Zatwierdź implementację:
Brzmi świetnie! Wprowadź zmiany.

OpenCode zaimplementuje funkcję, tworząc i modyfikując pliki w razie potrzeby.

Dokonywanie bezpośrednich zmian

Dla prostych zmian możesz pominąć etap planowania:

Musimy dodać autoryzację do ścieżki /settings.
Spójrz, jak to jest zrobione w ścieżce /notes
w @packages/functions/src/notes.ts i zaimplementuj taką samą logikę
w @packages/functions/src/settings.ts

Cofanie i ponawianie zmian

Popełniłeś błąd? Użyj polecenia undo:

/undo

To cofa ostatni zestaw zmian i pozwala Ci dopracować podpowiedź.

Aby ponowić cofnięte zmiany:

/redo

Możesz wielokrotnie używać /undo, aby cofnąć wiele zmian.

Polecenia CLI

OpenCode oferuje potężne CLI do dostępu programistycznego i automatyzacji.

Uruchamianie poleceń bez interakcji

Wykonaj OpenCode bez interaktywnego interfejsu:

opencode run "Wyjaśnij, jak działają closures w JavaScript"

Przydatne do skryptów, automatyzacji lub szybkich odpowiedzi bez uruchamiania TUI.

Zarządzanie modelami

Wyświetl listę wszystkich dostępnych modeli:

opencode models

Filtruj według dostawcy:

opencode models anthropic

Odśwież cache modeli (np. po dodaniu nowych):

opencode models --refresh

Pokaż szczegółowe informacje o modelach, w tym koszty:

opencode models --verbose

Uruchamianie serwera headless

Uruchom serwer HTTP do dostępu API:

opencode serve

Z niestandardowym portem:

opencode serve --port 3000

Przydatne do integracji OpenCode z aplikacjami webowymi lub szybszych odpowiedzi w skryptach (unika zimnego startu serwera MCP).

Dołączanie do serwera

W jednym terminalu uruchom serwer:

opencode serve

W innym dołącz do niego dla szybszego wykonania:

opencode run --attach http://localhost:4096 "Wyjaśnij async/await w JavaScript"

Zarządzanie agentami

Utwórz nowego niestandardowego agenta:

opencode agent create

Przeprowadzi Cię to przez tworzenie agenta z niestandardowymi promptami systemowymi i konfiguracją narzędzi.

Integracja z GitHub

Zainstaluj agenta GitHub do automatyzacji repozytorium:

opencode github install

Konfiguruje to workflow GitHub Actions do automatycznych przeglądów kodu i obsługi issue.

Aktualizacja OpenCode

Zaktualizuj do najnowszej wersji:

opencode upgrade

Lub do określonej wersji:

opencode upgrade v0.1.48

Określ metodę instalacji, jeśli potrzebujesz:

opencode upgrade --method brew

Konfiguracja

OpenCode wspiera elastyczną konfigurację poprzez pliki JSON.

Lokalizacje konfiguracji

Pliki konfiguracyjne są scalane (nie nadpisywane), co pozwala mieć konfigurację globalną, specyficzną dla projektu oraz niestandardową.

  1. Konfiguracja globalna: ~/.config/opencode/opencode.json

    • Używaj na motywy, dostawców, skróty klawiszowe i ustawienia ogólne

  2. Konfiguracja projektu: opencode.json w katalogu głównym projektu

    • Używaj na specyficznych dostawców, agentów lub ustawienia projektu
    • Można bezpiecznie dodać do Gita

  3. Niestandardowa ścieżka konfiguracji: Ustawiana zmienną środowiskową OPENCODE_CONFIG

  4. Niestandardowy katalog konfiguracji: Ustawiana zmienną środowiskową OPENCODE_CONFIG_DIR

Przykład podstawowej konfiguracji

Utwórz plik konfiguracyjny o takiej strukturze:

{
  "$schema": "https://opencode.ai/config.json",
  
  // Wybór motywu
  "theme": "opencode",
  
  // Główny model do użycia
  "model": "anthropic/claude-sonnet-4-5",
  
  // Mniejszy model do lekkich zadań
  "small_model": "anthropic/claude-haiku-4-5",
  
  // Ustawienia autoaktualizacji
  "autoupdate": true
}

Konfiguracja dostawców

Konfiguruj klucze API bezpośrednio w konfiguracji:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

Zaleca się używać zmiennych środowiskowych ze względów bezpieczeństwa. Syntax: {env:NAZWA_ZMIENNEJ}.

Korzystanie z odwołań do plików

Możesz także odwołać się do plików zawierających dane poufne:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Niestandardowe polecenia

Zdefiniuj własne polecenia do powtarzalnych zadań:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Uruchom pełny test suite z raportem pokrycia i pokaż błędy.\nSkup się na testach, które nie przeszły oraz zaproponuj poprawki.",
      "description": "Uruchom testy z pokryciem",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Utwórz nowy komponent React o nazwie $ARGUMENTS z obsługą TypeScript.\nUwzględnij odpowiednie typowanie i podstawową strukturę.",
      "description": "Utwórz nowy komponent"
    }
  }
}

Używaj własnych poleceń w TUI, wpisując /test lub /component MyComponent.

Niestandardowi agenci

Twórz wyspecjalizowanych agentów:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Przegląda kod pod kątem najlepszych praktyk i potencjalnych problemów",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "Jesteś recenzentem kodu. Skup się na bezpieczeństwie, wydajności i utrzymaniu.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Konfiguracja uprawnień

Kontroluj, co OpenCode może zrobić bez pytania:

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

Wymaga to zatwierdzenia użytkownika dla operacji edycji i bash.

Formatery kodu

Konfiguruj formatery do automatycznego formatowania kodu:

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": false
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Ustawienia TUI

Dostosuj interfejs terminala:

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

Zaawansowane funkcje

Udostępnianie konwersacji

Udostępniaj swoje konwersacje zespołowi:

/share

Tworzy link do udostępnienia i kopiuje go do schowka. Domyślnie konwersacje nie są udostępniane.

Konfiguruj zachowanie udostępniania:

{
  "share": "manual"  // "manual", "auto" lub "disabled"
}

Serwery MCP

Serwery Model Context Protocol (MCP) rozszerzają możliwości OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ścieżka/do/dozwolonych/plików"]
    }
  }
}

Instrukcje i zasady

Podaj instrukcje specyficzne dla projektu:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

OpenCode użyje tych plików do zrozumienia standardów kodowania i konwencji w projekcie.

Zmienne środowiskowe

Konfiguruj OpenCode za pomocą zmiennych środowiskowych:

# Automatyczne udostępnianie sesji
export OPENCODE_AUTO_SHARE=true

# Ścieżka do niestandardowej konfiguracji
export OPENCODE_CONFIG=/ścieżka/do/config.json

# Ścieżka do katalogu konfiguracji
export OPENCODE_CONFIG_DIR=/ścieżka/do/config-dir

# Wyłącz automatyczne aktualizacje
export OPENCODE_DISABLE_AUTOUPDATE=true

# Wyłącz domyślne wtyczki
export OPENCODE_DISABLE_DEFAULT_PLUGINS=true

# Włącz modele eksperymentalne
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true

# Włącz wyszukiwanie web Exa
export OPENCODE_ENABLE_EXA=true

Funkcje eksperymentalne

Włącz funkcje eksperymentalne:

export OPENCODE_EXPERIMENTAL=true

Konkretne funkcje eksperymentalne:

# Włącz wykrywanie ikon
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true

# Wyłącz kopiowanie po zaznaczeniu w TUI
export OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=true

# Ustaw maksymalną długość wyniku dla poleceń bash
export OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH=10000

# Ustaw domyślny timeout dla poleceń bash (w ms)
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=30000

Dobre praktyki

Skuteczne zapytania (promptowanie)

  1. Bądź precyzyjny: podawaj jasne, szczegółowe instrukcje
  2. Używaj kontekstu: odwołuj się do plików za pomocą @ dla lepszego zrozumienia
  3. Podawaj przykłady: pokazuj, czego oczekujesz
  4. Dziel zadania na kroki: złożone zadania najlepiej rozbijać na etapy

Praca z dużymi projektami

  1. Używaj /init: pozwól OpenCode poznać strukturę projektu
  2. Odwołuj się do konkretnych plików: używaj @ by ograniczyć kontekst
  3. Korzystaj z Trybu Planu: przeglądaj plany przed implementacją
  4. Zmieniaj stopniowo: wprowadzaj małe, kontrolowane zmiany

Optymalizacja kosztów

  1. Używaj mniejszych modeli: skonfiguruj small_model do lekkich zadań
  2. Planuj przed budową: przeglądaj plan w Trybie Planu, aby zmniejszyć ilość iteracji
  3. Niestandardowe polecenia: definiuj wydajne workflow dla częstych zadań
  4. Monitoruj zużycie: sprawdzaj statystyki w panelach dostawców

Praktyki bezpieczeństwa

  1. Nigdy nie commituj kluczy API: używaj zmiennych środowiskowych
  2. Korzystaj z uprawnień: konfiguruj permission, aby wymagać zgody na wrażliwe operacje
  3. Przeglądaj zmiany: zawsze sprawdzaj sugerowane zmiany przez OpenCode
  4. Używaj osobnych kluczy: twórz dedykowane klucze API dla OpenCode z odpowiednimi limitami

Rozwiązywanie problemów

Problemy z instalacją

Problem: Polecenie nieznalezione po instalacji

Rozwiązanie:

  • Sprawdź instalację: which opencode
  • Sprawdź PATH: echo $PATH
  • Spróbuj pełną ścieżką: ~/.local/bin/opencode
  • Zainstaluj ponownie inną metodą

Problemy z uwierzytelnieniem

Problem: Klucz API nie jest rozpoznawany

Rozwiązanie:

  • Sprawdź poprawność klucza: opencode auth list
  • Sprawdź zmienne środowiskowe: echo $ANTHROPIC_API_KEY
  • Zaloguj się ponownie: opencode auth login

Problemy z wydajnością

Problem: Wolny czas odpowiedzi

Rozwiązanie:

  • Użyj opencode serve dla szybszego wykonania
  • Przełącz się na szybszy model
  • Używaj mniejszych okienek kontekstu
  • Wyłącz nieużywane narzędzia w konfiguracji

Problemy z TUI

Problem: Problemy z wyświetlaniem w terminalu

Rozwiązanie:

  • Używaj nowoczesnego emulatora terminala (WezTerm, Alacritty itd.)
  • Sprawdź, czy terminal wspiera kolory 24-bitowe
  • Spróbuj innego motywu
  • Wyłącz przyspieszenie scrollowania, jeśli występują problemy

Problemy z modelem

Problem: Model nie znaleziony

Rozwiązanie:

  • Odśwież listę modeli: opencode models --refresh
  • Sprawdź, czy dostawca jest skonfigurowany: opencode auth list
  • Zweryfikuj format nazwy modelu: provider/model
  • Sprawdź, czy dostawca udostępnia dany model

Integracja OpenCode w Twoim workflow

Codzienny rozwój

  1. Rano: uruchom /init, aby zsynchronizować zmiany w kodzie
  2. Prace nad funkcjami: używaj Trybu Planu do projektowania, a Trybu Budowy do implementacji
  3. Debugowanie: zadawaj pytania o błędy z odniesieniami do plików
  4. Przegląd kodu: używaj niestandardowego agenta recenzenta kodu
  5. Dokumentacja: generuj dokumentację używając niestandardowych poleceń

Współpraca zespołowa

  1. Udostępniaj konfiguracje: commituj opencode.json i AGENTS.md do Gita
  2. Udostępniaj rozmowy: używaj /share do dyskusji o implementacjach
  3. Niestandardowe polecenia: definiuj polecenia specyficzne dla zespołu w konfiguracji projektu
  4. Spójni agenci: korzystaj ze wspólnych definicji agentów dla spójności

Integracja CI/CD

  1. Agent GitHub: instaluj do automatycznych przeglądów PR
  2. Testy: korzystaj z niestandardowych poleceń testowych w CI
  3. Jakość kodu: konfiguruj formatery i uprawnienia

Podsumowanie

OpenCode reprezentuje nowy paradygmat w rozwoju wspomaganym AI, dostarczając potężne możliwości AI bezpośrednio do Twojego terminala. Dzięki elastycznym opcjom konfiguracji, wsparciu dla wielu dostawców LLM oraz intuicyjnemu interfejsowi TUI, został zaprojektowany, by zwiększyć Twoją produktywność bez zakłócania istniejącego workflow.

Kluczowe informacje:

  • Instaluj za pomocą skryptu instalacyjnego lub preferowanego menedżera pakietów
  • Konfiguruj klucze API przez /connect lub opencode auth login
  • Inicjuj projekty przez /init w celu lepszego zrozumienia kontekstu
  • Używaj Trybu Planu dla złożonych funkcji, Trybu Budowy do bezpośrednich zmian
  • Dostosuj konfiguracje, polecenia i agentów
  • Korzystaj z poleceń CLI do automatyzacji i skryptowania
  • Przestrzegaj dobrych praktyk bezpieczeństwa z kluczami API i uprawnieniami

Kolejne kroki:

Gotowy, by przyspieszyć swój workflow developerski?
Sprawdź rozwiązania hostingowe LightNode zoptymalizowane pod kątem AI do wdrażania aplikacji opartych na AI z dedykowanymi instancjami GPU i skalowalną infrastrukturą.

OpenCode jest otwartym oprogramowaniem i ciągle się rozwija. Wspieraj projekt, zgłaszaj błędy lub dziel się swoimi doświadczeniami, aby uczynić go jeszcze lepszym dla wszystkich. Powodzenia w kodowaniu!

Oszczędzaj na tanim hostingu VPS