Skip to content

README_zh.md

Latest commit

 

History

History
600 lines (430 loc) · 34.2 KB

README_zh.md

File metadata and controls

600 lines (430 loc) · 34.2 KB

QwenPaw

GitHub 仓库 PyPI 文档 Python 版本 最后提交 许可证 代码风格 GitHub Star GitHub Fork DeepWiki Discord X 钉钉群

[文档] [English] [日本語] [Русский]

QwenPaw Logo

懂你所需，伴你左右。

你的 AI 个人助理；安装极简、本地与云上均可部署；支持多端接入、能力轻松扩展。

核心能力：

由你掌控 — 记忆与个性化完全由你掌控，支持本地或云端部署。无第三方托管，无数据上传。

Skills 扩展 — 内置定时任务、PDF/Office 处理、新闻摘要等；自定义技能自动加载，无绑定。通过 Skills 决定 QwenPaw 能做什么。

多智能体协作 — 创建多个独立智能体，各司其职；启用协作技能，智能体间互相通信共同完成复杂任务。

多层安全防护 — 工具防护、文件访问控制、技能安全扫描，保障运行安全。

全域触达 — 钉钉、飞书、微信、Discord、Telegram 等频道，一个 QwenPaw 按需连接。

记忆进化与主动交互 — 智能体从交互中学习、反思经验、主动服务，越用越聪明。

你可以用 QwenPaw 做什么
  • 社交媒体：每日热帖摘要（小红书、知乎、Reddit），B 站/YouTube 新视频摘要。
  • 生产力：邮件与 Newsletter 精华推送到钉钉/飞书/QQ，邮件与日历整理联系人。
  • 创意与构建：睡前说明目标、自动执行，次日获得雏形；从选题到成片全流程。
  • 研究与学习：追踪科技与 AI 资讯，个人知识库检索复用。
  • 桌面与文件：整理与搜索本地文件、阅读与摘要文档，在会话中索要文件。
  • 探索更多：用 Skills 与定时任务组合成你自己的 agentic app。

新闻

  • [2026-05-19] 我们发布了 v1.1.8！完整更新说明见 v1.1.8 发布说明。

    • [v1.1.8] 新增：官方插件资源（网站下载 + 控制台一键安装）；QwenPaw Pet 桌面宠物；CloudPaw 阿里云部署插件；/make-skill 命令；自定义 HTTP Headers 与鉴权模式；支持模型独立配置上下文；收件箱批量操作；聊天历史抽屉固定。
    • [v1.1.8] 安全：备份信任控制；Skill 与 AgentMd 路径穿越防护；插件 API 认证。
    • [v1.1.8] 修复：企业微信/微信/QQ 频道稳定性；按模型限速；SSE 连接泄漏。
    • [v1.1.8] 感谢新贡献者：@Morxi。

  • [2026-05-14] 我们发布了 v1.1.7！完整更新说明见 v1.1.7 发布说明。

  • [2026-05-09] 我们发布了 v1.1.6！完整更新说明见 v1.1.6 发布说明。

  • [2026-04-29] 我们发布了 v1.1.5！完整更新说明见 v1.1.5 发布说明。

  • [2026-04-12] CoPaw 正式更名为 QwenPaw：这是一次品牌名称焕新，也是我们迈向下一阶段开源的重要一步。

新的名字，更好地体现了我们正在构建的开源生态，以及我们持续推进的整体开源方向：

Qwen — 代表和 Qwen 开源生态的融合，以及对模型侧的对焦，包括本地化模型、大小模型协同。

Paw — 是我们初心的延续，目标是陪伴用户、成为用户可以信任的个人助手。

名称焕新，但在开源社区的愿景和目标始终不变：

  • 继续打造更实用、更安全、更个性化的个人 AI 体验；
  • 继续坚持开源共建、和社区一同前行！

感谢大家一直以来的支持。从今天起，请大家叫我们 QwenPaw。

目录

推荐阅读：

快速开始

方式一：pip 安装

如果你习惯自行管理 Python 环境：

pip install qwenpaw
qwenpaw init --defaults
qwenpaw app

然后在浏览器中打开控制台：http://127.0.0.1:8088/ ，配置模型后即可开始对话。 若要在钉钉、飞书、微信等 app 内对话，请参考 频道配置 文档。

Console

方式二：脚本安装

无需手动配置 Python，一行命令自动完成安装。脚本会自动下载 uv（Python 包管理器）、创建虚拟环境、安装 QwenPaw 及其依赖（含 Node.js 和前端资源）。注意：部分网络环境或企业权限管控下可能无法使用。

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 状态，若未安装则尝试自动下载配置。如遇自动安装失败，请遵循屏幕提示操作，或执行 python -m pip install -U uv，然后重新运行安装程序。

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

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

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

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

    • 找到安装目录：
      • 检查 uv 是否可用：在 CMD 中输入 uv --version ，如果显示版本号，则只需配置 QwenPaw 路径；如果提示 'uv' 不是内部或外部命令，也不是可运行的程序或批处理文件。，则需同时配置两者。
      • 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下载并将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 变量中。

