Szybki start OpenCode: instalacja, konfiguracja i użycie terminalowego agenta AI do kodowania

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

Page content

OpenCode to otwartoźródłowy agent AI do programowania, który możesz uruchamiać w terminalu (TUI + CLI) z opcjonalnymi interfejsami desktopowymi i dla IDE. To jest Szybki start OpenCode: instalacja, weryfikacja, podłączenie modelu/dostawcy i uruchomienie prawdziwych przepływów pracy (CLI + API).

Uwaga dotycząca wersji: OpenCode rozwija się szybko. Polecenia „najnowsze" przedstawione tutaj są stabilne, ale wyjście i wartości domyślne mogą ulegać zmianom – zawsze sprawdzaj oficjalną dokumentację CLI i listę zmian (linki poniżej).

Ten artykuł jest częścią Narzędzia dla programistów AI: Kompletny przewodnik po rozwoju wspieranym przez AI.

Czym jest OpenCode (i gdzie się mieści)

OpenCode został zaprojektowany do kodu opartego na terminalu i agentowego, zachowując jednocześnie elastyczność co do dostawcy/modelu. W praktyce jest to warstwa przepływu pracy, która może:

  • uruchomić interfejs terminalowy (TUI) po wpisaniu opencode
  • uruchomić niereaktywne polecenia „jednorazowe" poprzez opencode run (skrypty/automatyzacja)
  • udostępnić serwer HTTP bez interfejsu użytkownika poprzez opencode serve (oraz interfejs WWW poprzez opencode web)
  • być sterowana programowo poprzez oficjalny SDK JS/TS @opencode-ai/sdk

Jeśli chcesz porównać go z innym otwartoźródłowym asystentem agentowym, który może wykonywać wieloetapowe plany w zdalnym środowisku, zobacz Szybki start OpenHands Coding Assistant.

Dla agenta Anthropic opartego na terminalu z tą samą historią „lokalny model przez HTTP" (Ollama lub llama.cpp, uprawnienia, cennik), zobacz Instalacja i konfiguracja Claude Code dla Ollama, llama.cpp, cennik.

opencode z hostowanym samodzielnie modelem qwen3.5 27b LLM

Wymagania wstępne

Będziesz potrzebować:

  • Nowoczesnego emulatora terminala (ważne dla doświadczenia TUI).
  • Dostępu do co najmniej jednego modelu/dostawcy (klucze API lub uwierzytelnienie subskrypcyjne, w zależności od dostawcy). Opcje lokalne, takie jak Ollama lub llama.cpp, działają bez kluczy API, gdy uruchomisz kompatybilny serwer lokalnie.

Instalacja OpenCode (kopiuj-wklej)

Oficjalny skrypt instalacyjny (Linux/macOS/WSL):

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

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

# Globalna instalacja Node.js
npm install -g opencode-ai

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

# Arch Linux (stabilny)
sudo pacman -S opencode

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

Uwagi dotyczące Windowsa (oficjalne wskazówki często zalecają WSL dla najlepszej kompatybilności). Alternatywami są Scoop/Chocolatey lub npm.

# chocoloatey (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

Oczekiwany kształt wyjścia (będzie się różnić w zależności od wersji):

# Przykład:
# <wyświetla numer wersji, np. vX.Y.Z>
# <wyświetla pomoc z dostępnymi poleceniami/podpoleceniami>

Podłączanie dostawcy (dwa praktyczne ścieżki)

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

Uruchom OpenCode:

opencode

Następnie uruchom:

/connect

Postępuj zgodnie z krokami interfejsu, aby wybrać dostawcę i uwierzytelnić się (niektóre przepływy otwierają przeglądarkę lub logowanie urządzenia).

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

OpenCode obsługuje konfigurowanie dostawców poprzez:

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.

Lokalne hostowanie LLM (Ollama, llama.cpp)

OpenCode działa z dowolnym API kompatybilnym z OpenAI. Do rozwoju lokalnego wielu użytkowników uruchamia Ollama i wskazuje na nią OpenCode. Niedawno miałem bardzo dobre doświadczenia z konfigurowaniem i uruchamianiem OpenCode z llama.cpp zamiast tego – 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 wolisz bardziej szczegółową kontrolę nad pamięcią i czasem wykonania lub chcesz lżejszej stosu bez Pythona (BTW, ollama jest napisane w Go), llama.cpp jest warte spróbowania. Bardzo podobała mi się możliwość konfigurowania warstw offload, łatwość obsługi modeli w formacie GGUF i znacznie lepsza/szybsza implementacja kompatybilności z nowymi modelami, takimi jak Qwen3.5. Jeśli chcesz wiedzieć, które modele faktycznie dobrze działają wewnątrz OpenCode – w zadaniach programistycznych i dokładności strukturalnego wyjścia – zobacz moje porównanie LLM dla OpenCode.

Rozpoczęcie projektu poprawnie (zalecane pierwsze uruchomienie)

Z twojego repozytorium:

cd /path/to/your/repo
opencode

Następnie zainicjuj:

/init

Analizuje to twój projekt i tworzy plik AGENTS.md w katalogu głównym projektu. Zazwyczaj warto zatwierdzić ten plik, aby OpenCode (i członkowie zespołu) mieli spójny kontekst projektu.

Podstawowe przepływy pracy CLI (przykłady do kopiowania)

OpenCode obsługuje uruchamiania niereaktywne:

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

Przepływ pracy: generowanie kodu (CLI)

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

opencode run "Napisz funkcję Go ParsePort(envVar string, defaultPort int) (int, error). Powinna odczytać zmienną środowiskową, sparsować int, zwalidować 1-65535 i zwrócić defaultPort, jeśli jest pusta. Dołącz 3 testy sterowane tabelami."

Oczekiwane wyjście:

  • Wyjaśnienie oraz bloki kodu (funkcja + testy). Dokładny kod zależy od modelu/dostawcy i promptu.

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

Cel: refaktoryzacja bez przypadkowych edycji przy użyciu bardziej restrykcyjnego agenta.

opencode run --agent plan --file ./src/auth.ts \
  "Refaktoryzuj ten plik, aby zmniejszyć złożoność. Wyjście: (1) krótki plan, (2) patch diff unified, (3) ryzyka/przypadki brzegowe do przetestowania. Nie uruchamiaj poleceń."

Oczekiwane wyjście:

  • Sekcja z planem + blok patcha diff --git ... + lista kontrolna testów.
  • Treść jest zmienna. Jeśli nie wygeneruje diff, ponów prompt: „Zwróć tylko unified diff" lub „Użyj formatu diff --git."

Przepływ pracy: zadawanie pytań o repozytorium (CLI)

Cel: szybkie lokalizowanie szczegółów implementacji.

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

Oczekiwane wyjście:

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

Przepływ pracy: przyspieszenie powtarzanych uruchomień CLI z serwerem trwałym

Jeśli skryptujesz lub uruchamiasz wiele wywołań opencode run, możesz uruchomić serwer bez interfejsu użytkownika 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 refaktoryzacje o dużym wpływie i dlaczego."

Oczekiwane wyjście:

  • Takie samo jak opencode run, ale zazwyczaj z mniejszym powtarzającym się nakładem uruchamiania.

Użycie programowe (oficjalny SDK JS/TS)

OpenCode udostępnia serwer HTTP (OpenAPI) i zapewnia typowo bezpieczny klient JS/TS.

Instalacja:

npm install @opencode-ai/sdk

Przykład: uruchomienie serwera + klienta, następnie prompt

Stwó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 string modelu to provider/model (tylko przykład)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

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

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

// Stwórz sesję i wyślij prompt
const session = await opencode.client.session.create({ body: { title: "SDK quickstart demo" } });

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

console.log(result.data);

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

Uruchom:

node scripts/opencode-sdk-demo.mjs

Oczekiwany kształt wyjścia:

  • „Serwer działa pod adresem …"
  • Odpowiedź o zdrowiu zawierająca ciąg wersji
  • Obiekt odpowiedzi promptu sesji (dokładna struktura zależy od responseStyle i wersji SDK)

