OpenCode Quickstart: zainstaluj, skonfiguruj i użyj agenta AI do kodowania w terminalu

Jak zainstalować, skonfigurować i używać OpenCode

Page content

OpenCode to agent AI kodowania z otwartym źródłem, który możesz uruchomić w terminalu (TUI + CLI) z opcjonalnymi powierzchniami pulpitu i IDE. Oto Szybki start OpenCode: zainstaluj, zweryfikuj, połącz z modelem/dostawcą i uruchom rzeczywiste przepływy pracy (CLI + API).

Uwaga dotycząca wersji: OpenCode szybko się rozwija. Poniższe polecenia „latest” są stabilne, ale wyniki i domyślne ustawienia mogą się zmieniać – zawsze sprawdzaj oficjalne dokumenty CLI i log typów zmian (poniżej znajdują się linki).

Ten artykuł jest częścią Narzędzi AI dla programistów: Kompletny przewodnik po rozwoju opartym na AI.

Co to jest OpenCode (i gdzie pasuje)

OpenCode jest zaprojektowany do kodowania agenty z terminala jako pierwszego, przy jednoczesnym zachowaniu elastyczności w zakresie dostawców/modeli. W praktyce jest to warstwa przepływu pracy, która może:

  • uruchomić interfejs użytkownika terminala, gdy uruchomisz opencode
  • uruchomić nieinteraktywne „jednorazowe” polecenia za pomocą opencode run (skrypty/automatyzacja)
  • udostępnić bezinterfejsowy serwer HTTP przez opencode serve (i interfejs sieciowy przez opencode web)
  • być kontrolowany programowo za pomocą oficjalnego SDK JS/TS @opencode-ai/sdk

opencode z samozhostowanym qwen3.5 27b LLM

Jeśli budujesz klastrowy system /ai-devtools/, OpenCode jest dobrym kandydatem do podklasteru, ponieważ naturalnie rozwija się w kierunku:

  • analizy CLI
  • zachowania i kosztów modeli/dostawców (porównanie modeli LLM w OpenCode)
  • konfiguracji i agentów
  • integracji (GitHub/GitLab/Copilot)
  • cheatshetu

Wymagania wstępne

Zachodzi potrzeba:

  • nowoczesnego emulatora terminala (ważne dla doświadczenia TUI).
  • dostępu do co najmniej jednego modelu/dostawcy (klucze API lub autoryzacja subskrypcji, w zależności od dostawcy). Lokalne opcje takie jak Ollama lub llama.cpp działają bez kluczy API, jeśli uruchomisz kompatybilny serwer lokalnie.

Instalacja OpenCode (kopiuj i wklej)

Oficjalny skrypt instalacyjny (Linux/macOS/WSL):

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

Opcje menedżera pakietów (przykłady oficjalne):

# Instalacja globalna w Node.js
npm install -g opencode-ai

# Homebrew (rekomendowane przez OpenCode dla najnowszych wersji)
brew install anomalyco/tap/opencode

# Arch Linux (stabilna)
sudo pacman -S opencode

# Arch Linux (najnowsza z AUR)
paru -S opencode-bin

Uwagi dotyczące Windowsa (oficjalna wskazówka zazwyczaj rekomenduje WSL dla najlepszej kompatybilności). Alternatywami są Scoop/Chocolatey lub npm.

# Chocolatey (Windows)
choco install opencode

# Scoop (Windows)
scoop install opencode

Docker (przydatny do szybkiego testu):

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

Weryfikacja instalacji

opencode --version
opencode --help

Oczekiwana postać danych wyjściowych (może się różnić w zależności od wersji):

# Przykład:
# <wypisuje numer wersji, np. vX.Y.Z>
# <wypisuje pomoc z dostępnych poleceń/podpoleceń>

Połączenie z dostawcą (dwa praktyczne ścieżki)

Ścieżka A: /connect w TUI (interaktywnie)

Uruchom OpenCode:

opencode

Następnie uruchom:

/connect

Następnie wykonaj kroki w interfejsie użytkownika, aby wybrać dostawcę i uwierzytelnić się (niektóre przepływy otwierają przeglądarkę/logowanie na urządzeniu).

Ścieżka B: opencode auth login w CLI (klucze dostawcy)

OpenCode obsługuje konfigurację dostawców przez:

opencode auth login

Uwagi:

  • Uwierzytelnienie jest przechowywane w ~/.local/share/opencode/auth.json.
  • OpenCode może również wczytywać klucze z zmiennych środowiskowych lub pliku .env w Twoim projekcie.

Lokalne hostowanie LLM (Ollama, llama.cpp)

