OpenCode Claude Agent: Einrichtung, Abo-Limits und Regeln

Nutze den Provider Claude Agent in OpenCode mit deiner eigenen lokalen Installation von Claude Code. Installiere beide Tools, führe claude auth login aus und wähle Claude Agent unter /connect. Wenn dein Team einen klar dokumentierten Authentifizierungsweg für Drittanbieterprodukte braucht, verwende einen API-Schlüssel.

Stand 2026-11-05 bietet OpenCode eine eigene Einrichtungsanleitung für Claude Agent. Der Provider übernimmt die aktive Authentifizierung von Claude Code. Seine Auswahl bedeutet daher nicht automatisch, dass Anfragen über dein Abo abgerechnet werden.

Was ändert Claude Agent?

Claude Agent nutzt die Oberfläche und Tool-Ausführung von OpenCode, während Claude Code die Kommunikation mit dem Modell übernimmt. OpenCode ruft dein installiertes claude über das Claude Agent SDK von Anthropic auf.

Der integrierte Provider erschien in OpenCode v2.2.3. Version v2.2.4 ergänzte die geführte Einrichtung in der Provider-Auswahl der App. Ein zusätzliches Abo-Plugin brauchst du nicht.

Laut Provider-Entwurf übernimmt OpenCode Dateioperationen, Shell-Befehle und Berechtigungen. Die integrierten Tools von Claude Code sind deaktiviert.

OpenCode übernimmt auch die Kontextkomprimierung und führt Subagenten aus, wie die aktuelle Claude-Agent-Anleitung erklärt. Die Integration lädt keine nativen Einstellungen, Hooks, MCP-Server, Skills oder Memory-Daten von Claude Code. Hooks sind Aktionen, die bei bestimmten Ereignissen ausgeführt werden.

Deine Anweisungen und Tools in OpenCode bestimmen deshalb, wie das Projekt bearbeitet wird. Prüfe sie, bevor du Dateiänderungen oder Shell-Befehle freigibst. Benötigst du native Hooks oder Agententeams von Claude Code, bleibe bei Claude Code, bis du einen gleichwertigen Ablauf eingerichtet hast.

Dieser Provider ist sinnvoll, wenn du die Oberfläche von OpenCode und den gewohnten Modellwechsel behalten möchtest. Er bildet nicht alle Funktionen von Claude Code nach.

Claude Agent installieren und verbinden

Installiere OpenCode V2 und Claude Code auf derselben Maschine wie den OpenCode-Server. In den Remote-Arbeitsbereichen von OpenCode ist dieser Provider nicht verfügbar.

Der Abo-Zugang setzt einen aktiven Tarif Pro, Max oder Ultra für Einzelpersonen voraus.

Die passenden Versionen installieren

Installiere OpenCode V2. Die Funktion setzt mindestens v2.2.3 voraus; die geführte Einrichtung in der App benötigt v2.2.4 oder neuer.

Diese Befehle sind für Bash unter macOS, Linux oder WSL vorgesehen. Sie folgen den Installationsanweisungen für OpenCode V2 und den Installationsanweisungen für Claude Code:

curl -fsSL https://opencode.ai/v2/install | bash
curl -fsSL https://claude.ai/install.sh | bash

Öffne ein neues Terminal und prüfe beide Versionen:

opencode --version
claude --version

Claude Code muss 2.1.248 oder neuer sein. Das verlangt die Versionsprüfung des Providers. Ältere native Installationen aktualisierst du mit claude update. Hast du Claude Code über einen Paketmanager installiert, verwende diesen auch für Updates.

Wenn du bereits V1 nutzt, lies zuerst die Anleitung zum Wechsel auf V2. Beide Versionen verwenden den Befehl opencode und dieselben Speicherorte für die Konfiguration.

Die Installation allein stellt noch keinen Modellzugang bereit. Falls du den Zugangsweg noch nicht gewählt hast, lies über Installation, Abo und API-Zugang für Claude Code.

Anmelden und das Konto prüfen

Nutze den Anmeldevorgang von Claude Code selbst. Wähle dein Konto mit Claude-Abo, wenn du dessen enthaltenes Kontingent verwenden möchtest:

claude auth login
claude auth status --text

Prüfe, ob der Status das gewünschte Konto und die richtige Authentifizierungsmethode nennt. Die CLI-Referenz unterscheidet diesen Weg von claude auth login --console. Dieser Befehl wählt die API-Abrechnung über Console.

Prüfe vor einem Test mit dem Abo die Zugangsdaten aus der Umgebung. Anthropic dokumentiert, dass API-Schlüssel aus Umgebungsvariablen Vorrang vor der Abo-Authentifizierung haben können. Wenn in deiner persönlichen Shell versehentlich noch ein alter Schlüssel gesetzt ist, entferne die Variable:

unset ANTHROPIC_API_KEY
claude auth status --text

Prüfe auch, ob ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL oder Einstellungen eines Cloud-Anbieters unbeabsichtigt gesetzt sind. Gleiche sie mit der Authentifizierungsreihenfolge von Anthropic ab. Die Anmeldung mit einem Abo hat nicht vor allen anderen Zugangsdaten Vorrang.

Prüfe in der OpenCode-Konfiguration unter providers.claude-agent.settings, ob apiKey, authToken oder baseURL gesetzt sind. Beachte auch Einstellungen auf Modellebene, die diese Werte überschreiben. Die Verbindungsimplementierung wendet diese Einstellungen nach den Umgebungsvariablen des Servers an.

Verbinden und eine echte Anfrage prüfen

Starte für die erste Prüfung einen separaten OpenCode-Server:

opencode --standalone

Der Standalone-Modus verwendet einen separaten Server. So gilt die Umgebung deiner aktuellen Shell, ohne von einem bereits laufenden gemeinsamen Dienst abzuhängen. Explizite Konfigurationswerte bleiben weiterhin vorrangig.

Führe in OpenCode /connect aus und wähle Claude Agent. Führe anschließend /models aus und wähle eines der von Claude Code gemeldeten Modelle. Modellreferenzen des Providers können Aliasse wie claude-agent/opus verwenden. Sie müssen nicht mit den Modell-IDs der direkten API übereinstimmen.

In der App bietet die geführte Einrichtung Installation, Anmeldung, Verbindungsprüfung und Hilfe bei Fehlern. Eine erfolgreiche Prüfung führt zur Modellauswahl. Diese Bedienelemente gehören zur App; im Terminal nutzt du die oben beschriebenen Befehle.

Verwende ein Repository mit einer README.md und sende diese Anfrage:

Read README.md and summarize the project in three sentences. Do not modify files or run shell commands.

Die Anfrage verlangt eine Zusammenfassung des Projekts in drei Sätzen, ohne Dateien zu ändern oder Shell-Befehle auszuführen. Prüfe, ob OpenCode einen Tool-Aufruf zum Lesen der Datei und eine passende Antwort zeigt. Damit prüfst du den Modellzugang und die Rückgabe des Tool-Ergebnisses.

Eine gefüllte Modellauswahl allein reicht nicht. Die Verbindungsprüfung sendet keinen Prompt an das Modell.

OPENCODE_CLAUDE_PATH setzen, wenn die Suche fehlschlägt

Gib dem Server den Pfad zur ausführbaren Claude-Code-Datei, wenn sein PATH die gewünschte Installation nicht findet. Prüfe zuerst, ob command -v claude in deinem Terminal den Pfad zur richtigen ausführbaren Datei ausgibt.

Für eine weitere Prüfung mit einem separaten Server:

export OPENCODE_CLAUDE_PATH="$(command -v claude)"
opencode --standalone

Für den gemeinsamen Hintergrunddienst verwendest du dessen verwaltete Umgebung:

opencode service set env OPENCODE_CLAUDE_PATH "$(command -v claude)"

Das Ändern der Dienstumgebung stoppt den laufenden Dienst. Der nächste Befehl, der den lokalen Server benötigt, startet ihn mit dem neuen Wert. Verbinde Claude Agent erneut und wiederhole die kleine Anfrage.

Die Anleitung zur Serverumgebung erklärt, warum eine Änderung allein im Terminal des Clients nicht immer genügt.

Welches Kontingent verwendet Claude Agent?

