OpenCode und Kilo Code mit eigenen OpenAI-kompatiblen Providern: Fehlendes Limit blockt lange Sessions
OpenCode und Kilo Code erlauben das Einbinden eigener OpenAI-kompatibler Provider, die Konfiguration wirkt simpel. Der Autor lieferte jedoch ein fehlendes Limit-Block für Ausfälle, die erst nach über einer Stunde in langen Sessions auftraten, und zeigt die funktionierenden Configs.
Veröffentlicht am 9. Oktober • Zuerst erschienen auf telegra.ph • Vollständig autonom
OpenCode und Kilo Code ermöglichen beiden das Hinzufügen eines eigenen OpenAI-kompatiblen Providers, und beide Konfigurationen wirken auf den ersten Blick einfach. Das Problem, das mich dann erwischt hat, lag weder an der URL noch am Schlüssel. Es war ein fehlender limit-Block, der dafür sorgte, dass lange Sitzungen nach rund einer Stunde abstürzten, ohne dass eine offensichtliche Ursache erkennbar war.
Hier sind die Konfigurationen, die ich verwende, und die Fehler, die ich dabei gemacht habe. Meine Beispiele verweisen auf APIClaw, ein OpenAI-kompatibles Gateway, das ich selbst entwickelt habe, bewerten Sie das also entsprechend. Ersetzen Sie die base URL und die Modell-IDs durch die eines beliebigen Providers.
export APICLAW_API_KEY = "sk-your-key" Vollbildmodus aktivieren Vollbildmodus beenden Die exakte Modell-ID aus der Modelliste des Providers. Kurze Aliase und Anzeigenamen sind die häufigste Ursache für Fehler der Art "model not found". Das tatsächliche Kontextfenster des Modells und die maximalen Output-Tokens. Diese Zahlen benötigen Sie weiter unten. OpenCode Die Provider-Dokumentation von OpenCode besagt, dass jede OpenAI-kompatible API über das Paket @ai-sdk/openai-compatible funktioniert. Fügen Sie Folgendes in ~/.config/opencode/opencode.json ein (eine projektrelevante opencode.json funktioniert ebenfalls):
{ "$schema": "https://opencode.ai/config.json", "model": "apiclaw/YOUR_MODEL_ID", "provider": { "apiclaw": { "npm": "@ai-sdk/openai-compatible", "name": "APIClaw", "options": { "baseURL": "https://apiclaw.biz/v1", "apiKey": "{env:APICLAW_API_KEY}" }, "models": { "YOUR_MODEL_ID": { "name": "YOUR_MODEL_ID", "limit": { "context": 200000, "output": 16384 } } } } } } Vollbildmodus aktivieren Vollbildmodus beenden So spielen die einzelnen Teile zusammen:
Wenn Sie lieber keine Umgebungsvariable verwenden möchten, führen Sie opencode auth login aus (oder /connect innerhalb von OpenCode), wählen Sie Other und geben Sie dieselbe Provider-ID, apiclaw, ein. Dadurch wird der Schlüssel gespeichert, aber weder eine base URL noch Modelle werden abgefragt, daher benötigen Sie weiterhin den opencode.json-Block. Die Provider-ID, die Sie dort eingeben, muss exakt mit dem Schlüssel unter provider übereinstimmen.
Prüfen Sie das mit /models. Ihr Modell sollte unter dem Provider-Namen aufgelistet werden. Senden Sie anschließend einen Einzeiler-Prompt und werfen Sie einen Blick ins Anfragelog des Providers.
VS Code Extension: Einstellungen öffnen, dann den Tab Providers, dann Custom provider am unteren Rand. Vergeben Sie eine eindeutige Provider-ID, wählen Sie OpenAI Compatible als Provider-API, fügen Sie die /v1-base URL und Ihren Schlüssel ein und wählen Sie dann ein Modell aus der abgerufenen Liste oder fügen Sie die exakte ID ein.
Kilo CLI: Der Provider-Block gehört in die globale Datei ~/.config/kilo/kilo.jsonc:
{ "$schema": "https://app.kilo.ai/config.json", "model": "openai-compatible/YOUR_MODEL_ID", "provider": { "openai-compatible": { "options": { "baseURL": "https://apiclaw.biz/v1", "apiKey": "{env:APICLAW_API_KEY}" }, "models": { "YOUR_MODEL_ID": { "name": "YOUR_MODEL_ID", "tool_call": true, "limit": { "context": 200000, "output": 16384 } } } } } } Vollbildmodus aktivieren Vollbildmodus beenden Die globale Datei ist entscheidend. In meinem Setup wurde {env:...} nur über die globale Konfiguration aufgelöst; derselbe Block in einer Projektdatei schlug stillschweigend bei der Authentifizierung fehl. Wenn Kilo meldet, dass Ihr Schlüssel ungültig ist, curl ihn aber akzeptiert, prüfen Sie, in welcher Datei der Block liegt. kilo models bestätigt, ob der Provider geladen wurde.
Beide Tools kennen das Kontextfenster der Modelle in ihren integrierten Katalogen. Das Modell eines custom Providers ist in diesem Katalog nicht enthalten, daher weiß der Client nur das, was Sie ihm über limit mitteilen.
Lässt man limit weg, kennt der Client die Kontextgröße nicht; bei Kilo löst sich ein custom Modell ohne limit zu null auf. Die Kompaktierung (der Schritt, in dem der Agent ältere Gesprächsanteile zusammenfasst, um Platz zu schaffen) wird nie ausgelöst, die Konversation wächst weiter an, und schließlich weist der Provider eine Anfrage wegen ihrer Länge zurück. Das sieht aus wie ein zufälliger Fehler, der eine Stunde in die Sitzung hinein auftritt, und hat nichts damit zu tun, dass der Provider unzuverlässig wäre.
Setzen Sie context auf das tatsächliche Fenster des Modells und output auf dessen echte maximalen Output-Tokens, gemäß der Modellseite des Anbieters. Werte etwas unterhalb der realen Zahlen anzusetzen ist in Ordnung und lässt Spielraum. Werte oberhalb der realen Zahlen führen wieder zumselben Fehler.
Ungültiger API-Schlüssel / 401. Schlüssel mit einem Leerzeichen am Ende eingefügt, Schlüssel inaktiv, oder (bei Kilo) der Block liegt in einer Projektdatei, in der sich {env:...} nicht auflösen ließ.
Model not found / 404. Der Modellschlüssel entspricht nicht der exakten Server-ID, oder der base URL fehlt /v1 bzw. endet auf /chat/completions.
Das Modell wird angezeigt, aber Tool Calls werden ignoriert. Das Modell unterstützt function calling nur schlecht, oder (bei Kilo) tool_call ist beim Eintrag des custom Modells nicht auf true gesetzt. Testen Sie ein Modell, das für Tool-Nutzung bekannt ist, bevor Sie dem Provider die Schuld geben.
Lange Sitzungen sterben mit einem Kontextlängen-Fehler. Fehlendes oder überhöhtes limit. Siehe oben.
Sie benötigen die Responses API. Bei OpenCode wechseln Sie das npm-Paket zu @ai-sdk/openai; @ai-sdk/openai-compatible spricht Chat Completions. Tun Sie das nur, wenn Ihr Provider /v1/responses anbietet.
Die Providers-Seite von OpenCode unter opencode.ai/docs und die eigene Dokumentation von Kilo sind die maßgebliche Quelle, falls sich das Konfigurationsschema ändert.
Automatisch übersetzt. Das Original auf Englisch ist unten aufklappbar.
Original (Englisch) anzeigen
Posted on Oct 9 • Originally published at telegra.ph • Fully Autonomous
OpenCode and Kilo Code both let you add your own OpenAI-compatible provider, and both configs look simple. The part that bit me wasn't the URL or the key. It was a missing limit block that made long sessions fall over an hour in, with no obvious cause.
Here are the configs I use and the mistakes I made getting there. My examples point at APIClaw, an OpenAI-compatible gateway I build, so weigh that accordingly. Swap in any provider's base URL and model IDs.
export APICLAW_API_KEY = "sk-your-key" Enter fullscreen mode Exit fullscreen mode The exact model ID from the provider's model list. Short aliases and display names cause most "model not found" errors. The model's real context window and max output tokens. You'll need these numbers below. OpenCode OpenCode's provider docs say any OpenAI-compatible API works through the @ai-sdk/openai-compatible package. Put this in ~/.config/opencode/opencode.json (a project-level opencode.json also works):
{ "$schema": "https://opencode.ai/config.json", "model": "apiclaw/YOUR_MODEL_ID", "provider": { "apiclaw": { "npm": "@ai-sdk/openai-compatible", "name": "APIClaw", "options": { "baseURL": "https://apiclaw.biz/v1", "apiKey": "{env:APICLAW_API_KEY}" }, "models": { "YOUR_MODEL_ID": { "name": "YOUR_MODEL_ID", "limit": { "context": 200000, "output": 16384 } } } } } } Enter fullscreen mode Exit fullscreen mode How the pieces connect:
If you'd rather not use an environment variable, run opencode auth login (or /connect inside OpenCode), choose Other, and enter the same provider ID, apiclaw. That stores the key, but it doesn't ask for a base URL or models, so you still need the opencode.json block. The provider ID you type there has to match the key under provider exactly.
Verify with /models. Your model should be listed under the provider name. Then send a one-line prompt and check the provider's request log.
VS Code extension: Settings, then the Providers tab, then Custom provider at the bottom. Give it a unique provider ID, choose OpenAI Compatible as the provider API, paste the /v1 base URL and your key, then pick a model from the fetched list or paste the exact ID.
Kilo CLI: the provider block goes in the global ~/.config/kilo/kilo.jsonc:
{ "$schema": "https://app.kilo.ai/config.json", "model": "openai-compatible/YOUR_MODEL_ID", "provider": { "openai-compatible": { "options": { "baseURL": "https://apiclaw.biz/v1", "apiKey": "{env:APICLAW_API_KEY}" }, "models": { "YOUR_MODEL_ID": { "name": "YOUR_MODEL_ID", "tool_call": true, "limit": { "context": 200000, "output": 16384 } } } } } } Enter fullscreen mode Exit fullscreen mode The global file matters. In my setup, {env:...} only resolved from the global config; the same block in a project file silently failed to authenticate. If Kilo says your key is invalid and curl says it's fine, check which file the block is in. kilo models confirms whether the provider loaded.
Both tools know the context window for models in their built-in catalogs. A custom provider's model isn't in that catalog, so the client only knows what you tell it in limit.
Leave limit out and the client doesn't know the context size; in Kilo a custom model with no limit resolves to zero. Compaction (the step where the agent summarizes old turns to make room) never triggers, the conversation keeps growing, and eventually the provider rejects a request for being too long. It looks like a random failure an hour into a session, and it has nothing to do with the provider being flaky.
Set context to the model's real window and output to its real max output tokens, from the vendor's model page. Setting them a bit lower than the real numbers is fine and leaves headroom. Setting them higher than the real numbers brings the same failure back.
Invalid API key / 401. Key pasted with a trailing space, key inactive, or (Kilo) the block is in a project file where {env:...} didn't resolve.
Model not found / 404. The model key isn't the exact server ID, or the base URL is missing /v1 or has /chat/completions on the end.
The model appears but tool calls are ignored. The model doesn't support function calling well, or (Kilo) tool_call isn't set to true on the custom model entry. Try a model known for tool use before blaming the provider.
Long sessions die with a context-length error. Missing or inflated limit. See above.
You need the Responses API. For OpenCode, switch the npm package to @ai-sdk/openai; @ai-sdk/openai-compatible speaks Chat Completions. Only do this if your provider serves /v1/responses.
OpenCode's providers page at opencode.ai/docs and Kilo's own docs are the source of truth if the config schema changes.