OpenCode działa z dowolnym API kompatybilnym z OpenAI. W przypadku lokalnego rozwoju wielu użytkowników uruchamia Ollama i kieruje OpenCode na niego. W ostatnim czasie miałem bardzo dobre doświadczenie konfigurując i uruchamiając OpenCode z llama.cpp – llama-server udostępnia punkty końcowe kompatybilne z OpenAI, więc możesz używać modeli GGUF z tym samym przepływem pracy. Jeśli preferujesz drobniejszą kontrolę nad pamięcią i czasem działania, lub chcesz lżejszy stos bez Pythona (przypominam, że ollama jest zaimplementowany w Go), warto spróbować llama.cpp. Bardzo ceniłem możliwość konfiguracji odłożonych warstw, łatwość użycia modeli w formacie GGUF i znacznie lepszą/ szybszą implementację kompatybilności z nowymi modelami, takimi jak Qwen3.5.

Poprawne rozpoczęcie projektu (rekomendowany pierwszy uruchomienie)

Z Twojego repozytorium:

cd /ścieżka/do/Twojego/repozytorium
opencode

Następnie zainicjalizuj:

/init

To analizuje Twój projekt i tworzy plik AGENTS.md w katalogu głównym projektu. Zwykle warto dodać ten plik do repozytorium, aby OpenCode (i współpracownicy) dzielili się spójnym kontekstem projektu.

Główne przepływy CLI (przykłady kopiowania i wklejania)

OpenCode obsługuje uruchamianie bezinteraktywne:

opencode run "Wyjaśnij, jak działają zamknięcia w JavaScript"

Przepływ pracy: generowanie kodu (CLI)

Cel: wygeneruj małą, testowalną funkcję z minimalnym kontekstem.

opencode run "Napisz funkcję ParsePort(envVar string, defaultPort int) (int, error) w Go. Powinna odczytywać zmienną środowiskową, parsować liczbę całkowitą, walidować zakres 1-65535 i zwracać defaultPort, jeśli jest pusta. Dołącz 3 testy tabelowe."

Oczekiwany wynik:

  • Wyjaśnienie plus bloki kodu (funkcja + testy). Dokładny kod może się różnić w zależności od modelu/dostawcy i polecenia.

Przepływ pracy: bezpieczna refaktoryzacja pliku (CLI + agent Plan)

Cel: refaktoryzuj bez przypadkowych edycji, używając bardziej restrykcyjnego agenta.

opencode run --agent plan --file ./src/auth.ts \
  "Refaktoryzuj ten plik w celu zmniejszenia złożoności. Wynik: (1) krótki plan, (2) blok różnic jednolitych, (3) ryzyka/brzegowych przypadków do przetestowania. Nie uruchamiaj poleceń."

Oczekiwany wynik:

  • Sekcja planu + blok różnic diff --git ... + lista testów.
  • Zawartość może się różnić. Jeśli nie generuje różnic, ponownie zapytaj: „Zwróć tylko różnicę jednolitą” lub „Użyj formatu diff --git.”

Przepływ pracy: zadawanie pytań dotyczących repozytorium (CLI)

Cel: szybko lokalizować szczegóły implementacji.

opencode run --agent explore \
  "W tym repozytorium, gdzie jest walidowana autoryzacja dla żądań API? Wypisz prawdopodobne pliki i wyjaśnij przepływ. Jeśli nie jesteś pewien, powiedz, co sprawdziłeś."

Oczekiwany wynik:

  • Krótki mapa ścieżek plików + opis przepływu.
  • Wynik zależy od rozmiaru repozytorium i narzędzi kontekstowych modelu/dostawcy.

Przepływ pracy: przyspieszenie powtarzających się wywołań CLI za pomocą trwało serwera

Jeśli skryptujesz lub uruchamiasz wiele wywołań opencode run, możesz uruchomić serwer bezinterfejsowy raz:

Terminal 1:

opencode serve --port 4096 --hostname 127.0.0.1

Terminal 2:

opencode run --attach http://localhost:4096 "Streszczenie struktury repozytorium i głównych punktów wejścia."
opencode run --attach http://localhost:4096 "Teraz zaproponuj 3 wysokiego wpływu refaktoryzacje i dlaczego."

Oczekiwany wynik:

  • Taki sam jak opencode run, ale zazwyczaj z mniejszym powtarzaniem się kosztów uruchamiania.

Użycie programowe (oficjalny SDK JS/TS)

OpenCode udostępnia serwer HTTP (OpenAPI) i dostarcza klienta typowo bezpiecznego JS/TS.

Instalacja:

npm install @opencode-ai/sdk

Przykład: uruchom serwer + klient, a następnie zapytaj

Utwórz scripts/opencode-sdk-demo.mjs:

import { createOpencode } from "@opencode-ai/sdk";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    // Format łańcucha modelu to dostawca/model (przykład tylko)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Serwer działa na: ${opencode.server.url}`);

// Podstawowa weryfikacja stanu/wersji
const health = await opencode.client.global.health();
console.log("Zdrowy:", health.data.healthy, "Wersja:", health.data.version);

// Utwórz sesję i zapytaj
const session = await opencode.client.session.create({ body: { title: "Przewodnik szybkiego startu SDK" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Wygeneruj małą sekcję README opisującą ten repozytorium." }],
  },
});

