安装

zqagent 有两种安装形态：命令行工具（CLI） 与 桌面应用。本页讲解 CLI 的安装、升级与卸载。

不想用命令行？直接看桌面应用，下载安装包即可图形化使用。

最快：一行安装（Linux / macOS）

bash

curl -fsSL https://agent.cd-zq.com/install.sh | sh
# 服务器上建议用 root 执行，才能装成开机自启服务
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

脚本会读取官方版本清单、下载对应架构的单文件可执行程序、校验 SHA-256 后装进 PATH， 不需要预先安装 Node。默认装到 /usr/local/bin（可写时）或 ~/.local/bin。支持 Linux（x64 / arm64）与 macOS（Intel x64 / Apple Silicon arm64）。

装完会自动注册为开机自启服务（Linux systemd / macOS launchd；崩溃自动拉起），并打印当前状态与三种用法：

用途	方式
图形界面	浏览器打开 `http://127.0.0.1:8787`
命令行	`zqagent`（输入 `/connect` 配置模型）
远程管理	用 Hub 账号直接接入：`zqagent link --hub https://hub.cd-zq.com --username <邮箱/手机号> --password '<密码>'`（也可用接入码）

装有终端的机器在安装末尾会询问是否接入 Hub：直接输入 Hub 注册的邮箱/手机号与密码即可，密码不会回显。自动化场景可在安装命令里直接带上账号（密码建议用环境变量传入）：

bash

# 隐藏输入密码（不回显、不进 shell 历史）
read -rsp 'Hub 密码：' ZQAGENT_HUB_PASSWORD; echo
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- \
  --username you@example.com --password "$ZQAGENT_HUB_PASSWORD"

# 或使用一次性接入码（15 分钟有效）
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --code <接入码>

不想在安装时接入就加 --no-enroll，之后随时可以执行 zqagent link 补齐。

非 root 执行、容器内没有 systemd 时会跳过服务化并给出前台启动命令；需要纯 CLI 则加 --no-service。

可以重复执行：已安装且已是最新版本时不会重新下载，只报告当前状态（版本、服务是否运行、本地地址是否可访问、是否已接入 Hub、自动更新通道）；有新版本则自动升级并重启服务。

常用参数（通过 sh -s -- 传入）：

bash

# 换端口 / 监听地址 / 数据目录
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --port 9000 --host 0.0.0.0

# 装到自定义目录
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --bin-dir ~/bin

# 只装 CLI，不装开机自启服务
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --no-service

# 安装完成后用 Hub 账号接入（也可用 --code <接入码>）
read -rsp 'Hub 密码：' ZQAGENT_HUB_PASSWORD; echo
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- \
  --username you@example.com --password "$ZQAGENT_HUB_PASSWORD"

# 跳过安装尾声的接入询问
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --no-enroll

# 已安装时强制重新下载覆盖
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --force

# 强制走 npm
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --npm

# 不上报匿名安装统计
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --no-telemetry

一键脚本面向 macOS / Linux；Windows 请直接下载单文件 exe （目标机不需要 Node），或用下面的 npm 方式安装。

关于安装统计：安装成功后会向我们的自建统计服务上报一条匿名记录（仅版本、平台、架构、安装方式），用于判断各平台的实际使用情况。不含用户名、安装路径、IP 或任何可识别身份的信息，也不使用 Cookie。不需要的话加 --no-telemetry 或设置 ZQAGENT_NO_TELEMETRY=1 即可完全关闭。

macOS 说明

芯片架构：Intel（macos-x64）与 Apple Silicon（macos-arm64）各自下载对应产物。
开机自启：以 root 安装注册为 LaunchDaemon （/Library/LaunchDaemons/com.zqagent.node.plist，开机即启动）；普通用户安装注册为 LaunchAgent（~/Library/LaunchAgents/，登录后启动）。 plist 带 KeepAlive，进程退出会被 launchd 立即拉起。
自动更新：与 Linux 一致——服务内静默下载并按清单验签，空闲时替换二进制后退出，由 launchd 拉起新版本；zqagent update --status 可查看托管状态与上次检查时间。
卸载：sudo sh -s -- uninstall。会同时清理系统级 Daemon 与发起 sudo 的用户的 Agent；数据目录与二进制保留，重复执行不会报错。
单实例：root 重装时会先移除该用户的 LaunchAgent，避免系统级与用户级两个实例抢同一端口。

