3 passos para configurar o OpenCode no intermediário de API e desbloquear a troca livre entre mais de 400 modelos de IA

Quer usar o OpenCode, esse assistente de programação de IA de código aberto, mas sofre com os preços altos da API oficial ou com a instabilidade da rede? Um hub de API é a sua melhor solução. Este artigo vai te ensinar o passo a passo de como concluir a integração do OpenCode com o APIYI, OpenRouter e outros serviços de proxy em apenas 3 etapas, permitindo que você acesse mais de 75 modelos de IA populares, como Claude, GPT-4 e Gemini, com um custo muito menor.

Valor central: Ao ler este artigo, você aprenderá a configurar o OpenCode para usar qualquer API compatível com OpenAI, alcançando liberdade de escolha de modelos e otimização de custos.

O que é o OpenCode? Por que conectar a um Hub de API?

O OpenCode é um assistente de programação de IA para terminal, de código aberto, conhecido como a alternativa open-source ao Claude Code. Desenvolvido em Go, ele oferece uma interface TUI elegante, gerenciamento de múltiplas sessões, integração LSP e outras funcionalidades profissionais.

Visão geral das funcionalidades principais do OpenCode

Por que usar um Hub de API?

O uso direto das APIs oficiais pode apresentar os seguintes problemas:

🚀 Início Rápido: Recomenda-se o uso do APIYI apiyi.com como Hub, que oferece uma interface compatível com OpenAI pronta para uso. Ganhe crédito de teste gratuito ao se registrar e conclua a configuração do OpenCode em 5 minutos.

Pontos principais para conectar o OpenCode a um serviço de API intermediário

Antes de iniciar a configuração, entenda o princípio de conexão de API do OpenCode:

Descrição da Arquitetura de Configuração

O OpenCode utiliza um sistema unificado de gerenciamento de configurações, suportando múltiplas camadas de sobreposição:

Princípio de Conexão ao Relay de API

O OpenCode suporta qualquer API compatível com OpenAI através do adaptador @ai-sdk/openai-compatible. Os itens de configuração cruciais são:

• baseURL: O endereço da interface do relay de API.
• apiKey: A chave de API fornecida pelo relay.
• models: Lista de modelos disponíveis.

Isso significa que, desde que o hub forneça uma interface padrão /v1/chat/completions, ele poderá ser conectado diretamente ao OpenCode.

Configuração Rápida do OpenCode

Passo 1: Instalar o OpenCode

O OpenCode oferece várias formas de instalação, escolha a que melhor se adapta a você:

Script de instalação em um clique (Recomendado):

curl -fsSL https://opencode.ai/install | bash

Instalação via Homebrew (macOS/Linux):

brew install opencode-ai/tap/opencode

Instalação via npm:

npm i -g opencode-ai@latest

Instalação via Go:

go install github.com/opencode-ai/opencode@latest

Verifique se a instalação foi bem-sucedida:

opencode --version

Passo 2: Configurar a Chave do Relay de API

O OpenCode suporta dois métodos de autenticação:

Método 1: Usando o comando /connect (Recomendado)

Após iniciar o OpenCode, digite o comando /connect:

opencode
# Digite na interface TUI
/connect

Selecione Other para adicionar um Provider personalizado e insira sua chave de API. A chave será armazenada com segurança em ~/.local/share/opencode/auth.json.

Método 2: Configuração via Variáveis de Ambiente

Adicione ao seu ~/.zshrc ou ~/.bashrc:

# Configuração do relay APIYI
export OPENAI_API_KEY="sk-your-apiyi-key"
export OPENAI_BASE_URL="https://api.apiyi.com/v1"

Aplique a configuração:

source ~/.zshrc

Passo 3: Criar o arquivo de configuração opencode.json

Este é o passo mais importante: criar o arquivo de configuração para especificar o relay de API:

Configuração Global (aplica-se a todos os projetos):

mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json

Configuração do Projeto (aplica-se apenas ao projeto atual):

touch opencode.json  # Na raiz do projeto

Exemplo de Configuração Minimalista

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apiyi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "APIYI",
      "options": {
        "baseURL": "https://api.apiyi.com/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4"
        },
        "gpt-4o": {
          "name": "GPT-4o"
        }
      }
    }
  },
  "model": "apiyi/claude-sonnet-4-20250514"
}

