Permissões do OpenCode 2: migre da V1 e restaure a confirmação de acesso externo

Adicione uma regra explícita external_directory com effect: "ask" para restaurar as confirmações de acesso a diretórios externos após atualizar para o OpenCode 2. Em 2026-10-31, o guia oficial de migração documentava allow como padrão da V2, em vez do ask da V1. Mantenha a configuração V1 compatível até estar pronto para converter suas regras no array ordenado permissions da V2.

Este guia apresenta uma configuração base para programação interativa e uma sequência de validação que usa o OpenCode v2.2.0 como referência. Os resultados esperados vêm da documentação e do código-fonte marcado com a versão, não de um teste com uma instalação em execução.

Por que a V2 permite caminhos externos se verificações sem correspondência usam ask?

As regras internas também participam da avaliação. Portanto, a ausência de uma regra sua não significa que nenhuma regra corresponda à operação.

Segundo a seção Defaults da V2, todo agente começa com uma regra de permissão com curingas. Essa regra contém action: "*", resource: "*" e effect: "allow". As regras base seguintes pedem aprovação para ler *.env e *.env.*, e depois permitem *.env.example. Os agentes incluídos podem adicionar restrições.

Assim, leituras, edições, comandos shell e verificações de diretórios externos comuns já têm uma regra base correspondente. O resultado de fallback ask só se aplica quando não há correspondência em todo o conjunto avaliado. Não interprete a ausência de ajustes próprios de read ou edit como uma exigência de aprovação.

A aprovação do diretório externo e a aprovação da operação de arquivo continuam separadas. OpenCode considera a Location ativa e a árvore de trabalho do projeto, exceto quando essa árvore coincide com a raiz do sistema de arquivos. Para caminhos fora dessas duas áreas, verifica external_directory antes de read ou edit. Aqui, Location significa o local de trabalho ativo. Um arquivo externo pode passar pela verificação do limite e ainda encontrar uma restrição de leitura ou edição.

Essa sequência vem do mecanismo de verificação de diretórios, não da posição de ações com nomes diferentes no array. Mover uma regra external_directory para antes de uma regra read não estabelece essa ordem de verificação.

Dá para manter a configuração V1 e quais nomes mudam?

Sim. O formato nativo da V2 é opcional. OpenCode normaliza a configuração V1 compatível sem exigir que você reescreva os arquivos originais. As instruções de migração recomendam verificar modelos, credenciais, agentes, permissões e servidores MCP existentes antes de converter tudo.

Na V1, as decisões de permissão são agrupadas por ferramenta:

{
  "permission": {
    "bash": {
      "git push *": "ask"
    },
    "edit": "allow"
  },
  "tools": {
    "websearch": false
  }
}

A conversão documentada para a V2 expressa esses ajustes explícitos como regras ordenadas:

{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

Cada regra exige três campos de texto: action, resource e effect. allow deixa a operação continuar sem perguntar, deny a bloqueia e ask aguarda uma decisão no cliente.

Esse exemplo converte os ajustes mostrados; não é a configuração base recomendada abaixo. Ele ainda permite edições e não restaura as confirmações para diretórios externos.

Os mapeamentos de ações são bash → shell, task → subagent e write/patch → edit. Na V2, edit controla os caminhos de destino usados pelas operações edit, write e patch. subagent compara um ID de agente; shell compara strings de comandos produzidas pelo analisador. A referência de ações também informa que doom_loop e lsp não são ações de permissão atuais do V2 Core.

Revise os ajustes de nível superior, as definições de agentes e os scripts que geram configuração. Não substitua essas palavras em todos os arquivos sem considerar o contexto. Após uma conversão planejada, evite deixar definições de permissões V1 e V2 que entrem em conflito.

Use uma configuração base conservadora de permissões V2

Para programação interativa, exija aprovação antes de acessar caminhos externos, executar comandos shell ou editar arquivos. Permita consultas comuns do Git, negue os comandos push correspondentes e bloqueie a leitura de arquivos de ambiente, exceto os de exemplo.

Use opencode.jsonc na raiz do projeto para ajustes específicos do repositório. Use ~/.config/opencode/opencode.jsonc para a configuração do seu usuário. OpenCode também aceita as variantes .json; a referência de configuração descreve os locais disponíveis.

Integre este array à configuração existente. Preserve os ajustes do provedor, as definições de agentes e as restrições atuais, em vez de substituir o arquivo inteiro.

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" }
  ]
}

A exceção para .env.example aparece intencionalmente depois das duas proibições de leitura. Use essa exceção apenas para arquivos com exemplos sem segredos.

