OpenCode CLI na Prática: Fluxos de Trabalho, Automação e Armadilhas

A interface de linha de comando do OpenCode é construída para scriptização, pipelines de CI e execuções de agentes não supervisionados. Este artigo é um guia prático para o seu uso no trabalho diário.

Por trás da CLI está um sistema de modelos, ferramentas, permissões, agentes, habilidades, comandos, sessões, servidores MCP e uma arquitetura cliente/servidor. O agente pode ler e editar arquivos do projeto, buscar em repositórios, executar comandos de shell, chamar ferramentas externas e delegar trabalho a subagentes. O mesmo ambiente funciona interativamente na TUI ou de forma não interativa a partir de scripts.

Para tarefas pequenas, você pode instalá-lo, conectar um modelo e começar a fazer perguntas em minutos. Para trabalhos sérios, a qualidade da experiência depende fortemente da seleção do modelo, das instruções do repositório, dos limites de permissão, do gerenciamento de contexto e de quão agressivamente você permite que o agente opere. Este artigo foca nessa segunda etapa, a partir da linha de comando: quais casos de uso valem a pena, quais fluxos de automação se sustentam no uso diário e quais problemas surgem após a novidade de um terminal impulsionado por IA se dissipar. Ele faz parte da seção Ferramentas de Desenvolvimento de IA deste site.

As observações aqui foram verificadas contra o OpenCode 1.18.9 e a documentação atual em agosto de 2026. O OpenCode muda rapidamente, portanto, os exemplos de configuração merecem uma rápida verificação na documentação antes de serem copiados para uma configuração de equipe de longa duração. Se você ainda não instalou o OpenCode, o início rápido do OpenCode cobre a instalação, a verificação e a conexão com provedores.

O que o OpenCode Realmente É: Um Ambiente de Agente, Não uma Caixa de Chat

O OpenCode é um agente de programação de IA de código aberto projetado em torno do terminal. Uma visão simplificada do que ele integra é a seguinte:

A parte importante é a camada de permissão entre a intenção de um modelo e as ações que o OpenCode pode executar. Um excelente modelo com permissões ruins pode ser perigoso. Um modelo fraco com permissões perfeitas é apenas lento e irritante. O uso produtivo do OpenCode requer acertar razoavelmente os dois lados.

O mesmo ambiente atende a ambas as superfícies: a TUI interativa e a linha de comando não interativa. É isso que torna o OpenCode scriptável de uma forma que uma interface de chat pura não é. Se você quer uma abordagem deliberadamente minimalista da mesma ideia de agente de terminal — quatro ferramentas padrão, sem sandbox embutido, tudo o resto via extensões — a revisão do Pi Coding Agent é um contraste útil.

Configuração: Instalar, Conectar e Por que a Independência do Provedor Importa

O OpenCode é instalado em uma linha — script de instalação oficial, npm ou Homebrew — e inicia com opencode a partir de um diretório de repositório. O início rápido do OpenCode cobre a matriz completa de instalação (Arch, Windows, Docker), a verificação e a conexão com provedores (/connect e /models), então este artigo não repete isso.

Você pode usar os próprios serviços de modelo do OpenCode ou conectar provedores externos suportados. O OpenCode atualmente constrói grande parte de seu catálogo de provedores usando Models.dev e suporta uma ampla variedade de configurações de modelos comerciais e locais.

A independência do provedor é uma das decisões arquitetônicas mais úteis do OpenCode. Seu fluxo de trabalho de programação não precisa estar permanentemente acoplado a um único fornecedor de modelos: você pode usar um modelo para trabalho de arquitetura difícil, outro para tarefas de implementação baratas e um modelo local para código que não deve sair do seu ambiente.

Essa flexibilidade é real, mas cria outra variável a gerenciar. Quando o OpenCode desempenha mal, o problema pode ser a estrutura (harness), o prompt, o contexto disponível, o modelo selecionado ou a interação entre todos os quatro.

Inicialize o Repositório com AGENTS.md Antes de Pedir Código

Um dos primeiros comandos que valem a pena executar em um novo repositório é:

/init

O OpenCode analisa o projeto e cria um arquivo AGENTS.md. Commit esse arquivo.

AGENTS.md é onde restrições específicas do repositório podem se tornar contexto duradouro para cada conversa — interativa ou scriptada — em vez de serem repetidas manualmente. Um arquivo útil é curto o suficiente para permanecer relevante, mas concreto o suficiente para prevenir erros previsíveis. Por exemplo:

# Instruções do Repositório

## Arquitetura

- Os manipuladores de API estão sob src/api.
- A lógica de negócio pertence sob src/services.
- O acesso ao banco de dados pertence sob src/repositories.
- Não chame clientes de banco de dados diretamente dos manipuladores HTTP.

## Validação

Após mudanças em TypeScript, execute:

```bash
npm run typecheck
npm test
```

Após mudanças no front-end, execute também:

```bash
npm run lint
```

## Restrições

- Não modifique arquivos gerados.
- Não altere contratos de API pública sem perguntar primeiro.
- Não crie migrações de banco de dados a menos que explicitamente solicitado.
- Nunca execute comandos de implantação.

Isso é menos empolgante do que instalar outro servidor MCP, mas geralmente fornece mais valor. Agentes de programação falham surpreendentemente com frequência porque não sabem quais restrições são importantes. Um contrato curto de repositório remove parte dessa ambiguidade antes da primeira chamada de ferramenta.

Trabalhe a Partir da Linha de Comando com opencode run

A interface interativa recebe a maior parte da atenção, mas o modo não interativo do OpenCode muda consideravelmente o escopo dos fluxos de trabalho úteis:

opencode run "Explain the error handling strategy in this package"

Você pode usar o OpenCode a partir de scripts de shell, jobs de CI, Makefiles, executores de tarefas ou automação local sem entrar manualmente na TUI toda vez. Por exemplo, uma revisão de diff como um comando único:

opencode run \
  "Review the current git diff for correctness and missing tests. Do not edit files."

Ou pipeie o contexto diretamente para uma execução:

git diff --name-only HEAD~1 |
  opencode run "Inspect the changed files and identify risky behavior changes."

Em um Makefile, a mesma chamada se torna um alvo:

.PHONY: review
review:
	opencode run "Review the current git diff for correctness and missing tests. Do not edit files."

Como uma execução scriptada não tem um humano no prompt, a política de permissão que você configura é a única barreira entre o modelo e seu ambiente. É por isso que a seção de permissões abaixo importa mais para automação do que para uso interativo.

A direção interessante aqui não é substituir scripts determinísticos por um LLM. É inserir o raciocínio do modelo em lugares onde a lógica de shell tradicional se torna desajeitada, mantendo a validação determinística ao redor.

Os Melhores Casos de Uso da CLI do OpenCode

O OpenCode pode tentar quase qualquer tarefa de programação, mas isso não significa que cada tarefa deva ser delegada da mesma forma. Os fluxos de trabalho de maior valor tendem a ter três propriedades: o resultado desejado é testável, o contexto relevante do repositório pode ser descoberto e as mudanças incorretas são baratas de inspecionar ou reverter. Cada prompt abaixo funciona na TUI ou como um argumento para opencode run.

1. Exploração de repositório

O OpenCode é excelente em responder perguntas que, de outra forma, exigiriam uma sequência de comandos grep, buscas no editor, saltos de arquivo e git log. Por exemplo:

Explain how authentication works in this repository.

Trace a request from the HTTP middleware through token validation,
user loading, authorization, and the final handler.

Do not modify anything.

Um bom agente buscará pontos de entrada, seguirá referências, inspecionará testes e retornará algo mais próximo de uma apresentação de arquitetura do que uma busca de texto simples. Esta é uma das formas mais seguras de introduzir o OpenCode em uma base de código existente, porque o agente pode fornecer valor sem escrever código.

2. Pequenas correções bem delimitadas

Um bug de escopo estreito é próximo da tarefa ideal para um agente de programação. Por exemplo:

The CLI exits with status 0 when config validation fails.

Find the code path responsible, add a regression test, implement
the smallest fix, and run the relevant tests.

Do not refactor unrelated code.

A frase-chave não é “corrigir o bug”. É as restrições em torno da tarefa. O OpenCode funciona melhor quando o sucesso pode ser demonstrado com um teste, um compilador ou um comando observável. Requisitos vagos dão ao modelo espaço para criar código plausível em vez de código comprovadamente correto.

3. Geração de testes após a implementação

Testes são trabalho útil para agentes porque a implementação existente dá ao OpenCode algo concreto sobre o qual raciocinar. Um prompt produtivo poderia ser:

Review src/parser.ts and its existing tests.

Identify important edge cases that are currently uncovered.
Add tests only. Do not modify the implementation.

Run the parser test suite when finished.

