Proveedores rusos de IA para OpenCode

OpenCode es un agente de programación abierto que funciona directamente en la terminal: lee archivos de proyecto, edita código, ejecuta comandos y pruebas, busca en el repositorio y trabaja con git. Su punto fuerte es que no está vinculado a un solo proveedor modelo y puede conectar docenas de proveedores.

GigaChat es un modelo de lenguaje grande de Sber. No está en la lista lista de proveedores de OpenCode, pero esto no es un problema: OpenCode conecta proveedores arbitrarios a través de paquetes Vercel AI SDK. Para GigaChat existe un paquete gigachat-ai-sdk-provider, que se encarga de la autorización OAuth y de la actualización del token de acceso. Un matiz aparte son los certificados del Ministerio de Desarrollo Digital: sin ellos, Node no confía en los servidores de GigaChat y las solicitudes fallan con un error de verificación del certificado.

En esta publicación describiré cómo obtener una clave, instalar certificados y conectar GigaChat a OpenCode.

Lo que necesitas

Para trabajar necesitas tres cosas:

• OpenCode instalado. Si el agente aún no está instalado, analicé el procedimiento de instalación en una nota separada sobre OpenCode y DeepSeek.
• Cuenta GigaChat. Registro en GigaChat Studio y clave de autorización: necesitará Sber ID para iniciar sesión.
• Terminal moderno. WezTerm, Alacritty, Ghostty, Kitty o cualquier otro servirá.

Clave de autorización de GigaChat

La clave se crea en su cuenta personal de GigaChat Studio. Vaya a developments.sber.ru/studio, inicie sesión y cree un proyecto en la sección GigaChat API. En la configuración del proyecto hay un bloque con datos de autorización: la línea que se copia allí es una clave de autorización ya preparada en base64. Es esto lo que se sustituye en la variable de entorno, y no el par cliente-secreto por separado.

Junto con la clave, se especifica el alcance – el área de acceso:

• GIGACHAT_API_PERS – para particulares.
• GIGACHAT_API_B2B – para empresarios individuales y entidades legales.
• GIGACHAT_API_CORP – acceso corporativo.

El valor clave mostrado debe guardarse inmediatamente: no se volverá a mostrar más tarde y, si es necesario, deberá emitirse uno nuevo.

Es importante entender qué es esta línea. La clave de autorización no es un secreto separado, sino un par de client_id:client_secret ya codificados en base64. La biblioteca gigachat-js sustituye este encabezado en la solicitud de OAuth:

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

En respuesta, un token de acceso JWE tiene una vida útil de aproximadamente media hora y luego la biblioteca lo actualiza automáticamente. El paquete en sí verifica que el valor sea similar a base64 y advierte si la variable contiene accidentalmente un secreto de cliente “sin procesar”. Por lo tanto, es necesario transferir la cadena base64 ya preparada de la cuenta a la variable de configuración y de entorno, y no el par client_id y client_secret por separado.

Certificados del Ministerio de Desarrollo Digital

La API de GigaChat utiliza certificados del Ministerio de Desarrollo Digital de la NCA. El almacén raíz de confianza estándar no los tiene, por lo que al intentar obtener un token de acceso, la solicitud falla con un error como:

self-signed certificate in certificate chain

Los certificados se pueden instalar a nivel del sistema operativo; luego, el navegador y las utilidades del sistema confiarán en ellos. Pero OpenCode se ejecuta en Node y Bun, por lo que es más seguro y fácil especificar el archivo de certificado directamente en la variable NODE_EXTRA_CA_CERTS. Descargue los certificados raíz y de emisor y colóquelos en un archivo 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

El archivo se puede colocar en una ubicación conveniente y se puede especificar su ruta completa al iniciar el agente.

Hay un problema aquí. Los archivos descargados utilizan saltos de línea CRLF y el certificado raíz no tiene un salto de línea final. Por lo tanto, un gato normal concatena el final del primer certificado y el comienzo del segundo en una línea:

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

