Cómo usar opencode: guía paso a paso

Para usar opencode, instálalo con un solo comando, ejecuta opencode en la carpeta de un proyecto, conecta un proveedor de modelos con /connect, elige un modelo con /models y describe lo que quieres. El agente predeterminado, Build, lee tu código, edita archivos y ejecuta comandos. Pulsa Tab para pasar al agente Plan cuando quieras pensar un cambio sin tocar nada de código.

Ese es el ciclo básico. Esta guía cubre el resto: proveedores y modelos locales, los comandos de la TUI que usarás a diario, los dos agentes integrados, opencode.json, AGENTS.md, los servidores MCP, los comandos personalizados y cómo ejecutar opencode junto a otros agentes. Todo sigue la documentación oficial de opencode a octubre de 2026.

Qué es opencode

opencode es un agente de programación para la terminal que no está atado a una sola empresa de IA. Claude Code usa modelos de Anthropic y Codex usa modelos de OpenAI. opencode está construido sobre el AI SDK y Models.dev, así que funciona con docenas de proveedores y con modelos locales. Puedes usar un modelo para planificar y otro para construir, y cambiar de proveedor sin aprender una herramienta nueva.

Una nota sobre versiones: ya ha salido opencode 2, con su propia documentación. Las dos versiones instalan un comando llamado opencode, y no puedes tener ambas con ese nombre. Esta guía sigue la versión 1, que es la que instala el paquete npm opencode-ai. Casi todo vale también para la versión 2. Si lo instalaste con la fórmula principal de Homebrew o desde el repositorio principal de Arch, probablemente tienes la versión 2, así que consulta la documentación correspondiente.

Paso 1: instala opencode

bun, pnpm y yarn global add opencode-ai también funcionan. En Windows, la documentación recomienda ejecutar opencode dentro de WSL para tener la mejor experiencia. Una terminal moderna como WezTerm, Alacritty, Ghostty o Kitty es la que mejor muestra la TUI.

opencode nunca se actualiza solo en segundo plano. Dentro de una sesión, /update instala una versión 1 más reciente o, si ya tienes la última versión 1, te ofrece pasar a la versión 2. Desde la shell, opencode upgrade hace lo mismo.

Paso 2: conecta un proveedor y elige un modelo

Entra en un proyecto y arranca opencode:

cd my-project
opencode

Después ejecuta /connect y elige un proveedor. Puedes hacer lo mismo desde la shell con opencode auth login. Las credenciales se guardan en ~/.local/share/opencode/auth.json, y opencode auth list muestra qué hay conectado. opencode también toma las API keys de las variables de entorno y de un archivo .env en el proyecto.

Algunas opciones habituales:

• OpenCode Zen: una lista seleccionada de modelos que el equipo de opencode ha probado con el agente. Inicia sesión en opencode.ai/auth, añade la facturación, copia la key y pégala en /connect. La documentación lo sugiere para quienes empiezan.
• Anthropic: pega una API key de la Claude Console. No se ofrece iniciar sesión con una suscripción Claude Pro o Max. Anthropic no permite que herramientas de terceros usen esos planes de esta forma, y opencode dejó de incluir los plugins que lo hacían.
• OpenAI: elige “ChatGPT Plus/Pro” para iniciar sesión en el navegador, o introduce una API key a mano.
• GitHub Copilot: inicia sesión con un código de dispositivo en github.com/login/device. Algunos modelos necesitan un plan de Copilot superior.
• Modelos locales: añade un proveedor personalizado que apunte a un servidor compatible con OpenAI (lo verás más abajo).

Con un proveedor conectado, /models (o ctrl+x m) abre el selector de modelos. Desde la shell, opencode models lista todos los modelos que ofrecen tus proveedores, y opencode models anthropic lista los de un solo proveedor. Los modelos se escriben como proveedor/modelo, por ejemplo anthropic/claude-sonnet-5-5. Muchos modelos tienen variantes, como un esfuerzo de razonamiento mayor, y ctrl+t las recorre.

Modelos locales con Ollama

Un modelo local es un proveedor personalizado en opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

Si las llamadas a herramientas fallan con un modelo local, la documentación sugiere subir el num_ctx de Ollama a unos 16k–32k. Una ventana de contexto pequeña suele ser la causa. Para elegir el modelo local en primer lugar, consulta agentes de programación con LLM locales.

Paso 3: lo básico de la TUI

La pantalla de opencode es un chat con tu proyecto. Esto es lo que usarás todo el rato:

• @ busca archivos de forma aproximada y los añade a tu mensaje.
• ! al principio de una línea ejecuta un comando de shell, por ejemplo !npm test, y pone la salida en la conversación.
• ctrl+x es la tecla líder. La mayoría de los atajos son ctrl+x seguido de una letra.
• Puedes arrastrar imágenes a la terminal para incluirlas.

/undo se apoya en Git para revertir los cambios en archivos, así que el proyecto debería ser un repositorio Git. Para seguir donde lo dejaste desde la shell, opencode -c reabre la última sesión y opencode -s <id> abre una concreta. Para scripts y CI, opencode run "your prompt" ejecuta una sola tarea sin la TUI.

Paso 4: los agentes Build y Plan

opencode tiene dos agentes principales, y Tab alterna entre ellos:

• Build es el predeterminado. Tiene todas las herramientas activadas: edita archivos, ejecuta comandos de shell y llama a servidores MCP.
• Plan está restringido. No puede editar tu código; los únicos archivos que puede escribir son planes en Markdown en .opencode/plans/. Puede hacerte preguntas para aclarar dudas.

Un buen hábito para cualquier cosa que no sea trivial es empezar en Plan, acordar un enfoque y luego pulsar Tab y decirle a Build que lo lleve a cabo. También hay dos subagentes que llamas con @: @general, para investigación y cambios de varios pasos, y @explore, para búsquedas rápidas de solo lectura en el código. Cada uno se ejecuta en una sesión hija. ctrl+x y luego la flecha abajo entra en ella, y la flecha arriba vuelve a la sesión padre. La entrada del glosario sobre el subagente explica por qué esto ahorra contexto.

Un detalle que conviene vigilar: Plan no limita bash por sí mismo. Los comandos de shell siguen tus ajustes de permisos. Además, un "edit": "allow" en el nivel superior de tu configuración también se aplica a Plan, porque ganan las reglas que coinciden después. Si quieres Plan bien cerrado, define sus permisos directamente:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": "ask"
      }
    }
  }
}

Puedes crear tus propios agentes con opencode agent create, o como archivos Markdown en .opencode/agents/ (por proyecto) o ~/.config/opencode/agents/ (globales). El nombre del archivo pasa a ser el nombre del agente. El frontmatter define su description, mode (primary o subagent), model y permission.

Paso 5: el archivo de configuración

opencode lee opencode.json (u opencode.jsonc, que admite comentarios). Hay dos sitios habituales:

• Global: ~/.config/opencode/opencode.json, para tus valores por defecto.
• Proyecto: opencode.json en la raíz del proyecto, con commit junto al código.

Los archivos se combinan, no se sustituyen, y los ajustes del proyecto ganan donde se solapan. Una configuración de proyecto práctica:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "small_model": "anthropic/claude-haiku-5-5",
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "npm test *": "allow"
    }
  },
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

• model es el modelo por defecto. small_model se usa para tareas ligeras, como los títulos de las sesiones.
• permission acepta allow, ask o deny por herramienta, con patrones para bash. Gana el último patrón que coincide, así que pon "*" el primero.
• instructions añade más archivos de reglas además de AGENTS.md. Admite globs y URL.

Los valores pueden venir del entorno con {env:VAR} o de un archivo con {file:path}, así que las keys nunca tienen que estar en la configuración. Por defecto, la mayoría de las acciones están permitidas. Leer archivos .env y tocar carpetas fuera del proyecto piden confirmación antes. opencode --auto aprueba todo lo que no esté denegado explícitamente, así que úsalo solo donde te parezca bien dejar al agente trabajar sin supervisión.

Los ajustes de la TUI, como el tema y los keybinds, van en un tui.json aparte.

Paso 6: AGENTS.md

AGENTS.md contiene las reglas de tu proyecto: cómo compilar, probar y pasar el lint, las convenciones que hay que seguir y las carpetas que no hay que tocar. Ejecuta /init y opencode analiza el proyecto y te escribe uno. Léelo, recórtalo y haz commit.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- API handlers live in src/api/; one file per route.
- Never edit files in src/generated/.

Las reglas globales para todos los proyectos van en ~/.config/opencode/AGENTS.md. Si vienes de Claude Code, opencode recurre a un CLAUDE.md del proyecto cuando no hay AGENTS.md, y también lee ~/.claude/CLAUDE.md y ~/.claude/skills/. Define OPENCODE_DISABLE_CLAUDE_CODE=1 para desactivarlo. Cómo escribir CLAUDE.md y AGENTS.md explica qué debe ir en el archivo.

Paso 7: servidores MCP

