OpenCode: Manual Completo - Guía Definitiva del Agente de Coding

Introducción

Este manual cubre todo lo que necesitas saber para dominar OpenCode, desde la instalación hasta las configuraciones más avanzadas. Si ya leíste mi review y comparativa con competidores, este artículo profundiza en la parte técnica.

OpenCode es un agente de coding open-source que funciona como CLI, aplicación de escritorio o extensión de IDE. Soporta más de 75 proveedores de modelos y puede usarse completamente gratis.

Instalación

Requisitos previos

• Node.js 18.0.0 o superior
• Git
• Docker (opcional, solo si quieres agentes en contenedores sandbox)

Métodos de instalación

1
2
3
4
5
6
7
8
9
10
11

# Opción 1: npm (recomendado)
npm install -g @opencode-ai/cli

# Opción 2: pnpm
pnpm add -g @opencode-ai/cli

# Opción 3: Homebrew (macOS/Linux)
brew install opencode

# Opción 4: Script de instalación
curl -sL https://opencode.ai/install.sh | bash

Verificar instalación

1

opencode --version

Deberías ver un número de versión (ej: v0.12.0). Si ves un error, asegúrate de que Node.js está actualizado.

Inicialización

1

opencode init

Este comando interactivo te guiará para:

1. Default Model Provider: Elige ‘OpenCode Zen’ (recomendado para comenzar) o ‘Ollama’ (si prefieres modelos locales)
2. Sandbox Mode: Recomendado ‘On’ para tareas de refactoring extensivas
3. Plugins: Selecciona los plugins por defecto a instalar

Configuración

Estructura de archivos de configuración

OpenCode busca configuración en este orden (los posteriores sobrescriben los anteriores):

1. Remote config (.well-known/opencode) — Defaults organizacionales
2. Global config (~/.config/opencode/opencode.json) — Preferencias de usuario
3. Custom config (OPENCODE_CONFIG env var) — Override personalizado
4. Project config (opencode.json en la raíz del proyecto) — Config específica del proyecto
5. Directorio .opencode — Agentes, commands, plugins

Configuración global

Edita ~/.config/opencode/opencode.json:

1
2
3
4
5

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

Configuración por proyecto

Crea opencode.json en la raíz de tu proyecto:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/gpt-4o",
  "instructions": [
    "AGENTS.md",
    "docs/style-guide.md"
  ],
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "enabled": true
    }
  }
}

Variables de entorno

1
2
3
4
5
6
7
8
9
10
11

# Para modelos de Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Para modelos de OpenAI
export OPENAI_API_KEY="sk-..."

# Para usar un config específico
export OPENCODE_CONFIG=/path/to/custom/config.json

# Para usar un directorio de config específico
export OPENCODE_CONFIG_DIR=/path/to/config/directory

Modelos y Proveedores

Proveedores soportados (75+)

Modelos gratuitos

OpenCode incluye modelos gratuitos que funcionan sin configurar nada:

Precios de OpenCode

Elegir el modelo adecuado

1
2
3

{
  "model": "openai/gpt-4o"
}

Para cambiar el modelo durante una sesión:

1

/model anthropic/claude-sonnet-4-20250514

Sistema de Agentes

Agentes primarios

Build (defecto): Desarrollo completo con todas las herramientas habilitadas.

Plan: Análisis sin modificaciones. Ideal para:

• Estudiar código antes de tocarlo
• Planificar refactors complejos
• Revisiones architecturales

Cambiar entre agentes con Tab:

1

[Build] > [Plan] > [Build] > ...

Subagentes

Explore: Explora el codebase de forma readonly.

Invocarlo:

1

@explore encuentra todos los archivos que usan autenticación JWT

General: Asistente general para tareas diversas.

Comandos incorporados

Ejecutar comandos directamente

Usa el prefijo ! para ejecutar comandos de shell directamente sin pasar por el agente:

1
2
3

!ls -la
!npm test
!git status

Esto es útil para:

• Comandos rápidos que no necesitan contexto del agente
• Verificar el estado actual del proyecto
• Ejecutar scripts o comandos cortos

El agente continuará su trabajo mientras el comando se ejecuta en segundo plano.

Crear agentes personalizados

1

opencode agent create

Comando interactivo que:

1. Pregunta dónde guardar (global o proyecto)
2. Descripción del agente
3. Genera prompt e identificador
4. Selecciona permisos (lo que no seleccionas se deniega)
5. Crea archivo markdown con configuración

Ejemplo de agente personalizado en opencode.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "agent": {
    "code-reviewer": {
      "description": "Revisa código buscando bugs y seguridad",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "read": "allow"
      }
    }
  }
}

Interfaz TUI

Áreas de la pantalla

• Chat: Área principal para interactuar con el agente
• Diff: Vista de cambios en tiempo real
• Status bar: Información del modelo, sesión, tokens

Keyboard shortcuts

Temas

Configurar tema en opencode.json:

1
2
3

{
  "theme": "default-dark"
}

Temas disponibles: default-dark, default-light, gruvbox, nord, dracula.

MCP (Model Context Protocol)

¿Qué es MCP?

MCP es un estándar abierto que permite a OpenCode conectar con herramientas externas: bases de datos, APIs, sistemas de archivos, y más.

Configurar MCP servers

Local (en opencode.json):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/ruta/a/proyecto"],
      "enabled": true
    },
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_tu_token"
      },
      "enabled": true
    }
  }
}

Remoto:

1
2
3
4
5
6
7
8
9
10
11
12

{
  "mcp": {
    "mi-server-remoto": {
      "type": "remote",
      "url": "https://tu-servidor.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer tu_api_key"
      }
    }
  }
}

MCP servers populares

Verificar MCPs configurados

1

opencode mcp list

GitHub Integration

Instalación

1

opencode github install

Esto instala la GitHub App, crea el workflow, y configura los secrets.

Configuración manual

1. Instalar la GitHub App en github.com/apps/opencode-agent
2. Añadir workflow en .github/workflows/opencode.yml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

name: opencode

on:
  issue_comment:
    types: [created]
  pull_request:
    types: [opened, synchronize]

jobs:
  opencode:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      pull-requests: write
      issues: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
          persist-credentials: false

      - uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: $
        with:
          model: anthropic/claude-sonnet-4-20250514

Eventos soportados

Ejemplo: Auto-review en PR

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false

      - uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: $
        with:
          model: anthropic/claude-sonnet-4-20250514
          prompt: |
            Review this pull request:
            - Check for code quality issues
            - Look for potential bugs
            - Suggest improvements

Integración con IDE

Aplicación de escritorio

Descarga desde opencode.ai. Funciona como interfaz completa sin necesidad de terminal.

VS Code

Instala la extensión desde el Marketplace. Proporciona:

• Chat contextual
• Inline completions
• Diff view
• Historial de conversación

JetBrains

Disponible para IntelliJ, PyCharm, WebStorm, etc. Mismas features que VS Code.

AGENTS.md

Qué es AGENTS.md

Similar a CLAUDE.md de Claude Code o .cursorrules de Cursor. Es un archivo que da contexto persistente a OpenCode sobre tu proyecto.

Ubicaciones

Ejemplo de AGENTS.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Reglas del Proyecto

## Estilo de código
- Usar TypeScript siempre que sea posible
- Preferir const sobre let
- Usar ESLint con configuración estándar

## Testing
- Tests unitarios obligatorios para nuevas funciones
- Correr tests antes de hacer commit

## Git
- Commits siguiendo Conventional Commits
- Branches: feature/, bugfix/, hotfix/

## Comandos útiles
- `npm run dev` — Iniciar servidor de desarrollo
- `npm test` — Correr tests
- `npm run lint` — Verificar código

Alternatives

Si no existe AGENTS.md, OpenCode también lee:

• CLAUDE.md
• .cursorrules

Casos de uso prácticos

Debugging rápido

1

El test de login está fallando con "Cannot read property of undefined". Encuentra dónde está el error y propón una solución.

Añadir nueva feature

1

Quiero añadir autenticación con JWT al endpoint /api/users. Crea la estructura necesaria, los middleware de verificación, y los tests correspondientes.

Code review

1

/code-review src/auth/

Generar tests

1

/generate-tests src/utils/date.ts

Planificar refactor

1

/refactor-plan src/controllers/

Troubleshooting

Error: “Command not found”

Asegúrate de que OpenCode está en tu PATH:

1

export PATH="$PATH:$(npm root -g)/@opencode-ai/cli"

Añade esta línea a tu .bashrc o .zshrc para persistir el cambio.

Error: “Model not found”

Verifica que el modelo existe:

1

/models

Asegúrate de que el nombre del modelo está bien escrito. Algunos modelos requieren el formato completo: anthropic/claude-sonnet-4-20250514.

Error: “API key not found”

Configura tu API key:

1

export ANTHROPIC_API_KEY="sk-ant-..."

Para verificar que la key está configurada correctamente:

1

echo $ANTHROPIC_API_KEY

Si usas múltiples proveedores, asegúrate de exportar la variable correcta para el modelo que estás usando.

Problemas de rendimiento

• Usa modelos más rápidos para tareas simples (Haiku, Flash)
• Activa auto-compact para sesiones largas
• Limita el contexto usando /clear periódicamente
• Considera usar modelos locales con Ollama para tareas que no requieren modelos frontier

Sesiones que crecen demasiado

Si una sesión se vuelve muy larga, usa /clear para empezar de nuevo o usa la función de auto-compact que OpenCode ejecuta automáticamente cuando se acerca al límite de contexto. También puedes usar el agente Plan para analizar el código sin incrementar el contexto de la sesión principal.

WSL2 en Windows

OpenCode funciona mejor en WSL2. Instala en la distribución Linux:

1

npm install -g @opencode-ai/cli

Luego ejecuta desde WSL, no desde PowerShell. Si experimentas problemas de rendimiento, aumenta la memoria asignada a WSL en .wslconfig.

Errores con MCP

Si un MCP server no funciona, verifica:

1. Que está habilitado en opencode.json
2. Que el comando existe y está instalado (ej: npx -y @modelcontextprotocol/server-github)
3. Que las variables de entorno requeridas están configuradas
4. Que el timeout es suficiente (por defecto 5 segundos, aumenta si es necesario):

   1 2 3 4 5 6 7

   { "mcp": { "server-name": { "timeout": 30000 } } }

Este manual complementa mi review y comparativa donde analizo OpenCode vs la competencia.

Compártelo si te ha resultado útil.

Si lo necesitas a nivel profesional en tu empresa, puedo ayudarte.

Y… hasta aquí por hoy!