OpenCode – szybki start: instalacja, konfiguracja i użycie agenta kodowania AI w terminalu

Jak zainstalować, skonfigurować i korzystać z OpenCode

Page content

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

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

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

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

OpenCode został zaprojektowany do kodowania opartego na terminalu i agentów, zachowując elastyczność wyboru dostawcy i modelu. W praktyce jest to warstwa przepływu pracy, która może:

  • uruchomić interfejs terminalowy (TUI) po wykonaniu polecenia opencode
  • uruchomić nieludzkie, jednorazowe zapytania za pomocą opencode run (skrypty/automatyzacja)
  • udostępnić bezserwerowy serwer HTTP za pomocą opencode serve (oraz interfejs webowy za pomocą opencode web)
  • być sterowana programistycznie za pomocą oficjalnego 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 środowisku piaskownicy, zobacz Szybki start z OpenHands Coding Assistant.

opencode with self-hosted qwen3.5 27b LLM

Jeśli budujesz klastr /ai-devtools/, OpenCode jest silnym kandydatem na podklastr, ponieważ naturalnie rozszerza się o:

  • dogłębną analizę CLI
  • zachowanie i koszty modeli/dostawców (porównanie LLM wewnątrz OpenCode)
  • konfigurację i agentów
  • integracje (GitHub/GitLab/Copilot)
  • ściągę
  • Oh My Opencode — warstwa koordynacji wieloagentowej zbudowana na bazie OpenCode

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 wydań)
brew install anomalyco/tap/opencode

# Arch Linux (stabilna wersja)
sudo pacman -S opencode

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

