Guia opencode.jsonc: 7 checagens antes do commit

A resposta útil não é apenas onde colocar o arquivo. Use opencode.jsonc para ajustes revisáveis e sem segredos, deixe credenciais fora do repositório, entenda como configuração global e de projeto se combinam e valide provider, modelos, permissões e rollback.

A documentação oficial informa suporte a JSON e JSONC. Comentários devem explicar por que o ajuste existe, quem é o responsável e qual comando confirma o comportamento.

Não guarde segredos no arquivo. Modelos, shell, ferramentas, permissões e caminhos do projeto podem ficar na configuração; API keys, tokens, URLs privadas e senhas de proxy ficam fora do repositório.

OpenCode mescla arquivos de configuração em vez de substituí-los por completo. Preferências globais e regras de projeto podem coexistir, exceto quando a mesma chave é sobrescrita.

Configuração global serve para hábitos pessoais. Configuração de projeto serve para regras revisáveis pelo time: modelo, caminhos ignorados, comandos, MCP e permissões.

Copie IDs de modelo dos docs atuais ou do painel do provider. JSON válido não garante que o ID funcione em uma requisição real.

Use modelo principal e modelo pequeno só com motivo claro: custo, latência, contexto, disponibilidade local ou compliance. Quando o motivo mudar, revise o arquivo.

Permissões exigem mais cuidado. Mantenha edições e comandos em ask até provar quais ações são repetidas, reversíveis e de baixo risco.

Instalações, exclusões, migrações, deploys, push, segredos e pastas externas devem permanecer em deny ou revisão explícita. Exceções de agent ou MCP ficam perto do papel que as exige.

Adicione a URL do schema oficial para validação e autocomplete. Isso não substitui revisão humana, mas evita chaves erradas e formatos inválidos.

Depois, revise cada chave: é não secreta, pertence ao projeto, tem comentário útil e ainda corresponde à versão atual?

Antes do commit, teste em um repositório de baixo risco. Inicie OpenCode, liste modelos, leia arquivo, faça edição pequena, execute comando esperado e confirme uma ação bloqueada.

Registre sistema, shell, provider, modelo, comando e rollback. Assim a configuração vira uma base reproduzível.

1. Criar arquivo mínimoComece com schema, modelo e postura de permissão revisada.
2. Validar sintaxeUse schema do editor ou ferramenta JSONC.
3. Resolver camadasVeja se vence global, projeto, caminho customizado ou gerenciado.
4. Rodar tarefa pequenaLeia arquivo, faça edição inofensiva e execute comando conhecido.
5. Testar denyTente uma ação bloqueada e confirme que não roda.
6. Registrar rollbackDocumente como remover a regra ou iniciar sem o arquivo.

Se falhar, isole camadas: sintaxe JSONC, diretório atual, raiz Git, overrides globais, overrides de projeto, variáveis, provider e permissões.

No Windows, localização do arquivo e shell são assuntos diferentes. Uma configuração válida falha se o terminal não vê variáveis ou se o shell configurado não existe.

Inclua também uma revisão periódica quando nomes de providers, IDs de modelos, regras de permissão ou requisitos de segurança mudarem. Assim o opencode.jsonc continua sendo um artefato de equipe verificável, não uma exceção antiga herdada por acaso.