README_zh.md

QwenPaw

懂你所需，伴你左右。

你的个人 AI 助理 — 本地或云端部署，通过 Skills 与插件扩展能力，全频道连接。


不遗忘对话	三层记忆 — 实时工作上下文、完整逐字历史，以及由 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）实现跨系统编排。
通用文件工作区	在项目文件与 Agent 文件中统一提供文件导航、预览、编辑、Diff、上传和下载。
能力扩展	Skills 覆盖定时任务、文档、浏览器、新闻等。插件架构带 Plugin Market。MCP 集成外部工具。自由组合成面向场景的工作流。
随处可达	钉钉、飞书、微信、Discord、Telegram、iMessage、QQ — 一个实例，全频道连接。Console、TUI 与桌面应用可直接访问。
你的，不是我们的	本地部署，数据留在你的机器，无第三方托管，无数据上传。

你可以用 QwenPaw 做什么

自动化与定时任务：设置定时任务 — 新闻摘要、报告生成、多频道广播 — 全部按你的时间表自动运行。
代码与开发：通过通用文件工作区在项目中阅读、编辑、审查与测试代码。
文档处理：读取、写入与转换 PDF、Word、Excel、PowerPoint 文件。
信息收集：搜索网页、关注资讯订阅、总结视频内容，并从个人知识库中检索所需信息。
多频道运营：向钉钉、飞书、Discord、Telegram 等推送告警、摘要或 AI 生成内容 — 可同时或按频道分发。
自定义工作流：把内置能力、插件和定时任务组合起来，打造适合你的专属流程。

新闻

[2026-09-10] v2.2.1 | Creator 1.2 蓝图工作台、按智能体配置的模型路由和统一环境管理。v2.2.1 发布说明 →
[2026-09-03] v2.2.0 | 新增可自托管的多用户 QwenPaw Hub、QwenPaw Mail、原生 QwenPaw Data、统一模型路由和 Creator 1.1，并全面改进应用市场、控制台、Skills、频道与运行可靠性。v2.2.0 发布说明 →
[2026-08-13] v2.1.0 | QwenPaw OS Shell、统一文件工作区、QwenPaw Creator、Codex/Qoder 智能体接入、Browser-use、Computer-use、工作区检查点和长对话任务续接等。v2.1.0 发布说明 →
[2026-07-24] v2.0.1 | PawApp 小程序平台、用户可编辑 Agent Mode、Oh-My-Paw plugins、ReMe 记忆增强、桌面端用户体验增强等。v2.0.1 发布说明 →

[2026-07-10] v2.0.0 — QwenPaw 2.0 正式发布 🎉 | 基于 AgentScope 2.0 全面重构，带来 Agent OS 架构、Loop Engineering、Scroll 上下文、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 v0.4 自进化个人知识库	持续将对话与资料转化为可读、可编辑、可检索、相互链接的 Markdown 记忆。
终端界面（TUI）	全屏终端对话——与控制台和频道共享同一智能体、记忆与会话。

基于 Agent OS，我们将陆续推出开箱即用的 QwenPaw 应用小程序——如 QwenPaw Creator、QwenPaw Insight 等，敬请期待。 v2.0.0 发布说明 →

全部发布说明 →

快速开始

方式一：pip 安装

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

pip install qwenpaw
qwenpaw init --defaults
qwenpaw app

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

方式二：脚本安装

无需手动配置 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 可能运行在 受限语言模式 下，可能会遇到以下问题：

如果你使用的是 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，点击「编辑」。

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

如果你使用的是 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 1.1.12

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

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

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

方式三：使用 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 部署链接按页面提示操作即可。详细步骤见阿里云开发者社区：3 分钟部署你的 AI 助理。

方式五：AgentScope Platform 部署

AgentScope Platform 提供一键云端 QwenPaw 部署、插件分享与 Skill 市场。完全免费，7/24 在线。

方式六：使用魔搭创空间

使用魔搭创空间也可进行云端 QwenPaw 部署。注意：请将创空间设为 非公开，否则他人可能操纵你的 QwenPaw。

方式七：桌面应用（Beta）

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

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

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

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

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

下载

从官方下载页下载桌面应用（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 路径）。这会清除「从互联网下载」的隔离标志，使警告通常不会出现，但不如使用 右键 → 打开 安全和可控。

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

下一步？

安装完成后，在 控制台 → 设置 → 模型 中配置模型，然后探索：

添加 Skills 扩展能力（PDF、Office、浏览器、新闻等）
配置频道连接钉钉、飞书、Discord 等
配置 Cron 实现定时任务与自动化
查看完整快速开始指南了解所有选项与验证步骤

终端界面（TUI）

更喜欢待在终端里？运行 qwenpaw 即可打开一个全屏聊天 TUI，它驱动的是与控制台、IM 频道完全相同的智能体 — 同一份记忆、技能、MCP 工具与会话 — 无需离开键盘。

qwenpaw                     # 与当前激活的智能体开启对话
qwenpaw tui --resume <id>   # 恢复之前的某个会话
qwenpaw .                   # 在当前代码仓库中启动（Coding 模式）

支持流式回复、斜杠命令（/help、/resume、/theme，以及智能体自身的 /model、/clear 等）、把文件 / 长文本作为附件粘贴，以及行内工具授权提示。详见终端界面指南。

