Como usar Gemini 4 Hydrogen no Cline e no OpenCode

Para usar o Hydrogen pela Ofox, escolha um provedor compatível com OpenAI, defina a Base URL como https://api.ofox.io/v1 e envie o ID de modelo google/gemini-4-hydrogen. No Cline CLI, configure esse provedor diretamente. No OpenCode V2, declare um provedor e um modelo personalizados antes de selecioná-los. Receber uma resposta de texto é apenas a primeira verificação: um cliente de programação também precisa receber uma chamada de ferramenta, ler um arquivo e devolver o resultado ao modelo.

Este guia cobre o Cline CLI 3.0.74 e o OpenCode V2 2.3.0, verificados em 13 de novembro de 2026. Ele separa as credenciais nativas do Google das credenciais da Ofox e propõe uma pequena tarefa de leitura antes de conectar um repositório real. A extensão do Cline para o editor tem versão e interface próprias; os comandos de CLI aqui não são instruções para todas as versões da extensão.

A Ofox publica este guia. Executamos os clientes lançados oficialmente contra um servidor local que fornecia respostas sintéticas em streaming. Ambos realmente leram o arquivo de teste e devolveram seu conteúdo. Não executamos uma requisição paga ao Hydrogen, não validamos a conta de um cliente nem medimos qualidade ou velocidade do modelo. O teste com o serviço real, descrito abaixo, deve ser executado na sua conta para confirmar o funcionamento completo da rota escolhida. Os links para a documentação original de OpenCode, Cline e Google estão em inglês.

Escolha provedor, chave e modelo como uma configuração única

Não misture o nome de modelo do Google com um provedor Ofox nem insira uma chave Ofox no provedor Google. Um alias local de modelo também é diferente do ID enviado pela rede.

A recomendação do Google de usar Interactions em novas integrações não significa que o provedor Google de um cliente de programação existente utilize essa API automaticamente. Não cole um endpoint de Interactions no campo Base URL de um provedor compatível com OpenAI. O guia de configuração da API Hydrogen explica os diferentes formatos de requisição e resposta.

O catálogo Ofox verificado para este artigo lista suporte aos protocolos OpenAI e Gemini para o Hydrogen e um endpoint de Chat Completions. Essa informação identifica uma rota de integração, mas não comprova, por si só, todos os recursos do cliente, o comportamento das ferramentas no fornecedor ou a cota de uma conta específica. Para obter e usar a chave Ofox, siga as instruções de autenticação da API. Consulte os campos de mensagens, streaming e ferramentas na documentação de Chat Completions.

Instale a versão correta e prepare um projeto pequeno

O nome do pacote OpenCode importa. O guia oficial de instalação atual usa @opencode/cli para instalar a V2. O pacote antigo opencode-ai é a V1. Ambos oferecem o comando opencode, portanto o nome do comando não identifica qual sintaxe de configuração você deve usar.

Para instalar exatamente as versões verificadas aqui:

npm install -g cline@3.0.74
npm install -g @opencode/cli@2.3.0
cline --version
opencode --version

Confira os requisitos oficiais de instalação para o seu sistema operacional. Fixar as versões serve para reproduzir os passos, não para garantir que continuem sendo as mais recentes. Se você já usa OpenCode V1, leia o guia de migração de V1 para V2 antes de alterar a instalação global. A V2 pode substituir o comando utilizado no seu fluxo atual.

Documentação oficial em inglês capturada em 13 de novembro de 2026. A imagem registra a diferença entre versões, não um teste do modelo Hydrogen. Página original de migração.

Crie um diretório separado para o primeiro teste de ferramenta. Definir uma raiz Git própria também torna explícito o limite do projeto quando o cliente procura configurações.

mkdir hydrogen-client-check
cd hydrogen-client-check
git init
printf 'Local test marker: HYDROGEN_CLIENT_CHECK_20261113\n' > fixture.txt

Comece com um projeto que contenha apenas esse arquivo de teste. O objetivo é observar uma leitura, não revisar um repositório grande nem aprovar uma longa sequência de alterações. Não coloque a chave em opencode.json nem no controle de versão: o exemplo do OpenCode a lê de OFOX_API_KEY. Defina a variável pelo seu processo habitual de gerenciamento local de segredos. Não faça commit de um arquivo de ambiente preenchido.

Configure o Hydrogen no Cline CLI

A referência do Cline CLI documenta a autenticação de provedores e a seleção de modelos personalizados. Para a rota Ofox, configure o provedor compatível com OpenAI com a Base URL e o ID exatos:

cline auth -p openai \
  -b https://api.ofox.io/v1 \
  -m google/gemini-4-hydrogen \
  -k "$OFOX_API_KEY" \
  --data-dir "$PWD/.cline-hydrogen"

openai é o argumento de provedor da CLI utilizado no teste; o provedor salvo foi normalizado para openai-compatible. O diretório de dados separado isola o estado deste teste do estado normal da sua CLI. Trate esse diretório como configuração local privada e exclua-o do controle de versão. O comando passa credenciais ao cliente: não copie os argumentos depois da expansão das variáveis para logs ou capturas de tela. O Cline também oferece autenticação interativa, caso seja mais adequada ao seu ambiente.

