Como ajustar o buffer de contexto no OpenCode 2.2.5

A API do GitHub registra a publicação às 23:17 UTC, ou 20:17 no horário de Brasília.

A configuração deixa reservar uma parte da janela de contexto do modelo, em vez de repetir o mesmo número fixo de tokens em todos os modelos.

O OpenCode 2.2.5 aceita porcentagem em compaction.buffer

A release v2.2.5 informa que compaction.buffer agora aceita um percentual da janela de contexto, além de uma contagem fixa de tokens.

O exemplo oficial usa "20%" e explica que a proporção ajuda a manter uma parte livre em modelos com janelas pequenas ou grandes.

Uma janela de contexto é o limite de texto que o modelo consegue considerar em uma interação. O buffer é uma reserva dentro desse limite.

Configurar uma porcentagem não aumenta a capacidade do modelo, nem garante que uma conversa nunca precisará de compactação.

Com uma contagem fixa, o mesmo número representa parcelas diferentes em modelos com contextos distintos.

Com uma porcentagem, o valor acompanha o tamanho da janela informada para cada modelo. Esse é o benefício descrito na release, não uma promessa de ganho de qualidade ou velocidade.

A captura abaixo vem do repositório oficial do OpenCode e mostra a tela Geral do aplicativo Desktop. Ela não exibe compaction.buffer, que é configurado no arquivo JSON, mas ajuda a identificar a interface do produto.

A captura oficial no repositório do OpenCode mostra configurações de interface.

Para o buffer percentual, use a release como referência da sintaxe e a documentação oficial de configuração para entender o escopo do arquivo.

Como definir o buffer percentual no OpenCode

Passo 1: confira se a versão inclui o recurso

O anúncio documenta a opção na versão 2.2.5. Antes de editar a configuração, confirme que o OpenCode instalado está nessa versão ou em uma posterior que mantenha o campo.

Não assuma que uma versão anterior entende o sufixo percentual. Se a equipe fixa versões, consulte o changelog adotado pelo projeto antes de compartilhar o ajuste.

Passo 2: abra o arquivo de configuração do projeto

A release apresenta o exemplo em opencode.json. Se o arquivo já existe, edite a configuração atual e preserve as demais opções. Não substitua o arquivo inteiro por um exemplo reduzido.

A documentação do OpenCode explica os arquivos de configuração disponíveis e como eles se aplicam.

Confira se você está alterando o escopo desejado, por exemplo as opções do projeto, e não uma configuração global usada por outros repositórios.

Passo 3: adicione compaction.buffer como texto

Dentro do objeto principal, inclua a propriedade compaction com o campo buffer. O valor percentual deve ser uma string, com aspas, como no exemplo publicado pelo projeto:

{
  "compaction": {
    "buffer": "20%"
  }
}

Se já houver um objeto compaction, adicione ou atualize somente buffer. Em JSON, não mantenha duas chaves com o mesmo nome. Preserve vírgulas e chaves existentes para que o arquivo continue válido.

Passo 4: valide em uma conversa real

Reabra o OpenCode no projeto e use uma sessão de trabalho comum.

Observe se a configuração é aceita e se a reserva proporcional se comporta como esperado ao alternar entre modelos com janelas diferentes.

Não use uma tarefa crítica como primeiro teste. Anote a versão, o modelo selecionado e a configuração ativa. Se o resultado divergir do esperado, volte ao valor anterior e confira a documentação correspondente à sua versão.

O buffer percentual não amplia a janela do modelo

O valor "20%" é o exemplo da release, não uma recomendação universal.

A porcentagem que funciona para uma tarefa pode deixar pouco espaço para o histórico em outra, ou reservar mais contexto do que o necessário.

A função também não torna todos os modelos equivalentes. Cada modelo continua sujeito ao próprio limite e às regras de uso do OpenCode.

A opção ajusta a reserva proporcional, sem mudar a capacidade anunciada pelo provedor.

A release diz que contagens fixas de tokens continuam funcionando. Portanto, não é necessário converter todas as configurações existentes para porcentagens.

Uma contagem fixa pode ser mais clara quando o projeto usa um modelo específico e a equipe quer manter um número conhecido.

O changelog não publica medições de latência, economia de tokens ou qualidade para diferentes percentuais.

Trate a mudança como uma opção de configuração e valide com as sessões que seu time realmente executa.

Erros comuns ao configurar compaction.buffer

• Usar número sem aspas: o exemplo oficial escreve "20%" como texto. Não transforme em 20 ou em outro tipo de dado.
• Duplicar a chave: mantenha apenas um campo buffer dentro de compaction.
• Colar o exemplo sobre o arquivo inteiro: mescle só a propriedade nova para não apagar opções do projeto.
• Esperar mais contexto: o campo reserva uma proporção da janela, mas não aumenta o limite do modelo.
• Aplicar em versão antiga: confirme a versão antes de distribuir a configuração entre máquinas.

Se a configuração não for aceita, confira primeiro se o JSON está válido, se o campo está no objeto correto e se a versão reconhece o formato percentual.

Esses passos isolam erros de sintaxe de diferenças entre versões.

A página OpenCode versus bridgecode explica como o agente se encaixa em um fluxo de desenvolvimento.

Também há um exemplo de uso do OpenCode com métricas do GitHub Copilot, em um contexto diferente de configuração de contexto.