Factory Droid + JoinGonka Gateway: BYOK en modelos de la red Gonka

Paso 1: instalar Droid. Métodos oficiales de la documentación de Factory:

# macOS and Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# via npm
npm install -g droid

El script coloca el binario en ~/.local/bin y te indica cómo añadir el directorio al PATH; en Linux la documentación pide instalar además el paquete xdg-utils. Para verificar: droid --version.

Paso 2: obtener la clave. Regístrate en gate.joingonka.ai/register, confirma tu dirección y crea una clave con el prefijo jg- en la sección «Claves de API». Una sola clave y un solo saldo funcionan para todos los modelos de la red.

Paso 3: ejecutar el instalador.

npx @joingonka/setup --tool droid

El instalador te pedirá la clave —no se pasa como argumento de línea de comandos para que no quede en el historial del shell— y hará cuatro cosas:

• añadirá al array customModels del archivo ~/.factory/settings.json (en Windows, %USERPROFILE%\.factory\settings.json) una entrada por cada modelo de la red: la dirección del gateway, el tipo de proveedor generic-chat-completion-api, la clave en texto plano, la ventana de contexto real y el límite de respuesta; el archivo recibirá permisos 600;
• establecerá el modelo predeterminado —sessionDefaultSettings.model— en DeepSeek V4 Flash, pero solo si no hay ninguno seleccionado o si apunta a un modelo que ya no está en la red. No sobrescribirá un modelo del catálogo de Factory ni una entrada BYOK ajena, sino que te indicará cómo cambiar;
• guardará una copia del archivo anterior y dejará intactas las entradas ajenas en customModels, el resto de la configuración y los comentarios; si un archivo no se puede parsear, no lo sobrescribirá y te dirá qué corregir;
• al final enviará una petición real al gateway y te dirá claramente si la clave, la dirección y el modelo fueron aceptados.

Otro modelo predeterminado se define con el flag --model con las abreviaturas deepseek, glm o minimax —el modelo indicado explícitamente siempre se escribe. Para dotfiles y servidores hay un modo sin preguntas, en el que la clave se toma de una variable de entorno:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool droid --model glm --non-interactive

No hace falta reiniciar Droid: detecta los cambios en settings.json por sí solo. La línea ! Could not verify right now con una respuesta 429 al final significa que el modelo está ocupado, no un error de configuración —la configuración ya está escrita.

Todo lo que hace el instalador se puede escribir a mano. La configuración de usuario de Droid se guarda en ~/.factory/settings.json; si el archivo no existe, Droid lo crea en el primer arranque. Para la red Gonka hacen falta el array customModels y un modelo por defecto:

{
  "customModels": [
    {
      "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
      "id": "custom:deepseek-ai/DeepSeek-V4-Flash-0731",
      "displayName": "DeepSeek V4 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32768,
      "maxContextLimit": 380000,
      "noImageSupport": true
    },
    {
      "model": "zai-org/GLM-5.3-Flash",
      "id": "custom:zai-org/GLM-5.3-Flash",
      "displayName": "GLM 5.3 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 390000,
      "noImageSupport": true
    },
    {
      "model": "MiniMaxAI/MiniMax-M2.7",
      "id": "custom:MiniMaxAI/MiniMax-M2.7",
      "displayName": "MiniMax M2.7 (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 200000,
      "noImageSupport": true
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:deepseek-ai/DeepSeek-V4-Flash-0731"
  }
}

El modelo por defecto se guarda en sessionDefaultSettings.model y remite a la entrada por su id. La documentación de Factory menciona además la clave model en la raíz del archivo, pero en nuestra prueba droid exec sin el flag -m tomó el modelo precisamente de sessionDefaultSettings, y también después de cambiar el valor.

La clave está en el archivo en texto plano: protege el archivo con chmod 600 ~/.factory/settings.json y no traslades entradas con clave al .factory/settings.json del proyecto, porque suele acabar en el repositorio. Y si después de arrancar Droid el archivo se ve distinto, es normal: al guardar cualquier ajuste, Droid reescribe el archivo entero: ordena las claves, añade a las entradas el campo index y no conserva los comentarios. Los permisos 600 se mantienen, y el instalador actualiza esas entradas sin problema.

Droid muestra sus propias entradas por separado del catálogo: según la documentación, en modo interactivo el comando /model las lista en la sección Custom models, y Ctrl+N permite recorrer las modelos directamente en el campo de entrada. En modo puntual, la modelo se especifica con el flag -m con un valor del campo id, y las barras diagonales se escriben tal cual: droid exec -m custom:zai-org/GLM-5.3-Flash "…".

Si te equivocas en el nombre, Droid responderá Invalid model y listará todas las modelos que ve, incluidas las suyas como custom:… (display name): de paso se ve que las entradas se cargaron. Un nombre al estilo de la documentación de Factory, formado por el display name y el número (custom:DeepSeek-V4-Flash-(Gonka)-0), no funcionará con un id explícito — en nuestra prueba dio el mismo Invalid model.

Qué requiere una cuenta de Factory. Las modelos propias eliminan el problema del pago de tokens, pero no el del inicio de sesión en el propio producto. Esto es lo que mostró la prueba de Droid 0.225.1 sin iniciar sesión:

Para trabajar en la interfaz, crea una cuenta de Factory e inicia sesión a través del navegador — la opción Login o el comando /login; en una máquina sin navegador, la documentación propone una clave de la configuración de la cuenta en la variable FACTORY_API_KEY. Usar droid exec sin iniciar sesión es cómodo para probar, pero no está descrito oficialmente — no cuentes con ello en CI. Según la página de tarifas de Factory, BYOK está incluido en todos los planes individuales con un límite gratuito, y por encima del límite el uso de BYOK se factura según las condiciones del plan; las condiciones actuales están en factory.ai/pricing. Los tokens de las modelos de la red se pagan aparte — desde el saldo de JoinGonka.

Qué modelo elegir. El precio es el mismo para todas las modelos de la red, así que la elección va sobre el comportamiento. Así funcionaron en nuestra prueba de droid exec con una misma tarea — leer un archivo y encontrar el error:

El flag -r (nivel de razonamiento) no se aplica a las modelos BYOK, según la documentación de Factory. Por qué se eligió DeepSeek V4 Flash por defecto se analiza en el análisis del modelo.

Coloca en un directorio vacío un archivo calc.py con un error evidente —por ejemplo, el área de un rectángulo donde los lados se suman en lugar de multiplicarse— y pídele a Droid que lo encuentre:

droid exec "Read the file calc.py in the current project directory and tell me in one sentence whether it has a bug."

Sin flags, droid exec funciona en modo de solo lectura: se pueden ver los archivos, pero no modificarlos. El agente invocará por sí mismo la herramienta de lectura y responderá con precisión, indicando la expresión errónea. Con el flag -o json, la respuesta llega como un solo objeto que es cómodo de procesar con un script (salida abreviada):

{"type":"result","subtype":"success","is_error":false,"duration_ms":2239,"num_turns":2,
 "result":"Yes, the file has a bug: the rectangle area is computed as the sum of the side lengths, but it should be their product (width * height). …",
 "usage":{"input_tokens":19016,"output_tokens":146,"factory_credits":0,"ttft_ms":747}}

El campo factory_credits: 0 confirma que el trabajo se realizó en tu modelo, y no consumiendo créditos de Factory. Para que el agente pueda modificar archivos, añade un nivel de autonomía: droid exec --auto low "Fix the bug in calc.py and change nothing else." — en nuestra prueba, DeepSeek V4 Flash leyó el archivo, reemplazó la suma por una multiplicación y ejecutó el script por sí misma para comprobar que se imprime 12.

La tercera verificación es del lado de la puerta de enlace: en el panel, en la sección «Uso», la solicitud aparecerá en el desglose «Por modelos», y en el bloque «Por claves» se actualizará la hora de la última solicitud.

Si algo salió mal, ten en cuenta una particularidad de Droid: en la consola droid exec solo imprime Error during droid execution: Exec failed (en JSON — "result":"Exec failed"), y la causa real queda en el log. Puedes extraerla con un solo comando:

grep agent_error_count ~/.factory/logs/droid-log-single.log | grep -o '"errorMessage":"[^,]*' | tail -1

La herramienta de agentes consume tokens de forma distinta a un chat: por cada frase tuya, Droid añade un prompt de sistema, descripciones de herramientas y una instantánea del directorio de trabajo, y la tarea requiere varios turnos. En nuestra ejecución, cada turno consumía unas 9,5 mil tokens de entrada incluso antes de tu pregunta: la tarea de «leer un archivo y encontrar el error» tomó dos turnos y unas 19 mil tokens; «corregir y verificar», cuatro turnos y unas 44 mil. Por eso, el precio por token es decisivo aquí.

A través de JoinGonka Gateway, las tokens cuestan $0.0069 por millón de entrada y $0.021 por millón de salida; el precio es igual para todos los modelos de la red y se actualiza en esta página desde una fuente en tiempo real.

Las estimaciones de la columna derecha son según precios de septiembre de 2026. Para comparar, cómo se puede pagar por los modelos en Droid:

El comando /cost en la interfaz de Droid muestra las estadísticas de la sesión, mientras que el consumo exacto y el saldo para modelos BYOK se ven en el panel de control de la pasarela, en las secciones «Uso» y «Facturación». Crea una clave separada para Droid; su tráfico aparecerá como una línea independiente.

Autonomía. En el modo puntual, Droid por defecto solo lee; los niveles amplían los permisos: --auto low — edición de archivos, --auto medium — además instalación de dependencias, compilación, pruebas y commits locales, --auto high — hasta push y despliegue. El flag --skip-permissions-unsafe elimina todas las verificaciones — solo para contenedores desechables. En el modo interactivo, el nivel se cambia con Ctrl+L, y el inicial se define con sessionDefaultSettings.autonomyLevel; por defecto es off — todo con confirmación.

Firma en los commits. La configuración includeCoAuthoredByDroid está activada por defecto: Droid añade una línea de coautoría en los mensajes de commit. Si no la necesitas, escribe "includeCoAuthoredByDroid": false en settings.json.

Dónde se almacenan las sesiones. Tras iniciar sesión en la cuenta, Droid por defecto replica las sesiones del CLI en la versión web de Factory — de esto se encarga cloudSessionSync. Las claves BYOK, según la documentación, permanecen locales; si también la conversación debe quedarse en la máquina, pon "cloudSessionSync": false. La puerta de enlace, por su parte, no almacena el contenido de los prompts ni de las respuestas — en las estadísticas solo quedan agregados de consumo.

Actualizaciones. La instalación por script se actualiza sola; se puede fijar la versión con la variable FACTORY_DROID_AUTO_UPDATE_ENABLED=false o con el comando droid update --version <version>; las compilaciones de npm no se actualizan solas. Tras la actualización, con un solo droid exec verifica que los modelos de la red estén en su lugar.

Imágenes. Los modelos de la red son de texto; para capturas de pantalla, ten a mano una entrada con un modelo que sepa ver, de otro proveedor.

Si trabajar sin cuenta de proveedor es imprescindible. Los mismos modelos de la red se conectan a agentes de terminal abiertos, que no requieren inicio de sesión — por ejemplo, a OpenCode con el mismo instalador, con el flag --tool opencode.