Uwagi dotyczące Windowsa (oficjalne wytyczne często zalecają 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

Oczekiwany kształt wyjścia (będzie zależał od wersji):

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

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

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

Uruchom OpenCode:

opencode

Następnie wykonaj:

/connect

Postępuj zgodnie z krokami w 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 konfigurację 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 ze zmiennych środowiskowych lub pliku .env w Twoim projekcie.

Lokalne hostowanie LLM (Ollama, llama.cpp)

OpenCode współpracuje z każdym API kompatybilnym z OpenAI. Do rozwoju lokalnego wielu użytkowników uruchamia Ollama i wskazuje na niego OpenCode. Ostatnio miałem bardzo dobre doświadczenia z konfiguracją i uruchamianiem OpenCode z llama.cpp zamiast Ollama – serwer llama 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 środowiskiem uruchomieniowym lub lżejszy stos bez Pythona (BTW, ollama jest zaimplementowany w Go), llama.cpp jest warte spróbowania. Bardzo cieszyłem się możliwością konfiguracji warstw offloadowanych, łatwością używania modeli w formacie GGUF oraz znacznie lepszą/szybszą implementacją kompatybilności z nowymi modelami, takimi jak Qwen3.5. Jeśli chcesz wiedzieć, które modele faktycznie dobrze się spisują wewnątrz OpenCode – w zadaniach kodowania i dokładności strukturalnego wyjścia – zobacz moje porównanie LLM dla OpenCode.

Poprawne rozpoczęcie projektu (zalecany pierwszy 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 współpracownicy) mogli udostępniać spójny kontekst projektu.

Główne przepływy pracy CLI (przykłady do kopiowania)

OpenCode obsługuje uruchamiania nieludzkie:

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 ona odczytać zmienną środowiskową, sparsować int, zwalidować zakres 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 zapytania.

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

Cel: refaktoryzacja bez przypadkowych zmian dzięki użyciu bardziej restrykcyjnego agenta.

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

Oczekiwane wyjście:

  • Sekcja z planem + blok łatki diff --git ... + lista kontrolna testów.
  • Treść się różni. Jeśli nie wygeneruje diff, ponów zapytanie: „Zwróć tylko jednolitą 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 masz wątpliwości, 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 stałym

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

Terminal 1:

opencode serve --port 4096 --hostname 127.0.0.1

Terminal 2:

opencode run --attach http://localhost:4096 "Streszcz strukturę repozytorium i główne punkty wejścia."
opencode run --attach http://localhost:4096 "Teraz zaproponuj 3 refaktoryzacje o dużym wpływie i wyjaśnij dlaczego."

Oczekiwane wyjście:

  • Tak samo jak opencode run, ale zazwyczaj z mniejszym powtarzającym się nakładem na start.

Użycie programistyczne (oficjalne SDK JS/TS)

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

Zainstaluj:

npm install @opencode-ai/sdk

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

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 ciągu modelu to dostawca/model (tylko przykład)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Serwer uruchomiony 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 zapytaj
const session = await opencode.client.session.create({ body: { title: "Demo 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ą 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 uruchomiony pod adresem …"
  • Odpowiedź dotycząca zdrowia zawierająca ciąg wersji
  • Obiekt odpowiedzi zapytania sesji (dokładna struktura zależy od responseStyle i wersji SDK)

Minimalna konfiguracja OpenCode do skopiowania

OpenCode obsługuje konfigurację JSON i JSONC. To 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). Utrzymuj to zgodne 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: wartości domyślne serwera OpenCode (używane przez serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

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

Krótka ściągawka (szybkie odniesienie)

Komendy, których będziesz używać codziennie

opencode                       # uruchom TUI
opencode run "..."             # uruchomienie nieludzkie (automatyzacja)
opencode run --file path "..." # dołącz pliki do zapytania
opencode models --refresh      # odśwież listę modeli
opencode auth login            # skonfiguruj poświadczenia dostawcy
opencode serve                 # serwer HTTP bezserwerowy (OpenAPI)
opencode web                   # serwer bezserwerowy + interfejs webowy
opencode session list          # wyszczególnij sesje
opencode stats                 # statystyki tokenów/kosztów

Komendy TUI, które warto zapamiętać

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

Domyślne pojęcie „klawisza lidera" (TUI)

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

Jednostronicowa, drukowalna tabela ściągawki OpenCode

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

Zadanie Komenda / skrót Uwagi
Uruchom TUI opencode Domyślne zachowanie to uruchomienie interfejsu terminalowego
Uruchom jednorazowe zapytanie opencode run "..." Tryb nieludzki do skryptowania/automatyzacji
Dołącz plik(i) do zapytania 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 został zaprojektowany do bezpieczniejszej pracy „bez zmian" (ograniczone uprawnienia)
Wyświetl listę modeli opencode models [dostawca] Użyj --refresh, aby zaktualizować zwłoczoną listę
Skonfiguruj poświadczenia dostawcy opencode auth login Przechowuje poświadczenia w ~/.local/share/opencode/auth.json
Wyświetl uwierzytelnionych dostawców opencode auth list / opencode auth ls Potwierdza, co widzi OpenCode
Uruchom serwer bezserwerowy opencode serve --port 4096 --hostname 127.0.0.1 Specyfikacja OpenAPI pod http://host:port/doc
Podłącz uruchomienia do serwera opencode run --attach http://localhost:4096 "..." Przydatne, aby uniknąć 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 webowego opencode web Uruchamia serwer + otwiera przeglądarkę
Eksportuj sesję opencode export [sessionID] Przydatne do archiwizacji lub udostępniania kontekstu
Importuj sesję opencode import session.json Można też importować z URL udostępniania
Wyświetl globalne flagi CLI opencode --help / opencode --version --print-logs + --log-level do debugowania
Pojęcie klawisza lidera TUI domyślny klawisz lidera często ctrl+x Konfigurowalny w tui.json

Oh My Opencode – posuń OpenCode dalej z koordynacją wieloagentową

Gdy OpenCode działa, naturalnym następnym krokiem jest Oh My Opencode – wtyczka społecznościowa, która owija OpenCode w wieloagentowe osprzęt. Główna idea: wpisz ultrawork (lub ulw) w sesji, a koordynator (Sisyphus) przejmuje kontrolę, delegując zadania podagentom, którzy działają równolegle, każdy na rodzinie modeli, dla których są dostosowane ich zapytania.

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

Źródła (najpierw oficjalne)

Oficjalne:

Autorytatywny referencje integracyjne:

Wiarygodne porównania/tutorial: