configuración

Usando la configuración OpenCode JSON.

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

Formato

OpenCode admite los formatos JSON y JSONC (JSON con comentarios).

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

Ubicaciones

Puedes colocar tu configuración en un par de ubicaciones diferentes y tienen un diferente orden de precedencia.

Los archivos de configuración se fusionan, no se reemplazan. Se combinan las configuraciones de las siguientes ubicaciones de configuración. Las configuraciones posteriores anulan las anteriores solo para claves en conflicto. Se conservan las configuraciones no conflictivas de todas las configuraciones.

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

Orden de precedencia

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

Configuración remota (de .well-known/opencode): valores predeterminados de la organización
Configuración global (~/.config/opencode/opencode.json) - preferencias del usuario
Configuración personalizada (OPENCODE_CONFIG env var): anulaciones personalizadas
Configuración del proyecto (opencode.json en el proyecto): configuración específica del proyecto
Directorios .opencode - agentes, comandos, complementos
Configuración en línea (OPENCODE_CONFIG_CONTENT env var): anulaciones del tiempo de ejecución

Esto significa que las configuraciones del proyecto pueden anular los valores predeterminados globales y las configuraciones globales pueden anular los valores predeterminados de la organización remota.

Remoto

Las organizaciones pueden proporcionar una configuración predeterminada a través del punto final .well-known/opencode. Esto se obtiene automáticamente cuando se autentica con un proveedor que lo admita.

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

Por ejemplo, si su organización proporciona servidores MCP que están deshabilitados de forma predeterminada:

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

Puede habilitar servidores específicos en su configuración local:

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

Global

Coloque su configuración global OpenCode en ~/.config/opencode/opencode.json. Utilice la configuración global para las preferencias de todo el usuario, como temas, proveedores o combinaciones de teclas.

La configuración global anula los valores predeterminados de la organización remota.

Por proyecto

Agregue opencode.json en la raíz de su proyecto. La configuración del proyecto tiene la mayor prioridad entre los archivos de configuración estándar: anula las configuraciones globales y remotas.

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

Esto también es seguro para registrarlo en Git y utiliza el mismo esquema que el global.

Ruta personalizada

Especifique una ruta de archivo de configuración personalizada utilizando 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 las configuraciones globales y del proyecto en orden de prioridad.

Directorio personalizado

Especifique un directorio de configuración personalizado usando OPENCODE_CONFIG_DIR variable de entorno. En este directorio se buscarán agentes, comandos, modos y complementos como el directorio estándar .opencode, y debería Sigue la misma estructura.

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

El directorio personalizado se carga después de los directorios global config y .opencode, por lo que puede anular su configuración.

Esquema

El archivo de configuración tiene un esquema definido en opencode.ai/config.json.

Su editor debería poder validar y autocompletar según el esquema.

TUI

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

