Permisos

Controla qué acciones requieren aprobación para ejecutarse.

OpenCode usa la configuración permission para decidir si una acción dada debe ejecutarse automáticamente, pedirte aprobación o ser bloqueada.

A partir de v1.1.1, la configuración booleana heredada tools está obsoleta y se ha fusionado con permission. La antigua configuración tools aún es compatible por retrocompatibilidad.

Acciones

Cada regla de permiso se resuelve en una de:

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

Configuración

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

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

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

{
  "$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 según la entrada de la herramienta.

{
  "$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 patrón, y gana la última regla coincidente. Un patrón común es poner la regla comodín "*" primero y las reglas más específicas después.

Comodines

Los patrones de permisos usan coincidencia de comodines simple:

• * coincide con cero o más de cualquier carácter
• ? 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 hacer referencia a tu directorio home. Esto es particularmente útil para las reglas 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 se aplica a cualquier herramienta que reciba una ruta como entrada (por ejemplo read, edit, glob, grep y muchos comandos bash).

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

Por ejemplo, esto permite el acceso a todo lo que hay bajo ~/projects/personal/:

{
  "$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. Dado que el valor predeterminado de read es allow, también se permiten las lecturas para las entradas bajo external_directory a menos que se anulen. Agrega reglas explícitas cuando una herramienta deba restringirse en estas rutas, como bloquear las ediciones mientras se mantienen las lecturas:

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

Mantén la lista enfocada en rutas de confianza y agrega reglas allow o deny adicionales según sea necesario para otras herramientas (por ejemplo bash).

Permisos disponibles

Los permisos de OpenCode se identifican por nombre de herramienta, más un par de salvaguardas de seguridad:

• read — leer un archivo (coincide con la ruta del archivo)
• edit — todas las modificaciones de archivos (cubre edit , write , patch )
• glob — globbing de archivos (coincide con el patrón glob)
• grep — búsqueda de contenido (coincide con el patrón regex)
• bash — ejecutar comandos de shell (coincide con comandos analizados como git status --porcelain )
• task — lanzar subagentes (coincide con el tipo de subagente)
• skill — cargar una skill (coincide con el nombre de la skill)
• lsp — ejecutar consultas LSP (actualmente no granular)
• question — hacer preguntas al usuario durante la ejecución
• webfetch — obtener una URL (coincide con la URL)
• websearch — búsqueda web (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 una herramienta se repite 3 veces con una entrada idéntica

Valores predeterminados

Si no especificas nada, OpenCode parte de valores predeterminados permisivos:

• La mayoría de los permisos tienen como valor predeterminado "allow" .
• doom_loop y external_directory tienen como valor predeterminado "ask" .
• read es "allow" , pero los archivos .env se deniegan de forma predeterminada:

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

Qué hace "Ask"

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

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

El conjunto de patrones que always aprobaría lo proporciona la herramienta (por ejemplo, las aprobaciones de bash suelen incluir en la lista de permitidos un prefijo de comando seguro como git status*).

Agentes

Puedes anular permisos por agente. Los permisos del agente se fusionan con la configuración global, y las reglas del agente tienen prioridad. Más información sobre los permisos de los agentes.

Nota: Consulta la sección Reglas granulares (sintaxis de objeto) anterior para ver ejemplos más detallados de coincidencia de patrones.

{
  "$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 los permisos de los agentes en Markdown:

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

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