Ubuntu 22.04 安装 QwenPaw 2.2.2 指南

Ubuntu 22.04 上从零安装 QwenPaw 2.2.2：官方脚本与 pip 双方案、初始化、systemd 托管、升级降级、排障实录与卸载清理，全部命令与回显逐条实测。

QwenPawQwenPaw人工智能2026/10/23

Ubuntu 22.04 安装 QwenPaw 2.2.2 指南

目标：在 Ubuntu 22.04 服务器上从零完成 QwenPaw 2.2.2 的安装、初始化、启动验证与 systemd 托管，并给出 pip 备用方案、升级与降级方法、安装排障实录和卸载清理步骤。全部命令与回显逐条实测于 Ubuntu 22.04.5 LTS 服务器（实测日期 2026-10-22），逐行照抄，未实测的内容明确标注。

一、环境信息

本文实测环境：

项目值来源
操作系统Ubuntu 22.04.5 LTScat /etc/os-release 实测
架构x86_64uname -m 实测
QwenPaw 版本2.2.2.post1（方案 A 官方脚本装出）/ 2.2.2（方案 B pip 精确安装）qwenpaw --version 实测
Python 环境3.12.15（方案 A 由脚本内置 uv 托管；方案 B 为自建 venv）python3.12 --version / qwenpaw doctor 实测
安装目录/root/.qwenpaw（虚拟环境 /root/.qwenpaw/venv，命令包装器 /root/.qwenpaw/bin/qwenpaw）安装脚本输出实测
配置文件/root/.qwenpaw/config.json（由 qwenpaw init 生成）ls 实测
服务端口127.0.0.1:8088（qwenpaw app 默认值）探活实测

系统版本实测回显（cat /etc/os-release 节选前三行）：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"

二、前置条件

  1. 一台 Ubuntu 22.04 服务器，具备 root 或 sudo 权限（本文全程以 root 实测）；
  2. 已安装 curl（下载安装脚本用；apt install curl 可补装）；
  3. 服务器能访问 PyPI 软件源：官方脚本会先探测 pypi.org 连通性（3 秒超时），不通时自动切换阿里云 PyPI 源，无需手动配置（探测逻辑与实测见 9.2 节）；
  4. 默认服务端口 8088 未被占用；如需换端口，启动时用 qwenpaw app --port <端口> 指定（实测 --port 8097 场景横幅正常）；
  5. 若计划用 qwenpaw shutdown 停服务，建议提前 apt install psmisc（该命令依赖 fuser/lsof 定位监听进程，最小化安装两者都没有，排障实录见 9.4 节）。

三、版本选型说明

QwenPaw 通过 PyPI 分发，当前可选版本与两条安装路线的实测对应关系如下：

版本说明获取方式与实测结果
2.2.2最新稳定版（2026-10-15 发布，见《QwenPaw 介绍与选型指南》版本节奏表）pip install qwenpaw==2.2.2，实测装出 QwenPaw, version 2.2.2
2.2.2.post12.2.2 的补丁修订版（PEP 440 的 post-release，版本序排在 2.2.2 之后，属同一功能版本的修复性修订）官方脚本当前装出的版本：bash install.sh 后 qwenpaw --version 实测为 QwenPaw, version 2.2.2.post1
2.2.1上一稳定版（2026-09-10 发布）bash install.sh --version 2.2.1 或 pip install qwenpaw==2.2.1，实测回退成功（见第八章）

关键解读：官方脚本与 pip 精确安装装到的修订号不同（2.2.2.post1 对比 2.2.2），但同属 2.2.2 系列功能版本，日常部署与功能学习无差异；需要严格锁定版本号的场景（如批量部署、配置管理基线）选方案 B 用 == 精确锁版。本文标题按系列统一写作 2.2.2，正文如实标注两条路线各自装出的版本号。

四、方案 A：官方脚本在线安装

4.1 方案说明

这是官方 README 推荐的方式（macOS/Linux 通用）：一条命令的安装脚本自动完成「探测 PyPI 源 → 安装 uv → 创建 Python 3.12 虚拟环境 → 安装 qwenpaw → 生成命令包装器并写入 PATH」全流程，全程不需要手动安装 Python。

💡 技术拓展：「帮用户托管一套独立 Python 环境」的工具不止本文用的 uv，常见选项对比——

工具/方式原理与特点适用场景
uvRust 编写的 Python 包与环境管理器，秒级创建 venv、统一缓存下载脚本自动化安装、追求速度
apt 系统包直接装系统 Python，版本随发行版固定只跑系统自带版本的场景
deadsnakes PPA + venv在 Ubuntu 上补装新版解释器，再手动建 venv需要精确控制解释器来源
pyenv用户态编译多版本 Python，可切换多版本并行开发

本文方案 A 采用脚本内置的 uv：由安装脚本自动下载部署，不污染系统 Python，卸载时随 /root/.qwenpaw/venv 一并移除。

4.2 获取安装脚本

官方 README 给出的一键形态是直接管道执行：

curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash

本文建议先把脚本落盘、确认内容再执行。下载官方站脚本（实测，本文服务器网络环境下该域名不可达，直连报错如下）：

curl -fsSL https://qwenpaw.agentscope.io/install.sh -o install.sh

实测回显：

curl: (35) OpenSSL SSL_connect: Connection reset by peer in connection to qwenpaw.agentscope.io:443

改用 GitHub 仓库直链（脚本在仓库中的源文件路径为 scripts/install.sh），实测下载成功：

curl -fsSL https://raw.githubusercontent.com/agentscope-ai/QwenPaw/main/scripts/install.sh -o install.sh
wc -l install.sh

实测回显：

376 install.sh

⚠️ 注意：若你的服务器同样无法访问 qwenpaw.agentscope.io（该报错为 TLS 连接被重置，另一次实测经代理也复现为 error:0A000126:SSL routines::unexpected eof while reading），直接用上面的 GitHub 直链；需要经代理出网的服务器，为 curl 追加 -x http://代理地址:端口 参数即可。完整排障过程见 9.1 节。

4.3 执行安装

bash install.sh

实测全回显（全新环境首次安装）：

[qwenpaw] Using official PyPI source (network is good)
[qwenpaw] Installing QwenPaw into /root/.qwenpaw
[qwenpaw] Installing uv...
downloading uv 0.13.5 x86_64-unknown-linux-gnu
installing to /root/.local/bin
  uv
  uvx
everything's installed!

To add $HOME/.local/bin to your PATH, either restart your shell or run:

    source $HOME/.local/bin/env (sh, bash, zsh)
    source $HOME/.local/bin/env.fish (fish)
[qwenpaw] uv installed successfully
[qwenpaw] Creating Python 3.12 environment...
[qwenpaw] Python environment ready (Python 3.12.15)
[qwenpaw] Installing qwenpaw from PyPI...
[qwenpaw] QwenPaw installed successfully
[qwenpaw] Wrapper created at /root/.qwenpaw/bin/qwenpaw
[qwenpaw] Updated /root/.bashrc
[qwenpaw] Updated /root/.zshrc

QwenPaw installed successfully!

  Install location:  /root/.qwenpaw
  Python:            Python 3.12.15
  Console (web UI):  available

To get started, open a new terminal or run:

  source ~/.zshrc  # or ~/.bashrc

Then run:

  qwenpaw init       # first-time setup
  qwenpaw app        # start QwenPaw

To upgrade later, re-run this installer.
To uninstall, run: qwenpaw uninstall

逐段解读：

  • 首行 Using official PyPI source (network is good)：脚本探测 pypi.org 3 秒内可达，选用官方源（探测机制见 9.2 节）；
  • Installing uv...：下载 uv 0.13.5 到 /root/.local/bin，这是后续创建 Python 环境的工具；
  • Creating Python 3.12 environment...：uv 创建独立虚拟环境 /root/.qwenpaw/venv，解释器 3.12.15；
  • Wrapper created at /root/.qwenpaw/bin/qwenpaw：生成命令包装器，并把 /root/.qwenpaw/bin 写入 .bashrc/.zshrc 的 PATH；
  • 结尾提示：新开终端（或 source ~/.bashrc）后即可使用 qwenpaw 命令。

4.4 首次初始化

安装完成后需要初始化工作区（生成 config.json 与 HEARTBEAT.md）。先看 init 的参数自述（qwenpaw init --help 实测节选）：

Usage: qwenpaw init [OPTIONS]

  Create working dir with config.json and HEARTBEAT.md (interactive).

Options:
  --force            Overwrite existing config.json and HEARTBEAT.md if
                     present.
  --defaults         Use defaults only, no interactive prompts (for scripts).
  --accept-security  Skip security confirmation (use with --defaults for
                     scripts/Docker).
  -h, --help         Show this message and exit.

--defaults 表示全用默认值不做交互提问，--accept-security 表示跳过安全声明确认（帮助文本自述两者配合用于脚本场景）。在无法应答交互确认的终端里直接执行不带参数的 qwenpaw init 会中断，实测复现与处置见 9.3 节。

执行初始化（实测全回显）：

qwenpaw init --defaults --accept-security

Working dir: /root/.qwenpaw
╭───────────────────── 🐾 Security warning — please read ──────────────────────╮
│ Security warning — please read.                                              │
│                                                                              │
│ QwenPaw is a personal assistant that runs in your own environment. It can    │
│ connect to                                                                   │
│ channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.) and run skills that │
│ read                                                                         │
│ files, run commands, and call external APIs. By default it is a              │
│ single-operator                                                              │
│ boundary: one trusted user. A malicious or confused prompt can lead the      │
│ agent to                                                                     │
│ do unsafe things if tools are enabled.                                       │
│                                                                              │
│ If multiple people can message the same QwenPaw instance with tools enabled, │
│ they                                                                         │
│ share the same delegated authority (files, commands, secrets the agent can   │
│ use).                                                                        │
│                                                                              │
│ If you are not comfortable with access control and hardening, do not run     │
│ QwenPaw with                                                                 │
│ tools or expose it to untrusted users. Get help from someone experienced     │
│ before                                                                       │
│ enabling powerful skills or exposing the bot to the internet.                │
│                                                                              │
│ Recommended baseline:                                                        │
│ - Restrict which channels and users can trigger the agent; use allowlists    │
│ where possible.                                                              │
│ - Multi-user or shared inbox: use separate config/credentials and ideally    │
│ separate                                                                     │
│   OS users or hosts per trust boundary.                                      │
│ - Run skills with least privilege; sandbox where you can.                    │
│ - Keep secrets out of the agent's working directory and skill-accessible     │
│ paths.                                                                       │
│ - Use a capable model when the agent has tools or handles untrusted input.   │
│                                                                              │
│ Review your config and skills regularly; limit tool scope to what you need.  │
╰──────────────────────────────────────────────────────────────────────────────╯
Security acceptance assumed (--accept-security with --defaults).

=== Default Workspace Initialization ===
✓ Default workspace initialized
✓ Builtin QA agent workspace ensured

✓ Configuration saved to /root/.qwenpaw/config.json

✓ LLM already configured: kilo / kilo-auto/free
Skipped LLM configuration.
Syncing pool skills into workspace...
WARNING root/.qwenpaw/venv/lib/python3.12/site-packages/qwenpaw/security/skill_scanner/__init__.py:478 | 2026-10-22 16:59:21 | Skill 'make-skill' has 1 security finding(s) (max severity: CRITICAL) but blocking is disabled – proceeding anyway.
WARNING root/.qwenpaw/venv/lib/python3.12/site-packages/qwenpaw/security/skill_scanner/__init__.py:478 | 2026-10-22 16:59:22 | Skill 'make-skill' has 1 security finding(s) (max severity: CRITICAL) but blocking is disabled – proceeding anyway.
✓ 16 new skill(s) enabled.

Checking MD files [language: zh]...
✓ Copied 8 md file(s): MEMORY.md, AGENTS.md, MAIL_TRIAGE.md, SOUL.md, HEARTBEAT.md, CONTACTS.md, PROFILE.md, BOOTSTRAP.md
✓ Heartbeat query saved to /root/.qwenpaw/HEARTBEAT.md

✓ Initialization complete!

逐段解读：

  • 安全警告横幅：QwenPaw 是运行在自己环境里的个人助手，具备读文件、执行命令、调外部 API 的能力，默认按「单一可信操作者」边界设计；横幅给出准入白名单、最小权限、密钥隔离等基线建议，--accept-security 即代表已读悉；
  • LLM already configured: kilo / kilo-auto/free：默认配置自带 Kilo 免费路由作为初始模型，初始化直接跳过模型配置步骤（换用其他提供方见《QwenPaw 2.2.2 配置参数详解》第三章）；
  • 16 new skill(s) enabled：内置技能池同步 16 个技能到工作区；两条 WARNING 是技能扫描器对 make-skill 技能的检出提示（默认不阻断），属安装回显的一部分，照实保留；
  • 8 个 MD 文件（MEMORY/AGENTS/SOUL/BOOTSTRAP 等）是人格与记忆模板，落盘到工作区。

4.5 安装结果验证

ls /root/.qwenpaw
qwenpaw --version

实测回显：

HEARTBEAT.md
bin
config.json
skill_pool
skill_scanner_blocked.json
venv
workspaces
QwenPaw, version 2.2.2.post1

版本号显示 2.2.2.post1（2.2.2 的补丁修订版），与第三章版本选型说明一致。若 qwenpaw 提示找不到命令，先执行 source ~/.bashrc 或重新登录终端让安装时写入的 PATH 生效。