Ações não especificadas continuam herdando seus padrões efetivos. Essa configuração não bloqueia todas as ferramentas MCP, não impede toda forma possível de fazer push nem isola o sistema de arquivos do host. As restrições de read também não impedem que comandos shell leiam os mesmos arquivos.

O aviso sobre shell explica que os comandos mantêm os privilégios do usuário do host. A identificação dos diretórios envolvidos é uma tentativa, não uma garantia de cobertura completa. Revise os comandos antes de aprová-los e use controles separados de shell quando as regras de operações de arquivo forem insuficientes.

Para outro cliente, consulte o guia de permissões do Claude Code para segredos e Git. Não reutilize nele a sintaxe de configuração do OpenCode.

Coloque as exceções depois das regras que elas substituem

A ordem importa entre regras que correspondem à mesma ação e ao mesmo recurso. Uma correspondência posterior substitui a decisão anterior. Um curinga na ação pode abranger vários nomes de ações.

Na configuração base, shell: "*" exige aprovação inicialmente. As regras seguintes, git status * e git diff *, permitem esses comandos. A regra git push * nega os comandos push correspondentes.

Um padrão de shell terminado em * também corresponde ao comando sem argumentos. Por isso, git status * cobre tanto git status quanto git status --short.

A referência de correspondência define curingas que são comparados com o valor inteiro. * corresponde a zero ou mais caracteres, incluindo /; ? corresponde a um caractere. Os separadores dos caminhos são normalizados para barras, e a comparação no Windows ignora diferenças entre maiúsculas e minúsculas.

Operações com vários recursos exigem outra etapa. Primeiro, determine a última regra correspondente de cada recurso. Se algum resultado for uma negação, a operação será bloqueada; caso contrário, qualquer exigência de aprovação faz o cliente perguntar. Comandos shell compostos podem produzir vários recursos. Permitir um comando Git não autoriza toda a sequência.

Adicione um diretório externo confiável com cuidado

Configure separadamente o acesso ao diretório confiável e as operações sobre seus arquivos. Estas regras opcionais complementam a configuração base; não a substituem:

[
  { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "edit", "resource": "~/projects/reference/*", "effect": "deny" }
]

Coloque a permissão de acesso externo depois da regra geral external_directory com ask. Coloque a permissão de leitura antes das proibições para arquivos de ambiente, para manter essas restrições. Coloque a proibição de edição depois da regra geral que pede aprovação para editar.

As regras de diretórios aceitam referências iniciais ao diretório pessoal, como ~/, para essas ações sobre caminhos. Os recursos de shell permanecem como texto original do comando e não recebem essa expansão ao carregar a configuração.

A proibição de edição bloqueia operações controladas por edit, incluindo as ferramentas write e patch. Ela não bloqueia alterações feitas pelo shell. Mantenha restrições separadas de shell e revise qualquer aprovação que possa permitir mudanças nesses arquivos.

Migre a configuração e valide com arquivos de teste

Faça backup dos arquivos que você usa, peça uma proposta de alterações e valide a configuração aceita em um projeto descartável. Comece com um cliente V2 instalado e uma conexão funcional com o provedor e o modelo.

Revise a migração proposta antes de aplicá-la

Faça backup da configuração global e do projeto, incluindo as definições de agentes em .opencode/agents/. A documentação sobre locais dos agentes também inclui definições do usuário em ~/.config/opencode/agents/.

Trate plugins, integrações com a API do servidor e ajustes do terminal separadamente. O guia de migração identifica mudanças incompatíveis nessas áreas.

Envie ao OpenCode este prompt. Ele pede uma revisão e a apresentação das alterações antes de modificar arquivos:

Read the official OpenCode V1 migration and V2 permissions documentation.

Inspect my global, project, and agent permission configuration.
Do not modify any files yet.

Propose native V2 permissions rules.
Preserve unrelated settings and existing restrictions.
Map bash to shell, task to subagent, and write and patch to edit where applicable.
Identify unsupported fields and competing V1/V2 definitions.
Restore external_directory approval without weakening existing deny rules.
Use the baseline's shell and edit approval rules unless existing rules are stricter.
Put environment-file denies before the .env.example exception.
Show the complete proposed diff and explain every behavior change.
Wait for approval before applying it.

Confira o resultado combinado, não apenas o arquivo do projeto. As permissões específicas do agente vêm depois das regras de nível superior já resolvidas. Por isso, uma permissão posterior do agente pode substituir uma proibição comum de nível superior.

