QwenPaw 安装完成的标志，不是终端里出现了几行绿色日志，而是浏览器能打开本地控制台，初始化向导能保存配置，并且你发出的第一条消息确实经过已选模型返回。按这个验收标准部署，排错会比“装完再说”简单。

先选安装路线

路线	适合情况	要留意的事
pip	熟悉 Python，想直接管理环境	Python 需要大于等于 3.11 且低于 3.14
官方脚本	希望少处理 Python 和前端依赖	受网络、权限和企业终端策略影响
Docker	准备放到服务器或想隔离运行环境	必须挂载数据、密钥和备份卷

初次体验可用官方脚本；已有 Python 环境可用 pip；长期运行或多人共享机器，Docker 更容易把数据边界说清楚。不要同时用三种路线安装到同一个目录，否则排查命令到底调用了哪个版本会很麻烦。

路线一：pip 安装

1. 确认 Python 版本在 3.11 到 3.13 范围内，并准备一个独立虚拟环境。
2. 安装 QwenPaw：

   pip install qwenpaw

3. 初始化工作区：

   qwenpaw init
   qwenpaw app

4. 浏览器打开 http://127.0.0.1:8088/，在“设置 → 模型”中选择提供商并保存。

若只想先生成默认配置，也能使用 qwenpaw init --defaults。失败场景：命令提示找不到 qwenpaw，多数时候是虚拟环境没有激活，或 Python 的 Scripts 目录没有加入 Path，不是程序本身一定没装上。

路线二：官方脚本

macOS 或 Linux 可执行：

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

Windows CMD 可执行：

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

Windows PowerShell 可执行：

irm https://qwenpaw.agentscope.io/install.ps1 | iex

脚本会尝试准备 uv、虚拟环境、QwenPaw 及相关依赖。安装后打开新终端，再运行 qwenpaw init --defaults 和 qwenpaw app。失败场景：Windows LTSC 的受限语言模式可能阻止脚本写 Path 或下载 uv，此时要手动安装 uv，并把 uv 所在目录和 %USERPROFILE%.qwenpawbin 加入 Path。

路线三：Docker 部署

docker pull agentscope/qwenpaw:latest
docker run -p 127.0.0.1:8088:8088 
  -v qwenpaw-data:/app/working 
  -v qwenpaw-secrets:/app/working.secret 
  -v qwenpaw-backups:/app/working.backups 
  agentscope/qwenpaw:latest

其中，数据卷保存配置、记忆和 Skills，密钥卷保存模型提供商设置与 API Key，备份卷保存导出的归档。失败场景：只映射端口、不挂载卷，容器重建后可能发现记忆和备份都回到了初始状态。

最后做一次四项验收

• 能打开本地控制台，且地址是本机的 8088 端口。
• 模型页面显示已启用的提供商和模型。
• 新建一条短对话，确认能收到响应。
• 检查工作区、密钥和备份是否落在预期位置。

若使用 Ollama 或 LM Studio，先让对应服务运行，再回到 QwenPaw 选择本地提供商；若使用云端模型，则需要填入有效 API Key。安装成功只是起点，模型连接和数据持久化才决定部署是否真的可用。