Plane das Budget anhand der aktiven Zugangsdaten von Claude Code. Bei Abo-Authentifizierung zählen Anfragen über Claude Agent zu deinem bestehenden Claude-Kontingent.

OpenCode dokumentiert, dass dieser Zugangsweg vom Abo abgedeckt wird. Anthropic bestätigt, dass Claude und Claude Code die Nutzungslimits des Tarifs teilen. Aus diesen beiden Regeln folgt, dass ein Wechsel der Oberfläche kein zweites Kontingent erzeugt.

Unterscheide diese drei Fälle:

Authentifizierung in Claude Code	Abrechnung der Nutzung
Claude-Abo	Im Tarif enthaltenes Kontingent mit dessen Limits und gegebenenfalls aktiviertem kostenpflichtigem Nutzungsguthaben
Anthropic-API-Konto oder unterstütztes Cloud-Konto	API-Abrechnung und Limits dieses Kontos
Benutzerdefiniertes Gateway	Abrechnungsregeln des Gateway-Kontos

Eine fehlende Kostenschätzung ist kein Beleg für kostenlose Nutzung. Die Kostenlogik des Providers lässt Schätzungen auch bei benutzerdefinierten Basis-URLs weg.

Prüfe Verbrauch und Zeitpunkte zum Zurücksetzen der Limits unter Claude Settings > Usage. Die native /usage-Ansicht von Claude Code steht innerhalb von OpenCode nicht zur Verfügung. Prüfe außerdem das kostenpflichtige Nutzungsguthaben. Wenn es aktiviert ist, können nach Verbrauch des enthaltenen Kontingents zusätzliche Gebühren entstehen.

Für die Wahl des Zugangswegs hilft der Vergleich von Claude-Abos und API-Abrechnung.

Was belegen die Aussagen zu den Nutzungsbedingungen?

Bewerte die Erlaubnis für die jeweilige Implementierung und Nutzungsform. Der Einsatz des offiziellen SDK erlaubt nicht automatisch jeder Drittanbieter-App den Zugriff auf Abo-Zugangsdaten.

Die drei Dokumente behandeln unterschiedliche Situationen:

Offizielle Quelle	Aussage	Bedeutung für diesen Aufbau
Ältere Provider-Seite von OpenCode	Sie warnt, dass Anthropic Plugins für Pro/Max-Abos verbietet. OpenCode liefert diese seit 1.3.0 nicht mehr mit.	Diese Warnung zu früheren Plugins beschreibt nicht die Implementierung des neuen V2-Providers.
Übersicht zum Anthropic Agent SDK	Drittanbieterentwickler benötigen eine vorherige Genehmigung, um Claude-Kontoanmeldungen oder dessen Anfragelimits in ihren Produkten anzubieten.	Der SDK-Aufruf allein belegt keine Erlaubnis.
Rechtliche Hinweise und Compliance für Claude Code	Sie beschränken die Vermittlung von Zugangsdaten durch Dritte. Nutzer dürfen sich mit ihrem eigenen Abo über die unveränderte Binärdatei von Claude Code anmelden.	Behalte die native Anmeldung bei. Übertrage diese Ausnahme nicht auf gemeinsam genutzte Zugangsdaten oder einen neuen kommerziellen Dienst.

Es gibt außerdem eine Aussage zu dieser konkreten Implementierung. Am 2026-10-30 erklärte PR-Autor Tarquinen, Anthropic habe die Erlaubnis erteilt. Er bezeichnete die Integration als konform mit den Nutzungsbedingungen.

Diese Aussage stammt von einem OpenCode-Mitwirkenden. Sie ist kein von Anthropic veröffentlichtes Dokument zum Umfang der Genehmigung.

Verwende für die persönliche Nutzung deine eigene Anmeldung in einer unveränderten Claude-Code-Installation. Exportiere keine Sitzungstokens in ein anderes Plugin. Hole für den Einsatz im Unternehmen oder die Integration in ein Produkt eine Bestätigung für diesen Aufbau ein. Alternativ nutze den dokumentierten Zugang per API-Schlüssel.

Eine erfolgreiche Authentifizierung bestätigt, dass eine Anfrage funktioniert. Sie klärt nicht die vertragliche Zulässigkeit jeder möglichen Bereitstellung.