默认数据目录：普通用户为 ~/Library/Application Support/zqagent，以 root 安装时为 /var/root/Library/Application Support/zqagent。

macOS 两个架构的单文件产物随每个版本一同发布，安装时无需预先装 Node。若某次清单中缺少当前架构的产物，脚本会自动回退到 npm（需要 Node ≥ 18.17）； npm 全局目录不可写时会改装到 ~/.local 并给出提示。

端口被占用时自动换端口

默认端口 8787 在开发机上经常已被别的服务占用。安装脚本会在注册服务前检查端口，被占用时逐个往递增（8788、8789…），把每次尝试打印出来，并用最终端口生成服务配置：

→ 检查端口 8787 是否可用 ...
! 端口 8787 已被其它进程占用
→ 尝试端口 8788 ...
! 已自动改用端口 8788（原定 8787 被占用）
  本地控制台：http://127.0.0.1:8788

节点进程本身也有同样的保护：服务启动时若端口仍被占用，会自动改用下一个可用端口并在日志中说明，实际端口写入数据目录下的 server-port 文件，安装脚本与 zqagent update --status 都按它报告地址。

若端口是本节点自己占用的（服务已在运行），脚本会沿用该端口，不会再起一个实例。需要固定端口时用 --port <端口>；从起始端口起连续 20 个都被占用则报错退出。

Windows 单文件（免安装 Node）

Windows 产物是单个 zqagent.exe，目标机不需要 Node/npm。

系统要求：Windows 10 / Server 2016 或更高版本（仅 64 位 x64 或 ARM64）。 Windows 7、8、8.1 与 Server 2008 R2 / 2012 无法运行——缺的是系统 API，安装 C++ 运行库也不能解决，详见 Windows 支持版本。

下载与架构匹配的产物（目标机不需要 Node/npm）：
架构适用下载
x64 绝大多数 Windows zqagent-windows-x64
文件名带版本号与构建时间；链接随站点构建自动指向当前发布版本。完整清单见 https://agent.cd-zq.com/downloads/zqagent/stable.json（binaries.windows-x64.url）。 Windows ARM64 目前没有产物，请使用 x64 版本（Windows 会以仿真方式运行）。
放到任意目录（例如 %LOCALAPPDATA%\zqagent\），打开 PowerShell 或 cmd 运行：
bat
```
.\zqagent-windows-x64-v<版本>-<构建时间>.exe
```
首次启动后输入 /connect 配置模型即可使用。
想直接敲 zqagent：把该目录加入用户 PATH（「系统属性 → 环境变量」），并把文件重命名为 zqagent.exe。命令行方式（setx 对超长 PATH 会截断）：
bat
```
setx PATH "%PATH%;%LOCALAPPDATA%\zqagent"
```

架构	适用	下载
x64	绝大多数 Windows	zqagent-windows-x64

常驻为可远程管理的节点：

bat

zqagent.exe serve --port 8787 --data-dir "%APPDATA%\zqagent"

需要开机自启时，用「任务计划程序」创建“登录时运行”的任务：程序填 exe 绝对路径，参数填 serve --port 8787 --data-dir "%APPDATA%\zqagent"。

Windows 没有 systemd / launchd，因此单文件不启用自动更新（替换自身后没有服务管理器把它拉起）。升级方式：停止进程 → 下载新 exe 覆盖 → 重新启动。
产物未做 Authenticode 签名（注入 SEA 会破坏 node.exe 自带签名），首次运行可能出现 SmartScreen 提示；正式分发前用 signtool 重签。
CLI 已内置 ripgrep，无需另外安装 rg。

系统要求

项目	要求
操作系统	macOS / Linux / Windows。Windows 需 10 / Server 2016 及以上（桌面应用需 10 1709+），详见 Windows 支持版本
Node.js	≥ 18.17（仅 npm 安装需要；Linux / macOS / Windows 单文件包均自带运行时）
网络	能访问 `agent.cd-zq.com`（单文件安装）或公共 npm `registry.npmjs.org`（npm 安装）

子命令：管理已安装的节点

install.sh 同时是一个管理工具。除安装外还支持 status / logs / restart / rollback / print-config 子命令（需要 sudo 时加 sudo）：