A Base URL termina em /v1. Não acrescente /chat/completions: o provedor monta o caminho da requisição. Nas capturas locais, ele adicionou /chat/completions e enviou exatamente a string de modelo configurada.

Para usar a rota nativa do Google, configure uma chave Google e o ID nativo em outro diretório de dados:

cline auth -p gemini \
  -m gemini-4-hydrogen \
  -k "$GEMINI_API_KEY" \
  --data-dir "$PWD/.cline-google-hydrogen"

Não adicione a Base URL da Ofox a esse comando. Na nossa verificação, o Cline CLI 3.0.74 recusou uma Base URL personalizada para gemini. Salvar a configuração nativa com uma chave fictícia funcionou, mas isso prova somente que a CLI aceita a configuração, não que a chave é válida ou que o projeto tem acesso ao Hydrogen. Se a primeira chamada nativa falhar, verifique a cota e os requisitos de verificação do projeto Google no guia de acesso ao Hydrogen.

Agora inicie o teste Ofox no diretório do arquivo:

cline --data-dir "$PWD/.cline-hydrogen" \
  --auto-approve false \
  "Read fixture.txt using a file tool. Return its exact marker. Do not modify files or run shell commands."

Quando houver uma solicitação de aprovação, confira e autorize a leitura esperada. Definimos --auto-approve false explicitamente porque essa versão da CLI ativa a aprovação automática por padrão. Esta é uma tarefa de validação interativa, não uma execução sem supervisão. Uma automação posterior deve definir suas próprias permissões de forma deliberada.

Se o Hydrogen não aparecer no seletor de modelos, diferencie o seletor do serviço. O catálogo do código-fonte do Cline que verificamos não continha Hydrogen, enquanto a CLI aceitou um ID personalizado do Hydrogen. Nenhuma das observações comprova disponibilidade real. Use o ID exato, confira o provedor salvo e analise a primeira resposta real em vez de escolher um modelo antigo com nome parecido. Para o contexto específico da extensão, veja o guia de configuração da API no Cline, em inglês.

Configure um provedor Hydrogen personalizado no OpenCode V2

Crie opencode.json no projeto de teste com esta configuração V2 completa. Ela usa a estrutura atual de provedores e modelos:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ofox-hydrogen/hydrogen",
  "providers": {
    "ofox-hydrogen": {
      "name": "Ofox Hydrogen",
      "env": ["OFOX_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.ofox.io/v1"
      },
      "models": {
        "hydrogen": {
          "modelID": "google/gemini-4-hydrogen",
          "name": "Gemini 4 Hydrogen",
          "limit": {
            "context": 1048576,
            "output": 65536
          },
          "capabilities": {
            "tools": true,
            "temperature": false
          }
        }
      },
      "compatibility": {
        "maxTokensField": "max_tokens"
      }
    }
  },
  "permissions": [
    { "action": "*", "resource": "*", "effect": "deny" },
    { "action": "read", "resource": "*fixture.txt", "effect": "allow" }
  ]
}

É importante distinguir três nomes:

• ofox-hydrogen é a chave local do provedor. Um nome próprio evita confundir esta configuração com um provedor integrado ou uma personalização existente.
• hydrogen é a chave local do modelo. Juntas, elas formam a seleção ofox-hydrogen/hydrogen.
• google/gemini-4-hydrogen é o modelID, o valor que o provedor compatível envia à Ofox.

Os valores de contexto e saída descrevem os limites do modelo para o cliente. Não concedem cota nem garantem que toda requisição possa usar o máximo. O Hydrogen compartilha sua janela de 1.048.576 tokens entre entrada, raciocínio e saída. O orçamento de saída de 65.536 tokens inclui raciocínio, não apenas texto visível. Esses valores não são limites máximos independentes. Um teto de saída também não é o tamanho desejado da resposta. Comece com uma tarefa pequena e examine o uso efetivamente informado pela sua rota.

Duas opções de compatibilidade merecem atenção. temperature: false instrui o cliente a não enviar esse controle de amostragem. maxTokensField: max_tokens corresponde ao campo de tokens de saída documentado pela Ofox. Sem essa substituição, nossa captura do OpenCode V2 usou max_completion_tokens; com ela, as requisições principais usaram max_tokens. Isso comprova uma mudança de campo no cliente, não que a Ofox rejeite todos os outros aliases.

As regras de permissão negam outras ações e permitem ler um caminho que corresponda ao sufixo do arquivo de teste. São restritas de propósito para um projeto com esse único arquivo, mas o curinga pode corresponder a outros caminhos terminados em fixture.txt. Não são uma sandbox do sistema operacional. Leia a documentação de permissões do OpenCode antes de adaptá-las a um repositório real, a ferramentas de edição ou ao shell.

Execute o teste especificando o caminho da configuração:

