Permisos

Controla qué acciones requieren aprobación para ejecutarse.

OpenCode usa la configuración permission para decidir si una acción determinada debe ejecutarse automáticamente, solicitarte confirmación o ser bloqueada.

A partir de v1.1.1, la configuración booleana heredada tools está obsoleta y se ha fusionado en permission. La antigua configuración tools todavía se admite por compatibilidad con versiones anteriores.

Acciones

Cada regla de permiso se resuelve a una de las siguientes:

"allow" — ejecutar sin aprobación
"ask" — solicitar aprobación
"deny" — bloquear la acción

Configuración

Puedes establecer permisos globalmente (con *) y sobrescribir herramientas específicas.

opencode.json

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

También puedes establecer todos los permisos a la vez:

opencode.json

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

Reglas Granulares (Sintaxis de Objeto)

Para la mayoría de los permisos, puedes usar un objeto para aplicar diferentes acciones basadas en la entrada de la herramienta.

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"
    }
  }
}

Las reglas se evalúan por coincidencia de patrones, con la última regla coincidente ganando. Un patrón común es poner la regla catch-all "*" primero, y reglas más específicas después.

Comodines

Los patrones de permisos usan coincidencia simple de comodines:

* coincide con cero o más caracteres
? coincide con exactamente un carácter
Todos los demás caracteres coinciden literalmente

Expansión del Directorio Home

Puedes usar ~ o $HOME al inicio de un patrón para referenciar tu directorio home. Esto es particularmente útil para reglas de external_directory.

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

Directorios Externos

Usa external_directory para permitir llamadas a herramientas que tocan rutas fuera del directorio de trabajo donde se inició OpenCode. Esto aplica a cualquier herramienta que tome una ruta como entrada (por ejemplo read, edit, list, glob, grep, y muchos comandos bash).

La expansión home (como ~/...) solo afecta cómo se escribe un patrón. No hace que una ruta externa sea parte del espacio de trabajo actual, por lo que las rutas fuera del directorio de trabajo aún deben permitirse vía external_directory.

Por ejemplo, esto permite acceso a todo bajo ~/projects/personal/:

opencode.json

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

Cualquier directorio permitido aquí hereda los mismos valores predeterminados que el espacio de trabajo actual. Como read tiene por defecto allow, las lecturas también están permitidas para entradas bajo external_directory a menos que se sobrescriba. Agrega reglas explícitas cuando una herramienta deba restringirse en estas rutas, como bloquear ediciones mientras se mantienen las lecturas:

opencode.json

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

Mantén la lista enfocada en rutas confiables, y agrega reglas adicionales de permitir o denegar según sea necesario para otras herramientas (por ejemplo bash).

Permisos Disponibles

Los permisos de OpenCode están organizados por nombre de herramienta, más algunas protecciones de seguridad:

read — leer un archivo (coincide con la ruta del archivo)
edit — todas las modificaciones de archivos (cubre edit, write, patch, multiedit)
glob — globbing de archivos (coincide con el patrón glob)
grep — búsqueda de contenido (coincide con el patrón regex)
list — listar archivos en un directorio (coincide con la ruta del directorio)
bash — ejecutar comandos shell (coincide con comandos parseados como git status --porcelain)
task — lanzar subagentes (coincide con el tipo de subagente)
skill — cargar un skill (coincide con el nombre del skill)
lsp — ejecutar consultas LSP (actualmente no granular)
todoread, todowrite — leer/actualizar la lista de tareas
webfetch — obtener una URL (coincide con la URL)
websearch, codesearch — búsqueda web/código (coincide con la consulta)
external_directory — se activa cuando una herramienta toca rutas fuera del directorio de trabajo del proyecto
doom_loop — se activa cuando la misma llamada a herramienta se repite 3 veces con entrada idéntica

Valores Predeterminados

Si no especificas nada, OpenCode comienza con valores predeterminados permisivos:

La mayoría de los permisos tienen por defecto "allow".
doom_loop y external_directory tienen por defecto "ask".
read es "allow", pero los archivos .env se deniegan por defecto:

opencode.json

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

Qué Hace "Ask"

Cuando OpenCode solicita aprobación, la interfaz ofrece tres resultados:

once — aprobar solo esta solicitud
always — aprobar solicitudes futuras que coincidan con los patrones sugeridos (por el resto de la sesión actual de OpenCode)
reject — rechazar la solicitud

El conjunto de patrones que always aprobaría es proporcionado por la herramienta (por ejemplo, las aprobaciones de bash típicamente ponen en lista blanca un prefijo de comando seguro como git status*).

Agentes

Puedes sobrescribir permisos por agente. Los permisos del agente se fusionan con la configuración global, y las reglas del agente tienen precedencia. Aprende más sobre permisos de agentes.

Nota: Consulta la sección Reglas Granulares (Sintaxis de Objeto) arriba para ejemplos más detallados de coincidencia de patrones.

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"
        }
      }
    }
  }
}

También puedes configurar permisos de agentes en 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.

Consejo: Usa coincidencia de patrones para comandos con argumentos. "grep *" permite grep pattern file.txt, mientras que "grep" solo lo bloquearía. Comandos como git status funcionan para el comportamiento predeterminado pero requieren permiso explícito (como "git status *") cuando se pasan argumentos.

Formateadores Servidores LSP