bash

sudo sh -s -- status        # 版本、服务、本地地址、远程接入、自动更新
sudo sh -s -- logs          # 跟踪节点日志
sudo sh -s -- restart       # 重启服务
sudo sh -s -- rollback      # 回滚到上次自动更新前的版本
sudo sh -s -- print-config  # 只打印将使用的配置，不执行任何动作
sudo sh -s -- uninstall     # 卸载服务（数据目录与二进制保留）

通过管道执行时，子命令要放在 sh -s -- 之后：

bash

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

已下载脚本时直接当参数传：sudo sh install.sh status。

安装脚本会：

从官方清单读取最新版本，按平台/架构下载对应二进制
校验 SHA-256 与版本号
自动获取验签公钥（也可用 --pubkey 显式指定）
安装到 /usr/local/bin/zqagent（或 ~/.local/bin）
装成服务：Linux 用 systemd、macOS 用 launchd

所以一条命令即可，无需再手动找公钥。

带配置安装（端口、数据目录）

bash

curl -fsSLO https://agent.cd-zq.com/install.sh
sudo sh install.sh --port 8787 --data-dir /srv/zqagent

自行指定公钥（可选）

未传 --pubkey 时脚本会从 $BASE_URL/update-public.b64 自动获取。该文件与更新清单同源，所以这套默认信任建立在「站点 HTTPS 与域名未被攻破」之上。要更强的保证，请保存一份带外的公钥并在安装时显式传入：

bash

sudo sh install.sh --pubkey "$(cat /path/to/update-public.b64)"

显式给出的公钥优先，脚本不会再联网覆盖它；格式非法会直接报错退出。

参数	说明	默认
`--port <n>`	监听端口	`8787`
`--host <addr>`	监听地址	`127.0.0.1`
`--data-dir <dir>`	数据目录	Linux `~/.zqagent_data`；macOS `~/Library/Application Support/zqagent`（日志跟随数据目录）
`--pubkey <key>`	自动更新验签公钥	从 `$BASE_URL/update-public.b64` 自动获取
`--service-name <n>`	systemd unit 名	`zqagent`
`--label <name>`	launchd 作业名	`com.zqagent.node`
`--channel <name>`	更新通道	`stable`
`--version <x.y.z>`	指定版本	清单中的最新版
`--no-service`	只装二进制	—

Windows 请使用桌面应用；WSL 内可照上面的 Linux 方式安装。

远程服务器安装

不必先登录服务器，从本机用 SSH 把安装动作推过去即可。服务器上只要有 curl 和 sudo， 不需要 Node/npm——下载的是自带运行时的单文件二进制。

bash

ssh deploy@your-server \
  'curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh'

需要自定义端口、数据目录时，先下载再执行（管道方式无法传参）：

bash

ssh deploy@your-server '
  curl -fsSLO https://agent.cd-zq.com/install.sh &&
  sudo sh install.sh --port 8787 --data-dir /srv/zqagent
'

装好后同样是 install.sh status|logs|restart|rollback 这些子命令，后续升级由节点按清单自动完成（见下节）。

合并前发布的 install-node.sh 地址（/downloads/zqagent/install-node.sh）会继续同步同样内容的副本，已有脚本无需修改；新脚本建议统一用 install.sh。

单文件安装的升级

单文件安装的节点会自动更新：静默下载新版本，等到没有任务在跑时替换自身并重启。详见启动节点 · 自动更新。

想手动检查：

bash

zqagent update --check     # 是否有新版本
zqagent update --status    # 当前版本、通道、上次检查

软件源

@zqagent 系列包发布在公共 npm（https://registry.npmjs.org/），无需注册或申请账号，直接用 npm 默认源即可安装。

若你本机把 npm 默认为国内镜像（如 registry.npmmirror.com），也能正常安装——镜像会在发布后自动同步；两者都不需要为 @zqagent 单独配置作用域。

npm 安装（开发者 / 已在用 Node）

适合需要在开发机上随时用 zqagent 的场景；不受自动更新管理，升级走 npm。

bash

# 使用本机默认源（推荐）
npm i -g @zqagent/core

# 或临时指定公共 npm
npm i -g @zqagent/core --registry=https://registry.npmjs.org/

版本通道