Minimalna konfiguracja OpenCode do skopiowania

OpenCode obsługuje konfigurację JSON i JSONC. To jest rozsądny punkt wyjścia dla konfiguracji lokalnej projektu.

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

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

  // Wybierz domyślny model (dostawca/model). Zgodnie 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: wartości domyślne serwera OpenCode (używane przez serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // Opcjonalnie bezpieczeństwo: wymagaj potwierdzenia przed edycjami/poleceniami
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Krótka ściągawka (szybkie odniesienie)

Polecenia używane codziennie

opencode                       # uruchom TUI
opencode run "..."             # uruchomienie niereaktywne (automatyzacja)
opencode run --file path "..." # dołącz pliki do promptu
opencode models --refresh      # odśwież listę modeli
opencode auth login            # skonfiguruj poświadczenia dostawcy
opencode serve                 # serwer HTTP bez interfejsu (OpenAPI)
opencode web                   # serwer bez interfejsu + interfejs WWW
opencode session list          # lista sesji
opencode stats                 # statystyki tokenów/kosztów

Polecenia TUI do zapamiętania

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

Domyślna koncepcja „klawisza przywódcy" (TUI)

OpenCode używa konfigurowalnego klawisza „lidera" (zazwyczaj ctrl+x), aby uniknąć konfliktów w terminalu. Wiele skrótów to „Lider + klawisz".

Jednostronicowa drukowalna tabela-ściągawka OpenCode

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

Zadanie Polecenie / skrót Uwagi
Uruchom TUI opencode Domyślne zachowanie to uruchomienie interfejsu terminalowego
Uruchom jednorazowy prompt opencode run "..." Tryb niereaktywny do skryptów/automatyzacji
Dołącz plik(i) do promptu opencode run --file path/to/file "..." Użyj wielu flag --file dla wielu plików
Wybierz model dla uruchomienia opencode run --model dostawca/model "..." Ciągi modeli to dostawca/model
Wybierz agenta opencode run --agent plan "..." Plan jest zaprojektowany dla bezpieczniejszej pracy „bez zmian" (ograniczone uprawnienia)
Wylistuj modele opencode models [dostawca] Użyj --refresh, aby zaktualizować buforowaną listę
Skonfiguruj poświadczenia dostawcy opencode auth login Przechowuje poświadczenia w ~/.local/share/opencode/auth.json
Wylistuj uwierzytelnionych dostawców opencode auth list / opencode auth ls Potwierdza, co widzi OpenCode
Uruchom serwer bez interfejsu opencode serve --port 4096 --hostname 127.0.0.1 Specyfikacja OpenAPI pod http://host:port/doc
Dołącz uruchomienia do serwera opencode run --attach http://localhost:4096 "..." Przydatne do uniknięcia powtarzających się zimnych startów
Włącz podstawowe uwierzytelnianie OPENCODE_SERVER_PASSWORD=... opencode serve Nazwa użytkownika domyślnie to opencode, chyba że nadpisana
Tryb interfejsu WWW 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 też importować z URL udostępnienia
Wyświetl globalne flagi CLI opencode --help / opencode --version --print-logs + --log-level do debugowania
Koncepcja klawisza lidera TUI domyślny klawisz lidera często ctrl+x Konfigurowalny w tui.json

Oh My Opencode — zabierz OpenCode dalej z orkiestracją wieloagentową

Gdy OpenCode działa, naturalnym kolejnym krokiem jest Oh My Opencode – plugin społecznościowy, który owija OpenCode w osłonę wieloagentową. Główna idea: wpisz ultrawork (lub ulw) w sesji, a orchestrator (Sisyphus) przejmuje kontrolę, delegując podzadania specjalistycznym agentom, którzy działają równolegle, każdy na rodzinie modeli, dla których są dostrojone.

Trzy artykuły omawiają to szczegółowo:

Źródła (najpierw oficjalne)

Oficjalne:

Autorytatywne odniesienie do integracji:

Poważne porównania/tutorial:

Subskrybuj

Otrzymuj nowe wpisy o systemach, infrastrukturze i inżynierii AI.