Tutorial de introducción a OpenCode

OpenCode es un agente de programación con IA de código abierto (AI coding agent) que permite interactuar con la IA en la terminal (Terminal), aplicaciones de escritorio e IDE principales (como VS Code) para realizar tareas relacionadas con el código.

OpenCode nos ayuda a comprender el código base, escribir nuevas funciones, refactorizar código, corregir errores (bugs), etc., mejorando significativamente la eficiencia del desarrollo.

OpenCode es similar al modo Code de Claude o a la función Agent de Cursor, pero es completamente de código abierto, prioriza la privacidad, admite múltiples modelos de lenguaje grandes (LLM) y enfatiza la experiencia en terminal.

OpenCode admite más de 75 proveedores de modelos. Incluye modelos gratuitos integrados como GLM-4.7 y MiniMax M2.1, puede conectarse a modelos comerciales como OpenAI, Anthropic, Google, y también permite configurar modelos locales (como Llama 3), adaptándose según sea necesario a diferentes escenarios como scripts ligeros o arquitecturas complejas.

Referencia del tutorial completo de OpenCode:https://www.example.com/opencode/opencode-tutorial.html

Características clave

Dos modos de agente integrados:

  • Modo Build:Permisos completos; puede editar archivos y ejecutar comandos directamente.
  • Modo Plan:Planificación de solo lectura; rechaza la edición por defecto y requiere confirmación.

Conjunto de herramientas:Ejecución de bash, lectura/escritura de archivos, búsqueda grep, diagnóstico LSP, etc.

Percepción del contexto:Analiza automáticamente la estructura del proyecto y genera una guía AGENTS.md.

Compartir y colaborar:Genera con un clic un enlace para compartir la sesión.

Instalar OpenCode

OpenCode admite instalación en múltiples plataformas: macOS / Windows / Linux.

Script de instalación universal con un solo clic: este es el método más sencillo:

curl -fsSL https://opencode.ai/install | bash

Después de la instalación, deberías poder ejecutar desde la línea de comandos:

opencode --version

Si la salida es similar a1.1.19Ese tipo de información de versión indica que la instalación fue exitosa.

Instalación mediante gestor de paquetes

macOS / Linux

brew install opencode

O bien:

npm install -g opencode-ai

Windows

choco install opencode

O bien:


scoop bucket add extras
scoop install extras/opencode

Arch Linux

paru -S opencode-bin

OpenCode se ejecuta en la terminal; podemos usar la terminal predeterminada del sistema o también algunas herramientas de terminal modernas y útiles:

Aplicación de escritorio

OpenCode también ofrece una aplicación de escritorio, que se puede descargar directamente desdela página de lanzamientosoopencode.ai/downloadDescargar.

Plataforma del sistema Descargar el paquete de instalación
macOS (chip de Apple) opencode-desktop-darwin-aarch64.dmg
macOS (chip Intel) opencode-desktop-darwin-x64.dmg
Windows opencode-desktop-windows-x64.exe
Linux Formatos .deb, .rpm o AppImage

Inicio y uso

Para iniciar OpenCode solo necesitas ingresar el comando de inicio en la terminal:

opencode

El primer inicio te guiará para completar la configuración básica:

  • Selección de modelo:De forma predeterminada se muestra la lista de modelos disponibles; puedes seleccionar directamente los modelos gratuitos marcados como Free (por ejemplo, MiniMax M2.1, GLM-4.7) y usarlos sin necesidad de clave de API.
  • Opciones de inicio de sesión:Puedes optar por omitir el inicio de sesión y configurar una clave de API más adelante cuando necesites conectar modelos comerciales; también puedes iniciar sesión con una cuenta de Claude Code Pro para utilizar modelos exclusivos.

Una vez iniciado correctamente, entrarás en la interfaz TUI y podrás comenzar a usar las funciones principales.

Podemos escribir /models en la terminal para ver los modelos gratuitos disponibles:

En la vista emergente, los que tienen la palabra Free a la derecha son gratuitos:

Configurar la clave de API y el modelo

Si conectas una clave de API de un proveedor de IA, por ejemplo OpenAI o Anthropic Claude, ejecuta:

opencode auth login

O, después de iniciar la terminal, ingresa:

/connect

Selecciona el modelo. Sigue las indicaciones para iniciar sesión y pega tu clave de API.

También puedes usarZenEl conjunto de modelos (modelos de alta calidad recomendados y probados oficialmente por OpenCode), lo que te ahorra la molestia de gestionar múltiples cuentas externas por tu cuenta.

Si ya no quieres usarlo, puedes salir con el siguiente comando:

/exit

Uso básico

Iniciar OpenCode

Entra en el directorio del proyecto que quieres tratar:

cd /path/to/your/project
opencode

Por ejemplo, creamos el directorio opencode-ejemplo-test:

mkdir opencode-ejemplo-test
cd opencode-ejemplo-test

Luego ejecuta el comando:

opencode

Si hay problemas de permisos, puedes usar:

sudo opencode

Esto abrirá la interfaz interactiva de terminal (TUI) de OpenCode.

Inicialización del proyecto

En la interfaz de OpenCode, ejecuta:

/init

Esto generará una carpeta .opencode/ para almacenar el índice vectorial y las instrucciones personalizadas del proyecto.

Escanea la estructura de código del directorio actual y genera un archivo AGENTS.md para registrar la información del proyecto.

En el directorio opencode-ejemplo-test se puede ver el archivo AGENTS.md:

Luego usamos lenguaje natural para describir tus necesidades e iniciar la tarea:

Crear una página de inicio de sesión en el directorio actual.

A continuación, el modelo grande comenzará a razonar y creará la página de inicio de sesión:

Archivos generados:

Preguntar y explicar el código

Puedes preguntar directamente a OpenCode en lenguaje natural sobre los detalles del código base:

¿Qué funciones incluye el archivo @index.html?

Donde@se usa para hacer referencia a la ruta de archivos del proyecto.

Interacción diaria

  • Pregunta directamente: por ejemplo, "Explica la lógica de autenticación en src/main.ts".
  • Añadir funciones: describe el requisito, como "Agrega una API de registro de usuarios con verificación de correo electrónico".
  • Cambiar de modo: presiona la tecla Tab para alternar entre los modos Plan/Build (Plan es más seguro, para planificar).
  • Deshacer cambios: /undo
  • Rehacer: /redo
  • Compartir sesión: /share

Modo interactivo (scripting):

opencode -p "修复 login 函数中的 bug"

Introducción a las herramientas integradas

El agente de IA de OpenCode opera sobre el código base mediante las siguientes herramientas (puedesopencode.jsoncontrolar los permisos con allow/deny/ask):

  • bash: Ejecutar comandos de shell (por ejemplo,git status、npm test）。
  • write/edit/patch: Crear/modificar/aplicar parches a archivos.
  • read: Leer el contenido de archivos (admite rango de líneas).
  • grep/glob/list: Buscar y listar archivos (respeta .gitignore).
  • webfetch: Obtener contenido web (consultar documentación).
  • lsp(Experimental): navegación de código, información al pasar el cursor, etc.
  • question: Preguntarte para confirmar.
  • todo: Mantener la lista de tareas.

Las herramientas personalizadas y los servidores MCP (Model Context Protocol) admiten extensiones (como conectar a bases de datos).

Uso avanzado

  • Comandos personalizados: En~/.config/opencode/commands/crear un archivo Markdown, comoprime-context.md, cuyo contenido es una instrucción precargada.
  • Tema y teclas: Personaliza la apariencia y los atajos de teclado en la configuración.
  • Múltiples sesiones: Activa varios agentes al mismo tiempo para manejar diferentes tareas.
  • Integración con IDE: Actualmente admite la extensión de VS Code (busca 'OpenCode extension') o el control remoto a través de arquitectura cliente/servidor.
  • Control de permisos: En el archivo de configuración, configura las herramientas paraaskconfirmar manualmente las operaciones sensibles.

Crear una API sencilla de Node.js

  1. Crea un nuevo directorio:mkdir my-api && cd my-api
  2. Inicializa:npm init -y
  3. Inicia OpenCode:opencode
  4. Entrada/init
  5. Pregunta: crea un servicio Express.js que admita una ruta /hello que devuelva JSON { message: 'Hello World' }, y añade un README.

oh-my-opencode

oh-my-opencode es una potente capa de plugin/extensión diseñada para OpenCode. Actualiza un único agente de IA a un equipo de colaboración multiagente, ofreciendo funciones avanzadas listas para usar.

Repositorio de GitHub:https://github.com/code-yeongyu/oh-my-opencode

Los aspectos más destacados incluyen:

  • SisyphusAgente principal: responsable de ejecutar tareas complejas de forma continua hasta completarlas.
  • Admite la ejecución paralela de subagentes especializados (como Oracle (oráculo), Librarian (experto en documentación), Frontend Engineer (ingeniero frontend), Explore (explorador), etc.).
  • Herramientas LSP/AST integradas (refactorización de código), MCP (plugins de invocación de modelos, como búsqueda, recuperación de documentos), sistema de hooks (más de 25 tipos de activación por eventos).
  • Programación multimodelo: asigna automáticamente tareas al modelo más adecuado (por ejemplo, Gemini para frontend, Claude para planificación).
  • Activación por palabras clave de automatización completa (comoultraworkoulw), admite tareas en segundo plano, ejecución forzada de Todo, inyección de contexto, etc.
  • Totalmente compatible con el flujo de trabajo de Claude Code, enfatizando alto rendimiento, automatización y personalización.

Instalación

Se recomienda dejar que OpenCode complete la instalación automáticamente. Copia el siguiente mensaje y pégalo en el cuadro de diálogo de OpenCode:

按照以下说明安装和配置 oh-my-opencode：
https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/docs/guide/installation.md

Tras la instalación, está listo para usar por defecto. Puedes probar la mayoría de las funciones sin necesidad de configuración adicional.

Activación básica

Añade la palabra clave ultrawork (o su abreviatura ulw) al mensaje de OpenCode, por ejemplo:

ultrawork: 请帮我实现一个 React 组件，支持暗黑模式。

Esto activa el modo completo: el agente principal Sisyphus toma el control, asigna automáticamente subtareas a agentes especializados y las ejecuta en paralelo (mapeo de la base de código en segundo plano, exploración profunda, refactorización automática, etc.) hasta que la tarea se complete al 100%.

Tabla de referencia rápida de comandos Slash comunes de OpenCode TUI

Los comandos Slash de OpenCode (que comienzan con/) se utilizan principalmente en la interfaz de usuario de terminal (TUI) para controlar rápidamente sesiones, configuración y operaciones.

Configuración e inicialización principales

Comando Descripción Alias/Atajo
/connect Añadir o configurar el proveedor de LLM (API Key) Ninguno
/init Crear o actualizar el proyectoAGENTS.mdarchivo (analizar la base de código) Ctrl+X I
/models Listar los modelos disponibles y cambiar entre ellos Ctrl+X M

Gestión de sesiones

Comando Descripción Alias/Atajo
/new Iniciar nueva sesión (borrar la actual) /clear / Ctrl+X N
/sessions Listar y cambiar de sesión /resume / /continue / Ctrl+X L
/share Compartir la sesión actual (generar enlace) Ctrl+X S
/unshare Cancelar compartir la sesión actual Ninguno
/compact Comprimir/resumir la sesión actual /summarize / Ctrl+X C

Edición y deshacer

Comando Descripción Alias/Atajo
/undo Deshacer la última operación (requiere repositorio Git, admite revertir cambios de archivos) Ctrl+X U
/redo Rehacer la operación deshecha (requiere repositorio Git) Ctrl+X R

Vista y ayuda

Comando Descripción Alias/Atajo
/details Cambiar la visualización de detalles de ejecución de herramientas Ctrl+X D
/thinking Cambiar la visibilidad del proceso de pensamiento/razonamiento Ninguno
/theme Listar y cambiar de tema Ctrl+X T
/help Mostrar el diálogo de ayuda Ctrl+X H
/editor Escribir mensajes con un editor externo Ctrl+X E
/export Exportar la conversación actual a Markdown y abrir para editar Ctrl+X X

Salir

Comando Descripción Alias/Atajo
/exit Salir de OpenCode /quit / /q / Ctrl+X Q

Nota：

  • Estos comandos se introducen directamente en la interfaz de chat TUI/+ nombre del comando para activarlos (aparecerá autocompletado).
  • /undoy/redoEl proyecto debe ser un repositorio Git para poder revertir los cambios de archivos.
  • Puedes crear comandos Slash personalizados (colócalos en~/.config/opencode/commands/o en el directorio del proyecto), que sobrescribirán los comandos integrados.
  • Más detalles en la documentación oficial:https://opencode.ai/docs/tui

Tabla de referencia rápida de parámetros comunes de OpenCode CLI

La interfaz de línea de comandos (CLI) de OpenCode se utiliza principalmente para iniciar la TUI (interfaz de terminal), ejecutar mensajes en modo no interactivo o establecer opciones básicas. La ejecución por defectoopencodeiniciará directamente la TUI interactiva.

A continuación se muestran los parámetros globales (flags) comunes:

Parámetro Abreviatura Descripción Ejemplo
--help -h Mostrar información de ayuda (listar todos los parámetros disponibles) opencode --help
--debug -d Activar modo de depuración (genera más registros para facilitar la resolución de problemas) opencode -d
--cwd -c Especificar el directorio de trabajo actual (cambiar a esa ruta al iniciar) opencode -c /path/to/your/project
--prompt -p Modo no interactivo: ejecutar un solo mensaje y generar la respuesta (ideal para scripts/automatización) opencode -p "修复这个 bug"
--output-format -f Formato de salida en modo no interactivo (textojson, por defecto text) opencode -p "解释代码" -f json
--quiet -q Ocultar la animación de carga (spinner) en modo no interactivo opencode -p "生成 README" -q

Ejemplo de uso básico

  • Iniciar TUI interactiva：opencode
  • Iniciar con depuración：opencode -d
  • Iniciar especificando el directorio del proyecto：opencode -c ~/my-app
  • Mensaje único no interactivo：opencode -p "添加一个登录接口" -f json

Nota：

  • Estos parámetros son globales y se pueden combinar.
  • Modo no interactivo (-p) es especialmente adecuado para CI/CD, scripts o consultas rápidas, sin entrar en la TUI.
  • Más configuración avanzada (como selección de modelos) normalmente se gestiona mediante variables de entorno o archivos de configuración~/.opencode.json, no mediante parámetros CLI.
  • Ejecutaropencode --helppara ver la lista completa más reciente (recomendado, ya que la herramienta puede actualizarse).

Dirección de referencia

Otras extensiones