Unterstützt OpenCode eine benutzerdefinierte Basis-URL?

Ja. Du definierst einen benutzerdefinierten Anbieter in opencode.json mit einer Base URL, einem Schlüssel und einer Liste von Modellen. Prüfe die aktuellen OpenCode-Dokumente für die genauen Feldnamen, da sie sich zwischen Versionen ändern können.

Welche Modell-ID soll ich eingeben?

Gib uncensored exakt so ein, wie es geschrieben ist. Es muss mit dem Schlüssel im models-Block und der ID übereinstimmen, die von GET /v1/models zurückgegeben wird.

Gibt es eine kostenlose Möglichkeit, die Einrichtung zu testen?

Neue Nutzer können nach der Anmeldung mit einem Klick auf der API-Schlüssel-Seite $0,50 Testguthaben beanspruchen. Es gilt 7 Tage lang, erfordert keine Kreditkarte und ist auf einen pro Person begrenzt.

Warum erhalte ich 429-Fehler während eines Agentenlaufs?

Agenten senden oft mehrere Anfragen gleichzeitig. Der API-Schlüssel erlaubt 8 parallele Anfragen und 300 pro Minute, und der Versuchsschlüssel erlaubt 2 und 60. Reduziere die Parallelität oder versuche es nach der Retry-After-Verzögerung erneut.

OpenCode mit einer OpenAI-kompatiblen API: Einrichtung

Was du vor dem Start benötigst

OpenCode ist ein Open-Source-Coding-Agent, der in deinem Terminal läuft. Er kann mit vielen Modell-Anbietern kommunizieren und ermöglicht es dir, deinen eigenen Anbieter hinzuzufügen, wenn der Endpunkt dem OpenAI-Chat-Format folgt. Diese API tut dies, daher ist die Einrichtung eine Frage des Ausfüllens weniger Felder.

Sammle zunächst diese drei Werte:

Basis-URL: https://api.kimicode.top/v1
Modell-ID: uncensored
API-Schlüssel: Erstelle einen auf der API-Schlüssel-Seite. Neue Konten können dort mit einem Klick ein $0,50 kostenloses Testguthaben beanspruchen, das für die Tests unten mehr als ausreichend ist. Der Test-Schlüssel erlaubt 2 parallele Anfragen und 60 Anfragen pro Minute.

Bewahre den Schlüssel in einer Umgebungsvariable auf, anstatt ihn in Dateien einzufügen, die du in die Versionsverwaltung aufnimmst:

export KIMICODE_API_KEY="your-key-here"

Schritt 1: Teste den Endpunkt mit curl

Mache dies, bevor du ein Tool konfigurierst. Wenn curl funktioniert und OpenCode nicht, weißt du, dass das Problem in der Konfiguration liegt. Wenn curl fehlschlägt, behebst du den Schlüssel oder die URL einmal, nicht an zwei Stellen.

curl 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
  }'

Du solltest ein JSON-Objekt mit einem choices-Array und einem usage-Block erhalten. 401 bedeutet, der Schlüssel ist falsch oder fehlt das Bearer-Präfix. 404 bedeutet meist, dass die URL falsch eingegeben wurde oder bereits /chat/completions enthält.

Ein Coding-Agent streamt seine Antworten und ruft Tools auf, also prüfe auch diese beiden:

curl -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."}]
  }'

Du siehst eine Reihe von data:-Zeilen mit kleinen JSON-Deltas, endend mit den Nutzungszahlen und einem Finalmarker. Die -N-Flagge deaktiviert das Curl-Puffern, damit Chunks eintreffen, sobald sie ankommen.

Schritt 2: Füge einen benutzerdefinierten Anbieter zu OpenCode hinzu

OpenCode liest eine JSON-Konfigurationsdatei, opencode.json, aus deinem Projektordner oder aus seinem globalen Konfigurationsverzeichnis. Benutzerdefinierte OpenAI-kompatible Anbieter werden über das OpenAI-kompatible Paket des AI SDK deklariert, zusammen mit einer Basis-URL und einer Liste von Modellen. Das unten gezeigte Layout folgt der öffentlichen Dokumentation von OpenCode zum Zeitpunkt der Erstellung. Feldnamen können sich zwischen Releases ändern, daher vergleiche es bei Ablehnungen mit dem Anbieter-Abschnitt der aktuellen OpenCode-Dokumentation.