console.log(result.data);

// Zamknij serwer po zakończeniu
opencode.server.close();

Uruchom:

node scripts/opencode-sdk-demo.mjs

Oczekiwana postać danych wyjściowych:

  • „Serwer działa na …”
  • Odpowiedź zdrowia zawierająca łańcuch wersji
  • Obiekt odpowiedzi sesji (dokładna struktura zależy od responseStyle i wersji SDK)

Minimalna konfiguracja OpenCode, którą możesz skopiować

OpenCode obsługuje konfigurację JSON i JSONC. To dobry punkt wyjścia dla konfiguracji lokalnej projektu.

Utwórz opencode.jsonc w katalogu głównym repozytorium:

{
  "$schema": "https://opencode.ai/config.json",

  // Wybierz domyślny model (dostawca/model). Utrzymuj to zgodne z tym, co pokazuje `opencode models`.
  "model": "dostawca/model",

  // Opcjonalnie: tańszy „mały model” dla lekkich zadań (tytuły itp.)
  "small_model": "dostawca/small-model",

  // Opcjonalnie: domyślne ustawienia serwera OpenCode (używane przez serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // Opcjonalna bezpieczność: wymagaj potwierdzenia przed edytowaniem/poleceniami
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Krótki cheatshet (szybki odwołanie)

Polecenia, które będziesz używać codziennie

opencode                       # uruchom TUI
opencode run "..."             # uruchomienie bezinteraktywne (automatyzacja)
opencode run --file ścieżka "..." # dołączenie plików do zapytania
opencode models --refresh      # odświeżenie listy modeli
opencode auth login            # konfiguracja poświadczeń dostawcy
opencode serve                 # bezinterfejsowy serwer HTTP (OpenAPI)
opencode web                   # bezinterfejsowy serwer + interfejs sieciowy
opencode session list          # lista sesji
opencode stats                 # statystyki tokenów/kosztów

Warto zapamiętać polecenia TUI

/connect   # połączenie z dostawcą
/init      # analiza repozytorium, generowanie AGENTS.md
/share     # udostępnienie sesji (jeśli włączono)
/undo      # cofnięcie zmiany
/redo      # ponowne wykonanie zmiany
/help      # pomoc/skróty

Koncept domyślnego „klucza lidera” (TUI)

OpenCode korzysta z konfigurowalnego „klucza lidera” (zwykle ctrl+x) w celu uniknięcia konfliktów z terminalami. Wiele skrótów to „Leader + klawisz”.

Jednostronny drukowalny cheatshet OpenCode

Ta wersja jest celowo gęsta i „drukowalna”. (Możesz wkleić ją później do dedykowanej strony /ai-devtools/opencode/cheatsheet/.)

Zadanie Polecenie / skrót Uwagi
Uruchom TUI opencode Domyślnym zachowaniem jest uruchomienie interfejsu terminala
Uruchom jednorazowe zapytanie opencode run "..." Tryb bezinteraktywny do skryptowania/automatyzacji
Dołącz plik(y) do zapytania opencode run --file ścieżka/do/pliku "..." Użyj wielu flag --file dla wielu plików
Wybierz model dla uruchomienia opencode run --model dostawca/model "..." Łańcuchy modeli to dostawca/model
Wybierz agenta opencode run --agent plan "..." Plan jest zaprojektowany do bezpieczniejszej pracy „bez zmian” (ograniczone uprawnienia)
Lista modeli opencode models [dostawca] Użyj --refresh, aby odświeżyć zapisaną listę
Konfiguracja poświadczeń dostawcy opencode auth login Przechowuje poświadczenia w ~/.local/share/opencode/auth.json
Lista uwierzytelnionych dostawców opencode auth list / opencode auth ls Potwierdza, co widzi OpenCode
Uruchom bezinterfejsowy serwer opencode serve --port 4096 --hostname 127.0.0.1 Specyfikacja OpenAPI na http://host:port/doc
Dołącz uruchomienia do serwera opencode run --attach http://localhost:4096 "..." Przydatne, aby uniknąć powtarzających się startów
Włącz podstawowe uwierzytelnienie OPENCODE_SERVER_PASSWORD=... opencode serve Domyślnie nazwa użytkownika to opencode, chyba że została nadpisana
Tryb interfejsu sieciowego opencode web Uruchamia serwer i otwiera przeglądarkę
Eksportuj sesję opencode export [sessionID] Przydatne do archiwizowania lub udostępniania kontekstu
Importuj sesję opencode import session.json Można również importować z URL udostępnienia
Wyświetl globalne flagi CLI opencode --help / opencode --version --print-logs + --log-level do debugowania
Koncept klucza lidera TUI domyślny klucz lidera często ctrl+x Można dostosować w tui.json

Źródła (oficjalne pierwsze)

Oficjalne:

Autorytatywny odniesienie do integracji:

Uznane porównania/tutoriale: