Capitulo 4: Configuracion

< Volver al Indice del Tutorial

Archivo opencode.json

El archivo principal de configuracion de OpenCode es opencode.json, ubicado en la raiz de tu proyecto. Soporta formato JSON y JSONC (JSON con comentarios).

Schema Validation

OpenCode provee un JSON Schema para validacion y autocompletado en tu editor:

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

Con esto, editores como VS Code, Zed o Neovim te ofreceran autocompletado e indicaran errores en la configuracion.

Precedencia de Configuracion

OpenCode carga configuracion desde multiples fuentes. La precedencia de menor a mayor es:

1. Remote: configuracion remota del equipo (si existe)
2. Global: ~/.config/opencode/config.json
3. Custom path: especificado con OPENCODE_CONFIG
4. Project: opencode.json en la raiz del proyecto

Cada nivel sobreescribe al anterior. Esto permite tener configuracion base a nivel global y ajustes especificos por proyecto.

Ejemplo Practico

Si en tu config global tienes model: "claude-sonnet-4-20250514" pero en el opencode.json del proyecto defines model: "gpt-4o", el proyecto usara gpt-4o.

Campos Principales

Modelo y Proveedor

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

Campo	Descripcion
provider	Proveedor LLM a usar (anthropic, openai, google, etc.)
model	Modelo principal para el agente Build
small_model	Modelo ligero para tareas auxiliares (summaries, compactacion)

Herramientas

Controla que herramientas puede usar el agente:

{
  "tools": {
    "bash": true,
    "read": true,
    "write": true,
    "glob": true,
    "grep": true,
    "fetch": false
  }
}

Deshabilitar herramientas limita lo que el agente puede hacer. Util para entornos restrictivos.

Permisos

Define el nivel de permisos del agente:

{
  "permission": "auto"
}

Valor	Comportamiento
"ask"	Pide confirmacion para cada accion
"auto"	Ejecuta automaticamente sin preguntar
"deny"	Bloquea acciones que modifiquen archivos

Agente por Defecto

{
  "default_agent": "build"
}

Define cual agente se activa al iniciar OpenCode. Los valores son "build" o "plan".

Configuracion Completa del Agente

{
  "agent": {
    "build": {
      "model": "claude-sonnet-4-20250514",
      "tools": ["read", "write", "bash", "glob", "grep"]
    },
    "plan": {
      "model": "claude-haiku-35",
      "tools": ["read", "glob", "grep"]
    }
  }
}

Puedes configurar cada agente de forma independiente con su propio modelo y conjunto de herramientas.

Variables de Sustitucion

OpenCode soporta variables dinamicas en la configuracion:

Variables de Entorno

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

{
  "provider": "anthropic",
  "api_key": "{env:ANTHROPIC_API_KEY}"
}

Contenido de Archivos

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

{
  "system_prompt": "{file:./prompts/custom.md}"
}

Esto es util para mantener prompts largos en archivos separados y versionarlos con git.

Configuracion de la TUI

La interfaz TUI tiene su propia configuracion en tui.json:

{
  "theme": "dark",
  "keybinds": {
    "toggle_agent": "tab",
    "cancel": "ctrl+c",
    "quit": "ctrl+d"
  }
}

Puedes personalizar el tema visual y los atajos de teclado.

Variables de Entorno

OpenCode reconoce varias variables de entorno:

Variable	Descripcion
OPENCODE_CONFIG	Ruta a un archivo de configuracion custom
OPENCODE_DISABLE_AUTOUPDATE	Deshabilita actualizaciones automaticas
OPENCODE_SERVER_PASSWORD	Password para el modo server
ANTHROPIC_API_KEY	API key de Anthropic
OPENAI_API_KEY	API key de OpenAI
GOOGLE_API_KEY	API key de Google

Las API keys de los proveedores tambien se pueden configurar en opencode.json, pero las variables de entorno son mas seguras ya que no se commitean al repositorio.

Ejemplo Minimo Funcional

El archivo opencode.json mas simple que necesitas para empezar:

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

Con la variable de entorno ANTHROPIC_API_KEY configurada, esto es suficiente para usar OpenCode.

Ejemplo para Equipo

Un ejemplo mas completo para un proyecto de equipo:

{
  "$schema": "https://opencode.ai/config.schema.json",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "small_model": "claude-haiku-35",
  "permission": "ask",
  "autoupdate": "notify",
  "default_agent": "build",
  "tools": {
    "bash": true,
    "read": true,
    "write": true,
    "glob": true,
    "grep": true,
    "fetch": true
  }
}

Ejemplo con Modelo Local

Para usar OpenCode sin pagar por APIs:

{
  "$schema": "https://opencode.ai/config.schema.json",
  "provider": "ollama",
  "model": "qwen2.5-coder:32b",
  "small_model": "qwen2.5-coder:7b"
}

Requiere tener Ollama corriendo localmente con los modelos descargados.

Configuracion Global

Para definir defaults que apliquen a todos tus proyectos, crea el archivo global:

mkdir -p ~/.config/opencode

// ~/.config/opencode/config.json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "autoupdate": "notify"
}

Los proyectos individuales pueden sobreescribir cualquier campo de la configuracion global.

---

Siguiente: Capitulo 5: Agentes Built-in —>