OPENCODE_CONFIG="$PWD/opencode.json" \
  opencode run --standalone --format json \
  --model ofox-hydrogen/hydrogen \
  "Read fixture.txt using a file tool. Return its exact marker. Do not modify files or run shell commands."

--standalone está disponível na CLI V2 testada. O caminho explícito e a seleção do modelo facilitam o diagnóstico de configurações herdadas ou de um modelo padrão não pretendido. Guarde os eventos JSON para a validação, removendo credenciais e caminhos privados antes de compartilhá-los.

O guia geral de configuração da API no OpenCode, em inglês apresenta um contexto mais amplo de provedores. Para este exemplo, use a configuração V2 acima de forma consistente. Não insira seus campos plurais providers e permissions em partes de um exemplo antigo da V1.

Verifique o ciclo completo da ferramenta de leitura

A resposta esperada contém HYDROGEN_CLIENT_CHECK_20261113, mas o texto sozinho não é prova suficiente. O modelo pode repetir um valor do histórico sem ler o arquivo. Examine os eventos de ferramentas do cliente e confirme esta sequência:

1. A requisição usa o provedor pretendido e o ID exato do modelo.
2. O modelo pede uma ferramenta de leitura para fixture.txt.
3. O cliente executa a ferramenta, e o resultado contém o marcador do arquivo.
4. O cliente devolve esse resultado na próxima requisição ao modelo.
5. O modelo produz uma resposta final baseada no resultado retornado, sem chamada de ferramenta pendente nem erro do cliente.

Para uma verificação mais forte, altere o marcador no arquivo e inicie uma nova tarefa sem colocar o novo valor no prompt. O marcador devolvido deve mudar também. Confira que nenhum arquivo foi alterado e nenhuma ação inesperada foi aprovada. Esse é um pequeno teste de correção, não uma medida de como o Hydrogen implementará uma funcionalidade na sua base de código.

As verificações anteriores à publicação estabeleceram apenas estes resultados:

O OpenCode também fez uma requisição auxiliar durante o teste. Não presuma que uma tarefa visível do usuário equivale a exatamente uma requisição faturável ao modelo. Confira o uso real da conta depois de chamar o serviço de verdade. Não utilizamos a duração local nem os contadores sintéticos de tokens como evidência de desempenho ou cobrança.

As requisições capturadas do Cline com modelo personalizado não incluíam max_tokens nem temperature explícitos. Não presuma que salvar o nome do modelo também configura o mesmo teto de saída do exemplo OpenCode. Verifique as opções suportadas pelo cliente e o comportamento real das requisições antes de uma carga maior.

Diagnostique erros de versão, autenticação e histórico de ferramentas

Mude uma variável por vez. Primeiro identifique se a falha ocorre ao carregar a configuração, autenticar, gerar texto ou devolver o resultado da ferramenta.

Reproduzimos o primeiro erro com a V1 e o array de permissões V2. Atualizar o pacote e migrar a política de permissões são operações diferentes. Escolher o executável correto não comprova automaticamente que a política de um projeto existente mantém o mesmo significado.

A documentação Gemini sobre chamada de funções e assinaturas de raciocínio explica por que uma troca de ferramentas em vários turnos exige mais que um histórico textual. Um cliente ou adaptador que remove estado necessário do modelo pode passar no primeiro turno e falhar no seguinte. Veja o diagnóstico de assinatura de raciocínio ausente em ferramentas Gemini, em inglês. O artigo descreve esse padrão de falha, mas não prova que um dos clientes tenha esse problema com Hydrogen.

O guia de erros da API Gemini também ajuda a separar autenticação, cota e requisições malformadas. Ele foi escrito com foco no Argon; compare com a resposta real do Hydrogen, sem assumir que todos os detalhes específicos do modelo se aplicam. Nunca invente uma assinatura nem descarte silenciosamente um resultado de ferramenta com falha para corrigir um erro de assinatura.

Salve uma configuração de referência antes de uma tarefa real

Registre o pacote e a versão do cliente, o provedor selecionado, o ID enviado, a Base URL, as configurações relevantes, as permissões e o registro bem-sucedido da ferramenta. Não inclua credenciais. Anote se foi um teste local sintético ou um teste do serviço real e qual conta forneceu a cota.

Depois que o teste real de arquivo passar, abra um repositório pequeno e peça uma explicação de uma função, sem alterações. Em seguida, permita uma única edição que possa ser revisada e execute a verificação pertinente do projeto. Essa progressão separa roteamento e transporte de ferramentas do julgamento do modelo sobre o código. Ler um arquivo com sucesso não comprova segurança no shell, confiabilidade das edições ou compatibilidade com todos os plugins.

Ao trocar cliente, provedor ou versão do modelo, repita primeiro a pequena tarefa de validação. Use o guia da API Hydrogen para inspecionar requisições brutas e o guia de seleção entre Carbon, Hydrogen e Argon para escolher o modelo. Mantenha essa decisão separada da capacidade de um cliente específico de completar a troca com a ferramenta.