QwenPaw

[![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask_Devin-navy.svg?logo=data:image/png;base64,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......

目录

推荐阅读：

• 🚀 我是新手，想快速上手：快速入门 → 执行三条命令 → 配置模型 → 在控制台聊天
• 💬 我想在钉钉/飞书/微信中使用：完成快速入门 → 配置模型 → 渠道设置
• 🐍 我不想安装 Python：桌面应用 或 脚本安装 或 ModelScope Studio
• 💻 我想使用本地模型（无需 API 密钥）：本地模型 → 下载模型 → 开始使用
• 🛠️ 我想贡献代码或开发新功能：从源码安装 → 贡献指南

• 新闻
• 快速入门
• API 密钥
• 本地模型
• 文档
• 安全特性
• 常见问题解答
• 保持领先
• 路线图
• 从源码安装
• 贡献指南
• 为什么选择 QwenPaw？
• 由谁构建
• 许可证

快速入门

选项 1：pip 安装

如果您更喜欢自行管理 Python：

pip install qwenpaw
qwenpaw init --defaults
qwenpaw app

然后在浏览器中打开控制台，地址为 http://127.0.0.1:8088/，以配置您的模型。如需在钉钉、飞书、微信等平台聊天，请参阅 渠道设置 文档。

选项 2：脚本安装

无需任何 Python 环境配置，一条命令即可完成所有安装。该脚本会自动下载 uv（Python 包管理器），创建虚拟环境，并安装 QwenPaw 及其所有依赖项（包括 Node.js 和前端资源）。注意：在受限网络环境或企业防火墙下可能无法正常工作。

macOS / Linux：

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

若需支持 Ollama：

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

若需同时支持多个扩展（例如 Ollama + 本地模型）：

curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash -s -- --extras ollama,local

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 Enterprise 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 并按 Enter 打开系统属性。
     • 点击“高级”→“环境变量”。
     • 在“系统变量”中，找到并选择 Path，然后点击“编辑”。
     • 点击“新建”，依次输入两个目录路径，然后点击确定保存。

2. 若使用 PowerShell (.ps1)：脚本执行中断

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

• 手动安装 uv：请参考 GitHub 发布页面 下载 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

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

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

# 升级——只需重新运行安装程序
curl -fsSL ... | bash

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

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

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

# 升级——只需重新运行安装程序
irm ... | iex

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

选项 3：Docker

镜像托管在 Docker Hub 上（agentscope/qwenpaw）。镜像标签：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 \
  agentscope/qwenpaw:latest

同时，面向中国用户，该镜像也在阿里云容器镜像服务（ACR）上提供：agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw（标签相同）。

随后打开 http://127.0.0.1:8088/ 即可进入控制台。配置、内存和技能存储在 qwenpaw-data 卷中；模型提供商的设置和 API 密钥则存储在 qwenpaw-secrets 卷中。若需传递 API 密钥（如 DASHSCOPE_API_KEY），可在 docker run 命令中添加 -e VAR=value 或 --env-file .env。

连接宿主机上的 Ollama 或其他服务

在 Docker 容器内，localhost 指的是容器本身，而非宿主机。如果您在宿主机上运行 Ollama（或其他模型服务），并希望 Docker 中的 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 \
  agentscope/qwenpaw:latest

然后在 QwenPaw 的 设置 → 模型 中，将基础 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 \
  agentscope/qwenpaw:latest

此时无需进行端口映射（-p），容器会直接共享宿主机网络。请注意，容器的所有端口都会暴露在宿主机上，如果该端口已被占用，可能会导致冲突。

注意：如果您只挂载了 /app/working 而未单独创建 /app/working.secret 卷，则入口脚本会自动将密钥重定向到 /app/working/.secret，从而确保密钥保存在同一卷中。

该镜像是从零开始构建的。如需自行构建镜像，请参阅 scripts/README.md 中的 构建 Docker 镜像 部分，然后推送到您的镜像仓库。

选项 4：部署在阿里云 ECS 上

要在阿里云（ECS）上运行 QwenPaw，可以使用一键部署功能：打开 QwenPaw 在阿里云（ECS）上的部署链接，并按照提示操作。有关详细步骤，请参阅 阿里云开发者：3 分钟部署你的 AI 助手。

选项 5：使用 ModelScope

没有本地安装环境？ 可以通过 ModelScope Studio 进行一键云端部署。请将 Studio 设置为 非公开，以防止他人控制您的 QwenPaw。

选项 6：桌面应用（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 文件路径）。此操作会清除“从互联网下载”的隔离标记，通常可避免警告出现，但安全性及可控性不如使用“右键 → 打开”方法。

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

API 密钥

如果您使用 云端大模型 API（例如通义千问、Gemini、OpenAI），在开始聊天前必须配置 API 密钥。在设置有效的密钥之前，QwenPaw 将无法正常工作。详情请参阅官方文档。

如何配置：

1. 控制台（推荐） — 运行 qwenpaw app 后，打开 http://127.0.0.1:8088/ → 设置 → 模型。选择提供商，输入 API 密钥，并启用该提供商和模型。
2. qwenpaw init — 当您运行 qwenpaw init 时，它会引导您完成大模型提供商和 API 密钥的配置。按照提示选择提供商并输入您的密钥。
3. 环境变量 — 对于 DashScope，您可以在 shell 中或工作目录下的 .env 文件中设置 DASHSCOPE_API_KEY。

需要额外密钥的工具（例如用于网络搜索的 TAVILY_API_KEY）可以在控制台的 设置 → 环境变量 中进行设置，详情请参阅配置。

仅使用本地模型？ 如果您使用本地模型（llama.cpp / Ollama / LM Studio），则无需任何 API 密钥。

本地模型

QwenPaw 可以在您的设备上完全运行大模型，无需任何 API 密钥或云服务。详情请参阅官方文档。

文档

完整文档位于此仓库：website/public/docs/。

安全特性

QwenPaw 包含多层安全机制，以保护您的数据和系统：

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

详细信息请参阅安全文档。

常见问题解答

有关常见问题、故障排除技巧及已知问题，请访问**FAQ 页面**。

保持关注

在 GitHub 上为 QwenPaw 点赞，即可第一时间获取新版本通知。

Roadmap

Status: In Progress — actively being worked on; Planned — queued or under design, also welcome contributions; Seeking Contributors — we strongly encourage community contributions.

Install from source

git clone https://github.com/agentscope-ai/QwenPaw.git
cd QwenPaw

# Build console frontend first (required for web UI)
cd console && npm ci && npm run build
cd ..

# Copy console build output to package directory
mkdir -p src/qwenpaw/console
cp -R console/dist/. src/qwenpaw/console/

# Install Python package
pip install -e .

• Dev (tests, formatting): pip install -e ".[dev,full]"
• Then: Run qwenpaw init --defaults, then qwenpaw app.

Note for updates: When updating to a new major version after git pull, please also rebuild the frontend, reinstall the package (pip install -e .), restart qwenpaw app, and clear your browser cache with Ctrl+Shift+R (or Cmd+Shift+R on macOS).

Contributing

QwenPaw evolves through open collaboration, and we welcome all forms of contribution! Check the Roadmap above (especially items marked Seeking Contributors) to find areas that interest you, and read CONTRIBUTING to get started. We particularly welcome:

• Horizontal expansion — new channels, model providers, skills, MCPs.
• Existing feature extension & refinement — display and interaction improvements, download hints, Windows path compatibility, etc.

Join GitHub Discussions to discuss ideas or pick up tasks.

Why QwenPaw?

QwenPaw stands for Qwen Personal Agent Workstation, and also embodies the wisdom of Qwen and the warmth of a Paw. We hope it is not a cold tool, but an intelligent and warm "little paw" always ready to help—a most intuitive partner in your digital life.

Built by

AgentScope team · AgentScope · AgentScope Runtime · ReMe

Contact us

Discord	X (Twitter)	DingTalk	RedNote

Telemetry

QwenPaw collects anonymous usage data during qwenpaw init to help us understand our user base and prioritize improvements. Data is sent once per version — when you upgrade QwenPaw, telemetry is re-collected so we can track version adoption.

What we collect:

• QwenPaw version (e.g., 0.0.7)
• Install method (pip, Docker, or desktop app)
• OS and version (e.g., macOS 14.0, Ubuntu 22.04)
• Python version (e.g., 3.13)
• CPU architecture (e.g., x86_64, arm64)
• GPU availability (yes/no)

What we do NOT collect: No personal data, no files, no credentials, no IP addresses, no identifiable information.

When running qwenpaw init interactively, you will be asked whether to opt in. If you choose --defaults, telemetry is accepted automatically. The prompt appears once per version and never affects QwenPaw's functionality.

License

QwenPaw is released under the Apache License 2.0.

Contributors

All thanks to our contributors: