Iniciar el nodo

Un «nodo» es una máquina que ejecuta zqagent: tiene su directorio de trabajo, configuración de modelos y datos de conversaciones en local, y puede usarse solo en esa máquina o conectarse al centro de usuario para gestionarlo y consultarlo en remoto.

Esta página explica cómo iniciar, dejar residente y conectar un nodo.

Tres formas de ejecución

Forma	Cómo se inicia	Para qué
CLI interactiva	zqagent	Conversar y trabajar en la propia máquina; la más habitual
Nodo de servicio residente	zqagent serve	En un servidor o máquina siempre encendida, para gestión remota
App de escritorio	Instalar la app de escritorio	Si quieres interfaz gráfica; comparte el mismo nodo de inicio automático que el servicio residente

La app de escritorio y el nodo de servicio residente son el mismo servicio de nodo (mismo directorio de datos y puerto), solo cambia la interfaz. Instalar la app y luego ejecutar install.sh no crea un segundo nodo. La CLI interactiva usa datos independientes en el directorio actual; las tres formas se pueden combinar según necesidad.

CLI interactiva

zqagent

Al entrar en la interfaz interactiva, escribe tareas en lenguaje natural; el modelo se configura con /connect (ver Inicio rápido). Para todos los comandos, consulta Uso de la CLI.

La CLI interactiva es un nodo «utilizable en local», pero no escucha ningún puerto y no se puede gestionar en remoto. Si necesitas gestión remota, usa zqagent serve como se explica abajo.

Iniciar el nodo residente

zqagent serve arranca el servicio sin interfaz, escucha un puerto HTTP y se ejecuta en segundo plano.

zqagent serve

Tras arrancar, el registro muestra la dirección de escucha, el directorio de datos, el ID del nodo y la información del inquilino de demostración (en el primer arranque se crea el inquilino demo, cuya apiKey aleatoria se imprime en el registro y sirve para depurar en local).

Argumentos

Argumento	Descripción	Valor por defecto
--port <n>	Puerto de escucha; si está ocupado cambia al siguiente libre (el puerto real queda en server-port del directorio de datos y en el registro)	8787 (o PORT)
--host <addr>	Dirección de escucha; 0.0.0.0 permite acceso externo	127.0.0.1 (o HOST)
--data-dir <dir>	Directorio de datos (proyectos, conversaciones, libro, credenciales)	./.zqagent_data (o DATA_DIR)
--hub <url>	Dirección del centro de usuario; con --enroll-code conecta al arrancar	—
--enroll-code <code>	Código de conexión de un solo uso	—
--label <name>	Nombre visible del nodo	Nombre del host

Por defecto solo escucha en 127.0.0.1, es decir, solo accesible en local, lo más seguro. Si de verdad necesitas acceso desde la LAN o internet, define --host 0.0.0.0 y cuida el cortafuegos y el control de acceso.

Residencia en segundo plano

La ejecución en primer plano termina al cerrar la terminal; para uso prolongado instálalo como servicio del sistema (inicio automático + relanzado si falla).

Windows: no hay systemd / launchd. Crea en el «Programador de tareas» una tarea «Al iniciar sesión» con la ruta absoluta de zqagent.exe como programa y serve --port 8787 --data-dir "%APPDATA%\zqagent" como argumentos; también puedes poner un acceso directo a zqagent.exe serve ... en la carpeta de inicio (Win+R → shell:startup). Para detener o reiniciar, usa el Programador de tareas o el Administrador de tareas.

Recomendado: un solo comando (descarga el último archivo único, instala el servicio y activa la actualización automática; ver Instalación por archivo único):

curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

Después de instalar:

sudo sh -s -- status        # estado de ejecución
sudo sh -s -- logs          # seguir los registros
sudo sh -s -- restart       # reiniciar
sudo sh -s -- rollback      # volver a la versión anterior a la última actualización automática
sudo sh -s -- uninstall     # detener y eliminar

(sudo sh -s -- <subcomando> y curl ... | sudo sh -s -- <subcomando> son equivalentes; si ya descargaste el script, también sudo sh install.sh status.)

Instalar desde el código del repositorio (máquina de desarrollo / ya instalado con npm); launchd en macOS, systemd en Linux:

# Ejecutar en el directorio deploy/service del repositorio
bash install.sh install     # instalar y arrancar (inicio automático)
bash install.sh status      # estado de ejecución
bash install.sh logs        # seguir los registros
bash install.sh restart     # reiniciar
bash install.sh uninstall   # detener y eliminar

Directorio de datos por defecto: macOS ~/Library/Application Support/zqagent, Linux ~/.zqagent_data; registros: macOS ~/Library/Logs/zqagent/node.log, Linux ~/.zqagent_data/node.log. (Las versiones antiguas de Linux usaban /var/lib/zqagent; en instalaciones existentes el script mantiene la ruta de la unit original, sin migrar.) Se puede sobrescribir con PORT / HOST / DATA_DIR / LOG / SERVICE_NAME. Por ejemplo:

sudo PORT=9000 DATA_DIR=/data/zqagent bash install.sh install

El servicio arranca con «node en ruta absoluta + entrada de la CLI» y no depende del PATH de nvm/volta; las variables adicionales en Linux (LLM key, HUB_URL, SECRET_KEY, etc.) pueden ir en /etc/zqagent.env. La parada usa SIGTERM y serve guarda el libro antes de salir (periodo de gracia de 3 s, ajustable con ZQAGENT_SHUTDOWN_GRACE_MS).

El script comprueba que la CLI actual admita serve: las versiones antiguas (como 0.1.33) no tienen ese subcomando, así que ejecuta antes npm i -g @zqagent/core@latest o el proceso entrará en silencio en una sesión interactiva.

Escribir la unit de systemd a mano (sin el script)

# /etc/systemd/system/zqagent.service
[Unit]
Description=zqagent node
After=network-online.target

[Service]
# Sustituye <usuario> por el usuario que ejecutará el nodo; los datos van a su home y los permisos le pertenecen
User=<usuario>
ExecStart=/usr/local/bin/zqagent serve --port 8787 --data-dir %h/.zqagent_data
Restart=always
RestartSec=3
KillSignal=SIGTERM
TimeoutStopSec=15

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now zqagent
journalctl -u zqagent -f      # ver registros

pm2 (alternativa)

No metas todo el comando en una sola cadena (se tratará como script bash -c, se perderán los argumentos y volverá a la sesión interactiva):

pm2 start "$(command -v zqagent)" --name zqagent -- serve --port 8787 --data-dir "$HOME/.zqagent_data"
pm2 save && pm2 startup   # inicio automático

nohup (depuración temporal)

nohup zqagent serve --port 8787 --data-dir "$HOME/.zqagent_data" \
  > "$HOME/.zqagent_data/node.log" 2>&1 &

Actualización automática

Instalado como archivo único (SEA) y gestionado por el servicio del sistema, el nodo mantiene su versión solo. En una máquina nueva se recomienda el comando único de Instalación por archivo único, que prepara binario y servicio a la vez:

1. Comprueba una vez 5 minutos después del arranque y luego cada 6 horas (±15% de jitter)
2. Si hay versión nueva, la descarga en silencio, verifica el SHA-256 y ejecuta --version como autocomprobación
3. Espera a 60 segundos de inactividad continua (sin conversaciones en ejecución ni esperando aprobación/respuesta), se reemplaza y sale
4. systemd / launchd arranca la nueva versión y la versión se actualiza sola en la consola

Un fallo no afecta al nodo: los fallos de descarga/verificación solo se registran y, tras 3 fallos consecutivos con la misma versión, se omite.

Requisitos previos

La actualización automática solo actúa si se cumplen las tres condiciones (todas necesarias):

• Forma de archivo único (iniciado desde el artefacto SEA, no node dist/cli/index.js)
• Gestionado por systemd / launchd (instalado con install.sh)
• Clave pública de verificación ZQAGENT_UPDATE_PUBKEY configurada

Un nodo instalado con npm no se reemplaza automáticamente; actualízalo con npm i -g @zqagent/core@latest.

macOS: la detección de gestión es igual que en Linux. Dentro del proceso del servicio funciona directamente; al ejecutar a mano en la terminal zqagent update --status/--check/--now también reconoce el estado gestionado, la clave pública y el canal desde el job de launchd (pid / program) y las EnvironmentVariables del plist, sin necesidad de hacer source de variables. Para desinstalar, sudo sh -s -- uninstall.

Windows: sin systemd / launchd, el nodo de archivo único no se actualiza solo (zqagent update --status mostrará «gestión por servicio: no gestionado (primer plano/nohup)»). Para actualizar, detén el proceso serve, sobrescribe con el nuevo exe y vuelve a arrancar; zqagent update --now se rechaza en entornos no gestionados.

El script de instalación obtiene la clave pública por defecto, así que un comando instala y activa la actualización automática:

curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

Para sobrescribir la obtención automática con una clave guardada fuera de banda, añade --pubkey "..." (la clave explícita tiene prioridad y no se sobrescribe por red).

Interruptores y configuración

Variable	Por defecto	Descripción
ZQAGENT_AUTO_UPDATE	1	0 desactiva por completo la actualización automática
ZQAGENT_UPDATE_PUBKEY	Se escribe al instalar	Clave pública de verificación (PEM o base64 SPKI DER); sin ella no se instala automáticamente
ZQAGENT_UPDATE_CHANNEL	stable	Canal del manifiesto (stable / beta)
ZQAGENT_UPDATE_URL	https://agent.cd-zq.com/downloads/zqagent/<channel>.json	Dirección del manifiesto; se puede sobrescribir en red interna
ZQAGENT_UPDATE_INTERVAL_MS	21600000 (6 h)	Intervalo de comprobación
ZQAGENT_UPDATE_MIN_UPTIME_MS	600000 (10 min)	Tiempo mínimo desde el arranque antes de actualizar
ZQAGENT_UPDATE_IDLE_MS	60000	Inactividad continua necesaria para instalar
ZQAGENT_UPDATE_INSECURE	—	1 permite manifiesto http (solo pruebas internas)

Comprobar si hay actualización

zqagent update --check       # solo comprueba si hay versión nueva (sin descargar, inmediato)
zqagent update --status      # versión actual, canal, última comprobación, motivo de espera/fallo

Ejemplo de salida:

Versión actual   v0.2.1
Forma de ejecución archivo único (SEA)
Gestión por servicio systemd
Canal de actualización stable
Dirección del manifiesto https://agent.cd-zq.com/downloads/zqagent/stable.json
Actualización automática activada

--check imprime «Ya tienes la última versión (vX)» o «Nueva versión vY disponible (actual vX)».

Intervención manual

zqagent update --now         # descargar e instalar ya (omite la espera de inactividad; requiere reiniciar el servicio)
zqagent update --rollback    # volver a la versión anterior a la última actualización

Rollback desde el servicio (reinicio automático):

sudo sh -s -- rollback    # instalación por archivo único (si descargaste el script: sudo sh install.sh rollback)
sudo bash install.sh rollback        # instalación desde el repositorio

Tras el rollback se omite esa versión: la actualización automática no la reinstala de inmediato y espera a una versión más nueva; para forzarla, usa zqagent update --now.

Lado de publicación

Con un comando: compila el archivo único SEA → genera y firma el manifiesto → sincroniza al directorio de descargas. Sin pasar por npm y sin Node en el nodo (el binario incluye el runtime).

# Primera vez: generar el par de claves de firma (la privada solo en la máquina de publicación o CI secret; la pública se distribuye a los nodos)
node packages/core/scripts/gen_update_keys.mjs --out .update-keys

# Cada publicación (todos los argumentos tienen valor por defecto: versión de packages/core/package.json, clave privada de .update-keys/update-private.pem)
bash scripts/release_node.sh

Argumentos habituales:

Argumento	Por defecto	Descripción
--version X	versión de packages/core/package.json	Número de versión simple; el script comprueba que coincidan
--key FILE	.update-keys/update-private.pem	Clave privada Ed25519 para firmar el manifiesto
--pubkey-file FILE	update-public.b64 en el mismo directorio	Clave pública de verificación del nodo; antes de publicar se comprueba el par y se sincroniza
--host USER@HOST	vacío = publicar en local	No hace falta si la máquina de publicación es el servidor del sitio
--dest DIR	/var/www/zqagent-downloads/zqagent	Directorio real al que apunta /downloads/ de nginx
--notes TEXT	本次更新内容: 例行更新	Se escribe en el manifiesto y se ve en el registro del cliente
--skip-build	—	Reutiliza los artefactos existentes de packages/core/release/cli
--dry-run	—	Solo imprime los comandos que se ejecutarían

Tres usos típicos:

# 1) La máquina de publicación es el servidor del sitio: escribe directamente en el directorio local
bash scripts/release_node.sh --skip-build

# 2) Publicar desde otra máquina: ssh + rsync al servidor del sitio
bash scripts/release_node.sh --host deploy@your-server --skip-build

# 3) Ver primero qué haría
bash scripts/release_node.sh --dry-run

Los artefactos multiplataforma solo se pueden compilar en el sistema/arquitectura correspondiente; para publicar en todas las plataformas, compila cada una en una matriz de CI y luego reúne y publica con --skip-build --host ....

Estructura del directorio tras publicar:

/downloads/zqagent/
├── install.sh           # script de instalación en una línea
├── install-node.sh      # copia de compatibilidad de la dirección antigua (mismo contenido)
├── update-public.b64    # clave pública de verificación (se pasa con --pubkey al instalar)
├── stable.json          # manifiesto de actualización (lo lee el nodo)
├── stable.json.sig      # firma del manifiesto
├── stable.txt           # manifiesto en texto plano (para el script de instalación)
└── v0.2.2/
    └── zqagent-<platform>-<arch>

El nodo solo descarga el binario tras verificar la firma y luego vuelve a comprobarlo con el SHA-256 del manifiesto. Comprobación tras publicar:

curl -s https://agent.cd-zq.com/downloads/zqagent/stable.txt
curl -s https://agent.cd-zq.com/downloads/zqagent/stable.json | head -20

El flujo completo de publicación y rollback está en docs/release-runbook.md del repositorio.

Conectar al centro de usuario (opcional)

Tras conectar, puedes ver en el centro de usuario el estado en línea del nodo, sus proyectos y eventos. Dos formas, elige una:

• Cuenta del Hub (recomendado): usa el correo/teléfono registrado en el centro de usuario + contraseña
• Código de conexión de un solo uso: entra en el centro de usuario → crea una gestión de nodos → genera un código (válido 15 minutos)

Nodo ya en ejecución: conexión en caliente (sin reiniciar)

# Cuenta: correo o teléfono + contraseña
zqagent link --hub https://hub.cd-zq.com --username you@example.com --password '<contraseña>'
zqagent link --hub https://hub.cd-zq.com --username 13800000000 --password '<contraseña>'

# Teléfono + código SMS
zqagent link --hub https://hub.cd-zq.com --username 13800000000 --sms-code <código>

# O código de conexión de un solo uso
zqagent link --hub https://hub.cd-zq.com --code <código>

Archivo único de Windows:

zqagent.exe link --hub https://hub.cd-zq.com --username you@example.com --password <contraseña>
zqagent.exe link --hub https://hub.cd-zq.com --code <código>

Sin argumentos de credenciales, zqagent link entra en un asistente interactivo que pregunta la dirección del Hub, el método de acceso y usuario/contraseña (contraseña oculta). La contraseña también puede darse con ZQAGENT_HUB_PASSWORD para no dejarla en el historial.

El directorio de datos por defecto en Windows es %APPDATA%\zqagent; link lo descubre automáticamente desde runtime\service.json, registrado por la app de escritorio. Solo si configuraste una tarea programada a mano y el directorio de datos no está en la ubicación por defecto hay que añadir --data-dir.

link intenta primero la conexión en caliente al serve que ya corre en la máquina. Linux lo localiza por /proc, macOS por ps y Windows por Win32_Process de PowerShell, así que aunque serve use un --data-dir / --port propio también lo encuentra; si PowerShell no está disponible, vuelve a «escribir fleet.json y aplicar en el siguiente arranque».

Si encuentra varias instancias, link prefiere el servicio gestionado por systemd / launchd (inicio automático y sigue tras reiniciar) y luego el serve lanzado a mano desde la línea de comandos; el .zqagent_data del directorio actual es el último recurso, para evitar que una instancia temporal se quede con las credenciales y el comando diga «correcto» mientras el servicio gestionado sigue sin conexión.

Nombre del nodo

Los nodos sin --label al conectar usan por defecto el nombre del host como nombre visible; en el Hub se ve el nombre de la máquina, no el nodeId. Se puede cambiar después en dos sitios, que modifican el mismo registro:

• Centro de usuario del Hub → Gestión de nodos → «Renombrar» del nodo
• En la máquina del nodo (si hay servicio local, se aplica en caliente sin reiniciar):