五、方案 B：pip 手动安装（自管 Python 3.12）

5.1 方案说明

官方 README 给出的另一种方式是 pip 安装：要求 Python 版本 ≥ 3.11 且 < 3.14，适合需要精确锁版（pip install qwenpaw==2.2.2）或已有统一 Python 环境管理的服务器。Ubuntu 22.04 系统源自带的是 Python 3.10，不满足要求，需先通过 deadsnakes PPA 安装 Python 3.12。

5.2 安装 Python 3.12（deadsnakes PPA）

export DEBIAN_FRONTEND=noninteractive
apt-get update -q
apt-get install -y -q software-properties-common
add-apt-repository -y ppa:deadsnakes/ppa
apt-get install -y -q python3.12 python3.12-venv
python3.12 --version

实测回显（节选，保留关键步骤行）：

Adding deb entry to /etc/apt/sources.list.d/deadsnakes-ubuntu-ppa-jammy.list
Adding key to /etc/apt/trusted.gpg.d/deadsnakes-ubuntu-ppa.gpg with fingerprint F23C5A6CF475977595C89F51BA6932366A755776
Setting up python3.12 (3.12.15-1+jammy1) ...
Setting up python3.12-venv (3.12.15-1+jammy1) ...
Python 3.12.15

5.3 创建虚拟环境并安装

python3.12 -m venv /opt/qwenpaw-venv
/opt/qwenpaw-venv/bin/pip install qwenpaw==2.2.2
/opt/qwenpaw-venv/bin/qwenpaw --version

实测回显（pip 依赖解析与下载输出很长，此处为节选——实测采集时另加 --progress-bar off 关闭进度条以便留存文本）：

Building wheels for collected packages: alibabacloud-endpoint-util, alibabacloud-gateway-dingtalk, alibabacloud-tea, proxy_tools
Successfully built alibabacloud-endpoint-util alibabacloud-gateway-dingtalk alibabacloud-tea proxy_tools
Installing collected packages: pyperclip, proxy_tools, mpmath, flatbuffers, filetype, bottle, ast-grep-cli, ...（中段数百个依赖包名略）... agentscope, reme-ai, reme-daily-paper, reme-auto-fin, qwenpaw
Successfully installed MarkupSafe-3.0.4 SecretStorage-3.5.0 agent-client-protocol-0.10.1 agentscope-2.0.10 ...（中段略）... qwenpaw-2.2.2

[notice] A new release of pip is available: 25.0.1 -> 26.2.2
[notice] To update, run: python3.12 -m pip install --upgrade pip
QwenPaw, version 2.2.2

Successfully installed 行末尾可见 qwenpaw-2.2.2——== 精确锁版生效，版本号与方案 A 装出的 2.2.2.post1 区分开（差异说明见第三章）。

5.4 初始化与安装目录说明

pip 路线装完后同样要初始化工作区（命令与回显格式与方案 A 的 4.4 节一致）：

/opt/qwenpaw-venv/bin/qwenpaw init --defaults --accept-security

工作目录规则两条实测结论，直接决定多实例怎么隔离数据：

  • CLI 工作目录跟随 $HOME：实测 HOME=/opt/qwenpaw-home 时执行 init，回显 Working dir: /opt/qwenpaw-home/.qwenpaw，配置落在该目录下；默认 HOME=/root 时就是 /root/.qwenpaw；
  • QWENPAW_HOME 只定位安装目录、不影响工作目录：实测 QWENPAW_HOME=/opt/qw-test-a 配合命令包装器执行时报 Error: QwenPaw environment not found at /opt/qw-test-a/venv（包装器到该目录下找 venv），且 init 的 Working dir 仍是 /root/.qwenpaw。

也就是说方案 B 与方案 A 并存时，给 init 前面加独立 HOME 即可把数据目录隔开。重定向后全新初始化的实测回显（节选，横幅同 4.4 节）：

Working dir: /opt/qwenpaw-home/.qwenpaw
Security acceptance assumed (--accept-security with --defaults).

=== Default Workspace Initialization ===
✓ Default workspace initialized
✓ Builtin QA agent workspace ensured

✓ Configuration saved to /opt/qwenpaw-home/.qwenpaw/config.json

✓ LLM already configured: kilo / kilo-auto/free
Skipped LLM configuration.
Syncing pool skills into workspace...
✓ 16 new skill(s) enabled.