Separar a geração de testes da implementação é importante. Se o mesmo agente escrever tanto o recurso quanto os testes em uma passagem sem restrições, ele pode acidentalmente criar testes que validam sua própria interpretação em vez do comportamento pretendido.

4. Refatoração mecânica

O OpenCode é muito bom em transformações repetitivas onde o estado final desejado é claro. Exemplos incluem:

• substituindo uma API obsoleta em todo o repositório;
• convertendo código repetido em um helper compartilhado;
• renomeando um campo de configuração;
• migrando testes de um padrão de asserção para outro;
• atualizando imports após mover um pacote;
• substituindo uma abstração de log obsoleta.

O compilador e os testes do repositório se tornam o loop de feedback do agente. Um padrão útil é:

Replace uses of LegacyResult<T> with Result<T, AppError> in
packages/api only.

Preserve runtime behavior.

Work in small batches. After each batch run the package typecheck.
At the end run the package test suite and show me the final git diff
summary.

Isso é frequentemente mais confiável do que pedir a migração inteira em uma única etapa enorme.

5. Revisão de código

O OpenCode se torna muito mais útil quando a revisão é tratada como um papel de agente separado, em vez de outro prompt enviado ao mesmo contexto de edição. Você pode criar um agente orientado para revisão que não pode editar arquivos. Então, dê-lhe instruções como:

Review the current git diff.

Focus on:
- correctness;
- security;
- concurrency;
- missing tests;
- error handling;
- accidental API changes.

Do not summarize files that are unchanged.
Rank findings by severity.

Um revisor somente de leitura é útil mesmo que outro agente de programação tenha produzido as mudanças. A separação é valiosa porque a implementação e a crítica são tarefas diferentes: um agente que acabou de gastar vários milhares de tokens defendendo uma abordagem é frequentemente menos cético em relação a essa abordagem do que um revisor novo.

Use os Modos de Plano e Construção como Modos Mentais Diferentes

O OpenCode fornece agentes primários e subagentes, com fluxos de trabalho embutidos incluindo comportamento orientado para planejamento e implementação. Mesmo quando a configuração exata do agente muda com o tempo, a separação conceitual permanece útil.

O planejamento deve responder a perguntas como:

• Quais arquivos importam?
• Quais padrões existentes devem ser seguidos?
• O que pode quebrar?
• Como verificaremos a mudança?
• A mudança solicitada é realmente local?

A implementação deve acontecer apenas após essas perguntas terem respostas razoáveis. Para tarefas substanciais, prefiro uma sequência de prompts como esta:

First investigate the request.

Do not edit files yet.

Return:
1. the relevant files;
2. the current behavior;
3. the proposed change;
4. risks;
5. the exact verification commands.

A mesma sequência funciona como um comando único:

opencode run "First investigate the request. Do not edit files yet. Return: the relevant files; the current behavior; the proposed change; risks; the exact verification commands."

Então, inspecione o plano antes de permitir edições. Isso parece mais lento do que imediatamente dizer a um agente para “implementar”, mas as falhas caras na programação agêntica geralmente vêm de pressupostos incorretos feitos antes da primeira edição.

Esta é uma versão leve, por tarefa, do mesmo instinto por trás do desenvolvimento orientado por especificação: concorde no plano antes que o agente comece a editar. Para trabalho que abrange múltiplos arquivos, sessões ou colaboradores, uma especificação escrita justifica seu overhead de uma forma que um único prompt de investigação prévia não pode; a comparação do GitHub Spec Kit vs Kiro vs Claude Code cobre fluxos de trabalho SDD estruturados que vão além de um único prompt.

Subagentes São Úteis, mas a Delegação Não é Gratuita

O OpenCode pode invocar subagentes especializados automaticamente ou por menções explícitas. Por exemplo:

@general find where retry behavior is implemented

Você também pode definir subagentes dedicados para trabalhos como revisão de segurança, análise de dependências, testes de front-end ou documentação. O mesmo padrão funciona em outras estruturas (harnesses); o guia de subagentes do Claude Code cobre o design análogo no lado da Anthropic.

Isso é poderoso porque o trabalho dos subagentes pode permanecer fora do caminho imediato de raciocínio da conversa primária. Um agente primário pode delegar a exploração do repositório e consumir o resultado em vez de preencher seu próprio contexto com todas as buscas intermediárias. Mas subagentes criam três custos menos óbvios:

