Instalación de OpenCode y configuración de OmniProxy

OpenCode es un asistente de programación de código abierto que permite escribir código desde el terminal, un IDE o el escritorio. No guarda tu código ni el contexto, por lo que resulta adecuado para proyectos donde la privacidad es importante. build sirve para modificar el proyecto, mientras que plan es de solo lectura de forma predeterminada y resulta útil para comprender primero código que no conoces y organizar los cambios. Puedes elegir el servicio de modelos según tus necesidades.

Preparativos antes de la instalación

El script de instalación es la opción más sencilla. Necesitas un terminal moderno, es decir, un programa de terminal que permita ejecutar comandos y trabajar con los archivos del proyecto, como WezTerm, Alacritty, Ghostty o Kitty. En Windows se recomienda utilizar WSL, una herramienta que permite ejecutar un entorno Linux dentro de Windows y ofrece funciones y rendimiento más completos.

La opción más sencilla

Script de instalación

curl opencode.ai/install
Úsalo directamente en macOS Linux
En Windows se recomienda WSL

macOS Linux

Homebrew tap

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

Windows nativo

Gestor de paquetes

choco o scoop
O instálalo globalmente con npm
También puedes descargarlo desde Releases

Empieza con el script de instalación. Si ya estás acostumbrado a utilizar un gestor de paquetes, puedes recurrir a los demás comandos indicados.

Prepara también el ID del modelo que aparezca en la lista actual de modelos. El ID del modelo es el nombre que utiliza el servicio para identificar con precisión un modelo concreto.

Instalación y primer inicio

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

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

También puedes utilizar los siguientes métodos de instalación:

Node.js: npm install -g opencode-ai. Bun, pnpm y Yarn también disponen de sus respectivos comandos de instalación global; consulta la página introductoria enlazada al final.
Homebrew en macOS y Linux: brew install anomalyco/tap/opencode. Utiliza este tap, ya que se actualiza con más frecuencia que brew install opencode, mantenido por el equipo de Homebrew.
Arch Linux: utiliza sudo pacman -S opencode para la versión estable. Para una versión más reciente, puedes utilizar opencode-bin desde AUR.
Windows: utiliza choco install opencode o scoop install opencode; también puedes ejecutar npm install -g opencode-ai. Además, puedes descargar el archivo binario desde Releases. La compatibilidad con la instalación mediante Bun en Windows sigue en desarrollo.

Entra en el directorio de tu proyecto e inicia OpenCode:

cd /path/to/project
opencode

La primera vez puedes ejecutar /init. Este comando analizará el proyecto y creará AGENTS.md en su directorio raíz. Puedes incluir este archivo en Git para conservar estas instrucciones dentro del proyecto.

Obtener los parámetros de conexión de OmniProxy

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: copiar el ID completo de la lista actual de modelos de OmniProxy

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

Cuando se utilice /v1/chat/completions, el paquete npm debe ser @ai-sdk/openai-compatible. Chat Completions es una interfaz para solicitudes de conversación. Solo debes cambiar a @ai-sdk/openai cuando el modelo utilice /v1/responses. Si OmniProxy se utiliza mediante la ruta de Chat Completions, conserva el paquete compatible.

Copia íntegramente el ID del modelo desde la lista actual de OmniProxy, incluidas las barras. Los dos ID de referencia del 2026-10-09 son claude-sonnet-5-5 y gpt-6-luna. gpt-6-luna admite Chat Completions; dentro de Chat Completions, las llamadas a funciones solo se admiten cuando reasoning_effort tiene el valor none. No copies un ID que no figure en la lista.

Introducir la configuración de la herramienta

Un Provider puede entenderse como el conjunto de opciones de configuración que OpenCode utiliza para conectarse a un servicio de modelos. La documentación de Provider considera que un servicio compatible con OpenAI que no aparezca en la lista de /connect es un Provider personalizado. Un servicio compatible con OpenAI utiliza el mismo formato de solicitud y puede invocarse mediante el mismo tipo de cliente.

Ejecuta /connect en OpenCode y desplázate hasta Other.
Introduce un Provider ID. En este ejemplo se utiliza omniproxy. Elige un ID fácil de recordar, ya que tendrás que utilizar exactamente el mismo en el archivo de configuración.
Introduce la API Key de OmniProxy. Este paso solo guarda la credencial; todavía tendrás que añadir la dirección y los modelos a opencode.json. La credencial se guarda 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 Provider personalizado y sus modelos aparecerán en la lista.

El ID utilizado en /connect debe coincidir con la clave de opencode.json. No escribas la clave real en este archivo. Si no utilizas /connect, también puedes hacer referencia a una variable de entorno en options.apiKey, por ejemplo, {env:NOMBRE_DE_LA_VARIABLE}. En una prueba realizada el 2026-10-09 con OpenCode 1.18.34, también fue posible establecer la conexión escribiendo directamente la clave en options.apiKey dentro del proyecto, sin utilizar /connect. Si la puerta de enlace no valida la clave, este campo puede contener una cadena de marcadores de posición utilizada únicamente de forma local. Las claves de models deben ser los ID completos que aparecen en la lista.

Clave

/connect

Selecciona Other al final
Define tu propio ID de proveedor
Se guarda en auth.json

Proyecto

opencode.json

La clave provider debe tener el mismo nombre
Usa un paquete compatible con npm
baseURL debe terminar en /v1

Selección

/models

El modelo aparece en la lista
Selecciona uno antes de preguntar
Usa el ID de la lista de la puerta de enlace

La clave y la dirección se guardan en dos lugares distintos. El Provider ID debe ser el mismo en ambos.

Verificar una tarea real

Ejecuta primero una tarea real desde el directorio del proyecto. El formato de referencia del modelo es Provider ID/ID del modelo; conserva las barras que formen parte del ID del modelo:

opencode run --model omniproxy/claude-sonnet-5-5 --auto "Explica qué hace un archivo que yo especifique sin modificarlo."

--auto permite que esta ejecución utilice herramientas como la lectura de archivos. En una prueba realizada el 2026-10-09 con OpenCode 1.18.34, se pudo leer el contenido del archivo indicado. La primera ejecución tardó aproximadamente dos minutos.

Para utilizar el modo interactivo, ejecuta opencode y selecciona el modelo mediante /models. También puedes utilizar @ para buscar archivos. Ejecuta opencode auth list para confirmar las credenciales guardadas mediante /connect y, después, revisa el registro de llamadas de OmniProxy para verificar el origen y el ID del modelo.

Inicio

opencode puede iniciarse

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

Tarea

Ha leído el código

Pregunta por un archivo concreto
Revisa su explicación
Si algo no está bien, usa /undo

Registro

Es visible en la puerta de enlace

El origen es OpenCode
El ID del modelo coincide
No confirmes la clave en el repositorio

Después de guardar el archivo de configuración, todavía debes realizar una consulta real dentro del proyecto.

Errores habituales

OmniProxy no aparece en /models: comprueba que el ID de /connect coincida con la clave de opencode.json, que npm tenga el valor @ai-sdk/openai-compatible y que baseURL termine en /v1.
La credencial ha desaparecido: ejecuta opencode auth list. Los Provider como Bedrock que dependen de variables de entorno no aparecen aquí; un Provider personalizado configurado mediante /connect sí debería aparecer.
Algunas funciones no están disponibles en Windows: utiliza el script de instalación dentro de WSL.
El ID del modelo no es válido: vuelve a copiarlo desde la lista actual de OmniProxy y actualiza la clave correspondiente en models.
La solicitud utiliza la interfaz incorrecta: conserva @ai-sdk/openai-compatible para Chat Completions. No cambies el paquete para utilizar la interfaz Responses, salvo que ese modelo de OmniProxy realmente funcione mediante /v1/responses.

Referencias oficiales

Para la instalación, consulta Introducción a OpenCode. Para configurar un Provider personalizado, consulta Providers. Los ID de modelo utilizados como ejemplo aparecen en Resumen de modelos de Claude 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 demuestra compatibilidad total con el Agente. Verifica el origen y el modelo en el registro de llamadas de OmniProxy.

Fuentes oficiales · OpenCode ↗