560 lines
36 KiB
Markdown
560 lines
36 KiB
Markdown
<div align="center">
|
||
|
||
# QwenPaw
|
||
|
||
[](https://github.com/agentscope-ai/QwenPaw)
|
||
[](https://pypi.org/project/qwenpaw/)
|
||
[](https://qwenpaw.agentscope.io/)
|
||
[](https://www.python.org/downloads/)
|
||
[](https://github.com/agentscope-ai/QwenPaw)
|
||
[](LICENSE)
|
||
[](https://github.com/psf/black)
|
||
[](https://github.com/agentscope-ai/QwenPaw/stargazers)
|
||
[](https://github.com/agentscope-ai/QwenPaw/network)
|
||
[](https://deepwiki.com/agentscope-ai/QwenPaw)
|
||
[](https://discord.gg/eYMpfnkG8h)
|
||
[](https://x.com/agentscope_ai)
|
||
[](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)
|
||
[](https://platform.agentscope.io/)
|
||
|
||
<a href="https://trendshift.io/repositories/25882" target="_blank"><img src="https://trendshift.io/api/badge/trendshift/repositories/25882/daily" alt="agentscope-ai%2FQwenPaw | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
|
||
|
||
[[文档](https://qwenpaw.agentscope.io/)] [[English](README.md)] [[日本語](README_ja.md)] [[Русский](README_ru.md)]
|
||
|
||
<p align="center">
|
||
<img src="https://gw.alicdn.com/imgextra/i1/O1CN01sens5C1TuwioeGexL_!!6000000002443-55-tps-771-132.svg" alt="QwenPaw Logo" width="120">
|
||
</p>
|
||
|
||
<p align="center"><b>懂你所需，伴你左右。</b></p>
|
||
|
||
</div>
|
||
|
||
你的个人 AI 助理 — 本地或云端部署，通过 Skills 与插件扩展能力，全频道连接。
|
||
|
||
| | |
|
||
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| **不遗忘对话** | 三层记忆 — 实时工作上下文、完整逐字历史，以及由 [ReMe](https://github.com/agentscope-ai/ReMe) 驱动的自进化个人知识库。对话与资料持续沉淀为可读、可编辑、可检索、相互链接的 Markdown 记忆。 |
|
||
| **本地云端，自由运行** | QwenPaw-Flash 模型（2B / 4B / 9B）面向 Agent 场景专项训练。内置 QwenPaw Local 运行时，无需 API Key、不依赖云端。同时支持 Ollama、LM Studio 及 14+ 云端模型供应商。 |
|
||
| **安全机制** | 内核级 Sandbox、Tool Guard、File Guard 与 Skill Scanner。危险命令在执行前即被拦截。 |
|
||
| **多智能体与并行** | 创建拥有独立记忆与技能的 Agent；运行时生成子 Agent；通过 Agent Communication Protocol（ACP）实现跨系统编排。 |
|
||
| **代码模式** | 三面板 Web IDE，含文件树、Diff 预览与对话区。内置跳转定义、查找引用与结构化代码搜索。 |
|
||
| **能力扩展** | Skills 覆盖定时任务、文档、浏览器、新闻等。插件架构带 Plugin Market。MCP 集成外部工具。自由组合成面向场景的工作流。 |
|
||
| **随处可达** | 钉钉、飞书、微信、Discord、Telegram、iMessage、QQ — 一个实例，全频道连接。Console、TUI 与桌面应用可直接访问。 |
|
||
| **你的，不是我们的** | 本地部署，数据留在你的机器，无第三方托管，无数据上传。 |
|
||
|
||
<details>
|
||
<summary><b>你可以用 QwenPaw 做什么</b></summary>
|
||
|
||
<br>
|
||
|
||
- **自动化与定时任务**：设置定时任务 — 新闻摘要、报告生成、多频道广播 — 全部按你的时间表自动运行。
|
||
- **代码与开发**：在项目中阅读、编辑、审查与测试代码；Coding 模式帮你快速定位和理解代码。
|
||
- **文档处理**：读取、写入与转换 PDF、Word、Excel、PowerPoint 文件。
|
||
- **信息收集**：搜索网页、关注资讯订阅、总结视频内容，并从个人知识库中检索所需信息。
|
||
- **多频道运营**：向钉钉、飞书、Discord、Telegram 等推送告警、摘要或 AI 生成内容 — 可同时或按频道分发。
|
||
- **自定义工作流**：把内置能力、插件和定时任务组合起来，打造适合你的专属流程。
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
## 新闻
|
||
|
||
- [2026-07-24] **v2.0.1** | PawApp 小程序平台、用户可编辑 Agent Mode、Oh-My-Paw plugins、[ReMe](https://github.com/agentscope-ai/ReMe) 记忆增强、桌面端用户体验增强等。[v2.0.1 发布说明 →](https://qwenpaw.agentscope.io/release-notes#v2.0.1)
|
||
|
||
- [2026-07-10] **v2.0.0 — QwenPaw 2.0 正式发布** 🎉 | 基于 AgentScope 2.0 全面重构，带来 Agent OS 架构、Loop Engineering、Scroll 上下文、[ReMe](https://github.com/agentscope-ai/ReMe) v0.4 自进化个人知识库与内置终端界面。
|
||
|
||
| 亮点 | 更新内容 |
|
||
|------|----------|
|
||
| **Agent OS — 工作区** | 每个智能体三大支柱：**资源**（透明落盘）、**治理**（allow/deny/ask/sandbox）、**沙箱**（macOS / Linux / Windows）。 |
|
||
| **Agent OS — 驱动** | 协议中立的 MCP / A2A / ACP 连接器层，带加密凭据与逐次调用策略门控。 |
|
||
| **Loop Engineering** | 高级智能体循环模板（Coding Mode、Mission Mode，更多模板持续推出），配合可组合审批门控。 |
|
||
| **Scroll 上下文** | 每一轮都持久化；滚出窗口的轮次带索引，按需回放——不摘要、不丢失。 |
|
||
| **[ReMe](https://github.com/agentscope-ai/ReMe) v0.4 自进化个人知识库** | 持续将对话与资料转化为可读、可编辑、可检索、相互链接的 Markdown 记忆。 |
|
||
| **终端界面（TUI）** | 全屏终端对话——与控制台和频道共享同一智能体、记忆与会话。 |
|
||
|
||
基于 Agent OS，我们将陆续推出开箱即用的 QwenPaw 应用小程序——如 **QwenPaw Creator**、**QwenPaw Insight** 等，敬请期待。 [v2.0.0 发布说明 →](https://qwenpaw.agentscope.io/release-notes#v2.0.0)
|
||
|
||
- [2026-06-17] **v1.1.12 — 模型页面大改版 & 简洁模式** | 全新模型页面 Provider 聚合设计；新增简洁模式，扁平化导航。[v1.1.12 发布说明 →](https://qwenpaw.agentscope.io/release-notes#v1.1.12)
|
||
|
||
- [2026-06-11] **AgentScope 体验平台上线** — 支持免费部署 QwenPaw、插件分享与 Skill 市场。[立即体验 →](https://platform.agentscope.io/)
|
||
|
||
- [2026-06-10] **v1.1.11** — 免费模型 OAuth、插件市场、MCP 工具白名单。[v1.1.11 发布说明 →](https://qwenpaw.agentscope.io/release-notes#v1.1.11)
|
||
|
||
[全部发布说明 →](https://qwenpaw.agentscope.io/release-notes)
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [新闻](#新闻)
|
||
- [快速开始](#快速开始)
|
||
- [API Key](#api-key)
|
||
- [本地模型](#本地模型)
|
||
- [安全特性](#安全特性)
|
||
- [文档](#文档)
|
||
- [常见问题](#常见问题)
|
||
- [路线图](#路线图)
|
||
- [参与贡献](#参与贡献)
|
||
- [从源码安装](#从源码安装)
|
||
- [为什么叫 QwenPaw？](#为什么叫-qwenpaw)
|
||
- [由谁构建](#由谁构建)
|
||
- [许可证](#许可证)
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 方式一：pip 安装
|
||
|
||
如果你习惯自行管理 Python 环境（需 Python >= 3.11, < 3.14）：
|
||
|
||
```bash
|
||
pip install qwenpaw
|
||
qwenpaw init --defaults
|
||
qwenpaw app
|
||
```
|
||
|
||
然后在浏览器中打开控制台 **http://127.0.0.1:8088/** 配置模型。若要在钉钉、飞书、微信等 app 内对话，请参考 [频道配置](https://qwenpaw.agentscope.io/docs/channels) 文档。
|
||
|
||
|
||
|
||
---
|
||
|
||
### 方式二：脚本安装
|
||
|
||
无需手动配置 Python，一行命令自动完成安装。脚本会自动下载 uv（Python 包管理器）、创建虚拟环境、安装 QwenPaw 及其依赖（含 Node.js 和前端资源）。注意：部分网络环境或企业权限管控下可能无法使用。
|
||
|
||
**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
|
||
```
|
||
|
||
> **注意**：安装程序将自动检查 uv 状态，若未安装则尝试自动下载配置。如遇自动安装失败，请遵循屏幕提示操作，或执行 `python -m pip install -U uv`，然后重新运行安装程序。
|
||
|
||
> **⚠️ Windows 企业版 LTSC 用户特别提示**
|
||
>
|
||
> 如果您使用的是 Windows LTSC 或受严格安全策略管控的企业环境，PowerShell 可能运行在 **受限语言模式** 下，可能会遇到以下问题：
|
||
> 1. **如果你使用的是 CMD（.bat）：脚本执行成功但无法写入 `Path`**
|
||
>
|
||
> 脚本已完成文件安装，由于 **受限语言模式**，脚本无法自动更新环境变量，此时只需手动配置：
|
||
> - **找到安装目录**：
|
||
> - 检查 `uv` 是否可用：在 CMD 中输入 `uv --version`，如果显示版本号，则**只需配置 QwenPaw 路径**；如果提示 `'uv' is not recognized as an internal or external command, operable program or batch file,`，则需同时配置两者。
|
||
> - uv 路径（任选其一，取决于安装位置，若 `uv` 不可用则填）：通常在 `%USERPROFILE%\.local\bin`、`%USERPROFILE%\AppData\Local\uv` 或 Python 安装目录下的 `Scripts` 文件夹
|
||
> - QwenPaw 路径：通常在 `%USERPROFILE%\.qwenpaw\bin`。
|
||
> - **手动添加到系统的 Path 环境变量**：
|
||
> - 按 `Win + R`，输入 `sysdm.cpl` 并回车，打开「系统属性」。
|
||
> - 点击「高级」→「环境变量」。
|
||
> - 在「系统变量」中找到并选中 `Path`，点击「编辑」。
|
||
> - 点击「新建」，依次填入上述两个目录路径，点击确定保存。
|
||
> 2. **如果你使用的是 PowerShell（.ps1）：脚本运行中断**
|
||
>
|
||
> 由于 **受限语言模式**，脚本可能无法自动下载 `uv`。
|
||
> - **手动安装 uv**：参考 [GitHub Release](https://github.com/astral-sh/uv/releases) 下载并将 `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` 变量中。
|
||
|
||
安装完成后，请打开新终端并运行：
|
||
|
||
```bash
|
||
qwenpaw init --defaults # 或：qwenpaw init（交互式）
|
||
qwenpaw app
|
||
```
|
||
|
||
<details>
|
||
<summary><b>安装选项</b></summary>
|
||
|
||
**macOS / Linux：**
|
||
|
||
```bash
|
||
# 安装指定版本
|
||
curl -fsSL ... | bash -s -- --version 1.1.0
|
||
|
||
# 从源码安装（开发/测试用）
|
||
curl -fsSL ... | bash -s -- --from-source
|
||
|
||
# 升级 — 重新运行安装命令即可
|
||
curl -fsSL ... | bash
|
||
|
||
# 卸载
|
||
qwenpaw uninstall # 保留配置和数据
|
||
qwenpaw uninstall --purge # 删除所有内容
|
||
```
|
||
|
||
**Windows（PowerShell）：**
|
||
|
||
```powershell
|
||
# 安装指定版本
|
||
irm ... | iex; .\install.ps1 -Version 1.1.12
|
||
|
||
# 从源码安装（开发/测试用）
|
||
.\install.ps1 -FromSource
|
||
|
||
# 升级 — 重新运行安装命令即可
|
||
irm ... | iex
|
||
|
||
# 卸载
|
||
qwenpaw uninstall # 保留配置和数据
|
||
qwenpaw uninstall --purge # 删除所有内容
|
||
```
|
||
|
||
</details>
|
||
|
||
|
||
---
|
||
|
||
### 方式三：使用 Docker
|
||
|
||
镜像在 **Docker Hub**（`agentscope/qwenpaw`）。镜像 tag：`latest`（稳定版）；`pre`（PyPI 预发布版）。
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
国内用户也可选用阿里云容器镜像服务 (ACR)：`agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw`（tag 相同）。
|
||
|
||
然后在浏览器中打开 **http://127.0.0.1:8088/** 进入控制台。配置、记忆与 Skills 保存在 `qwenpaw-data` 卷中；模型提供商设置与 API Key 保存在 `qwenpaw-secrets` 卷中；备份归档保存在 `qwenpaw-backups` 卷中。如需传入 API Key（如 `DASHSCOPE_API_KEY`），在 `docker run` 时添加 `-e VAR=value` 或 `--env-file .env`。
|
||
|
||
> **从容器内连接宿主机上的 Ollama 或其他模型服务**
|
||
>
|
||
> Docker 容器内的 `localhost` 指向容器自身，而非宿主机。如果 Ollama（或其他模型服务）运行在宿主机上，可通过以下方式让容器内的 QwenPaw 访问：
|
||
>
|
||
> **方式 A** — 显式绑定宿主机地址（全平台通用）：
|
||
> ```bash
|
||
> docker run -p 127.0.0.1:8088:8088 \
|
||
> --add-host=host.docker.internal:host-gateway \
|
||
> -v qwenpaw-data:/app/working \
|
||
> -v qwenpaw-secrets:/app/working.secret \
|
||
> -v qwenpaw-backups:/app/working.backups \
|
||
> agentscope/qwenpaw:latest
|
||
> ```
|
||
> 然后在 QwenPaw **设置 → 模型** 中，将 Base URL 改为 `http://host.docker.internal:<端口>` — 例如 Ollama 填 `http://host.docker.internal:11434`，LM Studio 填 `http://host.docker.internal:1234/v1`。
|
||
>
|
||
> **方式 B** — 使用宿主机网络（仅限 Linux）：
|
||
> ```bash
|
||
> docker run --network=host \
|
||
> -v qwenpaw-data:/app/working \
|
||
> -v qwenpaw-secrets:/app/working.secret \
|
||
> -v qwenpaw-backups:/app/working.backups \
|
||
> agentscope/qwenpaw:latest
|
||
> ```
|
||
> 无需端口映射（`-p`），容器直接共享宿主机网络。注意这会将容器的所有端口暴露在宿主机上，可能与已占用的端口产生冲突。
|
||
>
|
||
|
||
镜像从零构建。若需自行构建镜像，请参阅 `scripts/README.md` 中的 [Build Docker image](scripts/README.md#build-docker-image) 小节，构建后推送到你的镜像仓库。
|
||
|
||
---
|
||
|
||
### 方式四：部署到阿里云 ECS
|
||
|
||
若希望将 QwenPaw 部署在阿里云上，可使用阿里云 ECS 一键部署：打开 [QwenPaw 阿里云 ECS 部署链接](https://computenest.console.aliyun.com/service/instance/create/cn-hangzhou?type=user&ServiceId=service-1ed84201799f40879884) 按页面提示操作即可。详细步骤见 [阿里云开发者社区：3 分钟部署你的 AI 助理](https://developer.aliyun.com/article/1713682)。
|
||
|
||
---
|
||
|
||
### 方式五：AgentScope Platform 部署
|
||
|
||
[AgentScope Platform](https://platform.agentscope.io/) 提供一键云端 QwenPaw 部署、插件分享与 Skill 市场。完全免费，7/24 在线。
|
||
|
||
---
|
||
|
||
### 方式六：使用魔搭创空间
|
||
|
||
使用 [魔搭创空间](https://modelscope.cn/studios/fork?target=AgentScope/QwenPaw) 也可进行云端 QwenPaw 部署。注意：请将创空间设为 **非公开**，否则他人可能操纵你的 QwenPaw。
|
||
|
||
---
|
||
|
||
### 方式七：桌面应用（Beta）
|
||
|
||
> **Beta 版本说明**：桌面应用目前处于 Beta 测试阶段，存在以下已知限制：
|
||
> - **兼容性测试不完整**：未在所有系统版本和硬件配置上进行充分测试
|
||
> - **性能可能存在缺陷**：启动速度、内存占用等方面可能需要进一步优化
|
||
> - **功能持续完善中**：部分功能可能不稳定或缺失
|
||
|
||
如果你不习惯使用命令行，可以下载并使用 QwenPaw 的桌面应用版本，无需手动配置 Python 环境或执行命令。
|
||
|
||
#### 下载
|
||
|
||
从 [官方下载页](https://qwenpaw.agentscope.io/downloads) 下载桌面应用（Tauri 版）：
|
||
- **Windows**：`QwenPaw-Tauri-<version>-Windows-setup.exe`
|
||
- **macOS**：`QwenPaw-Tauri-<version>-macOS.zip`（推荐 Apple Silicon）
|
||
|
||
#### 特点
|
||
|
||
- ✅ **零配置**：下载后双击即可运行，无需安装 Python 或配置环境变量
|
||
- ✅ **跨平台**：支持 Windows 10+ 和 macOS 14+
|
||
- ✅ **可视化**：自动打开应用界面，无需手动输入地址
|
||
- ⚠️ **Beta 阶段**：功能持续完善中，欢迎反馈问题
|
||
|
||
#### 首次启动
|
||
|
||
**重要提示**：首次启动可能需要 10-60 秒（取决于您的系统配置）。应用需要初始化 Python 环境和加载依赖，请耐心等待窗口自动打开。
|
||
|
||
#### macOS：绕过系统安全限制
|
||
|
||
当你从 Releases 下载 QwenPaw macOS 应用时，macOS 可能显示：*"Apple 无法验证 'QwenPaw' 不包含恶意软件"*。这是因为应用未经过公证。你仍然可以通过以下方式打开：
|
||
|
||
- **右键打开（推荐）**
|
||
右键点击（或 Control + 点击）QwenPaw 应用 → **「打开」** → 在对话框中再次点击 **「打开」**。这会告诉 Gatekeeper 你信任该应用；之后可以像往常一样双击启动。
|
||
|
||
- **在系统设置中允许**
|
||
如果仍被阻止，进入 **系统设置 → 隐私与安全性**，向下滚动找到类似 *「已阻止 'QwenPaw'，因为无法验证开发者」* 的提示，点击 **「仍要打开」** 或 **「允许」**。
|
||
|
||
- **移除隔离属性（不推荐大多数用户）**
|
||
在终端运行：
|
||
`xattr -cr "/Applications/QwenPaw Desktop.app"`
|
||
（或使用解压后的 `.app` 路径）。这会清除「从互联网下载」的隔离标志，使警告通常不会出现，但不如使用 **右键 → 打开** 安全和可控。
|
||
|
||
详细使用说明、故障排除和常见问题，请参见 [桌面应用指南](https://qwenpaw.agentscope.io/docs/desktop)。
|
||
|
||
---
|
||
|
||
### 下一步？
|
||
|
||
安装完成后，在 **控制台 → 设置 → 模型** 中配置模型，然后探索：
|
||
|
||
- [添加 Skills](https://qwenpaw.agentscope.io/docs/skills) 扩展能力（PDF、Office、浏览器、新闻等）
|
||
- [配置频道](https://qwenpaw.agentscope.io/docs/channels) 连接钉钉、飞书、Discord 等
|
||
- [配置 Cron](https://qwenpaw.agentscope.io/docs/cron) 实现定时任务与自动化
|
||
- [体验 Coding 模式](https://qwenpaw.agentscope.io/docs/coding-mode) 进行 IDE 式代码协作
|
||
- 查看完整 [快速开始指南](https://qwenpaw.agentscope.io/docs/quickstart) 了解所有选项与验证步骤
|
||
|
||
---
|
||
|
||
## 终端界面（TUI）
|
||
|
||
更喜欢待在终端里？运行 `qwenpaw` 即可打开一个全屏聊天 **TUI**，它驱动的是与控制台、IM 频道**完全相同**的智能体 — 同一份记忆、技能、MCP 工具与会话 — 无需离开键盘。
|
||
|
||
```bash
|
||
qwenpaw # 与当前激活的智能体开启对话
|
||
qwenpaw tui --resume <id> # 恢复之前的某个会话
|
||
qwenpaw . # 在当前代码仓库中启动（Coding 模式）
|
||
```
|
||
|
||
支持流式回复、斜杠命令（`/help`、`/resume`、`/theme`，以及智能体自身的 `/model`、`/clear` 等）、把文件 / 长文本作为附件粘贴，以及行内工具授权提示。详见 [终端界面指南](https://qwenpaw.agentscope.io/docs/tui)。
|
||
|
||
|
||
|
||
---
|
||
|
||
## API Key
|
||
|
||
若使用**云端大模型 API**（如 DashScope / 通义千问、OpenAI、Anthropic、Google Gemini、DeepSeek、Kimi、OpenRouter 等），在开始对话前必须配置 API Key。未配置有效 Key 前，QwenPaw 无法正常工作。详情请参考 [官方文档](https://qwenpaw.agentscope.io/docs/models)。
|
||
|
||
**配置方式：**
|
||
|
||
1. **控制台（推荐）** — 运行 `qwenpaw app` 后，打开 **http://127.0.0.1:8088/** → **设置** → **模型**。选择提供商、填写 **API Key**，并启用该提供商与模型。
|
||
2. **`qwenpaw init`** — 运行 `qwenpaw init` 时，会引导你配置 LLM 提供商与 API Key。按提示选择提供商并填写 Key 即可。
|
||
3. **环境变量** — 使用 DashScope 时，可在终端或工作目录下的 `.env` 文件中设置 `DASHSCOPE_API_KEY`。
|
||
|
||
其他工具所需密钥（如网页搜索的 `TAVILY_API_KEY`）可在控制台 **设置 → 环境变量** 中配置，详见 [配置](https://qwenpaw.agentscope.io/docs/config)。
|
||
|
||
> **仅用本地模型？** 若使用 [本地模型](#本地模型)（QwenPaw Local / Ollama / LM Studio），则**无需**任何 API Key。
|
||
|
||
## 本地模型
|
||
|
||
QwenPaw 可在本机完全本地运行大模型，无需 API Key 或云端服务。详情请见 [官方文档](https://qwenpaw.agentscope.io/docs/models)。
|
||
|
||
QwenPaw 还提供 **QwenPaw-Flash** 系列 — 面向 Agent 场景专项训练的 2B / 4B / 9B 模型，提供 Q4 与 Q8 量化版本。可在 [ModelScope](https://www.modelscope.cn/organization/AgentScope?tab=model) 与 [Hugging Face](https://huggingface.co/agentscope-ai/models) 获取。
|
||
|
||
| 后端 | 适用场景 | 安装 |
|
||
| --------------------------------- | ---------------------------------------- | -------------------------------------------------------------------- |
|
||
| **QwenPaw Local**（llama.cpp） | 跨平台（macOS / Linux / Windows） | 内置；在 Web 界面点击「Download」即可。支持 QwenPaw-Flash，并提供硬件感知推荐。 |
|
||
| **Ollama** | 跨平台（需要 Ollama 服务运行） | 安装并启动 Ollama；将上下文长度设为 ≥ 32k。 |
|
||
| **LM Studio** | 跨平台（需要 LM Studio 服务运行） | 安装并启动 LM Studio；启用 Local Server。 |
|
||
|
||
---
|
||
|
||
## 安全特性
|
||
|
||
QwenPaw 内置四层核心安全防护：
|
||
|
||
- **Sandbox** — 内核级执行隔离，macOS 使用 Seatbelt，Linux 使用 Bubblewrap / Landlock，Windows 使用 AppContainer。Shell 命令在受限文件系统视图中运行。
|
||
- **Tool Guard** — 带 `ShellEvasionGuardian` 的 YAML 规则引擎，在每次工具调用执行前进行检查，检测命令注入、路径遍历、反向 Shell 与混淆攻击。可配置审批级别：STRICT / SMART / AUTO / OFF。
|
||
- **File Guard** — 独立于 Tool Guard；阻止智能体访问敏感文件与目录（默认保护 `~/.qwenpaw.secret/`、`~/.ssh` 等）。
|
||
- **Skill Scanner** — 激活前扫描，支持 block / warn / off 模式与白名单。检测提示词注入、硬编码密钥、数据外泄等风险。
|
||
- **Access Policy** — 声明式访问策略，对每次能力调用裁定放行(allow)、拒绝(deny)或请求人工审批(ask)，支持工具级粒度和来源感知匹配。
|
||
|
||
详见 [安全文档](https://qwenpaw.agentscope.io/docs/security)。
|
||
|
||
---
|
||
|
||
## 文档
|
||
|
||
| 主题 | 说明 |
|
||
| -------------------------------------------------------------------- | ------------------------------------------------ |
|
||
| [项目介绍](https://qwenpaw.agentscope.io/docs/intro) | QwenPaw 是什么、怎么用 |
|
||
| [快速开始](https://qwenpaw.agentscope.io/docs/quickstart) | 安装与运行（本地或魔搭创空间） |
|
||
| [控制台](https://qwenpaw.agentscope.io/docs/console) | Web 界面：对话与智能体配置 |
|
||
| [终端界面（TUI）](https://qwenpaw.agentscope.io/docs/tui) | 终端全屏对话，与控制台共用同一智能体 |
|
||
| [桌面应用](https://qwenpaw.agentscope.io/docs/desktop) | 桌面应用安装与使用 |
|
||
| [模型](https://qwenpaw.agentscope.io/docs/models) | 配置云端、本地与自定义提供商 |
|
||
| [频道配置](https://qwenpaw.agentscope.io/docs/channels) | 钉钉、飞书、QQ、Discord、iMessage 等 |
|
||
| [Coding 模式](https://qwenpaw.agentscope.io/docs/coding-mode) | 面向代码任务的三面板 Web IDE |
|
||
| [Skills](https://qwenpaw.agentscope.io/docs/skills) | 扩展与自定义能力 |
|
||
| [插件系统](https://qwenpaw.agentscope.io/docs/plugins) | 插件体系与 Plugin Market |
|
||
| [MCP 和工具](https://qwenpaw.agentscope.io/docs/mcp) | 管理 MCP 客户端 |
|
||
| [Persona](https://qwenpaw.agentscope.io/docs/persona) | 智能体人格定制（SOUL / PROFILE） |
|
||
| [记忆](https://qwenpaw.agentscope.io/docs/memory) | 基于本地、可编辑、可检索且相互链接的 Markdown 记忆构建自进化个人知识库，由 [ReMe](https://github.com/agentscope-ai/ReMe) 驱动 |
|
||
| [ReMe 文档](https://docs.agentscope.io/reme/latest/zh/overview) | ReMe 官方概览与文档 |
|
||
| [记忆进化与主动交互](https://qwenpaw.agentscope.io/docs/memory-evolving-and-proactive) | 智能体记忆进化与主动交互 |
|
||
| [上下文](https://qwenpaw.agentscope.io/docs/context) | 基于滚动的上下文管理 |
|
||
| [魔法命令](https://qwenpaw.agentscope.io/docs/commands) | 无需等待 AI 理解即可控制对话状态 |
|
||
| [心跳](https://qwenpaw.agentscope.io/docs/heartbeat) | 定时自检与摘要 |
|
||
| [Cron / 定时任务](https://qwenpaw.agentscope.io/docs/cron) | 定时任务与自动化 |
|
||
| [多智能体](https://qwenpaw.agentscope.io/docs/multi-agent) | 创建多个智能体并启用协作 |
|
||
| [安全](https://qwenpaw.agentscope.io/docs/security) | Sandbox、Tool Guard、File Guard、Skill Scanner、Access Policy |
|
||
| [备份与恢复](https://qwenpaw.agentscope.io/docs/backup) | 数据备份与恢复 |
|
||
| [配置与工作目录](https://qwenpaw.agentscope.io/docs/config) | 工作目录与配置文件 |
|
||
| [REST API](https://qwenpaw.agentscope.io/docs/api-tutorial) | 用于集成与自动化的 HTTP API |
|
||
| [ACP 集成](https://qwenpaw.agentscope.io/docs/acp-integration) | Agent Communication Protocol 集成 |
|
||
| [CLI](https://qwenpaw.agentscope.io/docs/cli) | 初始化、定时任务、Skills、清理 |
|
||
| [Agent 团队实践](https://qwenpaw.agentscope.io/docs/practice-agent-team) | 多智能体团队部署指南 |
|
||
| [FAQ](https://qwenpaw.agentscope.io/docs/faq) | 常见问题与故障排查 |
|
||
|
||
完整文档：[qwenpaw.agentscope.io/docs](https://qwenpaw.agentscope.io/docs)
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
更多常见问题、故障排查技巧和已知问题，请访问 **[FAQ 页面](https://qwenpaw.agentscope.io/docs/faq)**。
|
||
|
||
---
|
||
|
||
## 路线图
|
||
|
||
| 方向 | 事项 | 状态 |
|
||
| ------------------------ | -------------------------------------------------------------------------------------------- | ------ |
|
||
| **横向拓展** | 更多频道、模型、技能、MCP 等 — **欢迎社区贡献** | 征集中 |
|
||
| **已有功能扩展与完善** | 展示优化、下载提示、Windows 路径兼容等 — **欢迎社区贡献** | 征集中 |
|
||
| **模型** | 多模型切换 | 进行中 |
|
||
| **Browser-use** | 支持 Chrome 扩展 | 进行中 |
|
||
| **长期记忆** | 个人知识库 | 进行中 |
|
||
| **QwenPaw 应用** | QwenPaw Creator | 进行中 |
|
||
| | QwenPaw Insight | 进行中 |
|
||
| **多智能体** | 兼容 Claude Code 等既有 Agent | 计划中 |
|
||
| | 群聊 | 计划中 |
|
||
| | Subagent 可视化 | 计划中 |
|
||
|
||
_状态说明：**进行中** — 正在积极开发；**计划中** — 已排队或设计中，也欢迎贡献；**征集中** — 我们强烈鼓励社区参与。_
|
||
|
||
---
|
||
|
||
## 参与贡献
|
||
|
||
QwenPaw 在开放协作中持续演进，欢迎各种形式的参与！请参考上方 [路线图](#路线图)（尤其是标记为 **征集中** 的项）选择你感兴趣的方向，并阅读 [CONTRIBUTING](https://github.com/agentscope-ai/QwenPaw/blob/main/CONTRIBUTING_zh.md) 了解如何开始。我们特别欢迎：
|
||
|
||
- **横向拓展** — 新频道、模型提供商、Skills、MCP。
|
||
- **已有功能扩展与完善** — 展示与交互优化、下载提示、Windows 路径兼容等。
|
||
|
||
欢迎在 [GitHub Discussions](https://github.com/agentscope-ai/QwenPaw/discussions) 参与讨论、提出想法或认领任务。
|
||
|
||
---
|
||
|
||
## 从源码安装
|
||
|
||
```bash
|
||
git clone https://github.com/agentscope-ai/QwenPaw.git
|
||
cd QwenPaw
|
||
|
||
# 先构建前端控制台（Web 界面必需）
|
||
cd console && npm ci && npm run build
|
||
cd ..
|
||
|
||
# 将控制台构建产物复制到包目录
|
||
mkdir -p src/qwenpaw/console
|
||
cp -R console/dist/. src/qwenpaw/console/
|
||
|
||
# 安装 Python 包
|
||
pip install -e .
|
||
```
|
||
|
||
- **开发**（测试、格式化）：`pip install -e ".[dev,test,full]"`
|
||
- **然后**：运行 `qwenpaw init --defaults`，再运行 `qwenpaw app`。
|
||
|
||
> **版本更新提示：** 当执行 `git pull` 更新到大版本后，请重新构建前端、重新安装 Python 包（`pip install -e .`）、重启 `qwenpaw app`，并清除浏览器缓存（`Ctrl+Shift+R` 或 macOS 上 `Cmd+Shift+R`）。
|
||
|
||
---
|
||
|
||
## 为什么叫 QwenPaw？
|
||
|
||
QwenPaw 既是 Qwen Personal Agent Workstation（千问个人智能体工作台），也寓意 Qwen 的智识与 Paw 的温度。我们希望它不是冰冷的工具，而是一只随时准备帮忙的智慧、温暖「小爪子」，是你数字生活中最默契的伙伴。
|
||
|
||
---
|
||
|
||
## 由谁构建
|
||
|
||
[AgentScope 团队](https://github.com/agentscope-ai) · [AgentScope](https://github.com/agentscope-ai/agentscope) · [AgentScope Runtime](https://github.com/agentscope-ai/agentscope-runtime) · [ReMe](https://github.com/agentscope-ai/ReMe)
|
||
|
||
---
|
||
|
||
## 联系我们
|
||
|
||
| [Discord](https://discord.gg/eYMpfnkG8h) | [X (Twitter)](https://x.com/agentscope_ai) | [钉钉](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) | [小红书](https://www.xiaohongshu.com/user/profile/691c18db0000000037032be9) |
|
||
| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||
| [<img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="80" height="80" alt="Discord">](https://discord.gg/eYMpfnkG8h) | [<img src="https://img.shields.io/badge/X-black.svg?logo=x&logoColor=white" width="80" height="80" alt="X">](https://x.com/agentscope_ai) | [<img src="https://img.alicdn.com/imgextra/i2/O1CN01vCWI8a1skHtLGXEMQ_!!6000000005804-2-tps-458-460.png" width="80" height="80" alt="钉钉">](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) | [<img src="https://img.alicdn.com/imgextra/i3/O1CN016BoEPS1l33CE9mHb9_!!6000000004762-0-tps-160-160.jpg" width="80" height="80" alt="小红书">](https://www.xiaohongshu.com/user/profile/691c18db0000000037032be9) |
|
||
|
||
---
|
||
|
||
## 掌握最新动态
|
||
|
||
<a href="https://github.com/agentscope-ai/QwenPaw">
|
||
<img src="https://img.alicdn.com/imgextra/i1/O1CN01V8HYv61By0HYcIDaq_!!6000000000013-1-tps-1698-954.gif" width="600" alt="Star QwenPaw" />
|
||
</a>
|
||
|
||
在 GitHub 上 Star QwenPaw，第一时间收到新版本发布通知。
|
||
|
||
---
|
||
|
||
## 遥测数据
|
||
|
||
QwenPaw 在执行 `qwenpaw init` 时会收集**匿名**使用数据，帮助我们了解用户环境并优化产品。数据**每个版本收集一次** — 当你升级 QwenPaw 后，会重新收集以便我们了解版本分布。
|
||
|
||
**收集的信息：**
|
||
|
||
- QwenPaw 版本（如 1.1.12）
|
||
- 安装方式（pip、Docker 或桌面应用）
|
||
- 操作系统及版本（如 macOS 14.0、Ubuntu 22.04）
|
||
- Python 版本（如 3.13）
|
||
- CPU 架构（如 x86_64、arm64）
|
||
- GPU 是否可用（是/否）
|
||
|
||
**不收集：** 不涉及任何个人数据、文件、密钥、IP 地址或可识别信息。
|
||
|
||
交互式运行 `qwenpaw init` 时，会询问你是否同意。使用 `--defaults` 模式则自动同意。提示每个版本仅出现一次，且不影响 QwenPaw 的任何功能。
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
QwenPaw 采用 [Apache License 2.0](LICENSE) 开源协议。
|
||
|
||
---
|
||
|
||
## 贡献者
|
||
|
||
感谢所有为 QwenPaw 做出贡献的朋友们：
|
||
|
||
<a href="https://github.com/agentscope-ai/QwenPaw/graphs/contributors">
|
||
<img src="https://contrib.rocks/image?repo=agentscope-ai/QwenPaw" alt="贡献者" />
|
||
</a>
|