Configuração do provedor compatível com OpenAI do OpenCode: Roteie modelos de agente de codificação através do Flatkey

Uma configuração de provedor compatível com OpenAI do OpenCode é útil quando você deseja que o OpenCode se comunique com uma rota de modelo que se comporta como a API de Conclusões de Chat da OpenAI, enquanto sua equipe mantém a propriedade da chave, o roteamento de modelos e a revisão de uso em um único gateway.

A parte importante é que o OpenCode tem um caminho documentado para provedor personalizado. Na documentação do provedor OpenCode, verificada em 8 de julho de 2026, o fluxo é: adicionar uma credencial com /connect, escolher Outro para um provedor que ainda não está listado, dar a esse provedor um ID memorável, configurar o provedor em opencode.json e, em seguida, executar /models para selecionar entre os modelos configurados.

O Flatkey se encaixa nesse padrão como o gateway por trás do provedor. Você mantém o OpenCode como o agente de codificação, aponta o provedor para a URL base da API compatível com OpenAI do Flatkey e verifica se o tráfego do modelo OpenCode aparece nos logs de uso ou de solicitação do Flatkey antes de torná-lo a rota padrão.

Resposta rápida para a configuração do provedor compatível com OpenAI do OpenCode

Use este formato de configuração quando o endpoint do modelo for compatível com Conclusões de Chat.

Este guia do provedor compatível com OpenAI do OpenCode usa modelos. Valide os aliases de modelo exatos e a família de endpoints em sua conta Flatkey antes de rotear o trabalho do agente de codificação de produção.

O que o OpenCode exige

O OpenCode tem dois estados separados para um provedor personalizado.

A configuração do OpenCode pode ser JSON ou JSONC. Você pode colocá-la globalmente em ~/.config/opencode/opencode.json ou na raiz de um projeto como opencode.json. A configuração do projeto tem precedência padrão mais alta, então use um arquivo de projeto quando quiser que um repositório teste o Flatkey sem alterar todos os workspaces do OpenCode.

Passo 1: Crie uma chave Flatkey para o OpenCode

Crie uma chave Flatkey para esta carga de trabalho e registre três valores fora do controle de versão.

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias

Mantenha a raiz da API separada do caminho do endpoint. A configuração do provedor OpenCode deve usar https://router.flatkey.ai/v1 como options.baseURL; testes de fumaça HTTP diretos adicionam /chat/completions.

Antes de conectar o OpenCode, execute um teste direto com a mesma chave Flatkey e o mesmo alias de modelo.

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      { "role": "user", "content": "Responda com exatamente: rota flatkey ok" }
    ]
  }'

Se esta solicitação direta falhar, corrija a chave Flatkey, o alias do modelo, a família de endpoints ou a rota da conta antes de depurar o OpenCode. Um provedor compatível com OpenAI do OpenCode não pode compensar um alias de modelo que a conta do gateway não pode chamar.

Passo 2: Adicione a credencial Flatkey no OpenCode

O OpenCode armazena as credenciais do provedor através de /connect. Na TUI do OpenCode:

/connect

Escolha Outro, insira um ID de provedor como flatkey e, em seguida, cole a chave de API do Flatkey. Não cole a URL base no prompt de credencial. A chave prova a identidade; a URL base pertence ao opencode.json.

Use um ID de provedor simples. flatkey é melhor do que flatkey-prod-openai-compatible-gateway-v2 porque você o digitará em IDs de modelo e notas de reversão.

Passo 3: Adicionar a configuração do provedor OpenCode

Crie ou atualize o opencode.json na raiz do projeto que você deseja testar.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "your-current-flatkey-model-alias": {
          "name": "Flatkey primary model"
        }
      }
    }
  },
  "model": "flatkey/your-current-flatkey-model-alias"
}

Esta é a menor configuração de provedor compatível com OpenAI do OpenCode. Ela fornece ao OpenCode um provedor chamado flatkey, instrui o OpenCode a usar o pacote AI SDK compatível com OpenAI e expõe um alias de modelo no seletor de modelos.

