OpenCode is an open programming agent that works directly in the terminal: reads project files, edits code, runs commands and tests, searches the repository and works with git. Its strength is that it is not tied to one model provider and can connect dozens of providers.
GigaChat is a large language model from Sber. It is not in the ready list of OpenCode providers, but this is not a problem: OpenCode connects arbitrary providers through Vercel AI SDK packages. For GigaChat there is a package gigachat-ai-sdk-provider, which takes care of OAuth authorization and updating the access token. A separate nuance is the Ministry of Digital Development certificates: without them, Node does not trust GigaChat servers, and requests fail with a certificate verification error.
In this post I will describe how to get a key, install certificates and connect GigaChat to OpenCode.
What you need
To work you need three things:
- OpenCode installed. If the agent is not yet installed, I discussed the installation procedure in a separate note about OpenCode and DeepSeek.
- GigaChat account. Registration in GigaChat Studio and authorization key – you will need Sber ID to log in.
- Modern terminal. WezTerm, Alacritty, Ghostty, Kitty or any other will do.
GigaChat authorization key
The key is created in your GigaChat Studio personal account. Go to developers.sber.ru/studio, log in and create a project in the GigaChat API section. In the project settings there is a block with authorization data: the line that is copied from there is a ready-made authorization key in base64. It is this that is substituted into the environment variable, and not the client-secret pair separately.
Together with the key, scope is specified – the access area:
- GIGACHAT_API_PERS – for individuals.
- GIGACHAT_API_B2B – for individual entrepreneurs and legal entities.
- GIGACHAT_API_CORP – corporate access.
The displayed key value should be saved immediately: it will not be shown again later, and if necessary, a new one will have to be issued.
It is important to understand what this line is. The authorization key is not a separate secret, but a pair of client_id:client_secret already encoded in base64. The gigachat-js library substitutes this header into the OAuth request:
Authorization: Basic ваш_ключ_авторизации
In response, a JWE access token comes with a lifetime of about half an hour, and then the library updates it automatically. The package itself checks that the value is similar to base64 and warns if the variable accidentally contains a “raw” client secret. Therefore, it is necessary to transfer the ready-made base64 string from the account to the config and environment variable, and not the client_id and client_secret pair separately.
Certificates of the Ministry of Digital Development
GigaChat API uses certificates from the NCA Ministry of Digital Development. The standard trusted roots store does not have them, so when trying to get an access token, the request fails with an error like:
self-signed certificate in certificate chain
Certificates can be installed at the operating system level – then they will be trusted by the browser and system utilities. But OpenCode runs on Node and Bun, so it’s safer and easier to specify the certificate file directly in the NODE_EXTRA_CA_CERTS variable. Download the root and issuer certificates and put them into one PEM file:
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
The file can be placed in a convenient location and its full path can be specified when starting the agent.
There’s a catch here. Downloaded files use CRLF line breaks, and the root certificate does not have a trailing line feed. Therefore, a regular cat concatenates the end of the first certificate and the beginning of the second into one line:
-----END CERTIFICATE----------BEGIN CERTIFICATE-----
LibreSSL – and the system openssl on macOS, let me remind you, is exactly LibreSSL – does not accept such a file and responds with an error:
PEM routines:CRYPTO_internal:bad end line
This means that cat alone is not enough. Each certificate must first be run through openssl: it will recode it into canonical PEM with LF line feeds and a final line feed, and only then merged:
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
You can check that the file is being read like this:
openssl x509 -in russian_trusted_ca_bundle.pem -noout -subject
If the certificates are taken from another source and come in DER or PKCS#7 format, they can also be recoded into PEM:
openssl x509 -in cert.crt -inform DER -outform PEM -out cert.pem
openssl pkcs7 -print_certs -in bundle.p7b -out cert.pem
Connect to OpenCode
The provider is described in the opencode.jsonc configuration file. OpenCode itself will download and connect the npm package specified in the npm field, find the createGigaChat factory in it and pass the options to it. It is enough to list the models by their identifiers from the API.
The file can be placed in two places:
- Global – ~/.config/opencode/opencode.jsonc. The settings apply to all user projects.
- In the project – opencode.jsonc in the project root. This config has higher priority and is safe to commit to git.
Both files use the same scheme and are combined: the project file overlaps the global one only with matching keys, the remaining settings are saved. The .jsonc extension is also supported. If GigaChat is needed only for some repositories, it is more convenient to keep the provider in the project config rather than in the global one.
{
"$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" }
}
}
}
}
Models available with a personal key are listed here. If you have a project for an individual entrepreneur or a legal entity with access to GigaChat 3, add the necessary identifiers from the models method to the models block.
It is more convenient not to store the key itself in a file, but to pass it to an environment variable: the gigachat-js package reads it automatically. The scope value can also be set to a variable. All that remains is to set the path to the certificates and launch the agent:
export GIGACHAT_CREDENTIALS=ваш_ключ_авторизации
export GIGACHAT_SCOPE=GIGACHAT_API_PERS
export NODE_EXTRA_CA_CERTS=/путь/к/russian_trusted_ca_bundle.pem
opencode
This option is also good because the secret does not end up in the local auth.json storage: it lives only in the environment of the process. This is more convenient for CI and one-time launches.
Models
The set of available models depends on the scope key. The personal key (GIGACHAT_API_PERS) is available to the GigaChat and GigaChat 2 family:
- GigaChat – basic model.
- GigaChat-2 – a fast and lightweight model for everyday tasks, displayed as Lite in the interface.
- GigaChat-2-Pro – an improved model for resource-intensive tasks.
- GigaChat-2-Max is the most powerful available using a personal key.
The GigaChat 3 family (GigaChat-3-Ultra, GigaChat-3-Pro, open models like GigaChat3.5-432B-A28B-Reasoning) is visible in the console catalog, but it is not available to the personal key: it requires an individual entrepreneur project or a legal entity with scope GIGACHAT_API_B2B or GIGACHAT_API_CORP and a suitable tariff. On a personal key, such a model responds with an error:
{"status":404,"message":"No such model"}
You can check what your key actually outputs by querying the list of models:
curl -H "Authorization: Bearer <токен_доступа>" https://gigachat.devices.sberbank.ru/api/v1/models
Two more points. Model IDs in the API do not match the displayed names – the light model is called as GigaChat-2, not GigaChat-2-Lite. And the catalog in the console does not show the same thing as what is available to your key, so you should focus on the response of the models method, and not on the list with prices.
In the interface, the list of models is opened with the command:
/models
For routine work in the repository – navigating through files, minor edits, running tests – GigaChat-2 is quite enough. For complex tasks and design, it makes sense to switch to Pro or Max.
First launch in the project
Go to the project directory and launch the agent:
cd ваш_проект
opencode
The first step is to initialize the agent:
/init
OpenCode will analyze the project structure and create a file AGENTS.md – instructions for the agent. This file is worth committing to git: it helps the agent understand the conventions and patterns adopted in the project.
Alternative: local proxy
If for some reason you don’t want to use the npm provider, a local proxy gives the same result. The GigaChat team has an official gpt2giga – FastAPI service that translates requests in OpenAI, Anthropic and Gemini format into the GigaChat API and updates the access token itself. It is raised locally on port 8090, after which a regular OpenAI-compatible provider is configured in OpenCode via the @ai-sdk/openai-compatible package with the base address http://localhost:8090/v1. The downside of this path is that you also need to keep a running Python service next to 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 and other models via Cloud.ru
The GigaChat API itself does not have DeepSeek models: there are only the GigaChat family and models for embeddings. If you need DeepSeek in OpenCode, but through a Russian cloud gateway, the Foundation Models service from Cloud.ru is suitable. It delivers models using the OpenAI-compatible protocol, so it is connected using the standard @ai-sdk/openai-compatible package.
In the Cloud.ru Foundation Models catalog there are, for example, the following models:
deepseek-ai/DeepSeek-V4.1-Flash
deepseek-ai/DeepSeek-V4-Flash
deepseek-ai/DeepSeek-V4-Pro
The key is issued in the Cloud.ru console: section Users, tab Service accounts. We create a project-level service account, then in its credentials we create an API key with the Foundation Models service. The key secret is shown once and we save it.
The provider configuration in opencode.json looks like this:
{
"$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 } }
}
}
}
}
We pass the key to the environment variable:
export CLOUDRU_API_KEY=ваш_ключ_cloudru
opencode
Ministry of Digital Development certificates are not needed here: the api.cloud.ru domain has regular TLS, unlike GigaChat. But it is worth monitoring the balance of the project. If the account is zero, authorization passes, and requests are dropped with the billing response:
{"message":"Not enough money"}
This is not a config error, but a signal that you need to update the project in the Cloud.ru console.
What to pay attention to
A couple of practical points that most often get in the way when setting up for the first time:
- Certificate verification error. The message about self-signed certificate in the chain means that the NODE_EXTRA_CA_CERTS variable was not picked up. Check the path to the file, that the agent is running in the same environment, and the file itself: if, when merging two certificates using cat, their ends end up on the same line, LibreSSL will return a bad end line, and the bundle needs to be rebuilt via openssl, as in the section about certificates.
- Error 401. As a rule, this is an incorrect authorization key or a mismatched scope – for an individual you need GIGACHAT_API_PERS.
- Error 404 with the text No such model. This is not a connection failure, but a lack of access to a specific model. Remove it from the config or replace it with an available one. In a message like GigaChat 404: Unknown error, the same GigaChat response is to blame – the provider simply could not parse the error body.
- Cost. OpenCode does not require a subscription: you pay GigaChat directly when you spend tokens, so long sessions are predictable in price.
- Model quality. For complex architectural tasks, models of different classes differ, so for design it makes sense to take a stronger model and give the routine to a faster one.
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
Sources
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
Leave a Reply