Configuración del proveedor compatible con OpenAI de OpenCode: Enruta modelos de agentes de codificación a través de Flatkey

Una configuración de proveedor compatible con OpenAI de OpenCode es útil cuando quieres que OpenCode se comunique con una ruta de modelo que se comporte como la API de Chat Completions de OpenAI, mientras tu equipo mantiene la propiedad de las claves, el enrutamiento de modelos y la revisión del uso en una única puerta de enlace.

La parte importante es que OpenCode tiene una ruta documentada para proveedores personalizados. En la documentación del proveedor de OpenCode, consultada el 8 de julio de 2026, el flujo es: añadir una credencial con /connect, elegir Otro para un proveedor que no esté ya en la lista, darle a ese proveedor un ID fácil de recordar, configurar el proveedor en opencode.json y luego ejecutar /models para seleccionar entre los modelos configurados.

Flatkey encaja en ese patrón como la puerta de enlace detrás del proveedor. Mantienes OpenCode como el agente de codificación, apuntas el proveedor a la URL base de la API compatible con OpenAI de Flatkey y verificas que el tráfico del modelo de OpenCode aparezca en los registros de uso o de solicitudes de Flatkey antes de convertirla en la ruta predeterminada.

Respuesta rápida para la configuración del proveedor compatible con OpenAI de OpenCode

Utiliza esta forma de configuración cuando el punto de conexión del modelo sea compatible con Chat Completions.

Esta guía del proveedor compatible con OpenAI de OpenCode utiliza plantillas. Valida los alias de modelo exactos y la familia de puntos de conexión con tu cuenta de Flatkey antes de enrutar el trabajo del agente de codificación de producción.

Lo que OpenCode requiere

OpenCode tiene dos piezas de estado separadas para un proveedor personalizado.

La configuración de OpenCode puede ser JSON o JSONC. Puedes colocarla globalmente en ~/.config/opencode/opencode.json, o en la raíz de un proyecto como opencode.json. La configuración del proyecto tiene una precedencia estándar más alta, así que utiliza un archivo de proyecto cuando quieras que un repositorio pruebe Flatkey sin cambiar cada espacio de trabajo de OpenCode.

Paso 1: Crea una clave de Flatkey para OpenCode

Crea una clave de Flatkey para esta carga de trabajo y anota tres valores fuera del control de código fuente.

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias

Mantén la raíz de la API separada de la ruta del punto de conexión. La configuración del proveedor de OpenCode debe usar https://router.flatkey.ai/v1 como options.baseURL; las pruebas de humo HTTP directas añaden /chat/completions.

Antes de conectar OpenCode, ejecuta una prueba directa con la misma clave de Flatkey y el mismo alias de modelo.

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      { "role": "user", "content": "Responde exactamente con: flatkey route ok" }
    ]
  }'

Si esta solicitud directa falla, corrige la clave de Flatkey, el alias del modelo, la familia de puntos de conexión o la ruta de la cuenta antes de depurar OpenCode. Un proveedor compatible con OpenAI de OpenCode no puede compensar un alias de modelo al que la cuenta de la puerta de enlace no puede llamar.

Paso 2: Añade la credencial de Flatkey en OpenCode

OpenCode almacena las credenciales del proveedor a través de /connect. En la TUI de OpenCode:

/connect

Elige Otro, introduce un ID de proveedor como flatkey y luego pega la clave de API de Flatkey. No pegues la URL base en la solicitud de credenciales. La clave demuestra la identidad; la URL base pertenece a opencode.json.

Usa un ID de proveedor sencillo. flatkey es mejor que flatkey-prod-openai-compatible-gateway-v2 porque lo escribirás en los ID de modelo y en las notas de reversión.

Paso 3: Añade la configuración del proveedor de OpenCode

Crea o actualiza opencode.json en la raíz del proyecto que quieres probar.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "your-current-flatkey-model-alias": {
          "name": "Flatkey primary model"
        }
      }
    }
  },
  "model": "flatkey/your-current-flatkey-model-alias"
}

Esta es la configuración más pequeña de un proveedor compatible con OpenAI de OpenCode. Le da a OpenCode un proveedor llamado flatkey, le indica a OpenCode que use el paquete AI SDK compatible con OpenAI y expone un alias de modelo en el selector de modelos.

Si quieres que OpenCode use una ruta más pequeña para trabajos ligeros, añade small_model solo después de que la ruta principal funcione.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "primary-flatkey-model-alias": {
          "name": "Flatkey primary"
        },
        "lighter-flatkey-model-alias": {
          "name": "Flatkey lightweight"
        }
      }
    }
  },
  "model": "flatkey/primary-flatkey-model-alias",
  "small_model": "flatkey/lighter-flatkey-model-alias"
}

Usa los alias de modelo que tu clave de Flatkey realmente puede llamar. Si tu cuenta expone una ruta autenticada /v1/models, compara los ID de modelo configurados con esa respuesta. De lo contrario, copia los alias del panel de control actual de Flatkey o del directorio de modelos y verifícalos con una solicitud real.

Paso 4: Selecciona y prueba el modelo en OpenCode

Después de guardar la configuración, abre el selector de modelos.

/models

Selecciona el modelo del proveedor Flatkey. Luego, ejecuta un pequeño prompt en OpenCode:

Reply with exactly: opencode flatkey route ok

No muevas todo un flujo de trabajo de codificación todavía. Primero, guarda un paquete de verificación compacto.

Esto convierte una migración de un proveedor compatible con OpenAI de OpenCode en un pequeño cambio operativo en lugar de un intercambio de proveedor a ciegas.

Paso 5: Mantén las Completions de Chat y las Responses separadas

La documentación de proveedores personalizados de OpenCode señala un límite de paquete: usa @ai-sdk/openai-compatible para proveedores compatibles con OpenAI que usan /v1/chat/completions; si un proveedor o modelo usa /v1/responses, usa @ai-sdk/openai.

Eso significa que la primera ruta de Flatkey debería ser un modelo de estilo Chat Completions, a menos que tengas evidencia actual de que tu modelo seleccionado y la ruta del cliente usan una familia de puntos de conexión diferente.

Usa esta tabla de decisiones antes de añadir más modelos.

Para la mayoría de los trabajos de configuración, comienza con una ruta de Chat Completions. Añade streaming, llamadas a herramientas y alias de modelos secundarios después de que la primera prueba de humo del proveedor compatible con OpenAI de OpenCode sea visible en Flatkey.

Paso 6: Añade controles de equipo después de que la ruta funcione

Una vez que OpenCode pueda llamar a Flatkey, haz que la ruta sea observable.

Aquí es donde Flatkey se convierte en algo más que una URL base. Un proveedor compatible con OpenAI de OpenCode que funcione también debería dar a los equipos de plataforma, finanzas y operaciones un lugar para revisar el uso de los modelos y cambiar la ruta sin pedir a cada desarrollador que gestione cuentas de proveedor separadas.

Para una planificación de migración más amplia, combina esta guía con la guía de migración de API compatibles con OpenAI de Flatkey. Si estás comparando herramientas de codificación adyacentes, consulta la guía del proveedor compatible con OpenAI de Continue.dev y la guía de configuración compatible con OpenAI de Roo Code.

Solución de problemas de un proveedor compatible con OpenAI de OpenCode

Si la primera solicitud falla, no cambies todavía los prompts, los agentes, los permisos ni el código del repositorio. Mantén la superficie de depuración del proveedor compatible con OpenAI de OpenCode pequeña: credencial, ID del proveedor, URL base, paquete, alias del modelo y una solicitud de chat simple.

Lista de verificación final

Antes de usar Flatkey como la ruta predeterminada de OpenCode, confirma:

1. /connect tiene una credencial de Flatkey bajo el mismo ID de proveedor utilizado en opencode.json.
2. provider.flatkey.npm es @ai-sdk/openai-compatible para la ruta de Chat Completions.
3. provider.flatkey.options.baseURL es https://router.flatkey.ai/v1.
4. model apunta a un valor configurado de flatkey/<alias-del-modelo>.
5. /models muestra el modelo de Flatkey configurado.
6. Un prompt de una línea de OpenCode se devuelve con éxito.
7. Los registros de uso o de solicitudes de Flatkey muestran la solicitud de prueba de OpenCode.
8. La ruta anterior del proveedor/modelo está documentada para su reversión.

La configuración de un proveedor compatible con OpenAI de OpenCode está completa cuando el proveedor está configurado, es seleccionable, está verificado en los registros de Flatkey y es reversible. Cuando estés listo para enrutar el tráfico del modelo de agente de codificación a través de una sola clave, obtén una clave de Flatkey y comienza con un único prompt de OpenCode de bajo riesgo.