OpenCode Quickstart: Instalacja, konfiguracja i użycie agenta AI do kodowania w terminalu

Jak zainstalować, skonfigurować i korzystać z OpenCode

Page content

OpenCode to open-source agent do kodowania oparty na sztucznej inteligencji, którego można uruchamiać w terminalu (TUI + CLI) z opcjonalnymi interfejsami pulpitu i IDE. To Szybki start OpenCode: instalacja, weryfikacja, połączenie modelu/dostawcy oraz uruchamianie rzeczywistych procesów pracy (CLI + API).

Uwaga dotycząca wersji: OpenCode pojawia się w szybkim tempie. Poniższe „najnowsze” polecenia są stabilne, ale dane wyjściowe i wartości domyślne mogą ulec zmianie — 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 napędzanym przez AI.

Co to jest OpenCode (i gdzie się znajduje)

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

  • uruchamiać interfejs terminalowy (TUI) po uruchomieniu opencode
  • uruchamiać nieinteraktywne, jednorazowe prompty przez opencode run (skrypty/automatyzacja)
  • udostępniać bezgłowy serwer HTTP przez opencode serve (oraz interfejs webowy przez opencode web)
  • być sterowana programowo przez oficjalny JS/TS SDK @opencode-ai/sdk

Jeśli chcesz porównać go z innym open-source’owym asystentem agencją, który może wykonywać wieloetapowe plany w piaskownicy, zobacz Szybki start OpenHands Coding Assistant.

Dla terminal-first agenta Anthropic z tą samą historią „modelu lokalnego przez HTTP” (Ollama lub llama.cpp, uprawnienia, ceny), zobacz Instalacja i konfiguracja Claude Code dla Ollama, llama.cpp, ceny.

opencode z własnym serwerem qwen3.5 27b LLM

Wymagania wstępne

Potrzebujesz:

  • Nowoczesnego emulatora terminala (ważne dla doświadczenia TUI).
  • Dostępu do co najmniej jednego modelu/dostawcy (klucze API lub uwierzytelnianie 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żerów pakietów (oficjalne przykłady):

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

# Homebrew (zalecane przez OpenCode dla najnowniejszych wydań)
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). Alternatywy to Scoop/Chocolatey lub npm.

# chocolatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (przydatny do szybkiego sprawdzenia):

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

Weryfikacja instalacji

opencode --version
opencode --help

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

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

Połączenie dostawcy (dwa praktyczne sposoby)

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

Uruchom OpenCode:

opencode

Następnie uruchom:

/connect

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

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

OpenCode obsługuje konfigurację dostawców przez:

opencode auth login

Uwagi:

  • Dane uwierzytelniające 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 działa z każdym API zgodnym z OpenAI. W przypadku rozwoju lokalnego wielu użytkowników uruchamia Ollama i wskazuje OpenCode na niego. Niedawno miałem bardzo dobre doświadczenia z konfiguracją i uruchamianiem OpenCode z llama.cpp zamiast tego — llama-server udostępnia punkty końcowe zgodne z OpenAI, więc możesz używać modeli GGUF z tym samym przepływem pracy. Jeśli wolisz ścisłą kontrolę nad pamięcią i środowiskiem wykonawczym, lub chcesz lżejszego stosu bez Pythona (BTW, ollama jest zaimplementowany w Go), llama.cpp warto spróbować. Naprawdę doceniłem możliwość konfiguracji warstw offloadowanych, łatwość użycia 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 naprawdę dobrze sprawdzają się w OpenCode — w zadaniach kodowania i dokładności strukturyzowanego wyjścia — zobacz moje porównanie LLM dla OpenCode.

Poprawny start projektu (zalecany pierwszy uruchomienie)

Z Twojego repozytorium:

cd /path/to/your/repo
opencode

Następnie zainicjuj:

/init

To analizuje Twój projekt i tworzy plik AGENTS.md w korzeniu projektu. Zazwyczaj warto zatwierdzić ten plik, aby OpenCode (i współpracownicy) dzielili spójny kontekst projektu.

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

OpenCode obsługuje nieinteraktywne uruchomienia:

opencode run "Wyjaśnij, jak działają domknięcia 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 pusta. Dołącz 3 testy oparte na tablicy."

Oczekiwane dane wyjściowe:

  • Wyjaśnienie plus 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) jednolita łata diff, (3) ryzyka/przypadki brzegowe do przetestowania. Nie uruchamiaj poleceń."

Oczekiwane dane wyjściowe:

  • Sekcja planu + blok łaty diff --git ... + lista kontrolna testów.
  • Zawartość się różni. Jeśli nie wygeneruje diffu, ponownie promptuj: „Zwróć tylko jednolity diff” lub „Użyj formatu diff --git.”

Przepływ pracy: pytania o repozytorium (CLI)

Cel: szybkie zlokalizowanie szczegółów implementacji.

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

Oczekiwane dane wyjściowe:

  • 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 powtarzających się uruchomień CLI za pomocą trwałego serwera

Jeśli skryptujesz lub uruchamiasz wiele wywołań opencode run, możesz uruchomić bezgłowy serwer 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 wysokim wpływie i dlaczego."

Oczekiwane dane wyjściowe:

  • Takie same jak opencode run, ale zazwyczaj z mniejszym narzutem ponownego uruchamiania.

Użycie programowe (oficjalny JS/TS SDK)

OpenCode udostępnia serwer HTTP (OpenAPI) i dostarcza klienta JS/TS z bezpieczeństwem typów.

Instalacja:

npm install @opencode-ai/sdk

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

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

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

// Utwórz sesję i prompt
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 danych wyjściowych:

  • „Serwer działa na …”
  • Odpowiedź o stanie zdrowia 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 rozsądny punkt startowy dla konfiguracji lokalnej projektu.

Stwórz opencode.jsonc w korzeniu Twojego repozytorium:

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

  // Wybierz domyślny model (dostawca/model). Dostosuj to do tego, co pokazuje `opencode models`.
  "model": "provider/model",

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

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

  // Opcjonalna ochrona: wymagaj potwierdzenia przed edycją/poleceniami
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Krótki cheat sheet (szybkie odwołanie)

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

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

Warte zapamiętania polecenia TUI

/connect   # połą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ślna koncepcja „klucza lidera” (TUI)

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

Jednostronicowa, drukowalna tabela cheat sheet OpenCode

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

Zadanie Polecenie / skrót Uwagi
Uruchom TUI opencode Domyślne zachowanie to uruchomienie interfejsu terminalowego
Uruchom jednorazowy prompt opencode run "..." Tryb nieinteraktywny 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 provider/model "..." Ciągi modeli to provider/model
Wybierz agenta opencode run --agent plan "..." Plan jest zaprojektowany dla bezpieczniejszej pracy „bez zmian” (ograniczone uprawnienia)
Wyświetl modele opencode models [provider] Użyj --refresh, aby zaktualizować buforowaną listę
Skonfiguruj dane dostawcy opencode auth login Przechowuje dane w ~/.local/share/opencode/auth.json
Wyświetl uwierzytelnione dostawców opencode auth list / opencode auth ls Potwierdza, co widzi OpenCode
Uruchom bezgłowy 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 do unikania powtarzających się zimnych startów
Włącz podstawowe uwierzytelnianie OPENCODE_SERVER_PASSWORD=... opencode serve Nazwa użytkownika domyślnie to opencode, jeśli nie zostanie nadpisana
Tryb interfejsu webowego opencode web Uruchamia serwer i otwiera przeglądarkę
Eksportuj sesję opencode export [sessionID] Przydatne do archiwizacji lub udostępniania kontekstu
Importuj sesję opencode import session.json Można również importować z URL udostępniania
Wyświetl globalne flagi CLI opencode --help / opencode --version --print-logs + --log-level do debugowania
Koncepcja klucza lidera TUI domyślny klucz lidera często ctrl+x Konfigurowalny w tui.json

Oh My Opencode — rozszerz możliwości OpenCode za pomocą orkiestracji wielu agentów

Gdy OpenCode działa, naturalnym kolejnym krokiem jest Oh My Opencode — plugin społecznościowy, który otacza OpenCode w wieloagentową konstrukcję. Główna idea: wpisz ultrawork (lub ulw) w sesji, a orkiestrator (Sisyphus) przejmuje kontrolę, delegując podzadania do specjalistycznych agentów działających równolegle, każdy na rodzinie modeli, dla których jego prompty są dostrojone.

Trzy artykuły omawiają to w szczegółach:

OpenCode był jednym z pierwszych narzędzi, które zostały dotknięte przez politykę Anthropic blokującą dostęp do subskrypcji Claude dla stron trzecich — ruch wykonany w styczniu 2026 roku, miesiąc przed tym, jak to samo ograniczenie dotknęło OpenClaw. Oś czasu wzrostu i upadku OpenClaw dokumentuje oba te wydarzenia i szerszy wzorzec, który reprezentują one dla narzędzi agencji zbudowanych na subskrypcyjnym compute.

Źródła (najpierw oficjalne)

Oficjalne:

Autorytatywne odwołanie do integracji:

Wiarygodne porównania/tutorial:

Subskrybuj

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