Inicio rápido

Esta página te guía para instalar y ejecutar zqagent desde cero y completar tu primera conversación.

¿No quieres usar la línea de comandos? Consulta la app de escritorio: descarga el instalador y usa la interfaz gráfica.

Instalación

Las tres plataformas ofrecen paquetes sin dependencias; no hace falta instalar Node previamente. Aquí tienes la descarga para tu sistema:

未能识别你的系统。 请从下面选择对应平台的安装包。

Windows64 位macOSApple 芯片macOSIntel 芯片Linuxx64LinuxARM64

不确定选哪个？第一个通常就对了。

查看支持的系统版本

En Linux y macOS también puedes instalar con una línea (registra el inicio automático):

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

Si ya tienes Node.js 18+, también puedes usar npm:

# Instalación global (publicado en npm público; no hace falta configurar otro registro)
npm i -g @zqagent/core

Tras instalar, ejecuta zqagent para iniciar la CLI.

Para elegir el canal de versiones (estable / beta), ver los requisitos o resolver problemas de instalación, consulta Instalación.

Conectar el LLM

No hace falta escribir .env a mano: escribe /connect y configura la conexión de forma interactiva:

1. Elige el provider (OpenAI / DeepSeek / Qwen / Zhipu GLM / Kimi / Xiaomi MiMo / personalizado)
2. Introduce la API Key
3. Actualiza automáticamente la lista de modelos y elige uno (los modelos de conversación van primero; los de embeddings/voz/imagen/canales dedicados se marcan con ⚠️ y se colocan al final)
4. Autocomprobación: envía una petición mínima real para confirmar que el modelo funciona en este endpoint; si falla, explica el motivo y pide elegir otro
5. Ajusta el esfuerzo de razonamiento

La API Key se guarda cifrada con AES-256-GCM en ~/.config/zqagent/ del equipo, nunca en texto plano.

Si eliges un modelo que no puede conversar, la pasarela suele devolver solo Required parameter(s) missing or invalid, sin indicar dónde está el problema. La ordenación y la autocomprobación anteriores existen para detectarlo en la configuración y no en la primera conversación. Para diagnosticarlo, consulta Preguntas frecuentes.

Desarrollo local

# Instalar dependencias
pnpm install

# Configurar variables de entorno (copia a .env y rellena), o usa /connect al iniciar
#   OPENAI_API_KEY=sk-...          # Obligatorio (si no usas /connect)
#   OPENAI_MODEL=nombre-del-modelo # Opcional; si no se define, elige con /connect al iniciar
#   OPENAI_BASE_URL=...            # Opcional; endpoint personalizado
#   WORKSPACE=./                   # Opcional; raíz del espacio de trabajo, por defecto el directorio actual
cp .env.example .env

# Iniciar la CLI
pnpm run dev

Primera tarea

Al iniciar entras en la CLI interactiva; escribe la tarea en lenguaje natural, por ejemplo:

> Inicializa un proyecto TypeScript en el directorio actual

Planificará y llamará a las herramientas para completarla. Por defecto se ejecuta en modo interactivo: las operaciones con efectos secundarios muestran una tarjeta de aprobación y esperan tu confirmación.

Para más comandos, modos y detalles de aprobación, consulta Uso de la CLI.

Siguiente paso

• Detalles de instalación y canales de versión: Instalación
• Dejarlo como nodo con gestión remota: Iniciar el nodo
• Interfaz gráfica: Consola del nodo
• Ver todas las herramientas integradas: Herramientas integradas
• Comandos y modos de ejecución: Uso de la CLI
• Si prefieres interfaz gráfica: App de escritorio
• Control remoto o uso compartido: Descripción del control remoto