OpenCode é um agente de programação aberto que funciona diretamente no terminal: lê arquivos de projeto, edita código, executa comandos e testes, pesquisa no repositório e trabalha com git. Seu ponto forte é que ele não está vinculado a um provedor modelo e pode conectar dezenas de provedores.
GigaChat é um grande modelo de linguagem da Sber. Não está na lista pronta de provedores OpenCode, mas isso não é um problema: OpenCode conecta provedores arbitrários por meio de pacotes Vercel AI SDK. Para o GigaChat existe um pacote gigachat-ai-sdk-provider, que cuida da autorização OAuth e da atualização do token de acesso. Uma nuance separada são os certificados do Ministério de Desenvolvimento Digital: sem eles, o Node não confia nos servidores GigaChat e as solicitações falham com um erro de verificação do certificado.
Neste post irei descrever como obter uma chave, instalar certificados e conectar o GigaChat ao OpenCode.
O que você precisa
Para funcionar você precisa de três coisas:
- OpenCode instalado. Se o agente ainda não estiver instalado, discuti o procedimento de instalação em uma nota separada sobre OpenCode e DeepSeek.
- Conta GigaChat. Registro no GigaChat Studio e chave de autorização – você precisará do Sber ID para fazer login.
- Terminal moderno. WezTerm, Alacritty, Ghostty, Kitty ou qualquer outro serve.
Chave de autorização do GigaChat
A chave é criada na sua conta pessoal do GigaChat Studio. Acesse developers.sber.ru/studio, faça login e crie um projeto na seção GigaChat API. Nas configurações do projeto existe um bloco com dados de autorização: a linha que é copiada de lá é uma chave de autorização pronta em base64. É isso que é substituído na variável de ambiente, e não no par segredo do cliente separadamente.
Juntamente com a chave, é especificado o escopo – a área de acesso:
- GIGACHAT_API_PERS – para indivíduos.
- GIGACHAT_API_B2B – para empreendedores individuais e pessoas jurídicas.
- GIGACHAT_API_CORP – acesso corporativo.
O valor da chave exibida deverá ser salvo imediatamente: não será mostrado novamente posteriormente e, se necessário, deverá ser emitida uma nova.
É importante entender o que é essa linha. A chave de autorização não é um segredo separado, mas um par de client_id:client_secret já codificados em base64. A biblioteca gigachat-js substitui este cabeçalho na solicitação OAuth:
Authorization: Basic ваш_ключ_авторизации
Em resposta, um token de acesso JWE tem vida útil de cerca de meia hora e, em seguida, a biblioteca o atualiza automaticamente. O próprio pacote verifica se o valor é semelhante a base64 e avisa se a variável contém acidentalmente um segredo “bruto” do cliente. Portanto, é necessário transferir a string base64 pronta da conta para a variável de configuração e ambiente, e não o par client_id e client_secret separadamente.
Certificados do Ministério do Desenvolvimento Digital
A API GigaChat usa certificados do Ministério de Desenvolvimento Digital da NCA. O armazenamento de raízes confiáveis padrão não os possui, portanto, ao tentar obter um token de acesso, a solicitação falha com um erro como:
self-signed certificate in certificate chain
Os certificados podem ser instalados no nível do sistema operacional – então eles serão confiáveis para o navegador e os utilitários do sistema. Mas o OpenCode roda em Node e Bun, então é mais seguro e fácil especificar o arquivo de certificado diretamente na variável NODE_EXTRA_CA_CERTS. Baixe os certificados raiz e do emissor e coloque-os em um arquivo 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
O arquivo pode ser colocado em um local conveniente e seu caminho completo pode ser especificado ao iniciar o agente.
Há um problema aqui. Os arquivos baixados usam quebras de linha CRLF e o certificado raiz não possui um feed de linha final. Portanto, um gato normal concatena o final do primeiro certificado e o início do segundo em uma linha:
-----END CERTIFICATE----------BEGIN CERTIFICATE-----
LibreSSL – e o sistema openssl no macOS, deixe-me lembrá-lo, é exatamente LibreSSL – não aceita tal arquivo e responde com um erro:
PEM routines:CRYPTO_internal:bad end line
Isso significa que só o gato não é suficiente. Cada certificado deve primeiro ser executado através do openssl: ele será recodificado em PEM canônico com feeds de linha LF e um feed de linha final, e só então mesclado:
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
Você pode verificar se o arquivo está sendo lido assim:
openssl x509 -in russian_trusted_ca_bundle.pem -noout -subject
Se os certificados forem obtidos de outra fonte e vierem no formato DER ou PKCS#7, eles também poderão ser recodificados em PEM:
openssl x509 -in cert.crt -inform DER -outform PEM -out cert.pem
openssl pkcs7 -print_certs -in bundle.p7b -out cert.pem
Conecte-se ao OpenCode
O provedor está descrito no arquivo de configuração opencode.jsonc. O próprio OpenCode irá baixar e conectar o pacote npm especificado no campo npm, encontrar a fábrica createGigaChat nele e passar as opções para ele. Basta listar os modelos pelos seus identificadores da API.
O arquivo pode ser colocado em dois locais:
- Global – ~/.config/opencode/opencode.jsonc. As configurações se aplicam a todos os projetos do usuário.
- No projeto – opencode.jsonc na raiz do projeto. Esta configuração tem prioridade mais alta e é segura para commitar no git.
Ambos os arquivos usam o mesmo esquema e são combinados: o arquivo do projeto se sobrepõe ao arquivo global apenas com as chaves correspondentes, as configurações restantes são salvas. A extensão .jsonc também é suportada. Se o GigaChat for necessário apenas para alguns repositórios, é mais conveniente manter o provedor na configuração do projeto do que na configuração 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" }
}
}
}
}
Os modelos disponíveis com chave pessoal estão listados aqui. Se você possui um projeto para empresário individual ou pessoa jurídica com acesso ao GigaChat 3, adicione os identificadores necessários do método models ao bloco models.
É mais conveniente não armazenar a chave em si em um arquivo, mas passá-la para uma variável de ambiente: o pacote gigachat-js a lê automaticamente. O valor do escopo também pode ser definido como uma variável. Resta apenas definir o caminho para os certificados e iniciar o agente:
export GIGACHAT_CREDENTIALS=ваш_ключ_авторизации
export GIGACHAT_SCOPE=GIGACHAT_API_PERS
export NODE_EXTRA_CA_CERTS=/путь/к/russian_trusted_ca_bundle.pem
opencode
Essa opção também é boa porque o segredo não vai parar no armazenamento local auth.json: ele fica apenas no ambiente do processo. Isso é mais conveniente para CI e lançamentos únicos.
Modelos
O conjunto de modelos disponíveis depende da chave do escopo. A chave pessoal (GIGACHAT_API_PERS) está disponível para a família GigaChat e GigaChat 2:
- GigaChat – modelo básico.
- GigaChat-2 – um modelo rápido e leve para tarefas diárias, exibido como Lite na interface.
- GigaChat-2-Pro – um modelo aprimorado para tarefas que consomem muitos recursos.
- GigaChat-2-Max é o mais poderoso disponível usando uma chave pessoal.
A família GigaChat 3 (GigaChat-3-Ultra, GigaChat-3-Pro, modelos abertos como GigaChat3.5-432B-A28B-Reasoning) é visível no catálogo do console, mas não está disponível para a chave pessoal: requer um projeto de empreendedor individual ou pessoa jurídica com escopo GIGACHAT_API_B2B ou GIGACHAT_API_CORP e tarifa adequada. Em uma chave pessoal, esse modelo responde com um erro:
{"status":404,"message":"No such model"}
Você pode verificar o que sua chave realmente produz consultando a lista de modelos:
curl -H "Authorization: Bearer <токен_доступа>" https://gigachat.devices.sberbank.ru/api/v1/models
Mais dois pontos. Os IDs de modelo na API não correspondem aos nomes exibidos – o modelo light é chamado de GigaChat-2, não de GigaChat-2-Lite. E o catálogo do console não mostra a mesma coisa que está disponível para sua chave, então você deve focar na resposta do método dos modelos, e não na lista com preços.
Na interface, a lista de modelos é aberta com o comando:
/models
Para trabalhos de rotina no repositório – navegação por arquivos, pequenas edições, execução de testes – o GigaChat-2 é suficiente. Para tarefas e design complexos, faz sentido mudar para Pro ou Max.
Primeiro lançamento do projeto
Vá para o diretório do projeto e inicie o agente:
cd ваш_проект
opencode
A primeira etapa é inicializar o agente:
/init
OpenCode analisará a estrutura do projeto e criará um arquivo AGENTS.md – instruções para o agente. Vale a pena comprometer esse arquivo com o git: ele ajuda o agente a entender as convenções e padrões adotados no projeto.
Alternativa: proxy local
Se por algum motivo você não quiser usar o provedor npm, um proxy local fornecerá o mesmo resultado. A equipe GigaChat possui um serviço oficial gpt2giga – FastAPI que traduz solicitações nos formatos OpenAI, Anthropic e Gemini para a API GigaChat e atualiza o próprio token de acesso. Ele é gerado localmente na porta 8090, após a qual um provedor regular compatível com OpenAI é configurado no OpenCode por meio do pacote @ai-sdk/openai-compatível com o endereço base http://localhost:8090/v1. A desvantagem desse caminho é que você também precisa manter um serviço Python em execução próximo ao 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 e outros modelos via Cloud.ru
A API GigaChat em si não possui modelos DeepSeek: existem apenas a família GigaChat e modelos para embeddings. Se você precisar do DeepSeek no OpenCode, mas por meio de um gateway de nuvem russo, o serviço Foundation Models da Cloud.ru é adequado. Ele fornece modelos usando o protocolo compatível com OpenAI, portanto, é conectado usando o pacote padrão @ai-sdk/openai-compatível.
No catálogo Cloud.ru Foundation Models existem, por exemplo, os seguintes modelos:
deepseek-ai/DeepSeek-V4.1-Flash
deepseek-ai/DeepSeek-V4-Flash
deepseek-ai/DeepSeek-V4-Pro
A chave é emitida no console Cloud.ru: seção Usuários, guia Contas de serviço. Criamos uma conta de serviço em nível de projeto e, em suas credenciais, criamos uma chave de API com o serviço Foundation Models. O segredo da chave é mostrado uma vez e nós o salvamos.
A configuração do provedor em opencode.json é assim:
{
"$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 } }
}
}
}
}
Passamos a chave para a variável de ambiente:
export CLOUDRU_API_KEY=ваш_ключ_cloudru
opencode
Os certificados do Ministério do Desenvolvimento Digital não são necessários aqui: o domínio api.cloud.ru possui TLS regular, ao contrário do GigaChat. Mas vale a pena acompanhar o equilíbrio do projeto. Se a conta for zero, a autorização será aprovada e as solicitações serão descartadas com a resposta de cobrança:
{"message":"Not enough money"}
Este não é um erro de configuração, mas um sinal de que você precisa atualizar o projeto no console Cloud.ru.
No que prestar atenção
Alguns pontos práticos que costumam atrapalhar na primeira configuração:
- Erro de verificação do certificado. A mensagem sobre certificado autoassinado na cadeia significa que a variável NODE_EXTRA_CA_CERTS não foi selecionada. Verifique o caminho do arquivo, se o agente está rodando no mesmo ambiente e o próprio arquivo: se, ao mesclar dois certificados usando cat, suas extremidades terminarem na mesma linha, o LibreSSL retornará uma linha final incorreta e o pacote precisa ser reconstruído via openssl, como na seção sobre certificados.
- Erro 401. Como regra, esta é uma chave de autorização incorreta ou um escopo incompatível. Para um indivíduo, você precisa de GIGACHAT_API_PERS.
- Erro 404 com o texto Esse modelo não existe. Isso não é uma falha de conexão, mas uma falta de acesso a um modelo específico. Remova-o da configuração ou substitua-o por um disponível. Em uma mensagem como GigaChat 404: Erro desconhecido, a culpa é da mesma resposta do GigaChat – o provedor simplesmente não conseguiu analisar o corpo do erro.
- Custo. O OpenCode não requer assinatura: você paga o GigaChat diretamente quando gasta tokens, portanto, sessões longas têm preço previsível.
- Qualidade do modelo. Para tarefas arquitetônicas complexas, modelos de classes diferentes são diferentes, portanto, para o projeto, faz sentido escolher um modelo mais forte e dar a rotina a um modelo mais rápido.
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
Fontes
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