安装完成后，请打开新终端并运行：

qwenpaw init --defaults   # 或：qwenpaw init（交互式）
qwenpaw app
安装选项

macOS / Linux：

# 安装指定版本
curl -fsSL ... | bash -s -- --version 1.1.0

# 从源码安装（开发/测试用）
curl -fsSL ... | bash -s -- --from-source

# 升级 — 重新运行安装命令即可
curl -fsSL ... | bash

# 卸载
qwenpaw uninstall          # 保留配置和数据
qwenpaw uninstall --purge  # 删除所有内容

Windows（PowerShell）：

# 安装指定版本
irm ... | iex; .\install.ps1 -Version 0.0.2

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

# 升级 — 重新运行安装命令即可
irm ... | iex

# 卸载
qwenpaw uninstall          # 保留配置和数据
qwenpaw uninstall --purge  # 删除所有内容

注意：如需安装本地模型支持（llama.cpp、Ollama、LM Studio），请参考 本地模型 章节。

方式三：使用 Docker

镜像在 Docker Hub（agentscope/qwenpaw）。镜像 tag：latest（稳定版）；pre（PyPI 预发布版）。

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 — 显式绑定宿主机地址（全平台通用）：

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）：

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」小节，构建后推送到你的镜像仓库。

方式四：部署到阿里云 ECS

若希望将 QwenPaw 部署在阿里云上，可使用阿里云 ECS 一键部署：打开 QwenPaw 阿里云 ECS 部署链接 按页面提示操作即可。详细步骤见 阿里云开发者社区：QwenPaw 3 分钟部署你的 AI 助理。

方式五：使用魔搭创空间

不想本地安装？ 使用 魔搭创空间 一键云端配置。请将创空间设为 非公开，否则他人可能操纵你的 QwenPaw。

方式六：桌面应用（Beta）

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

  • 兼容性测试不完整：未在所有系统版本和硬件配置上进行充分测试
  • 性能可能存在缺陷：启动速度、内存占用等方面可能需要进一步优化
  • 功能持续完善中：部分功能可能不稳定或缺失

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

下载

从 GitHub Releases 下载桌面应用：

  • Windows: QwenPaw-Setup-<version>.exe
  • macOS: QwenPaw-<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.app （或使用解压后的 .app 路径）。这会清除“从互联网下载”的隔离标志，使警告通常不会出现，但不如使用 右键 → 打开 安全和可控。

详细使用说明、故障排除和常见问题，请参见 桌面应用指南。

使用魔搭创空间

不想本地安装？ 使用 魔搭创空间 一键云端配置。请将创空间设为 非公开，否则他人可能操纵你的 QwenPaw。

使用 Docker

镜像在 Docker Hub（agentscope/qwenpaw）。镜像 tag：latest（稳定版）；pre（PyPI 预发布版）。

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 — 显式绑定宿主机地址（全平台通用）：

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）：

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），容器直接共享宿主机网络。注意这会将容器的所有端口暴露在宿主机上，可能与已占用的端口产生冲突。

提示： 如果你只挂载了 /app/working 而没有单独挂载 /app/working.secret，入口脚本会自动将 secrets 重定向到 /app/working/.secret，使其也保存在同一个 volume 中。

镜像从零构建。若需自行构建镜像，请参阅 scripts/README.md 中的「Build Docker image」小节，构建后推送到你的镜像仓库。

部署到阿里云 ECS

若希望将 QwenPaw 部署在阿里云上，可使用阿里云 ECS 一键部署：打开 QwenPaw 阿里云 ECS 部署链接 按页面提示操作即可。详细步骤见 阿里云开发者社区：QwenPaw 3 分钟部署你的 AI 助理。

API Key

若使用云端大模型 API（如通义千问、Gemini、OpenAI），在开始对话前必须配置 API Key。未配置有效 Key 前，QwenPaw 无法正常工作。详情请参考官方文档。

配置方式：

  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）可在控制台 设置 → 环境变量 中配置，详见 配置。

仅用本地模型？ 若使用 本地模型（llama.cpp，Ollama，LM Studio），则无需任何 API Key。

本地模型

QwenPaw 可在本机完全本地运行大模型，无需 API Key 或云端服务。详情请见官方文档

后端 适用场景 安装
llama.cpp 跨平台（macOS / Linux / Windows） 无需额外安装，在 Web 界面中点击 Download Llama.cpp 即可
Ollama 跨平台（需要 Ollama 服务运行） 提前安装 Ollama 应用并启动
LM Studio 跨平台（需要 LM Studio 服务运行） 提前安装 LM Studio 应用并启动

文档

