Szybki start OpenCode: instalacja, konfiguracja i użycie agenta kodującego AI w terminalu

Jak zainstalować, skonfigurować i wykorzystać OpenCode

Page content

OpenCode to otwartoźródłowy agent AI do programowania, którego można uruchamiać w terminalu (TUI + CLI) z opcjonalnymi interfejsami desktopowymi i w IDE. To jest Szybki start OpenCode: instalacja, weryfikacja, podłączenie modelu/dostawcy oraz uruchamianie rzeczywistych procesów pracy (CLI + API).

Uwaga dotycząca wersji: OpenCode jest wydawany szybko. Poniższe polecenia „latest” są stabilne, ale wyjście i wartości domyślne mogą się zmieniać — zawsze cross-checkuj oficjalną dokumentację CLI i changelog (podlinkowane poniżej).

Ten artykuł stanowi część Narzędzia dla deweloperów AI: Kompletny przewodnik po programowaniu z napędem AI. Jeśli również utrzymujesz własnego asystenta (self-hosted), takiego jak Nous Hermes, Karta ściągawki CLI Agent Hermes mapuje zestaw poleceń hermes obok tego szybkiego startu OpenCode.

Czym jest OpenCode (i gdzie pasuje)

OpenCode został zaprojektowany do programowania agentowego z priorytetem terminala, pozostając jednocześnie elastycznym względem dostawcy/modelu. W praktyce to warstwa workflow, która może:

  • uruchamiać interfejs terminala (TUI), gdy wykonujesz opencode
  • wykonywać nielinteraktywne, jednorazowe prompty za pomocą opencode run (skrypty/automatyzacja)
  • wystawiać bezgłowy serwer HTTP za pomocą opencode serve (oraz interfejs webowy za pomocą opencode web)
  • być sterowany programowo 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 piaskownicowym, zobacz Szybki start asystenta kodującego OpenHands.

W przypadku agenta Anthropic o priorytecie terminalowym z tą samą historią „lokalnego modelu przez HTTP” (Ollama lub llama.cpp, uprawnienia, cennik), zobacz Instalacja i konfiguracja Claude Code dla Ollama, llama.cpp, cennika.

Dla celowo minimalnego podejścia do tego samego pomysłu agenta terminalowego — cztery narzędzia domyślne, brak wbudowanej piaskownicy, wszystko inne przez rozszerzenia — zobacz recenzję Agent kodujący Pi.

opencode with self-hosted 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 uwierzytelnianie subskrypcyjne, w zależności od dostawcy). Opcje lokalne, takie jak Ollama lub llama.cpp działają bez kluczy API, gdy uruchamiasz 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 (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 (stabilne)
sudo pacman -S opencode

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

Uwagi dotyczące Windows (oficjalne wytyczne często zalecają WSL dla najlepszej kompatybilności). Alternatywy obejmują Scoop/Chocolatey lub npm.

# chocoloatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (przydatne do szybkiego wypróbowania):

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

Weryfikacja instalacji

opencode --version
opencode --help

Oczekiwany kształt wyjścia (może 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 wykonaj:

/connect

Postępuj zgodnie z krokami w interfejsie, aby wybrać dostawcę i uwierzytelniać się (niektóre przepływy otwierają logowanie w przeglądarce/urządzeniu).

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

Hostowanie lokalnych LLM (Ollama, llama.cpp)

OpenCode działa z dowolnym API kompatybilnym z OpenAI. Do programowania lokalnego wielu użytkowników uruchamia Ollama i kieruje OpenCode do niego. Ostatnio miałem bardzo dobre doświadczenie z konfiguracją i uruchamianiem OpenCode z llama.cpp zamiast tego — llama-server wystawia końcówki kompatybilne z OpenAI, więc możesz używać modeli GGUF z tym samym workflow. Jeśli wolisz precyzyjną kontrolę nad pamięcią i środowiskiem uruchomieniowym, lub chcesz lżejszego stacku bez Pythona (PS, ollama jest zaimplementowany w Go), llama.cpp jest warty spróbowania. Bardzo podobała mi się możliwość konfiguracji warstw offloaded, łatwość użycia modeli w formacie GGUF oraz znacznie lepsza/szybsza implementacja kompatybilności z nowymi modelami, takimi jak Qwen3.5. Jeśli chcesz wiedzieć, które modele naprawdę dobrze działają w OpenCode — w zadaniach kodowania i dokładności wyjść strukturalnych — zobacz moje praktyczne porównanie LLM dla OpenCode.

Poprawne rozpoczęcie projektu (zalecane pierwsze uruchomienie)

Z Twojego repozytorium:

cd /path/to/your/repo
opencode

Następnie zainicjalizuj:

/init

Działanie to analizuje Twój projekt i tworzy plik AGENTS.md w głównym katalogu projektu. Zazwyczaj warto commitować ten plik, aby OpenCode (i koledzy) dzielili spójny kontekst projektu.

Podstawowe workflow CLI (przykłady do skopiowania)

OpenCode obsługuje uruchomienia nielinteraktywne:

opencode run "Explain how closures work in JavaScript"

Dla wzorców workflow wiersza poleceń — piping wyjścia git, cele Makefile i CI, polityki uprawnień dla uruchomień bez nadzoru — oraz oczekiwanych trybów awarii, zobacz Praktyczny przewodnik CLI OpenCode. Opiera się on na tym szybkim starcie, zamiast go powtarzać.

Workflow: generowanie kodu (CLI)

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

opencode run "Write a Go function ParsePort(envVar string, defaultPort int) (int, error). It should read the env var, parse an int, validate 1-65535, and return defaultPort if empty. Include 3 table-driven tests."

Oczekiwane wyjście:

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

Workflow: bezpieczna refaktoryzacja pliku (CLI + agent Plan)

Cel: potwierdzenie, że bardziej restrykcyjny agent plan działa, zanim na nim polegamy.

opencode run --agent plan --file ./src/auth.ts \
  "Refactor this file to reduce complexity. Output a short plan only. Do not run commands."

Oczekiwane wyjście: sekcja planu, brak edycji plików, brak wykonanych poleceń.

Workflow: zadawanie pytań o repozytorium (CLI)

Cel: potwierdzenie, że agent explore może zlokalizować szczegóły implementacji.

opencode run --agent explore \
  "Where is authentication validated for API requests in this repository?"

Oczekiwane wyjście: krótka mapa ścieżek plików i opis przepływu.

Oba te działania to jednorazowe testy dymne (smoke tests). Dla ograniczonej, produkcyjnej wersji tych samych zadań — jawnego wyjścia ryzyka/wypadków brzegowych, łat unified-diff, promptów eksploracyjnych uwzględniających uprawnienia oraz postępowania, gdy model nie współpracuje — zobacz sekcję „Najlepsze przypadki użycia CLI OpenCode” w Praktycznym przewodniku CLI OpenCode.

Workflow: przyspieszenie powtarzanych uruchomień CLI za pomocą trwałego serwera

Jeśli piszesz skrypty lub wykonujesz 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 "Summarize the repo structure and main entrypoints."
opencode run --attach http://localhost:4096 "Now propose 3 high-impact refactors and why."

Oczekiwane wyjście:

  • Takie samo jak opencode run, ale zazwyczaj z mniejszym powtarzalnym obciążeniem startowym.

Użycie programowe (oficjalne SDK JS/TS)

OpenCode wystawia serwer HTTP (OpenAPI) i zapewnia typowane klient JS/TS.

Instalacja:

npm install @opencode-ai/sdk

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

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

console.log(`Server running at: ${opencode.server.url}`);

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

// Utworzenie sesji i promptu
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: "Generate a small README section describing this repo." }],
  },
});

console.log(result.data);

// Zamknięcie serwera po zakończeniu
opencode.server.close();

Uruchomienie:

node scripts/opencode-sdk-demo.mjs

Oczekiwany kształt wyjścia:

  • „Server running at …”
  • Odpowiedź o zdrowiu zawierająca ciąg wersji
  • Obiekt odpowiedzi na prompt 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 rozsądny punkt wyjścia dla konfiguracji lokalnej projektu.

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

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

  // Wybierz domyślny model (provider/model). Zachowaj zgodność z tym, co pokazuje `opencode models`.
  "model": "provider/model",

  // Opcjonalnie: tańszy „mały model” do 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"
  },

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

Dla bardziej kompletnej polityki uprawnień przeznaczonej do niepilnowanych zadań opencode run, zobacz Praktyczny przewodnik CLI OpenCode.

Krótka karta ściągawki (szybkie odniesienie)

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

opencode                       # uruchom TUI
opencode run "..."             # uruchomienie nielinteraktywne (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                 # bezgłowy serwer HTTP (OpenAPI)
opencode web                   # bezgłowy serwer + interfejs webowy
opencode session list          # lista sesji
opencode stats                 # statystyki tokenów/kosztów

Polecenia TUI warte zapamiętania

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

Domyślna koncepcja „klawisza lidera” (TUI)

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

Jednostronicowa, wydrukowalna tabela ściągawki OpenCode

Ta wersja jest celowo gęsta i „przyjazna wydrukom”. (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 terminala
Uruchom jednorazowy prompt opencode run "..." Tryb nielinteraktywny 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 do uruchomienia opencode run --model provider/model "..." Ciągi modeli to provider/model
Wybierz agenta opencode run --agent plan "..." Plan jest zaprojektowany do bezpieczniejszej pracy „bez zmian” (ograniczone uprawnienia)
Lista modeli opencode models [provider] Użyj --refresh, aby zaktualizować zbufowaną 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 bezgłowy serwer 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, aby uniknąć powtarzalnych zimnych startów
Włącz podstawowe uwierzytelnianie OPENCODE_SERVER_PASSWORD=... opencode serve Nazwa użytkownika domyślnie to opencode, chyba że przesłonięto
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że również importować z URL udostępniania
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 — idź dalej z OpenCode dzięki orkiestracji wielu agentów

Gdy OpenCode działa, naturalnym kolejnym krokiem jest Oh My Opencode — plugin społecznościowy, który owija OpenCode w szkielet wieloagentowy. Główny pomysł: 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órej jego prompty są dostrojone.

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

OpenCode był jednym z pierwszych narzędzi dotkniętych polityką Anthropic blokującą dostęp do subskrypcji Claude przez strony trzecie — ruch poczyniony w styczniu 2026 r., miesiąc przed tym, jak to samo ograniczenie dotknęło OpenClaw. Oś czasu wzrostu i upadku OpenClaw dokumentuje oba wydarzenia oraz szerszy wzorzec, jaki reprezentują dla narzędzi agentowych zbudowanych na subskrypcyjnym obliczeniu.

Źródła (najpierw oficjalne)

Oficjalne:

Autorytatywne odniesienie integracyjne:

Wiarygodne porównania/tutoriale:

Subskrybuj

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