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.
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 tarefa | Por onde começar | Motivo | O que conferir |
|---|---|---|---|
| Explorar um repositório local e revisar várias mudanças | Desktop | Sessões e diferenças de código em uma interface visual combinam com trabalho centrado em revisão | Abra a pasta correta e inspecione os arquivos antes de aceitar alterações |
| Trabalhar via SSH em uma máquina de desenvolvimento | CLI | Permite começar no shell remoto já aberto | Credenciais, arquivos e ferramentas precisam existir nessa máquina |
| Repetir um prompt em script ou CI | CLI | opencode run dispensa abrir a interface interativa | Modelo, permissões, tratamento da saída e estado de falha |
| Preferir teclado, mas ainda querer uma conversa interativa | CLI TUI | A CLI também é um aplicativo interativo, não apenas um comando para scripts | Exibição do terminal e projeto selecionado |
| Trocar de interface durante uma tarefa local | Qualquer uma, com uma passagem consciente | A V2 atual oferece um servidor local compartilhado | Os dois clientes precisam usar de fato o mesmo servidor e projeto |
| Corrigir erro de autenticação ou de provedor | Diagnostique primeiro a conexão | Outra interface não corrige uma chave inválida ou uma requisição incompatível | Provedor, 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 é:
- Abra Settings → Providers e depois Show more providers.
- Procure Ofox, conecte o provedor e informe a chave.
- Abra Settings → Models, procure Ofox e habilite o modelo desejado.
- 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.

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.
| Item | O que conferir na passagem | Por que importa |
|---|---|---|
| Arquivos | Mesmo caminho absoluto do projeto e conteúdo atual dos arquivos | Pastas com o mesmo nome podem conter trabalhos diferentes |
| Servidor | Ambos os clientes apontam para o serviço esperado | Um serviço privado ou remoto não é automaticamente o serviço local compartilhado |
| Sessão | Selecione a sessão desejada, não apenas a mais recente | O histórico recente pode pertencer a outra tarefa |
| Modelo | Compare a seleção exata de provedor e modelo | Um nome de exibição familiar não comprova a mesma rota |
| Permissões | Revise o que a tarefa pode ler, editar e executar | Trocar de interface não autoriza ampliar o acesso |
| Ferramentas e ambiente | Confira as ferramentas na máquina onde ocorre a execução | Ter 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.
- Extraia o arquivo duas vezes em pastas separadas, como
desktop-checkecli-check. - Em cada pasta, execute
python3 -m unittest -v. Se seu sistema inicia Python 3 compython, use esse comando. - A versão inicial deve apresentar dois testes com falha entre quatro. Registre essa referência antes de envolver um agente.
- Abra
desktop-checkno Desktop e inicie a CLI emcli-check. Use o mesmo provedor/modelo e permissões equivalentes. - 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
| Sintoma | Primeira verificação | Próxima ação |
|---|---|---|
opencode não é encontrado | Instalação e PATH do shell | Verifique o método da versão escolhida; reabra o shell se o PATH mudou |
| Um comando copiado rejeita um argumento | opencode --version e o --help desse comando | Use a sintaxe da geração instalada antes de trocar credenciais |
| Provedor conectado, mas modelo ausente | Visibilidade do modelo, ID do provedor e ID do modelo | Confira 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 mostra | Caminho do projeto, conta e servidor | Liste sessões no projeto correto e confira o estado do serviço |
| A requisição retorna 401 | Origem da credencial e endpoint de destino | Siga o guia de autenticação e erros da Ofox; não cole segredos em relatos de erro |
| A requisição retorna 429 | Limites de taxa e informações de nova tentativa retornadas | Use 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 falham | Capacidade do modelo, protocolo e formato do resultado da ferramenta | Use 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.


