本节介绍多种方式安装 QwenPaw：

📖 阅读前请先了解 项目介绍，完成安装与启动后可查看 控制台。

💡 安装并启动后的关键步骤：

1. 在浏览器访问 控制台（http://127.0.0.1:8088/）

2. 配置模型（必需）：设置 → 模型 → 配置 API Key 或下载本地模型

3. 开始对话测试

4. （可选）配置频道以在钉钉、飞书、QQ 等 app 里对话，详见 频道配置

方式一：pip 安装

如果你更习惯自行管理 Python 环境（需 Python >= 3.10, < 3.14）：

pip install qwenpaw

可选：先创建并激活虚拟环境再安装（python -m venv .venv，Linux/macOS 下 source .venv/bin/activate，Windows 下 .venv\Scripts\Activate.ps1）。安装后会提供 qwenpaw 命令。

然后按下方 步骤二：初始化 和 步骤三：启动服务 操作。

步骤二：初始化

在工作目录（默认 ~/.qwenpaw）下生成 config.json 与 HEARTBEAT.md。两种方式：

• 快速用默认配置（不交互，适合先跑起来再改配置）：

  复制

  qwenpaw init --defaults

• 交互式初始化（按提示填写心跳间隔、投递目标、活跃时段，并可顺带配置频道与 Skills）：

  复制

  qwenpaw init

  详见 CLI - 快速上手。

若已有配置想覆盖，可使用 qwenpaw init --force（会提示确认）。 初始化后若尚未启用频道，接入钉钉、飞书、QQ 等需在 频道配置 中按文档填写。

步骤三：启动服务

qwenpaw app

服务默认监听 127.0.0.1:8088。若已配置频道，QwenPaw 会在对应 app 内回复；若尚未配置，也可先完成本节再前往频道配置。

方式二：脚本安装

无需预装 Python — 安装脚本通过 uv 自动管理一切。

步骤一：安装

macOS / Linux：

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

然后打开新终端（或执行 source ~/.zshrc / source ~/.bashrc）。

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

然后打开新终端（安装脚本会自动将 QwenPaw 加入 PATH）。

⚠️ Windows 企业版 LTSC 用户特别提示

如果您使用的是 Windows LTSC 或受严格安全策略管控的企业环境，PowerShell 可能运行在 受限语言模式 下，可能会遇到以下问题：

1. 如果你使用的是 CMD（.bat）：脚本执行成功但无法写入Path

   脚本已完成文件安装，由于 受限语言模式 ，脚本无法自动写入环境变量，此时只需手动配置：

• 按 Win + R，输入 sysdm.cpl 并回车，打开"系统属性"。

• 点击 "高级" -> "环境变量"。

• 在 "系统变量" 中找到并选中 Path，点击 "编辑"。

• 点击 "新建"，依次填入上述两个目录路径，点击确定保存。

• 检查 uv 是否可用：在 CMD 中输入 uv --version ，如果显示版本号，则只需配置 QwenPaw 路径；如果提示 'uv' 不是内部或外部命令，也不是可运行的程序或批处理文件。，则需同时配置两者。

• uv路径（任选其一，取决于安装位置，若uv不可用则填）：通常在%USERPROFILE%\.local\bin、%USERPROFILE%\AppData\Local\uv或 Python 安装目录下的 Scripts 文件夹

• QwenPaw路径：通常在 %USERPROFILE%\.qwenpaw\bin 。

• 找到安装目录：

• 手动添加到系统的 Path 环境变量：

2. 如果你使用的是 PowerShell（.ps1）：脚本运行中断

由于 受限语言模式 ，脚本可能无法自动下载uv。

• 手动安装uv：参考 GitHub Release下载并将uv.exe放至%USERPROFILE%\.local\bin或%USERPROFILE%\AppData\Local\uv；或者确保已安装 Python ，然后运行python -m pip install -U uv

• 配置uv环境变量：将uv所在目录和 %USERPROFILE%\.qwenpaw\bin 添加到系统的 Path 变量中。

• 重新运行：打开新终端，再次执行安装脚本以完成 QwenPaw 安装。

• 配置QwenPaw环境变量：将 %USERPROFILE%\.qwenpaw\bin 添加到系统的 Path 变量中。

也可以指定选项：

macOS / Linux：

# 安装指定版本curl -fsSL ... | bash -s -- --version 1.1.0# 从源码安装（开发/测试用）curl -fsSL ... | bash -s -- --from-source

Windows（PowerShell）：

# 安装指定版本
.\install.ps1 -Version 0.0.2

# 从源码安装（开发/测试用）
.\install.ps1 -FromSource

升级只需重新运行安装命令。卸载请运行 qwenpaw uninstall。

步骤二：初始化

在工作目录（默认 ~/.qwenpaw）下生成 config.json 与 HEARTBEAT.md。两种方式：

• 快速用默认配置（不交互，适合先跑起来再改配置）：

  复制

  qwenpaw init --defaults

• 交互式初始化（按提示填写心跳间隔、投递目标、活跃时段，并可顺带配置频道与 Skills）：

  复制

  qwenpaw init

  详见 CLI - 快速上手。

若已有配置想覆盖，可使用 qwenpaw init --force（会提示确认）。 初始化后若尚未启用频道，接入钉钉、飞书、QQ 等需在 频道配置 中按文档填写。

步骤三：启动服务

qwenpaw app

服务默认监听 127.0.0.1:8088。若已配置频道，QwenPaw 会在对应 app 内回复；若尚未配置，也可先完成本节再前往频道配置。

方式三：Docker

镜像在 Docker Hub（agentscope/qwenpaw）。镜像 tag：latest（稳定版）；pre（PyPI 预发布版）。国内用户也可选用阿里云 ACR：agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw（tag 相同）。

拉取并运行：

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

然后在浏览器打开 http://127.0.0.1:8088/ 进入控制台。配置、记忆与 Skills 保存在 qwenpaw-data 卷中；模型配置与 API Key 保存在 qwenpaw-secrets 卷中；备份归档保存在 qwenpaw-backups 卷中。传入 API Key 可在 docker run 时加 -e DASHSCOPE_API_KEY=xxx 或 --env-file .env。

方式四：部署到阿里云 ECS

若希望将 QwenPaw 部署在阿里云上，可使用阿里云 ECS 一键部署：

1. 打开 QwenPaw 阿里云 ECS 部署链接，按页面提示填写部署参数；

2. 参数配置完成后确认费用并创建实例，部署完成后即可获取访问地址并使用服务。

详细步骤与说明请参考 阿里云开发者社区：QwenPaw 3 分钟部署你的 AI 助理。

方式五：魔搭创空间一键配置（无需安装）

若不想在本地安装 Python，可通过魔搭创空间将 QwenPaw 部署到云端运行：

1. 先前往 魔搭 注册并登录；

2. 打开 QwenPaw 创空间，一键配置即可使用。

重要：使用创空间请将空间设为 非公开，否则你的 QwenPaw 可能被他人操纵。

方式六：桌面应用

如果你不习惯使用命令行，可以下载并使用 QwenPaw 的桌面应用版本，无需手动配置 Python 环境或执行命令。

特点

• ✅ 零配置：下载后双击即可运行，无需安装 Python 或配置环境变量

• ✅ 跨平台：支持 Windows 10+ 和 macOS 14+ (推荐 Apple Silicon)

• ✅ 可视化：自动打开浏览器界面，无需手动输入地址

下载与使用

1. 下载安装包 前往 GitHub Releases 下载对应系统的版本：

• Windows: QwenPaw-Setup-<version>.exe

• macOS: QwenPaw-<version>-macOS.zip

2. 安装并启动

• Windows: 双击 .exe 文件按向导安装，完成后双击桌面快捷方式启动

• macOS: 解压 .zip 得到 QwenPaw.app，首次需右键选择"打开"以绕过系统安全限制

3. 首次启动提示 首次启动可能需要 10-60 秒（取决于系统配置），应用需要初始化 Python 环境和加载依赖，请耐心等待浏览器窗口自动打开。

完整使用指南

桌面应用涉及系统权限、安全提示、调试模式等细节，请查看 桌面应用完整指南 了解：

• Windows 两种启动模式（普通版 vs Debug 版）

• macOS 如何解除系统安全限制（3种方法）

• 常见问题与解决方案

• 日志查看与问题报告

验证安装（可选）

服务启动后,可通过 HTTP 调用 Agent 接口以确认环境正常。接口为 POST /api/agent/process,请求体为 JSON,支持 SSE 流式响应。单轮请求示例:

curl -N -X POST "http://localhost:8088/api/agent/process" \
  -H "Content-Type: application/json" \
  -d '{"input":[{"role":"user","content":[{"type":"text","text":"你好"}]}],"session_id":"session123"}'

同一 session_id 可进行多轮对话。

接下来做什么？

必要步骤

✅ 1. 配置模型（必需）

QwenPaw 需要大语言模型才能工作。你可以选择以下任一方式：

选项 A：使用云端模型（需要 API Key）

1. 在控制台进入 设置 → 模型

2. 选择一个提供商（如 DashScope、ModelScope 等）

3. 点击 设置 按钮，输入你的 API Key

4. 点击 保存

5. 在顶部 默认 LLM 中选择该提供商和具体模型

6. 点击 保存

详见 模型 - 配置云提供商。

选项 B：使用本地模型（无需 API Key，完全离线）

1. 安装本地模型后端：

• QwenPaw Local（llama.cpp）：在 QwenPaw Local 提供商设置中下载 llama.cpp，详见 模型 - 配置本地提供商。

• Ollama：从 Ollama 官网 安装 Ollama，并启动 Ollama 服务。

• LM Studio：从 LM Studio 官网 安装 LM Studio，并启动 LM Studio 服务。

2. 下载模型：

• 对于 QwenPaw Local（llama.cpp），你可以直接在控制台的提供商设置中下载模型，或者手动将 GGUF 模型文件放到本地模型目录中（默认 ~/.qwenpaw/local_models/models/<org>/<model>，例如 ~/.qwenpaw/local_models/models/Qwen/Qwen3-0.6B-GGUF）。

• 对于 Ollama 和 LM Studio，需要先在各自服务中添加模型，之后 QwenPaw 才能自动获取模型列表并连接。

3. 在控制台选择本地提供商和模型

配置好本地模型后，你可以在控制台的 默认 LLM 设置中选择它，也可以直接在 聊天 页面中切换使用。

🎯 2. 在控制台测试对话

模型配置完成后，在控制台的 聊天 页面发送消息测试功能，确认 QwenPaw 可以正常回复。

可选扩展

配置模型并测试成功后，可以根据需要进行以下扩展：

📱 接入消息频道

在钉钉、飞书、QQ、Discord、iMessage 等 app 里与 QwenPaw 对话：

1. 在控制台进入 控制 → 频道

2. 选择要接入的频道

3. 按照 频道配置 文档获取凭据并填写

4. 保存后即可在对应 app 中发消息给 QwenPaw

🔧 启用和扩展技能

赋予 QwenPaw 更多能力（PDF 处理、Office 文档、新闻摘要等）：

• 在控制台进入 智能体 → 技能池 或 智能体 → 技能

• 导入内置技能、从 Skill Hub 导入、或创建自定义技能

• 详见 Skills

🔌 接入 MCP 工具

通过 MCP（Model Context Protocol）扩展外部工具能力：

• 在控制台进入 智能体 → MCP

• 创建 MCP 客户端，连接外部工具服务器

• 详见 MCP

⏰ 设置定时任务与心跳

让 QwenPaw 自动执行任务：

• 定时任务：在控制台 控制 → 定时任务 中创建，或使用 CLI 的 qwenpaw cron 命令

• 心跳：配置定时自检或摘要，详见 心跳

👥 创建多智能体

创建多个专用助手，各司其职或互相协作：

• 在控制台 设置 → 智能体管理 中创建新智能体

• 每个智能体拥有独立的配置、记忆、技能和对话历史

• 启用协作技能让智能体间可以互相通信

• 详见 多智能体

📂 调整工作目录

如需更改配置文件或工作目录的位置，详见 配置与工作目录。

QwenPaw Desktop 桌面应用版使用指南

⚠️ Beta 版本说明

桌面应用目前处于 Beta 测试阶段，存在以下已知限制：

• 兼容性测试不完整：未在所有系统版本和硬件配置上进行充分测试

• 性能可能存在缺陷：启动速度、内存占用等方面可能需要进一步优化

• 更新方式存在缺陷：目前暂时需要卸载后重新下载才能完成版本更新

• 功能持续完善中：部分功能可能不稳定或缺失

欢迎反馈问题，帮助我们改进产品质量。

下载地址：GitHub Releases

本文档说明如何在 Windows 和 macOS 系统上安装和使用 QwenPaw Desktop 桌面应用。

特别说明

首次启动可能需要较长时间（10-60秒不等，甚至可能更长），具体取决于您的系统配置。 应用需要初始化 Python 环境、加载依赖库和启动 Web 服务，请耐心等待窗口出现。后续启动会更快。

目录

• Windows 使用指南

• macOS 使用指南

• 技术支持

Windows 使用指南

系统要求

• 操作系统: Windows 10 或更高版本

• 架构: x64 (64位)

安装步骤

1. 下载安装包 从 Release 页面下载 QwenPaw-Setup-<version>.exe 文件

2. 运行安装程序 双击 .exe 文件，按照安装向导提示完成安装

• 默认安装位置：C:\Users\<你的用户名>\AppData\Local\QwenPaw

• 安装完成后会在桌面和开始菜单创建快捷方式

启动方式

安装完成后，您会看到两个启动快捷方式：

QwenPaw Desktop (推荐日常使用)

• 特点: 静默启动，无终端窗口，界面简洁

• 适用场景: 正常使用，不需要查看技术日志

• 启动方式: 双击桌面或开始菜单的 "QwenPaw Desktop" 图标

• 技术说明: 使用 VBScript 启动器，后台运行 Python 进程

QwenPaw Desktop (Debug) (调试模式)

• 特点: 显示终端窗口，实时输出运行日志

• 适用场景:

• 遇到问题需要查看错误信息

• 开发测试

• 报告 Bug 时需要提供日志

• 启动方式: 双击开始菜单的 "QwenPaw Desktop (Debug)" 图标

• 日志内容:

• 应用启动信息

• Python 错误堆栈

• API 调用日志

• 按 Ctrl+C 或关闭窗口可停止应用

常见问题

Q: 应用启动后窗口白屏，无法正常显示？

A: 这通常是因为系统缺少 Microsoft WebView2 运行时（部分 Windows 10 系统未预装）。 请前往微软官网下载并安装： Microsoft WebView2 安装完成后重启应用即可。

Q: 应用启动后没有反应？

A: 使用 "QwenPaw Desktop (Debug)" 模式启动，查看终端输出的错误信息

Q: 如何卸载？

A: 在 Windows 设置 → 应用 → 已安装的应用 → 找到 "QwenPaw Desktop" → 卸载

Q: 安装包是否安全？

A: 应用未经过 Microsoft 代码签名（成本 $200-800/年），Windows Defender SmartScreen 会显示警告 这是正常现象，点击 "更多信息" → "仍要运行" 即可 代码完全开源，构建过程在 GitHub Actions 上透明可查

macOS 使用指南

系统要求

• 操作系统: macOS 14 (Sonoma) 或更高版本

• 架构:

• ✅ Apple Silicon (M1/M2/M3/M4) - 推荐

• ⚠️ Intel 芯片 - 可能可以运行，但可能无法使用内置的本地模型服务

安装步骤

1. 下载压缩包 从 Release 页面下载 QwenPaw-<version>-macOS.zip 文件

2. 解压缩 双击 .zip 文件自动解压，得到 QwenPaw.app 应用

3. 移动到应用程序文件夹 (可选) 将 QwenPaw.app 拖到 /Applications 文件夹

首次启动：解除系统安全限制

为什么需要手动信任？

QwenPaw 应用未经过 Apple 开发者签名和公证（Notarization），macOS Gatekeeper 会默认阻止运行。

为什么没有签名？

• 📋 开发者签名需要额外成本和流程，后续版本会补上

当前影响：

• ✅ 不影响功能：应用完全正常运行

• ⚠️ 首次需手动信任：一次操作后永久有效

• 🔒 安全性：开源代码可审计，构建过程透明（CI/CD）

如何解除限制？

方法 1：右键打开 (推荐)

1. 右键点击（或 Control + 点击）QwenPaw.app

2. 在菜单中选择 "打开"

3. 在弹出的对话框中，再次点击 "打开" 按钮

4. ✅ 之后双击即可正常启动，不会再弹窗

方法 2：系统设置解除拦截

如果仍被拦截：

1. 打开 系统设置 → 隐私与安全性

2. 向下滚动，找到类似以下提示： "已阻止使用 'QwenPaw'，因为无法验证开发者"

3. 点击 "仍要打开" 或 "允许" 按钮

4. 输入管理员密码确认

方法 3：终端命令解除隔离

# 移除下载隔离属性xattr -cr /Applications/QwenPaw.app

⚠️ 注意: 此方法会完全移除安全检查，仅当您完全信任应用来源时使用。

🔍 权限请求

首次启动时，macOS 可能会弹窗请求以下权限：

• 桌面文件访问权限 用于访问您的文件（如果使用文件相关功能）

• 点击 "允许" 以正常使用

• 点击 "不允许" 应用仍可运行，但部分功能受限

启动方式

正常启动（双击）

• 双击 QwenPaw.app 即可启动

• 应用会在后台运行，打开浏览器窗口

• 日志输出到：~/.qwenpaw/desktop.log

终端启动（查看实时日志）

如果应用崩溃或需要查看详细日志：

# 切换到应用目录cd /Applications  # 或您的 QwenPaw.app 所在目录# 设置环境变量并启动（隔离打包环境，避免冲突）APP_ENV="$(pwd)/QwenPaw.app/Contents/Resources/env"PYTHONNOUSERSITE=1 PYTHONPATH= PYTHONHOME="$APP_ENV" "$APP_ENV/bin/python" -m qwenpaw desktop

终端启动的优势：

• ✅ 实时查看所有日志输出

• ✅ 看到完整的 Python 错误堆栈

• ✅ 便于调试和报告问题

• ✅ 可添加 --log-level debug 查看更详细信息

查看日志文件：

# 查看最近的启动日志tail -f ~/.qwenpaw/desktop.log

常见问题

Q: 双击后没有任何反应？

A: 请尝试以下步骤：

1. 检查 ~/.qwenpaw/desktop.log 文件查看错误

2. 使用上述终端命令启动，查看实时输出

Q: 提示"Apple 无法验证此应用"？

A: 按照上述"解除系统安全限制"步骤操作

Q: 如何卸载？

A: 将 QwenPaw.app 拖到废纸篓，然后删除 ~/.qwenpaw 配置文件夹

Q: Intel Mac 可以用吗？ A: 可以运行，但可能无法使用内置的本地模型服务

Q: 应用为什么没有签名，为什么系统会提示有风险？

A: 当前采用

• ✅ 开源透明：所有代码和构建流程公开在 GitHub

• ✅ CI/CD 可验证：GitHub Actions 自动构建，日志可查

• ✅ 用户审计：可以自行检查代码并本地构建

• ✅ 一次信任：手动信任后永久有效

技术支持

• GitHub Issues: 提交问题

• 打包文档: scripts/pack/README.md - 技术细节和本地构建指南

• 日志位置:

• Windows: Debug 模式终端查看，或 %USERPROFILE%\.qwenpaw\ 目录

• macOS: ~/.qwenpaw/desktop.log

使用建议

Windows 用户

• 日常使用: 使用普通版（无终端窗口）

• 遇到问题: 切换到 Debug 版查看日志

macOS 用户

• 首次安装: 务必按照"解除安全限制"步骤操作

• 调试问题: 使用终端启动方式查看实时日志

• 权限问题: 首次启动时请允许文件访问权限