Permisos de OpenCode 2: migra desde V1 y recupera las confirmaciones de acceso externo

Añade una regla explícita external_directory con effect: "ask" para recuperar las confirmaciones de acceso a directorios externos tras actualizar a OpenCode 2. A fecha de 2026-10-31, la guía oficial de migración documenta allow como valor predeterminado en V2, frente a ask en V1. Conserva la configuración V1 compatible hasta que puedas convertir sus reglas al array ordenado permissions de V2.

Esta guía presenta una configuración base para programar de forma interactiva y una comprobación de permisos que toma OpenCode v2.2.0 como referencia. Los resultados esperados proceden de la documentación y del código fuente etiquetado con esa versión, no de una prueba con el cliente en ejecución.

¿Por qué V2 permite rutas externas si una comprobación sin coincidencias usa ask?

Las reglas integradas también participan en la evaluación. Por tanto, que no hayas definido una regla no significa que la comprobación carezca de coincidencias.

Según la sección Defaults de V2, cada agente empieza con una regla de permiso con comodines. Esa regla contiene action: "*", resource: "*" y effect: "allow". Las reglas base posteriores solicitan aprobación para leer *.env y *.env.*, y después permiten *.env.example. Los agentes incluidos pueden añadir restricciones.

Así, las lecturas, ediciones, comandos de shell y comprobaciones de directorios externos habituales ya tienen una regla base coincidente. El resultado de reserva ask solo se aplica cuando no hay coincidencias en todo el conjunto evaluado. No interpretes la ausencia de ajustes propios de read o edit como una exigencia de aprobación.

La aprobación de un directorio externo y la aprobación de una operación de archivo siguen siendo comprobaciones distintas. OpenCode considera la Location activa y el árbol de trabajo del proyecto, salvo cuando ese árbol coincide con la raíz del sistema de archivos. Para rutas fuera de ambas áreas, comprueba external_directory antes de read o edit. Aquí, Location significa la ubicación de trabajo activa. Un archivo externo puede superar la comprobación del límite y seguir sujeto a una restricción de lectura o edición.

Esta secuencia depende del mecanismo de comprobación de directorios, no de la posición de acciones con nombres distintos en el array. Mover una regla external_directory por encima de otra read no establece ese orden de comprobación.

¿Puedes mantener la configuración V1 y qué nombres cambian?

Sí. El formato nativo V2 es opcional. OpenCode normaliza la configuración V1 compatible sin obligarte a reescribir sus archivos originales. Las instrucciones de migración recomiendan comprobar los modelos, credenciales, agentes, permisos y servidores MCP existentes antes de convertirlo todo.

V1 agrupa las decisiones de permisos por herramienta:

{
  "permission": {
    "bash": {
      "git push *": "ask"
    },
    "edit": "allow"
  },
  "tools": {
    "websearch": false
  }
}

La conversión documentada para V2 expresa esos ajustes explícitos como reglas ordenadas:

{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

Cada regla requiere tres campos de texto: action, resource y effect. allow deja continuar sin preguntar, deny bloquea la operación y ask espera una decisión en el cliente.

Este ejemplo convierte los ajustes mostrados; no es la configuración base recomendada más abajo. Sigue permitiendo ediciones y no recupera las confirmaciones para directorios externos.

Las equivalencias de acciones son bash → shell, task → subagent y write/patch → edit. En V2, edit controla las rutas de destino de las operaciones edit, write y patch. subagent compara un ID de agente; shell compara cadenas de comandos producidas por el analizador. La referencia de acciones también indica que doom_loop y lsp no son acciones de permisos actuales de V2 Core.

Revisa los ajustes de nivel superior, las definiciones de agentes y los scripts que generan configuración. No sustituyas estas palabras en todos los archivos sin distinguir su función. Tras una conversión deliberada, evita dejar definiciones de permisos V1 y V2 que compitan entre sí.

Usa una configuración base conservadora de permisos V2

Para programar de forma interactiva, exige aprobación antes de acceder fuera del proyecto, ejecutar comandos de shell o editar archivos. Permite las consultas habituales de Git, bloquea los comandos push coincidentes y deniega la lectura de archivos de entorno, salvo los de ejemplo.

Usa opencode.jsonc en la raíz del proyecto para los ajustes de ese repositorio. Usa ~/.config/opencode/opencode.jsonc para la configuración de tu usuario. OpenCode también acepta las variantes .json; la referencia de configuración describe las ubicaciones admitidas.

Integra este array en la configuración existente. Conserva los ajustes del proveedor, las definiciones de agentes y las restricciones anteriores, en lugar de sustituir todo el archivo.

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" }
  ]
}

La excepción para .env.example aparece intencionadamente después de las dos prohibiciones de lectura. Úsala solo para archivos de ejemplo que no contengan secretos.

Las acciones no especificadas siguen heredando sus valores predeterminados efectivos. Esta configuración no bloquea todas las herramientas MCP, no impide cualquier forma posible de hacer push ni aísla el sistema de archivos del host. Sus restricciones de read tampoco impiden que los comandos de shell lean esos mismos archivos.

La advertencia sobre shell explica que los comandos conservan los privilegios del usuario del host. La detección de los directorios afectados no es exhaustiva. Revisa los comandos antes de aprobarlos y aplica controles de shell separados cuando las reglas de operaciones de archivo no sean suficientes.

Para otro cliente, consulta la guía de permisos de Claude Code para secretos y Git. No reutilices allí la sintaxis de configuración de OpenCode.

Coloca las excepciones después de las reglas que sustituyen

El orden importa entre reglas que coinciden con la misma acción y el mismo recurso. La última coincidencia sustituye la decisión anterior. Un comodín en la acción puede abarcar varios nombres de acciones.

En la configuración base, shell: "*" exige aprobación inicialmente. Las reglas posteriores git status * y git diff * permiten esos comandos. La regla git push * deniega los comandos push que coincidan.

Un patrón de shell que termina en * también coincide con el comando sin argumentos. Por eso, git status * cubre tanto git status como git status --short.

La referencia de coincidencias define comodines que se comparan con el valor completo. * coincide con cero o más caracteres, incluido /; ? coincide con un carácter. Los separadores de las rutas se normalizan a barras inclinadas y, en Windows, la comparación no distingue mayúsculas de minúsculas.

Las operaciones con varios recursos requieren otro paso. Primero se resuelve la última regla coincidente de cada recurso. Si alguna decisión resultante deniega el acceso, se bloquea la operación; de lo contrario, cualquier petición de aprobación obliga a preguntar. Los comandos de shell compuestos pueden producir varios recursos. Permitir un comando Git no autoriza toda la secuencia.

Añade un directorio externo de confianza con cuidado

Configura por separado el acceso al directorio de confianza y las operaciones sobre sus archivos. Estas reglas opcionales se añaden a la configuración base; no la sustituyen:

[
  { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "edit", "resource": "~/projects/reference/*", "effect": "deny" }
]

Coloca el permiso de acceso externo después de la regla general external_directory con ask. Coloca el permiso de lectura antes de las prohibiciones para archivos de entorno, para conservar esas restricciones. Coloca la prohibición de edición después de la regla general que pide aprobación para editar.

Las reglas de directorios admiten referencias iniciales al directorio personal, como ~/, para estas acciones sobre rutas. Los recursos de shell mantienen el texto original del comando y no reciben esa expansión al cargar la configuración.

La prohibición de edición bloquea las operaciones controladas por edit, incluidas las herramientas write y patch. No bloquea modificaciones realizadas desde el shell. Mantén restricciones de shell independientes y revisa cualquier aprobación que pueda permitir cambios en esos archivos.

Migra la configuración y valídala con archivos de prueba

Haz una copia de los archivos que utilizas, solicita una propuesta de cambios y comprueba la configuración aceptada en un proyecto desechable. Antes de empezar, necesitas un cliente V2 instalado y una conexión operativa con el proveedor y el modelo.

Revisa la migración propuesta antes de aplicarla

Haz una copia de la configuración global y del proyecto, incluidas las definiciones de agentes en .opencode/agents/. La documentación sobre ubicaciones de agentes también incluye definiciones de usuario en ~/.config/opencode/agents/.

Gestiona por separado los plugins, las integraciones con la API del servidor y los ajustes del terminal. La guía de migración señala cambios incompatibles en esas áreas.

Envía a OpenCode este prompt. Le pide revisar y mostrar los cambios antes de modificar archivos:

Read the official OpenCode V1 migration and V2 permissions documentation.

Inspect my global, project, and agent permission configuration.
Do not modify any files yet.

Propose native V2 permissions rules.
Preserve unrelated settings and existing restrictions.
Map bash to shell, task to subagent, and write and patch to edit where applicable.
Identify unsupported fields and competing V1/V2 definitions.
Restore external_directory approval without weakening existing deny rules.
Use the baseline's shell and edit approval rules unless existing rules are stricter.
Put environment-file denies before the .env.example exception.
Show the complete proposed diff and explain every behavior change.
Wait for approval before applying it.

Comprueba el resultado combinado, no solo el archivo del proyecto. Los permisos específicos del agente se aplican después de las reglas de nivel superior ya resueltas. Por tanto, un permiso posterior del agente puede sustituir una prohibición ordinaria de nivel superior.

