17. Seguridad, privacidad y solución de problemas

Objetivo del tema

Entender qué datos maneja OpenCode y dónde viven, aplicar permisos y buenas prácticas para trabajar con seguridad incluso en código sensible, y aprender a diagnosticar los fallos más comunes usando los registros y comandos de mantenimiento.

17.1 El modelo de privacidad de OpenCode

La base de confianza del proyecto es simple: OpenCode no almacena tu código ni tu contexto de trabajo en servidores ajenos. Todo el trabajo sucede entre tu máquina, tus repositorios y el proveedor de modelos que tú mismo configuras:

Local primero

Sesiones, historiales y snapshots viven en tu directorio de usuario, no en una nube del fabricante del agente.

Compartir es opcional

Nada se publica sin acción explítita (/share) y todo enlace se retira con /unshare.

Tú eliges el destino

Decides qué proveedor recibe tu código; con modelos locales, ninguno.

Matices que sí debes conocer: el contenido de archivos referenciados viaja al proveedor del modelo elegido en cada petición (así funciona cualquier LLM), y algunas tareas internas menores usan un "modelo pequeño" configurable (small_model). Para código confidencial considera modelos locales (tema 5) o revisa las opciones empresariales de residencia de datos.

17.2 Protege tus credenciales y datos locales

El directorio de datos concentra todo lo sensible:

~/.local/share/opencode/
├── auth.json        # claves API y tokens OAuth
├── mcp-auth.json    # credenciales OAuth de servidores MCP
├── log/              # registros (se conservan los 10 más recientes)
└── project/         # sesiones y mensajes por proyecto
  • Aplica permisos restrictivos sobre estos archivos, especialmente en equipos compartidos.
  • Nunca los incluyas en copias de seguridad compartidas ni repositorios.
  • Cuidado con la variable OPENCODE_AUTO_SHARE: comparte sesiones automáticamente; déjala apagada salvo necesidad concreta.
  • Antes de reportar bugs o compartir sesiones, usa la opción de sanitización (opencode export --sanitize) para redactar contenido sensibles.

17.3 Los permisos como barrera de seguridad

El sistema allow/ask/deny del tema 14 es tu herramienta principal de contención. Postura recomendada por escenario:

  • Proyecto sensible: "webfetch": "deny", bash en modo ask con excepciones mínimas (npm test*, git status*), y ediciones permitidas sólo dentro del proyecto.
  • Sesiones de revisión: usa agentes de solo lectura (modo Plan o un subagent propio con edit: deny) cuando el objetivo es analizar y no modificar.
  • Automatización CI/CD: si usas --auto para no bloquear el pipeline, define antes permisos explícitos que nieguen todo lo peligroso: lo no denegado será aprobado automáticamente.
  • Equipos y organizaciones: centraliza políticas en la configuración compartida del repositorio para que todos los agentes nazcan con los mismos límites.

Checklist de seguridad rápida

  • ¿auth.json tiene permisos restrictivos y está fuera de cualquier repositorio?
  • ¿Los secretos del proyecto viven en variables de entorno y no en archivos que el agente pueda leer innecesariamente?
  • ¿El agente corre sobre un repositorio Git limpio (posibilidad de revertir)?
  • ¿Revisaste el diff antes de cada commit?
  • ¿Los MCP habilitados son los estrictamente necesarios?

17.4 Diagnóstico: logs y almacenamiento

Cuando algo falla, los registros son el primer recurso. Se escriben en ~/.local/share/opencode/log/ (en Windows: %USERPROFILE%\.local\share\opencode\log), con nombres por marca de tiempo y conservando los diez más recientes:

opencode --print-logs            # logs en la propia terminal
opencode --log-level DEBUG       # máximo detalle

Para un reinicio completo sin desinstalar, borra los cachés reconstruibles: ~/.cache/opencode (paquetes de proveedores) y, como último recurso, ~/.local/share/opencode (configuración y sesiones locales — perderás credenciales y deberás reautenticarte con /connect).

17.5 Problemas comunes y su solución

Diagnóstico rápido de fallos frecuentes
Síntoma Causa probable Solución
No arranca Error puntual o versión vieja Revisa los logs, prueba --print-logs y actualiza con opencode upgrade.
Fallos de autenticación Credenciales vencidas o red bloqueada Reautentica con /connect; verifica clave válida y acceso de red a la API del proveedor.
ProviderModelNotFoundError Identificador de modelo mal escrito Usa el formato proveedor/modelo exacto; consulta el catálogo con opencode models.
ProviderInitError Configuración inválida o corrupta Valida la sección provider; si persiste, limpia ~/.local/share/opencode y reautentica.
AI_APICallError Paquetes de proveedor desactualizados en caché Borra ~/.cache/opencode y reinicia para re-descargar versiones vigentes.
Portapapeles roto en Linux Falta utilidad de sistema Instala xclip/xsel (X11) o wl-clipboard (Wayland).
Escritorio en blanco (Windows/Linux) Runtime gráfico faltante o compositor Windows: instala WebView2 Runtime. Linux/Wayland: prueba OC_ALLOW_WAYLAND=1 o sesión X11.
App de escritorio inestable al iniciar Plugin conflictivo o caché corrupta Vacía la clave plugin del config global, saca plugins locales y limpia el caché; reactiva uno a uno.

Si nada funciona: el comando opencode uninstall muestra exactamente qué eliminará y admite conservar configuración (-c) o datos (-d). Y para ayuda humana, reporta en github.com/anomalyco/opencode/issues (buscando primero entre issues existentes) o entra al Discord oficial en opencode.ai/discord.

Conclusión: OpenCode ofrece una postura de privacidad sólida por defecto (datos locales, compartición opt-in) y te da las palancas para endurecerla tanto como necesites: permisos granulares, agentes de solo lectura y modelos locales. Combinado con una rutina de diagnóstico simple (logs, caché, reautenticación), podrás resolver casi cualquier incidente sin salir de la terminal. En el próximo tema compararemos OpenCode con sus competidores directos.

Retornar