Guía Completa de Configuración de OpenCode: Variables de Entorno y Ajustes JSON

¿Alguna vez has experimentado fallos en la invocación de modelos LLM debido a una configuración incorrecta de las claves API? ¿Te has sentido abrumado al gestionar archivos de configuración durante el cambio entre distintos entornos?

Esta guía te presentará de manera sistemática el sistema de configuración de OpenCode, abarcando desde variables de entorno hasta archivos JSON, y desde ajustes básicos hasta optimizaciones avanzadas, con el objetivo de dominar las técnicas de configuración y evitar el 90% de los problemas comunes.

Sistema de Configuración General

OpenCode adopta una arquitectura de configuración de doble capa: las variables de entorno permiten la sobrescritura dinámica, mientras que los archivos JSON almacenan la configuración persistente. La prioridad de carga de la configuración se establece en el siguiente orden: Parámetros de línea de comandos > Variables de Entorno > Archivo JSON del Proyecto > Archivo JSON del Usuario > Configuración Predeterminada.

El código central del sistema de configuración se encuentra en internal/config/config.go, donde se definen la estructura completa de configuración y la lógica de carga. Los archivos de configuración JSON se adhieren a la especificación opencode-schema.json para garantizar la corrección del formato.

Configuración Mediante Variables de Entorno

Las variables de entorno son la opción ideal para la configuración temporal y la gestión de credenciales, admitiendo la configuración de claves API para los principales proveedores de LLM:

Variables de Entorno Comunes

OPENAI_API_KEY: Clave API de OpenAI. Ejemplo: sk-xxxx
ANTHROPIC_API_KEY: Clave API de Anthropic. Ejemplo: sk-ant-xxxx
GEMINI_API_KEY: Clave API de Google Gemini. Ejemplo: AIzaSyxxxx
GROQ_API_KEY: Clave API de Groq. Ejemplo: gsk_xxxx
AZURE_OPENAI_ENDPOINT: Endpoint de Azure OpenAI. Ejemplo: https://xx.openai.azure.com/

Métodos de Configuración

Para establecer variables de entorno de forma temporal en la terminal (Linux/macOS):

export OPENAI_API_KEY="sk-xxxx"

Para que los cambios sean permanentes (~/.bashrc o ~/.zshrc):

echo 'export OPENAI_API_KEY="sk-xxxx"' >> ~/.bashrc
 source ~/.bashrc

En sistemas Windows (PowerShell):

$env:OPENAI_API_KEY="sk-xxxx"

Archivos de Configuración JSON

Los archivos JSON ofrecen opciones de configuración más complejas y permiten personalizar el comportamiento de la aplicación en múltiples dimensiones. OpenCode carga los archivos de configuración en el siguiente orden:

Nivel de Usuario: ~/.opencode.json
Nivel de Proyecto: .opencode.json en el directorio de trabajo actual

Estructura Básica de Configuración

{
   "data": {
     "directory": ".opencode"
   },
   "tui": {
     "theme": "opencode"
   },
   "providers": {
     "openai": {
       "apiKey": "sk-xxxx"
     }
   },
   "agents": {
     "coder": {
       "model": "gpt-4.1",
       "maxTokens": 4096
     }
   }
 }

Detalles de los Elementos de Configuración Clave

1. Configuración de Almacenamiento de Datos

{
   "data": {
     "directory": "/ruta/personalizada/de/datos"
   }
 }

Especifica el directorio de almacenamiento de datos de la aplicación. El valor predeterminado es .opencode, ubicado en el directorio de inicio del usuario.

2. Configuración de Tema de TUI

Admite varios temas integrados:

{
   "tui": {
     "theme": "dracula"
   }
 }

Los temas disponibles incluyen: opencode, catppuccin, dracula, flexoki, gruvbox, monokai, onedark, tokyonight, tron.

3. Configuración de Proveedores de LLM

{
   "providers": {
     "openai": {
       "apiKey": "sk-xxxx",
       "disabled": false
     },
     "anthropic": {
       "apiKey": "sk-ant-xxxx",
       "disabled": true
     }
   }
 }

Se pueden configurar múltiples proveedores simultáneamente. La habilitación/deshabilitación se realiza mediante el campo disabled.

4. Configuración de Agentes

OpenCode utiliza diferentes agentes para distintas tareas:

{
   "agents": {
     "coder": {
       "model": "gpt-4.1",
       "maxTokens": 4096,
       "reasoningEffort": "medium"
     },
     "summarizer": {
       "model": "claude-3.5-sonnet",
       "maxTokens": 2048
     },
     "title": {
       "model": "gpt-4.1-mini",
       "maxTokens": 80
     }
   }
 }

coder: Agente de generación de código.
summarizer: Agente de resumen de contenido.
title: Agente de generación de títulos (maxTokens fijo en 80).

5. Configuración de LSP

Configuración del Protocolo de Servidor de Lenguaje:

{
   "lsp": {
     "go": {
       "command": "gopls",
       "args": ["-remote=auto"],
       "disabled": false
     },
     "python": {
       "command": "pyright-langserver",
       "args": ["--stdio"]
     }
   }
 }

Técnicas Avanzadas de Configuración

Estrategia de Fusión de Configuración

Cuando coexisten archivos de configuración de usuario y de proyecto, OpenCode los fusiona de manera inteligente:

Valores simples (cadenas, números, booleanos): El archivo de proyecto tiene prioridad.
Objetos complejos: Se fusionan las propiedades recursivamente.
Arrays: El array del archivo de proyecto reemplaza completamente al del archivo de usuario.

Establecimiento de Prioridad para Múltiples Modelos

OpenCode selecciona automáticamente el modelo disponible según la configuración. El orden de prioridad se define en internal/config/config.go, aproximadamente:

Copilot
Anthropic
OpenAI
Google Gemini
Groq
OpenRouter

Cnofiguración del Modo de Depuración

Habilita el modo de depuración para obtener registros detallados:

{
   "debug": true,
   "debugLSP": true
 }

Los registros de depuración se guardan por defecto en debug.log dentro del directorio de datos.

Validación de Configuración y Solución de Problemas

Validar la Efectividad de la Configuración

Utiliza el siguiente comando para verificar la corrección de la configuración:

opencode config validate

Solución de Problemas Comunes

1. Claves API No Funcionan

Verifica si las variables de entorno están sobrescribiendo la configuración del archivo.
Confirma que el formato de la clave sea correcto.
Asegúrate de que el proveedor no esté marcado con disabled: true.

2. Fallos al Cargar Modelos

Comprueba si el ID del modelo está incluido en la lista admitida definida en opencode-schema.json.
Verifica que la clave API del proveedor correspondiente esté configurada correctamente.
Consulta los registros de depurcaión para obtener información detallada del error.

3. Archivos de Configuración Ineficaces

Verifica la corrección de la ruta y el nombre del archivo (.opencode.json).
Asegúrate de que el formato JSON sea válido (puedes usar herramientas como jsonlint para verificar).
Confirma que los permisos del archivo permitan la lectura.

Prácticas Recomendadas

Gestión de Credenciales

Entorno de Producción: Utiliza variables de entorno o servicios de gestión de credenciales.
Entorno de Desarrollo: Puedes almacenar temporalmente las credenciales en el archivo de configuración del proyecto, pero no las subas al control de versiones.
Excluye los archivos de configuración del proyecto del control de versiones usando .gitignore: ```

.gitignore
```
    .opencode.json
```

Configuración para Múltiples Entornos

Crea archivos de configuración para diferentes entornos, por ejemplo:

.opencode.dev.json (Entorno de desarrollo)
.opencode.prod.json (Entorno de producción)

Utiliza enlaces simbólicos para cambiar de configuración:

ln -s .opencode.dev.json .opencode.json

Control de Versiones

Sube una plantilla de archivo de configuración de usuario al control de versiones para facilitar el intercambio de especificaciones de configuración en equipo:

{
   "tui": {
     "theme": "copilot"
   },
   "agents": {
     "coder": {
       "model": "gpt-4.1",
       "maxTokens": 4096
     }
   }
 }

Mediante los métodos de configuración presentados, podrás aprovechar al máximo la potente funcionalidad de OpenCode y personalizar tu experiencia de interacción con LLM según tus necesidades. Una configuración adecuada no solo mejora la eficiencia, sino que también reduce significativamente los costos de uso de API. Para más opciones de configuración, consulta la definición completa en opencode-schema.json.

Etiquetas: OpenCode configuracion variables de entorno json LLM

Publicado el 6-23 23:53

Friki Work