OpenCode z API kompatybilnym z OpenAI: Konfiguracja

Czego potrzebujesz przed rozpoczęciem

OpenCode to open-source agent kodujący działający w terminalu. Może łączyć się z wieloma dostawcami modeli i pozwala dodać własnego dostawcę, jeśli endpoint jest zgodny z formatem czatu OpenAI. To API jest zgodne, więc konfiguracja sprowadza się do wypełnienia kilku pól.

Najpierw zbierz te trzy wartości:

• Adres URL podstawowy: https://api.kimicode.top/v1
• Identyfikator modelu: uncensored
• Klucz API: utwórz go na stronie klucza API. Nowe konta mogą zaksięgować tam $0.50 kredytu próbnego jednym kliknięciem, co wystarczy do poniższych testów. Klucz próbny pozwala na 2 równoległe zapytania i 60 zapytań na minutę.

Przechowuj klucz w zmiennej środowiskowej zamiast wklejać go do plików, które dodajesz do repozytorium:

Copyexport KIMICODE_API_KEY="your-key-here"

Krok 1: przetestuj endpoint za pomocą curl

Zrób to przed skonfigurowaniem dowolnego narzędzia. Jeśli curl działa, a OpenCode nie, wiesz, że problem leży w konfiguracji. Jeśli curl nie działa, naprawiasz klucz lub URL raz, a nie w dwóch miejscach.

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Say hello in five words."}],
    "max_tokens": 40
  }'

Powinieneś otrzymać obiekt JSON z tablicą choices i blokiem usage. Kod 401 oznacza, że klucz jest nieprawidłowy lub brakuje prefiksu Bearer. Kod 404 zwykle oznacza literówkę w URL lub to, że URL zawiera już /chat/completions.

Agent kodujący strumieniuje odpowiedzi i wywołuje narzędzia, dlatego sprawdź również te dwie funkcje:

Copycurl -N https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to five."}]
  }'

Powinieneś zobaczyć serię linii data:, z których każda zawiera mały obiekt delta JSON, kończąc się statystykami użycia i znacznikiem końcowym. Flaga -N wyłącza buforowanie curl, dzięki czemu fragmenty pojawiają się w miarę ich przybywania.

Krok 2: dodaj niestandardowego dostawcę do OpenCode

OpenCode odczytuje plik konfiguracyjny JSON, opencode.json, z folderu projektu lub z globalnego katalogu konfiguracyjnego. Niestandardowych dostawców w stylu OpenAI definiuje się za pomocą pakietu kompatybilnego z OpenAI SDK AI, podając Base URL i listę modeli. Poniższy układ odpowiada publicznej dokumentacji OpenCode na moment pisania tego przewodnika. Nazwy pól mogą się zmieniać między wydaniami, dlatego porównaj go z sekcją dostawców w aktualnej dokumentacji OpenCode, jeśli coś zostanie odrzucone.