Checking MD files [language: zh]...
✓ Copied 8 md file(s): MEMORY.md, AGENTS.md, MAIL_TRIAGE.md, SOUL.md, HEARTBEAT.md, CONTACTS.md, PROFILE.md, BOOTSTRAP.md
✓ Heartbeat query saved to /opt/qwenpaw-home/.qwenpaw/HEARTBEAT.md

✓ Initialization complete!

初始化后的工作目录内容（实测 ls）：

HEARTBEAT.md
config.json
skill_pool
skill_scanner_blocked.json
workspaces

注意 pip 路线的工作目录里没有 bin/ 与 venv/——命令入口在自建 venv 里，这正是它与方案 A 目录结构的区别。后续把 /opt/qwenpaw-venv/bin/qwenpaw 加入 PATH 或做软链即可当日常命令用；systemd 托管时 ExecStart 直接指向该绝对路径（单元文件模板见 7.3 节，替换其中三处路径即可）。

六、方案对比与选择建议

两条安装路线的实测对照：

维度方案 A：官方脚本方案 B：pip 手动
Python 来源脚本自动下载 uv 并托管 3.12.15自备（deadsnakes 3.12.15）
装出版本2.2.2.post1（当前脚本实测）可精确锁版 ==2.2.2
虚拟环境位置/root/.qwenpaw/venv（固定）自定（本文用 /opt/qwenpaw-venv）
命令包装器与 PATH自动生成并写入 .bashrc/.zshrc手动（用 venv 内绝对路径或自行加 PATH）
升级方式重跑安装脚本（见 8.1 节）pip install -U qwenpaw
卸载方式qwenpaw uninstall（见第十一章）删 venv 目录 + 工作目录
适用场景从零快速上线、不想管 Python严格锁版、复用现有 Python 体系

选择建议：一般服务器与首次部署选方案 A，一条命令拿到全套可用环境；需要版本基线一致、或服务器已有统一的 Python/venv 管理规范时选方案 B。两条路线的数据目录都默认在 $HOME/.qwenpaw（重定向方法见 5.4 节），互不冲突，也可并存。

七、安装后配置与 systemd 托管

7.1 配置文件说明

初始化生成的全部配置集中在 /root/.qwenpaw/config.json（实测生成文件约 32KB），包含渠道（18 个 IM 渠道开关）、模型提供方、安全准入、技能沙箱等所有参数。改完配置执行热重载即可生效，无需重启：

qwenpaw daemon reload-config

实测回显：

**Config reloaded**

- load_config() re-invoked successfully.

各段参数的含义、默认值与改动影响逐项拆解见《QwenPaw 2.2.2 配置参数详解》。

7.2 首次启动与探活验证

先用前台临时方式验证安装成果（生产环境请直接用 7.3 节的 systemd 托管）：

nohup /root/.qwenpaw/bin/qwenpaw app >/root/app.out 2>&1 &

启动成功后进程会在 127.0.0.1:8088 监听，启动横幅（Status: Ready 与 Startup 耗时）同时写进 /root/app.out。探活验证（fuser 属于 psmisc 包，最小化安装先 apt install psmisc，原因见 9.4 节）：

fuser 8088/tcp
ps -p $(fuser 8088/tcp 2>/dev/null | tr -d " ") -o pid,args
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/

实测回显：

8088/tcp:             6720
    PID COMMAND
   6720 /root/.qwenpaw/venv/bin/python /root/.qwenpaw/venv/bin/qwenpaw app
200

三个信号齐全即安装成功：端口被 qwenpaw app 进程监听、HTTP 探活 200。再做一次环境自检：

qwenpaw doctor

实测回显（节选）：

=== Environment ===
  python version: 3.12.15
  qwenpaw version: 2.2.2
  platform: Linux x86_64
  doctor_python_environment: venv (sys.prefix=/root/.qwenpaw/venv)
  qwenpaw_python_environment: venv (sys.prefix=/root/.qwenpaw/venv)
  working_dir: /root/.qwenpaw
  sqlite library: 3.53.1
  disk free (working dir volume): 365.11 GiB

=== Config ===
OK — /root/.qwenpaw/config.json

7.3 systemd 托管（开机自启）

生产环境用 systemd 托管替代前台/nohup 启动。创建单元文件 /etc/systemd/system/qwenpaw.service（内容如下，实测文件全文）：

[Unit]
Description=QwenPaw Personal AI Assistant
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
Environment=PATH=/root/.qwenpaw/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ExecStart=/root/.qwenpaw/venv/bin/qwenpaw app --host 127.0.0.1 --port 8088
WorkingDirectory=/root
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

