Russische KI-Anbieter für OpenCode

OpenCode ist ein offener Programmieragent, der direkt im Terminal arbeitet: Projektdateien liest, Code bearbeitet, Befehle und Tests ausführt, das Repository durchsucht und mit Git arbeitet. Seine Stärke liegt darin, dass es nicht an einen Modellanbieter gebunden ist und Dutzende Anbieter verbinden kann.

GigaChat ist ein großes Sprachmodell von Sber. Es ist nicht in der Liste der OpenCode-Anbieter enthalten, aber das ist kein Problem: OpenCode verbindet beliebige Anbieter über Vercel AI SDK-Pakete. Für GigaChat gibt es ein Paket gigachat-ai-sdk-provider, das sich um die OAuth-Autorisierung und die Aktualisierung des Zugriffstokens kümmert. Eine weitere Nuance sind die Zertifikate des Ministeriums für digitale Entwicklung: Ohne sie vertraut Node den GigaChat-Servern nicht und Anfragen schlagen mit einem Fehler bei der Zertifikatsüberprüfung fehl.

In diesem Beitrag beschreibe ich, wie man einen Schlüssel erhält, Zertifikate installiert und GigaChat mit OpenCode verbindet.

Was Sie brauchen

Zum Arbeiten benötigen Sie drei Dinge:

• OpenCode installiert. Wenn der Agent noch nicht installiert ist, habe ich den Installationsvorgang in einem separaten Hinweis zu OpenCode und DeepSeek besprochen.
• GigaChat-Konto. Registrierung in GigaChat Studio und Autorisierungsschlüssel – Sie benötigen eine Sber-ID, um sich anzumelden.
• Modernes Terminal. WezTerm, Alacritty, Ghostty, Kitty oder jedes andere reicht aus.

GigaChat-Autorisierungsschlüssel

Der Schlüssel wird in Ihrem persönlichen GigaChat Studio-Konto erstellt. Gehen Sie zu Developers.sber.ru/studio, melden Sie sich an und erstellen Sie ein Projekt im Abschnitt GigaChat API. In den Projekteinstellungen gibt es einen Block mit Berechtigungsdaten: Die Zeile, die von dort kopiert wird, ist ein vorgefertigter Berechtigungsschlüssel in base64. Dies wird in die Umgebungsvariable eingefügt und nicht das Client-Geheimnis-Paar separat.

Zusammen mit dem Schlüssel wird scope angegeben – der Zugriffsbereich:

• GIGACHAT_API_PERS – für Einzelpersonen.
• GIGACHAT_API_B2B – für Einzelunternehmer und juristische Personen.
• GIGACHAT_API_CORP – Unternehmenszugriff.

Der angezeigte Schlüsselwert sollte sofort gespeichert werden, er wird später nicht mehr angezeigt und muss ggf. neu vergeben werden.

Es ist wichtig zu verstehen, was diese Zeile ist. Der Autorisierungsschlüssel ist kein separates Geheimnis, sondern ein Paar von client_id:client_secret, das bereits in base64 codiert ist. Die gigachat-js-Bibliothek ersetzt diesen Header in der OAuth-Anfrage:

Authorization: Basic ваш_ключ_авторизации

Als Reaktion darauf verfügt ein JWE-Zugriffstoken über eine Lebensdauer von etwa einer halben Stunde und wird dann von der Bibliothek automatisch aktualisiert. Das Paket selbst prüft, ob der Wert Base64 ähnelt, und warnt, wenn die Variable versehentlich ein „rohes“ Client-Geheimnis enthält. Daher ist es notwendig, den vorgefertigten Base64-String vom Konto in die Konfigurations- und Umgebungsvariable zu übertragen und nicht das Paar client_id und client_secret separat.

Zertifikate des Ministeriums für digitale Entwicklung

