Permissões

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

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

A partir da v1.1.1, a configuração booleana legada tools está obsoleta e foi mesclada em permission. A antiga configuração tools ainda é suportada para compatibilidade com versões anteriores.

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 sobrescrever 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 diferentes ações 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ões, com a última regra correspondente vencendo. Um padrão comum é colocar a regra catch-all "*" primeiro, e regras mais específicas depois.

Curingas

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

* corresponde a zero ou mais caracteres
? 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 ferramentas 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, list, glob, grep, e muitos comandos bash).

A expansão 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, leituras também são permitidas para entradas sob external_directory a menos que sejam sobrescritas. Adicione regras explícitas quando uma ferramenta deve ser restrita nesses caminhos, como bloquear edições enquanto mantém 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 permitir ou negar conforme necessário para outras ferramentas (por exemplo bash).

Permissões Disponíveis

As permissões do OpenCode são organizadas por nome de ferramenta, mais algumas proteções de segurança:

read — ler um arquivo (corresponde ao caminho do arquivo)
edit — todas as modificações de arquivos (cobre edit, write, patch, multiedit)
glob — globbing de arquivos (corresponde ao padrão glob)
grep — busca de conteúdo (corresponde ao padrão regex)
list — listar arquivos em um diretório (corresponde ao caminho do diretório)
bash — executar comandos shell (corresponde a comandos parseados como git status --porcelain)
task — lançar subagentes (corresponde ao tipo de subagente)
skill — carregar um skill (corresponde ao nome do skill)
lsp — executar consultas LSP (atualmente não granular)
todoread, todowrite — ler/atualizar a lista de tarefas
webfetch — buscar uma URL (corresponde à URL)
websearch, codesearch — busca web/código (corresponde à consulta)
external_directory — acionado quando uma ferramenta toca caminhos fora do diretório de trabalho do projeto
doom_loop — acionado quando a mesma chamada de ferramenta se repete 3 vezes com entrada idêntica

Padrões

Se você não especificar nada, o OpenCode começa com 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 solicitação
always — aprovar solicitações futuras que correspondam aos padrões sugeridos (pelo resto da sessão atual do OpenCode)
reject — rejeitar a solicitação

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

Agentes

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

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 agentes 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 bloquearia. Comandos como git status funcionam para o comportamento padrão, mas requerem permissão explícita (como "git status *") quando argumentos são passados.

Formatadores Servidores LSP