Para restrições impostas pela organização, consulte as políticas do OpenCode. Elas podem bloquear uma verificação depois da avaliação das permissões do agente e das aprovações salvas. Um array comum de permissões não equivale a uma restrição imposta pelo administrador.

Depois de aceitar as alterações, recarregue a configuração com opencode reload. A referência da CLI documenta esse comando; verifique os avisos de configuração antes de continuar.

Faça uma rodada de validação

Use a v2.2.0 como versão de referência para estes resultados esperados, com o agente integrado build. A tabela pressupõe que a configuração base esteja ativa, sem regras conflitantes do agente, aprovações salvas ou políticas adicionais.

Crie arquivos de teste sem dados sensíveis em Bash:

lab=$(mktemp -d)
mkdir -p "$lab/project" "$lab/outside"
git -C "$lab/project" init -q
printf 'ordinary fixture\n' > "$lab/project/README.md"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env.example"
printf 'outside fixture\n' > "$lab/outside/fixture.txt"
cd "$lab/project"

Salve a configuração base no opencode.jsonc desse projeto e execute opencode. Selecione build por meio de /agents, conforme o guia da interface de terminal.

Peça ao agente que tente cada operação separadamente, usando a ferramenta indicada. Comandos executados manualmente no terminal não substituem as verificações de permissões do agente.

Operação do agente	Resultado esperado de permissão
Ler README.md com read	Permitido pela regra base de leitura
Ler ../outside/fixture.txt com read	Pede aprovação para o diretório externo; a leitura comum é permitida após a aprovação
Ler .env com read	Negado
Ler .env.example com read	Permitido
Modificar README.md com edit, write ou patch	Pede aprovação pela ação edit
Executar git status, git status --short ou git diff por shell	Permitido
Executar git push por shell	Negado pela regra de shell correspondente
Executar pwd por shell	Pede aprovação

Antes de verificar o push, execute git remote manualmente e confirme que nenhum nome aparece. Não adicione um remoto. Um erro do Git por falta de remoto não demonstra que a regra de permissão bloqueou o comando.

Nos testes de aprovação, escolha Allow once («Permitir uma vez»), não Allow always («Permitir sempre»). As aprovações salvas persistem para o projeto e podem evitar novas perguntas, mas não substituem proibições configuradas. Mantenha a aprovação automática desativada.

Inspecione a solicitação real da ferramenta, a decisão de permissão e as mudanças nos arquivos. Uma promessa do modelo de não fazer push ou não ler um arquivo não comprova que o mecanismo de permissões bloqueou a operação.

Investigue as diferenças antes de flexibilizar uma regra

Verifique primeiro a configuração carregada e o agente selecionado. Os comandos de depuração da CLI incluem opencode debug config e opencode debug agents. Inspecione a saída localmente; não compartilhe credenciais nem configurações sensíveis.

Se a confirmação de acesso externo não aparecer, verifique se o destino está fora tanto da Location quanto da árvore de trabalho do projeto. Depois, confira as aprovações salvas e a aprovação automática. Se uma leitura tiver resultado inesperado, confirme que o agente usou read, não shell.

Se um comando Git for bloqueado, inspecione o recurso produzido pelo analisador e quaisquer subcomandos adicionais. Se .env.example for negado, verifique se uma regra *.env.* posterior ou uma política adicional substitui a exceção pretendida.

Confira separadamente o provedor existente, o ID do modelo, a autenticação e a Base URL. As instruções de integração do OpenCode com BetterToken documentam uma conexão personalizada compatível com OpenAI usando https://www.bettertoken.ai/v1. Essa conexão não substitui a configuração de permissões do OpenCode.

Se a migração também envolver a escolha da ferramenta, compare as configurações e formas de acesso do Cursor e do OpenCode. Para avaliar outro fluxo de trabalho no terminal, use a mesma tarefa descartável com Aider ou OpenCode em um projeto Git.

O que muda com a correção do sistema de arquivos na v2.2.0?

A correção muda como os arquivos do projeto são resolvidos nas verificações de diretórios externos. Ela não muda a recomendação de definir uma regra explícita de aprovação.

As notas da v2.2.0 incluem a mudança para usar o sistema de arquivos do projeto. O PR #59089 explica que projetos remotos ou em memória antes consultavam o disco do host. O autor afirma que projetos locais comuns não são afetados.

Em projetos remotos, repita a verificação do diretório externo no sistema de arquivos real daquele projeto. Os padrões da V2 documentados em 2026-10-31 ainda exigem uma regra explícita external_directory com ask ou deny para impor esse limite.