ロシアの OpenCode 用 AI プロバイダー

OpenCode は、ターミナルで直接動作するオープン プログラミング エージェントです。プロジェクト ファイルの読み取り、コードの編集、コマンドとテストの実行、リポジトリの検索、git との連携を行います。その強みは、1 つのモデル プロバイダーに縛られず、数十のプロバイダーを接続できることです。

GigaChat は、Sber による大規模な言語モデルです。 OpenCode プロバイダーの準備完了リストには含まれていませんが、これは問題ではありません。OpenCode は Vercel AI SDK パッケージを通じて任意のプロバイダーに接続します。 GigaChat には、OAuth 認証とアクセス トークンの更新を処理するパッケージ gigachat-ai-sdk-provider があります。別のニュアンスは、デジタル開発省の証明書です。証明書がないと、Node は GigaChat サーバーを信頼せず、リクエストは証明書検証エラーで失敗します。

この投稿では、キーを取得し、証明書をインストールし、GigaChat を OpenCode に接続する方法について説明します。

必要なもの

機能するには次の 3 つのものが必要です。

• OpenCode がインストールされています。 エージェントがまだインストールされていない場合は、OpenCode と DeepSeek に関する別のメモでインストール手順について説明しました。
• GigaChat アカウント。 GigaChat Studio への登録と認証キー – ログインするには Sber ID が必要です。
• 最新の端末。 WezTerm、Alacritty、Ghostty、Kitty などの端末を使用できます。

GigaChat 認証キー

キーは GigaChat Studio 個人アカウントで作成されます。 developers.sber.ru/studio に移動し、ログインして、GigaChat API セクションでプロジェクトを作成します。プロジェクト設定には、認証データを含むブロックがあります。そこからコピーされた行は、base64 の既製の認証キーです。環境変数に代入されるのは、クライアントとシークレットのペアを個別に代入するのではなく、これです。

キーとともにスコープ が指定されます – アクセス領域:

• GIGACHAT_API_PERS – 個人向け
• GIGACHAT_API_B2B – 個人起業家および法人向け
• GIGACHAT_API_CORP – 企業アクセス。

表示されたキー値はすぐに保存する必要があります。後で再度表示されることはなく、必要に応じて新しいキー値を発行する必要があります。

この線が何であるかを理解することが重要です。認証キーは個別のシークレットではなく、すでに Base64 でエンコードされた client_id:client_secret のペアです。 gigachat-js ライブラリは、次のヘッダーを OAuth リクエストに置き換えます。

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

これに応じて、JWE アクセス トークンの有効期間は約 30 分で、ライブラリはそれを自動的に更新します。パッケージ自体は、値がbase64に類似していることをチェックし、変数に誤って「生の」クライアント シークレットが含まれている場合は警告します。したがって、client_id と client_secret のペアを個別に転送するのではなく、既製の Base64 文字列をアカウントから config および環境変数に転送する必要があります。

デジタル開発省の証明書

GigaChat API は、NCA デジタル開発省からの証明書を使用します。標準の信頼されたルート ストアにはそれらが存在しないため、アクセス トークンを取得しようとすると、リクエストは次のようなエラーで失敗します。

self-signed certificate in certificate chain

証明書はオペレーティング システム レベルでインストールでき、ブラウザおよびシステム ユーティリティによって信頼されます。ただし、OpenCode は Node と Bun で実行されるため、証明書ファイルを NODE_EXTRA_CA_CERTS 変数に直接指定する方が安全かつ簡単です。ルート証明書と発行者の証明書をダウンロードし、1 つの PEM ファイルに入れます。

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

ファイルは便利な場所に配置でき、エージェントの起動時にそのフルパスを指定できます。

ここに落とし穴があります。ダウンロードされたファイルには CRLF 改行が使用されており、ルート証明書には末尾に改行がありません。したがって、通常の cat は、最初の証明書の終わりと 2 番目の証明書の始まりを 1 行に連結します。

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

LibreSSL – macOS 上のシステム openssl は、正確に LibreSSL であることを思い出してください。このようなファイルは受け入れられず、エラーで応答します。

PEM routines:CRYPTO_internal:bad end line

つまり、猫だけでは不十分なのです。各証明書はまず openssl で実行する必要があります。openssl は、LF 改行と最終改行を含む正規の PEM に再コード化し、その後にのみマージします。

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

次のようにファイルが読み取られていることを確認できます。

openssl x509 -in russian_trusted_ca_bundle.pem -noout -subject

証明書が別のソースから取得され、DER または PKCS#7 形式である場合は、PEM に再コード化することもできます。

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

OpenCode に接続

プロバイダは opencode.jsonc 設定ファイルに記述されています。 OpenCode 自体は、npm フィールドで指定された npm パッケージをダウンロードして接続し、 その中でcreateGigaChat ファクトリを見つけてオプションを渡します。 API からの識別子によってモデルをリストするだけで十分です。

ファイルは次の 2 つの場所に配置できます。

• グローバル – ~/.config/opencode/opencode.jsonc。設定はすべてのユーザー プロジェクトに適用されます。
• プロジェクト内 – プロジェクト ルートの opencode.jsonc。この構成は優先度が高く、git に安全にコミットできます。

両方のファイルは同じスキームを使用し、結合されます。プロジェクト ファイルは一致するキーを持つグローバル ファイルとのみ重複し、残りの設定は保存されます。 .jsonc 拡張子もサポートされています。 GigaChat が一部のリポジトリでのみ必要な場合は、プロバイダーをグローバル構成ではなくプロジェクト構成に保持する方が便利です。

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

個人キー付きで利用可能なモデルはここにリストされています。 GigaChat 3 にアクセスできる個人起業家または法人向けのプロジェクトがある場合は、models メソッドからの必要な識別子を models ブロックに追加します。

キー自体をファイルに保存するのではなく、環境変数に渡す方が便利です。gigachat-js パッケージが自動的にキーを読み取ります。スコープ値を変数に設定することもできます。残っているのは、証明書へのパスを設定し、エージェントを起動することだけです。

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

このオプションは、シークレットがローカルの auth.json ストレージに保存されず、プロセスの環境内にのみ存在するため、優れています。これは、CI や 1 回限りの起動の場合に便利です。

モデル

使用可能なモデルのセットはスコープ キーによって異なります。個人キー (GIGACHAT_API_PERS) は、GigaChat および GigaChat 2 ファミリで使用できます。

• GigaChat – 基本モデル。
• GigaChat-2 – 日常業務向けの高速かつ軽量のモデル。インターフェースでは Lite として表示されます。
• GigaChat-2-Pro – リソースを大量に消費するタスク向けに改良されたモデル。
• GigaChat-2-Max は、個人キーを使用して利用できる中で最も強力です。

GigaChat 3 ファミリ (GigaChat-3-Ultra、GigaChat-3-Pro、GigaChat3.5-432B-A28B-Reasoning などのオープン モデル) はコンソール カタログに表示されますが、個人キーでは利用できません。スコープ GIGACHAT_API_B2B または GIGACHAT_API_CORP と適切な料金を持つ個人の起業家プロジェクトまたは法人が必要です。個人キーでは、このようなモデルはエラーで応答します。

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

モデルのリストをクエリすることで、キーが実際に出力するものを確認できます。

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

あと2点。 API のモデル ID は表示される名前と一致しません。ライト モデルは GigaChat-2-Lite ではなく、GigaChat-2 と呼ばれます。また、コンソールのカタログには、キーで利用できるものと同じものは表示されないため、価格のリストではなく、モデル メソッドの応答に焦点を当てる必要があります。

インターフェイスでは、次のコマンドを使用してモデルのリストが開きます。

/models

ファイル間の移動、軽微な編集、テストの実行など、リポジトリ内での日常的な作業には、GigaChat-2 で十分です。複雑なタスクやデザインの場合は、Pro または Max に切り替えるのが合理的です。

プロジェクトでの最初の起動

プロジェクト ディレクトリに移動し、エージェントを起動します。

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

最初のステップは、エージェントを初期化することです。

/init

OpenCode はプロジェクト構造を分析し、エージェントへの指示であるファイル AGENTS.md を作成します。このファイルは git にコミットする価値があります。エージェントがプロジェクトで採用されている規則とパターンを理解するのに役立ちます。

代替: ローカル プロキシ

何らかの理由で npm プロバイダーを使用したくない場合は、ローカル プロキシでも同じ結果が得られます。 GigaChat チームには、公式の gpt2giga – FastAPI サービスがあり、OpenAI、Anthropic、Gemini 形式のリクエストを GigaChat API に変換し、アクセス トークン自体を更新します。これはポート 8090 でローカルに生成され、その後、通常の OpenAI 互換プロバイダーが、ベース アドレス http://localhost:8090/v1 の @ai-sdk/openai-compatibility パッケージを介して OpenCode で設定されます。このパスの欠点は、実行中の Python サービスを OpenCode の隣に維持する必要があることです。

{
  "$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 および Cloud.ru 経由のその他のモデル

GigaChat API 自体には DeepSeek モデルはありません。存在するのは GigaChat ファミリと埋め込み用のモデルのみです。 OpenCode で DeepSeek が必要だが、ロシアのクラウド ゲートウェイを経由する場合は、Cloud.ru の Foundation Models サービスが適しています。 OpenAI 互換プロトコルを使用してモデルを配信するため、標準の @ai-sdk/openai-compatibility パッケージを使用して接続されます。

Cloud.ru Foundation Models カタログには、たとえば次のモデルがあります。

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

キーは、Cloud.ru コンソールの [ユーザー] セクション、[サービス アカウント] タブで発行されます。プロジェクト レベルのサービス アカウントを作成し、その認証情報で Foundation Models サービスの API キーを作成します。キーの秘密は一度表示され、保存されます。

opencode.json のプロバイダー構成は次のようになります。

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

キーを環境変数に渡します。

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

ここではデジタル開発省の証明書は必要ありません。api.cloud.ru ドメインには、GigaChat とは異なり、通常の TLS があります。しかし、プロジェクトのバランスを監視する価値はあります。アカウントがゼロの場合、認証は成功し、リクエストは請求応答とともにドロップされます。

{"message":"Not enough money"}

これは構成エラーではなく、Cloud.ru コンソールでプロジェクトを更新する必要があることを示しています。

注意すべきこと

初めてセットアップするときに最もよく問題となるいくつかの実用的なポイント:

• 証明書検証エラー。 チェーン内の自己署名証明書に関するメッセージは、NODE_EXTRA_CA_CERTS 変数が選択されなかったことを意味します。ファイルへのパス、エージェントが同じ環境で実行されていること、およびファイル自体を確認します。cat を使用して 2 つの証明書をマージするときに、それらの末尾が同じ行になる場合、LibreSSL は不正な末尾行を返し、証明書に関するセクションと同様に、openssl を介してバンドルを再構築する必要があります。
• エラー 401。 原則として、これは不正な認証キーまたはスコープの不一致です。個人の場合は GIGACHAT_API_PERS が必要です。
• エラー 404 とそのようなモデルはありません。 これは接続エラーではなく、特定のモデルにアクセスできないことです。構成から削除するか、利用可能なものに置き換えてください。 「GigaChat 404: Unknown error」のようなメッセージでは、同じ GigaChat の応答が原因です。プロバイダがエラー本文を解析できなかっただけです。
• コスト。 OpenCode はサブスクリプションを必要としません。トークンを使用するときに GigaChat に直接支払うため、長時間のセッションの価格は予測可能です。
• モデルの品質。 複雑なアーキテクチャ タスクの場合、クラスごとにモデルが異なるため、設計ではより強力なモデルを採用し、より高速なモデルにルーチンを与えることが合理的です。

リンク

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

ソース

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