LibreSSL, y el sistema openssl en macOS, permítanme recordarles, es exactamente LibreSSL, no acepta dicho archivo y responde con un error:

PEM routines:CRYPTO_internal:bad end line

Esto significa que el gato por sí solo no es suficiente. Cada certificado debe ejecutarse primero a través de openssl: lo recodificará en PEM canónico con avances de línea LF y un avance de línea final, y solo luego se fusionará:

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

Puedes comprobar que el archivo se está leyendo así:

openssl x509 -in russian_trusted_ca_bundle.pem -noout -subject

Si los certificados se toman de otra fuente y vienen en formato DER o PKCS#7, también se pueden recodificar en PEM:

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

Conectarse a OpenCode

El proveedor se describe en el archivo de configuración opencode.jsonc. OpenCode descargará y conectará el paquete npm especificado en el campo npm, buscará la fábrica createGigaChat en él y le pasará las opciones. Basta con enumerar los modelos por sus identificadores de la API.

El archivo se puede colocar en dos lugares:

• Global – ~/.config/opencode/opencode.jsonc. La configuración se aplica a todos los proyectos de usuario.
• En el proyecto – opencode.jsonc en la raíz del proyecto. Esta configuración tiene mayor prioridad y es seguro confirmarla con git.

Ambos archivos usan el mismo esquema y se combinan: el archivo del proyecto se superpone al global solo con claves coincidentes, las configuraciones restantes se guardan. También se admite la extensión .jsonc. Si GigaChat es necesario sólo para algunos repositorios, es más conveniente mantener el proveedor en la configuración del proyecto que en la global.

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

Los modelos disponibles con clave personal se enumeran aquí. Si tiene un proyecto para un empresario individual o una entidad legal con acceso a GigaChat 3, agregue los identificadores necesarios del método de modelos al bloque de modelos.

Es más conveniente no almacenar la clave en un archivo, sino pasarla a una variable de entorno: el paquete gigachat-js la lee automáticamente. El valor del alcance también se puede establecer en una variable. Todo lo que queda es establecer la ruta a los certificados e iniciar el agente:

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

Esta opción también es buena porque el secreto no termina en el almacenamiento local de auth.json: vive solo en el entorno del proceso. Esto es más conveniente para CI y lanzamientos únicos.

Modelos

El conjunto de modelos disponibles depende de la clave de alcance. La clave personal (GIGACHAT_API_PERS) está disponible para la familia GigaChat y GigaChat 2:

• GigaChat – modelo básico.
• GigaChat-2: un modelo rápido y liviano para tareas cotidianas, que se muestra como Lite en la interfaz.
• GigaChat-2-Pro: un modelo mejorado para tareas que consumen muchos recursos.
• GigaChat-2-Max es el más poderoso disponible usando una clave personal.

La familia GigaChat 3 (GigaChat-3-Ultra, GigaChat-3-Pro, modelos abiertos como GigaChat3.5-432B-A28B-Reasoning) está visible en el catálogo de consolas, pero no está disponible para la clave personal: requiere un proyecto de empresario individual o una entidad legal con alcance GIGACHAT_API_B2B o GIGACHAT_API_CORP y una tarifa adecuada. En una clave personal, dicho modelo responde con un error:

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

Puede verificar lo que realmente genera su clave consultando la lista de modelos:

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

Dos puntos más. Los ID de modelo en la API no coinciden con los nombres mostrados: el modelo ligero se llama GigaChat-2, no GigaChat-2-Lite. Y el catálogo en la consola no muestra lo mismo que lo que está disponible para tu llave, por lo que debes centrarte en la respuesta del método de modelos, y no en la lista con precios.

En la interfaz, la lista de modelos se abre con el comando:

/models

Para el trabajo de rutina en el repositorio (navegar a través de archivos, realizar ediciones menores, ejecutar pruebas), GigaChat-2 es suficiente. Para tareas y diseños complejos, tiene sentido cambiar a Pro o Max.

Primer lanzamiento del proyecto

Vaya al directorio del proyecto e inicie el agente:

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

El primer paso es inicializar el agente:

/init

OpenCode analizará la estructura del proyecto y creará un archivo AGENTS.md: instrucciones para el agente. Vale la pena comprometer este archivo con git: ayuda al agente a comprender las convenciones y patrones adoptados en el proyecto.

Alternativa: proxy local

Si por alguna razón no desea utilizar el proveedor npm, un proxy local dará el mismo resultado. El equipo de GigaChat tiene un servicio oficial gpt2giga – FastAPI que traduce solicitudes en formato OpenAI, Anthropic y Gemini a la API de GigaChat y actualiza el token de acceso. Se genera localmente en el puerto 8090, después de lo cual se configura un proveedor regular compatible con OpenAI en OpenCode a través del paquete @ai-sdk/openai-compatible con la dirección base http://localhost:8090/v1. La desventaja de esta ruta es que también es necesario mantener un servicio Python en ejecución junto a 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 y otros modelos a través de Cloud.ru

La API de GigaChat en sí no tiene modelos DeepSeek: solo existen la familia GigaChat y modelos para incrustaciones. Si necesita DeepSeek en OpenCode, pero a través de una puerta de enlace en la nube rusa, el servicio Foundation Models de Cloud.ru es adecuado. Ofrece modelos que utilizan el protocolo compatible con OpenAI, por lo que se conecta mediante el paquete estándar @ai-sdk/openai-compatible.

En el catálogo de modelos de Cloud.ru Foundation se encuentran, por ejemplo, los siguientes modelos:

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

La clave se emite en la consola Cloud.ru: sección Usuarios, pestaña Cuentas de servicio. Creamos una cuenta de servicio a nivel de proyecto, luego en sus credenciales creamos una clave API con el servicio Foundation Models. La clave secreta se muestra una vez y la guardamos.

La configuración del proveedor en opencode.json se ve así:

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

Pasamos la clave a la variable de entorno:

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

Aquí no se necesitan certificados del Ministerio de Desarrollo Digital: el dominio api.cloud.ru tiene TLS normal, a diferencia de GigaChat. Pero vale la pena seguir el equilibrio del proyecto. Si la cuenta es cero, la autorización pasa y las solicitudes se descartan con la respuesta de facturación:

{"message":"Not enough money"}

Esto no es un error de configuración, sino una señal de que necesita actualizar el proyecto en la consola Cloud.ru.

A qué prestar atención

Un par de puntos prácticos que suelen obstaculizar la instalación por primera vez:

• Error de verificación del certificado. El mensaje sobre el certificado autofirmado en la cadena significa que la variable NODE_EXTRA_CA_CERTS no fue seleccionada. Verifique la ruta al archivo, que el agente se está ejecutando en el mismo entorno, y el archivo en sí: si, al fusionar dos certificados usando cat, sus extremos terminan en la misma línea, LibreSSL devolverá una línea final incorrecta y el paquete debe reconstruirse a través de openssl, como en la sección sobre certificados.
• Error 401. Como regla general, se trata de una clave de autorización incorrecta o un alcance que no coincide; para un individuo necesita GIGACHAT_API_PERS.
• Error 404 con el texto No existe tal modelo. Esto no es un fallo de conexión, sino una falta de acceso a un modelo específico. Elimínelo de la configuración o reemplácelo por uno disponible. En un mensaje como GigaChat 404: Error desconocido, la culpa es de la misma respuesta de GigaChat: el proveedor simplemente no pudo analizar el cuerpo del error.
• Costo. OpenCode no requiere suscripción: usted paga a GigaChat directamente cuando gasta tokens, por lo que el precio de las sesiones largas es predecible.
• Calidad del modelo. Para tareas arquitectónicas complejas, los modelos de diferentes clases difieren, por lo que para el diseño tiene sentido tomar un modelo más fuerte y darle la rutina a uno más rápido.

Enlaces

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

Fuentes

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