Motores

Un motor es un adaptador LLM directo dentro de APX. Cuando ejecutás apx exec o apx chat, APX resuelve el modelo de destino, selecciona el adaptador correspondiente y llama a la API del proveedor — no se lanza ningún proceso externo.

Esto es distinto de apx run, que delega a un CLI de codificación externo. Mirá Runtimes para ese camino.

Motores soportados

Proveedor	ID del adaptador	Notas
Anthropic	anthropic	Modelos Claude; clave desde ANTHROPIC_API_KEY o config
OpenAI	openai	Modelos GPT y serie o; clave desde OPENAI_API_KEY o config
Gemini	gemini	Modelos Google Gemini; clave desde GEMINI_API_KEY o config
Ollama	ollama	Modelos locales; no necesita API key, solo base_url
Groq	groq	Compatible con OpenAI; modelo por defecto llama-3.3-70b-versatile
OpenRouter	openrouter	Compatible con OpenAI; enruta a muchos proveedores; modelo por defecto meta-llama/llama-3.3-70b-instruct
Mock	mock	Devuelve una respuesta prefabricada; útil para testing y CI

Configuración de motores

Los motores se configuran en ~/.apx/config.json bajo la clave engines:

{
  "engines": {
    "anthropic": { "api_key": "sk-ant-..." },
    "openai":    { "api_key": "sk-...", "base_url": "https://api.openai.com/v1" },
    "gemini":    { "api_key": "..." },
    "groq":      { "api_key": "...", "base_url": "https://api.groq.com/openai/v1" },
    "openrouter":{ "api_key": "...", "base_url": "https://openrouter.ai/api/v1" },
    "ollama":    { "base_url": "http://localhost:11434" }
  }
}

Las API keys también se pueden definir mediante variables de entorno — ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY — sin editar el archivo de configuración.

Gramática del ID de modelo

Al especificar un modelo en --model o en una definición de agente, APX acepta dos formas:

• Explícita: <provider>:<model> — p. ej. ollama:llama3.2, anthropic:claude-sonnet-4-5, openrouter:meta-llama/llama-3.3-70b-instruct
• Inferida: nombre del modelo a secas — APX resuelve el proveedor automáticamente:
  • claude-* → anthropic
  • gpt-*, o1-*, o3-*, o4-* → openai
  • gemini-* → gemini
  • mock → mock

Si APX no puede inferir el proveedor, usá la forma explícita provider:model.

Ejecutar un exec one-shot

apx exec "<prompt>" [--model <id>] [--max-tokens N] [--temperature T] [--project <name|id|path>]
apx exec -a <agent> "<prompt>" [--model <id>]

Sin -a, la llamada va al super-agente de APX (el predeterminado del daemon). Con -a, usa el system prompt y la memoria del agente APC especificado.

Ejemplos:

# Super-agente, modelo por defecto
apx exec "Summarize the open tasks in this project"

# Agente específico con override de modelo
apx exec -a reviewer "What are the riskiest changes in this PR?" --model anthropic:claude-opus-4-5

# Modelo local de Ollama
apx exec "Explain this stack trace" --model ollama:llama3.2

# Forzar un tamaño de salida específico
apx exec "Write a haiku about daemons" --max-tokens 100

Chat interactivo

apx chat <agent> [--model <id>] [--conversation <id>] [--project <name|id|path>]

apx chat abre un REPL interactivo que mantiene viva una hebra de conversación a lo largo de los turnos. Cada sesión se almacena en ~/.apx/projects/<apx-id>/agents/<slug>/conversations/. Pasá --conversation <id> para retomar una hebra anterior.

apx chat reviewer
apx chat reviewer --conversation abc123

El enrutador de fallback de modelos

Para el super-agente de APX (el asistente propio del daemon), APX mantiene un enrutador de fallback de modelos. En lugar de fallar cuando un proveedor no está disponible, prueba los proveedores en un orden configurable.

El enrutador se configura bajo super_agent.model_fallback en ~/.apx/config.json:

{
  "super_agent": {
    "model": "ollama:llama3.2:3b",
    "model_fallback": {
      "enabled": true,
      "models": [
        "openrouter:meta-llama/llama-3.3-70b-instruct",
        "groq:llama-3.3-70b-versatile"
      ],
      "health_timeout_ms": 800
    }
  }
}

El enrutador prueba super_agent.model primero. Si falla el health check (Ollama verifica estrictamente que el modelo esté descargado; los proveedores en la nube comprueban la accesibilidad dentro de health_timeout_ms), recorre model_fallback.models en orden y usa el primero que esté sano.

super_agent.model es también el modelo de todo agente de proyecto con Model: inherit (o sin modelo). Para darle al super-agente otro modelo sin mover a toda la flota, definí super_agent.self_model (Configuración → Super-agente → Modelo propio). Es una preferencia, no un modelo fijo: pasa por el health check y cae por la misma cadena, empezando por el #1 del router. Apagalo con super_agent.self_model_fallback: false (el checkbox de abajo) para que falle en su lugar; un agente de proyecto con su propio Model: tiene el mismo interruptor (model_fallback: false, apx agent set --no-model-fallback).

