O OpenCode é um dos agentes de codificação de IA de código aberto mais comentados de 2026. Sua filosofia de design é "agnóstica ao modelo e prioridade ao terminal", permitindo que desenvolvedores executem o Claude, invoquem o GPT, Gemini, modelos locais ou até mesmo misturem e combinem conforme a necessidade. Assim como o Claude Code, ele roda diretamente no terminal, mas segue um caminho diferente: abstrai o provedor em itens de configuração "plug-and-play", deixando a decisão sobre o modelo subjacente inteiramente nas mãos do usuário.
Muitos leitores me perguntam algo muito específico: pela configuração, o OpenCode parece usar o modo de compatibilidade da OpenAI, então ele suporta o formato nativo da Anthropic? Como escolher a melhor opção ao conectar serviços proxy de API como o APIYI?
Este artigo apresenta uma verificação completa baseada na documentação oficial em inglês e no código-fonte. Primeiro, explicaremos o que é o OpenCode e suas diferenças cruciais em relação ao Claude Code, e depois demonstraremos passo a passo como conectá-lo ao serviço proxy de API APIYI (apiyi.com), cobrindo os métodos de invocação compatíveis com OpenAI e os nativos da Anthropic. Após a leitura, você estará pronto para configurar o seu.
Introdução ao projeto OpenCode: O posicionamento central de um agente de codificação de IA de código aberto
O OpenCode é mantido pela equipe sst (os mesmos autores do framework SST/Serverless Stack), com repositório em github.com/sst/opencode e sob licença MIT. Até o momento desta publicação, já acumulou mais de 150 mil estrelas no GitHub e conta com mais de 850 colaboradores, sendo um dos projetos de agentes de codificação de código aberto mais ativos atualmente. Seu público-alvo é muito claro: desenvolvedores de nível pleno a sênior que desejam realizar a maioria das tarefas de codificação no terminal sem ficarem presos a um único fornecedor de modelos.
Design de arquitetura e modo de operação do OpenCode
O OpenCode adota uma arquitetura cliente/servidor, executando a lógica central do agente em um processo de serviço local, onde a TUI (Interface de Usuário do Terminal) é apenas um dos muitos front-ends. Isso significa que a mesma instância do agente pode ser acessada simultaneamente pelo terminal, aplicativos de desktop, plugins de IDE e até dispositivos móveis, oferecendo um grande potencial para colaboração multiplataforma no futuro.
Ele possui dois modos de agente integrados, alternáveis instantaneamente pela tecla Tab:
- Modo
build: Permite acesso total às ferramentas por padrão, com permissões de leitura, escrita e execução de comandos, ideal para tarefas de desenvolvimento reais. - Modo
plan: Modo somente leitura, focado apenas em análise de código, design de soluções e sugestões, sem modificar nenhum arquivo.
| Dimensão | Pontos de design do OpenCode | Valor para o desenvolvedor |
|---|---|---|
| Arquitetura | Separação cliente/servidor | Colaboração multiplataforma, controle remoto |
| Camada de modelo | Abstração como provedor plugável | Alternância livre entre mais de 75 modelos |
| Camada de interação | TUI / App Desktop / Plugin IDE | Não limitado a uma interface |
| Camada de permissão | Modos duplos build / plan | Equilíbrio entre segurança e eficiência |
| Método de implantação | Prioridade local, suporte a conexão remota | Dados permanecem localmente |
🎯 Dica de configuração: Se você deseja usar vários modelos como Claude, GPT, Gemini e DeepSeek no OpenCode, sem precisar abrir uma conta e manter várias chaves API para cada um, pode conectar-se diretamente ao serviço proxy de API APIYI (apiyi.com) e usar um único token para cobrir os principais modelos.
Capacidades principais do OpenCode
O escopo de suas capacidades é muito maior do que o dos plugins de IDE tradicionais. Ao inserir linguagem natural no terminal, o OpenCode pode interpretar todo o repositório de código, adicionar funcionalidades, modificar lógicas existentes, executar testes e até realizar refatorações entre arquivos. O modo plan é usado para revisão prévia: deixe o agente gerar o fluxo de implementação e, após a confirmação do desenvolvedor, mude para o modo build para aplicar as alterações.
Ele também suporta o modo não interativo opencode run "seu comando", que pode ser incluído diretamente em scripts de shell para automação em CI/CD, refatorações em lote, tarefas agendadas, etc. Essa capacidade não estava presente nas primeiras versões do Claude Code e é uma das razões pelas quais o OpenCode é frequentemente escolhido para cenários de engenharia.
Vale ressaltar que o OpenCode busca por padrão a lista de modelos no banco de dados público models.dev e a faz a correspondência. Portanto, mesmo que o provedor upstream lance um novo modelo, o OpenCode consegue detectá-lo rapidamente. Ao conectar-se via serviço proxy, o mapeamento de modelos mantido localmente pode ser sincronizado com a lista de modelos do painel da APIYI, evitando situações embaraçosas onde "o ID do modelo foi escrito na configuração, mas a solicitação real foi recusada".
Diferenças fundamentais entre OpenCode e Claude Code
Muitas pessoas consideram o OpenCode como uma "versão open source do Claude Code", mas o posicionamento de ambos não se sobrepõe. O Claude Code é uma ferramenta de primeira classe criada pela Anthropic especificamente para seus próprios modelos, enquanto o OpenCode é uma estrutura neutra voltada para um ecossistema de múltiplos modelos.
Alcance do suporte a modelos e controle de custos
O Claude Code só pode invocar modelos da própria Anthropic (séries Sonnet, Opus e Haiku), o que significa que todas as tarefas são cobradas de acordo com a precificação da Anthropic. O OpenCode suporta mais de 75 provedores, incluindo OpenAI, Anthropic, Google Vertex, Bedrock, Groq, Azure, OpenRouter e até backends de inferência local como Ollama e LM Studio.
Essa flexibilidade é muito útil em fluxos de trabalho reais. Tarefas leves, como geração de documentação, mensagens de commit ou renomeação de variáveis, podem ser delegadas a modelos menores e mais baratos, enquanto refatorações complexas e reflexões arquiteturais podem ser direcionadas ao Claude Sonnet ou Opus, reduzindo o custo total em 40–60%.
Diferenças no fluxo de trabalho e modelo de permissões
O Claude Code adota uma abordagem conservadora por padrão: ele solicita confirmação antes de escrever arquivos ou executar comandos, o que é amigável para iniciantes, mas pode interromper o ritmo. O OpenCode segue uma linha transparente — o código é totalmente aberto, permitindo auditoria pela equipe de segurança, e as permissões são gerenciadas explicitamente através da alternância build/plan, sendo mais amigável para automação e scripts.
| Dimensão de Comparação | OpenCode | Claude Code |
|---|---|---|
| Status Open Source | MIT, código auditável | Fechado, apenas binário |
| Alcance de modelos | 75+ provedores, incl. locais | Apenas modelos Anthropic |
| Endpoint personalizado | Qualquer provedor (baseURL) | Via ANTHROPIC_BASE_URL |
| Interface | TUI / App Desktop / Plugin IDE | Focado no terminal |
| Política de permissão | Alternância explícita build/plan | Confirmação por pergunta |
| Maturidade | Evolução rápida, detalhes em ajuste | Experiência mais polida |
| Cenário ideal | Mix de modelos, local, customização | Experiência Claude completa |
🎯 Sugestão de escolha: Se o seu fluxo de trabalho é centrado no Claude, mas você ocasionalmente deseja usar GPT ou Gemini como backup, recomendo configurar vários modelos no OpenCode através do serviço proxy de API da APIYI (apiyi.com), alternando com a mesma chave. Use o Claude Code nativo para o desenvolvimento principal e mude para o OpenCode para validação cruzada em tarefas complexas.
Para quem é o OpenCode?
O público ideal para o OpenCode são desenvolvedores dispostos a ler 20 minutos de documentação de configuração, sensíveis a custos, que desejam usar a mesma cadeia de ferramentas em vários modelos ou que trabalham em empresas onde os modelos precisam ser auditáveis. Se você quer apenas "usar o Claude imediatamente", o Claude Code continua sendo a escolha mais prática.
Dois modos de invocação do OpenCode ao conectar ao serviço proxy de API da APIYI
Voltando à pergunta que mais interessa aos leitores: o OpenCode usa o modo compatível com OpenAI ou o formato nativo da Anthropic? A resposta é que ambos são suportados, dependendo de como você configura o provedor no opencode.json.
Modo 1: Compatível com OpenAI (Mais universal)
Esta é a forma recomendada pela documentação do OpenCode e o caminho mais seguro para conectar a um serviço proxy de terceiros. Internamente, utiliza o pacote @ai-sdk/openai-compatible do Vercel AI SDK, encapsulando qualquer endpoint que siga o protocolo Chat Completions da OpenAI como um provedor do OpenCode. O endpoint compatível com OpenAI da APIYI é api.apiyi.com/v1, permitindo invocar GPT, Claude, Gemini, DeepSeek e dezenas de outros modelos, unificando-os no formato OpenAI.
Sua vantagem é a versatilidade; quase todos os modelos podem ser configurados sob o mesmo provedor. O custo é que algumas capacidades exclusivas da Anthropic (como extended thinking ou blocos de tool use nativos) passarão por uma conversão de protocolo, podendo haver pequenas diferenças de comportamento em relação ao endpoint oficial da Anthropic.
Modo 2: Nativo da Anthropic (Recomendado para Claude)
O provedor anthropic embutido no OpenCode utiliza o pacote @ai-sdk/anthropic, com o caminho de requisição /v1/messages e o formato de corpo de requisição definido pela API de Mensagens da Anthropic. Este formato suporta blocos de conteúdo, blocos de tool_use, extended thinking e outros recursos do Claude, utilizando exatamente o mesmo protocolo do Claude Code.
Ao apontar provider.anthropic.options.baseURL para https://api.apiyi.com da APIYI, o OpenCode enviará requisições no formato nativo da Anthropic, que serão encaminhadas pelo serviço proxy da APIYI para o Claude. Isso significa que você pode obter uma experiência de invocação do Claude no OpenCode quase idêntica à do Claude Code.
| Modo | Pacote Base | Base URL da APIYI | Ideal para | Fidelidade de Protocolo |
|---|---|---|---|---|
| Compatível OpenAI | @ai-sdk/openai-compatible |
https://api.apiyi.com/v1 |
Mix de modelos | Padrão OpenAI |
| Nativo Anthropic | @ai-sdk/anthropic |
https://api.apiyi.com |
Toda a linha Claude | Idêntico ao oficial |
🎯 Sugestão de configuração: Para o uso diário, recomendamos a coexistência de ambos os modos — configure o provedor
anthropice um provedoropenai-compatibleno mesmoopencode.json. O primeiro para o Claude e o segundo para GPT/Gemini/DeepSeek, etc. Ambos os provedores podem compartilhar a mesma chave da APIYI (apiyi.com), sem a necessidade de gerenciar chaves repetidamente.
3 passos para configurar o OpenCode com o serviço proxy de API da APIYI
Abaixo, apresento o fluxo mínimo para colocar tudo em funcionamento. O processo completo leva menos de 5 minutos.
Passo 1: Instalar o cliente OpenCode
Existem duas formas principais de instalação oficial; escolha a que melhor se adapta ao seu ambiente.
# Opção A: Instalação global via npm (recomendado para usuários de Node.js)
npm install -g opencode-ai@latest
# Opção B: Instalação via script (recomendado para macOS / Linux)
curl -fsSL https://opencode.ai/install | bash
Após a instalação, execute opencode --version para verificar. Usuários de Windows podem utilizar via Scoop ou WSL. Se a instalação via npm falhar, provavelmente é devido a uma versão do Node muito antiga; recomenda-se atualizar para a 18+ ou 20+.
Passo 2: Obter a chave API no painel da APIYI
Acesse o painel da APIYI, vá até a página de gerenciamento de tokens em api.apiyi.com/token e crie uma nova chave. Recomendo nomeá-la como OpenCode e selecionar o grupo correspondente (se precisar usar o Claude, certifique-se de que o grupo inclui os modelos da série Claude). Copie a string sk-xxx gerada; você precisará dela no próximo passo.
🎯 Dica sobre tokens: Após registrar-se na APIYI (apiyi.com), recomendo criar um token separado para cada cliente, por exemplo: um para o ClaudeCode, um para o OpenCode e outro para o Cursor. Assim, se uma das pontas apresentar comportamento estranho, basta revogar o token específico sem afetar os outros clientes.
Passo 3: Editar o arquivo de configuração opencode.json
O OpenCode lê prioritariamente o arquivo opencode.json na raiz do projeto; caso não encontre, ele busca a configuração do usuário em ~/.config/opencode/opencode.json. Abaixo, apresento um exemplo completo que combina o modo nativo da Anthropic com o modo compatível com OpenAI:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://api.apiyi.com",
"apiKey": "{env:APIYI_KEY}"
}
},
"apiyi-openai": {
"npm": "@ai-sdk/openai-compatible",
"name": "APIYI OpenAI Compatível",
"options": {
"baseURL": "https://api.apiyi.com/v1",
"apiKey": "{env:APIYI_KEY}"
},
"models": {
"gpt-4o": { "name": "GPT-4o" },
"claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
"gemini-2.5-pro": { "name": "Gemini 2.5 Pro" }
}
}
}
}
Em seguida, adicione o token às suas variáveis de ambiente:
# macOS / Linux
echo 'export APIYI_KEY="sk-seu-token-obtido-no-painel-da-APIYI"' >> ~/.zshrc
source ~/.zshrc
# Windows PowerShell
$env:APIYI_KEY = "sk-seu-token-obtido-no-painel-da-APIYI"
Após iniciar o OpenCode, use o comando /models para selecionar o modelo. Para a série Claude, recomendo usar o provedor anthropic; para outros modelos, utilize o provedor apiyi-openai.
🎯 Regra da base URL: No modo nativo da Anthropic, não adicione
/v1, pois o SDK adicionará automaticamente/v1/messages. No modo compatível com OpenAI, é obrigatório adicionar/v1. Essa regra é idêntica à orientação fornecida pela APIYI (apiyi.com) na documentação do Claude Code. Lembre-se: "nativo não adiciona, compatível adiciona".
Solução de problemas comuns
| Erro | Causa provável | Solução |
|---|---|---|
Route /api/messages not found |
baseURL configurada com /v1 |
Remova o sufixo /v1 |
Required provider.anthropic.models |
Campo models ausente após definir baseURL | Liste explicitamente os IDs dos modelos |
401 Unauthorized |
Token inválido ou grupo sem acesso ao modelo | Gere um novo token na APIYI |
model not found |
ID do modelo diferente do painel da APIYI | Verifique o ID real no catálogo da APIYI |
| Timeout na requisição | Instabilidade na rede ou limite de taxa | Troque o nó da APIYI ou tente novamente |
🎯 Dica de diagnóstico: Ao encontrar qualquer erro, recomendo usar
curl https://api.apiyi.com/v1/models -H "Authorization: Bearer $APIYI_KEY"para verificar a validade do token e a conectividade. Este passo localiza 90% dos problemas em 30 segundos, sendo muito mais rápido do que editar oopencode.jsonrepetidamente. Se a lista retornar normalmente, o problema provavelmente está na camada de configuração do OpenCode.
Cenários de uso prático do OpenCode com o serviço proxy da APIYI
Após configurar, o que define a experiência de uso é o fluxo de trabalho. Abaixo, listo os cenários mais comuns.
Cenário 1: Revisão de código sem efeitos colaterais no modo "plan"
Mude para o modo plan (pressione a tecla Tab) e digite /interprete o fluxo de autenticação deste repositório. O OpenCode analisará o código e gerará um relatório sem alterar nenhum arquivo. Este uso é ideal para integrar novos colegas, realizar revisões de segurança ou organizar a arquitetura de códigos legados.
Cenário 2: Desenvolvimento ponta a ponta no modo "build"
Após confirmar o plano, mude para o modo build e execute tarefas como altere o middleware de autenticação para uma implementação baseada em JWT e adicione testes unitários. O OpenCode lerá automaticamente os arquivos relevantes, fará as alterações, executará os testes e iterará conforme necessário. Recomendo executar em uma branch limpa do git para facilitar o rollback.
Cenário 3: Colaboração entre modelos e controle de custos
Utilizando a abstração de provedores do OpenCode, você pode delegar tarefas diferentes para modelos distintos. Por exemplo:
- Documentação e mensagens de commit: use
gpt-4o-miniviaapiyi-openai(custo baixíssimo). - Refatoração complexa e revisão de código: use
claude-sonnet-4-6ou a série Opus via provedoranthropic. - Conteúdo multilíngue/visual: use
gemini-2.5-proviaapiyi-openai.
🎯 Dica de custo: Ao utilizar a APIYI (apiyi.com), todos os modelos são cobrados pelo uso real de tokens, sem valor mínimo. Recomendo testar o fluxo com modelos mais baratos e, após validar o resultado, mudar para modelos mais potentes, otimizando seu orçamento.
Cenário 4: Integração CI/CD em modo não interativo
O comando opencode run permite inserir o comando diretamente no shell, retornando a saída via stdout, o que facilita a integração com GitHub Actions, GitLab CI ou tarefas agendadas. Por exemplo, você pode executar automaticamente uma revisão da estrutura do repositório semanalmente ou gerar um rascunho de changelog antes de realizar o merge de um PR.
Perguntas Frequentes (FAQ)
P1: O OpenCode realmente suporta o protocolo nativo /v1/messages da Anthropic?
Sim, suporta. O provedor anthropic integrado ao OpenCode utiliza o pacote @ai-sdk/anthropic. O caminho da requisição é o /v1/messages oficial da Anthropic e o corpo da requisição segue o formato oficial da API Messages, utilizando o mesmo protocolo do Claude Code. Basta apontar o baseURL para o APIYI (apiyi.com) para obter no OpenCode uma experiência quase idêntica à do Claude Code.
P2: Se eu usar apenas o modo compatível com OpenAI, quais capacidades do Claude perderei?
No modo compatível com OpenAI, recursos exclusivos da Anthropic, como blocos de tool_use, extended thinking e cabeçalhos de controle de cache, serão adaptados pela camada de protocolo. Embora funcionem, o formato da resposta é convertido, e alguns comportamentos granulares (como a cobrança de tokens de raciocínio ou motivos específicos de parada) podem diferir ligeiramente do modo nativo. Para o desenvolvimento principal com Claude, recomendamos o uso do modo nativo.
P3: O arquivo de configuração do OpenCode suporta ${env:VAR} ou {env:VAR}?
A versão mais recente utiliza a sintaxe {env:VAR}. Versões antigas utilizavam ${env:VAR}. Se o OpenCode retornar um erro de apiKey is undefined, verifique se você escreveu ${env:APIYI_KEY} e altere para {env:APIYI_KEY} conforme a especificação atual.
P4: O comando /connect nativo do OpenCode pode se conectar diretamente ao APIYI?
Sim. Ao executar /connect, selecione "Other", insira o ID do provedor (como apiyi-openai) e cole o seu token APIYI; o OpenCode escreverá automaticamente no opencode.json. No entanto, o /connect utiliza o caminho compatível com OpenAI por padrão. Se você deseja utilizar o modo nativo da Anthropic, recomendamos editar manualmente o provider.anthropic.options.baseURL.
P5: É possível fazer com que o Claude Code e o OpenCode compartilhem a mesma chave API do APIYI?
Com certeza, e é altamente recomendável. O token do APIYI (apiyi.com) não está vinculado a um cliente específico. O mesmo token sk-xxx pode ser usado simultaneamente pelo Claude Code (via ANTHROPIC_BASE_URL), OpenCode (via opencode.json), Cursor, Continue e outros clientes. Você pode visualizar o faturamento consolidado no painel de controle de acordo com a origem da invocação.
P6: O modo plan/build do OpenCode é a mesma coisa que a confirmação de permissões do Claude Code?
Os objetivos de design são semelhantes, mas os caminhos de implementação são diferentes. O Claude Code solicita confirmação a cada passo, perguntando antes de cada escrita de arquivo ou execução de comando. O OpenCode utiliza a troca de modos: o modo plan bloqueia fundamentalmente as permissões de escrita, enquanto o modo build as libera por padrão. A abordagem do OpenCode é mais adequada para cenários de automação, enquanto o Claude Code é ideal para cenários que exigem controle passo a passo.
P7: A latência de invocação do Claude através do serviço proxy de API do APIYI é maior do que a conexão direta oficial?
O APIYI (apiyi.com) possui pontos de entrada implantados em vários nós centrais na China e otimizou a conexão para os principais modelos como Claude, GPT e Gemini. Para usuários locais, a latência do primeiro byte (TTFB) costuma ser significativamente menor do que a conexão direta com os endpoints oficiais. Você pode comparar os números reais no seu ambiente de rede usando curl -w "%{time_starttransfer}".
Conclusão: A melhor combinação de práticas com OpenCode + APIYI
O verdadeiro valor do OpenCode reside em devolver ao desenvolvedor o "poder de escolha do modelo", e serviços proxy de API como o APIYI fornecem a base necessária para que essa flexibilidade seja aplicada na prática. Com essa combinação, o desenvolvedor desfruta de uma experiência Claude próxima à do Claude Code no terminal, podendo alternar facilmente para modelos como GPT, Gemini ou DeepSeek para validação cruzada. Todo o fluxo de trabalho exige apenas o gerenciamento de um arquivo de configuração do OpenCode e uma única chave API do APIYI.
Voltando à pergunta inicial deste artigo: o OpenCode suporta simultaneamente o modo compatível com OpenAI e o formato nativo da Anthropic, e eles não são excludentes. Recomendamos que usuários de longo prazo mantenham ambos os provedores no opencode.json: o Claude via caminho nativo para preservar todas as capacidades, e outros modelos via caminho compatível para maximizar a versatilidade.
🎯 Dica final: Se você está pensando em experimentar o OpenCode, a maneira mais fácil de começar é registrar-se no APIYI (apiyi.com), criar uma chave API e configurar ambos os modos conforme este artigo. Em uma semana, você verá que não consegue mais viver sem a praticidade de "usar uma única chave para todos os modelos", sem precisar manter contas e saldos separados para cada provedor.
— Equipe Técnica APIYI | Acompanhando o ecossistema de agentes de codificação de IA. Mais tutoriais na central de ajuda do APIYI (apiyi.com).