Se você quiser que o OpenCode use uma rota menor para trabalhos leves, adicione small_model somente depois que a rota principal funcionar.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "primary-flatkey-model-alias": {
          "name": "Flatkey primary"
        },
        "lighter-flatkey-model-alias": {
          "name": "Flatkey lightweight"
        }
      }
    }
  },
  "model": "flatkey/primary-flatkey-model-alias",
  "small_model": "flatkey/lighter-flatkey-model-alias"
}

Use os aliases de modelo que sua chave Flatkey pode realmente chamar. Se sua conta expõe uma rota /v1/models autenticada, compare os IDs de modelo configurados com essa resposta. Caso contrário, copie os aliases do painel atual do Flatkey ou do diretório de modelos e verifique-os com uma solicitação real.

Passo 4: Selecionar e testar o modelo no OpenCode

Após salvar a configuração, abra o seletor de modelos.

/models

Selecione o modelo do provedor Flatkey. Em seguida, execute um pequeno prompt no OpenCode:

Reply with exactly: opencode flatkey route ok

Ainda não mova um fluxo de trabalho de codificação inteiro. Primeiro, salve um pacote de verificação compacto.

Isso transforma uma migração de provedor compatível com OpenAI do OpenCode em uma pequena mudança operacional, em vez de uma troca cega de provedor.

Passo 5: Manter as Conclusões de Chat e as Respostas separadas

Os documentos de provedor personalizado do OpenCode destacam um limite de pacote: use @ai-sdk/openai-compatible para provedores compatíveis com OpenAI que usam /v1/chat/completions; se um provedor ou modelo usar /v1/responses, use @ai-sdk/openai.

Isso significa que a primeira rota do Flatkey deve ser um modelo no estilo de Conclusões de Chat, a menos que você tenha evidências atuais de que o modelo selecionado e o caminho do cliente usam uma família de endpoints diferente.

Use esta tabela de decisão antes de adicionar mais modelos.

Para a maioria dos trabalhos de configuração, comece com uma rota de Conclusões de Chat. Adicione streaming, chamadas de ferramentas e aliases de modelo secundários depois que o primeiro teste de fumaça do provedor compatível com OpenAI do OpenCode estiver visível no Flatkey.

Passo 6: Adicionar controles de equipe depois que a rota funcionar

Assim que o OpenCode puder chamar o Flatkey, torne a rota observável.

É aqui que o Flatkey se torna mais do que um URL base. Um provedor compatível com OpenAI do OpenCode funcional também deve fornecer às equipes de plataforma, finanças e operações um local para revisar o uso do modelo e alterar a rota sem pedir a cada desenvolvedor para gerenciar contas de provedor separadas.

Para um planejamento de migração mais amplo, combine este guia com o guia de migração de API compatível com OpenAI do Flatkey. Se você estiver comparando ferramentas de codificação adjacentes, consulte o guia do provedor compatível com OpenAI do Continue.dev e o guia de configuração compatível com OpenAI do Roo Code.

Solução de problemas de um provedor compatível com OpenAI do OpenCode

Se a primeira solicitação falhar, não altere prompts, agentes, permissões ou código do repositório ainda. Mantenha a superfície de depuração do provedor compatível com OpenAI do OpenCode pequena: credencial, ID do provedor, URL base, pacote, alias do modelo e uma solicitação de chat simples.

Lista de verificação final

Antes de usar o Flatkey como a rota padrão do OpenCode, confirme:

1. /connect tem uma credencial Flatkey sob o mesmo ID de provedor usado em opencode.json.
2. provider.flatkey.npm é @ai-sdk/openai-compatible para a rota de Chat Completions.
3. provider.flatkey.options.baseURL é https://router.flatkey.ai/v1.
4. model aponta para um valor flatkey/<model-alias> configurado.
5. /models mostra o modelo Flatkey configurado.
6. Um prompt de uma linha do OpenCode retorna com sucesso.
7. Os logs de uso ou solicitação do Flatkey mostram a solicitação de teste do OpenCode.
8. A rota anterior do provedor/modelo está documentada para reversão.

Uma configuração de provedor compatível com OpenAI do OpenCode está completa quando o provedor está configurado, selecionável, verificado nos logs do Flatkey e reversível. Quando estiver pronto para rotear o tráfego do modelo de agente de codificação através de uma única chave, obtenha uma chave Flatkey e comece com um único prompt de baixo risco do OpenCode.