Instalación de OpenCode y configuración de OmniProxy

OpenCode es un asistente de programación de código abierto que te permite escribir código desde una terminal, IDE o escritorio. No almacena tu código ni tu contexto, lo que lo hace adecuado para proyectos sensibles a la privacidad. build se utiliza para modificar un proyecto, mientras que plan es de solo lectura por defecto y es útil para entender código desconocido y planificar cambios antes de realizarlos. Puedes elegir un servicio de modelos según tus necesidades.

Antes de comenzar

El script de instalación es la opción más sencilla. Necesitas una terminal moderna (una aplicación de terminal que pueda ejecutar comandos y trabajar con archivos de proyecto), como WezTerm, Alacritty, Ghostty o Kitty. En Windows, se prefiere WSL. Proporciona un entorno Linux dentro de Windows con un rendimiento y funcionalidad más completos.

Más fácil

Script de instalación

curl opencode.ai/install
Usar directamente en macOS Linux
Se recomienda WSL en Windows

macOS Linux

Homebrew tap

anomalyco/tap/opencode
Actualizado con más frecuencia que la fórmula
También hay un paquete disponible para Arch

Windows nativo

Gestor de paquetes

choco o scoop
O instalar globalmente con npm
También puedes descargarlo desde Releases

Comienza con el script de instalación. Si ya te sientes cómodo con los gestores de paquetes, usa uno de los otros comandos listados.

Prepara también el ID del modelo de la lista de modelos actual. Un ID de modelo es el nombre que el servicio utiliza para identificar un modelo específico con precisión.

Instalación y primer inicio

El comando de instalación más sencillo es:

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

También puedes usar uno de estos métodos de instalación:

Node.js: npm install -g opencode-ai. Bun, pnpm y Yarn también tienen comandos de instalación global correspondientes; consulta la página de introducción al final de esta guía.
Homebrew en macOS y Linux: brew install anomalyco/tap/opencode. Usa este tap porque se actualiza con más frecuencia que brew install opencode, que es mantenido por el equipo de Homebrew.
Arch Linux: usa sudo pacman -S opencode para la versión estable, o el paquete AUR opencode-bin para una versión más reciente.
Windows: usa choco install opencode o scoop install opencode. También puedes usar npm install -g opencode-ai. Los archivos binarios también se pueden descargar desde Releases. El soporte para instalar con Bun en Windows aún está en desarrollo.

Ingresa a tu directorio de proyecto, luego inicia OpenCode:

cd /path/to/project
opencode

Al usarlo por primera vez, puedes ejecutar /init. Analiza el proyecto y crea AGENTS.md en la raíz del proyecto. Este archivo se puede subir a Git para que el proyecto conserve estas instrucciones.

Obtener valores de conexión de OmniProxy

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy from the current OmniProxy model list

baseURL es la dirección del servicio, API Key es la credencial de acceso y Model ID es el nombre completo del modelo.

Al usar /v1/chat/completions, establece el paquete npm en @ai-sdk/openai-compatible. Chat Completions es un tipo de interfaz de solicitud de chat. Cambia a @ai-sdk/openai solo cuando el modelo use /v1/responses. Cuando OmniProxy se usa a través del endpoint de chat completions, mantén el paquete de compatibilidad.

Copia el ID completo del modelo de la lista actual de OmniProxy, incluyendo cualquier barra diagonal. Al 09-10-2026, dos IDs de referencia eran claude-sonnet-5-5 y gpt-6-luna. gpt-6-luna soporta Chat Completions; la llamada a funciones a través de Chat Completions solo se admite cuando reasoning_effort es none. No copies un ID que no esté en la lista.

Ingresar la configuración de la herramienta

Un Proveedor puede entenderse como un conjunto de valores de configuración que OpenCode utiliza para conectarse a un servicio de modelo. La documentación del Proveedor trata a un servicio compatible con OpenAI que no aparece bajo /connect como un Proveedor personalizado. Un servicio compatible con OpenAI utiliza el mismo formato de solicitud y puede ser llamado por el mismo tipo de cliente.

Ejecuta /connect en OpenCode y desplázate hasta Other.
Ingresa un ID de Proveedor. El ejemplo a continuación usa omniproxy. Elige un ID que sea fácil de recordar porque debes usar el mismo en el archivo de configuración.
Ingresa la clave API de OmniProxy. Este paso solo guarda la credencial; la dirección y los modelos aún deben añadirse a opencode.json. La credencial se almacena en ~/.local/share/opencode/auth.json.
Crea o modifica opencode.json en el directorio del proyecto:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

Ejecuta /models. El Proveedor personalizado y sus modelos aparecerán en la lista.

El ID ingresado bajo /connect debe coincidir con la clave en opencode.json. No pongas una clave secreta real en este archivo. Si no usas /connect, puedes usar la sintaxis de variable de entorno en options.apiKey, como {env:VARIABLE_NAME}. En las pruebas realizadas el 09-10-2026 con OpenCode 1.18.34, poner la clave directamente en el options.apiKey del proyecto sin usar /connect también se conectó con éxito. Si el gateway no valida la clave, este valor puede ser una cadena de marcador de posición usada solo en la máquina local. Las claves bajo models deben usar los IDs completos de la lista.

Clave

/connect

Seleccionar Other en la parte inferior
Elige tu propio ID de Proveedor
Almacenado en auth.json

Proyecto

opencode.json

La clave del proveedor debe usar el mismo nombre
Usar un paquete npm compatible
baseURL termina con /v1

Seleccionar

/models

El modelo aparece en la lista
Selecciona uno antes de hacer una pregunta
Usar el ID de la lista del gateway

La clave y la dirección se almacenan en dos lugares diferentes. El ID del Proveedor debe ser el mismo en ambos.

Verificar con una tarea real

Ejecuta primero una tarea real desde el directorio del proyecto. El formato de referencia del modelo es Provider ID/model ID; conserva cualquier barra diagonal dentro del ID del modelo:

opencode run --model omniproxy/claude-sonnet-5-5 --auto "Explain what a file you specify does. Do not modify the file."

--auto permite que esta ejecución use herramientas como las de lectura de archivos. En las pruebas realizadas el 09-10-2026 con OpenCode 1.18.34, leyó con éxito el contenido del archivo especificado. La primera ejecución tomó alrededor de dos minutos.

Para uso interactivo, ejecuta opencode, luego selecciona un modelo con /models. Puedes usar @ para buscar archivos. Usa opencode auth list para confirmar la credencial guardada a través de /connect, luego comprueba los registros de solicitudes de OmniProxy para verificar la fuente y el ID del modelo.

Iniciar

opencode se inicia

Primero cd al proyecto
auth list muestra el ID
El archivo de configuración está en el proyecto

Tarea

Leyó el código

Preguntar sobre un archivo específico
Revisar su explicación
Usar /undo si está mal

Registros

Visible en el gateway

La fuente es OpenCode
El ID del modelo coincide
No subir la clave

Después de guardar el archivo de configuración, completa una solicitud real desde dentro del proyecto.

Errores comunes

OmniProxy no aparece bajo /models: Comprueba que el ID ingresado bajo /connect coincida con la clave en opencode.json, que npm esté establecido en @ai-sdk/openai-compatible y que baseURL termine con /v1.
Falta la credencial: Ejecuta opencode auth list. Los proveedores como Bedrock que dependen de variables de entorno no aparecen aquí; un Proveedor personalizado configurado a través de /connect debería ser visible.
La funcionalidad de Windows está incompleta: Usa el script de instalación dentro de WSL en su lugar.
El ID del modelo no es válido: Cópialo de nuevo de la lista actual de OmniProxy y actualiza la clave correspondiente bajo models.
Las solicitudes van al endpoint incorrecto: Mantén @ai-sdk/openai-compatible para chat completions. No cambies el paquete para la interfaz de Respuestas a menos que ese modelo en OmniProxy realmente use /v1/responses.

Referencias oficiales

Para la instalación, consulta la OpenCode introduction. Para Proveedores personalizados, consulta Providers. Para los IDs de modelo usados en los ejemplos, consulta el Claude model overview y GPT-6 Luna.

Reemplaza cada marcador de posición con valores de tu propia configuración de OmniProxy. Nunca publiques una clave real.

Un resultado guardado o HTTP 200 por sí solo no prueba la compatibilidad completa del Agente. Verifica el origen y el modelo en el registro de llamadas de OmniProxy.

Fuentes oficiales · OpenCode ↗