QwenPaw 安装与使用手册

面向个人开发者与技术用户的完整指南版本：v2.x | 最后更新：2026-09-22

[QwenPaw 是什么](#QwenPaw 是什么 "#1-qwenpaw-%E6%98%AF%E4%BB%80%E4%B9%88")
系统与环境要求
安装方式
- 3.1 一键安装脚本（推荐）
- 3.2 pip 安装
- 3.3 Docker 部署
- 3.4 桌面客户端（Beta）
- 3.5 云端一键部署
首次初始化与启动
模型配置
- 5.1 云端模型提供商
- 5.2 阿里云百炼四种计费方案
- 5.3 本地模型（QwenPaw-Flash / Ollama / LM Studio）
- 5.4 高级生成参数
使用界面
- 6.1 Web Console
- 6.2 TUI 命令行
- 6.3 Coding 模式
- 6.4 桌面 App
核心能力
- 7.1 Workspace 文件工作区
- 7.2 Skills 技能
- 7.3 Plugin Market 插件市场
- 7.4 MCP / A2A / ACP 驱动层
- 7.5 Multi-Agent 多智能体
- 7.6 ReMe 长期记忆
- 7.7 IM 通道接入
安全与治理
环境变量与配置文件
升级、卸载与迁移
[故障排查 FAQ](#故障排查 FAQ "#11-%E6%95%85%E9%9A%9C%E6%8E%92%E6%9F%A5-faq")
参考资料

1. QwenPaw 是什么

QwenPaw （原名 CoPaw ）是阿里巴巴 AgentScope 团队开源的个人 AI 智能体工作台，定位是「Works for you, grows with you」------一个可以本地部署、也可以云端运行、随你成长的私人 AI 助理。

它的核心特点：

本地/云端双部署：数据可完全保留在本机，也可托管到 ECS、ModelScope、AgentScope Platform。
模型自由：内置 QwenPaw-Flash 系列本地模型；也支持 DashScope、OpenAI、Anthropic、Google Gemini、DeepSeek、Kimi、OpenRouter 等云端提供商；还能对接 Ollama、LM Studio。
Agent OS 架构（v2.0+）：Workspace（沙箱工作区）、Drivers（协议中立的 MCP / A2A / ACP 连接器）、Loop Engineering（可复用的智能体循环模板）、Scroll Context（长会话上下文回溯）、ReMe Memory（结构化 Markdown 长期记忆）。
可扩展性：Skills 技能、Plugin Market 插件市场、MCP 工具、定时任务、自定义工作流。
多端接入：Web Console、TUI、桌面 App、DingTalk、Lark、WeChat、Discord、Telegram、iMessage、QQ。
内建安全：Kernel-level Sandbox、Tool Guard、File Guard、Skill Scanner、Access Policy，支持 allow / deny / ask / sandbox 四种治理动作。

典型使用场景：定时新闻简报、代码阅读/修改/评审、PDF/Word/Excel/PPT 文档处理、Web 搜索与订阅、多渠道告警、AI 生成内容分发等。

2. 系统与环境要求

安装方式	关键依赖	说明
一键脚本	联网环境	脚本自动下载 `uv`、创建虚拟环境、安装 QwenPaw 及前端资源
pip	Python ≥ 3.11, < 3.14（阿里云文档标注 3.10--3.13 亦可）	建议先自行创建 venv/conda 环境
Docker	Docker Engine + 本地端口 `8088` 空闲	官方镜像 `agentscope/qwenpaw`
桌面 App	Windows 10+ / macOS 14+	Beta 版本，首次启动可能需要 10--60 秒
云一键	阿里云 ECS / AgentScope Platform / ModelScope 账号	ModelScope 空间务必设为「非公开」

硬件建议：

CPU：x86_64 或 arm64（Apple Silicon 原生支持）
内存：≥ 4GB（跑本地 QwenPaw-Flash 9B Q4 建议 ≥ 16GB）
磁盘：≥ 5GB 空闲（含镜像与依赖）

3. 安装方式

3.1 一键安装脚本（推荐）

脚本会自动完成：下载 uv → 创建独立虚拟环境 → 安装 QwenPaw 主程序 → 下载 Node/前端资源。

macOS / Linux

bash 复制代码

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

Windows CMD

cmd 复制代码

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

Windows PowerShell

powershell 复制代码

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

指定版本 / 从源码安装

bash 复制代码

# 指定版本
curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash -s -- --version 1.1.0

# 从源码构建
curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash -s -- --from-source

powershell 复制代码

# PowerShell 指定版本
.\install.ps1 -Version 1.1.12
# PowerShell 从源码
.\install.ps1 -FromSource

安装完成后 重开终端，执行：

bash 复制代码

qwenpaw init --defaults
qwenpaw app

浏览器打开 http://127.0.0.1:8088/ 即可进入 Console。

3.2 pip 安装

适合已有 Python 环境管理的开发者。

bash 复制代码

# 建议使用独立虚拟环境
python -m venv .venv && source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate                             # Windows

pip install -U pip
pip install qwenpaw
qwenpaw init --defaults
qwenpaw app

Python 版本必须落在 >= 3.11, < 3.14 区间；若使用 conda，请 conda create -n qwenpaw python=3.12。

3.3 Docker 部署

拉取镜像

bash 复制代码

# Docker Hub（境外/全球）
docker pull agentscope/qwenpaw:latest
# 或预览版
docker pull agentscope/qwenpaw:pre

# 阿里云 ACR（中国大陆加速）
docker pull agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw:latest

启动容器

bash 复制代码

docker run -d --name qwenpaw \
  -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

三个卷的作用：

Volume	挂载点	用途
`qwenpaw-data`	`/app/working`	工作区文件（Workspace）
`qwenpaw-secrets`	`/app/working.secret`	加密的密钥、凭据
`qwenpaw-backups`	`/app/working.backups`	自动备份

注入环境变量 / 密钥

bash 复制代码

docker run -d --name qwenpaw \
  -p 127.0.0.1:8088:8088 \
  -e DASHSCOPE_API_KEY=sk-xxxxxxxx \
  -e TAVILY_API_KEY=tvly-xxxxxxxx \
  --env-file ./.env \
  -v qwenpaw-data:/app/working \
  -v qwenpaw-secrets:/app/working.secret \
  -v qwenpaw-backups:/app/working.backups \
  agentscope/qwenpaw:latest

容器访问宿主机模型服务（Ollama / LM Studio）

bash 复制代码

docker run -d --name qwenpaw \
  --add-host=host.docker.internal:host-gateway \
  -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

然后在模型设置里填：

Ollama：host.docker.internal:11434
LM Studio：host.docker.internal:1234/v1

Linux 主机网络（可选）

bash 复制代码

docker run -d --name qwenpaw --network=host \
  -v qwenpaw-data:/app/working \
  -v qwenpaw-secrets:/app/working.secret \
  -v qwenpaw-backups:/app/working.backups \
  agentscope/qwenpaw:latest

3.4 桌面客户端（Beta）

到官方下载页获取安装包：

Windows：QwenPaw-Tauri-<version>-Windows-setup.exe
macOS：QwenPaw-Tauri-<version>-macOS.zip

要求 Windows 10+ 或 macOS 14+。首次冷启动 10--60 秒属正常现象。

macOS 若被 Gatekeeper 拦截：

右键 App → Open，或
到「系统设置 → 隐私与安全性」点击「仍要打开」，或
命令行去除隔离属性：

bash 复制代码

xattr -cr "/Applications/QwenPaw Desktop.app"

3.5 云端一键部署

阿里云 ECS 一键部署：在 QwenPaw 官方页面点「Deploy on ECS」，选好规格即可自动完成安装与开机自启。
AgentScope Platform：登录控制台一键创建实例，适合团队共享。
ModelScope Space ：把 Space 可见性设置为 「非公开」，否则任何人都能远程操作你的实例。

4. 首次初始化与启动

交互式初始化（推荐第一次使用）

bash 复制代码

qwenpaw init

按向导依次选择：语言、默认模型提供商、API Key、Workspace 目录、是否启用 Web 搜索等。

跳过向导使用默认值

bash 复制代码

qwenpaw init --defaults

启动 Web Console

bash 复制代码

qwenpaw app
# 打开 http://127.0.0.1:8088/

启动 TUI 交互模式

bash 复制代码

qwenpaw

恢复历史会话

bash 复制代码

qwenpaw tui --resume <session-id>

进入 Coding 模式（在当前仓库工作）

bash 复制代码

cd /path/to/your/repo
qwenpaw .

5. 模型配置

启动后打开 http://127.0.0.1:8088/ → Settings → Models，选择 Provider、填入 API Key、启用模型即可。

5.1 云端模型提供商

内置支持：

DashScope（阿里云百炼）
OpenAI（含 Azure OpenAI 兼容端点）
Anthropic Claude
Google Gemini
DeepSeek
Moonshot Kimi
OpenRouter

5.2 阿里云百炼四种计费方案

QwenPaw 与阿里云百炼深度集成，支持以下四种计费方案的 API Key（四种 Key 不通用，务必与 Base URL 匹配）：

计费方案	Provider 名称	API Key 来源
Token Plan 个人版	`Aliyun Token Plan`	Token Plan 个人版控制台
Token Plan 团队版	`Aliyun Token Plan`	Token Plan 团队版控制台
Coding Plan	`Aliyun Coding Plan (China)`	Coding Plan 控制台
按量付费	`DashScope`	百炼 API-KEY

按量付费 Base URL（需替换 {WorkspaceId}）

text 复制代码

# 华北2（北京）
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

# 新加坡
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1

# 美国（弗吉尼亚）
https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1

设置默认模型 ：Settings → Models → Default LLM 选择后 Save。也可以在对话页右上角临时切换 Provider/Model。

5.3 本地模型

选项	说明
QwenPaw Local	内置的 QwenPaw-Flash 系列，无需 API Key，开箱即用
Ollama	需本机运行 Ollama 服务；建议模型上下文 ≥ 32k
LM Studio	需启动 Local Server；OpenAI 兼容协议

QwenPaw-Flash 提供 2B / 4B / 9B 三种规模，各有 Q4 / Q8 量化版本，可按内存/显存选择。

5.4 高级生成参数

长会话或复杂工具调用触发上下文限制时，进入 Provider Settings → Advanced Configuration，用 JSON 覆写：

json 复制代码

{
  "temperature": 0.7,
  "top_p": 0.9,
  "max_tokens": 4096
}

按需要调低 max_tokens、temperature，或提高 top_p，保存后立即生效。

6. 使用界面

6.1 Web Console

浏览器打开 http://127.0.0.1:8088/，主要模块：

Chat：与智能体对话，可切换 Provider/Model、附加文件、开启工具。
Workspace：文件浏览、编辑、预览、Diff、上传/下载。
Skills / Plugins / MCP：安装、启用、配置扩展能力。
Agents：管理多智能体，查看子代理运行状态。
Memory (ReMe)：查看和编辑结构化 Markdown 记忆。
Schedules：定时任务编排。
Settings：模型、密钥、治理策略、外观主题等。

6.2 TUI 命令行

bash 复制代码

qwenpaw           # 直接进入 TUI
qwenpaw tui --resume <session-id>

常用斜杠命令：

命令	作用
`/help`	帮助
`/resume`	列出并恢复历史会话
`/theme`	切换配色主题
`/model`	切换当前会话使用的模型
`/clear`	清空当前上下文

6.3 Coding 模式

在任意代码仓库根目录执行：

bash 复制代码

qwenpaw .

QwenPaw 会以该目录作为 Workspace，读取 git 信息、按需生成 diff、跑测试，并结合 Tool Guard 阻止高风险命令。适合代码阅读、重构、评审、写单测。

6.4 桌面 App

Beta 阶段，功能与 Web Console 基本对齐，好处是常驻托盘、系统级快捷键、原生通知。

7. 核心能力

7.1 Workspace 文件工作区

每个 Agent 拥有独立 Workspace，包含资源、治理策略、沙箱边界。你可以：

直接在 Web 里浏览、编辑、Diff、上传下载文件；
通过 File Guard 限制可访问的路径；
通过 Access Policy 决定「允许 / 拒绝 / 询问 / 沙箱化」四类操作。

7.2 Skills 技能

Skills 是 QwenPaw 的能力单元，覆盖：

定时任务与调度
文档处理（PDF、Word、Excel、PPT）
浏览器自动化
新闻资讯与订阅
邮件、日历、通讯录（可对接 DingTalk / Lark）
更多社区技能

在 Skills 页面搜索、一键安装；也可以本地开发后打包上传。

7.3 Plugin Market 插件市场

v2.2.0 起，Plugin 与 Oh-My-Paw 统一到同一个 Marketplace。插件比 Skill 更重，可以包含前后端逻辑，适合封装完整业务流程。

7.4 MCP / A2A / ACP 驱动层

Drivers 是协议中立的连接器层：

MCP（Model Context Protocol）：接入外部工具/数据源，如 GitHub、Slack、数据库、内网系统。
A2A：Agent 之间的点对点通信。
ACP（Agent Communication Protocol）：跨系统的智能体编排协议。

凭据加密存储于 /app/working.secret，每次调用都会经过 Access Policy 检查。

7.5 Multi-Agent 多智能体

独立 Agent：可创建多个具备各自记忆、技能、Workspace 的智能体。
Runtime Subagent：主 Agent 在运行时按需 fork 子代理，处理并行子任务。
ACP 编排：跨机器/跨系统的多 Agent 协同。

7.6 ReMe 长期记忆

ReMe 会把对话与资源自动整理为可编辑的 Markdown 知识库：

Active Context（当前上下文）
Complete History（完整历史）
Personal Knowledge（个人知识）

被驱逐的上下文可通过 Scroll Context 召回，避免"失忆"。

7.7 IM 通道接入

原生支持将 QwenPaw 桥接到：DingTalk、Lark（飞书）、WeChat、Discord、Telegram、iMessage、QQ。配置方式：Settings → Channels，填入对应机器人 Token/Webhook 即可。

8. 安全与治理

QwenPaw 内建五道防线：

| 组件 | 作用 |
|--------------------------|-------------------------------------------|---------|
| Kernel-level Sandbox | 内核级隔离，容器/进程双保险 |
| Tool Guard | 拦截高风险工具调用（如 rm -rf /、`curl | bash`） |
| File Guard | 限制可读写的路径范围 |
| Skill Scanner | 安装/加载 Skill 时静态扫描可疑代码 |
| Access Policy | 对每次动作执行 allow / deny / ask / sandbox 策略 |

生产部署建议：

Web 端口只绑 127.0.0.1，通过 SSH 隧道或反向代理 + 认证暴露。
Docker 卷独立命名，定期备份 qwenpaw-secrets 与 qwenpaw-backups。
ModelScope Space 一定设为「非公开」。
生产密钥走 --env-file 或 Secret Manager，不写死在镜像里。

9. 环境变量与配置文件

常用环境变量：

变量	用途
`DASHSCOPE_API_KEY`	阿里云百炼 API Key
`TAVILY_API_KEY`	Web 搜索（Tavily）Key
`OPENAI_API_KEY`	OpenAI 兼容端点 Key
`ANTHROPIC_API_KEY`	Anthropic Claude Key
`HTTP_PROXY` / `HTTPS_PROXY`	代理设置

设置方式（三选一）：

bash 复制代码

# 1. shell 环境
export DASHSCOPE_API_KEY=sk-xxxxxxxx

# 2. .env 文件（放在启动目录）
echo "DASHSCOPE_API_KEY=sk-xxxxxxxx" >> .env

# 3. Docker
docker run --env-file .env ...

配置文件位置：

macOS/Linux：~/.qwenpaw/
Windows：%USERPROFILE%\.qwenpaw\
Docker：容器内 /app/working、/app/working.secret

10. 升级、卸载与迁移

升级

bash 复制代码

# 脚本安装的用户
curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash -s -- --version <new-version>

# pip 安装的用户
pip install -U qwenpaw

# Docker
docker pull agentscope/qwenpaw:latest
docker stop qwenpaw && docker rm qwenpaw
# 用原来的 run 命令重启，卷数据会自动继承

卸载

bash 复制代码

qwenpaw uninstall           # 卸载程序，保留数据
qwenpaw uninstall --purge   # 卸载并清空 ~/.qwenpaw

迁移

将以下三个目录/卷整体拷贝到新机器即可：

~/.qwenpaw/working（或 Docker qwenpaw-data 卷）
~/.qwenpaw/working.secret
~/.qwenpaw/working.backups

11. 故障排查 FAQ

11.1 Windows：`'uv' is not recognized ...`

一键脚本装完但 PATH 没生效，多见于 LTSC 或受限环境。

处理步骤：

Win+R → sysdm.cpl → 高级 → 环境变量。
在用户变量 Path 追加：
- %USERPROFILE%\.local\bin
- %USERPROFILE%\AppData\Local\uv
- %USERPROFILE%\.qwenpaw\bin
重开终端执行 uv --version 验证。

若 PowerShell 被执行策略拦住，可以：

powershell 复制代码

# 方式 A：手动装 uv
python -m pip install -U uv

# 方式 B：从 GitHub Release 下载 uv 二进制
# https://github.com/astral-sh/uv/releases

再把 uv 与 QwenPaw bin 目录加入 PATH，重跑安装脚本。

11.2 macOS：App 打不开，提示"来自身份不明的开发者"

bash 复制代码

xattr -cr "/Applications/QwenPaw Desktop.app"

或者右键 → Open；也可以到「隐私与安全性」点击「仍要打开」。

11.3 Docker 容器无法访问宿主机 Ollama / LM Studio

原因：容器里的 localhost 指向容器自身。

解决：

bash 复制代码

docker run --add-host=host.docker.internal:host-gateway ...

然后模型 Base URL 填 http://host.docker.internal:11434（Ollama）或 http://host.docker.internal:1234/v1（LM Studio）。Linux 也可以直接 --network=host。

11.4 `401 Incorrect API key provided`

三种常见原因：

Key 与计费方案不匹配 ：Token Plan / Coding Plan / 按量付费三种 Key 不能互换。
Key 与 Region 不匹配：按量付费时，Key 属于哪个地域，Base URL 就必须是那个地域。
Key 前后带空格或换行：复制粘贴时留意。

11.5 长对话/多工具调用报「上下文超限」

进入 Provider Settings → Advanced Configuration，降低 max_tokens、缩短系统提示，或切换到上下文更大的模型（例如 Qwen3-Max-Long、Claude Sonnet 4.5 等）。

11.6 ModelScope Space 被陌生人操作

立即把 Space 可见性改为「非公开」，并重置 API Key。

11.7 端口 8088 被占用

bash 复制代码

# macOS/Linux
lsof -i :8088
# Windows
netstat -ano | findstr :8088

释放端口，或用环境变量指定新端口后再 qwenpaw app。

11.8 pip 安装报 Python 版本不兼容

QwenPaw 要求 >= 3.11, < 3.14。使用 pyenv/conda 切换：

bash 复制代码

conda create -n qwenpaw python=3.12 -y
conda activate qwenpaw
pip install qwenpaw

12. 参考资料

官方文档站：qwenpaw.agentscope.io/docs/
快速上手：qwenpaw.agentscope.io/docs/quicks...
GitHub 仓库（含中文 README）：github.com/agentscope-...
阿里云百炼集成指南：help.aliyun.com/zh/model-st...
一键脚本入口：
- macOS/Linux：qwenpaw.agentscope.io/install.sh
- Windows CMD：qwenpaw.agentscope.io/install.bat
- Windows PowerShell：qwenpaw.agentscope.io/install.ps1
Docker Hub：hub.docker.com/r/agentscop...
中国大陆镜像：agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw

本手册基于 QwenPaw v2.x 公开文档整理；具体命令与界面可能随版本更新略有差异，请以官方文档为准。

QwenPaw 安装与使用手册