逐项说明：ExecStart 直接用虚拟环境内的 qwenpaw 入口，绕开包装器对登录 Shell PATH 的依赖；Environment=PATH 一行保证子进程（技能执行的外部命令）能找到常规可执行文件；Restart=on-failure 加 RestartSec=5 让异常退出 5 秒后自动拉起；--host 127.0.0.1 只监听本机，需要局域网访问时改为 0.0.0.0 并配合 config.json 的访问控制收紧（参数见《QwenPaw 2.2.2 配置参数详解》5.3 节）。

启用并启动：

systemctl daemon-reload
systemctl enable --now qwenpaw
systemctl is-active qwenpaw

实测回显：

active

探活与开机自启确认：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/

实测回显：

200

启动横幅会记录在 journal 里（journalctl -u qwenpaw 实测节选）：

│  ├── Address: http://127.0.0.1:8088  │
│  └── Startup: 5.768s                 │

重启验证（systemctl restart qwenpaw 后再查 is-active）：

active

日常运维只需 systemctl start/stop/restart qwenpaw；qwenpaw shutdown 是给前台/nohup 场景用的，systemd 场景不要混用。

八、升级与降级

8.1 升级：重跑安装脚本

方案 A 的升级就是重跑安装脚本（脚本自述 To upgrade later, re-run this installer）。实测在已安装环境重跑 bash install.sh，脚本检测到 uv 已存在直接复用，重建虚拟环境并安装新版本：

[qwenpaw] Using official PyPI source (network is good)
[qwenpaw] Installing QwenPaw into /root/.qwenpaw
[qwenpaw] uv found: /root/.local/bin/uv
[qwenpaw] Creating Python 3.12 environment...
[qwenpaw] Python environment ready (Python 3.12.15)
[qwenpaw] Installing qwenpaw from PyPI...
[qwenpaw] QwenPaw installed successfully
[qwenpaw] Wrapper created at /root/.qwenpaw/bin/qwenpaw
[qwenpaw] Updated /root/.bashrc
[qwenpaw] Updated /root/.zshrc

QwenPaw installed successfully!

  Install location:  /root/.qwenpaw
  Python:            Python 3.12.15
  Console (web UI):  available

方案 B 用 pip install -U qwenpaw 升级；也可以用 CLI 自带的 qwenpaw update（-y 免确认，升级前会先停运行中的服务，参数说明见《QwenPaw 2.2.2 常用 CLI 命令与工具详解》4.11 节）。

8.2 指定版本安装与降级

安装脚本支持 --version 指定版本（bash install.sh --help 实测全文）：

QwenPaw Installer

Usage: bash install.sh [OPTIONS]

Options:
  --version <VER>       Install a specific version (e.g. 0.0.2)
  --from-source [DIR]   Install from source. If DIR is given, use that local
                        directory; otherwise clone from GitHub.
  --extras <EXTRAS>     Comma-separated optional extras to install
                        (e.g. dev, whisper)
  --prerelease          Install the latest PyPI release, including pre-releases
  -h, --help            Show this help

Environment:
  QWENPAW_HOME        Installation directory (default: ~/.qwenpaw)

实际降级也可以直接用 uv 在既有虚拟环境里锁版本安装（比整脚本重跑更快），实测从 2.2.2.post1 降到 2.2.1：

/root/.local/bin/uv pip install --python /root/.qwenpaw/venv/bin/python qwenpaw==2.2.1

实测回显：

Using Python 3.12.15 environment at: /root/.qwenpaw/venv
Resolved 241 packages in 10.14s
Downloading qwenpaw (35.5MiB)
Downloading agentscope (1.1MiB)
 Downloaded agentscope
 Downloaded qwenpaw
Prepared 2 packages in 4m 14s
Uninstalled 2 packages in 241ms
Installed 2 packages in 41ms
 - agentscope==2.0.10
 + agentscope==2.0.7.post1
 - qwenpaw==2.2.2.post1
 + qwenpaw==2.2.1

qwenpaw --version

实测回显：

QwenPaw, version 2.2.1

恢复到原版本同理（实测）：

/root/.local/bin/uv pip install --python /root/.qwenpaw/venv/bin/python qwenpaw==2.2.2.post1
qwenpaw --version

实测回显（节选）：

Resolved 241 packages in 1.63s
Uninstalled 2 packages in 33ms
Installed 2 packages in 42ms
 - agentscope==2.0.7.post1
 + agentscope==2.0.10
 - qwenpaw==2.2.1
 + qwenpaw==2.2.2.post1
QwenPaw, version 2.2.2.post1