{
  "$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 prioridad 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 la representación de diferencias. "auto" se adapta al ancho del terminal, "stacked" siempre muestra una sola columna.

Obtenga más información sobre el uso de TUI aquí.

Servidor

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

{
  "$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 ningún nombre de host, el valor predeterminado es 0.0.0.0.
mdns: habilita el descubrimiento de servicios mDNS. Esto permite que otros dispositivos en la red descubran su servidor OpenCode.
mdnsDomain - Nombre de dominio personalizado para el servicio mDNS. El valor predeterminado es opencode.local. Útil para ejecutar múltiples instancias en la misma red.
cors: orígenes adicionales para permitir CORS cuando se utiliza el servidor HTTP desde un cliente basado en navegador. Los valores deben ser orígenes completos (esquema + host + puerto opcional), por ejemplo, https://app.example.com.

Obtenga más información sobre el servidor aquí.

Herramientas

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

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

Obtenga más información sobre las herramientas aquí.

Modelos

Puede configurar los proveedores y modelos que desea utilizar en su configuración OpenCode a través de las opciones provider, model y small_model.

{
  "$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 livianas como la generación de títulos. De forma predeterminada, OpenCode intenta utilizar un modelo más económico si su proveedor tiene uno disponible; de lo contrario, recurre a su modelo principal.

Las opciones de proveedores pueden incluir timeout y setCacheKey:

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

timeout: tiempo de espera de solicitud en milisegundos (predeterminado: 300000). Establezca en false para desactivar.
setCacheKey: asegúrese de que siempre haya una clave de caché configurada para el proveedor designado.

También puede configurar modelos locales. Más información.

Opciones específicas del proveedor

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

Amazon Bedrock

Amazon Bedrock admite la configuración específica de AWS:

{
  "$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 - AWS región para Bedrock (el valor predeterminado es AWS_REGION env var o us-east-1)
profile - AWS perfil con nombre de ~/.aws/credentials (el valor predeterminado es AWS_PROFILE var env)
endpoint: URL de punto de enlace personalizada para puntos de enlace de VPC. Este es un alias para la opción genérica baseURL que utiliza terminología específica de AWS. Si se especifican ambos, endpoint tiene prioridad.

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

Temas

Puede configurar el tema que desea usar en su configuración OpenCode a través de la opción theme.

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

Más información aquí.

Agentes

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

{
  "$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": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

También puede definir agentes utilizando archivos de Markdown en ~/.config/opencode/agents/ o .opencode/agents/. Más información aquí.

Agente predeterminado

Puede configurar el agente predeterminado usando la opción default_agent. Esto determina qué agente se utiliza cuando no se especifica ninguno explícitamente.

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

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

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

Intercambio

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

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

Esto requiere:

"manual" - Permitir compartir manualmente mediante comandos (predeterminado)
"auto" - Comparte automáticamente nuevas conversaciones
"disabled" - Deshabilitar el uso compartido por completo

De forma predeterminada, el uso compartido está configurado en modo manual, donde debe compartir conversaciones explícitamente usando el comando /share.

Comandos

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

{
  "$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 puede definir comandos utilizando archivos de Markdown en ~/.config/opencode/commands/ o .opencode/commands/. Más información aquí.

combinaciones de teclas

Puede personalizar sus combinaciones de teclas a través de la opción keybinds.

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

Más información aquí.

Actualización automática

OpenCode descargará automáticamente cualquier actualización nueva cuando se inicie. Puede desactivar esto con la opción autoupdate.

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

Si no desea actualizaciones pero desea recibir una notificación cuando haya una nueva versión disponible, configure autoupdate en "notify". Tenga en cuenta que esto sólo funciona si no se instaló mediante un administrador de paquetes como Homebrew.

Formateadores

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

{
  "$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"]
    }
  }
}

Obtenga más información sobre los formateadores aquí.

Permisos

De forma predeterminada, opencode permite todas las operaciones sin requerir aprobación explícita. Puede cambiar esto usando la opción permission.

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

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

Obtenga más información sobre los permisos aquí.

Compactación

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

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

auto: compacta automáticamente la sesión cuando el contexto está lleno (predeterminado: true).
prune: elimina las salidas de herramientas antiguas para guardar tokens (predeterminado: true).

Vigilante

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

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

Los patrones siguen la sintaxis global. Utilice esto para excluir directorios ruidosos de la visualización de archivos.

MCP servidores

Puede configurar los servidores MCP que desee utilizar a través de la opción mcp.

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

Más información aquí.

Complementos

Los complementos amplían OpenCode con herramientas, enlaces e integraciones personalizados.

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

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

Más información aquí.

Instrucciones

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

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

Esto requiere una variedad de rutas y patrones globales para archivos de instrucciones. Más información sobre las reglas aquí.

Proveedores deshabilitados

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

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

La opción disabled_providers acepta una variedad de ID de proveedores. Cuando un proveedor está deshabilitado:

No se cargará incluso si se establecen variables de entorno.
No se cargará incluso si las teclas API están configuradas mediante el comando /connect.
Los modelos del proveedor no aparecerán en la lista de selección de modelos.

Proveedores habilitados

Puede especificar una lista de proveedores permitidos a través de la opción enabled_providers. Cuando se establece, solo se habilitarán los proveedores especificados y se ignorarán todos los demás.

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

Esto es útil cuando desea restringir OpenCode para que utilice únicamente proveedores específicos en lugar de deshabilitarlos uno por uno.

Si un proveedor aparece tanto en enabled_providers como en disabled_providers, el disabled_providers tiene prioridad para la compatibilidad con versiones anteriores.

Experimental

La clave experimental contiene opciones que se encuentran en desarrollo activo.

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

##Variables

Puede utilizar la sustitución de variables en sus archivos de configuración para hacer referencia a variables de entorno y contenidos de archivos.

Variables ambientales

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

{
  "$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á configurada, se reemplazará con una cadena vacía.

Archivos

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

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

Las rutas de los archivos pueden ser:

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

Estos son útiles para:

Mantener datos confidenciales como claves API en archivos separados.
Incluye archivos de instrucciones grandes sin saturar tu configuración.
Compartir fragmentos de configuración comunes en múltiples archivos de configuración.