第 25 章：命令行与部署

发表于 更新于 分类于 阅读次数：
QwenPaw CLI 命令全景与生产部署方案——Click 框架与 LazyGroup 延迟加载的设计、Docker 容器化构建与运行、Cloudflare 隧道实现内网穿透的完整配置。
个人公众号
1
2
卷四：纵深
[20] 配置 -> [21] 记忆 -> [22] 自治 -> [23] 多智能体 -> [24] 插件 -> [25] CLI与部署 <- you are here

QwenPaw 不只有 Web UI——它有完整的命令行工具和 Docker 部署方案。这一章看 CLI 命令的全景、Cloudflare 隧道、Docker 容器化部署。

CLI 命令全景

qwenpaw 命令（别名 copaw）用 Click 框架实现，LazyGroup 延迟加载子命令：

命令用途
qwenpaw init交互式初始化（配置 Provider、渠道、技能）
qwenpaw app启动 FastAPI 服务（核心命令）
qwenpaw doctor诊断检查（可选 fix 子命令修复）
qwenpaw agents list列出所有 Agent
qwenpaw agents create创建新 Agent
qwenpaw agents chatAgent 间通信
qwenpaw modelsProvider/模型配置
qwenpaw skills技能管理
qwenpaw cron list/run/create定时任务管理
qwenpaw plugin install/list插件管理
qwenpaw acp以 ACP Agent 模式运行（stdio JSON-RPC）
qwenpaw task无头单任务执行
qwenpaw desktop启动桌面 WebView 窗口
qwenpaw mission start/statusMission 模式任务管理
qwenpaw channels list/config频道配置管理
qwenpaw update自更新

qwenpaw app 的选项

1
qwenpaw app --host 0.0.0.0 --port 8088 --reload --log-level info

启动流程：uvicorn.run("qwenpaw.app._app:app", host, port, ...)

qwenpaw init 的流程

交互式引导：

  1. 选择 LLM Provider 并输入 API Key
  2. 选择聊天平台（钉钉/飞书/微信等）
  3. 选择要安装的技能
  4. 写入 config.json

加 --defaults 跳过交互，使用默认配置。

qwenpaw doctor 的检查项

  • Provider 连接是否正常
  • API Key 是否有效
  • 工作区目录是否存在
  • 配置文件格式是否正确
  • 技能是否完整

doctor fix 自动修复发现的问题（保守策略，先备份）。

Cloudflare 隧道——内网穿透

CloudflareTunnelDriver 用 cloudflared 把本地服务暴露到公网：

1
2
3
4
5
6
7
8
9
10
11
async def start(self, local_port: int) -> TunnelInfo:
    # 1. 检查/下载 cloudflared
    binary = await BinaryManager.get_binary_path()
    # 2. 启动隧道进程
    self._proc = await asyncio.create_subprocess_exec(
        binary, "tunnel", "--url", f"http://localhost:{local_port}",
        stderr=asyncio.subprocess.PIPE,
    )
    # 3. 等待公网 URL（30 秒超时）
    url = await self._wait_for_url(timeout=30)
    return TunnelInfo(public_url=url)

BinaryManager 自动下载 cloudflared，支持 macOS/Linux/Windows，SHA256 校验。

安全提醒：Cloudflare 隧道把你的本地服务暴露到了公网。如果你的 QwenPaw 没有启用 Web 认证，任何人都能通过这个公网 URL 访问你的 Agent。启用隧道前务必开启认证：设置 QWENPAW_AUTH_ENABLED=true 并配置用户名和密码。

Docker 部署

多阶段构建

1
2
3
4
5
6
7
8
9
10
11
# Stage 1: 构建前端
FROM node:20 AS console-builder
RUN npm ci && npm run build

# Stage 2: 运行时
FROM agentscope/node:slim
RUN apt-get install python3 chromium xvfb xfce4 supervisor
RUN pip install .
COPY --from=console-builder /console/dist /app/console/dist
RUN qwenpaw init --defaults --accept-security
EXPOSE 8088

Supervisord 管理四个进程

1
2
3
4
dbus      (D-Bus 系统消息)
xvfb      (虚拟显示器，供 Playwright 使用)
xfce4     (桌面环境，供浏览器自动化使用)
app       (qwenpaw app --host 0.0.0.0 --port ${QWENPAW_PORT})

Docker Compose

1
2
3
4
5
6
7
8
9
10
11
12
13
services:
  qwenpaw:
    image: agentscope/qwenpaw:latest
    ports:
      - "127.0.0.1:8088:8088"
    volumes:
      - qwenpaw-data:/app/working
      - qwenpaw-secrets:/app/working.secret
      - qwenpaw-backups:/app/working.backups
    environment:
      - QWENPAW_AUTH_ENABLED=true
      - QWENPAW_AUTH_USERNAME=admin
      - QWENPAW_AUTH_PASSWORD=secret

三个命名卷分别存储数据、密钥、备份。端口绑定到 127.0.0.1——默认只允许本地访问。

备份与恢复

backup/ 模块实现了完整的备份恢复：

创建备份：选定的 Agent 配置、密钥、技能池打包为 ZIP 文件。SSE 进度通知。

恢复备份：两阶段提交——先写入临时目录，验证成功后原子替换。恢复前自动停止受影响的 Agent。

Token 用量统计

TokenUsageManager 记录每次 LLM 调用的 Token 消耗：

1
2
3
4
5
6
7
8
9
10
# 每日按 Provider+Model 汇总
{
  "2026-05-11": {
    "openai:gpt-4o": {
      "prompt_tokens": 15000,
      "completion_tokens": 3000,
      "call_count": 25
    }
  }
}

TokenRecordingModelWrapper 包裹 ChatModel，在每次调用后自动记录用量。

工程权衡

为什么 Docker 里要装 Chromium 和 XFCE？

QwenPaw 的 browser_use 工具用 Playwright 控制浏览器。在容器中没有物理显示器，用 Xvfb 虚拟显示器 + Chromium 运行浏览器自动化。这是 CI/CD 和服务器部署的常见模式。

为什么用 Supervisord 而非 systemd？

Docker 容器通常运行单一进程。但 QwenPaw 需要虚拟显示器（Xvfb）和桌面环境（XFCE4）。Supervisord 管理多个进程比 systemd 更适合容器环境。

自检

  • 知道 qwenpaw app 启动 FastAPI 服务
  • 知道 Cloudflare 隧道提供内网穿透
  • 知道 Docker 部署用 Supervisord 管理四个进程
  • 知道 Token 用量按 Provider+Model 每日汇总

最后一章我们看测试与质量——怎么保证改了这里不会破坏那里。