Modelos personalizados en Factory Droid: Claude y GPT con tu propia API key

En Droid 1.0.0, los modelos personalizados se escriben en customModels, dentro de ~/.factory/settings.json. Cada entrada lleva model, baseUrl, apiKey y provider. Claude usa anthropic con el host pelado, GPT usa openai y el resto usa generic-chat-completion-api. Los tres modelos arreglaron el mismo bug en 33.7, 77.4 y 30.7 segundos.

Las tres ejecuciones pasaron por OmniaKey con una sola key. Así probamos Claude Sonnet 5.5, GPT-6.1 Terra y MiniMax M3.1 Flash, cada uno con la misma función median() rota.

Respuesta corta

• Dónde va. En customModels, dentro de ~/.factory/settings.json, con model, baseUrl, apiKey y provider (documentación de ajustes de Factory, revisada el 30 de octubre de 2026).
• Qué provider. anthropic para Claude, openai para los modelos GPT y generic-chat-completion-api para el resto que hable Chat Completions.
• Dónde va /v1. anthropic lleva el host pelado, porque Droid añade /v1/messages; openai y generic-chat-completion-api llevan una URL que termina en /v1.
• El id para droid exec. custom:, el nombre visible con los espacios convertidos en guiones y la posición contada desde 0: custom:Claude-Sonnet-5.5-[OmniaKey]-0.
• Qué salió en nuestras pruebas. Los tres arreglaron el bug: 30.7 s con Flash, 33.7 s con Claude y 77.4 s con GPT-6.1 Terra.

¿Qué valor de provider tienes que usar?

Elige por la API que habla tu endpoint, no por el nombre del modelo.

• anthropic envía peticiones a la API Messages de Anthropic. Úsalo con Claude; la URL de Anthropic es https://api.anthropic.com.
• openai envía peticiones a la API Responses de OpenAI. Úsalo con modelos GPT; la URL de OpenAI es https://api.openai.com/v1.
• generic-chat-completion-api envía peticiones Chat Completions de OpenAI. Úsalo con la mayoría de los demás modelos, pasarelas y servidores locales, con la URL /v1 del proveedor.

Factory incluye generic-chat-completion-api para OpenRouter, Fireworks, Together AI, Ollama, vLLM y la mayoría de los proveedores de código abierto, y lo recomienda salvo que llames a la API oficial de OpenAI o de Anthropic (documentación BYOK de Factory, revisada el 30 de octubre de 2026).

Una pasarela que también hable la API Messages o la API Responses puede usar anthropic u openai. Nuestras entradas de Claude y GPT-6.1 Terra lo hicieron a través de OmniaKey y ambas funcionaron. OmniaKey sirve los modelos GPT en POST /v1/responses (documentación de compatibilidad con OpenAI de OmniaKey, revisada el 30 de octubre de 2026).

Hay un cuarto valor, bedrock-converse, para modelos de la API Converse de AWS Bedrock. Factory advierte de que solo los modelos de Anthropic y OpenAI en sus API oficiales están probados y medidos por completo, y de que los modelos con menos de 30 mil millones de parámetros rinden bastante peor en programación con agentes (documentación BYOK de Factory, revisada el 30 de octubre de 2026).

El settings.json que usamos

Droid crea ~/.factory/settings.json en el primer arranque, así que añade customModels al archivo que ya existe (documentación de ajustes de Factory, revisada el 30 de octubre de 2026). El nuestro es este:

{
  "customModels": [
    {
      "model": "claude-sonnet-5-5",
      "displayName": "Claude Sonnet 5.5 [OmniaKey]",
      "baseUrl": "https://api.omniakey.com",
      "apiKey": "${OMNIAKEY_API_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 16000
    },
    {
      "model": "gpt-6.1-terra",
      "displayName": "GPT-6.1 Terra [OmniaKey]",
      "baseUrl": "https://api.omniakey.com/v1",
      "apiKey": "${OMNIAKEY_API_KEY}",
      "provider": "openai",
      "maxOutputTokens": 16000
    },
    {
      "model": "minimax-m3.1-flash",
      "displayName": "MiniMax M3.1 Flash [OmniaKey]",
      "baseUrl": "https://api.omniakey.com/v1",
      "apiKey": "${OMNIAKEY_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 16000
    }
  ]
}

• model es el id que se envía a la API; cópialo de la lista de modelos del proveedor. displayName es tu propia etiqueta: aparece en /model y construye el id custom:.
• baseUrl es el host pelado para anthropic y termina en /v1 para los otros dos.
• apiKey: "${OMNIAKEY_API_KEY}" lee la key de una variable de entorno, así que no queda en el archivo (documentación BYOK de Factory, revisada el 30 de octubre de 2026).
• provider elige la API; una errata aquí produce el error "Invalid provider" de más abajo.
• maxOutputTokens: 16000 limita la longitud de cada respuesta.

Con una key y dos URL base cubres los tres modelos: el host pelado de OmniaKey para Claude y el host /v1 para los otros dos. Si seguiste la guía de configuración para agentes de programación de OmniaKey, la misma key te sirve aquí.

Factory dice que las keys se quedan en local y no se suben a sus servidores (documentación BYOK de Factory, revisada el 30 de octubre de 2026). Las guías antiguas ponían los modelos en ~/.factory/config.json. La documentación BYOK de Factory sigue diciendo que Droid los copia a settings.json al arrancar. Un pull request del repositorio de Factory (#76) indica que un cambio fusionado el 15 de octubre de 2026 eliminó esa copia, así que pon los modelos nuevos directamente en settings.json.

¿Cómo eliges un modelo personalizado en Droid?

En la app, abre /model y mira la sección Custom Models. En la línea de comandos, pasa un id custom: a droid exec.

La documentación de Factory dice que los modelos guardados aparecen ahí con su displayName, y que también puedes añadir uno desde /settings > Custom models o /model > Manage custom models (revisada el 30 de octubre de 2026).

El id de droid exec es custom:, luego el nombre visible con los espacios convertidos en guiones y, por último, un guion y la posición del modelo en customModels contada desde 0 (documentación de droid exec de Factory, revisada el 30 de octubre de 2026). Los nuestros quedaron como custom:Claude-Sonnet-5.5-[OmniaKey]-0, custom:GPT-6.1-Terra-[OmniaKey]-1 y custom:MiniMax-M3.1-Flash-[OmniaKey]-2.

El índice sigue el orden del array, así que insertar un modelo por encima desplaza todos los id de abajo; vuelve a copiar el id después de editar el archivo.

-r / --reasoning-effort en droid exec no se aplica a los modelos personalizados (documentación de droid exec de Factory, revisada el 30 de octubre de 2026). Configura reasoningEffort en la entrada.

Tres modelos con el mismo bug

Los mismos dos archivos, el mismo comando, una ejecución por modelo. stats.py:

def median(values):
    """Return the median of a non-empty list of numbers."""
    ordered = sorted(values)
    mid = len(ordered) // 2
    return ordered[mid]

test_stats.py:

from stats import median

assert median([3, 1, 2]) == 2
assert median([4, 1, 3, 2]) == 2.5
assert median([5]) == 5
assert median([1.5, 2.5]) == 2.0
print("all tests passed")

El comando, con solo el valor de --model cambiando entre ejecuciones:

droid exec --auto medium -o json --model "custom:Claude-Sonnet-5.5-[OmniaKey]-0" "python3 test_stats.py fails. Fix the bug in stats.py without changing the tests, run python3 test_stats.py again, and tell me in one sentence what you changed."

Son los números que dio Droid (duration_ms, num_turns, output_tokens). Flash terminó primero con 30.7 s, Claude usó menos turnos y GPT-6.1 Terra tardó más, 77.4 s. Droid informó del primer token a los 8.7 s con Claude, 17.8 s con Terra y 7.0 s con Flash. Los tres arreglaron el bug sin tocar test_stats.py, y las pruebas imprimieron all tests passed.

El cambio de Claude:

-    return ordered[mid]
+    if len(ordered) % 2:
+        return ordered[mid]
+    return (ordered[mid - 1] + ordered[mid]) / 2

GPT-6.1 Terra añadió la misma rama encima de la línea return original, y MiniMax M3.1 Flash la escribió con % 2 == 1. Las tres respuestas describían ese arreglo: promediar los dos valores centrales cuando la lista tiene longitud par. La reseña de MiniMax M3.1 Flash trata ese modelo con más detalle.

El resultado JSON de Droid también imprimió factory_credits en cada ejecución, aunque nunca iniciamos sesión: 31,534 con Claude Sonnet 5.5, 4,830 con GPT-6.1 Terra y 835 con MiniMax M3.1 Flash. La documentación de Factory no explica qué mide ese número ni cómo se relaciona con el margen de BYOK (revisada el 30 de octubre de 2026).

¿Hace falta una cuenta o un plan de Factory?

En nuestras ejecuciones, droid exec con un modelo custom: no necesitó cuenta de Factory. Los modelos propios de Factory y la app interactiva sí la pedían.

Droid CLI 1.0.0 salió el 29 de octubre de 2026 (registro de cambios de Factory, revisado el 30 de octubre de 2026). En una carpeta home limpia, sin sesión iniciada en Factory, cada llamada a droid exec con un modelo custom: corrió con nuestra propia key. El mismo comando sin --model se detuvo al instante con "Authentication failed. Please log in using /login or set a valid FACTORY_API_KEY environment variable." (error de autenticación: inicia sesión con /login o define una variable de entorno FACTORY_API_KEY válida). La entrada v0.236.0 del registro de cambios de Factory (8 de octubre de 2026) habla de sesiones retomadas: "Droid exec now resumes a session on your own model credentials without a Factory sign-in." (Droid exec ahora retoma una sesión con las credenciales de tu propio modelo, sin iniciar sesión en Factory).

Al arrancar droid sin argumentos en la misma carpeta, se detuvo en "Please login with your Factory account to continue." (inicia sesión con tu cuenta de Factory para continuar). Sin sesión no pudimos probar modelos personalizados en la app interactiva ni en la de escritorio, y no probamos la entrada de imágenes, Bedrock, apiKeyHelper, reasoningEffort ni los ajustes de thinking, Windows, sesiones más largas que una tarea ni el archivo antiguo config.json.

Los planes Individual de Factory cuestan $20 (Pro), $100 (Plus) y $200 (Max) al mes; la página de precios añade Teams a $60 al mes por equipo más $40 por asiento, y ningún plan Individual gratuito (documentación de precios y página de precios de Factory, revisadas el 30 de octubre de 2026).

La documentación de precios de Individual dice: "BYOK is free up to an allowance on all Individual plans. After that, usage is charged according to your specific plan." (BYOK es gratis hasta un límite en todos los planes Individual; a partir de ahí, el uso se cobra según tu plan concreto). Factory no dice de cuánto es ese límite ni cómo es el cobro después.

Los modelos personalizados personales funcionan en la CLI y en la app de escritorio, y no aparecen en las apps web y móvil alojadas por Factory (documentación BYOK de Factory, revisada el 30 de octubre de 2026).

¿Qué errores vas a encontrar y qué los arregla?

Cada uno vino de un valor mal puesto en una configuración que por lo demás funcionaba, con Droid 1.0.0.

1. anthropic con /v1 en la URL base. Droid imprimió "Requested model was not found on the API provider" (no se encontró el modelo solicitado en el proveedor de API) a los 0.9 s, y su log mostró 404 en Invalid URL (POST /v1/v1/messages). Droid añade /v1/messages por su cuenta, así que nuestro /v1 lo duplicaba. Arreglo: el host pelado, https://api.anthropic.com o https://api.omniakey.com.

2. openai con el host pelado. Droid imprimió 404 y una página "404 Not Found" de nginx a los 1.4 s; la API Responses vive bajo /v1. Arreglo: https://api.openai.com/v1 o https://api.omniakey.com/v1.

3. Un id de modelo con puntos, claude-sonnet-5.5, en lugar de claude-sonnet-5-5. El endpoint respondió 503 con el código model_not_found y el mensaje "No available channel for model claude-sonnet-5.5" (no hay canal disponible para ese modelo). El log de Droid etiquetó cada fallo como "overloaded" e hizo 10 intentos durante 259.7 segundos (unos 4 minutos 20 segundos) antes de salir con ese mensaje. El texto es de la pasarela; los reintentos son de Droid. Arreglo: copia el id exacto de la lista de modelos de tu proveedor.

4. OMNIAKEY_API_KEY vacía en la shell desde la que arrancaste Droid. Droid recibió 401 con "Invalid token" (token no válido) a los 2.8 s. Arreglo: exporta la key en la shell desde la que lanzas droid y empieza una sesión nueva.

La lista de solución de problemas de Factory añade dos. "Invalid provider" significa que el valor está mal escrito o con otras mayúsculas, y tiene que ser exactamente anthropic, openai, generic-chat-completion-api o bedrock-converse. Si un modelo falta en el selector, la documentación dice que revises la sintaxis JSON de ~/.factory/settings.json y que cada entrada tenga sus campos obligatorios (revisada el 30 de octubre de 2026).

Preguntas frecuentes

¿Dónde está el archivo de ajustes de Droid en Windows?

%USERPROFILE%\.factory\settings.json, el mismo archivo que ~/.factory/settings.json en macOS y Linux (documentación de ajustes de Factory, revisada el 30 de octubre de 2026). Pon ahí customModels.

¿Por qué no aparece mi modelo personalizado en /model?

Revisa primero la sintaxis JSON de ~/.factory/settings.json y después los campos model, baseUrl y provider. Droid detecta los cambios guardados mediante vigilancia de archivos (documentación BYOK de Factory, revisada el 30 de octubre de 2026). Según un informe con Desktop 0.184.0 y CLI 0.227.0, los modelos personalizados aparecían un momento en el selector de escritorio y luego desaparecían, mientras droid exec --help seguía listando los 14; ese issue ya está cerrado (Factory-AI issue #40, revisado el 30 de octubre de 2026).

¿Pueden leer imágenes los modelos personalizados?

Las imágenes vienen activadas por defecto en anthropic y openai, y desactivadas en generic-chat-completion-api, donde noImageSupport vale true por defecto (documentación BYOK de Factory, revisada el 30 de octubre de 2026). Pon noImageSupport: false en una entrada generic para permitirlas. Según un informe, las imágenes se eliminaban igualmente en CLI v0.205.1 con ese valor puesto (Factory-AI issue #24, revisado el 30 de octubre de 2026).

¿Puedo configurar el esfuerzo de razonamiento de un modelo personalizado?

-r / --reasoning-effort en droid exec no se aplica a los modelos personalizados. Configura reasoningEffort en la entrada: fija el esfuerzo por defecto de un modelo que Droid no reconoce y añade off, low, medium y high al selector (documentación BYOK de Factory, revisada el 30 de octubre de 2026).

¿Funcionan los modelos personalizados en la app de escritorio de Droid?

Sí: los modelos personalizados personales están disponibles en la CLI y en la app de escritorio, y se quedan fuera de las apps web y móvil alojadas. Los editores de modelos de la CLI y de la app de escritorio guardan en ~/.factory/settings.json (documentación BYOK de Factory, revisada el 30 de octubre de 2026).

Fuentes revisadas

• Documentación BYOK de Factory, revisada el 30 de octubre de 2026
• Documentación de ajustes de Factory, revisada el 30 de octubre de 2026
• Documentación de droid exec de Factory, revisada el 30 de octubre de 2026
• Notas de la versión de Factory, revisada el 30 de octubre de 2026
• Planes Individual de Factory, revisada el 30 de octubre de 2026
• Precios de Factory, revisada el 30 de octubre de 2026
• Factory-AI issue #40: los modelos personalizados desaparecen del selector de escritorio, revisado el 30 de octubre de 2026
• Factory-AI issue #24: imágenes eliminadas, revisado el 30 de octubre de 2026
• Factory-AI pull request #76: migración de config.json, revisado el 30 de octubre de 2026

Documentación propia de OmniaKey, revisada el 30 de octubre de 2026: descripción general de la API y API compatible con OpenAI.