Para restricciones que una organización deba imponer, consulta las políticas de OpenCode. Estas pueden bloquear una comprobación después de evaluar los permisos del agente y las aprobaciones guardadas. Un array ordinario de permisos no equivale a una restricción impuesta por el administrador.

Tras aceptar los cambios, recarga la configuración con opencode reload. La referencia de CLI documenta este comando; revisa las advertencias de configuración antes de continuar.

Ejecuta una ronda de validación

Usa v2.2.0 como versión de referencia para estos resultados esperados, con el agente integrado build. La tabla supone que la configuración base está activa, sin reglas de agente contradictorias, aprobaciones guardadas ni políticas adicionales.

Crea archivos de prueba sin información sensible en Bash:

lab=$(mktemp -d)
mkdir -p "$lab/project" "$lab/outside"
git -C "$lab/project" init -q
printf 'ordinary fixture\n' > "$lab/project/README.md"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env.example"
printf 'outside fixture\n' > "$lab/outside/fixture.txt"
cd "$lab/project"

Guarda la configuración base en opencode.jsonc dentro de este proyecto y ejecuta opencode. Selecciona build mediante /agents, como describe la guía de la interfaz de terminal.

Pide al agente que intente cada operación por separado mediante la herramienta indicada. Los comandos que ejecutas manualmente en el terminal no sustituyen las comprobaciones de permisos del agente.

Operación del agente	Resultado esperado de permisos
Leer README.md con read	Permitido por la regla base de lectura
Leer ../outside/fixture.txt con read	Se solicita aprobación para el directorio externo; la lectura normal se permite tras aprobar
Leer .env con read	Denegado
Leer .env.example con read	Permitido
Modificar README.md con edit, write o patch	Se solicita aprobación mediante edit
Ejecutar git status, git status --short o git diff mediante shell	Permitido
Ejecutar git push mediante shell	Denegado por la regla de shell coincidente
Ejecutar pwd mediante shell	Se solicita aprobación

Antes de comprobar el push, ejecuta git remote tú mismo y confirma que no muestra ningún nombre. No añadas un remoto. Un error de Git por falta de remoto no demuestra que los permisos hayan bloqueado el comando.

En las pruebas de aprobación, elige Allow once («Permitir una vez») en lugar de Allow always («Permitir siempre»). Las aprobaciones guardadas persisten para el proyecto y pueden evitar preguntas posteriores, pero no sustituyen prohibiciones configuradas. Mantén desactivada la aprobación automática.

Inspecciona la solicitud real de la herramienta, la decisión de permisos y los cambios en los archivos. Que el modelo prometa no hacer push o no leer un archivo no demuestra que el motor de permisos haya bloqueado la operación.

Investiga las diferencias antes de flexibilizar una regla

Comprueba primero la configuración cargada y el agente seleccionado. Los comandos de depuración de CLI incluyen opencode debug config y opencode debug agents. Revisa su salida localmente; no compartas credenciales ni configuración sensible.

Si falta la confirmación de acceso externo, comprueba que el destino quede fuera tanto de la Location como del árbol de trabajo del proyecto. Después revisa las aprobaciones guardadas y la aprobación automática. Si una lectura produce un resultado inesperado, confirma que el agente utilizó read, no shell.

Si se bloquea un comando Git, inspecciona el recurso que generó el analizador y los subcomandos adicionales. Si se deniega .env.example, comprueba si una regla *.env.* posterior o una política adicional sustituye la excepción prevista.

Revisa por separado el proveedor existente, el ID del modelo, la autenticación y la Base URL. Las instrucciones de integración de OpenCode con BetterToken documentan una conexión personalizada compatible con OpenAI mediante https://www.bettertoken.ai/v1. Esa conexión no sustituye la configuración de permisos de OpenCode.

Si la migración también implica elegir herramienta, compara la configuración y las vías de acceso de Cursor y OpenCode. Para evaluar otro flujo de trabajo en terminal, utiliza la misma tarea desechable con Aider u OpenCode en un proyecto Git.

¿Qué cambia con la corrección del sistema de archivos en v2.2.0?

La corrección cambia cómo se resuelven los archivos del proyecto al comprobar directorios externos. No cambia la recomendación de definir una regla explícita de aprobación.

Las notas de v2.2.0 incluyen el cambio para usar el sistema de archivos del proyecto. El PR #59089 explica que los proyectos remotos o en memoria antes consultaban el disco del host. Su autor afirma que los proyectos locales normales no se ven afectados.

En proyectos remotos, repite la comprobación del directorio externo contra el sistema de archivos real de ese proyecto. Los valores predeterminados de V2 documentados el 2026-10-31 siguen exigiendo una regla explícita external_directory con ask o deny para imponer ese límite.