Die GigaChat-API verwendet Zertifikate des NCA Ministry of Digital Development. Der standardmäßige vertrauenswürdige Stammspeicher verfügt nicht über sie. Wenn Sie also versuchen, ein Zugriffstoken abzurufen, schlägt die Anforderung mit einem Fehler wie dem folgenden fehl:

self-signed certificate in certificate chain

Zertifikate können auf Betriebssystemebene installiert werden – dann werden sie vom Browser und den Systemdienstprogrammen als vertrauenswürdig eingestuft. Aber OpenCode läuft auf Node und Bun, daher ist es sicherer und einfacher, die Zertifikatsdatei direkt in der Variablen NODE_EXTRA_CA_CERTS anzugeben. Laden Sie die Stamm- und Ausstellerzertifikate herunter und fügen Sie sie in einer PEM-Datei zusammen:

curl -s https://gu-st.ru/content/lending/russian_trusted_root_ca_pem.crt -o russian_trusted_root_ca_pem.crt
curl -s https://gu-st.ru/content/lending/russian_trusted_sub_ca_pem.crt -o russian_trusted_sub_ca_pem.crt
cat russian_trusted_root_ca_pem.crt russian_trusted_sub_ca_pem.crt > russian_trusted_ca_bundle.pem

Die Datei kann an einem geeigneten Ort abgelegt werden und ihr vollständiger Pfad kann beim Starten des Agenten angegeben werden.

Hier gibt es einen Haken. Heruntergeladene Dateien verwenden CRLF-Zeilenumbrüche und das Stammzertifikat verfügt über keinen nachgestellten Zeilenvorschub. Daher verkettet eine normale Katze das Ende des ersten Zertifikats und den Anfang des zweiten in einer Zeile:

-----END CERTIFICATE----------BEGIN CERTIFICATE-----

LibreSSL – und das System OpenSSL unter macOS ist, ich möchte Sie daran erinnern, genau LibreSSL – akzeptiert eine solche Datei nicht und antwortet mit einem Fehler:

PEM routines:CRYPTO_internal:bad end line

Das bedeutet, dass eine Katze allein nicht ausreicht. Jedes Zertifikat muss zuerst über openssl ausgeführt werden: Es wird in kanonisches PEM mit LF-Zeilenvorschüben und einem letzten Zeilenvorschub umcodiert und erst dann zusammengeführt:

openssl x509 -in russian_trusted_root_ca_pem.crt -out russian_trusted_root_ca.pem
openssl x509 -in russian_trusted_sub_ca_pem.crt -out russian_trusted_sub_ca.pem
cat russian_trusted_root_ca.pem russian_trusted_sub_ca.pem > russian_trusted_ca_bundle.pem

Sie können überprüfen, ob die Datei wie folgt gelesen wird:

openssl x509 -in russian_trusted_ca_bundle.pem -noout -subject

Wenn die Zertifikate aus einer anderen Quelle stammen und im DER- oder PKCS#7-Format vorliegen, können sie auch in PEM umcodiert werden:

openssl x509 -in cert.crt -inform DER -outform PEM -out cert.pem
openssl pkcs7 -print_certs -in bundle.p7b -out cert.pem

Mit OpenCode verbinden

Der Anbieter ist in der Konfigurationsdatei opencode.jsonc beschrieben. OpenCode selbst lädt das im npm-Feld angegebene npm-Paket herunter, verbindet es, findet darin die createGigaChat-Factory und übergibt ihr die Optionen. Es reicht aus, die Modelle anhand ihrer Kennungen aus der API aufzulisten.

Die Datei kann an zwei Orten abgelegt werden:

• Global – ~/.config/opencode/opencode.jsonc. Die Einstellungen gelten für alle Benutzerprojekte.
• Im Projekt – opencode.jsonc im Projektstamm. Diese Konfiguration hat eine höhere Priorität und kann sicher an git übergeben werden.