主题 说明
项目介绍 QwenPaw 是什么、怎么用
快速开始 安装与运行（本地或魔搭创空间）
控制台 Web 界面：对话、配置与定时任务
模型 配置云/本地/自定义提供商
频道配置 钉钉、飞书、微信、Discord、Telegram 等
Skills 扩展与自定义能力
插件系统 插件系统
MCP和工具 管理 MCP 客户端和工具
记忆 长期记忆机制
记忆进化与主动交互 智能体记忆进化与主动交互
上下文 上下文管理机制
魔法命令 控制对话状态，无需等待 AI 理解
安全 工具防护、文件防护、技能安全扫描
心跳 定时自检与摘要
多智能体 创建多个智能体并启用协作
配置与工作目录 工作目录与配置文件
CLI 初始化、定时任务、Skills、清理
FAQ 常见问题与报错排查

完整文档见本仓库 website/public/docs/。

安全特性

QwenPaw 内置多层安全防护机制，保障你的数据与系统安全：

  • 工具防护 — 自动拦截危险 Shell 命令（如 rm -rf /、fork 炸弹、反向 shell 等）
  • 文件访问守卫 — 限制智能体访问敏感路径（如 ~/.ssh、密钥文件、系统目录等）
  • 技能安全扫描 — 安装技能前自动扫描，检测提示词注入、命令注入、硬编码密钥、数据外泄等风险
  • 本地部署 — 所有数据与记忆存储在本地，无第三方上传（使用云端 LLM API 时，对话内容会发送到对应的 API 提供商）
  • Web 登录认证 — 可选的控制台登录防护，默认关闭；设置 QWENPAW_AUTH_ENABLED=true 即可开启。详见 Web 登录认证。

详见 安全文档。

常见问题

更多常见问题、故障排查技巧和已知问题，请访问 FAQ 页面。

掌握最新动态

Star QwenPaw

在 GitHub 上 Star QwenPaw，第一时间收到新版本发布通知。

路线图

方向 事项 状态
横向拓展 更多频道、模型、技能、MCP 等 — 欢迎社区贡献 征集中
已有功能扩展与完善 展示优化、下载提示、Windows 路径兼容等 — 欢迎社区贡献 征集中
客户端体验 安装、更新、打包优化 进行中
模型 端云模型智能切换 进行中
OAuth 计划中
Response API 计划中
主动性 定时任务与心跳升级 进行中
主动式简报、定制推送 进行中
洞察系统：对话与交互挖掘需求 计划中
工作区 结合 Sandbox 的文件权限管控 进行中
子目录划分（配置、生产文件等） 计划中
Coding 能力 LSP、专用 Prompt、工作区版本控制、执行环境等配套 infra 计划中
轻量原生接口 计划中
工具自进化 计划中
兼容 Claude Code 等既有 Agent 计划中
多智能体 群聊 计划中
Subagent 计划中
HiClaw 企业级能力 计划中
上下文管理 上下文智能压缩 进行中
用户可选压缩（细粒度控制） 计划中

状态说明：进行中 — 正在积极开发；计划中 — 已排队或设计中，也欢迎贡献；征集中 — 我们强烈鼓励社区参与。

从源码安装

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,full]"
  • 然后：运行 qwenpaw init --defaults，再运行 qwenpaw app。

版本更新提示： 当执行 git pull 更新到大版本后，请重新构建前端、重新安装 Python 包（pip install -e .）、重启 qwenpaw app，并清除浏览器缓存（Ctrl+Shift+R 或 macOS 上 Cmd+Shift+R）。

参与贡献

QwenPaw 在开放协作中持续演进，欢迎各种形式的参与！请参考上方 路线图（尤其是标记为 征集中 的项）选择你感兴趣的方向，并阅读 CONTRIBUTING 了解如何开始。我们特别欢迎：

  • 横向拓展 — 新频道、模型提供商、Skills、MCP。
  • 已有功能扩展与完善 — 展示与交互优化、下载提示、Windows 路径兼容等。

欢迎在 GitHub Discussions 参与讨论、提出想法或认领任务。

为什么叫 QwenPaw？

QwenPaw 既是 Qwen Personal Agent Workstation（千问个人智能体工作台），也寓意 Qwen 的智识，Paw 的温度。我们希望它不是冰冷的工具，而是一只随时准备帮忙的智慧、温暖“小爪子”，是你数字生活中最默契的伙伴。

由谁构建

AgentScope 团队 · AgentScope · AgentScope Runtime · ReMe

联系我们

Discord X (Twitter) 钉钉 小红书
Discord X 钉钉 小红书

遥测数据

QwenPaw 在执行 qwenpaw init 时会收集匿名使用数据，帮助我们了解用户环境并优化产品。数据每个版本收集一次 — 当你升级 QwenPaw 后，会重新收集以便我们了解版本分布。

收集的信息：

  • QwenPaw 版本（如 0.0.7）
  • 安装方式（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 开源协议。

贡献者

感谢所有为 QwenPaw 做出贡献的朋友们：

贡献者