1. Eles consomem tokens. Uma árvore de agentes que relê o repositório pode se tornar surpreendentemente cara — meu relatório de experiência com Oh My Opencode documenta o que acontece quando esse overhead é levado ao extremo.
2. Eles criam complexidade de política. As permissões devem ser consideradas para o agente delegado, não apenas para o pai.
3. A delegação pode ocultar o raciocínio. Quando o agente primário diz “o subagente encontrou X”, você pode precisar inspecionar a sessão do filho para entender quão confiável essa conclusão realmente é.

Para a maioria das tarefas de programação, dois ou três agentes propositais são mais úteis do que uma elaborada empresa de software fictícia vivendo dentro do seu terminal.

Se a tarefa genuinamente precisa de um orquestrador completo delegando a um elenco fixo de especialistas — execução em segundo plano paralela, fases de planejamento e pesquisa, roteamento de modelo por papel — isso é um produto diferente construído sobre esses primitivos, não um prompt maior. O início rápido do Oh My Opencode cobre essa estrutura.

Use Agentes Personalizados como Limites de Permissão

Os agentes do OpenCode podem ter prompts, modelos e permissões separados. Isso torna os agentes úteis como limites de segurança e fluxo de trabalho, não apenas personalidades diferentes. Por exemplo, um agente de revisão local do projeto pode ser definido como um arquivo Markdown:

---
description: Reviews code without modifying the repository
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff *": allow
    "git status *": allow
    "git log *": allow
  webfetch: deny
---

Review code for correctness, security, maintainability,
unexpected behavior changes, and missing tests.

Do not modify files.

Isso é muito melhor do que escrever “por favor, não edite nada” em prosa. Instruções influenciam o modelo. Permissões restringem a ferramenta. Esses não são controles equivalentes.

Configure as Permissões do OpenCode no Primeiro Dia

Uma das características práticas mais importantes do OpenCode é que seus padrões normais são permissivos. Isso é conveniente durante uma demonstração e não necessariamente o que eu quero em uma estação de trabalho contendo chaves SSH, credenciais de produção, tokens de publicação de pacotes, contextos Kubernetes e acesso a várias contas de nuvem. Para jobs não supervisionados de opencode run, as apostas são ainda maiores: nada impede uma execução exceto a política que você configura.

O modelo de permissão atual do OpenCode suporta:

allow
ask
deny

As regras podem ser aplicadas a acesso a arquivos, edições, comandos de shell, operações web, subagentes, habilidades, diretórios externos e outras categorias de ferramentas. Um ponto de partida conservador poderia ser assim:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "git diff *": "allow",
      "git log *": "allow",
      "git push *": "deny",
      "rm *": "deny"
    }
  }
}

As regras exatas devem corresponder ao seu ambiente. O que importa é tornar a política intencional em vez de descobrir o padrão após o agente já ter executado algo surpreendente.

Não confunda prompts de aprovação com sandboxing

As regras de permissão são úteis, mas não são a mesma coisa que isolamento do sistema operacional. Se o OpenCode tem permissão para executar um comando de shell permitido, esse processo roda com o acesso disponível para o seu ambiente. Um agente de programação pode potencialmente interagir com arquivos, serviços de rede, variáveis de ambiente, credenciais, sockets, gerenciadores de pacotes e outras ferramentas de desenvolvedor.

Para repositórios sensíveis ou execuções não supervisionadas, isolamento mais forte vale a pena considerar:

Git é rollback. Permissões são política. Um contêiner ou VM é isolamento. Essas são três camadas diferentes.

Transforme Prompts Repetitivos em Comandos Personalizados

Se você digita repetidamente as mesmas instruções, elas provavelmente devem parar de ser histórico de chat e se tornar configuração. O OpenCode suporta comandos slash personalizados de projeto e globais para a interface interativa. Por exemplo, crie:

.opencode/commands/review.md

com:

---
description: Review the current changes
agent: plan
---

Review the current git diff.

Look for:
- bugs;
- security issues;
- incomplete error handling;
- missing tests;
- accidental API changes.

Do not modify files.

Então use:

/review

Este é um pequeno recurso com valor desproporcional. Fluxos de trabalho confiáveis de agentes de programação emergem quando bons prompts se tornam infraestrutura de projeto compartilhada em vez de trechos pessoais de área de transferência. Outros comandos de projeto úteis podem incluir:

/test-changes
/review
/prepare-pr
/check-migration
/update-docs
/release-check

Use Habilidades para Fluxos de Trabalho Reutilizáveis

O OpenCode também suporta arquivos SKILL.md. Habilidades são úteis quando um fluxo de trabalho precisa de mais do que um único prompt. Uma habilidade pode conter orientações operacionais detalhadas e arquivos de apoio, permanecendo descarregada até que o agente realmente a precise. Candidatos úteis incluem:

• procedimentos de migração de banco de dados;
• fluxos de trabalho de lançamento;
• investigação de incidentes;
• revisões de compatibilidade de API;
• publicação de pacotes;
• validação de infraestrutura;
• convenções de arquitetura interna.

Por exemplo:

.opencode/skills/database-migration/SKILL.md

Uma descrição de habilidade pode dizer ao OpenCode quando o procedimento se aplica, enquanto o corpo explica como inspecionar esquemas, criar migrações, validar o comportamento de rollback e executar testes de integração. Se você já usa o conceito equivalente em outra estrutura (harness), o guia de Habilidades Claude para desenvolvedores mapeia as mesmas decisões de design.

A vantagem é a disciplina de contexto. Jogar cada regra organizacional em AGENTS.md eventualmente cria um prompt de sistema gigante que é caro e cada vez mais fácil para o modelo ignorar. Habilidades permitem que instruções especializadas entrem no contexto apenas quando necessário.

MCP: Útil Até o Catálogo de Ferramentas se Tornar o Problema

O OpenCode suporta servidores MCP locais e remotos. Isso pode expor rastreadores de problemas, sistemas de documentação, navegadores, plataformas de observabilidade, bancos de dados, APIs e outras ferramentas ao agente de programação. Uma configuração típica pode fornecer um servidor de documentação:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

MCP é um daqueles recursos que é fácil superutilizar. Cada ferramenta que o agente deve entender consome atenção e frequentemente tokens de contexto. Uma configuração com quinze servidores MCP pode parecer poderosa em uma captura de tela de configuração, mas torna o comportamento real do modelo mais lento, mais caro e menos previsível.

Minha regra é simples: se uma ferramenta não é útil em uma semana normal de trabalho, ela provavelmente não deve ser habilitada globalmente. Carregue ferramentas porque um fluxo de trabalho as requer, não porque a integração existe.

Modelos Locais no OpenCode: Uma Opção Real, Não uma Solução Mágica

Um dos casos de uso mais fortes do OpenCode é sua capacidade de trabalhar com endpoints de modelos locais ou auto-hospedados compatíveis com OpenAI. Isso é atraente quando:

• o código-fonte deve permanecer local;
• os custos de API são significativos;
• você já opera infraestrutura de GPU;
• você quer experimentar com modelos abertos;
• a conectividade à internet é instável;
• o roteamento de modelos faz parte da sua plataforma.

Um provedor personalizado pode apontar o OpenCode para um endpoint local como LM Studio, llama.cpp via llama-server, vLLM, infraestrutura compatível com Ollama ou outro servidor compatível com OpenAI.

É aqui que as expectativas importam. Uma boa estrutura de programação (harness) não pode compensar completamente um modelo que é fraco em uso de ferramentas, planejamento de longo prazo, raciocínio de código ou retenção de instruções. Discussões da comunidade em torno de configurações locais do OpenCode convergem repetidamente na mesma observação: modelos locais podem ser excelentes para tarefas delimitadas, mas os menores frequentemente precisam de mais supervisão. Para números medidos sobre como modelos específicos realmente se comportam dentro do OpenCode, veja minha comparação de LLMs hands-on para OpenCode.

A solução prática é o roteamento de modelos por complexidade da tarefa. Use um modelo mais barato ou local para:

• busca em repositório;
• documentação;
• testes simples;
• edições repetitivas;
• mudanças de formatação;
• correções de bugs diretas.

Use um modelo mais forte para:

• mudanças de arquitetura;
• bugs ambíguos;
• refatorações entre pacotes;
• concorrência;
• código sensível à segurança;
• migrações difíceis.

A independência do provedor torna essa estratégia possível. Não torna a qualidade do modelo irrelevante.

Um Fluxo de Trabalho Diário Prático com OpenCode

Meu fluxo de trabalho preferido é deliberadamente conservador. Ele funciona da mesma forma na TUI ou via opencode run; onde uma etapa é um prompt, a variante de linha de comando é mostrada ao lado.

Etapa 1: Comece de um estado Git limpo

git status

Ou commit as mudanças existentes ou registre deliberadamente o que já está modificado. Um agente de programação de IA operando dentro de uma árvore de trabalho suja torna a revisão muito mais difícil, porque as mudanças humanas e as mudanças do agente se misturam.

Etapa 2: Peça investigação primeiro

Investigate issue #482.

Do not modify files.

Explain:
- the current behavior;
- likely root cause;
- relevant files;
- existing tests;
- proposed fix;
- verification commands.

O mesmo prompt como um comando único:

opencode run "Investigate issue #482. Do not modify files. Explain the current behavior, likely root cause, relevant files, existing tests, proposed fix, and verification commands."

Se a investigação estiver errada, corrigi-la é barato.

Etapa 3: Estreite a implementação

Implement the proposed fix only.

Do not refactor unrelated code.
Add the regression test first.
Run the smallest relevant test suite after the change.

Ou não interativamente:

opencode run "Implement the proposed fix only. Do not refactor unrelated code. Add the regression test first. Run the smallest relevant test suite after the change."

O agente agora tem um espaço de decisão menor.

Etapa 4: Inspecione o diff você mesmo

git diff --stat
git diff

Não terceire essa etapa para outro modelo inteiramente. Você está verificando não apenas se o código parece plausível, mas se o agente modificou arquivos que não precisava tocar.

Etapa 5: Execute verificação determinística

npm run typecheck
npm test
npm run lint

Use os comandos reais do projeto. “OpenCode diz que os testes passam” não é evidência mais forte do que seu terminal exibindo um processo de teste bem-sucedido.

Etapa 6: Execute uma revisão independente

Peça a um agente somente de leitura:

Review the uncommitted diff as if it were a pull request written
by another engineer.

Try to find reasons this implementation is wrong.

Do not edit files.

A variante de linha de comando:

opencode run "Review the uncommitted diff as if it were a pull request written by another engineer. Try to find reasons this implementation is wrong. Do not edit files."

A frase “tente encontrar razões pelas quais isso está errado” é intencional. Modelos são muito bons em confirmar educadamente trabalho plausível. Prompts de revisão devem encorajar a falsificação em vez de aplausos.

Etapa 7: Commit apenas após o diff fazer sentido

git add -p
git commit

Eu ainda prefiro staging interativo após mudanças geradas por agente. Isso força uma passagem final humana através de cada hunk que se torna parte do histórico do repositório.

Onde o OpenCode se Torna Frustrante: Armadilhas Comuns

As limitações interessantes geralmente não são “a IA fez um erro de sintaxe”. Compiladores são bons em pegar esses. Os problemas difíceis vêm da autonomia, contexto, pressupostos ocultos e configuração.

Desafio 1: A qualidade do modelo domina a experiência

O mesmo fluxo de trabalho do OpenCode pode parecer excelente com um modelo e quase inutilizável com outro. Isso torna as revisões de produto difíceis porque os usuários frequentemente atribuem o comportamento do modelo à estrutura do agente (harness).

Se o OpenCode repetidamente:

• ignora instruções;
• reescreve muito código;
• chama ferramentas incorretamente;
• entra em loop na mesma ação falha;
• perde o controle das restrições;
• inventa APIs;

tente outro modelo antes de redesenhar toda a configuração do OpenCode. O terminal não ficou subitamente mais inteligente. O modelo ficou.

Desafio 2: Sessões longas acumulam contexto ruim

Sessões de agentes de programação se tornam menos confiáveis à medida que pressupostos incorretos se acumulam. Um erro inicial como “este serviço é sem estado” pode influenciar dezenas de decisões posteriores mesmo após os arquivos relevantes terem mudado.

O OpenCode suporta compactação para gerenciar limites de contexto, mas a compressão cria seu próprio tradeoff. Um resumo necessariamente decide quais detalhes sobrevivem. Para transições de tarefa importantes, começar uma nova sessão é frequentemente mais limpo do que continuar uma conversa heróica de 80.000 tokens. Com execuções scriptadas, a resposta é ainda mais simples: uma nova opencode run começa com um contexto limpo toda vez, então o estado de longa duração pertence a arquivos como AGENTS.md, não a uma conversa.

Contexto não é memória gratuita. É estado de trabalho, e o estado de trabalho fica obsoleto.

Desafio 3: As permissões podem se tornar enganosa e complicadamente

Regras simples são fáceis:

read -> allow
edit -> ask
git push -> deny

Hierarquias de agentes complexas são mais difíceis. Uma vez que agentes primários podem invocar subagentes, ferramentas personalizadas, servidores MCP e comandos de shell, você precisa raciocinar sobre as capacidades efetivas de todo o fluxo de trabalho, em vez de uma única linha de configuração.

Também houve discussões reais da comunidade e do GitHub sobre o comportamento de permissão de subagentes e a herança de permissões. A lição é mais ampla do que qualquer bug individual: teste suposições de segurança com um repositório descartável real — por exemplo, git init /tmp/opencode-perm-test e tente fazer o agente executar um comando que você negou lá. Se uma ação absolutamente não deve ocorrer, não confie apenas em instruções em prosa.

Desafio 4: O OpenCode muda rapidamente

O OpenCode foi lançado em um ritmo notável. Isso é bom para recursos e menos agradável para a longevidade da documentação. Uma armadilha particularmente fácil em 2026 é encontrar exemplos de configuração de uma geração diferente do OpenCode. A documentação atual também contém material separado V2 cujo esquema de configuração difere da sintaxe 1.x estabelecida. Por exemplo, conceitos de permissão podem aparecer sob nomes de campo diferentes na documentação V2.

Não combine casualmente exemplos de:

/docs/

e:

/v2/docs/

sem verificar qual runtime você está realmente usando. Ao solucionar problemas de uma configuração copiada de um post de blog, verifique a data de publicação antes de assumir que o OpenCode está quebrado.

Desafio 5: A TUI pode ocultar a escala

Uma interface conversacional faz uma mudança de dez arquivos parecer menor do que uma mudança de dez arquivos. O agente pode relatar:

Implemented the new validation and updated the relevant tests.

Essa frase pode representar três linhas ou 600 linhas. Mantenha ferramentas de shell independentes por perto:

git status --short
git diff --stat
git diff --name-only
git diff

O agente de programação não deve ser a única interface através da qual você observa o agente de programação.

Desafio 6: O MCP pode destruir a eficiência do contexto

Mais integrações não produzem automaticamente um agente de programação melhor. Grandes servidores MCP podem expor muitos esquemas de ferramentas, cada um consumindo contexto do modelo e aumentando a complexidade de seleção de ferramentas. Se o OpenCode parecer estranhamente indeciso após você instalar metade do ecossistema MCP, desative a maioria e compare. Uma superfície de ferramentas menor frequentemente produz um melhor comportamento do agente.

Desafio 7: A privacidade local requer verificar o caminho inteiro

Executar um modelo local não garante automaticamente que cada parte da cadeia de ferramentas seja local. Discussões da comunidade no início de 2026 levantaram questões de privacidade em torno do comportamento do modelo auxiliar do OpenCode e da arquitetura da interface web. Algumas dessas alegações se referiam a versões mais antigas, algumas foram disputadas e alguns caminhos de código mudaram desde então.

A lição duradoura não é “OpenCode envia tudo para algum lugar”. A lição duradoura é: se a operação somente local é um requisito rígido, verifique. Use inspeção de rede, leia a configuração atual, entenda qual interface você está usando, desative integrações remotas desnecessárias e teste a versão exata que você pretende implantar. Requisitos de segurança devem ser validados, não inferidos de uma categoria de produto.

OpenCode vs Claude Code e Codex CLI

O diferencial mais forte do OpenCode não é necessariamente a qualidade de programação. O modelo subjacente ainda contribui fortemente para a qualidade de programação. Seu diferencial é o controle sobre a estrutura (harness).

O OpenCode é convincente quando você valoriza:

• uma implementação de código aberto;
• flexibilidade de provedores;
• fluxos de trabalho centrados no terminal;
• agentes configuráveis;
• permissões granulares;
• suporte a modelos locais;
• MCP;
• comandos e habilidades reutilizáveis;
• arquitetura cliente/servidor.

Claude Code é convincente quando você quer uma experiência Anthropic altamente integrada com forte comportamento de modelo de primeira parte e fluxos de trabalho de agentes embutidos cada vez mais polidos. Codex CLI é convincente quando seus modelos e fluxo de trabalho preferidos já estão centrados na pilha de programação da OpenAI.

Eu não escolheria entre eles contando recursos. Escolha com base em qual camada você quer possuir. Se você quer que um fornecedor tome a maioria das decisões de fluxo de trabalho, um agente de programação de primeira parte pode ser atraente. Se você quer que a estrutura (harness) permaneça substituível enquanto experimenta com provedores e configurações de agente, o OpenCode faz um argumento mais forte.

O que Reddit e Hacker News Acertam Sobre o OpenCode

As discussões da comunidade em torno do OpenCode são incomumente polarizadas. Alguns desenvolvedores o descrevem como sua estrutura de programação favorita, especialmente quando combinado com modelos Codex, modelos locais ou configurações de agentes personalizados. Outros focam no uso de recursos, comportamento de permissão, questões de privacidade, mudanças de autenticação de provedores ou a complexidade que aparece uma vez que uma aplicação de terminal aparentemente simples se torna infraestrutura. Ambas as perspectivas são razoáveis.

O OpenCode não é difícil porque a linha de comando é difícil. É difícil porque um ambiente de programação autônomo expõe perguntas que desenvolvedores anteriormente não precisavam responder explicitamente:

• Qual modelo deve tomar essa decisão?
• Quais arquivos ele pode ler?
• Quais comandos ele pode executar?
• Quais credenciais o processo pode ver?
• Quais tarefas devem se tornar subagentes?
• Quanto contexto deve sobreviver?
• Quais ferramentas merecem contexto permanente?
• Qual resultado um humano deve verificar?

Um produto fechado polido pode tomar muitas dessas decisões por você. O OpenCode torna mais delas suas. É precisamente por isso que usuários avançados gostam dele.

Uma Configuração Inicial que Eu Recomendaria

Eu resistiria a construir uma configuração elaborada imediatamente. Comece com:

1. um modelo padrão forte;
2. um AGENTS.md;
3. permissões conservadoras de shell e edição;
4. um agente de revisão somente de leitura;
5. dois ou três comandos personalizados;
6. nenhum servidor MCP até que uma necessidade real apareça.

Um ambiente simples é mais fácil de depurar. Uma vez que um fluxo de trabalho se torna repetitivo, promova-o para um comando, habilidade ou agente. Uma vez que uma capacidade se torna arriscada, restrinja-a com permissões. Uma vez que o contexto se torna inchado, divida o fluxo de trabalho em vez de apenas comprar uma janela de contexto maior. Essa abordagem incremental é menos impressionante em capturas de tela e consideravelmente mais agradável de manter.

Quem Deve Usar o OpenCode

O OpenCode é um ajuste particularmente bom para desenvolvedores que já vivem em terminais e querem que seu agente de programação se comporte como outra ferramenta de desenvolvimento programável. Eu o consideraria fortemente se você:

• trabalha em vários provedores de LLM;
• quer suporte a modelos locais;
• não gosta de estar preso a um único fornecedor de IA;
• precisa de agentes específicos do projeto;
• automatiza tarefas de desenvolvimento a partir de scripts de shell;
• quer inspecionar ou modificar a estrutura de programação (harness);
• já entende Git e ferramentas de CLI normais.

É menos convincente se você primariamente quer uma camada de IA invisível dentro de uma IDE. O OpenCode também espera mais julgamento operacional do que uma ferramenta de autocompletar tradicional. Se revisar diffs, entender comandos de shell e gerenciar branches Git já se sentem desconfortáveis, dar a um processo autônomo acesso a essas ferramentas não fará a complexidade subjacente desaparecer.

Veredito Final

O OpenCode é um dos exemplos mais convincentes de uma ferramenta de programação de IA se tornando infraestrutura de desenvolvedor em vez de meramente uma interface de chat. Seus melhores recursos não são chamativos. Independência de provedores, permissões explícitas, agentes reutilizáveis, execução não interativa, instruções de repositório, comandos, habilidades e ferramentas composáveis tornam possível moldar o agente em torno de um fluxo de trabalho de engenharia real.

A fraqueza é a imagem espelhada dessa força. O OpenCode lhe dá controle suficiente para criar um ambiente de programação disciplinado, mas também lhe dá controle suficiente para criar um enxame complicado, caro e mal isolado de agentes com vinte servidores MCP e nenhum limite de verificação claro.

Eu não otimizaria o OpenCode para autonomia máxima. Eu o otimizaria para loops de feedback curtos. Dê-lhe um problema delimitado, contexto suficiente para entender o problema, permissão para executar apenas as ações necessárias e comandos determinísticos que podem provar se o resultado funciona. Isso é menos mágico do que pedir a um agente para construir um aplicativo inteiro enquanto você dorme. Também está muito mais perto de como o OpenCode se torna genuinamente útil.

Referências

• Documentação do OpenCode: https://opencode.ai/docs/
• Changelog do OpenCode: https://opencode.ai/changelog
• Repositório GitHub do OpenCode: https://github.com/anomalyco/opencode
• Catálogo de provedores Models.dev: https://models.dev