Guía de configuración opencode.jsonc: 7 comprobaciones antes de hacer commit

La respuesta útil no es solo dónde guardar el archivo. Usa opencode.jsonc para ajustes no secretos y revisables, deja las credenciales fuera del repositorio, entiende cómo se combinan la configuración global y la del proyecto, y valida provider, modelos, permisos y rollback antes de compartirlo con el equipo.

La documentación oficial indica soporte para JSON y JSONC, así que los comentarios sirven para explicar por qué existe cada ajuste. Úsalos como notas operativas: propietario, fecha de prueba y comando que confirma el comportamiento.

No guardes secretos en el archivo. Modelos, shell, herramientas, permisos y rutas del proyecto pueden ir en la configuración; claves API, tokens, base URLs privadas y credenciales de proxy deben quedarse en variables de entorno o en el flujo del provider.

OpenCode combina archivos de configuración en vez de reemplazarlos por completo. Por eso una preferencia global puede convivir con una regla de proyecto, y solo una clave conflictiva será sobreescrita por una capa posterior.

La configuración global funciona para hábitos personales. La configuración de proyecto funciona mejor para reglas revisables por el equipo: modelo predeterminado, rutas ignoradas, postura de comandos, MCP y permisos.

Copia IDs de modelo desde la documentación actual o el panel del provider. Un JSON válido puede fallar si el ID no existe o si el provider usa otro nombre operativo.

Define un modelo principal y uno pequeño solo si hay una razón clara: coste, latencia, contexto, disponibilidad local o cumplimiento. Cuando cambie la razón, revisa la configuración.

Los permisos son la zona de mayor riesgo. Mantén ediciones y comandos en ask hasta comprobar qué acciones son repetidas, reversibles y de bajo impacto.

Instalaciones, borrados, migraciones, deploys, push, secretos y carpetas externas deben seguir en deny o revisión explícita. Una excepción para agent o MCP debe quedar cerca de ese rol o integración.

Añade la URL del schema oficial para obtener autocompletado y validación. No sustituye una revisión de seguridad, pero detecta claves mal escritas y formas de valor incorrectas.

Después del schema, revisa si cada clave es no secreta, si el comentario sigue siendo correcto y si el ajuste pertenece al repositorio o a una preferencia personal.

Antes del commit, prueba el archivo en un repositorio de bajo riesgo. Inicia OpenCode, lista modelos, lee un archivo, haz una edición pequeña, ejecuta un comando esperado y confirma que una acción bloqueada se detiene.

Guarda la evidencia: sistema operativo, shell, provider, modelo, comando probado y paso de rollback. Así el archivo se convierte en una línea base reproducible.

1. Crear un archivo mínimoEmpieza con schema, modelo y una postura de permisos revisada.
2. Validar sintaxisUsa schema del editor o herramienta compatible con JSONC.
3. Resolver capasComprueba si gana configuración global, proyecto, ruta personalizada o administrada.
4. Ejecutar una tarea pequeñaLee un archivo, edita algo inocuo y ejecuta un comando conocido.
5. Probar denyIntenta una acción bloqueada y confirma que no se ejecuta.
6. Registrar rollbackDocumenta cómo quitar la regla o iniciar sin ese archivo.

Si algo falla, aísla capas: sintaxis JSONC, directorio actual, raíz Git, overrides globales, overrides de proyecto, variables de entorno, provider y permisos.

En Windows separa ubicación del archivo y comportamiento del shell. Una configuración válida puede fallar si la terminal integrada no ve variables del provider o si el shell configurado no existe.