File size: 20,831 Bytes

0dbc9de

---
title: Configuración
description: 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).

```jsonc title="opencode.jsonc"
{
  "$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.

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

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):

1. **Configuración remota** (de `.well-known/opencode`): valores predeterminados de la organización
2. **Configuración global** (`~/.config/opencode/opencode.json`) - preferencias del usuario
3. **Configuración personalizada** (`OPENCODE_CONFIG` env var): anulaciones personalizadas
4. **Configuración del proyecto** (`opencode.json` en el proyecto): configuración específica del proyecto
5. Directorios **`.opencode`** - agentes, comandos, complementos
6. **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.

:::note
Los directorios `.opencode` y `~/.config/opencode` usan **nombres en plural** para los subdirectorios: `agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/` y `themes/`. También se admiten nombres singulares (por ejemplo, `agent/`) para compatibilidad con versiones anteriores.
:::

---

### 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:

```json title="Remote config from .well-known/opencode"
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}
```

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

```json title="opencode.json"
{
  "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.

:::tip
Coloque la configuración específica del proyecto en la raíz de su proyecto.
:::

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`.

```bash
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.

```bash
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`**](https://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`.

```json title="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 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í](/docs/tui).

---

### Servidor

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

```json title="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 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í](/docs/server).

---

### Herramientas

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

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

[Obtenga más información sobre las herramientas aquí](/docs/tools).

---

### 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`.

```json title="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 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`:

```json title="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). 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](/docs/models#local). [Más información](/docs/models).

---

#### 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:

```json title="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` - 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.

:::note
Los tokens de portador (`AWS_BEARER_TOKEN_BEDROCK` o `/connect`) tienen prioridad sobre la autenticación basada en perfil. Consulte [precedencia de autenticación](/docs/providers#authentication-precedence) para obtener más detalles.
:::

[Obtenga más información sobre la configuración de Amazon Bedrock](/docs/providers#amazon-bedrock).

---

### Temas

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

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

[Más información aquí](/docs/themes).

---

### Agentes

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

```jsonc title="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": {
        // 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í](/docs/agents).

---

### 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.

```json title="opencode.json"
{
  "$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](/docs/agents) 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.

---

### Compartir

Puede configurar la función [compartir](/docs/share) a través de la opción `share`.

```json title="opencode.json"
{
  "$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`.

```jsonc title="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 puede definir comandos utilizando archivos de Markdown en `~/.config/opencode/commands/` o `.opencode/commands/`. [Más información aquí](/docs/commands).

---

### Atajos de teclado

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

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

[Más información aquí](/docs/keybinds).

---

### Actualización automática

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

```json title="opencode.json"
{
  "$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`.

```json title="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"]
    }
  }
}
```

[Obtenga más información sobre los formateadores aquí](/docs/formatters).

---

### 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:

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

[Obtenga más información sobre los permisos aquí](/docs/permissions).

---

### Compactación

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

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

- `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: `false`).

---

### Observador

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

```json title="opencode.json"
{
  "$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.

---

### Servidores MCP

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

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

[Más información aquí](/docs/mcp-servers).

---

### Complementos

Los [complementos](/docs/plugins) 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`.

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

[Más información aquí](/docs/plugins).

---

### Instrucciones

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

```json title="opencode.json"
{
  "$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í](/docs/rules).

---

### 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.

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

:::note
El `disabled_providers` tiene prioridad sobre `enabled_providers`.
:::

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.

```json title="opencode.json"
{
  "$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.

:::note
El `disabled_providers` tiene prioridad sobre `enabled_providers`.
:::

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.

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

:::caution
Las opciones experimentales no son estables. Pueden cambiar o eliminarse sin previo aviso.
:::

---

## 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 de entorno

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

```json title="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á configurada, se reemplazará con una cadena vacía.

---

### Archivos

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

```json title="opencode.json"
{
  "$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.