Configuración

APX usa dos capas de configuración — global (local a la máquina, nunca commiteada) y local al proyecto (commiteada al repo, sin secretos). Los comandos de ambas capas usan sintaxis de claves con puntos y entienden JSON.

Config global — `~/.apx/config.json`

El archivo de config global se crea en la primera ejecución. Contiene las credenciales de los engines, los ajustes del daemon, el modelo del super-agente, voz, memoria y las opciones de Telegram.

Estructura de nivel superior

{
  "port": 7430,
  "host": "127.0.0.1",
  "log_level": "info",
  "user": {
    "language": "en",
    "locale": "",
    "timezone": ""
  },
  "super_agent": { ... },
  "engines": { ... },
  "memory": { ... },
  "voice": { ... },
  "telegram": { ... },
  "projects": []
}

Engines

API keys y base URLs para cada proveedor de LLM soportado:

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

Super-agente

{
  "super_agent": {
    "enabled": false,
    "name": "apx",
    "model": "anthropic:claude-sonnet-4-5",
    "permission_mode": "automatico",
    "allowed_tools": [],
    "model_fallback": {
      "enabled": true,
      "models": [
        "openrouter:meta-llama/llama-3.3-70b-instruct",
        "groq:llama-3.3-70b-versatile"
      ],
      "health_timeout_ms": 800
    }
  }
}

permission_mode controla qué herramientas puede correr el super-agente sin preguntar:

Modo	Comportamiento
`total`	Todas las herramientas permitidas, sin confirmación
`automatico`	APX decide automáticamente según heurísticas de seguridad
`permiso`	Sólo las herramientas listadas en `allowed_tools`; el resto pregunta

El archivo de identidad — `~/.apx/identity.json`

Este archivo define el nombre de cara al usuario y la personalidad del asistente:

{
  "name": "APX",
  "persona": ""
}

Cambiá name para darle a tu asistente un nombre distinto en todas las superficies (Telegram, Desktop, Web). La clave técnica de config super_agent.name es algo aparte — identity.json es lo que ven los usuarios finales.

Config de proyecto — `.apc/config.json`

Los overrides a nivel de proyecto se commitean junto a las definiciones de los agentes. Tienen prioridad sobre la config global sólo para ese proyecto. Nunca pongas secretos acá — este archivo se commitea.

{
  "super_agent": {
    "model": "groq:llama-3.3-70b-versatile",
    "permission_mode": "total"
  },
  "telegram": {
    "route_to_agent": "reviewer"
  }
}

Comandos de config

apx config show                   # effective config (global merged with project defaults)
apx config show --only-overrides  # only what differs from defaults

apx project config show my-app
apx project config show my-app --key super_agent.model
apx project config show my-app --effective

apx

$ apx config show
{
"port": 7430,
"host": "127.0.0.1",
"log_level": "info",
"super_agent": {
  "enabled": true,
  "model": "anthropic:claude-sonnet-4-5",
  "permission_mode": "automatico"
},
"engines": {
  "anthropic": { "api_key": "sk-ant-••••a91f" },
  "openai":    { "api_key": "sk-••••7c2d" },
  "ollama":    { "base_url": "http://localhost:11434" }
},
"telegram": { "enabled": true, "channels": [ { "name": "default" } ] }
}

apx config show — configuración efectiva completa como JSON

Setear y desetear valores

Los valores entienden JSON — booleanos, números y arrays se parsean correctamente:

apx config set super_agent.enabled true
apx config set super_agent.model "anthropic:claude-sonnet-4-5"
apx config set engines.openai.api_key "sk-..."
apx config unset super_agent.model                  # remove key, fall back to default

Para la config de proyecto:

apx project config set my-app super_agent.model groq:llama-3.3-70b-versatile
apx project config set my-app telegram.route_to_agent reviewer
apx project config unset my-app super_agent.model
apx project config edit my-app                      # open in $EDITOR

Comandos de modelo

apx model gestiona el router de fallback de modelos del super-agente — la lista ordenada de proveedores que APX prueba en secuencia cuando el modelo primario no está disponible:

apx model status                                    # probe all providers, show active model
apx model order ollama openrouter groq              # set fallback order
apx model key groq sk-xxxx                          # save an API key
apx model set openrouter meta-llama/llama-3.3-70b-instruct  # pin a model for one provider
apx model test                                      # which model would be picked right now?
apx model enable                                    # enable the fallback router
apx model disable                                   # disable (primary only, no fallback)

apx

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

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

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

apx model status — sondeos de proveedores, presencia de API key y modelo activo

Comandos de permisos

apx permission es un atajo para leer y escribir super_agent.permission_mode:

apx permission show                                 # print current mode
apx permission set total                            # allow all tools
apx permission set automatico                       # APX decides
apx permission set permiso                          # only allowed_tools

Proyectos — config por proyecto en .apc/config.json.
Instalación — dónde se crea por primera vez ~/.apx/.