公共 npm 目前只发布稳定版（latest 标签）：

通道	安装命令	说明
稳定版（默认）	`npm i -g @zqagent/core@latest`	每次发版更新 `latest`，适合日常使用

不指定版本时等同于 @latest。早期文档提到的 @dev 测试通道尚未开放， npm i -g @zqagent/core@dev 会报找不到版本，请勿使用。

验证安装

bash

zqagent link --help       # macOS / Linux（已加入 PATH）

bat

.\zqagent-windows-x64-v<版本>-<构建时间>.exe link --help    :: Windows 单文件（未加入 PATH）

随后直接运行 zqagent 进入交互式 CLI，输入 /connect 配置模型即可开始，详见快速开始。

升级与卸载

Windows 单文件

bat

:: 升级：先停止正在运行的 serve，再用新 exe 覆盖旧文件
:: （文件名保持不变，任务计划程序 / 快捷方式无需修改）
copy /Y zqagent-windows-x64.exe "%LOCALAPPDATA%\zqagent\zqagent.exe"

:: 卸载：停止进程后删除 exe 与数据目录
rmdir /S /Q "%LOCALAPPDATA%\zqagent"

单文件安装（install.sh，macOS / Linux）

bash

# 升级：重跑安装脚本即可；已是最新则只报告状态
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

# 卸载服务（数据目录与二进制保留）
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- uninstall

# 彻底清理（Linux；数据默认在运行用户的家目录）
sudo rm -rf ~/.zqagent_data /usr/local/bin/zqagent

# 彻底清理（macOS；普通用户安装时数据目录在 ~/Library/Application Support/zqagent）
sudo rm -rf "/var/root/Library/Application Support/zqagent" /usr/local/bin/zqagent

安装和卸载都可以重复执行：已安装时重跑不会重复下载，只报告当前状态；没装服务时执行 uninstall 也不会报错。卸载后再安装会复用已保留的二进制和数据目录，已接入的 Hub 凭据、模型配置都还在。

npm 安装

bash

# 升级到最新稳定版
npm i -g @zqagent/core@latest

# 卸载
npm uninstall -g @zqagent/core

升级只替换程序本体，不会动你的模型配置与会话数据（配置在 ~/.config/zqagent/，会话与项目数据在各自数据目录，见启动节点）。

常见问题

zqagent: command not found？ 全局 bin 目录不在 PATH 中。查看并加入 PATH：

Windows 单文件则用完整路径或 .\zqagent.exe 运行；加入 PATH 的方法见 Windows 单文件。

bash

npm prefix -g        # 输出 npm 全局前缀，bin 在其中（Windows 为同目录）
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc   # macOS/Linux

安装报 EACCES 权限错误？ 说明 npm 全局目录归 root 所有。不要用 sudo npm i -g，改用版本管理器（nvm/fnm）或把 npm 全局前缀改到用户目录：

bash

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

安装很慢或超时？ 确认能访问 https://registry.npmjs.org/（或你配置的镜像源）；公司内网可配置 HTTP 代理：

bash

npm config set proxy http://<host>:<port>
npm config set https-proxy http://<host>:<port>

换台机器要重新配置吗？~/.npmrc 与 ~/.config/zqagent/ 都在用户目录下，换机器需重新配置软件源；模型 API Key 可用 /connect 重新连接。

下一步

快速开始：连接模型并完成第一个任务
启动节点：把 zqagent 常驻为可远程管理的节点
节点控制台：图形界面管理节点、会话与用量

安装 ​

最快：一行安装（Linux / macOS） ​

macOS 说明 ​

端口被占用时自动换端口 ​

Windows 单文件（免安装 Node） ​

系统要求 ​

子命令：管理已安装的节点 ​

远程服务器安装 ​

单文件安装的升级 ​

软件源 ​

npm 安装（开发者 / 已在用 Node） ​

版本通道 ​

验证安装 ​

升级与卸载 ​

常见问题 ​

下一步 ​

安装

最快：一行安装（Linux / macOS）

macOS 说明

端口被占用时自动换端口

Windows 单文件（免安装 Node）

系统要求

子命令：管理已安装的节点

远程服务器安装

单文件安装的升级

软件源

npm 安装（开发者 / 已在用 Node）

版本通道

验证安装

升级与卸载

常见问题

下一步