{
  "$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"
}

Der Schlüssel unter models ist die exakte Modell-ID, die an den Server gesendet wird, also muss sie uncensored lauten. Die letzte Zeile wählt den Anbieter und das Modell als Standard aus, geschrieben als Anbietername, ein Schrägstrich, dann Modell-ID.

Die {env:KIMICODE_API_KEY}-Form teilt OpenCode mit, die Variable aus der Shell zu lesen. Wenn deine Version Anmeldedaten über einen eigenen Login-Befehl verarbeitet, nutze diesen und lass den Schlüssel in der Datei weg. Gib keinen echten Schlüssel in das Repository ein.

Projekt-Konfiguration oder globale Konfiguration

Du kannst den Anbieterblock an zwei Orten aufbewahren. Eine Datei im Projektstamm gilt nur für dieses Repository, was für ein Team geeignet ist, das eine Einrichtung teilt. Eine Datei in deinem Benutzerkonfigurationsverzeichnis gilt überall, was für eine persönliche Standardeinstellung geeignet ist. Wenn beide existieren, fügt die Projektdatei der globalen Datei hinzu oder überschreibt sie.

Bevorzuge die globale Datei für die Anbieterdefinition und die Umgebungsvariable für den Schlüssel. Dann kann jedes Repository den Endpunkt verwenden, und nichts Geheimliches liegt neben deinem Quellcode. Wenn mehrere Personen an einem Projekt arbeiten, nimm nur den Anbieterblock ohne Schlüssel in die Versionsverwaltung auf und lass jede Person ihre eigene Variable setzen. Das macht es auch einfach, einen Schlüssel zu rotieren: Ändere die Variable, starte das Terminal neu, und die Konfigurationsdatei bleibt unberührt.

Schritt 3: Wähle das Modell und führe eine Aufgabe aus

Starte OpenCode in einem Projektordner und öffne den Modellwähler. Dein benutzerdefinierter Anbieter sollte in der Liste mit dem angezeigten Namen erscheinen, den du festgelegt hast. Wähle ihn aus und gib dem Agenten eine kleine, überprüfbare Aufgabe, wie das Erklären einer Funktion oder das Schreiben eines Unit-Tests für eine kurze Datei.

Starte klein aus zwei Gründen. Erstens kannst du sehen, ob Tool-Calls funktionieren: Wenn OpenCode das Modell bittet, eine Datei zu lesen oder zu bearbeiten, geschieht dies über die Function-Calling-Schnittstelle. Zweitens sendet ein Coding-Agent pro Anfrage viel Text, einschließlich Dateiinhalt und Verlauf, sodass eine lange Sitzung schnell Token verbraucht. Der nächste Abschnitt beleuchtet das numerisch.

Wenn das Modell nicht erscheint, prüfe, ob die Datei gültiges JSON ist, ob sie am richtigen Ort liegt und ob der Provider-Name mit dem Feld model übereinstimmt.

Tool-Calling und JSON-Modus direkt testen

OpenCode verlässt sich auf Tool-Calling, um Dateien zu lesen, Befehle auszuführen und Code zu bearbeiten, daher lohnt es sich, zu bestätigen, dass der Endpunkt eine Tool-Definition verarbeitet, bevor du den Agenten für einen Fehler verantwortlich machst. Diese Anfrage bietet ein Tool und stellt eine Frage, die es benötigt.

curl 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"
  }'

Eine gute Antwort enthält einen tool_calls-Eintrag, der read_file mit einem JSON-Argumentstring benennt. Der Agent führt das Tool aus und sendet das Ergebnis dann als Nachricht mit role auf tool zurück, und das Modell setzt dort fort. Wenn du nur Klartext siehst, versuche einen direkteren Prompt, da es zum Verhalten des Modells gehört, ob es sich entscheidet, ein Tool aufzurufen.

JSON-Modus ist ein separater Schalter. "response_format": {"type": "json_object"} fordert gültige JSON-Ausgabe an und hilft, wenn ein anderes Skript das zurückgegebene Ergebnis parsen muss. Erwähne JSON auch in deinem Prompt, damit das Modell die erwartete Struktur kennt.

Kontextgröße und was eine Sitzung kostet