Una cuenta con el límite de uso agotado se saltea durante una hora en vez de reintentarse en cada turno, y los turnos que nadie mira (a2a, rutinas) frenan en vez de caer por la cadena, salvo que hayan arrancado en un modelo que elegiste vos con el fallback prendido — ver la página del super-agente. Para el plan de ChatGPT, el esfuerzo de razonamiento es un ajuste del modelo, no otro modelo: el panel muestra un control Esfuerzo al lado de cada selector de modelo y muestra el par como gpt-5.6-luna · high. Se guarda como sufijo del id — chatgpt-codex:gpt-5.6-luna@medium (minimal|low|medium|high|xhigh), que es también como lo toma el CLI — o como default en engines.chatgpt-codex.reasoning_effort.

Lo que cuestan las llamadas

Cada llamada a un motor queda registrada en ~/.apx/usage/<día>.jsonl (días UTC) con su modelo, superficie, agente, duración y tokens. apx usage resume un día por modelo, canal y agente:

apx usage                       # hoy
apx usage --date 2026-09-23 --since 11
apx usage breaker               # el freno de gasto: la última hora de llamadas en segundo plano, y si hay pausa
apx usage resume                # levantar la pausa ya

El freno de gasto

El trabajo en segundo plano — rutinas, agentes hablando entre sí e hilos de tareas que los agentes se pasan — tiene un techo de llamadas al modelo por hora, contado sobre la última hora, global y por proyecto. Si lo pasa, ese trabajo se pausa (30 minutos por defecto) y te llega una sola línea por Telegram. Tus propios chats nunca se pausan, ni un agente al que estás esperando desde uno de ellos. Los límites están en super_agent.spend_breaker:

{ "super_agent": { "spend_breaker": {
  "enabled": true, "calls_per_hour": 400, "project_calls_per_hour": 250, "pause_min": 30
} } }

Gestionar el enrutador con apx model

Los subcomandos de apx model te permiten inspeccionar y configurar el enrutador de fallback sin editar el JSON a mano:

apx model status          # imprime salud del proveedor, orden de fallback y modelo activo
apx model order ollama openrouter groq   # define el orden de intentos
apx model key groq sk-xxxx              # guarda una API key de proveedor
apx model key openrouter sk-or-xxxx
apx model set openrouter openrouter/anthropic/claude-3.7-sonnet  # fija un modelo específico para un proveedor
apx model test                          # resuelve qué modelo elegiría el enrutador ahora mismo
apx model enable                        # habilita el enrutador de fallback
apx model disable                       # deshabilita (solo modelo primario)

apx

$ apx model status
Model router
primary:   anthropic:claude-sonnet-4-5
fallback:  on
order:     ollama → openrouter → groq
active:    anthropic:claude-sonnet-4-5

✓ ollama       llama3.2:3b                      up    key:config
✓ openrouter   meta-llama/llama-3.3-70b         up    key:config
✗ groq         llama-3.3-70b-versatile          down  (no key)
✓ anthropic    claude-sonnet-4-5                up    key:config

Keys → ~/.apx/config.json engines.{groq,openrouter}.api_key
Or env: GROQ_API_KEY, OPENROUTER_API_KEY

apx model status — muestra la salud del proveedor, el orden de fallback y el modelo actualmente activo

Consejo

apx model status es la forma más rápida de diagnosticar por qué el super-agente está usando un modelo inesperado. Muestra el resultado del sondeo de salud de cada proveedor junto al modelo activo resuelto.

Atajos para claves de proveedor

apx model key escribe la clave en engines.<provider>.api_key en ~/.apx/config.json. Dos proveedores que se usan comúnmente como fallbacks tienen nombres de atajo:

apx model key groq <key>          # → engines.groq.api_key
apx model key openrouter <key>    # → engines.openrouter.api_key

Para Anthropic, OpenAI y Gemini, definí las claves de la misma forma:

apx model key anthropic <key>
apx model key openai <key>
apx model key gemini <key>

Nota sobre terminología

El archivo de configuración usa la clave engines para lo que esta documentación llama motores (adaptadores LLM directos). Un diseño anterior usaba la clave model_providers internamente. Si ves referencias a model_providers en archivos de skills o notas más viejas, se refieren al mismo concepto; la clave canónica en ~/.apx/config.json es engines.

run vs. exec

	apx exec / apx chat	apx run
Modelo de ejecución	Llamada LLM directa dentro de APX	Subproceso de CLI externo
Ediciones de archivos / shell	No	Sí (el CLI externo puede escribir archivos y ejecutar comandos)
Elección de modelo	Flag --model o config del agente, resuelto por APX	Controlado por la propia config del CLI externo
Velocidad	Rápido — una llamada a la API	Más lento — lanza un proceso, puede tardar minutos
Usalo cuando	Preguntas rápidas, generación, razonamiento	Trabajo completo de agente de código (ediciones, terminal)

Relacionado

• Runtimes — CLIs de codificación externos vía apx run
• Configuración — referencia completa de ~/.apx/config.json