Configuración Básica con opencode.json

Principiante⏱45 min📖3 min de lecturaLección 5 de 5

Configuración Básica con opencode.json

Configura OpenCode usando opencode.json. Aprende el esquema de configuración, agentes, proveedores, permisos y cómo personalizar el comportamiento para tus proyectos.

Ubicaciones del Archivo de Configuración

OpenCode busca la configuración en este orden:

Prioridad	Ubicación	Propósito
1	`.opencode/config.json`	Específico del proyecto (preferido)
2	`opencode.json`	Específico del proyecto (heredado)
3	`~/.config/opencode/config.json`	Valores predeterminados del usuario

💡Consejo

Para nuevos proyectos, use .opencode/config.json. El opencode.json raíz se mantiene por compatibilidad.

Estructura Básica de Configuración

json

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {},
  "providers": {},
  "permissions": [],
  "skills": {}
}

Configurando Agentes

Los agentes son asistentes de IA con modelos y comportamientos específicos.

Agente Simple

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Asistente de codificación de propósito general"
    }
  }
}

Múltiples Agentes

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Asistente de codificación de propósito general"
    },
    "reviewer": {
      "model": "claude-sonnet-4-20250514",
      "description": "Especialista en revisión de código"
    },
    "fast": {
      "model": "gpt-4o-mini",
      "description": "Tareas rápidas y preguntas simples"
    }
  }
}

Agente con Indicación Personalizada

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Ingeniero de software senior",
      "prompt": "You are a senior software engineer with 10+ years of experience. Focus on clean, maintainable code. Always consider edge cases and error handling."
    }
  }
}

Configurando Proveedores

Los proveedores definen cómo OpenCode se conecta a servicios LLM.

OpenAI

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o"
    }
  }
}

Anthropic

json

{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

Múltiples Proveedores

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    },
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    },
    "google": {
      "apiKey": "${GOOGLE_API_KEY}"
    }
  }
}

Configurando Permisos

Los permisos controlan qué acciones pueden realizar los agentes.

Permisos Básicos

json

{
  "permissions": [
    {
      "tool": "bash",
      "allow": ["npm *", "git *", "pip *"],
      "deny": ["rm -rf /", "sudo *"]
    },
    {
      "tool": "write",
      "allow": ["src/**", "docs/**"],
      "deny": [".env", "secrets/**"]
    }
  ]
}

Reglas de Permisos

Regla	Descripción
`tool`	La herramienta a controlar
`allow`	Patrones que están permitidos
`deny`	Patrones que están bloqueados
Orden	Las reglas de denegación se verifican primero

Configurando Habilidades

Las habilidades son paquetes de instrucciones reutilizables.

json

{
  "skills": {
    "react-component": {
      "manifest": "skills/react-component/skill.yaml",
      "autoLoad": true,
      "matchPattern": "react component|jsx"
    },
    "python-helper": {
      "manifest": "skills/python-helper/skill.yaml",
      "autoLoad": false
    }
  }
}

Opción	Descripción
`manifest`	Ruta al archivo de manifiesto de la habilidad
`autoLoad`	Cargar automáticamente cuando el patrón coincida
`matchPattern`	Patrón regex para activar la carga automática

Configurando Servidores MCP

Los servidores MCP conectan OpenCode con herramientas y servicios externos.

json

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["mcp-server-fs.js"],
      "env": {
        "ALLOWED_PATHS": "/home/user/projects"
      }
    },
    "database": {
      "command": "python",
      "args": ["mcp-server-db.py"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Ejemplo Completo

Aquí hay un opencode.json completo para un proyecto típico:

json

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Asistente principal de codificación",
      "prompt": "You are a senior developer. Focus on clean, testable code."
    },
    "reviewer": {
      "model": "claude-sonnet-4-20250514",
      "description": "Especialista en revisión de código"
    }
  },
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    },
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  },
  "permissions": [
    {
      "tool": "bash",
      "allow": ["npm *", "git *", "pytest *"],
      "deny": ["rm -rf *", "sudo *"]
    },
    {
      "tool": "write",
      "allow": ["src/**", "tests/**", "docs/**"],
      "deny": [".env", "secrets/**", "*.key"]
    }
  ],
  "skills": {
    "customize-opencode": {
      "manifest": ".opencode/skills/customize-opencode/skill.yaml"
    }
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Validación

OpenCode valida su configuración al iniciar. Errores comunes:

Error	Causa	Solución
"Invalid JSON"	Error de sintaxis	Verifique el formato JSON
"Unknown provider"	Proveedor no soportado	Consulte la documentación del proveedor
"Invalid model"	Nombre de modelo incorrecto	Verifique que el modelo exista
"Permission conflict"	Reglas superpuestas	Revise el orden de permisos

Sustitución de Variables de Entorno

Use ${VARIABLE_NAME} para referenciar variables de entorno:

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    }
  }
}

Esto mantiene los datos sensibles fuera de sus archivos de configuración.