安裝

zqagent 有兩種安裝形態：命令列工具（CLI） 與 桌面應用。本頁講解 CLI 的安裝、升級與解除安裝。

不想用命令列？直接看桌面應用，下載安裝包即可圖形化使用。

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

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 註冊的電子電子郵件/手機號與密碼即可， 密碼不會回顯。自動化場景可在安裝命令裡直接帶上賬號（密碼建議用環境變數傳入）：

# 隱藏輸入密碼（不回顯、不進 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 -- 傳入）：

# 換埠 / 監聽地址 / 資料目錄
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 支援版本。

1. 下載與架構匹配的產物（目標機不需要 Node/npm）：

   架構	適用	下載
   x64	絕大多數 Windows	zqagent-windows-x64

   檔名帶版本號與構建時間；連結隨站點構建自動指向當前釋出版本。完整清單見 https://agent.cd-zq.com/downloads/zqagent/stable.json（binaries.windows-x64.url）。 Windows ARM64 目前沒有產物，請使用 x64 版本（Windows 會以模擬方式執行）。

2. 放到任意目錄（例如 %LOCALAPPDATA%\zqagent\），開啟 PowerShell 或 cmd 執行：

   .\zqagent-windows-x64-v<版本>-<構建時間>.exe

   首次啟動後輸入 /connect 設定模型即可使用。

3. 想直接敲 zqagent：把該目錄加入使用者 PATH（「系統屬性 → 環境變數」）， 並把檔案重新命名為 zqagent.exe。命令列方式（setx 對超長 PATH 會截斷）：

   setx PATH "%PATH%;%LOCALAPPDATA%\zqagent"

常駐為可遠端管理的節點：

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）：

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 -- 之後：

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

已下載指令碼時直接當引數傳：sudo sh install.sh status。

安裝指令碼會：

1. 從官方清單讀取最新版本，按平臺/架構下載對應二進位制
2. 校驗 SHA-256 與版本號
3. 自動獲取驗籤公鑰（也可用 --pubkey 顯式指定）
4. 安裝到 /usr/local/bin/zqagent（或 ~/.local/bin）
5. 裝成服務：Linux 用 systemd、macOS 用 launchd

所以一條命令即可，無需再手動找公鑰。

帶設定安裝（埠、資料目錄）

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 與域名未被攻破」之上。要更強的保證，請儲存一份帶外的 公鑰並在安裝時顯式傳入：

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——下載的是自帶執行時的單檔案二進位制。

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

需要自定義埠、資料目錄時，先下載再執行（管道方式無法傳參）：

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。

單檔案安裝的升級

單檔案安裝的節點會自動更新：靜默下載新版本，等到沒有任務在跑時替換自身並重啟。 詳見啟動節點 · 自動更新。

想手動檢查：

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

軟體源

@zqagent 系列包釋出在公共 npm（https://registry.npmjs.org/），無需註冊或申請賬號，直接用 npm 預設源即可安裝。

若你本機把 npm 預設為國內映象（如 registry.npmmirror.com），也能正常安裝——映象會在釋出後自動同步；兩者都不需要為 @zqagent 單獨設定作用域。

npm 安裝（開發者 / 已在用 Node）

適合需要在開發機上隨時用 zqagent 的場景；不受自動更新管理，升級走 npm。

# 使用本機預設源（推薦）
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 會報找不到版本，請勿使用。

驗證安裝

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

.\zqagent-windows-x64-v<版本>-<構建時間>.exe link --help    :: Windows 單檔案（未加入 PATH）

隨後直接執行 zqagent 進入互動式 CLI，輸入 /connect 設定模型即可開始， 詳見快速開始。

升級與解除安裝

Windows 單檔案

:: 升級：先停止正在執行的 serve，再用新 exe 覆蓋舊檔案
:: （檔名保持不變，任務計劃程式 / 快捷方式無需修改）
copy /Y zqagent-windows-x64.exe "%LOCALAPPDATA%\zqagent\zqagent.exe"

:: 解除安裝：停止程序後刪除 exe 與資料目錄
rmdir /S /Q "%LOCALAPPDATA%\zqagent"

單檔案安裝（install.sh，macOS / Linux）

# 升級：重跑安裝指令碼即可；已是最新則只報告狀態
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 安裝

# 升級到最新穩定版
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 單檔案。

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 全域性字首改到使用者目錄：

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

安裝很慢或超時？ 確認能訪問 https://registry.npmjs.org/（或你設定的映象源）；公司內網可設定 HTTP 代理：

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

換臺機器要重新設定嗎？~/.npmrc 與 ~/.config/zqagent/ 都在使用者目錄下，換機器需重新設定軟體源； 模型 API Key 可用 /connect 重新連線。

下一步

• 快速開始：連線模型並完成第一個任務
• 啟動節點：把 zqagent 常駐為可遠端管理的節點
• 節點控制台：圖形介面管理節點、會話與用量