Beide Dateien verwenden das gleiche Schema und werden kombiniert: Die Projektdatei überlappt die globale Datei nur bei passenden Schlüsseln, die restlichen Einstellungen werden gespeichert. Die Erweiterung .jsonc wird ebenfalls unterstützt. Wenn GigaChat nur für einige Repositories benötigt wird, ist es bequemer, den Anbieter in der Projektkonfiguration zu belassen, statt in der globalen.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gigachat": {
      "npm": "gigachat-ai-sdk-provider",
      "name": "GigaChat",
      "models": {
        "GigaChat-2-Max": { "name": "GigaChat 2 Max" },
        "GigaChat-2-Pro": { "name": "GigaChat 2 Pro" },
        "GigaChat-2": { "name": "GigaChat 2 Lite" },
        "GigaChat": { "name": "GigaChat" }
      }
    }
  }
}

Verfügbare Modelle mit persönlichem Schlüssel finden Sie hier. Wenn Sie ein Projekt für einen Einzelunternehmer oder eine juristische Person mit Zugriff auf GigaChat 3 haben, fügen Sie die erforderlichen Identifikatoren aus der Models-Methode zum Models-Block hinzu.

Bequemer ist es, den Schlüssel selbst nicht in einer Datei zu speichern, sondern ihn an eine Umgebungsvariable zu übergeben: Das Paket gigachat-js liest ihn automatisch. Der Bereichswert kann auch auf eine Variable festgelegt werden. Jetzt müssen nur noch der Pfad zu den Zertifikaten festgelegt und der Agent gestartet werden:

export GIGACHAT_CREDENTIALS=ваш_ключ_авторизации
export GIGACHAT_SCOPE=GIGACHAT_API_PERS
export NODE_EXTRA_CA_CERTS=/путь/к/russian_trusted_ca_bundle.pem
opencode

Diese Option ist auch deshalb gut, weil das Geheimnis nicht im lokalen auth.json-Speicher landet: Es lebt nur in der Umgebung des Prozesses. Dies ist praktischer für CI- und einmalige Starts.

Modelle

Die Menge der verfügbaren Modelle hängt vom Scope-Schlüssel ab. Der persönliche Schlüssel (GIGACHAT_API_PERS) steht der GigaChat- und GigaChat 2-Familie zur Verfügung:

• GigaChat – Basismodell.
• GigaChat-2 – ein schnelles und leichtes Modell für alltägliche Aufgaben, angezeigt als Lite in der Benutzeroberfläche.
• GigaChat-2-Pro – ein verbessertes Modell für ressourcenintensive Aufgaben.
• GigaChat-2-Max ist das leistungsstärkste, das mit einem persönlichen Schlüssel verfügbar ist.

Die GigaChat 3-Familie (GigaChat-3-Ultra, GigaChat-3-Pro, offene Modelle wie GigaChat3.5-432B-A28B-Reasoning) ist im Konsolenkatalog sichtbar, steht aber nicht für den persönlichen Schlüssel zur Verfügung: Sie erfordert ein einzelnes Unternehmerprojekt oder eine juristische Person mit dem Geltungsbereich GIGACHAT_API_B2B oder GIGACHAT_API_CORP und einen passenden Tarif. Auf einen persönlichen Schlüssel antwortet ein solches Modell mit einem Fehler:

{"status":404,"message":"No such model"}

Sie können überprüfen, was Ihr Schlüssel tatsächlich ausgibt, indem Sie die Liste der Modelle abfragen:

curl -H "Authorization: Bearer <токен_доступа>" https://gigachat.devices.sberbank.ru/api/v1/models

Noch zwei Punkte. Modell-IDs in der API stimmen nicht mit den angezeigten Namen überein – das Light-Modell heißt GigaChat-2, nicht GigaChat-2-Lite. Und der Katalog in der Konsole zeigt nicht das Gleiche an, was für Ihren Schlüssel verfügbar ist. Daher sollten Sie sich auf die Reaktion der Modellmethode und nicht auf die Preisliste konzentrieren.

