Configuración de permisos de OpenCode

El sistema de permisos de OpenCode se utiliza para controlar qué operaciones pueden ejecutarse automáticamente, cuáles requieren tu aprobación manual y cuáles se bloquearán directamente. Configurar los permisos adecuadamente permite que la IA complete tareas de manera eficiente y, al mismo tiempo, evita que operaciones accidentales dañen el código o filtren archivos sensibles.

Desde v1.1.1, la versión anteriortoolsla configuración booleana ha quedado obsoleta y se ha fusionado enpermissionen. La configuración anterior sigue siendo compatible para mantener la compatibilidad hacia atrás, pero se recomienda migrar a la nuevapermissionsintaxis.

Tres acciones de permiso

Cada regla de permiso se resuelve finalmente en una de las siguientes tres acciones:

Acción Efecto Escenario de aplicación
"allow" Sin aprobación, se ejecuta automáticamente Operaciones de bajo riesgo y alta frecuencia, como leer archivos o ejecutar pruebas
"ask" Muestra un aviso de aprobación para que decidas si permitirlo Operaciones con cierto riesgo, como escribir archivos o ejecutar scripts
"deny" Bloqueado directamente, no se ejecuta ni se muestra aviso Operaciones peligrosas explícitamente no permitidas, como eliminar archivos o hacer push del código

Configuración básica

La configuración de permisos se escribe en el directorio raíz del repositorio (o directorio de configuración del usuario) enopencode.jsonel archivo, usandopermissionel campo para la configuración.

1. Configurar todos los permisos globalmente

La forma más sencilla: usar una cadena para establecer los permisos de todas las operaciones de una sola vez. Es adecuada para comenzar rápidamente o depuraciones temporales:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
"permission": "allow" // todas las operaciones se ejecutan automáticamente, sin mostrar avisos (adecuado para desarrollo local cuando se confía plenamente en la IA)
}

2. Configurar por nombre de herramienta

Usando la sintaxis de objeto, se pueden especificar permisos para diferentes herramientas."*"Es un comodín que indica que coincide con todas las operaciones y normalmente se usa como valor predeterminado de respaldo:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask", // regla de respaldo: todas las herramientas no configuradas individualmente muestran un aviso de forma predeterminada
"bash": "allow", // bash (ejecutar comandos Shell): se permite directamente, sin aviso
"edit": "deny" // edit (modificar archivos): se bloquea directamente
  }
}

Reglas de grano fino (sintaxis de objeto)

Para la mayoría de los permisos, además de establecer una acción uniforme, se puede usarsintaxis de objetopara aplicar diferentes reglas según el contenido específico de entrada de la herramienta. Por ejemplo, parabashla herramienta, se puede distinguir qué comandos se permiten, cuáles requieren aprobación y cuáles se rechazan directamente:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
"*": "ask", // respaldo: todos los comandos bash requieren aprobación por defecto
"git *": "allow", // los comandos que comienzan con git (como git status, git log) se permiten directamente
"npm *": "allow", // los comandos que comienzan con npm (como npm install, npm run build) se permiten directamente
"grep *": "allow", // los comandos de búsqueda grep se permiten directamente
"rm *": "deny" // los comandos de eliminación rm se bloquean directamente (para evitar borrados accidentales)
    },
    "edit": {
"*": "deny", // bloquea toda edición de archivos por defecto
"packages/web/src/content/docs/*.mdx": "allow" // solo permite editar archivos .mdx en el directorio de documentación
    }
  }
}

Orden de coincidencia de reglas: la regla que coincide al final tiene prioridad.Se recomienda colocar la regla comodín"*"al principio como valor predeterminado, y las reglas más específicas después para sobrescribirla. De esta manera, cuanto más específica es una regla, mayor es su prioridad, y la lógica es clara y menos propensa a errores.

Reglas de comodines

Los patrones de permisos admiten coincidencia simple con comodines, con las siguientes reglas:

Comodín Significado Ejemplo
* Coincide con cero o más caracteres arbitrarios (sin cruzar directorios) git *Coincide congit status、git log --onelineesperar
** Coincide con cualquier ruta que cruce directorios ~/projects/**Coincide con todos los archivos y subdirectorios bajo projects
? Coincide exactamente con un carácter arbitrario file?.txtCoincide confile1.txt、fileA.txt
Otros caracteres Coincidencia exacta por valor literal git statusSolo coincide congit status, no coincide con variantes con parámetros

Nota:Para comandos con parámetros, asegúrate de añadir al final*. Por ejemplo"grep *"puede coincidir congrep pattern file.txt, mientras que escribir solo"grep"solo coincide con el comando simple sin parámetros, y en la práctica casi nunca se aplica.

Expansión del directorio principal

Al inicio del patrón se puede usar~o$HOMEpara hacer referencia al directorio principal del usuario actual, OpenCode lo expande automáticamente a la ruta completa:

Ejemplo

// Las tres formas siguientes tienen el mismo efecto: todas se expanden a /Users/username/projects/* (la ruta varía según el sistema)
"~/projects/*"
"$HOME/projects/*"
"/Users/username/projects/*" // escribir la ruta absoluta directamente también es posible, pero no se recomienda (no es lo suficientemente universal)

Permisos de directorio externo (external_directory)

De forma predeterminada, OpenCode solo permite que las herramientas accedanal directorio de trabajo en el que se inicióy sus subdirectorios. Si necesitas acceder a rutas fuera del directorio del proyecto (por ejemplo, otro proyecto o un directorio de configuración compartido), debes hacerlo medianteexternal_directoryautorización explícita.

La expansión del directorio principal (~/...) es solo una forma deescritura simplificada de rutas, y no autoriza automáticamente el acceso a esa ruta. Las rutas fuera del directorio de trabajo aún debenexternal_directorypermitirse explícitamente.

1. Permitir acceso a directorios externos

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow" // permite acceder a todos los archivos y subdirectorios bajo ~/projects/personal/
// ** coincide con subrutas de cualquier nivel
    }
  }
}

2. Permitir lectura pero prohibir edición

Edredónexternal_directoryEl directorio autorizado hereda los permisos predeterminados del espacio de trabajo actual. Dado quereadel valor predeterminado es"allow", después de la autorización, los archivos de ese directorio se pueden leer. Si necesitas restringir aún más alguna operación (por ejemplo, permitir lectura pero prohibir edición), puedes agregar reglas adicionales:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow" // primer paso: autorizar el acceso a ese directorio externo
    },
    "edit": {
"~/projects/personal/**": "deny" // segundo paso: agregar una regla sobre este directorio, permitir lectura pero prohibir edición
    }
  }
}

Todos los elementos de permiso disponibles

Los permisos de OpenCode usan los nombres de las herramientas como clave y cubren todos los tipos: operaciones de archivos, ejecución de comandos, acceso a red, etc.:

Elemento de permiso Operaciones que controla Contenido que coincide con el patrón Valor predeterminado
read Leer contenido de archivos Ruta del archivo (comosrc/index.js） allow（.envexcepto archivos)
edit Todas las modificaciones de archivos, incluyendo edit, write, patch, multiedit Ruta de archivo allow
glob Búsqueda de archivos por comodín (por ejemplo, buscar todos los.tsarchivos) Patrón comodín (por ejemplo,**/*.ts） allow
grep Buscar texto en el contenido de archivos Patrón de expresión regular allow
list Listar archivos en un directorio Ruta de directorio allow
bash Ejecutar comandos de shell Comando completo analizado (por ejemplo,git status --porcelain） allow
task Iniciar subagente Nombre del tipo de subagente allow
skill Cargar habilidad Nombre de la habilidad allow
lsp Ejecutar consulta del servidor de lenguaje LSP Actualmente no se admite configuración de grano fino allow
webfetch Obtener contenido de URL de red URL completa (por ejemplo,https://example.com/api） allow
websearch Búsqueda web Cadena de consulta de búsqueda allow
codesearch Búsqueda de código Cadena de consulta de búsqueda allow
external_directory Acceder a rutas fuera del directorio de trabajo Ruta de directorio externo ask
doom_loop Se activa cuando la misma herramienta se llama 3 veces con la misma entrada (para evitar que la IA se quede en un bucle infinito) — ask

Descripción de permisos predeterminados

Si no configuras ningún permiso, OpenCode utilizará los siguientes valores predeterminados integrados:

  • La mayoría de los permisos de herramientas tienen como valor predeterminado"allow", es decir, se ejecutan automáticamente sin aviso
  • doom_loopyexternal_directoryEl valor predeterminado es"ask", requiere aprobación manual
  • readDe forma predeterminada se permite leer todos los archivos, pero para.envlos archivos relacionados hay protección integrada:

Ejemplo

// Reglas predeterminadas integradas de read de OpenCode (sin necesidad de configuración manual, solo como referencia)
{
  "permission": {
    "read": {
"*": "allow", // Por defecto se permite leer todos los archivos
"*.env": "deny", // Bloquear la lectura de archivos .env (evita la filtración de contraseñas de bases de datos, claves API, etc.)
"*.env.*": "deny", // Bloquear la lectura de variantes como .env.local, .env.production, etc.
"*.env.example": "allow" // Permitir la lectura de .env.example (archivo de ejemplo, sin claves reales)
    }
  }
}

Tres opciones del aviso de aprobación

Cuando el permiso de una operación es"ask", OpenCode mostrará un aviso de aprobación con las siguientes tres opciones:

Opción Efecto Escenario de uso
once (solo una vez) Solo aprueba esta solicitud; la próxima vez que se realice la misma operación, se volverá a mostrar el aviso Permitir temporalmente una operación sin habilitarla de forma permanente
always (permitir siempre) Añade el patrón coincidente de esta operación a la lista blanca; no se volverá a preguntar durante el resto de la sesión actual Confirmar que cierto tipo de operación es seguro y desea que se apruebe automáticamente en esta sesión
reject (rechazar) Rechaza esta solicitud; la operación no se ejecutará Se detecta que la operación es riesgosa y no se desea ejecutarla

Al elegiralways, OpenCode proporcionará automáticamente un patrón de lista blanca sugerido por la herramienta (por ejemplo, al aprobargit statusnormalmente se añadirágit status*a la lista blanca).La lista blanca solo es válida en la sesión actual; se restablecerá al reiniciar OpenCode.

Configurar permisos por separado para el agente

Si utilizas varios agentes en tu flujo de trabajo, puedes sobrescribir la configuración de permisos para cada agente individualmente. Los permisos del agente se combinan con la configuración global, ylas reglas del agente tienen prioridad sobre las reglas globales。

1. Configurar permisos del agente en opencode.json

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
// Permisos globales: las operaciones de git están permitidas, pero se prohíben commit y push
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
"build": { // Agente llamado build
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
"git commit *": "ask", // Sobrescribe lo global: el agente build permite commit, pero requiere aprobación
"git push *": "deny", // Hereda lo global: push sigue prohibido
          "grep *": "allow"
        }
      }
    }
  }
}

2. Configurar permisos del agente en archivos Markdown

Los agentes también se pueden configurar mediante archivos Markdown; los permisos se escriben en el YAML Front Matter en la parte superior del archivo (---la parte comprendida entre los delimitadores):

Ejemplo

# Ruta de archivo: ~/.config/opencode/agents/review.md
---
description: Agente de revisión de código (solo analiza el código, no realiza ninguna modificación)
mode: subagent
permission:
  edit: deny        # Prohibir todas las ediciones de archivos
  bash: ask         # Los comandos bash requieren aprobación
  webfetch: deny    # Prohibir el acceso a URL externas
---

Only analyze code and suggest changes.
# A continuación se muestra el prompt del sistema del agente, que describe sus responsabilidades y normas de comportamiento

Ejemplos de configuración prácticos

Ejemplo 1: Modo conservador (todas las operaciones requieren aprobación)

Adecuado para quienes usan OpenCode por primera vez o trabajan en proyectos importantes; todas las operaciones requieren confirmación manual:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask" // Todas las operaciones de todas las herramientas muestran un aviso de aprobación
  }
}

Ejemplo 2: Configuración común de desarrollo (lectura permitida, escritura requiere aprobación)

Adecuado para el desarrollo diario: permite a la IA leer y buscar código libremente, pero requiere confirmación al modificar archivos y ejecutar comandos:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask", // Respaldo: las herramientas no configuradas individualmente requieren aprobación por defecto
"read": "allow", // Leer archivos: permitido directamente
"glob": "allow", // Búsqueda de archivos por comodín: permitido directamente
"grep": "allow", // Búsqueda de contenido: permitido directamente
"list": "allow", // Listar directorios: permitido directamente
    "bash": {
"*": "ask", // Los comandos bash requieren aprobación por defecto
"git status *": "allow", // Ver el estado de git: permitido
"git log *": "allow", // Ver el registro de git: permitido
"git diff *": "allow", // Ver diferencias de git: permitido
"npm run *": "allow", // Ejecutar scripts de npm: permitido
"npm test *": "allow", // Ejecutar pruebas: permitido
"rm *": "deny" // Eliminar archivos: bloqueado directamente
    }
  }
}

Ejemplo 3: Permitir acceso a múltiples directorios de proyectos

Cuando la IA necesita trabajar en varios directorios de proyectos, autoriza el acceso a directorios externos:

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow", // Permitir acceso al directorio de proyectos personales
"~/projects/work/**": "allow", // Permitir acceso al directorio de proyectos de trabajo
"~/dotfiles/**": "allow" // Permitir acceso al directorio de archivos de configuración
    },
    "edit": {
"~/dotfiles/**": "deny" // Incluso si se permite acceder a dotfiles, se prohíbe editarlos (solo lectura)
    }
  }
}
Otras extensiones