Configuración

Usando la configuración JSON de OpenCode.

Puedes configurar OpenCode usando un archivo de configuración JSON.

Formato

OpenCode soporta tanto JSON como JSONC (JSON con Comentarios).

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  // Configuración del tema
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

Ubicaciones

Puedes colocar tu configuración en diferentes ubicaciones que tienen diferente orden de precedencia.

Nota: Los archivos de configuración se fusionan, no se reemplazan.

Los archivos de configuración se fusionan, no se reemplazan. Las configuraciones de las siguientes ubicaciones se combinan. Las configuraciones posteriores solo sobrescriben las claves en conflicto. Las configuraciones que no entran en conflicto de todas las fuentes se preservan.

Por ejemplo, si tu configuración global establece theme: "opencode" y autoupdate: true, y tu configuración de proyecto establece model: "anthropic/claude-sonnet-4-5", la configuración final incluirá las tres opciones.

Orden de precedencia

Las fuentes de configuración se cargan en este orden (las fuentes posteriores sobrescriben las anteriores):

Configuración remota (de .well-known/opencode) - valores predeterminados organizacionales
Configuración global (~/.config/opencode/opencode.json) - preferencias del usuario
Configuración personalizada (variable de entorno OPENCODE_CONFIG) - sobrescrituras personalizadas
Configuración del proyecto (opencode.json en el proyecto) - configuraciones específicas del proyecto
Directorios .opencode - agentes, comandos, plugins
Configuración inline (variable de entorno OPENCODE_CONFIG_CONTENT) - sobrescrituras en tiempo de ejecución

Esto significa que las configuraciones del proyecto pueden sobrescribir los valores predeterminados globales, y las configuraciones globales pueden sobrescribir los valores predeterminados organizacionales remotos.

Nota: Los subdirectorios de .opencode y ~/.config/opencode usan nombres en plural: agents/, commands/, modes/, plugins/, skills/, tools/ y themes/. Los nombres en singular (ej. agent/) también se soportan por compatibilidad hacia atrás.

Remota

Las organizaciones pueden proporcionar configuración predeterminada a través del endpoint .well-known/opencode. Esta se obtiene automáticamente cuando te autentificas con un proveedor que lo soporta.

La configuración remota se carga primero, sirviendo como capa base. Todas las demás fuentes de configuración (global, proyecto) pueden sobrescribir estos valores predeterminados.

Por ejemplo, si tu organización proporciona servidores MCP que están deshabilitados por defecto:

Configuración remota de .well-known/opencode

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

Puedes habilitar servidores específicos en tu configuración local:

opencode.json

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Global

Coloca tu configuración global de OpenCode en ~/.config/opencode/opencode.json. Usa la configuración global para preferencias a nivel de usuario como temas, proveedores o atajos de teclado.

La configuración global sobrescribe los valores predeterminados organizacionales remotos.

Por proyecto

Agrega opencode.json en la raíz de tu proyecto. La configuración del proyecto tiene la mayor precedencia entre los archivos de configuración estándar - sobrescribe tanto la configuración global como la remota.

Consejo: Coloca la configuración específica del proyecto en la raíz de tu proyecto.

Cuando OpenCode inicia, busca un archivo de configuración en el directorio actual o recorre hacia arriba hasta el directorio Git más cercano.

Esto también es seguro para hacer commit en Git y usa el mismo esquema que la configuración global.

Ruta personalizada

Especifica una ruta de archivo de configuración personalizada usando la variable de entorno OPENCODE_CONFIG.

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

La configuración personalizada se carga entre la configuración global y la del proyecto en el orden de precedencia.

Directorio personalizado

Especifica un directorio de configuración personalizado usando la variable de entorno OPENCODE_CONFIG_DIR. Este directorio se buscará para agentes, comandos, modos y plugins igual que el directorio estándar .opencode, y debe seguir la misma estructura.

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

El directorio personalizado se carga después de la configuración global y los directorios .opencode, por lo que puede sobrescribir sus configuraciones.

Esquema

El archivo de configuración tiene un esquema definido en opencode.ai/config.json (opens in a new tab).

Tu editor debería poder validar y autocompletar basándose en el esquema.

TUI

Puedes configurar ajustes específicos de TUI a través de la opción tui.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

Opciones disponibles:

scroll_acceleration.enabled - Habilita la aceleración de desplazamiento estilo macOS. Tiene precedencia sobre scroll_speed.
scroll_speed - Multiplicador de velocidad de desplazamiento personalizado (predeterminado: 3, mínimo: 1). Se ignora si scroll_acceleration.enabled es true.
diff_style - Controla el renderizado de diff. "auto" se adapta al ancho del terminal, "stacked" siempre muestra una sola columna.

Aprende más sobre el uso de TUI aquí.

Servidor

Puedes configurar ajustes del servidor para los comandos opencode serve y opencode web a través de la opción server.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

Opciones disponibles:

port - Puerto para escuchar.
hostname - Nombre de host para escuchar. Cuando mdns está habilitado y no se establece hostname, el predeterminado es 0.0.0.0.
mdns - Habilita el descubrimiento de servicios mDNS. Esto permite que otros dispositivos en la red descubran tu servidor OpenCode.
mdnsDomain - Nombre de dominio personalizado para el servicio mDNS. El predeterminado es opencode.local. Útil para ejecutar múltiples instancias en la misma red.
cors - Orígenes adicionales a permitir para CORS cuando se usa el servidor HTTP desde un cliente basado en navegador. Los valores deben ser orígenes completos (esquema + host + puerto opcional), ej. https://app.example.com.

Aprende más sobre el servidor aquí.

Herramientas

Puedes gestionar las herramientas que un LLM puede usar a través de la opción tools.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Aprende más sobre herramientas aquí.

Modelos

Puedes configurar los proveedores y modelos que quieres usar en tu configuración de OpenCode a través de las opciones provider, model y small_model.

opencode.json

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

La opción small_model configura un modelo separado para tareas ligeras como generación de títulos. Por defecto, OpenCode intenta usar un modelo más económico si hay uno disponible de tu proveedor, de lo contrario recurre a tu modelo principal.

Las opciones del proveedor pueden incluir timeout y setCacheKey:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}

timeout - Tiempo de espera de solicitud en milisegundos (predeterminado: 300000). Establece a false para deshabilitar.
setCacheKey - Asegura que siempre se establezca una clave de caché para el proveedor designado.

También puedes configurar modelos locales. Aprende más.

Opciones específicas del proveedor

Algunos proveedores soportan opciones de configuración adicionales más allá de las configuraciones genéricas timeout y apiKey.

Amazon Bedrock

Amazon Bedrock soporta configuración específica de AWS:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}

region - Región de AWS para Bedrock (predeterminado a la variable de entorno AWS_REGION o us-east-1)
profile - Perfil nombrado de AWS de ~/.aws/credentials (predeterminado a la variable de entorno AWS_PROFILE)
endpoint - URL de endpoint personalizado para endpoints VPC. Este es un alias para la opción genérica baseURL usando terminología específica de AWS. Si ambos se especifican, endpoint tiene precedencia.

Nota: Los tokens Bearer (AWS_BEARER_TOKEN_BEDROCK o /connect) tienen precedencia sobre la autenticación basada en perfil. Ver precedencia de autenticación para detalles.

Aprende más sobre la configuración de Amazon Bedrock.

Temas

Puedes configurar el tema que quieres usar en tu configuración de OpenCode a través de la opción theme.

opencode.json

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

Aprende más aquí.

Agentes

Puedes configurar agentes especializados para tareas específicas a través de la opción agent.

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Deshabilitar herramientas de modificación de archivos para agente solo de revisión
        "write": false,
        "edit": false
      }
    }
  }
}

También puedes definir agentes usando archivos markdown en ~/.config/opencode/agents/ o .opencode/agents/. Aprende más aquí.

Agente predeterminado

Puedes establecer el agente predeterminado usando la opción default_agent. Esto determina qué agente se usa cuando no se especifica ninguno explícitamente.

opencode.json

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

El agente predeterminado debe ser un agente primario (no un subagente). Puede ser un agente incorporado como "build" o "plan", o un agente personalizado que hayas definido. Si el agente especificado no existe o es un subagente, OpenCode recurrirá a "build" con una advertencia.

Esta configuración se aplica a todas las interfaces: TUI, CLI (opencode run), aplicación de escritorio y GitHub Action.

Puedes configurar la función de compartir a través de la opción share.

opencode.json

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

Esto acepta:

"manual" - Permitir compartir manual a través de comandos (predeterminado)
"auto" - Compartir automáticamente nuevas conversaciones
"disabled" - Deshabilitar compartir completamente

Por defecto, compartir está configurado en modo manual donde necesitas compartir conversaciones explícitamente usando el comando /share.

Comandos

Puedes configurar comandos personalizados para tareas repetitivas a través de la opción command.

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

También puedes definir comandos usando archivos markdown en ~/.config/opencode/commands/ o .opencode/commands/. Aprende más aquí.

Atajos de teclado

Puedes personalizar tus atajos de teclado a través de la opción keybinds.

opencode.json

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

Aprende más aquí.

Actualización automática

