← Volver al listado de tecnologías ← Índice de OpenCode

Capitulo 4: Configuracion

4 de abril de 2026 Por: Artiko

opencodeaiconfiguracionconfig

Capitulo 4: Configuracion

Archivo opencode.json

El archivo principal de configuración de OpenCode es opencode.json, ubicado en la raíz de tu proyecto. Soporta formato JSON y JSONC (JSON con comentarios), lo que te permite documentar decisiones de configuración directamente en el archivo.

Schema Validation

OpenCode provee un JSON Schema oficial para validación y autocompletado en tu editor:

{
  "$schema": "https://opencode.ai/config.json"
}

Con esto, editores como VS Code, Zed o Neovim te ofrecerán autocompletado inteligente, documentación inline de cada campo, e indicarán errores en la configuración antes de que ejecutes OpenCode. Es altamente recomendable incluir siempre el $schema como primer campo.

Configuracion Completa de Referencia

Este es un ejemplo de opencode.json con todas las opciones principales de v1.3.15:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true
  },
  "share": "manual",
  "snapshot": false,
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  },
  "watcher": {
    "ignore": ["node_modules/**", "dist/**"]
  },
  "enabled_providers": ["anthropic", "openai"],
  "disabled_providers": ["gemini"],
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

Cada uno de estos campos se explica en detalle a lo largo de este capítulo.

Precedencia de Configuracion

OpenCode carga configuración desde múltiples fuentes. Un punto clave es que las configuraciones se fusionan (merge), no se reemplazan. Esto significa que puedes tener una base global y solo sobreescribir campos específicos por proyecto.

La precedencia de menor a mayor prioridad es:

graph LR
    A[1. Config Remota] --> B[2. Config Global]
    B --> C[3. OPENCODE_CONFIG]
    C --> D[4. Config Proyecto]
    D --> E[5. .opencode dirs]
    E --> F[6. CONFIG_CONTENT]
    F --> G[7. Config Administradas]
    G --> H[8. Preferencias macOS MDM]

Config remota (.well-known/opencode): configuración distribuida por la organización via HTTP
Config global (~/.config/opencode/opencode.json): tu configuración personal que aplica a todos los proyectos
Variable de entorno OPENCODE_CONFIG: ruta a un archivo de configuración específico
Config del proyecto (opencode.json en la raíz del proyecto): configuración específica del repositorio
Directorios .opencode: configuración en subdirectorios del proyecto
OPENCODE_CONFIG_CONTENT: contenido de configuración inyectado directamente via variable de entorno
Config administradas: configuraciones gestionadas por herramientas de administración
Preferencias macOS (MDM): máxima prioridad, usado en entornos corporativos con MDM

Como Funciona la Fusion

Cuando OpenCode encuentra la misma clave en múltiples niveles, el nivel de mayor prioridad gana. Pero las claves que solo existen en niveles inferiores se mantienen. Por ejemplo:

Config global (~/.config/opencode/opencode.json):

{
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": "notify",
  "compaction": { "auto": true, "reserved": 5000 }
}

Config del proyecto (opencode.json):

{
  "model": "openai/gpt-4o",
  "compaction": { "reserved": 10000 }
}

Resultado fusionado:

{
  "model": "openai/gpt-4o",
  "autoupdate": "notify",
  "compaction": { "auto": true, "reserved": 10000 }
}

El modelo se sobreescribe, autoupdate se hereda de la global, y en compaction el reserved se sobreescribe pero auto se hereda.

Campos Principales

Modelo

El campo model define qué modelo LLM usa el agente. En v1.3.15 se usa el formato proveedor/modelo:

{
  "model": "anthropic/claude-sonnet-4-5"
}

Ejemplos de modelos válidos:

Proveedor	Modelo	Uso Recomendado
`anthropic/claude-sonnet-4-5`	Claude Sonnet 4.5	Desarrollo general, balance calidad/costo
`anthropic/claude-opus-4`	Claude Opus 4	Tareas complejas, razonamiento profundo
`openai/gpt-4o`	GPT-4o	Alternativa multimodal
`openai/o3`	o3	Razonamiento avanzado
`google/gemini-2.5-pro`	Gemini 2.5 Pro	Contexto largo
`ollama/qwen2.5-coder:32b`	Qwen local	Sin costo, offline

Auto-Update

Controla cómo OpenCode maneja las actualizaciones:

{
  "autoupdate": true
}

Valor	Comportamiento
`true`	Actualiza automáticamente al iniciar
`false`	Nunca actualiza automáticamente
`"notify"`	Notifica que hay nueva versión pero no actualiza

Server

Configuración del servidor HTTP de OpenCode. Las interfaces Desktop, Web e IDE se conectan a este servidor:

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true
  }
}

Campo	Descripción
`port`	Puerto del servidor HTTP (default: 4096)
`hostname`	Dirección de escucha. `0.0.0.0` para acceso en red, `127.0.0.1` solo local
`mdns`	Habilita descubrimiento mDNS para que las interfaces encuentren el servidor automáticamente

Compartir Sesiones

El campo share controla cómo se comparten las sesiones:

{
  "share": "manual"
}

Valor	Comportamiento
`"manual"`	Solo se comparte al ejecutar `/share` explícitamente
`"auto"`	Cada sesión genera un enlace compartido automáticamente
`false`	Deshabilita completamente la funcionalidad de compartir

Snapshots

Los snapshots guardan el estado del proyecto antes de cada cambio del agente, permitiendo rollbacks granulares:

{
  "snapshot": false
}

Cuando está habilitado (true), OpenCode crea un snapshot antes de cada operación de escritura. Esto consume más espacio en disco pero proporciona un historial completo de cambios que va más allá de lo que /undo ofrece.

Compactacion

La compactación reduce el consumo de tokens en sesiones largas:

{
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

Campo	Descripción
`auto`	Compacta automáticamente cuando el contexto supera el umbral
`prune`	Elimina información redundante durante la compactación
`reserved`	Tokens mínimos que siempre se mantienen (información crítica)

Sin compactación automática, en sesiones largas el contexto crece hasta agotar la ventana del modelo. Con auto: true, OpenCode compacta proactivamente manteniendo los reserved tokens más importantes.

Watcher

Configura qué archivos ignora OpenCode al monitorear cambios:

{
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**", "*.lock"]
  }
}

Los patrones usan glob syntax. Es importante ignorar directorios grandes como node_modules o dist para evitar consumo innecesario de recursos y tokens.

Proveedores Habilitados

Controla qué proveedores LLM están disponibles:

{
  "enabled_providers": ["anthropic", "openai"],
  "disabled_providers": ["gemini"]
}

Esto es útil para equipos que quieren estandarizar qué modelos se usan en el proyecto. Si un desarrollador tiene configuradas API keys de múltiples proveedores, disabled_providers impide que se use uno no autorizado.

Instrucciones Adicionales

El campo instructions permite cargar archivos adicionales como contexto para el agente:

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", "docs/architecture.md"]
}

Estos archivos se cargan junto con AGENTS.md al inicio de cada sesión. Es útil para dar contexto sobre convenciones del equipo, guías de contribución, o documentación de arquitectura que el agente debe respetar.

Variables de Sustitucion

OpenCode soporta variables dinámicas en la configuración, lo que permite mantener secretos fuera del archivo de configuración y reutilizar valores del entorno.

Variables de Entorno

Usa {env:NOMBRE} para referenciar variables de entorno:

{
  "model": "{env:OPENCODE_MODEL}"
}

Esto es especialmente útil para:

API keys que no quieres commitear al repositorio
Configuración que varía entre entornos (desarrollo, staging, producción)
Valores que cambian entre máquinas del equipo

Contenido de Archivos

Usa {file:ruta} para incluir el contenido de un archivo externo:

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Casos de uso comunes:

Mantener API keys en archivos separados fuera del repositorio
Cargar prompts de sistema desde archivos Markdown versionados
Configuraciones dinámicas generadas por scripts de CI/CD

La ruta soporta ~ para el directorio home y rutas relativas al proyecto.

Configuracion de la TUI

La interfaz TUI tiene su propio archivo de configuración separado: tui.json. Esto permite personalizar la experiencia visual sin mezclar con la configuración funcional de OpenCode.

{
  "$schema": "https://opencode.ai/tui.json",
  "scroll_speed": 3,
  "theme": "tokyonight",
  "keybinds": {
    "leader": "ctrl+x"
  }
}

Temas Disponibles

OpenCode incluye varios temas de color predefinidos. Algunos de los más populares:

Tema	Descripción
`"tokyonight"`	Inspirado en el tema Tokyo Night de VS Code
`"catppuccin"`	Tonos pastel suaves y agradables
`"dracula"`	Tema oscuro clásico con acentos púrpura
`"gruvbox"`	Colores cálidos retro
`"dark"`	Tema oscuro por defecto
`"light"`	Tema claro para terminales con fondo blanco