Das Kontextfenster umfasst 100.000 Token (Prompt und Completion zusammen). limit.context auf 100000 zu setzen, informiert den Agenten über die tatsächliche Obergrenze, damit er den Verlauf kürzen oder zusammenfassen kann, bevor der Server eine Anfrage ablehnen muss. Eine Completion darf den verbleibenden Platz nutzen, und max_tokens ist optional.

Die Abrechnung beträgt $0,15 pro 1M Input-Token und $0,50 pro 1M Ausgabe-Token. Agenten sind eingabefokussiert, weil jeder Durchgang die Konversation erneut sendet. Hier ist ein durchgerechnetes Beispiel für eine moderate Sitzung:

40 Züge, jeder sendet etwa 30.000 Input-Token: 1.200.000 Input-Token, was 1,2 x $0,15 = $0,18 entspricht.
Jeder Durchlauf gibt etwa 800 Output-Token zurück: 32.000 Output-Token, was 0,032 x $0,50 = $0,016 entspricht.
Gesamt: $0,196, also etwa zwanzig Cent für die gesamte Sitzung.

Deine Zahlen werden abweichen. Lies die usage-Werte in Antworten, oder beobachte den X-Balance-USD-Header, der dein verbleibendes Guthaben bei jeder Antwort meldet. Guthaben ist Prepaid und verfällt nie, und fehlgeschlagene oder abgelehnte Anfragen werden nicht berechnet. Details stehen auf der Preisseite.

Ehrliche Erwartungen an einen Coding-Agenten

Dies ist ein allgemeines Textmodell, das darauf abgestimmt ist, ohne Inhaltsablehnungen für die rechtmäßige Nutzung durch Erwachsene zu antworten. Es ist kein speziell für Code gebautes Modell, und diese Seite macht keine Benchmark-Ansprüche. Ob es dein Repository zuverlässig bearbeitet, solltest du an deinen eigenen Aufgaben testen, mit aktivierter Versionskontrolle, bevor du ihm etwas Wichtiges anvertraust.

Es erledigt die Infrastruktur, die ein Agent benötigt: Function Calling mit gestreamten tool_calls, Tool-Ergebnisse, die als role: "tool"-Nachrichten zurückgesendet werden, und JSON-Modus über response_format. Es ist nur Text, ohne Bilder, daher funktionieren Funktionen, die Screenshots anhängen, nicht.

Zwei Limits sind für Agenten relevant. Ein voller Schlüssel erlaubt 8 parallele Anfragen und 300 Anfragen pro Minute. Sub-Agenten oder parallele Tool-Ausführungen, die viele Aufrufe gleichzeitig auslösen, können die Parallelitätsbegrenzung erreichen, und eine gestreamte Anfrage behält ihren Slot, bis der Stream endet. Wenn das passiert, erhältst du HTTP 429 mit dem Code concurrency. Der Code rate_limited bedeutet zu viele Anfragen pro Minute. Bei temporärer Überlastung siehst du vielleicht auch eine 429 mit Retry-After: 5. Reduziere die Parallelität oder warte und versuche es erneut.

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Lösung
401 Unauthorized	Leerer oder falscher Schlüssel; die Umgebungsvariable ist in der Shell, die OpenCode gestartet hat, nicht gesetzt	Führe `echo $KIMICODE_API_KEY` im selben Terminal aus und starte OpenCode neu.
404 Not Found	Basis-URL enthält `/chat/completions` oder fehlt `/v1`	Verwende exakt `https://api.kimicode.top/v1`
Modell nicht gefunden	Modellschlüssel weicht von `uncensored` ab	Vergleiche den Key in `models` mit der ID, die von `GET /v1/models` zurückgegeben wird.
429 mit `concurrency`	Zu viele Anfragen gleichzeitig	Reduziere parallele Tool-Aufrufe oder warte, bis die Streams abgeschlossen sind.
Anfrage zu groß	Body über 8 MB oder Verlauf nahe der Fensterbegrenzung	Starte eine neue Sitzung oder fasse den Verlauf zusammen.

Für alles, was hier nicht abgedeckt ist, findest du auf der Dokumentationsseite die vollständige Referenz zu den Anfragen, und der Integrationsleitfaden behandelt denselben Endpunkt aus der Perspektive anderer OpenAI-kompatibler Clients.