⚠️ 注意：降级会连带回退依赖包版本（实测 agentscope 从 2.0.10 回退到 2.0.7.post1），配置文件与数据目录不受影响；恢复升级后依赖同步回到 2.0.10。

九、安装排障实录

9.1 官方站脚本拉取失败：改走 GitHub 直链

现象：按 README 执行 curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash，TLS 握手直接失败。

实测定位：分别验证直连与经代理两条路径（-m 12 限制 12 秒超时）：

curl: (35) OpenSSL SSL_connect: Connection reset by peer in connection to qwenpaw.agentscope.io:443

curl: (35) error:0A000126:SSL routines::unexpected eof while reading

两条路径都在 SSL 层被中断（exit 35），说明是该域名到本服务器链路的问题，与代理无关。

解决：脚本本体就在 GitHub 仓库 scripts/install.sh，改用仓库直链下载后正常执行（实测 376 行完整落盘，见 4.2 节）。需要经代理出网的服务器给 curl 加 -x http://代理地址:端口。

9.2 PyPI 源探测与自动切换

安装脚本首行 [qwenpaw] Using official PyPI source (network is good) 是脚本内置的源探测结果。下载脚本后可读到这段逻辑（install.sh 源码节选，实测文件）：

choose_pypi_mirror() {
    # Test the connectivity of the official PyPI source (timeout 3 seconds, no output)
    if curl -s --connect-timeout 3 https://pypi.org/simple/ > /dev/null 2>&1; then
        echo "https://pypi.org/simple/"
        info "Using official PyPI source (network is good)" >&2
    else
        echo "https://mirrors.aliyun.com/pypi/simple/"
        info "Using Aliyun PyPI mirror (official source is unreachable)" >&2
    fi
}

即：3 秒内 pypi.org 可达就用官方源，否则自动切换阿里云 PyPI 源。国内服务器 pypi.org 直连超时会自动落到阿里云源，无需手动改源；如果脚本卡在这一步很久才继续，说明 pypi.org 到服务器的链路在超时边缘，可考虑自行给服务器配置可用的 PyPI 源后重跑。

9.3 init 交互确认中断：脚本场景必须带参数

现象：在无法交互应答的环境（脚本、无终端输入的会话）直接执行 qwenpaw init，打完安全警告横幅后中断：

Warning: Input is not a terminal (fd=0).

Aborted!

退出码为 1，工作目录里只留下一个空的 .qwenpaw_restore.lock，config.json 并未生成（实测 ls 确认）。

定位：init 默认是交互式流程，安全声明确认是一处必答提问；stdin 拿不到输入时 Click 框架直接 Aborted。

解决：脚本与无人值守场景按官方帮助文本的指引加参数：--defaults 跳过全部交互提问、--accept-security 跳过安全确认（即 4.4 节实测的完整命令）：

qwenpaw init --defaults --accept-security

同类机制也存在于其他交互命令（如 qwenpaw agent delete 缺 --yes 时同样 Aborted），逐条处置见《QwenPaw 2.2.2 常用 CLI 命令与工具详解》第五章。

9.4 shutdown 定位不到进程：装 psmisc

现象：qwenpaw app 明明在跑（curl 探活 200），qwenpaw shutdown 却报 Error: No running QwenPaw backend/frontend process was found.

定位：shutdown 命令依赖 lsof -iTCP:8088 -sTCP:LISTEN 或 fuser 8088/tcp 找监听端口的 PID，最小化安装的 Ubuntu 两个工具都没有，命令返回空集后直接放弃。

解决：

apt install psmisc

装好后 fuser 8088/tcp 即可看到监听 PID（实测回显见 7.2 节），qwenpaw shutdown 也能正常定位进程了。此外它还有一类「报 Failed to stop 但进程实际已停」的僵尸进程误报，完整排障过程见《QwenPaw 2.2.2 常用 CLI 命令与工具详解》4.1 节；systemd 托管场景直接 systemctl stop qwenpaw，不经过这条命令。

十、常见问题（FAQ）

Q1：安装脚本下载失败或卡住？ 先区分两段：脚本本身下载失败看 9.1 节（官方站不可达走 GitHub 直链）；脚本执行中下载依赖慢看 9.2 节（源探测自动切换，无需手动干预）。

Q2：qwenpaw 命令提示找不到？ 安装脚本把 /root/.qwenpaw/bin 写进了 .bashrc/.zshrc，但只对新开的终端生效。当前终端执行 source ~/.bashrc，或直接用绝对路径 /root/.qwenpaw/bin/qwenpaw。