Keybinds Personalizados

El campo keybinds permite redefinir atajos de teclado. El leader es una tecla prefijo que activa comandos secundarios:

{
  "keybinds": {
    "leader": "ctrl+x",
    "toggle_agent": "tab",
    "cancel": "ctrl+c",
    "quit": "ctrl+d"
  }
}

Scroll Speed

Controla qué tan rápido se desplaza el panel de output al navegar con las teclas:

{
  "scroll_speed": 3
}

Valores más altos significan scroll más rápido. El default es 1.

Variables de Entorno del Sistema

OpenCode reconoce varias variables de entorno que afectan su comportamiento sin necesidad de archivo de configuración:

Variable	Descripción
`OPENCODE_CONFIG`	Ruta a un archivo de configuración custom
`OPENCODE_CONFIG_CONTENT`	Contenido de configuración inyectado directamente como string
`OPENCODE_DISABLE_AUTOUPDATE`	Deshabilita actualizaciones automáticas
`OPENCODE_SERVER_PASSWORD`	Password para proteger el servidor HTTP
`ANTHROPIC_API_KEY`	API key de Anthropic
`OPENAI_API_KEY`	API key de OpenAI
`GOOGLE_API_KEY`	API key de Google
`HTTP_PROXY` / `HTTPS_PROXY`	Proxy para conexiones de red

Las API keys configuradas via variables de entorno tienen prioridad sobre las configuradas en opencode.json. Esto es una buena práctica de seguridad ya que evita commitear secretos al repositorio.

Ejemplos Practicos

Ejemplo Minimo Funcional

El opencode.json más simple para empezar:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}

Con la variable de entorno ANTHROPIC_API_KEY configurada, esto es todo lo que necesitas.

Ejemplo para Desarrollador Individual

Configuración cómoda para desarrollo diario con compactación y actualizaciones automáticas:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  },
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Ejemplo para Equipo

Configuración estandarizada para un equipo de desarrollo:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": "notify",
  "share": "manual",
  "snapshot": true,
  "enabled_providers": ["anthropic"],
  "disabled_providers": ["openai", "gemini"],
  "compaction": {
    "auto": true,
    "reserved": 8000
  },
  "instructions": ["CONTRIBUTING.md", "docs/architecture.md"],
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", "coverage/**"]
  }
}

Esta configuración:

Estandariza el uso de Anthropic como único proveedor
Notifica de actualizaciones sin instalarlas automáticamente
Habilita snapshots para rollbacks granulares
Carga guías de contribución y arquitectura como contexto adicional

Ejemplo con Modelo Local (Ollama)

Para usar OpenCode sin pagar por APIs, completamente offline:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen2.5-coder:32b",
  "autoupdate": false,
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 4000
  }
}

Requiere tener Ollama corriendo localmente con el modelo descargado:

ollama pull qwen2.5-coder:32b

Los modelos locales son más lentos pero ofrecen privacidad total — tu código nunca sale de tu máquina.

Ejemplo con Variables de Entorno

Para CI/CD donde la configuración viene del entorno:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Configuracion Global

Para definir defaults que apliquen a todos tus proyectos, crea el archivo de configuración global:

mkdir -p ~/.config/opencode

Crea ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": "notify",
  "compaction": {
    "auto": true,
    "reserved": 8000
  }
}

Los proyectos individuales pueden sobreescribir cualquier campo de la configuración global a través de su propio opencode.json. La fusión de configuraciones garantiza que no pierdas settings globales que no sobreescribes explícitamente.

Configuracion Global de TUI

De forma similar, puedes crear un tui.json global:

# ~/.config/opencode/tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "scroll_speed": 2,
  "keybinds": {
    "leader": "ctrl+x"
  }
}

Esta configuración aplica a todas las sesiones de TUI independientemente del proyecto.

Buenas Practicas de Configuracion

Siempre incluir $schema: activa autocompletado y validación en tu editor
API keys en variables de entorno: nunca commitear secretos en opencode.json
Configurar watcher.ignore: excluir directorios grandes ahorra recursos y tokens
Habilitar compactación automática: especialmente si trabajas en sesiones largas
Usar instructions: cargar documentación del proyecto como contexto adicional mejora la calidad de las respuestas
autoupdate: "notify" para equipos: evita incompatibilidades por versiones distintas
Commitear opencode.json: que todo el equipo comparta la misma configuración base

Siguiente: Capitulo 5: Agentes Built-in —>