API Key

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

配置方式：

控制台（推荐） — 运行 qwenpaw app 后，打开 http://127.0.0.1:8088/ → 设置 → 模型。选择提供商、填写 API Key，并启用该提供商与模型。
qwenpaw init — 运行 qwenpaw init 时，会引导你配置 LLM 提供商与 API Key。按提示选择提供商并填写 Key 即可。
环境变量 — 使用 DashScope 时，可在终端或工作目录下的 .env 文件中设置 DASHSCOPE_API_KEY。

其他工具所需密钥（如网页搜索的 TAVILY_API_KEY）可在控制台 设置 → 环境变量 中配置，详见配置。

仅用本地模型？ 若使用本地模型（QwenPaw Local / Ollama / LM Studio），则无需任何 API Key。

本地模型

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

QwenPaw 还提供 QwenPaw-Flash 系列 — 面向 Agent 场景专项训练的 2B / 4B / 9B 模型，提供 Q4 与 Q8 量化版本。可在 ModelScope 与 Hugging Face 获取。

后端	适用场景	安装
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)，支持工具级粒度和来源感知匹配。

详见安全文档。

文档

主题	说明
项目介绍	QwenPaw 是什么、怎么用
快速开始	安装与运行（本地或魔搭创空间）
控制台	Web 界面：对话与智能体配置
终端界面（TUI）	终端全屏对话，与控制台共用同一智能体
桌面应用	桌面应用安装与使用
模型	配置云端、本地与自定义提供商
频道配置	钉钉、飞书、QQ、Discord、iMessage 等
Skills	扩展与自定义能力
插件系统	插件体系与 Plugin Market
MCP 和工具	管理 MCP 客户端
Persona	智能体人格定制（SOUL / PROFILE）
记忆	基于本地、可编辑、可检索且相互链接的 Markdown 记忆构建自进化个人知识库，由 ReMe 驱动
ReMe 文档	ReMe 官方概览与文档
记忆进化与主动交互	智能体记忆进化与主动交互
上下文	基于滚动的上下文管理
魔法命令	无需等待 AI 理解即可控制对话状态
心跳	定时自检与摘要
Cron / 定时任务	定时任务与自动化
多智能体	创建多个智能体并启用协作
安全	Sandbox、Tool Guard、File Guard、Skill Scanner、Access Policy
备份与恢复	数据备份与恢复
配置与工作目录	工作目录与配置文件
REST API	用于集成与自动化的 HTTP API
ACP 集成	Agent Communication Protocol 集成
CLI	初始化、定时任务、Skills、清理
Agent 团队实践	多智能体团队部署指南
FAQ	常见问题与故障排查

完整文档：qwenpaw.agentscope.io/docs

常见问题

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

路线图

方向	事项	状态
横向拓展	更多频道、模型、技能、MCP	征集中
已有功能扩展与完善	展示、下载与 Windows 兼容优化	征集中
模型	多模型切换	进行中
安全与审批	批量预览与批准	进行中
自动化	自动化任务	进行中
智能体交互	智能体任务交接	进行中
	运行中任务调整	进行中
工作区	多工作区	进行中
上下文	系统提示压缩	进行中
工具系统	多位置文件修改	进行中
	持久终端与后台任务	进行中
Computer-use	屏幕目标定位与操作	进行中
语音交互	实时语音任务	进行中
上下文管理与记忆	向量模型与存储热切换	进行中
	个人知识库	进行中
QwenPaw 应用	QwenPaw Insight	进行中
	QwenPaw Mail	进行中

状态说明：进行中 — 正在积极开发；征集中 — 我们强烈鼓励社区参与。

参与贡献

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

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

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

从源码安装

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 团队 · AgentScope · AgentScope Runtime · ReMe

联系我们

Discord	X (Twitter)	钉钉	小红书

掌握最新动态

在 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 开源协议。

贡献者

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

Navigation Menu

Repository navigation

QwenPaw

新闻

目录

快速开始

方式一：pip 安装

方式二：脚本安装

方式三：使用 Docker

方式四：部署到阿里云 ECS

方式五：AgentScope Platform 部署

方式六：使用魔搭创空间

方式七：桌面应用（Beta）

下载

特点

首次启动

macOS：绕过系统安全限制

下一步？

终端界面（TUI）

API Key

本地模型

安全特性

文档

常见问题

路线图

参与贡献

从源码安装

为什么叫 QwenPaw？

由谁构建

联系我们

掌握最新动态

遥测数据

许可证

贡献者

FilesExpand file tree

README_zh.md

Latest commit

History

README_zh.md

File metadata and controls

QwenPaw

新闻

目录

快速开始

方式一：pip 安装

方式二：脚本安装

方式三：使用 Docker

方式四：部署到阿里云 ECS

方式五：AgentScope Platform 部署

方式六：使用魔搭创空间

方式七：桌面应用（Beta）

下载

特点

首次启动

macOS：绕过系统安全限制

下一步？

终端界面（TUI）

API Key

本地模型

安全特性

文档

常见问题

路线图

参与贡献

从源码安装

为什么叫 QwenPaw？

由谁构建

联系我们

掌握最新动态

遥测数据

许可证

贡献者