Q3：8088 端口被占用了怎么办？ qwenpaw app --port 8097 换端口启动（实测可用，启动横幅同步显示新端口）；systemd 场景改单元文件 ExecStart 的 --port 后 systemctl daemon-reload && systemctl restart qwenpaw。

Q4：能同时保留方案 A 和方案 B 吗？ 可以。两者虚拟环境分属 /root/.qwenpaw/venv 与自建 venv；工作目录默认同为 $HOME/.qwenpaw，并存时建议给方案 B 的初始化设独立的 HOME（见 5.4 节实测）把数据目录隔开。

Q5：装完之后下一步做什么？ qwenpaw app 起服务后访问 http://127.0.0.1:8088 的 Web Console；模型与渠道配置见《QwenPaw 2.2.2 配置参数详解》，命令行全家桶见《QwenPaw 2.2.2 常用 CLI 命令与工具详解》。

十一、卸载与清理

11.1 保留数据卸载（uninstall --yes）

只移除 Python 环境与命令包装器，配置和数据保留在 /root/.qwenpaw：

qwenpaw uninstall --yes

实测回显：

This will remove the QwenPaw Python environment and CLI wrapper.
Your configuration and data in /root/.qwenpaw will be preserved.
  Removed /root/.qwenpaw/venv
  Removed /root/.qwenpaw/bin
  Cleaned /root/.zshrc
  Cleaned /root/.bashrc

QwenPaw uninstalled. Please restart your terminal.

卸载后目录里剩下的全部是数据（实测 ls -la /root/.qwenpaw）：

total 280
drwxr-xr-x  6 root root   4096 Oct 22 16:56 .
drwx------  1 root root   4096 Oct 22 16:49 ..
-rw-r--r--  1 root root      0 Oct 22 16:02 .qwenpaw_restore.lock
-rw-------  1 root root    154 Oct 22 16:03 .telemetry_collected
-rw-r--r--  1 root root    145 Oct 22 16:03 HEARTBEAT.md
-rw-------  1 root root  32159 Oct 22 16:52 config.json
drwxr-xr-x  3 root root   4096 Oct 22 16:10 governance
-rw-------  1 root root    109 Oct 22 16:05 nm-bridge.json
drwxr-xr-x  6 root root   4096 Oct 22 16:05 plugins
-rw-r--r--  1 root root 199663 Oct 22 16:52 qwenpaw.log
drwxr-xr-x 18 root root   4096 Oct 22 16:34 skill_pool
-rw-r--r--  1 root root   1228 Oct 22 16:03 skill_scanner_blocked.json
-rw-r--r--  1 root root      2 Oct 22 16:50 token_usage.json
drwxr-xr-x  5 root root   4096 Oct 22 16:33 workspaces

保留这份数据再重跑安装脚本，配置与会话都能接上（本文 8.1 节的重装实测即此场景）。

11.2 彻底清除（uninstall --purge --yes）

连配置、会话、工作区一起删除：

qwenpaw uninstall --purge --yes

实测回显：

This will remove ALL QwenPaw data in /root/.qwenpaw
  Removed /root/.qwenpaw/venv
  Removed /root/.qwenpaw/bin
  Removed /root/.qwenpaw
  Cleaned /root/.zshrc
  Cleaned /root/.bashrc

QwenPaw uninstalled. Please restart your terminal.

验证残留：

ls /root/.qwenpaw/

实测回显：

ls: cannot access '/root/.qwenpaw/': No such file or directory

⚠️ 注意：--purge 不可逆，config.json 里的渠道凭据、workspaces 下的会话与记忆数据会全部删除；只换机器/重装系统时用 11.1 节的保留数据模式，先把数据目录备份带走。方案 B 的卸载对应删掉自建 venv 目录与数据目录（$HOME/.qwenpaw，重定向过 HOME 的以实际值为准）。

十二、参考链接

  1. GitHub 仓库：https://github.com/agentscope-ai/QwenPaw （查询日期 2026-10-22）
  2. 官方文档站：https://qwenpaw.agentscope.io/ （查询日期 2026-10-22）
  3. PyPI 项目页：https://pypi.org/project/qwenpaw/ （查询日期 2026-10-22）
  4. 官方安装脚本（仓库直链）：https://raw.githubusercontent.com/agentscope-ai/QwenPaw/main/scripts/install.sh
  5. 本系列同版本篇目：《QwenPaw 介绍与选型指南》、《QwenPaw 2.2.2 配置参数详解》、《QwenPaw 2.2.2 常用 CLI 命令与工具详解》