Copy{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kimicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kimicode API",
      "options": {
        "baseURL": "https://api.kimicode.top/v1",
        "apiKey": "{env:KIMICODE_API_KEY}"
      },
      "models": {
        "uncensored": {
          "name": "Uncensored",
          "limit": {
            "context": 100000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "kimicode/uncensored"
}

Klucz pod models to dokładne ID modelu wysyłane do serwera, więc musi mieć wartość uncensored. Ostatnia linia wybiera dostawcę i model jako domyślne, zapisane jako nazwa dostawcy, ukośnik, a następnie ID modelu.

Forma {env:KIMICODE_API_KEY} mówi OpenCode, aby odczytało zmienną z powłoki. Jeśli Twoja wersja obsługuje uwierzytelnianie za pomocą własnego polecenia logowania, użyj tej ścieżki i nie dodawaj klucza do pliku. W każdym razie nie dodawaj prawdziwego klucza do repozytorium.

Konfiguracja projektu lub globalna

Możesz umieścić blok dostawcy w dwóch miejscach. Plik w katalogu głównym projektu dotyczy tylko tego repozytorium, co pasuje do zespołu dzielącego jedną konfigurację. Plik w katalogu konfiguracji użytkownika dotyczy wszystkich projektów, co pasuje do domyślnego ustawienia osobistego. Jeśli istnieją oba, konfiguracja projektu dodaje się do lub nadpisuje konfigurację globalną.

Preferuj plik globalny dla definicji dostawcy i zmienną środowiskową dla klucza. Dzięki temu każde repozytorium może korzystać z endpointu, a nic poufnego nie znajduje się obok kodu źródłowego. Jeśli w projekcie pracuje kilka osób, dodaj do repozytorium tylko blok dostawcy bez klucza, a każda osoba powinna ustawić swoją własną zmienną. Ułatwia to też rotację klucza: zmień zmienną, zrestartuj terminal i plik konfiguracyjny pozostaje niezmieniony.

Krok 3: wybierz model i uruchom zadanie

Uruchom OpenCode w folderze projektu i otwórz selektor modeli. Twój niestandardowy dostawca powinien pojawić się na liście z nazwą wyświetlaną, którą ustawiłeś. Wybierz go, a następnie zleć agentowi małe, weryfikowalne zadanie, np. wyjaśnienie funkcji lub napisanie testu jednostkowego dla krótkiego pliku.

Zacznij od prostego zadania z dwóch powodów. Po pierwsze, możesz sprawdzić, czy wywoływanie narzędzi działa: gdy OpenCode prosi model o odczytanie lub edycję pliku, robi to przez interfejs wywoływania narzędzi. Po drugie, agent kodujący wysyła dużo tekstu na jedną turę, w tym zawartość plików i historię, więc długa sesja szybko zużywa tokeny. W kolejnej sekcji przedstawiamy liczby.

Jeśli model nie pojawia się, sprawdź, czy plik jest poprawnym JSON, czy znajduje się w miejscu, w którym OpenCode szuka konfiguracji, i czy nazwa dostawcy zgadza się z tym, co wpisałeś w polu model.

Bezpośrednie testowanie wywoływania narzędzi i trybu JSON

OpenCode opiera się na wywoływaniu narzędzi do odczytu plików, uruchamiania poleceń i edycji kodu, dlatego warto potwierdzić, że endpoint obsługuje definicję narzędzia, zanim obwinisz agenta za błąd. To zapytanie oferuje jedno narzędzie i zadaje pytanie, które go wymaga.

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "read_file",
        "description": "Read a text file by path",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Dobra odpowiedź zawiera wpis tool_calls z nazwą read_file i ciągiem argumentów JSON. Agent wykonuje narzędzie, a następnie wysyła wynik z powrotem jako wiadomość z role ustawionym na tool, a model kontynuuje działanie. Jeśli widzisz tylko zwykły tekst, spróbuj bardziej bezpośredniego promptu, ponieważ to, czy model zdecyduje się wywołać narzędzie, jest częścią jego zachowania.

Tryb JSON to osobne przełączenie. Dodanie "response_format": {"type": "json_object"} żąda poprawnego wyjścia JSON, co pomaga, gdy inny skrypt musi zinterpretować zwrócone dane. Wspomnij o JSON w swoim promptcie, aby model wiedział, jakiego kształtu oczekujesz.

Rozmiar okna kontekstu i koszt sesji

Okno kontekstu wynosi 100,000 tokenów, licząc razem prompt i uzupełnienie. Ustawienie limit.context na 100000 informuje agenta o rzeczywistej granicy, dzięki czemu może on przycinać lub podsumowywać historię przed odrzuceniem zapytania przez serwer. Uzupełnienie może wykorzystać dowolną dostępną przestrzeń, a max_tokens jest opcjonalne.

Rozliczenie wynosi $0.15 za 1M tokenów wejściowych i $0.50 za 1M tokenów wyjściowych. Agenci generują dużo ruchu wejściowego, ponieważ każda tura ponownie wysyła całą rozmowę. Oto przykładowe obliczenia dla umiarkowanej sesji:

• 40 tur, każda wysyła około 30,000 tokenów wejściowych: 1,200,000 tokenów wejściowych, co daje 1.2 x $0.15 = $0.18.
• Każda tura zwraca około 800 tokenów wyjściowych: 32,000 tokenów wyjściowych, co daje 0.032 x $0.50 = $0.016.
• Razem: $0.196, czyli około dwadzieścia centów za całą sesję.

Twoje liczby będą się różnić. Odczytuj wartości usage w odpowiedziach lub obserwuj nagłówek X-Balance-USD, który podaje Twoje pozostałe saldo w każdej odpowiedzi. Kredyt jest przedpłacony i nigdy nie wygasa, a nieudane lub odrzucone zapytania nie są rozliczane. Szczegóły znajdziesz na stronie z cenami.

Realne oczekiwania wobec agenta kodującego

To ogólny model tekstowy dostosowany do odpowiadania bez odrzucania treści dla prawnego użytku dorosłych. Nie jest to model zbudowany specjalnie do kodu, a ta strona nie zawiera żadnych twierdzeń benchmarkowych. To, czy niezawodnie edytuje Twoje repozytorium, powinieneś przetestować na własnych zadaniach, z włączoną kontrolą wersji, zanim powierzysz mu cokolwiek ważnego.

Obsługuje infrastrukturę potrzebną agentowi: wywoływanie narzędzi ze strumieniowaniem tool_calls, wyniki narzędzi wysyłane z powrotem jako wiadomości role: "tool" oraz tryb JSON przez response_format. Obsługuje tylko tekst, bez obrazów, więc funkcje wymagające dołączania zrzutów ekranu nie będą działać.

Dla agentów istotne są dwa limity. Pełny klucz pozwala na 8 równoległych zapytań i 300 zapytań na minutę. Sub-agenci lub równoległe uruchomienia narzędzi, które wysyłają wiele wywołań naraz, mogą przekroczyć limit współbieżności, a strumieniowane zapytanie zajmuje slot do końca strumienia. W takim przypadku otrzymasz HTTP 429 z kodem concurrency. Kod rate_limited oznacza zbyt wiele zapytań na minutę. Przy tymczasowym przeciążeniu możesz również zobaczyć 429 z Retry-After: 5. Zmniejsz równoległość lub poczekaj i ponów próbę.

Rozwiązywanie problemów

Objaw	Prawdopodobna przyczyna	Naprawa
401 Nieautoryzowany	Pusty lub nieprawidłowy klucz; zmienna środowiskowa nie jest ustawiona w powłoce uruchamiającej OpenCode	Uruchom echo $KIMICODE_API_KEY w tym samym terminalu, a następnie zrestartuj OpenCode
404 Nie znaleziono	Base URL zawiera /chat/completions lub brakuje mu /v1	Użyj dokładnie https://api.kimicode.top/v1
Model nie znaleziony	Klucz modelu różni się od uncensored	Dopasuj klucz w models do identyfikatora zwracanego przez GET /v1/models
429 z concurrency	Zbyt wiele zapytań naraz	Zmniejsz liczbę równoległych wywołań narzędzi lub poczekaj na zakończenie strumieniowania
Zapytanie zbyt duże	Treść przekraczająca 8 MB lub historia bliska limitowi okna kontekstu	Rozpocznij nową sesję lub podsumuj historię

Dla dowolnych przypadków nieobjętych tymi informacjami, strona dokumentacji zawiera pełną referencję zapytania, a przewodnik integracji omawia ten sam endpoint z perspektywy innych klientów w stylu OpenAI.

Więcej przewodników

• Co oznacza kompatybilność z OpenAI dla API?
• Alternatywa dla Kimicode: Niefiltrowany API LLM w chmurze
• Niefiltrowane API LLM: Integracja i cennik kompatybilny z OpenAI