远程控制概览

把 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 接口。详见服务端配置。