In der Schnittstelle wird die Liste der Modelle mit dem Befehl geöffnet:

/models

Für Routinearbeiten im Repository – Navigieren durch Dateien, kleinere Änderungen, Ausführen von Tests – reicht GigaChat-2 vollkommen aus. Bei komplexen Aufgaben und Designs ist es sinnvoll, auf Pro oder Max umzusteigen.

Erster Start im Projekt

Gehen Sie in das Projektverzeichnis und starten Sie den Agenten:

cd ваш_проект
opencode

Der erste Schritt besteht darin, den Agenten zu initialisieren:

/init

OpenCode analysiert die Projektstruktur und erstellt eine Datei AGENTS.md – Anweisungen für den Agenten. Es lohnt sich, diese Datei an Git zu übergeben: Sie hilft dem Agenten, die im Projekt übernommenen Konventionen und Muster zu verstehen.

Alternative: lokaler Proxy

Wenn Sie den NPM-Anbieter aus irgendeinem Grund nicht verwenden möchten, liefert ein lokaler Proxy das gleiche Ergebnis. Das GigaChat-Team verfügt über einen offiziellen gpt2giga – FastAPI-Dienst, der Anfragen im OpenAI-, Anthropic- und Gemini-Format in die GigaChat-API übersetzt und das Zugriffstoken selbst aktualisiert. Es wird lokal auf Port 8090 ausgelöst, woraufhin ein regulärer OpenAI-kompatibler Anbieter in OpenCode über das Paket @ai-sdk/openai-kompatible mit der Basisadresse http://localhost:8090/v1 konfiguriert wird. Der Nachteil dieses Weges besteht darin, dass Sie neben OpenCode auch einen laufenden Python-Dienst aufrechterhalten müssen.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gigachat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "GigaChat (proxy)",
      "options": {
        "baseURL": "http://localhost:8090/v1"
      },
      "models": {
        "GigaChat-2-Max": { "name": "GigaChat 2 Max" }
      }
    }
  }
}

DeepSeek und andere Modelle über Cloud.ru

Die GigaChat-API selbst verfügt nicht über DeepSeek-Modelle: Es gibt nur die GigaChat-Familie und Modelle für Einbettungen. Wenn Sie DeepSeek in OpenCode benötigen, aber über ein russisches Cloud-Gateway, ist der Foundation Models-Dienst von Cloud.ru geeignet. Es liefert Modelle mithilfe des OpenAI-kompatiblen Protokolls und ist daher über das Standardpaket @ai-sdk/openai-kompatible verbunden.

Im Cloud.ru Foundation Models-Katalog gibt es beispielsweise folgende Modelle:

deepseek-ai/DeepSeek-V4.1-Flash
deepseek-ai/DeepSeek-V4-Flash
deepseek-ai/DeepSeek-V4-Pro

Der Schlüssel wird in der Cloud.ru-Konsole ausgegeben: Abschnitt Benutzer, Registerkarte Dienstkonten. Wir erstellen ein Dienstkonto auf Projektebene und erstellen dann in seinen Anmeldeinformationen einen API-Schlüssel mit dem Foundation Models-Dienst. Das Schlüsselgeheimnis wird einmalig angezeigt und wir speichern es.

Die Anbieterkonfiguration in opencode.json sieht folgendermaßen aus:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cloudru": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Cloud.ru Foundation Models",
      "options": {
        "baseURL": "https://foundation-models.api.cloud.ru/v1",
        "apiKey": "{env:CLOUDRU_API_KEY}"
      },
      "models": {
        "deepseek-ai/DeepSeek-V4.1-Flash": { "name": "DeepSeek V4.1 Flash", "limit": { "context": 1048576, "output": 1048576 } },
        "deepseek-ai/DeepSeek-V4-Flash": { "name": "DeepSeek V4 Flash", "limit": { "context": 1048576, "output": 1048576 } },
        "deepseek-ai/DeepSeek-V4-Pro": { "name": "DeepSeek V4 Pro", "limit": { "context": 1048576, "output": 1048576 } }
      }
    }
  }
}

