Quick Start

This page walks you through installing and running zqagent from scratch and completing your first conversation.

Prefer not to use the command line? Check out the Desktop App and download the installer to use it graphically.

Installation

All three platforms offer a zero-dependency runtime package—no need to pre-install Node. Below is the download prepared for your current system:

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

Windows64 位macOSApple 芯片macOSIntel 芯片Linuxx64LinuxARM64

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

查看支持的系统版本

On Linux and macOS, you can also install with a single command (automatically registers auto-start on boot):

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

If you already have Node.js 18+, you can also install via npm:

# 全局安装（发布在公共 npm，无需配置额外软件源）
npm i -g @zqagent/core

Once installed, run zqagent to start the CLI.

To choose a release channel (stable / beta), check system requirements, or troubleshoot installation issues, see Installation.

Connect to an LLM

After startup, there's no need to write .env manually—just enter /connect to configure the LLM connection interactively:

1. Select a provider (OpenAI / DeepSeek / Qwen / Zhipu GLM / Kimi / Xiaomi MiMo / Custom)
2. Enter the API Key
3. Automatically refresh the model list and choose a model (chat models are listed first; non-chat models such as embedding/speech/image/dedicated channels are marked with ⚠️ and placed at the end)
4. Self-check: actually send a minimal request to confirm the model is available on this endpoint; if it fails, the reason is shown and you're asked to choose again
5. Set the reasoning effort

The API Key is saved locally to ~/.config/zqagent/ with AES-256-GCM encryption and is never written to disk in plaintext.

When you pick a model that can't chat, the gateway usually just returns Required parameter(s) missing or invalid, giving no clue what's wrong—the list ordering and self-check above exist so you catch it during configuration rather than on your first conversation. For troubleshooting, see FAQ.

Local Development

# 安装依赖
pnpm install

# 配置环境变量（复制为 .env 后填写），或启动后直接 /connect
#   OPENAI_API_KEY=sk-...          # 必填（未用 /connect 时）
#   OPENAI_MODEL=你的模型名        # 可选，不设则启动后 /connect 选择
#   OPENAI_BASE_URL=...            # 可选，自定义端点
#   WORKSPACE=./                   # 可选，工作区根目录，默认当前目录
cp .env.example .env

# 启动 CLI
pnpm run dev

First Task

After startup you enter the interactive CLI; simply type a natural-language task, for example:

> 帮我在当前目录初始化一个 TypeScript 项目

It will automatically plan and call tools to complete the task. It runs in interactive mode by default, and operations with side effects will pop up an approval card awaiting your confirmation.

For more commands, run modes, and approval details, see CLI Usage.

Next Steps

• Installation details and release channels: Installation
• Run persistently as a remotely manageable node: Start a Node
• Graphical interface: Node Console
• View all built-in tools: Built-in Tools
• Learn commands and run modes: CLI Usage
• Want a graphical interface: Desktop App
• Want remote control or multi-user use: Remote Control Overview