Los servidores MCP dan a opencode herramientas nuevas: un navegador, un gestor de incidencias, búsqueda en documentación. Van bajo la clave mcp. Un servidor local es un comando que opencode arranca; un servidor remoto es una URL:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    },
    "my-remote": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_MCP_TOKEN}"
      }
    }
  }
}

opencode mcp add añade un servidor de forma interactiva, y opencode mcp list muestra lo que está configurado y si conecta. Los servidores remotos que usan OAuth inician sesión automáticamente, y opencode mcp auth <name> inicia sesión a mano. opencode mcp debug <name> ayuda cuando un servidor no conecta.

Cada servidor añade sus herramientas al contexto de cada petición, y algunos grandes, como el servidor MCP de GitHub, añaden mucho. Activa solo los servidores que necesites y pon "enabled": false para dejar uno configurado pero apagado.

Paso 8: comandos personalizados

Un comando personalizado es un prompt que, si no, tendrías que volver a escribir. Pon un archivo Markdown en .opencode/commands/ (por proyecto) o ~/.config/opencode/commands/ (global); el nombre del archivo pasa a ser el comando:

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

Guardado como .opencode/commands/test.md, se convierte en /test. Los comandos aceptan argumentos: $ARGUMENTS es todo lo que va después del nombre del comando, $1, $2, etc. son argumentos sueltos, !`git diff --staged` inserta la salida de un comando de shell y @src/file.ts incluye un archivo. También puedes definir comandos bajo la clave command de opencode.json con un template. Si un comando personalizado se llama igual que uno integrado, gana el integrado.

Errores habituales

• “No provider” en la primera ejecución. Todavía no hay nada conectado. Ejecuta /connect.
• Ediciones en modo Plan. Un "edit": "allow" global también llega a Plan. Define agent.plan.permission de forma explícita.
• /undo no revierte archivos. La carpeta no es un repositorio Git.
• Dos versiones de opencode peleándose. Homebrew core instala la versión 2 y npm instala la versión 1 con el mismo nombre de comando. Comprueba opencode --version y quédate con una.
• Sesiones lentas y caras. Demasiados servidores MCP o una sesión larga. Apaga servidores y usa /compact o /new.

Ejecutar opencode en paneles de AgentVera

Una sesión de opencode es fácil de seguir. Varios agentes a la vez, unos en opencode y otros en Claude Code o Codex, es donde las pestañas de la terminal empiezan a estorbar. AgentVera es una app de escritorio que ejecuta estas CLI una al lado de otra en terminales reales, con tus propias instalaciones e inicios de sesión. Su soporte de opencode funciona así:

• Tus proveedores, tu inicio de sesión. Inicias sesión en los proveedores dentro del propio opencode (/connect u opencode auth login), y cada proveedor que conectas, modelos locales incluidos, aparece en la lista de modelos de AgentVera, agrupado por proveedor. Las variantes de los modelos aparecen como opciones de esfuerzo. Si opencode no está instalado, AgentVera lo instala con npm i -g opencode-ai.
• Una sesión por agente. Cada agente de opencode tiene su propia sesión, así que duplicar un agente bifurca su conversación en lugar de compartirla. /compact funciona como siempre.
• Tu opencode.json queda intacto. El rol del agente, los servidores MCP que añadiste en el gestor de MCP de AgentVera y el navegador de AgentVera se pasan como configuración extra y se combinan con la tuya.
• Paneles y worktrees. Ejecuta opencode junto a Claude Code en la cuadrícula del workspace, cada agente en su propio git worktree, para que no se pisen los archivos.
• Revisión y flujos. Los agentes de opencode funcionan con la revisión de código automática, y en los flujos (Pro y Team) la respuesta de un agente puede pasar a otro automáticamente. Por ejemplo, un modelo barato planifica y uno más potente construye.

La cuadrícula, los worktrees, la revisión de código y el gestor de MCP están en el plan gratuito. Descarga AgentVera para probarlo. Si tu equipo también ejecuta Claude en CI, Claude Code GitHub Actions cubre esa parte, y cómo usar Codex CLI es la misma guía para el agente de OpenAI.

Conclusión

Para usar opencode, instálalo, ejecuta opencode en un proyecto, conecta un proveedor con /connect y elige un modelo con /models. Usa Plan para pensar y Build para cambiar código, y alterna entre ellos con Tab. Pon tus valores por defecto en opencode.json, las reglas del proyecto en AGENTS.md, tus herramientas bajo mcp y los prompts que repites en .opencode/commands/. A partir de ahí, opencode consiste sobre todo en elegir el modelo adecuado para cada trabajo, y te deja cambiarlo cuando quieras.