Nota de configuração: A sintaxe {env:OPENAI_API_KEY} lerá automaticamente a variável de ambiente, evitando o hardcoding da chave no arquivo. As chaves obtidas via APIYI (apiyi.com) são compatíveis com o formato da OpenAI e podem ser usadas diretamente.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apiyi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "APIYI (Recomendado)",
      "options": {
        "baseURL": "https://api.apiyi.com/v1",
        "apiKey": "{env:APIYI_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
          "limit": {
            "context": 200000,
            "output": 65536
          }
        },
        "claude-opus-4-20250514": {
          "name": "Claude Opus 4",
          "limit": {
            "context": 200000,
            "output": 32000
          }
        },
        "gpt-4o": {
          "name": "GPT-4o",
          "limit": {
            "context": 128000,
            "output": 16384
          }
        },
        "gpt-4o-mini": {
          "name": "GPT-4o Mini",
          "limit": {
            "context": 128000,
            "output": 16384
          }
        },
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro",
          "limit": {
            "context": 1000000,
            "output": 65536
          }
        },
        "deepseek-chat": {
          "name": "DeepSeek V3",
          "limit": {
            "context": 64000,
            "output": 8192
          }
        }
      }
    },
    "openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenRouter",
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "{env:OPENROUTER_API_KEY}",
        "headers": {
          "HTTP-Referer": "https://your-site.com",
          "X-Title": "OpenCode Client"
        }
      },
      "models": {
        "anthropic/claude-sonnet-4": {
          "name": "Claude Sonnet 4 (OpenRouter)"
        },
        "openai/gpt-4o": {
          "name": "GPT-4o (OpenRouter)"
        }
      }
    }
  },
  "model": "apiyi/claude-sonnet-4-20250514",
  "small_model": "apiyi/gpt-4o-mini",
  "agent": {
    "coder": {
      "model": "apiyi/claude-sonnet-4-20250514",
      "maxTokens": 8000
    },
    "planner": {
      "model": "apiyi/gpt-4o",
      "maxTokens": 4000
    }
  },
  "tools": {
    "write": true,
    "bash": true,
    "glob": true,
    "grep": true
  }
}

Comparativo de Gateways de API suportados pelo OpenCode

Parâmetros de Configuração dos Principais Gateways de API

Detalhes da Configuração APIYI

A APIYI é uma plataforma de gateway de API de IA otimizada para desenvolvedores que buscam eficiência, oferecendo:

• Interface unificada compatível com OpenAI
• Suporte para Claude, GPT, Gemini, DeepSeek e outros modelos principais
• Pagamento por uso (pay-as-you-go), sem mensalidades
• Créditos de teste gratuitos
• Suporte técnico ágil

{
  "provider": {
    "apiyi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "APIYI",
      "options": {
        "baseURL": "https://api.apiyi.com/v1"
      },
      "models": {
        "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
        "claude-opus-4-20250514": { "name": "Claude Opus 4" },
        "gpt-4o": { "name": "GPT-4o" },
        "gpt-4o-mini": { "name": "GPT-4o Mini" },
        "gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
        "deepseek-chat": { "name": "DeepSeek V3" }
      }
    }
  }
}

Detalhes da Configuração OpenRouter

O OpenRouter agrega mais de 400 modelos de IA, sendo ideal para quem precisa experimentar ou trocar de modelo com frequência:

{
  "provider": {
    "openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenRouter",
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "{env:OPENROUTER_API_KEY}",
        "headers": {
          "HTTP-Referer": "https://your-app.com",
          "X-Title": "My OpenCode App"
        }
      },
      "models": {
        "anthropic/claude-sonnet-4": {
          "name": "Claude Sonnet 4"
        },
        "google/gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro"
        },
        "meta-llama/llama-3.1-405b": {
          "name": "Llama 3.1 405B"
        }
      }
    }
  }
}

💡 Dica de Escolha: Se você usa principalmente os modelos das séries Claude e GPT, recomendamos a APIYI (apiyi.com) pela economia e velocidade de resposta. Se precisar de modelos de código aberto específicos ou modelos de nicho, o OpenRouter oferece a maior cobertura.