Wir übergeben den Schlüssel an die Umgebungsvariable:

export CLOUDRU_API_KEY=ваш_ключ_cloudru
opencode

Zertifikate des Ministeriums für digitale Entwicklung sind hier nicht erforderlich: Die Domain api.cloud.ru verfügt im Gegensatz zu GigaChat über reguläres TLS. Es lohnt sich jedoch, die Ausgewogenheit des Projekts zu überwachen. Wenn das Konto Null ist, ist die Autorisierung erfolgreich und Anfragen werden mit der Abrechnungsantwort verworfen:

{"message":"Not enough money"}

Dies ist kein Konfigurationsfehler, sondern ein Signal, dass Sie das Projekt in der Cloud.ru-Konsole aktualisieren müssen.

Worauf Sie achten sollten

Ein paar praktische Punkte, die bei der Ersteinrichtung am häufigsten im Weg stehen:

• Fehler bei der Zertifikatsüberprüfung. Die Meldung über ein selbstsigniertes Zertifikat in der Kette bedeutet, dass die Variable NODE_EXTRA_CA_CERTS nicht erfasst wurde. Überprüfen Sie den Pfad zur Datei, ob der Agent in derselben Umgebung ausgeführt wird, und die Datei selbst: Wenn beim Zusammenführen zweier Zertifikate mit cat deren Enden in derselben Zeile landen, gibt LibreSSL eine fehlerhafte Endzeile zurück und das Bundle muss über openSL neu erstellt werden, wie im Abschnitt über Zertifikate beschrieben.
• Fehler 401. In der Regel handelt es sich hierbei um einen falschen Autorisierungsschlüssel oder einen nicht übereinstimmenden Bereich – für eine Einzelperson benötigen Sie GIGACHAT_API_PERS.
• Fehler 404 mit dem Text „Kein solches Modell“. Hierbei handelt es sich nicht um einen Verbindungsfehler, sondern um einen fehlenden Zugriff auf ein bestimmtes Modell. Entfernen Sie es aus der Konfiguration oder ersetzen Sie es durch ein verfügbares. In einer Nachricht wie GigaChat 404: Unbekannter Fehler ist dieselbe GigaChat-Antwort schuld – der Anbieter konnte den Fehlertext einfach nicht analysieren.
• Kosten. OpenCode erfordert kein Abonnement: Sie zahlen GigaChat direkt, wenn Sie Token ausgeben, sodass der Preis für lange Sitzungen vorhersehbar ist.
• Modellqualität. Bei komplexen Architekturaufgaben unterscheiden sich Modelle verschiedener Klassen, daher ist es für das Design sinnvoll, ein stärkeres Modell zu nehmen und die Routine einem schnelleren zu übergeben.

Links

https://opencode.ai/
https://opencode.ai/docs/providers/
https://developers.sber.ru/studio/
https://developers.sber.ru/docs/ru/gigachat/guides/main
https://github.com/nyddle/gigachat-ai-sdk-provider
https://github.com/ai-forever/gpt2giga
https://cloud.ru/docs/foundation-models/ug/topics/quickstart

Quellen

https://opencode.ai/docs/providers/#custom-provider
https://developers.sber.ru/docs/ru/gigachat/certificates
https://developers.sber.ru/docs/ru/gigachat/models/main
https://developers.sber.ru/docs/ru/gigachat/guides/selecting-a-model
https://github.com/nyddle/gigachat-ai-sdk-provider
https://github.com/ai-forever/gpt2giga
https://cloud.ru/docs/foundation-models/ug/topics/quickstart
https://cloud.ru/docs/foundation-models/ug/topics/overview__available__models