Den tatsächlich auftretenden Fehler beheben

Prüfe die zum Symptom passende Ursache und wiederhole anschließend die kleine Anfrage zum Lesen der Datei.

Symptom	Prüfung und nächster Schritt
`Claude Code is not installed`	Installiere Claude Code auf der Maschine des OpenCode-Servers oder setze dort `OPENCODE_CLAUDE_PATH`. Verbinde den Provider erneut.
`Claude Code is not logged in`	Führe `claude auth login` auf dieser Maschine unter demselben Benutzer aus. Prüfe den Status und verbinde den Provider erneut.
Die Meldung enthält `2.1.248 or later is required`	Aktualisiere Claude Code und prüfe vor dem nächsten Versuch die Version der ausführbaren Datei.
Verbunden, aber keine Modelle oder keine funktionierende Antwort	Prüfe die ausführbare Datei und die Anmeldung auf dem Server. Verbinde erneut; erkannte Modelle belegen noch keine funktionierenden Anfragen.

Die dokumentierten Verbindungsfehler behandeln eine fehlende Installation und Anmeldung. Erreicht eine Anfrage stattdessen ein Tariflimit, prüfe die Nutzungsseite des Kontos. Erneutes Verbinden füllt das Kontingent nicht auf.

Wann ist ein API-Schlüssel sinnvoll?

Wähle einen API-Schlüssel, wenn du getrennte Abrechnung, einen Server ohne lokales Claude Code oder die dokumentierte Authentifizierung für ein Drittanbieterprodukt benötigst. Halte Budget und Limits dieses Zugangs vom Claude-Abo getrennt.

Direkter Zugang zur Anthropic-API

Erstelle deinen eigenen Schlüssel in der Claude Console. Wähle in OpenCode über /connect den Provider Anthropic und die Authentifizierung per API-Schlüssel.

Der entsprechende Authentifizierungsbefehl von V2 fragt den geheimen Schlüssel interaktiv ab:

opencode auth login anthropic --method key
opencode run --standalone --model anthropic/claude-sonnet-5-5 "Reply with only: OK"

Prüfe, ob du eine Antwort mit OK erhältst und die Nutzung dem gewünschten API-Konto zugeordnet wird. Falls Konto oder Modell falsch gewählt sind, korrigiere die Auswahl über /connect oder /models, bevor du erneut testest.

Zugang über eine OpenAI-kompatible API

Stand 2026-11-05 führt BetterToken ebenfalls claude-sonnet-5-5 und claude-opus-5-5 im Katalog. Die dokumentierte OpenCode-Integration nutzt eine OpenAI-kompatible API und deinen eigenen BetterToken-Schlüssel. Dieser API-Zugang wird separat abgerechnet.

Erstelle einen Schlüssel in deiner Konsole. Ergänze für eine neue native V2-Konfiguration die opencode.jsonc deines Projekts um diesen Provider:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "bettertoken": {
      "name": "BetterToken",
      "env": ["BETTERTOKEN_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "claude-sonnet-5-5": {
          "name": "Claude Sonnet 5.5"
        }
      }
    }
  }
}

Das Beispiel folgt dem nativen V2-Format für benutzerdefinierte Provider. Es verwendet providers, package und settings. Mische innerhalb dieses Provider-Eintrags keine Feldnamen aus V1 ein.

Gib den Schlüssel ein, ohne ihn anzuzeigen, und starte die Prüfung im selben Bash-Terminal:

read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY
opencode run --standalone --model bettertoken/claude-sonnet-5-5 "Reply with only: OK"

Erwartet wird eine normale Antwort mit OK. Prüfe anschließend die Anfrage und die Gebühr in der Konsole. Hast du bereits ein BetterToken-Konto in OpenCode gespeichert, kontrolliere das aktive Konto: Gespeicherte Konten haben Vorrang vor Verbindungen über Umgebungsvariablen.

Sieh dir vor einer größeren Aufgabe die aktuellen Preise an. Dieser API-Zugang enthält kein Claude-Abo. Er erteilt auch keine Erlaubnis für andere Integrationen, die eine Abo-Anmeldung nutzen.