Dicas de Configuração Avançada do OpenCode

Estratégia de Alocação de Modelos para Agents

O OpenCode possui dois Agents integrados, o Coder e o Planner. Você pode atribuir modelos diferentes para cada um deles:

{
  "agent": {
    "coder": {
      "model": "apiyi/claude-sonnet-4-20250514",
      "maxTokens": 8000,
      "description": "Tarefas principais de codificação, utiliza um modelo robusto"
    },
    "planner": {
      "model": "apiyi/gpt-4o-mini",
      "maxTokens": 4000,
      "description": "Planejamento e análise, utiliza um modelo leve para economizar custos"
    }
  }
}

Alternando entre Múltiplos Provedores

Após configurar vários Provedores (Providers), você pode usar o comando /models no OpenCode para alternar entre eles a qualquer momento:

# Iniciar o OpenCode
opencode

# Alternar modelos na TUI (Interface de Usuário de Terminal)
/models
# Selecione apiyi/claude-sonnet-4-20250514 ou outro modelo

Melhores Práticas para Variáveis de Ambiente

Recomendamos gerenciar suas chaves de API em um arquivo .env:

# Arquivo .env
APIYI_API_KEY=sua-chave-apiyi
OPENROUTER_API_KEY=sua-chave-openrouter

Em seguida, faça a referência no seu opencode.json:

{
  "provider": {
    "apiyi": {
      "options": {
        "apiKey": "{env:APIYI_API_KEY}"
      }
    }
  }
}

Configuração de Limite de Tokens

Especifique os limites de contexto e de saída para o modelo para evitar erros de estouro de limite:

{
  "models": {
    "claude-sonnet-4-20250514": {
      "name": "Claude Sonnet 4",
      "limit": {
        "context": 200000,
        "output": 65536
      }
    }
  }
}

Resolução de Problemas Comuns do OpenCode

Confira os problemas que podem surgir durante a configuração e como resolvê-los:

"baseURL": "https://api.apiyi.com/v1"

"baseURL": "https://api.apiyi.com/v1/chat/completions"

{
  "provider": {
    "apiyi": {
      "models": {
        "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" }
      }
    }
  },
  "model": "apiyi/claude-sonnet-4-20250514"
}

# Ver as informações de autenticação configuradas
opencode auth list

# Ver os modelos disponíveis
opencode
/models

# Testar uma conversa simples
opencode -p "Olá, por favor responda em português"

opencode
/models
# Basta selecionar o modelo de um Provedor diferente para alternar

{
  "model": "apiyi/claude-sonnet-4-20250514"
}

OpenCode vs Claude Code: Comparação de Métodos de Integração de API

🎯 Sugestão técnica: A maior vantagem do OpenCode é a flexibilidade de modelos. Ao utilizá-lo com o gateway da APIYI (apiyi.com), você pode usar a mesma configuração para alternar entre diversos modelos como Claude, GPT-4, Gemini e outros, encontrando a melhor relação custo-benefício para o seu projeto.

Referências

Aqui estão alguns recursos que podem ser úteis ao configurar o OpenCode:

Resumo

Com o método de configuração de 3 etapas deste artigo, você aprendeu a:

1. Instalar o OpenCode: use scripts de comando único ou gerenciadores de pacotes para uma instalação rápida.
2. Configurar a chave de API: defina a autenticação através do comando /connect ou de variáveis de ambiente.
3. Criar o arquivo de configuração: escreva o arquivo opencode.json para especificar o gateway e o modelo desejado.

O OpenCode, como um assistente de programação por IA de código aberto para terminal, oferece uma experiência comparável ao Claude Code quando utilizado com um gateway de API, mantendo os custos controlados e a flexibilidade de escolha entre diferentes modelos.

Recomendamos utilizar o APIYI (apiyi.com) para obter rapidamente sua chave de API e começar os testes. A plataforma oferece cotas gratuitas e suporte aos principais modelos do mercado, como Claude, GPT e Gemini, com um formato de interface unificado que torna a configuração muito mais simples.

📝 Autor: Equipe Técnica APIYI | APIYI (apiyi.com) – Facilitando a chamada de APIs de IA.