遠端控制概覽

把 zqagent 跑在你的電腦或伺服器上，然後從手機或 QQ 遠端派任務： AI 在服務端執行，進度、審核請求和結果會即時回傳到你手上。適合不想守在電腦前、或想隨時讓 AI 幫你處理事情的場景。

使用官方雲端（推薦）

不想自己搭建 broker？直接使用已部署的雲端：

在目標裝置上執行一條命令接入（按載體任選其一，憑據會自動落盤，免手工搬運）：

已有節點（熱接入，免重啟）

bash

zqagent link --hub https://hub.cd-zq.com --code <接入碼>

啟動即接入（原始碼 / 裸機）

bash

HUB_URL=https://hub.cd-zq.com HUB_ENROLL_CODE=<接入碼> pnpm run server

Docker

bash

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

桌面應用：控制台頂欄「接入雲端」，貼上 Hub 地址 + 接入碼。

憑據自動寫入 {DATA_DIR}/fleet.json，後續重啟無需再帶接入碼；節點上線後即可在使用者中心或節點控制台（瀏覽器 / 手機）檢視狀態、專案與事件，並能完成提交任務、審核、中斷等完整會話操作。

節點只需出站連線閘道器（wss://，通常走 443），無需公網入站、無需開放埠。

接入碼一次性、短時有效；同一節點 ID 不會被其他節點管理重複納管（防搶注）。
自建 Hub 時，下發給節點的閘道器地址由 Hub 側的 HUB_GATEWAY_URL 決定。

只裝了 CLI 的機器（無需原始碼）也能常駐為可納管的節點：

bash

zqagent serve                                                      # 僅本機使用
zqagent serve --hub https://hub.cd-zq.com --enroll-code <接入碼>    # 啟動即接入

後臺常駐（nohup / pm2 / systemd）、資料目錄與線上驗證等，見啟動節點。

在專案目錄下啟動服務（原始碼方式，等價於已安裝 CLI 的 zqagent serve）：

bash

pnpm run server   # 預設埠 8787，首次啟動自動建立演示租戶 demo（apiKey 隨機生成並列印在日誌中）

啟動日誌會列印演示租戶資訊：

zqagent server 監聽 http://localhost:8787
資料目錄: ./data
已建立演示租戶: id=demo apiKey=zk_xxxx（隨機生成） model=gpt-4o-mini

詳細設定見服務端設定。

結論：服務端本體不需要公網 IP。 所有「遠端互動」都走出站連線，通過第三方中轉完成：

能力	服務端動作	中轉方	需要公網入站？
遠端控制	連閘道器（出站 wss）	公網 Rust 閘道器	否
QQ 機器人	連騰訊閘道器（出站）	騰訊 QQ 開放平臺	否
電子郵件 / Bark / Server醬 / Webhook 通知	主動 POST（出站）	SMTP / 各推送服務	否

只有一種情況需要公網（或內網穿透）：你想讓外部直接訪問 REST 介面。詳見服務端設定。