OpenCode descargará automáticamente cualquier nueva actualización cuando inicie. Puedes deshabilitar esto con la opción autoupdate.

opencode.json

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

Si no quieres actualizaciones pero quieres ser notificado cuando una nueva versión esté disponible, establece autoupdate a "notify". Ten en cuenta que esto solo funciona si no fue instalado usando un gestor de paquetes como Homebrew.

Formateadores

Puedes configurar formateadores de código a través de la opción formatter.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Aprende más sobre formateadores aquí.

Permisos

Por defecto, opencode permite todas las operaciones sin requerir aprobación explícita. Puedes cambiar esto usando la opción permission.

Por ejemplo, para asegurar que las herramientas edit y bash requieran aprobación del usuario:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Aprende más sobre permisos aquí.

Compactación

Puedes controlar el comportamiento de compactación de contexto a través de la opción compaction.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}

auto - Compactar automáticamente la sesión cuando el contexto está lleno (predeterminado: true).
prune - Eliminar salidas de herramientas antiguas para ahorrar tokens (predeterminado: true).

Watcher

Puedes configurar patrones de ignorar del observador de archivos a través de la opción watcher.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Los patrones siguen la sintaxis glob. Usa esto para excluir directorios ruidosos de la observación de archivos.

Servidores MCP

Puedes configurar los servidores MCP que quieres usar a través de la opción mcp.

opencode.json

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

Aprende más aquí.

Plugins

Los Plugins extienden OpenCode con herramientas personalizadas, hooks e integraciones.

Coloca archivos de plugins en .opencode/plugins/ o ~/.config/opencode/plugins/. También puedes cargar plugins desde npm a través de la opción plugin.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Aprende más aquí.

Instrucciones

Puedes configurar las instrucciones para el modelo que estás usando a través de la opción instructions.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

Esto acepta un array de rutas y patrones glob a archivos de instrucciones. Aprende más sobre reglas aquí.

Proveedores deshabilitados

Puedes deshabilitar proveedores que se cargan automáticamente a través de la opción disabled_providers. Esto es útil cuando quieres prevenir que ciertos proveedores se carguen incluso si sus credenciales están disponibles.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

Nota: disabled_providers tiene prioridad sobre enabled_providers.

La opción disabled_providers acepta un array de IDs de proveedor. Cuando un proveedor está deshabilitado:

No se cargará incluso si las variables de entorno están establecidas.
No se cargará incluso si las claves API están configuradas a través del comando /connect.
Los modelos del proveedor no aparecerán en la lista de selección de modelos.

Proveedores habilitados

Puedes especificar una lista de permitidos de proveedores a través de la opción enabled_providers. Cuando se establece, solo los proveedores especificados serán habilitados y todos los demás serán ignorados.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

Esto es útil cuando quieres restringir OpenCode a usar solo proveedores específicos en lugar de deshabilitarlos uno por uno.

Nota: disabled_providers tiene prioridad sobre enabled_providers.

Si un proveedor aparece tanto en enabled_providers como en disabled_providers, disabled_providers tiene prioridad por compatibilidad hacia atrás.

Experimental

La clave experimental contiene opciones que están en desarrollo activo.

opencode.json

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

Precaución: Las opciones experimentales no son estables. Pueden cambiar o ser eliminadas sin previo aviso.

Variables

Puedes usar sustitución de variables en tus archivos de configuración para referenciar variables de entorno y contenidos de archivos.

Variables de entorno

Usa {env:VARIABLE_NAME} para sustituir variables de entorno:

opencode.json

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

Si la variable de entorno no está establecida, será reemplazada con una cadena vacía.

Archivos

Usa {file:path/to/file} para sustituir el contenido de un archivo:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Las rutas de archivo pueden ser:

Relativas al directorio del archivo de configuración
O rutas absolutas que comienzan con / o ~

Estos son útiles para:

Mantener datos sensibles como claves API en archivos separados.
Incluir archivos de instrucciones grandes sin desordenar tu configuración.
Compartir fragmentos de configuración comunes entre múltiples archivos de configuración.

Introducción Proveedores

Configuración

Formato

Ubicaciones

Orden de precedencia

Remota

Global

Por proyecto

Ruta personalizada

Directorio personalizado

Esquema

TUI

Servidor

Herramientas

Modelos

Opciones específicas del proveedor

Amazon Bedrock

Temas

Agentes

Agente predeterminado

Compartir

Comandos

Atajos de teclado

Actualización automática

Formateadores

Permisos

Compactación

Watcher

Servidores MCP

Plugins

Instrucciones

Proveedores deshabilitados

Proveedores habilitados

Experimental

Variables

Variables de entorno

Archivos