Preguntas técnicas (avanzado)
Esta página es para quien usa la línea de comandos, conecta su propio modelo o construye una integración. Si solo quieres que ordene archivos, con las preguntas frecuentes tienes suficiente.
Instalación y conexión
¿Cómo configuro un modelo? Tras iniciar la CLI, escribe /connect y sigue las indicaciones para elegir un proveedor (DeepSeek / OpenAI / personalizado), introducir la API Key, elegir modelo y fijar el esfuerzo de razonamiento. No hace falta editar ningún archivo de configuración.
¿Dónde se guarda la API Key? ¿Puede filtrarse en texto plano? Se guarda en local en ~/.config/zqagent/, cifrada, y nunca se escribe en disco en texto plano.
¿Qué modelos admite? Cualquier endpoint compatible con OpenAI: DeepSeek, OpenAI, Ollama o un servicio propio. Usa la opción "Personalizado" de /connect o define OPENAI_BASE_URL.
Aparece el error Required parameter(s) missing or invalid / fallo al llamar a Responses API. Lo más probable es que el modelo elegido no sirva para chat. El catálogo del gateway (/models) suele ser "completo" e incluye modelos de embeddings (*-embedding), reranking (*-rerank), voz (*-asr / *-tts), tiempo real (*-realtime), imagen (qwen-image* / wan*) y canales dedicados (cmaas-*), que no aceptan peticiones de chat normales. /connect ya mueve esos modelos al final de la lista con una marca ⚠️ y, tras seleccionarlo, hace una autocomprobación (envía una petición mínima real); si no funciona, te pide elegir otro. Cambia a un modelo de chat de la parte superior de la lista (qwen3.8-flash, qwen-plus, deepseek-flash).
Los dos motivos que indica cuando falla la autocomprobación:
| Aviso | Significado | Qué hacer |
|---|---|---|
The product is not activated | El modelo no está activado con esa API Key / cuenta (o hay impago o cuota agotada) | Actívalo en la consola del gateway o cambia a uno activado |
InvalidParameter: Required parameter(s) missing or invalid | El nombre del modelo no lo acepta la interfaz de chat, o se envían parámetros no admitidos | Cambia a un modelo de chat; si persiste, pon el esfuerzo de razonamiento en "Predeterminado" |
Para comprobar a mano si un modelo funciona:
curl -s <BaseURL>/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" -H "content-type: application/json" \
-d '{"model":"<nombre-del-modelo>","messages":[{"role":"user","content":"hi"}]}'Error command not found al instalar, o descargas muy lentas. El paquete está publicado en npm público; normalmente basta con instalarlo:
npm i -g @zqagent/coreLas descargas lentas suelen ser un problema de red. Puedes usar temporalmente un espejo nacional (el espejo se sincroniza automáticamente tras cada publicación):
npm i -g @zqagent/core --registry=https://registry.npmmirror.com/Para otros problemas de instalación, consulta Instalación.
¿Estable o beta? Actualmente npm público solo publica la versión estable (@latest); no hay etiqueta beta aparte, así que instala la última versión. Consulta Instalación.
Uso diario
¿Cómo cambio el modo de ejecución?/discuss (conversación de solo lectura), /plan (exploración de solo lectura + plan), /interactive (aprobación paso a paso, por defecto), /auto (totalmente automático, alto riesgo). Consulta Uso de la CLI.
¿Se ejecutan directamente las operaciones peligrosas? En el modo interactivo por defecto, no: escribir archivos o ejecutar comandos muestra primero una tarjeta de aprobación y tú decides si permitir o rechazar.
¿Puedo cambiar los requisitos mientras una tarea larga está en marcha? Sí. Mientras se ejecuta, escribe directamente y pulsa Enter: se inyecta como información adicional en la siguiente iteración. Para empezar otra tarea, interrumpe primero.
¿Cómo interrumpo una tarea atascada? Pulsa ESC dos veces.
¿Una conversación larga supera la ventana de contexto del modelo? No. Al alcanzar el umbral, la conversación anterior se compacta automáticamente conservando lo importante. No necesitas intervenir.
¿Cómo guardo y recupero sesiones?/sessions lista las sesiones guardadas y te deja elegir una para recuperarla; /clear vacía la sesión actual.
Nodos y consola
¿Cómo mantengo zqagent en marcha y además lo gestiono en remoto? Ejecuta zqagent serve para dejarlo residente como nodo, o instala la app de escritorio. Al conectarlo al Centro de usuario podrás verlo en remoto. Los pasos están en Iniciar un nodo.
¿Se pueden gestionar nodos desde el navegador? ¿Y desde el móvil? Sí. Tras conectar el nodo, abre el Centro de usuario en el navegador para entrar en la Consola de nodos. También funciona en navegadores móviles (diseño adaptable + PWA, con "Añadir a pantalla de inicio").
¿Dónde veo el uso y el coste? En el panel de uso de la Consola de nodos (la tarjeta de token de la portada del proyecto o "Monitorización → Ver uso" en el detalle del nodo), con estadísticas por periodo y modelo y exportación a CSV. La página de cuenta muestra además totales entre nodos.
¿Se pierde lo que no he enviado? No. El borrador del cuadro de entrada de la consola se guarda automáticamente y se restaura al cambiar de sesión o recargar la página.
¿Se pierde el contenido si se cae la red o paso a segundo plano? No. El flujo de eventos en tiempo real se reconecta solo y completa los incrementos: al recuperarse, el contenido no se pierde ni se duplica.
App de escritorio
¿Las tareas siguen en marcha al cerrar la ventana? Sí. Cerrar la ventana solo la oculta en la bandeja del sistema; incluso si sales desde la bandeja, el servicio de nodo en segundo plano sigue vivo gracias a launchd / systemd.
¿Dónde están los datos? Los datos del nodo están en el directorio de datos del servicio del sistema (macOS ~/Library/Application Support/zqagent/, Linux ~/.zqagent_data/, Windows %APPDATA%\zqagent\) y se comparten con el nodo instalado por install.sh. Las preferencias de escritorio se guardan aparte en ~/.config/zqagent-desktop/desktop.json. Consulta App de escritorio → detalles de instalación.
Control remoto
¿Hace falta un servidor con IP pública? No. Tanto el control por móvil como por QQ usan conexiones salientes a través de un relé de terceros. Consulta Descripción del control remoto.
¿Cómo lo uso desde el móvil o QQ? Consulta Acceso remoto y Bot de QQ.
Ampliar las herramientas
¿Cómo le doy más herramientas a la IA? Conecta servidores de herramientas externos vía MCP, o añade herramientas que ejecutan comandos con /tool add. Consulta MCP y herramientas.