# Cómo usar opencode: guía paso a paso URL: https://agentvera.dev/es/blog/how-to-use-opencode/ · Publicado: 2026-10-27 Cómo usar opencode: instálalo, conecta un proveedor, elige un modelo, alterna entre Build y Plan y configura opencode.json, AGENTS.md, servidores MCP y comandos. **En resumen:** - Instala opencode con el script oficial o npm, ejecuta opencode en un proyecto, conecta un proveedor con /connect y elige un modelo con /models; sirve cualquier proveedor, también modelos locales. - Tab alterna entre el agente Build, que edita y ejecuta comandos, y el agente Plan, que no puede editar tu código y sirve para pensar un cambio antes de hacerlo. - Los ajustes van en opencode.json (global y por proyecto) y las reglas del proyecto en AGENTS.md; los servidores MCP, bajo la clave mcp, y los comandos propios, en .opencode/commands/. 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](/es/glossary/coding-agent/ "Qué 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 | Plataforma | Comando | | --- | --- | | macOS, Linux | `curl -fsSL https://opencode.ai/install \| bash` | | Cualquier plataforma con Node.js | `npm install -g opencode-ai` | | macOS, Linux (Homebrew, versión 1) | `brew install anomalyco/tap/opencode` | | Windows | `choco install opencode` o `scoop install 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: ```bash 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`: ```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](/es/blog/local-llm-coding-agent/ "Agente de programación con un LLM local"). ## 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. | Comando | Atajo | Qué hace | | --- | --- | --- | | `/connect` | | Añade un proveedor | | `/models` | `ctrl+x m` | Elige un modelo | | `/new` | `ctrl+x n` | Empieza una sesión nueva | | `/sessions` | `ctrl+x l` | Abre una sesión anterior | | `/compact` | `ctrl+x c` | Resume la sesión para liberar contexto | | `/undo` | `ctrl+x u` | Deshace el último mensaje y sus cambios en archivos | | `/redo` | `ctrl+x r` | Rehace lo que deshiciste | | `/editor` | `ctrl+x e` | Escribe un prompt largo en tu `$EDITOR` | | `/export` | `ctrl+x x` | Exporta la conversación como Markdown | | `/init` | | Crea o actualiza `AGENTS.md` | | `/exit` | `ctrl+x q` | Sale | `/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 ` 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](/es/glossary/subagent/ "Qué es un 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: ```json { "$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: ```json { "$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. ```markdown # 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](/es/blog/claude-md-agents-md/ "Cómo escribir CLAUDE.md y AGENTS.md") explica qué debe ir en el archivo. ## Paso 7: servidores MCP Los [servidores MCP](/es/blog/what-is-mcp-server/ "Qué es un servidor 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: ```json { "$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 ` inicia sesión a mano. `opencode mcp debug ` 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: ```markdown --- 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](/es/agents/opencode/ "opencode en AgentVera") 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](/es/features/mcp-manager/ "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](/es/features/workspace/ "Workspace"), cada agente en su propio [git worktree](/es/glossary/git-worktree/ "Qué es un 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](/es/features/code-review/ "Revisión de código automática"), y en los [flujos](/es/features/flows/ "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](/es/download/ "Descargar AgentVera") para probarlo. Si tu equipo también ejecuta Claude en CI, [Claude Code GitHub Actions](/es/blog/claude-code-github-actions/ "Claude Code GitHub Actions") cubre esa parte, y [cómo usar Codex CLI](/es/blog/how-to-use-codex-cli/ "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. ## Preguntas frecuentes **¿opencode es gratis?** Instalar la CLI no cuesta nada. Pagas los modelos que usas a través de tu proveedor: una API key facturada por token, una suscripción que ya tengas, como GitHub Copilot o ChatGPT Plus/Pro, u OpenCode Zen. Los modelos locales con Ollama no cuestan nada aparte de tu propio hardware. **¿Qué modelos puede usar opencode?** Los de cualquier proveedor compatible: Anthropic, OpenAI, Google, GitHub Copilot, OpenRouter, OpenCode Zen y muchos más, además de modelos locales a través de un servidor compatible con OpenAI como Ollama. Ejecuta opencode models para ver lo que ofrecen tus proveedores conectados. **¿Qué diferencia hay entre los agentes Build y Plan?** Build es el predeterminado y tiene todas las herramientas, así que edita archivos y ejecuta comandos. Plan no puede editar tu código; solo puede escribir planes en Markdown en .opencode/plans/. Usa Plan para pensar un cambio y luego pulsa Tab para pasar a Build y llevarlo a cabo. **¿opencode lee CLAUDE.md?** Sí, como alternativa. Si un proyecto no tiene AGENTS.md, opencode lee CLAUDE.md, y para las reglas globales también recurre a ~/.claude/CLAUDE.md. Define OPENCODE_DISABLE_CLAUDE_CODE=1 para desactivar estas alternativas de Claude Code. **¿Dónde guarda opencode sus ajustes y sus inicios de sesión?** Los ajustes globales están en ~/.config/opencode/opencode.json y los del proyecto en opencode.json, en la raíz del proyecto; los dos se combinan. Las credenciales de proveedor de /connect se guardan en ~/.local/share/opencode/auth.json. --- **Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/