zqagent rename ten004-dev

Si el nodo ya se conectó al Hub, el comando sincroniza el registro con las credenciales del propio nodo y la consola lo refleja al actualizar. Si no está conectado, solo escribe la configuración local y se aplica al siguiente serve.

Aunque el servicio no esté en ejecución, link analiza el plist / la unit de systemd para encontrar el directorio de datos registrado y escribe allí las credenciales (el servicio se conectará solo al arrancar). Por eso, tanto en la app de escritorio como en un nodo instalado con install.sh, no hace falta pasar --data-dir a mano.

Normalmente no hay que escribir --data-dir: el comando anterior descubre el nodo local automáticamente. Solo hay que añadirlo cuando aparezca «no se encontró el servicio de nodo local», y usando un directorio escribible por el usuario actual (el valor por defecto de cada plataforma):

Plataforma	Directorio de datos por defecto
macOS	$HOME/Library/Application Support/zqagent
Linux	~/.zqagent_data (propiedad del usuario actual; versiones antiguas /var/lib/zqagent)
Windows	%APPDATA%\zqagent

No copies el --data-dir /var/lib/zqagent de tutoriales antiguos: las instalaciones nuevas usan ~/.zqagent_data por defecto y indicar un directorio del sistema provoca EACCES: permission denied. Omite ese argumento.

Conectar al arrancar

Pasa la dirección del Hub y la cuenta (o el código) a serve:

# Cuenta (adecuado para entornos no interactivos como systemd / contenedores)
zqagent serve --hub https://hub.cd-zq.com --username you@example.com --password '<contraseña>'

# Código de conexión
zqagent serve --hub https://hub.cd-zq.com --enroll-code <código>

También con variables de entorno (para contenedores / scripts):

HUB_URL=https://hub.cd-zq.com ZQAGENT_HUB_USERNAME=you@example.com \
  ZQAGENT_HUB_PASSWORD='<contraseña>' zqagent serve

HUB_URL=https://hub.cd-zq.com HUB_ENROLL_CODE=<código> zqagent serve

Conectar desde la CLI interactiva

Dentro de zqagent:

/link                                # asistente de conexión de cuenta
/link <código> [dirección Hub]

Docker

docker run -d -p 8787:8787 -v zqagent-data:/data \
  -e HUB_URL=https://hub.cd-zq.com -e HUB_ENROLL_CODE=<código> \
  ghcr.io/<owner>/zqagent-server

Credenciales y red

• Tras conectar, las credenciales se escriben en {DATA_DIR}/fleet.json; los siguientes arranques no necesitan cuenta ni código
• El nodo solo necesita conexión saliente a la pasarela (wss://, normalmente 443); no requiere entrada pública ni abrir puertos
• Para revincular o desvincular: desde el detalle del nodo en el centro de usuario, o borra fleet.json y vuelve a conectar

Directorio de datos

Todos los datos persistentes del nodo están en {DATA_DIR} (por defecto ./.zqagent_data, viaja con el proyecto):

Ruta	Contenido
{DATA_DIR}/admin.json	Clave de administrador
{DATA_DIR}/fleet.json	Credenciales de conexión (0600)
{DATA_DIR}/usage/	Libro de uso, resúmenes y tabla de precios
Conversaciones y proyectos	Cada proyecto los guarda según su directorio de trabajo

La API Key del modelo se guarda cifrada aparte en el directorio de configuración del usuario (macOS / Linux ~/.config/zqagent/, Windows %APPDATA%\zqagent\), separada del directorio de datos.

Verificar que el nodo está en línea

1. Abre el centro de usuario y entra en la gestión de nodos correspondiente
2. El nodo aparece en la lista con estado en línea
3. Haz clic en el nodo para entrar en la consola del nodo y ver proyectos, conversaciones, uso y eventos

Si el nodo está desconectado: comprueba que el proceso serve siga vivo y que la máquina pueda conectar saliente a la pasarela (FLEET_GATEWAY_URL).

Siguiente paso

• Consola del nodo: gestionar nodos, conversaciones y uso con interfaz gráfica
• Descripción del control remoto: encargar tareas desde el móvil y QQ
• Configuración del servidor: variables de entorno, conexión a la nube y opciones de red pública