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 open source, który możesz uruchomić w terminalu (TUI + CLI) z opcjonalnymi powierzchniami pulpitu i IDE. Oto Szybki start OpenCode: instalacja, weryfikacja, połączenie z modelem/dostawcą oraz uruchomienie rzeczywistych przepływów pracy (CLI + API).

Uwaga dotycząca wersji: OpenCode szybko rozwija się. Komendy „latest” tutaj są stabilne, ale wyniki i domyślne ustawienia mogą się zmieniać — zawsze sprawdzaj oficjalne dokumenty CLI i dziennik 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 mieści się)

OpenCode jest zaprojektowany do kodowania z terminala jako pierwszego planu, z agencją i jednocześnie jest elastyczny pod względem dostawcy/modelu. W praktyce to warstwa przepływu pracy, która może:

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

opencode z samowystawionym qwen3.5 27b LLM

Jeśli budujesz klaster /ai-devtools/, OpenCode jest silnym kandydatem do podklastera, ponieważ naturalnie rozwija się w kierunku:

  • głębokiego zrozumienia CLI
  • zachowania i kosztów modelu/dostawcy (porównanie LLM wewnątrz OpenCode)
  • konfiguracji i agentów
  • integracji (GitHub/GitLab/Copilot)
  • karty cheat

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).

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 (zalecane 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 Windows (oficjalna rekomendacja często sugeruje 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 forma wyjścia (zależy od wersji):

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

Połączenie z dostawcą (dwa praktyczne podejścia)

Ścieżka A: TUI /connect (interaktywna)

Uruchom OpenCode:

opencode

Następnie uruchom:

/connect

Postępuj zgodnie z krokami interfejsu użytkownika, aby wybrać dostawcę i uwierzytelnić się (niektóre przepływy otwierają przeglądarkę/logowanie na urządzeniu).

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

OpenCode obsługuje konfigurowanie dostawców za pomocą:

opencode auth login

Uwagi:

  • Poświadczenia są przechowywane w ~/.local/share/opencode/auth.json.
  • OpenCode może również ładować klucze z zmiennych środowiskowych lub pliku .env w Twoim projekcie.

Poprawny start projektu (zalecany pierwszy uruchomienie)

Z Twojego repozytorium:

cd /ścieżka/do/Twojego/repo
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 kontroli wersji, aby OpenCode (i koledzy) dzielili się spójnym kontekstem projektu.

Podstawowe przepływy CLI (przykłady do kopiowania i wklejania)

OpenCode obsługuje uruchamianie bezinteraktywne:

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

Przepływ pracy: generowanie kodu (CLI)

Cel: wygenerowanie małej, testowalnej funkcji z minimalnym kontekstem.

opencode run "Napisz funkcję Go ParsePort(envVar string, defaultPort int) (int, error). Powinna odczytywać zmienną środowiskową, parsować int, 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 zmienia się w zależności od modelu/dostawcy i monitu.

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

Cel: refaktoryzacja bez przypadkowych edycji za pomocą bardziej restrykcyjnego agenta.

opencode run --agent plan --file ./src/auth.ts \
  "Refaktoryzuj ten plik, aby zmniejszyć złożoność. Wynik: (1) krótki plan, (2) blok różnicy (diff), (3) ryzyka/brzegowych przypadków do testowania. Nie uruchamiaj poleceń."

Oczekiwany wynik:

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

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

Cel: szybkie znalezienie szczegółów implementacji.

opencode run --agent explore \
  "W tym repozytorium, gdzie weryfikowana jest 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 mapowanie ścieżek plików + opis przepływu.
  • Wynik zależy od rozmiaru repozytorium i narzędzi kontekstowych modelu/dostawcy.

Przepływ pracy: przyspieszenie powtarzalnych uruchomień CLI za pomocą trwało działającego serwera

Jeśli skryptujesz lub uruchamiasz wiele 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 "Podsumuj strukturę repozytorium i główne punkty 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 powtarzalnym obciążeniem startowym.

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 monit

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)
    // 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 monit
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 forma wyjścia:

  • „Serwer działa na …”
  • Odpowiedź stanu 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 dobre miejsce do rozpoczęcia 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 zgodność z tym, co pokazuje `opencode models`.
  "model": "dostawca/model",

  // Opcjonalnie: tańszy „mały model” do 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ótka karta cheat (szybki przewodnik)

Komendy, które używasz codziennie

opencode                       # uruchom TUI
opencode run "..."             # tryb bezinteraktywny (automatyzacja)
opencode run --file path "..." # dołącz pliki do monitu
opencode models --refresh      # odśwież listę modeli
opencode auth login            # skonfiguruj poświadczenia 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

Komendy TUI, które warto zapamiętać

/connect   # połącz się z dostawcą
/init      # analizuj repozytorium, generuj AGENTS.md
/share     # udostępnij sesję (jeśli włączono)
/undo      # cofnij zmianę
/redo      # ponów zmianę
/help      # pomoc/skróty

Koncept domyślnej „klawiszy lidera” (TUI)

OpenCode korzysta z konfigurowalnej „klawiszy lidera” (często ctrl+x) w celu uniknięcia konfliktów w terminalu. Wiele skrótów to „Leader + klawisz”.

FAQ (gotowy do schematu)

Co to jest OpenCode?

OpenCode to agent AI kodowania open source, zaprojektowany do pracy w terminalu (TUI + CLI) z dodatkowymi powierzchniami pulpitu i IDE.

Czy OpenCode jest darmowy?

Narzędzie jest open source. Koszt użycia zależy od połączonego modelu/dostawcy. Niektórzy dostawcy mogą oferować subskrypcyjną autoryzację lub darmowe warstwy.

Jak uruchomić OpenCode bez otwierania TUI?

Użyj opencode run "..." w trybie bezinteraktywnym (przydatne do skryptów/automatyzacji).

Gdzie OpenCode przechowuje poświadczenia dostawcy?

opencode auth login przechowuje poświadczenia w ~/.local/share/opencode/auth.json.

Czy OpenCode ma API / SDK?

Tak. OpenCode może uruchomić bezinterfejsowy serwer HTTP (opencode serve) z specyfikacją OpenAPI na /doc, a także oferuje oficjalny SDK JS/TS: @opencode-ai/sdk.

Czy mogę używać GitHub Copilota z OpenCode?

GitHub ogłosił, że Copilot obsługuje uwierzytelnianie z OpenCode za pomocą formalnej integracji. Dostępność zależy od Twojego planu Copilota i bieżącego przepływu uwierzytelniania dostawcy.

Jednostronowa drukowalna karta cheat OpenCode

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

Zadanie Komenda / skrót Uwagi
Uruchom TUI opencode Domyślnym zachowaniem jest uruchomienie interfejsu użytkownika terminala
Uruchom monit jednorazowy opencode run "..." Tryb bezinteraktywny do skryptów/automatyzacji
Dołącz plik(y) do monitu 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 modelu to dostawca/model
Wybierz agenta opencode run --agent plan "..." Plan jest zaprojektowany do bezpieczniejszych „bez zmian” prac (ograniczone uprawnienia)
Lista modeli opencode models [dostawca] Użyj --refresh, aby odświeżyć zapisaną listę
Skonfiguruj poświadczenia 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 serwer bezinterfejsowy 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 do uniknięcia powtarzających się startów
Włącz podstawowe uwierzytelnianie OPENCODE_SERVER_PASSWORD=... opencode serve Domyślnie nazwa użytkownika to opencode, chyba że nadpisano
Tryb interfejsu sieciowego opencode web Uruchamia serwer + 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 Konfigurowalny w tui.json

Źródła (oficjalne pierwsze)

Oficjalne:

Autorytatywna referencja integracji:

Pojęte porównania/tutoriale: