OpenCode Desktop ou CLI: qual escolher para o seu trabalho?

Compare OpenCode Desktop e CLI por fluxo de trabalho, configuração do provedor e troca de sessão. Inclui exercício em Python e diagnóstico de erros por versão.

OpenCode Desktop ou CLI: qual escolher para o seu trabalho?

Escolha o OpenCode Desktop quando quiser um ambiente visual para organizar sessões e revisar alterações. Comece pela CLI quando seu trabalho partir de um terminal, de um shell remoto ou de um script que precisa ser repetido. É possível usar os dois, mas conferir a pasta do projeto, o servidor e o modelo é mais importante do que simplesmente entrar na conta duas vezes.

Esta comparação trata de duas interfaces do OpenCode. Para decidir entre OpenCode e Codex, da OpenAI, consulte OpenCode vs Codex CLI (em inglês).

Consultamos a documentação atual em 17 de novembro de 2026 e instalamos a CLI 2.3.0 do OpenCode em um diretório isolado para verificar a versão e a saída de ajuda. Também executamos localmente os testes Python do exercício disponível para download. Não fizemos uma comparação paga entre modelos nem concluímos o exercício no Desktop. O comportamento das interfaces descrito abaixo é documentado, não uma medição de qual delas gera código melhor. A Ofox, que oferece acesso a APIs, publica este guia.

Escolha conforme a tarefa que precisa concluir

Sua próxima tarefaPor onde começarMotivoO que conferir
Explorar um repositório local e revisar várias mudançasDesktopSessões e diferenças de código em uma interface visual combinam com trabalho centrado em revisãoAbra a pasta correta e inspecione os arquivos antes de aceitar alterações
Trabalhar via SSH em uma máquina de desenvolvimentoCLIPermite começar no shell remoto já abertoCredenciais, arquivos e ferramentas precisam existir nessa máquina
Repetir um prompt em script ou CICLIopencode run dispensa abrir a interface interativaModelo, permissões, tratamento da saída e estado de falha
Preferir teclado, mas ainda querer uma conversa interativaCLI TUIA CLI também é um aplicativo interativo, não apenas um comando para scriptsExibição do terminal e projeto selecionado
Trocar de interface durante uma tarefa localQualquer uma, com uma passagem conscienteA V2 atual oferece um servidor local compartilhadoOs dois clientes precisam usar de fato o mesmo servidor e projeto
Corrigir erro de autenticação ou de provedorDiagnostique primeiro a conexãoOutra interface não corrige uma chave inválida ou uma requisição incompatívelProvedor, modelo, endpoint e erro exatos

A página do produto OpenCode (em inglês) apresenta o Desktop como um ambiente com sessões, abas e diferenças de código, e o Terminal como uma interface utilizável em um shell ou servidor remoto. São diferenças úteis de fluxo de trabalho, mas não evidência de capacidades distintas do modelo subjacente.

Por exemplo, quem já está investigando testes que falharam via SSH pode ganhar pouco ao migrar para uma interface gráfica local com outro sistema de arquivos. Quem revisa várias alterações locais pode preferir visualizar a conversa e as diferenças no mesmo ambiente. Nenhuma escolha elimina a necessidade de executar os testes do projeto.

Confira a versão antes de seguir um tutorial

“Desktop ou CLI” e “OpenCode 1 ou OpenCode 2” são comparações diferentes. Uma incompatibilidade de versão pode parecer uma limitação da interface.

No terminal, execute:

opencode --version
opencode --help
opencode run --help

Nossa instalação isolada retornou opencode v2.3.0. A ajuda lista run, session, service, models, auth e debug. Nessa versão, em particular, opencode models não recebe o nome do provedor como argumento posicional. Não presuma que um comando copiado de um tutorial antigo será aceito pelo executável atual.

Para instalar a V2 do zero com npm no macOS ou Linux, a documentação de instalação atual (em inglês) lista:

npm install -g @opencode/cli
opencode --version

Quem já usa a V1 deve consultar primeiro o guia oficial de migração (em inglês). As duas gerações usam o comando opencode; instalar outro pacote sem conferir pode substituir o comando existente ou causar conflito. No Windows, use o download independente da CLI indicado pelo OpenCode, em vez de presumir que as instruções do gerenciador de pacotes se aplicam. O Desktop também tem downloads para macOS, Windows e Linux.

A V2 mantém suporte às configurações V1 compatíveis, então a adoção não exige reescrever todos os arquivos. Porém, há mudanças incompatíveis em plugins e integrações com o servidor. Entradas nativas de provedor V2 usam providers, package e settings; as antigas usam provider, npm e options. Mantenha cada entrada aninhada de provedor em um único formato completo, sem montar uma mistura a partir de trechos de busca. Faça backup antes de converter uma configuração que funciona.

Conecte o provedor e depois selecione o modelo

São três verificações separadas: o provedor está conectado, o modelo aparece e uma requisição realmente funciona. Passar na primeira não comprova as outras duas.

Para a Ofox, comece pelas instruções de integração com OpenCode, que cobrem as duas interfaces. Obtenha uma chave com o guia de autenticação por API Key e não a inclua em arquivos versionados, capturas de tela ou logs de diagnóstico copiados.

Caminho no Desktop

O fluxo documentado pela Ofox é:

  1. Abra Settings → Providers e depois Show more providers.
  2. Procure Ofox, conecte o provedor e informe a chave.
  3. Abra Settings → Models, procure Ofox e habilite o modelo desejado.
  4. Crie uma sessão no projeto correto e escolha esse modelo no seletor da sessão.

Se a interface for diferente, verifique a versão instalada e os controles atuais do provedor antes de concluir que a conta está com problema. A imagem abaixo registra a documentação em inglês da Ofox, não uma nova execução de inferência no Desktop.

Documentação em inglês da Ofox mostrando o caminho das configurações de provedor no Desktop

Captura da documentação feita em 17 de novembro de 2026. A interface incorporada é um exemplo da documentação e não identifica a versão instalada no seu computador.

Caminho na CLI

Abra o diretório do projeto, inicie opencode, use /connect para escolher o provedor e /models para selecionar o modelo. Esses comandos com barra pertencem à interface interativa, não ao prompt normal do shell.

Para scripts, consulte a lista com opencode models e use o identificador exato retornado:

opencode run --model 'PROVIDER/MODEL' "Explain the files in this project. Do not edit them."

Substitua PROVIDER/MODEL: é um marcador, não um modelo real. O prompt em inglês pede uma explicação dos arquivos sem editá-los. Esse comando envia uma requisição ao modelo e pode gerar cobrança pelo provedor. Verificamos as opções na ajuda local, sem executar essa requisição.

Use o provedor Ofox integrado quando ele atender à sua necessidade. Um provedor personalizado é outro caminho para um protocolo ou endpoint específico; não é um pré-requisito para usar o Desktop. A seção sobre provedor integrado e personalizado explica a distinção. Se precisar de uma rota personalizada, use a referência atual de provedores do OpenCode (em inglês) junto do endpoint exato e do protocolo aceito na documentação da Ofox. Nosso guia de configuração de provedor personalizado (em inglês) explica a relação entre registro do provedor e do modelo; os exemplos datados precisam ser conferidos com sua versão instalada.

O que é compartilhado quando você troca de interface?

A documentação atual da CLI (em inglês) descreve um servidor em segundo plano compartilhado pelo usuário local. Ele gerencia sessões, configuração, permissões, integrações e execução de ferramentas. A CLI também pode usar um servidor privado com --standalone ou se conectar a um servidor específico com --server.

Assim, “estou no mesmo notebook” não basta para validar a passagem. Um servidor privado, outra conta, um host remoto ou outro caminho de projeto podem representar contextos de trabalho diferentes.

ItemO que conferir na passagemPor que importa
ArquivosMesmo caminho absoluto do projeto e conteúdo atual dos arquivosPastas com o mesmo nome podem conter trabalhos diferentes
ServidorAmbos os clientes apontam para o serviço esperadoUm serviço privado ou remoto não é automaticamente o serviço local compartilhado
SessãoSelecione a sessão desejada, não apenas a mais recenteO histórico recente pode pertencer a outra tarefa
ModeloCompare a seleção exata de provedor e modeloUm nome de exibição familiar não comprova a mesma rota
PermissõesRevise o que a tarefa pode ler, editar e executarTrocar de interface não autoriza ampliar o acesso
Ferramentas e ambienteConfira as ferramentas na máquina onde ocorre a execuçãoTer Python localmente não significa que ele exista no host remoto

Para inspecionar o estado do serviço sem reiniciar trabalho ativo:

opencode service status
opencode session list

Execute o comando de sessões no projeto que pretende continuar. A ajuda local da CLI 2.3.0 o descreve como uma listagem das sessões de nível superior do projeto atual. Verificamos as definições dos comandos, não uma transferência de sessão entre interfaces.

Se houver divergência de configuração, consulte os locais de configuração do projeto e do usuário na referência de configuração (em inglês). Configurações administradas podem ter prioridade. Não desative políticas administrativas para fazer as interfaces parecerem idênticas.

Experimente a mesma tarefa pequena em cópias separadas

Baixe o exercício de comparação. Ele contém uma função Python intencionalmente incompleta, quatro testes, um prompt e uma solução de referência escrita pela equipe editorial. As instruções e o prompt estão em inglês. Os testes em si não exigem chave de API nem instalação de dependências.

A tarefa é aceitar nomes de arquivo terminados em .csv, sem diferenciar maiúsculas de minúsculas, e rejeitar sufixos como .csv.tmp. É um exercício de programação restrito, não um benchmark de capacidade de engenharia de software.

  1. Extraia o arquivo duas vezes em pastas separadas, como desktop-check e cli-check.
  2. Em cada pasta, execute python3 -m unittest -v. Se seu sistema inicia Python 3 com python, use esse comando.
  3. A versão inicial deve apresentar dois testes com falha entre quatro. Registre essa referência antes de envolver um agente.
  4. Abra desktop-check no Desktop e inicie a CLI em cli-check. Use o mesmo provedor/modelo e permissões equivalentes.
  5. Envie o mesmo prompt aos dois. O original em inglês abaixo exige alterar somente a função, preservar os testes e relatar o resultado real:
Read app.py and test_app.py. Update only accepts_csv in app.py so filenames
ending in .csv are accepted case-insensitively. Reject .csv.tmp and names
with no .csv suffix. Do not modify the tests or install dependencies.
Run python3 -m unittest -v and report the result. If Python is unavailable,
say so rather than claiming the tests passed. Explain the exact code change.

Após cada execução, inspecione app.py e confirme que test_app.py não mudou. Execute os testes por conta própria: os quatro devem passar. A mensagem “corrigido” não substitui essa verificação. A solução de referência serve para conferir a regra esperada; ela não é uma saída gerada por qualquer uma das interfaces do OpenCode.

Confirmamos localmente as duas falhas iniciais e os quatro testes aprovados da referência. Não coletamos tempo, custo ou taxa de sucesso de modelos no Desktop contra a CLI. Se fizer o exercício, registre essas observações separadamente do resultado determinístico dos testes. Uma tarefa pequena ajuda a descobrir se o fluxo combina com você; não demonstra que uma interface seja sempre mais rápida ou precisa.

Para testar uma passagem, pare primeiro o trabalho ativo, troque de interface e confira os seis itens da tabela anterior antes de continuar. Não deixe os dois agentes editarem a mesma cópia simultaneamente durante a comparação: as mudanças se misturariam e comprometeriam o resultado.

Investigue a camada que está falhando

SintomaPrimeira verificaçãoPróxima ação
opencode não é encontradoInstalação e PATH do shellVerifique o método da versão escolhida; reabra o shell se o PATH mudou
Um comando copiado rejeita um argumentoopencode --version e o --help desse comandoUse a sintaxe da geração instalada antes de trocar credenciais
Provedor conectado, mas modelo ausenteVisibilidade do modelo, ID do provedor e ID do modeloConfira a habilitação no Desktop e a lista da CLI; valide o registro personalizado, se houver
Desktop mostra uma sessão que a CLI não mostraCaminho do projeto, conta e servidorListe sessões no projeto correto e confira o estado do serviço
A requisição retorna 401Origem da credencial e endpoint de destinoSiga o guia de autenticação e erros da Ofox; não cole segredos em relatos de erro
A requisição retorna 429Limites de taxa e informações de nova tentativa retornadasUse o guia de diagnóstico de 429 (em inglês); trocar de interface não remove o limite
O chat funciona, mas ferramentas do agente falhamCapacidade do modelo, protocolo e formato do resultado da ferramentaUse as verificações de API compatível com OpenAI para separar chat simples de compatibilidade com chamadas de ferramentas

Se houver atualização de versão, registre a versão antiga, a nova e a primeira operação que falha. Altere uma variável por vez. Reinstalar o aplicativo, trocar a chave e reescrever a configuração do provedor ao mesmo tempo dificulta saber o que resolveu o problema.

Comece pelo Desktop para revisão visual local ou pela CLI para trabalho em terminal e scripts. Mantenha os dois quando a passagem for útil. O critério de sucesso é obter um resultado verificável com os arquivos, o modelo e as permissões corretos, não uma interface que pareça mais poderosa.