Permissões

Controle quais ações exigem aprovação para serem executadas.

O OpenCode usa a config permission para decidir se uma determinada ação deve ser executada automaticamente, solicitar sua aprovação ou ser bloqueada.

A partir da v1.1.1, a config booleana legada tools está obsoleta e foi mesclada em permission. A config antiga tools ainda é suportada para compatibilidade retroativa.

Ações

Cada regra de permissão resolve para uma das seguintes:

"allow" — executar sem aprovação
"ask" — solicitar aprovação
"deny" — bloquear a ação

Configuração

Você pode definir permissões globalmente (com *) e substituir ferramentas específicas.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

Você também pode definir todas as permissões de uma vez:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": "allow"
}

Regras Granulares (Sintaxe de Objeto)

Para a maioria das permissões, você pode usar um objeto para aplicar ações diferentes com base na entrada da ferramenta.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

As regras são avaliadas por correspondência de padrão, com a última regra correspondente vencendo. Um padrão comum é colocar a regra coringa "*" primeiro e as regras mais específicas depois dela.

Curingas

Os padrões de permissão usam correspondência simples de curingas:

* corresponde a zero ou mais de qualquer caractere
? corresponde a exatamente um caractere
Todos os outros caracteres correspondem literalmente

Expansão do Diretório Home

Você pode usar ~ ou $HOME no início de um padrão para referenciar seu diretório home. Isso é particularmente útil para regras de external_directory.

~/projects/* -> /Users/username/projects/*
$HOME/projects/* -> /Users/username/projects/*
~ -> /Users/username

Diretórios Externos

Use external_directory para permitir chamadas de ferramenta que tocam caminhos fora do diretório de trabalho onde o OpenCode foi iniciado. Isso se aplica a qualquer ferramenta que receba um caminho como entrada (por exemplo, read, edit, glob, grep e muitos comandos bash).

A expansão do home (como ~/...) afeta apenas como um padrão é escrito. Ela não torna um caminho externo parte do workspace atual, então caminhos fora do diretório de trabalho ainda devem ser permitidos via external_directory.

Por exemplo, isso permite acesso a tudo sob ~/projects/personal/:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

Qualquer diretório permitido aqui herda os mesmos padrões do workspace atual. Como read tem padrão allow, as leituras também são permitidas para entradas sob external_directory, a menos que sejam substituídas. Adicione regras explícitas quando uma ferramenta deve ser restrita nesses caminhos, como bloquear edições enquanto mantém as leituras:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

Mantenha a lista focada em caminhos confiáveis e adicione regras extras de allow ou deny conforme necessário para outras ferramentas (por exemplo, bash).

Permissões Disponíveis

As permissões do OpenCode são indexadas pelo nome da ferramenta, mais alguns guardas de segurança:

read — ler um arquivo (corresponde ao caminho do arquivo)
edit — todas as modificações de arquivo (cobre edit , write , patch )
glob — globbing de arquivos (corresponde ao padrão glob)
grep — busca de conteúdo (corresponde ao padrão regex)
bash — executar comandos de shell (corresponde a comandos analisados como git status --porcelain )
task — iniciar subagentes (corresponde ao tipo de subagente)
skill — carregar uma skill (corresponde ao nome da skill)
lsp — executar consultas LSP (atualmente não granular)
question — fazer perguntas ao usuário durante a execução
webfetch — buscar uma URL (corresponde à URL)
websearch — busca na web (corresponde à consulta)
external_directory — acionada quando uma ferramenta toca caminhos fora do diretório de trabalho do projeto
doom_loop — acionada quando a mesma chamada de ferramenta se repete 3 vezes com entrada idêntica

Padrões

Se você não especificar nada, o OpenCode parte de padrões permissivos:

A maioria das permissões tem padrão "allow" .
doom_loop e external_directory têm padrão "ask" .
read é "allow" , mas arquivos .env são negados por padrão:

opencode.json

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

O Que "Ask" Faz

Quando o OpenCode solicita aprovação, a interface oferece três resultados:

once — aprovar apenas esta requisição
always — aprovar requisições futuras correspondentes aos padrões sugeridos (pelo restante da sessão atual do OpenCode)
reject — negar a requisição

O conjunto de padrões que always aprovaria é fornecido pela ferramenta (por exemplo, aprovações de bash normalmente colocam na whitelist um prefixo de comando seguro como git status*).

Agentes

Você pode substituir permissões por agente. As permissões do agente são mescladas com a config global, e as regras do agente têm precedência. Saiba mais sobre permissões de agente.

Nota: Consulte a seção Regras Granulares (Sintaxe de Objeto) acima para exemplos mais detalhados de correspondência de padrões.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
          "git commit *": "ask",
          "git push *": "deny",
          "grep *": "allow"
        }
      }
    }
  }
}

Você também pode configurar permissões de agente em Markdown:

~/.config/opencode/agents/review.md

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---
 
Only analyze code and suggest changes.

Dica: Use correspondência de padrões para comandos com argumentos. "grep *" permite grep pattern file.txt, enquanto "grep" sozinho o bloquearia. Comandos como git status funcionam para o comportamento padrão, mas exigem permissão explícita (como "git status *") quando argumentos são passados.

Formatadores Servidores LSP