Configuración

Usar el archivo JSON de configuración de OpenCode.

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

Formato

OpenCode admite tanto JSON como JSONC (JSON con comentarios).

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

Ubicación

Puedes colocar la configuración en varios sitios con distinto orden de precedencia.

Las configuraciones de todas las ubicaciones se fusionan. Los archivos cargados más tarde solo sobrescriben las claves que entren en conflicto; el resto se conserva.

Por ejemplo, si tu configuración global define theme: "opencode" y autoupdate: true y la configuración del proyecto define model: "anthropic/claude-sonnet-4-5", la configuración final contendrá los tres valores.

Orden de precedencia

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

Config remota (.well-known/opencode) – valores predeterminados de la organización
Config global (~/.config/opencode/opencode.json) – preferencias del usuario
Config personalizada (variable de entorno OPENCODE_CONFIG)
Config del proyecto (opencode.json en el proyecto)
Directorios .opencode – agents, commands, plugins
Config inline (OPENCODE_CONFIG_CONTENT)

Así, la config del proyecto puede sobrescribir la global y la global puede sobrescribir la de la organización.

Remota

Las organizaciones pueden exponer configuración por defecto mediante el endpoint .well-known/opencode. Se descarga automáticamente cuando te autenticas con un proveedor que la soporta.

La config remota se carga primero como base; el resto de capas (global y proyecto) la pueden sobrescribir.

Ejemplo de MCP desactivado por defecto:

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

Y cómo activarlo en local:

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

Global

Coloca la configuración global de OpenCode en ~/.config/opencode/opencode.json. Úsala para preferencias de usuario: temas, proveedores, atajos de teclado, etc.

La configuración global sobrescribe los valores remotos de la organización.

Por proyecto

Añade opencode.json en la raíz del proyecto. La configuración del proyecto tiene la mayor prioridad entre los archivos estándar: sobrescribe tanto la global como la remota.

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

Este archivo se puede commitear con seguridad y usa el mismo esquema que la config global.

Ruta personalizada

Con la variable de entorno OPENCODE_CONFIG puedes indicar una ruta alternativa:

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

Esta configuración se carga entre la global y la del proyecto.

Directorio personalizado

Con OPENCODE_CONFIG_DIR puedes indicar un directorio de configuración alternativo. Se trata igual que un .opencode estándar: se busca ahí agents, commands, modes y plugins.

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

Este directorio se carga después de la config global y los directorios .opencode, por lo que puede sobrescribir sus ajustes.

Esquema

El archivo de configuración sigue el esquema definido en opencode.ai/config.json.

Tu editor puede usarlo para validar y autocompletar.

TUI

Las opciones específicas del TUI se configuran bajo la clave tui:

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

Opciones disponibles:

scroll_acceleration.enabled – activa aceleración de scroll al estilo macOS. Tiene prioridad sobre scroll_speed.
scroll_speed – multiplicador de velocidad de scroll (por defecto 1, mínimo 1), ignorado si scroll_acceleration.enabled es true.
diff_style – estilo de diff: "auto" se adapta al ancho del terminal, "stacked" fuerza una sola columna.

Más sobre el TUI.

Servidor

Los ajustes del servidor para opencode serve y opencode web se definen bajo server:

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

Opciones:

port – puerto de escucha
hostname – host de escucha; si mdns está activado y no se define, se usa 0.0.0.0
mdns – habilita descubrimiento mDNS
cors – orígenes adicionales permitidos para CORS (esquema + host + puerto opcional), p. ej. https://app.example.com

Más sobre el servidor.

Herramientas

Con la opción tools puedes controlar qué herramientas puede usar el LLM:

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

Más sobre herramientas.

Modelos

Los proveedores y modelos se configuran mediante 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"
}

small_model define un modelo más ligero para tareas sencillas (por ejemplo generar títulos). Por defecto, OpenCode intentará usar un modelo más barato del mismo proveedor; si no lo hay, usará el modelo principal.

Las opciones de proveedor pueden incluir timeout y setCacheKey:

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

timeout – timeout en milisegundos (por defecto 300000). Usa false para desactivarlo.
setCacheKey – garantiza que siempre se establezca una clave de caché para ese proveedor.

También puedes configurar modelos locales. Más sobre modelos.

Opciones específicas de proveedor

Algunos proveedores soportan opciones adicionales.

Amazon Bedrock

{
  "$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 (por defecto AWS_REGION o us-east-1)
profile – perfil nombrado de ~/.aws/credentials (por defecto AWS_PROFILE)
endpoint – URL de endpoint personalizada (alias de baseURL; si ambos están definidos, gana endpoint).

Más sobre Amazon Bedrock.

Temas

El tema se configura con la clave theme:

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

Más sobre temas.

Agentes

Puedes definir agentes especializados para tareas concretas con 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 puedes definir agentes como archivos Markdown bajo ~/.config/opencode/agent/ o .opencode/agent/. Más información.

Agente por defecto

El agente por defecto se define con default_agent y se usa cuando no se indica otro explícitamente:

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

Debe ser un agente primario (no un sub‑agente). Puede ser uno integrado ("build", "plan") o un agente personalizado. Si el agente no existe o es un sub‑agente, OpenCode vuelve a "build" y muestra un aviso.

Este ajuste afecta a todas las interfaces: TUI, CLI (opencode run), app de escritorio y GitHub Action.

Compartir sesiones

La función de compartir se controla con la clave share:

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

Valores posibles:

"manual" – solo compartir manualmente mediante comandos (por defecto)
"auto" – compartir automáticamente las nuevas conversaciones
"disabled" – desactivar por completo el sharing

Por defecto se usa "manual", es decir, hay que usar /share explícitamente.

Comandos

Las tareas repetitivas se pueden definir como comandos personalizados mediante 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 puedes definir comandos como archivos Markdown bajo ~/.config/opencode/command/ o .opencode/command/. Más información.

Atajos de teclado

Los atajos se personalizan mediante la clave keybinds:

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

Más sobre keybinds.

Actualizaciones automáticas

OpenCode descarga nuevas versiones automáticamente al iniciarse. Puedes desactivar ese comportamiento con autoupdate:

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

Si no quieres actualizaciones automáticas pero sí recibir avisos, usa "notify".

Formatters

Los formatters de código se configuran con la clave 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"]
    }
  }
}

Más sobre formatters.

Permisos

Por defecto, OpenCode permite todas las operaciones sin pedir confirmación. Puedes endurecerlo con la opción permission, por ejemplo para exigir confirmación al usar edit y bash:

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

Más sobre permisos.

Compactación

El comportamiento de compactación de contexto se configura con compaction:

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

auto – compactar la sesión automáticamente cuando el contexto se llena (por defecto true).
prune – eliminar salidas antiguas de herramientas para ahorrar tokens (por defecto true).

Watcher

Los patrones de exclusión del watcher de archivos se definen con watcher:

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

Los patrones usan sintaxis glob.

Servidores MCP

Los servidores MCP se configuran mediante la clave mcp:

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

Más información.

Plugins

Los plugins amplían OpenCode con herramientas, hooks e integraciones personalizadas.

Coloca archivos de plugin en .opencode/plugin/ o ~/.config/opencode/plugin/. También puedes cargar plugins desde npm mediante la clave plugin:

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

Más sobre plugins.

Instrucciones

Puedes indicar archivos de instrucciones para el modelo con la opción instructions:

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

Acepta una lista de rutas y patrones glob. Más sobre reglas.

Proveedores deshabilitados

Con disabled_providers puedes desactivar por completo algunos proveedores, incluso si tienen credenciales configuradas:

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

Cuando un proveedor está deshabilitado:

no se carga aunque existan variables de entorno;
se ignoran las claves configuradas con /connect;
sus modelos no aparecen en la lista de modelos.

Proveedores permitidos

Con enabled_providers defines una allowlist de proveedores. Si se establece, solo esos proveedores se habilitan, el resto se ignora:

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

Es útil si quieres limitar OpenCode a un conjunto concreto de proveedores.

Si un proveedor aparece en ambas listas, prevalece disabled_providers.

Experimental

La clave experimental agrupa opciones en desarrollo activo:

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

Variables

Puedes usar sustitución de variables en los archivos de configuración para referenciar variables de entorno y contenido de archivos.

Variables de entorno

Usa {env:NOMBRE} para sustituir una variable de entorno:

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

Si la variable no está definida, se sustituye por una cadena vacía.

Archivos

Usa {file:ruta/al/archivo} para insertar 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 pueden ser:

relativas al directorio del archivo de configuración;
o absolutas empezando por / o ~.

Esto resulta útil para:

mantener credenciales sensibles (API keys, etc.) en archivos separados;
incluir instrucciones grandes sin llenar el JSON;
reutilizar fragmentos de configuración entre proyectos.