<div align="center">

# QwenPaw

[![GitHub Repo](https://img.shields.io/badge/GitHub-Repo-black.svg?logo=github)](https://github.com/agentscope-ai/QwenPaw)
[![PyPI](https://img.shields.io/pypi/v/qwenpaw?color=3775A9&label=PyPI&logo=pypi)](https://pypi.org/project/qwenpaw/)
[![Documentation](https://img.shields.io/badge/Docs-Website-green.svg?logo=readthedocs&label=Docs)](https://qwenpaw.agentscope.io/)
[![Python Version](https://img.shields.io/badge/python-3.11%20~%20%3C3.14-blue.svg?logo=python&label=Python)](https://www.python.org/downloads/)
[![Last Commit](https://img.shields.io/github/last-commit/agentscope-ai/QwenPaw)](https://github.com/agentscope-ai/QwenPaw)
[![License](https://img.shields.io/badge/license-Apache%202.0-red.svg?logo=apache&label=License)](LICENSE)
[![Code Style](https://img.shields.io/badge/code%20style-black-black.svg?logo=python&label=CodeStyle)](https://github.com/psf/black)
[![GitHub Stars](https://img.shields.io/github/stars/agentscope-ai/QwenPaw?style=flat&logo=github&color=yellow&label=Stars)](https://github.com/agentscope-ai/QwenPaw/stargazers)
[![GitHub Forks](https://img.shields.io/github/forks/agentscope-ai/QwenPaw?style=flat&logo=github&color=purple&label=Forks)](https://github.com/agentscope-ai/QwenPaw/network)
[![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask_Devin-navy.svg?logo=data:image/png;base64, )](https://deepwiki.com/agentscope-ai/QwenPaw)
[![Discord](https://img.shields.io/badge/Discord-Join_Us-blueviolet.svg?logo=discord)](https://discord.gg/eYMpfnkG8h)
[![X](https://img.shields.io/badge/X-Follow_Us-black.svg?logo=x)](https://x.com/agentscope_ai)
[![DingTalk](https://img.shields.io/badge/DingTalk-Join_Us-orange.svg)](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)
[![AgentScope Platform](https://img.shields.io/badge/%E2%98%81_AgentScope_Platform-%F0%9F%90%BE_7%2F24_Online_%26_Free-FF6B2B.svg)](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>

[[Tài liệu](https://qwenpaw.agentscope.io/)] [[English](README.md)] [[中文](README_zh.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>Phục vụ bạn, đồng hành cùng bạn.</b></p>

</div>

Trợ lý AI cá nhân của bạn — triển khai cục bộ hoặc trên đám mây, mở rộng bằng Skills & Plugins, kết nối trên mọi kênh.

| | |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Không bao giờ quên**                       | Bộ nhớ ba lớp — ngữ cảnh làm việc trực tiếp, lịch sử nguyên văn đầy đủ và tri thức đã chưng cất. Các lượt cũ bị loại khỏi cửa sổ nhưng vẫn truy xuất theo yêu cầu; không bị tóm tắt hay mất mát.     |
| **Cục bộ hoặc đám mây, chạy tự do**          | Mô hình QwenPaw-Flash (2B / 4B / 9B) huấn luyện cho tác vụ tác nhân. Runtime QwenPaw Local tích hợp sẵn — không cần API key, không phụ thuộc đám mây. Cũng hỗ trợ Ollama, LM Studio hoặc 14+ nhà cung cấp đám mây.   |
| **Bảo mật tích hợp sẵn**                     | Sandbox cấp kernel, Tool Guard, File Guard và Skill Scanner. Lệnh nguy hiểm bị chặn trước khi chạy.                                            |
| **Đa tác nhân & song song**                  | Tạo tác nhân độc lập với bộ nhớ và Skills riêng. Tác nhân con lúc chạy. Agent Communication Protocol (ACP) để điều phối liên hệ thống.                               |
| **Coding Mode**                              | Web IDE ba khung với cây tệp, xem trước diff và chat. Nhảy tới định nghĩa, tìm tham chiếu và tìm kiếm mã cấu trúc tích hợp sẵn.                                              |
| **Mở rộng**                                  | Skills cho lập lịch, tài liệu, trình duyệt, tin tức và hơn thế. Kiến trúc plugin kèm chợ. Tích hợp MCP cho công cụ bên ngoài. Kết hợp thành quy trình theo mục đích.  |
| **Sẵn sàng mọi nơi**                      | DingTalk, Lark, WeChat, Discord, Telegram, iMessage, QQ — một instance, mọi kênh. Console, TUI và ứng dụng desktop để truy cập trực tiếp.                                            |
| **Của bạn, không phải của chúng tôi**        | Triển khai cục bộ — dữ liệu ở lại máy bạn. Không qua bên thứ ba lưu trữ, không tải dữ liệu lên.                                                                         |

> <details>
> <summary><b>Bạn có thể làm gì với QwenPaw</b></summary>
>
> <br>
>
> - **Tự động hóa & lập lịch**: Thiết lập tác vụ định kỳ — tóm tắt tin tức, tạo báo cáo, phát sóng đa kênh — tất cả theo lịch của bạn.
> - **Mã nguồn & phát triển**: Đọc, chỉnh sửa, review và kiểm thử mã trong dự án; Coding Mode giúp bạn nhanh chóng tìm và hiểu mã.
> - **Xử lý tài liệu**: Đọc, ghi và chuyển đổi tệp PDF, Word, Excel và PowerPoint.
> - **Thu thập thông tin**: Tìm kiếm web, theo dõi nguồn đăng ký, tóm tắt video và tìm thông tin trong cơ sở tri thức cá nhân.
> - **Vận hành đa kênh**: Đẩy cảnh báo, tóm tắt hoặc nội dung do AI tạo tới DingTalk, Lark, Discord, Telegram, v.v. — đồng thời hoặc theo từng kênh.
> - **Quy trình tùy chỉnh**: Kết hợp khả năng tích hợp sẵn, plugin và tác vụ định kỳ thành quy trình phù hợp với nhu cầu của bạn.
>
> </details>

---

## Tin Tức

- [2026-07-24] **v2.0.1** | Nền tảng mini-app PawApp, Agent Mode do người dùng chỉnh sửa, Oh-My-Paw plugins, nâng cấp bộ nhớ ReMe, cải thiện UX desktop v.v. [Ghi chú phát hành v2.0.1 →](https://qwenpaw.agentscope.io/release-notes#v2.0.1)

- [2026-07-10] **v2.0.0 — QwenPaw 2.0 Official Release** 🎉 | Viết lại toàn bộ dựa trên AgentScope 2.0: kiến trúc Agent OS, Loop Engineering, Scroll Context, ReMe v0.4.0 Long-term Memory và TUI tích hợp.

  | Nổi bật | Nội dung mới |
  |-----------|------------|
  | **Agent OS — Workspace** | Ba trụ cột mỗi agent: **Resources** (lưu trữ minh bạch trên đĩa), **Governance** (allow/deny/ask/sandbox), **Sandbox** (macOS / Linux / Windows). |
  | **Agent OS — Drivers** | Lớp connector trung lập giao thức MCP / A2A / ACP với credentials mã hóa và policy gate mỗi lần gọi. |
  | **Loop Engineering** | Mẫu vòng lặp agent nâng cao (Coding Mode, Mission Mode, thêm nhiều sắp tới) với cổng phê duyệt kết hợp. |
  | **Scroll Context** | Mọi lượt được lưu trữ; lượt bị đẩy ra có chỉ mục, recall theo yêu cầu — không tóm tắt, không mất. |
  | **ReMe v0.4.0 Long-term Memory** | Theo dõi tự động theo lượt, tìm kiếm nhận biết mức sử dụng, embedding riêng backend. |
  | **Terminal UI (TUI)** | Chat terminal toàn màn hình — cùng agent, bộ nhớ và phiên với Console và kênh. |

  Dựa trên Agent OS, chúng tôi sẽ ra mắt các ứng dụng QwenPaw sẵn sàng sử dụng — như **QwenPaw Creator** và **QwenPaw Insight** — hãy theo dõi. [v2.0.0 Release Notes →](https://qwenpaw.agentscope.io/release-notes#v2.0.0)

- [2026-06-17] **v1.1.12 — Trang Mô Hình Đổi Mới & Chế Độ Đơn Giản** | Trang mô hình thiết kế lại với tổng hợp nhà cung cấp; Chế độ Đơn giản mới. [Ghi chú phát hành v1.1.12 →](https://qwenpaw.agentscope.io/release-notes#v1.1.12)

- [2026-06-11] **AgentScope Platform ra mắt** — Triển khai QwenPaw miễn phí, chia sẻ plugin và Chợ Skills. [Dùng thử ngay →](https://platform.agentscope.io/)

- [2026-06-10] **v1.1.11** — OAuth Mô hình Miễn phí, Chợ Plugin, Danh sách trắng MCP. [Ghi chú phát hành v1.1.11 →](https://qwenpaw.agentscope.io/release-notes#v1.1.11)

[Tất cả ghi chú phát hành →](https://qwenpaw.agentscope.io/release-notes)

---

## Mục Lục

- [Tin Tức](#tin-tức)
- [Bắt Đầu Nhanh](#bắt-đầu-nhanh)
- [API Key](#api-key)
- [Mô Hình Địa Phương](#mô-hình-địa-phương)
- [Tính Năng Bảo Mật](#tính-năng-bảo-mật)
- [Tài Liệu](#tài-liệu)
- [Câu Hỏi Thường Gặp](#câu-hỏi-thường-gặp)
- [Lộ Trình Phát Triển](#lộ-trình-phát-triển)
- [Đóng Góp](#đóng-góp)
- [Cài Đặt Từ Mã Nguồn](#cài-đặt-từ-mã-nguồn)
- [Tại Sao Là QwenPaw?](#tại-sao-là-qwenpaw)
- [Được Xây Dựng Bởi](#được-xây-dựng-bởi)
- [Giấy Phép](#giấy-phép)

---

## Bắt Đầu Nhanh

### Tùy Chọn 1: Pip Install

Nếu bạn thích tự quản lý Python (yêu cầu Python >= 3.11, < 3.14):

```bash
pip install qwenpaw
qwenpaw init --defaults
qwenpaw app
```

Sau đó mở Console trong trình duyệt tại **http://127.0.0.1:8088/** để cấu hình mô hình. Để chat trong DingTalk, Lark, WeChat, v.v., xem tài liệu [Thiết lập kênh](https://qwenpaw.agentscope.io/docs/channels).

![Console](https://img.alicdn.com/imgextra/i2/O1CN01EP1ra01iOAcBvF0TC_!!6000000004402-2-tps-3822-2070.png)

---

### Tùy Chọn 2: Cài Đặt Bằng Script

Không cần thiết lập Python thủ công, một lệnh duy nhất cài đặt mọi thứ. Script sẽ tự động tải xuống uv (trình quản lý gói Python), tạo môi trường ảo, và cài đặt QwenPaw với tất cả phụ thuộc (bao gồm Node.js và tài nguyên frontend). Lưu ý: Có thể không hoạt động trong môi trường mạng bị hạn chế hoặc tường lửa doanh nghiệp.

**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
```

> **Lưu ý**: Trình cài đặt sẽ tự động kiểm tra trạng thái của uv. Nếu chưa được cài đặt, nó sẽ cố gắng tải xuống và cấu hình tự động. Nếu quá trình cài đặt tự động thất bại, vui lòng làm theo hướng dẫn trên màn hình hoặc thực thi `python -m pip install -U uv`, sau đó chạy lại trình cài đặt.

> **⚠️ Thông báo đặc biệt cho người dùng Windows Enterprise LTSC**
>
> Nếu bạn đang sử dụng Windows LTSC hoặc môi trường doanh nghiệp bị ràng buộc bởi chính sách bảo mật nghiêm ngặt, PowerShell có thể chạy ở **Chế độ Ngôn ngữ Hạn chế (Constrained Language Mode)**, gây ra các vấn đề sau:
> 1. **Nếu dùng CMD (.bat): Script thực thi thành công nhưng không ghi được vào `Path`**
>
>    Script đã hoàn tất cài đặt tệp. Do **Chế độ Ngôn ngữ Hạn chế**, nó không thể tự động cập nhật biến môi trường. Hãy cấu hình thủ công như sau:
>    - **Xác định thư mục cài đặt**:
>      - Kiểm tra `uv` có sẵn không: Nhập `uv --version` trong CMD. Nếu có số phiên bản, **chỉ cần cấu hình đường dẫn QwenPaw**. Nếu nhận được thông báo `'uv' không được nhận dạng là lệnh nội bộ hay bên ngoài, chương trình có thể thực thi hay tệp lệnh,` hãy cấu hình cả hai đường dẫn.
>      - Đường dẫn uv (chọn một tùy vị trí cài đặt; dùng khi `uv` không khả dụng): Thường là `%USERPROFILE%\.local\bin`, `%USERPROFILE%\AppData\Local\uv`, hoặc thư mục `Scripts` trong thư mục cài đặt Python
>      - Đường dẫn QwenPaw: Thường nằm tại `%USERPROFILE%\.qwenpaw\bin`.
>    - **Thêm thủ công vào biến môi trường Path của hệ thống**:
>      - Nhấn `Win + R`, gõ `sysdm.cpl` và nhấn Enter để mở System Properties.
>      - Nhấp "Advanced" -> "Environment Variables".
>      - Trong "System variables", tìm và chọn `Path`, sau đó nhấp "Edit".
>      - Nhấp "New", lần lượt nhập cả hai đường dẫn thư mục, sau đó nhấp OK để lưu.
> 2. **Nếu dùng PowerShell (.ps1): Script bị gián đoạn**
>
>   Do **Chế độ Ngôn ngữ Hạn chế**, script có thể không tự động tải xuống được `uv`.
>   - **Cài đặt uv thủ công**: Tham khảo [GitHub Release](https://github.com/astral-sh/uv/releases) để tải `uv.exe` và đặt vào `%USERPROFILE%\.local\bin` hoặc `%USERPROFILE%\AppData\Local\uv`; hoặc đảm bảo Python đã được cài đặt và chạy `python -m pip install -U uv`.
>   - **Cấu hình biến môi trường `uv`**: Thêm thư mục chứa `uv` và `%USERPROFILE%\.qwenpaw\bin` vào biến `Path` của hệ thống.
>   - **Chạy lại trình cài đặt**: Mở terminal mới và thực thi lại script cài đặt để hoàn tất cài đặt `QwenPaw`.
>   - **Cấu hình biến môi trường `QwenPaw`**: Thêm `%USERPROFILE%\.qwenpaw\bin` vào biến `Path` của hệ thống.

Sau khi cài đặt, mở terminal mới và chạy:

```bash
qwenpaw init --defaults   # hoặc: qwenpaw init (tương tác)
qwenpaw app
```

<details>
<summary><b>Tùy chọn cài đặt</b></summary>

**macOS / Linux:**

```bash
# Cài đặt phiên bản cụ thể
curl -fsSL ... | bash -s -- --version 1.1.0

# Cài đặt từ mã nguồn (dev/testing)
curl -fsSL ... | bash -s -- --from-source

# Nâng cấp — chỉ cần chạy lại trình cài đặt
curl -fsSL ... | bash

# Gỡ cài đặt
qwenpaw uninstall          # giữ lại cấu hình và dữ liệu
qwenpaw uninstall --purge  # xóa mọi thứ
```

**Windows (PowerShell):**

```powershell
# Cài đặt phiên bản cụ thể
irm ... | iex; .\install.ps1 -Version 1.1.12

# Cài đặt từ mã nguồn (dev/testing)
.\install.ps1 -FromSource

# Nâng cấp — chỉ cần chạy lại trình cài đặt
irm ... | iex

# Gỡ cài đặt
qwenpaw uninstall          # giữ lại cấu hình và dữ liệu
qwenpaw uninstall --purge  # xóa mọi thứ
```

</details>


---

### Tùy Chọn 3: Docker

Image có trên **Docker Hub** (`agentscope/qwenpaw`). Tag image: `latest` (ổn định); `pre` (bản phát hành thử nghiệm 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
```

Cũng có sẵn trên Alibaba Cloud Container Registry (ACR) cho người dùng tại Trung Quốc: `agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw` (cùng tag).

Sau đó mở **http://127.0.0.1:8088/** để truy cập Console. Cấu hình, bộ nhớ và Skills được lưu trong volume `qwenpaw-data`; cài đặt nhà cung cấp mô hình và API key được lưu trong volume `qwenpaw-secrets`; các bản sao lưu được lưu trong volume `qwenpaw-backups`. Để truyền API key (ví dụ: `DASHSCOPE_API_KEY`), thêm `-e VAR=value` hoặc `--env-file .env` vào lệnh `docker run`.

> **Kết nối với Ollama hoặc các dịch vụ khác trên máy chủ**
>
> Bên trong container Docker, `localhost` trỏ đến chính container, không phải máy chủ của bạn. Nếu bạn chạy Ollama (hoặc các dịch vụ mô hình khác) trên máy chủ và muốn QwenPaw trong Docker truy cập được, hãy sử dụng một trong các cách sau:
>
> **Cách A** — Gắn kết máy chủ rõ ràng (mọi nền tảng):
> ```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
> ```
> Sau đó trong QwenPaw **Settings → Models**, thay đổi Base URL thành `http://host.docker.internal:<port>` — ví dụ: `http://host.docker.internal:11434` cho Ollama, hoặc `http://host.docker.internal:1234/v1` cho LM Studio.
>
> **Cách B** — Mạng máy chủ (chỉ 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
> ```
> Không cần ánh xạ cổng (`-p`); container chia sẻ trực tiếp mạng máy chủ. Lưu ý rằng tất cả cổng của container đều được lộ ra trên máy chủ, có thể gây xung đột nếu cổng đã được sử dụng.
>

Image được xây dựng từ đầu. Để tự xây dựng image, vui lòng tham khảo phần [Build Docker image](scripts/README.md#build-docker-image) trong `scripts/README.md`, sau đó đẩy lên registry của bạn.

---

### Tùy Chọn 4: Triển Khai Trên Alibaba Cloud ECS

Để chạy QwenPaw trên Alibaba Cloud (ECS), sử dụng triển khai một chạm: mở [đường dẫn triển khai QwenPaw trên Alibaba Cloud (ECS)](https://computenest.console.aliyun.com/service/instance/create/cn-hangzhou?type=user&ServiceId=service-1ed84201799f40879884) và làm theo hướng dẫn. Để biết hướng dẫn từng bước, xem [Alibaba Cloud Developer: Triển khai trợ lý AI trong 3 phút](https://developer.aliyun.com/article/1713682).

---

### Tùy Chọn 5: AgentScope Platform

[AgentScope Platform](https://platform.agentscope.io/) cung cấp triển khai QwenPaw trên đám mây một chạm, chia sẻ plugin và Chợ Skills. Miễn phí, trực tuyến 7/24.

---

### Tùy Chọn 6: Sử Dụng ModelScope

[ModelScope Studio](https://modelscope.cn/studios/fork?target=AgentScope/QwenPaw) cũng hỗ trợ triển khai QwenPaw trên đám mây. Lưu ý: đặt Studio của bạn ở chế độ **không công khai** để người khác không thể điều khiển QwenPaw của bạn.

---

### Tùy Chọn 7: Ứng Dụng Desktop (Beta)

> **Thông báo Beta**: Ứng dụng desktop hiện đang trong giai đoạn thử nghiệm Beta với các hạn chế đã biết sau:
> - **Kiểm tra tương thích chưa đầy đủ**: Chưa được kiểm tra đầy đủ trên tất cả các phiên bản hệ thống và cấu hình phần cứng
> - **Có thể có vấn đề về hiệu suất**: Thời gian khởi động, sử dụng bộ nhớ và các khía cạnh hiệu suất khác có thể cần tối ưu thêm
> - **Tính năng đang phát triển**: Một số tính năng có thể không ổn định hoặc bị thiếu

Nếu bạn không quen với công cụ dòng lệnh, bạn có thể tải xuống và sử dụng ứng dụng desktop của QwenPaw mà không cần cấu hình môi trường Python thủ công hay chạy lệnh.

#### Tải Xuống

Tải ứng dụng desktop (bản Tauri) từ [trang tải xuống chính thức](https://qwenpaw.agentscope.io/downloads):
- **Windows**: `QwenPaw-Tauri-<version>-Windows-setup.exe`
- **macOS**: `QwenPaw-Tauri-<version>-macOS.zip` (khuyên dùng Apple Silicon)

#### Tính Năng

- ✅ **Không cấu hình**: Tải về và nhấp đúp để chạy, không cần cài Python hay cấu hình biến môi trường
- ✅ **Đa nền tảng**: Hỗ trợ Windows 10+ và macOS 14+
- ✅ **Giao diện trực quan**: Tự động mở cửa sổ ứng dụng, không cần nhập địa chỉ thủ công
- ⚠️ **Giai đoạn Beta**: Các tính năng đang được liên tục cải thiện, rất mong nhận phản hồi

#### Lần Đầu Khởi Động

**Quan trọng**: Lần đầu khởi động có thể mất 10-60 giây (tùy thuộc vào cấu hình hệ thống của bạn). Ứng dụng cần khởi tạo môi trường Python và tải các phụ thuộc. Vui lòng kiên nhẫn chờ cửa sổ tự động mở.

#### macOS: Vượt Qua Rào Cản Bảo Mật Hệ Thống

Khi bạn tải ứng dụng macOS QwenPaw từ Releases, macOS có thể hiển thị: *"Apple không thể xác minh rằng 'QwenPaw' không chứa phần mềm độc hại"*. Điều này xảy ra vì ứng dụng chưa được notarization. Bạn vẫn có thể mở nó như sau:

- **Nhấp chuột phải để mở (khuyên dùng)**
  Nhấp chuột phải (hoặc Control+click) vào ứng dụng QwenPaw → **Open** → trong hộp thoại, nhấp **Open** lần nữa. Thao tác này báo cho Gatekeeper rằng bạn tin tưởng ứng dụng; sau đó bạn có thể nhấp đúp để khởi chạy như bình thường.

- **Cho phép trong System Settings**
  Nếu vẫn bị chặn, vào **System Settings → Privacy & Security**, cuộn đến thông báo như *"QwenPaw was blocked because it is from an unidentified developer"*, và nhấp **Open Anyway** hoặc **Allow**.

- **Xóa thuộc tính cách ly (không khuyên dùng cho hầu hết người dùng)**
  Trong Terminal chạy:
  `xattr -cr "/Applications/QwenPaw Desktop.app"`
  (hoặc dùng đường dẫn tới tệp `.app` sau khi giải nén). Thao tác này xóa cờ cách ly "đã tải xuống từ internet" để cảnh báo thường không xuất hiện, nhưng kém an toàn và kiểm soát hơn so với dùng **Nhấp chuột phải → Open**.

Để biết hướng dẫn sử dụng chi tiết, khắc phục sự cố và các vấn đề thường gặp, xem [Hướng dẫn ứng dụng Desktop](https://qwenpaw.agentscope.io/docs/desktop).

---

### Tiếp Theo?

Sau khi cài đặt, cấu hình mô hình trong **Console → Settings → Models**, rồi khám phá:

- [Thêm Skills](https://qwenpaw.agentscope.io/docs/skills) để mở rộng khả năng (PDF, Office, trình duyệt, tin tức, v.v.)
- [Thiết lập Kênh](https://qwenpaw.agentscope.io/docs/channels) cho DingTalk, Lark, Discord, v.v.
- [Cấu hình Cron](https://qwenpaw.agentscope.io/docs/cron) cho tác vụ định kỳ và tự động hóa
- [Thử Coding Mode](https://qwenpaw.agentscope.io/docs/coding-mode) để hợp tác mã nguồn kiểu IDE
- Xem [hướng dẫn Bắt đầu nhanh](https://qwenpaw.agentscope.io/docs/quickstart) đầy đủ cho mọi tùy chọn và bước xác minh

---

## Terminal UI (TUI)

Muốn ở lại terminal? Chạy `qwenpaw` để mở **TUI** chat toàn màn hình, điều khiển _cùng_ tác nhân với Console và các Kênh IM — cùng bộ nhớ, Skills, công cụ MCP và phiên — mà không rời bàn phím.

```bash
qwenpaw                     # mở chat với tác nhân đang hoạt động
qwenpaw tui --resume <id>   # tiếp tục phiên trước
qwenpaw .                   # bắt đầu trong repo hiện tại (Coding Mode)
```

Hỗ trợ phản hồi streaming, lệnh slash (`/help`, `/resume`, `/theme`, cùng các lệnh riêng của tác nhân như `/model`, `/clear`, …), dán tệp/văn bản dài làm đính kèm, và nhắc quyền công cụ nội tuyến. Xem [hướng dẫn Terminal UI](https://qwenpaw.agentscope.io/docs/tui) để biết chi tiết.

![QwenPaw TUI](https://img.alicdn.com/imgextra/i2/O1CN01IULzib1TRAzigIcqG_!!6000000002378-2-tps-2350-1312.png)

---

## API Key

Nếu bạn sử dụng **API LLM đám mây** (ví dụ: DashScope / Qwen, OpenAI, Anthropic, Google Gemini, DeepSeek, Kimi, OpenRouter, v.v.), bạn phải cấu hình API key trước khi chat. QwenPaw sẽ không hoạt động cho đến khi có key hợp lệ. Xem [tài liệu chính thức](https://qwenpaw.agentscope.io/docs/models) để biết chi tiết.

**Cách cấu hình:**

1. **Console (khuyên dùng)** — Sau khi chạy `qwenpaw app`, mở **http://127.0.0.1:8088/** → **Settings** → **Models**. Chọn nhà cung cấp, nhập **API Key**, và kích hoạt nhà cung cấp cùng mô hình đó.
2. **`qwenpaw init`** — Khi chạy `qwenpaw init`, bạn sẽ được hướng dẫn cấu hình nhà cung cấp LLM và API key. Làm theo lời nhắc để chọn nhà cung cấp và nhập key.
3. **Biến môi trường** — Với DashScope bạn có thể đặt `DASHSCOPE_API_KEY` trong shell hoặc trong tệp `.env` trong thư mục làm việc.

Các công cụ cần key bổ sung (ví dụ: `TAVILY_API_KEY` cho tìm kiếm web) có thể được đặt trong Console **Settings → Environment variables**, xem [Config](https://qwenpaw.agentscope.io/docs/config) để biết chi tiết.

> **Chỉ dùng mô hình địa phương?** Nếu bạn sử dụng [Mô Hình Địa Phương](#mô-hình-địa-phương) (QwenPaw Local (llama.cpp) / Ollama / LM Studio), bạn **không** cần bất kỳ API key nào.

## Mô Hình Địa Phương

QwenPaw có thể chạy LLM hoàn toàn trên máy của bạn — không cần API key hoặc dịch vụ đám mây. Xem [tài liệu chính thức](https://qwenpaw.agentscope.io/docs/models) để biết chi tiết.

QwenPaw cũng cung cấp dòng **QwenPaw-Flash** — mô hình 2B / 4B / 9B huấn luyện chuyên biệt cho kịch bản tác nhân, với lượng tử hóa Q4 và Q8. Có sẵn trên [ModelScope](https://www.modelscope.cn/organization/AgentScope?tab=model) và [Hugging Face](https://huggingface.co/agentscope-ai/models).

| Backend              | Phù hợp nhất cho                                 | Cài đặt                                                              |
| -------------------- | ---------------------------------------------- | -------------------------------------------------------------------- |
| **QwenPaw Local** (llama.cpp) | Đa nền tảng (macOS / Linux / Windows)          | Tích hợp sẵn; nhấp "Download" trong giao diện web. Hỗ trợ QwenPaw-Flash với gợi ý theo phần cứng. |
| **Ollama**           | Đa nền tảng (cần dịch vụ Ollama)               | Cài đặt và khởi động Ollama; đặt độ dài ngữ cảnh ≥ 32k. |
| **LM Studio**        | Đa nền tảng (cần dịch vụ LM Studio)            | Cài đặt và khởi động LM Studio; bật Local Server. |

---

## Tính Năng Bảo Mật

QwenPaw bao gồm bốn lớp bảo mật cốt lõi:

- **Sandbox** — Cách ly thực thi cấp kernel bằng Seatbelt (macOS), Bubblewrap / Landlock (Linux) và AppContainer (Windows). Lệnh shell chạy trong phạm vi hệ thống tệp bị hạn chế.
- **Tool Guard** — Công cụ quy tắc YAML với `ShellEvasionGuardian` kiểm tra mọi lệnh gọi công cụ trước khi thực thi, phát hiện command injection, path traversal, reverse shell và tấn công che giấu. Mức phê duyệt cấu hình được: STRICT / SMART / AUTO / OFF.
- **File Guard** — Độc lập với Tool Guard; chặn tác nhân truy cập tệp và thư mục nhạy cảm (mặc định bảo vệ `~/.qwenpaw.secret/`, `~/.ssh`, v.v.).
- **Skill Scanner** — Quét trước khi kích hoạt với chế độ block / warn / off và hỗ trợ danh sách trắng. Phát hiện prompt injection, khóa nhúng cứng, rò rỉ dữ liệu, v.v.
Xem [Bảo mật](https://qwenpaw.agentscope.io/docs/security) để biết chi tiết.

---

## Tài Liệu

| Chủ đề                                                                 | Mô tả                                               |
| --------------------------------------------------------------------- | --------------------------------------------------- |
| [Giới thiệu](https://qwenpaw.agentscope.io/docs/intro)                | QwenPaw là gì và cách sử dụng                         |
| [Bắt đầu nhanh](https://qwenpaw.agentscope.io/docs/quickstart)        | Cài đặt và chạy (cục bộ hoặc ModelScope Studio)      |
| [Console](https://qwenpaw.agentscope.io/docs/console)                 | Giao diện Web: chat và cấu hình tác nhân              |
| [Terminal UI (TUI)](https://qwenpaw.agentscope.io/docs/tui)             | Chat terminal toàn màn hình, cùng tác nhân với Console |
| [Ứng dụng Desktop](https://qwenpaw.agentscope.io/docs/desktop)               | Cài đặt và sử dụng ứng dụng desktop       |
| [Mô hình](https://qwenpaw.agentscope.io/docs/models)                  | Cấu hình nhà cung cấp đám mây, cục bộ và tùy chỉnh   |
| [Kênh](https://qwenpaw.agentscope.io/docs/channels)                   | DingTalk, Lark, QQ, Discord, iMessage, và hơn nữa  |
| [Coding Mode](https://qwenpaw.agentscope.io/docs/coding-mode)           | Web IDE ba khung cho tác vụ tập trung mã nguồn       |
| [Skills](https://qwenpaw.agentscope.io/docs/skills)                  | Mở rộng và tùy chỉnh khả năng                         |
| [Plugins](https://qwenpaw.agentscope.io/docs/plugins)                    | Hệ thống plugin và Chợ Plugin                  |
| [MCP](https://qwenpaw.agentscope.io/docs/mcp)                         | Quản lý máy khách MCP                                 |
| [Persona](https://qwenpaw.agentscope.io/docs/persona)                   | Tùy chỉnh tính cách tác nhân (SOUL / PROFILE)  |
| [Bộ nhớ](https://qwenpaw.agentscope.io/docs/memory)                   | Bộ nhớ ngữ nghĩa dài hạn (ReMe)                 |
| [Bộ nhớ tiến hóa & Chủ động](https://qwenpaw.agentscope.io/docs/memory-evolving-and-proactive) | Tác nhân tiến hóa bộ nhớ và tương tác chủ động       |
| [Ngữ cảnh](https://qwenpaw.agentscope.io/docs/context)               | Quản lý ngữ cảnh dựa trên cuộn (scroll)                  |
| [Lệnh ma thuật](https://qwenpaw.agentscope.io/docs/commands)         | Điều khiển trạng thái hội thoại mà không cần đợi AI   |
| [Nhịp tim](https://qwenpaw.agentscope.io/docs/heartbeat)             | Kiểm tra định kỳ và tóm tắt                           |
| [Cron / Tác Vụ Định Kỳ](https://qwenpaw.agentscope.io/docs/cron)       | Tác vụ định kỳ và tự động hóa                   |
| [Đa tác nhân](https://qwenpaw.agentscope.io/docs/multi-agent)        | Tạo nhiều tác nhân và kích hoạt hợp tác                    |
| [Bảo mật](https://qwenpaw.agentscope.io/docs/security)                  | Sandbox, tool guard, file guard, skill scanner, access policy |
| [Sao lưu & Khôi phục](https://qwenpaw.agentscope.io/docs/backup)           | Sao lưu và khôi phục dữ liệu                         |
| [Cấu hình & thư mục làm việc](https://qwenpaw.agentscope.io/docs/config) | Thư mục làm việc và tệp cấu hình                      |
| [REST API](https://qwenpaw.agentscope.io/docs/api-tutorial)             | HTTP API cho tích hợp và tự động hóa          |
| [Tích hợp ACP](https://qwenpaw.agentscope.io/docs/acp-integration)   | Tích hợp Agent Communication Protocol         |
| [CLI](https://qwenpaw.agentscope.io/docs/cli)                        | Init, cron jobs, Skills, dọn dẹp                    |
| [Thực hành Nhóm Tác Nhân](https://qwenpaw.agentscope.io/docs/practice-agent-team) | Hướng dẫn triển khai nhóm đa tác nhân           |
| [FAQ](https://qwenpaw.agentscope.io/docs/faq)                        | Câu hỏi thường gặp và khắc phục sự cố                 |

Tài liệu đầy đủ: [qwenpaw.agentscope.io/docs](https://qwenpaw.agentscope.io/docs)

---

## Câu Hỏi Thường Gặp

Đối với các câu hỏi thường gặp, mẹo khắc phục sự cố và các vấn đề đã biết, vui lòng truy cập **[trang FAQ](https://qwenpaw.agentscope.io/docs/faq)**.

---

## Lộ Trình Phát Triển

| Lĩnh vực                   | Mục                                                                                        | Trạng thái          |
| -------------------------- | ------------------------------------------------------------------------------------------ | ------------------- |
| **Mở rộng ngang**          | Thêm kênh, mô hình, Skills, MCP — **hoan nghênh đóng góp từ cộng đồng**                   | Đang kêu gọi đóng góp |
| **Mở rộng tính năng hiện có** | Tối ưu hiển thị, gợi ý tải xuống, tương thích đường dẫn Windows — **hoan nghênh đóng góp** | Đang kêu gọi đóng góp |
| **Mô hình**                | Chuyển đổi đa mô hình                                                                       | Đang thực hiện      |
| **Browser-use**            | Hỗ trợ tiện ích mở rộng Chrome                                                              | Đang thực hiện      |
| **Bộ nhớ dài hạn**        | Cơ sở tri thức cá nhân                                                                      | Đang thực hiện      |
| **Ứng dụng QwenPaw**      | QwenPaw Creator                                                                             | Đang thực hiện      |
|                            | QwenPaw Insight                                                                             | Đang thực hiện      |
| **Đa tác nhân**            | Tương thích với các tác nhân hiện có (ví dụ: Claude Code)                                  | Đã lên kế hoạch     |
|                            | Chat nhóm                                                                                   | Đã lên kế hoạch     |
|                            | Trực quan hóa tác nhân con                                                                  | Đã lên kế hoạch     |

_Trạng thái:_ **Đang thực hiện** — đang tích cực phát triển; **Đã lên kế hoạch** — đã xếp hàng hoặc đang thiết kế, cũng hoan nghênh đóng góp; **Đang kêu gọi đóng góp** — chúng tôi khuyến khích đóng góp từ cộng đồng.

---

## Đóng Góp

QwenPaw phát triển thông qua hợp tác mở, và chúng tôi hoan nghênh mọi hình thức đóng góp! Xem [Lộ Trình Phát Triển](#lộ-trình-phát-triển) ở trên (đặc biệt là các mục được đánh dấu **Đang kêu gọi đóng góp**) để tìm lĩnh vực bạn quan tâm, và đọc [CONTRIBUTING](https://github.com/agentscope-ai/QwenPaw/blob/main/CONTRIBUTING.md) để bắt đầu. Chúng tôi đặc biệt hoan nghênh:

- **Mở rộng ngang** — kênh mới, nhà cung cấp mô hình, Skills, MCP.
- **Mở rộng & hoàn thiện tính năng hiện có** — cải thiện hiển thị và tương tác, gợi ý tải xuống, tương thích đường dẫn Windows, v.v.

Tham gia [GitHub Discussions](https://github.com/agentscope-ai/QwenPaw/discussions) để thảo luận ý tưởng hoặc nhận nhiệm vụ.

---

## Cài Đặt Từ Mã Nguồn

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

# Xây dựng frontend console trước (cần cho giao diện web)
cd console && npm ci && npm run build
cd ..

# Sao chép đầu ra build console vào thư mục gói
mkdir -p src/qwenpaw/console
cp -R console/dist/. src/qwenpaw/console/

# Cài đặt gói Python
pip install -e .
```

- **Dev** (kiểm thử, định dạng): `pip install -e ".[dev,full]"`
- **Sau đó**: Chạy `qwenpaw init --defaults`, rồi `qwenpaw app`.

> **Lưu ý khi cập nhật:** Khi cập nhật lên phiên bản chính mới sau `git pull`, vui lòng xây dựng lại frontend, cài đặt lại gói (`pip install -e .`), khởi động lại `qwenpaw app`, và xóa bộ nhớ đệm trình duyệt với `Ctrl+Shift+R` (hoặc `Cmd+Shift+R` trên macOS).

---

## Tại Sao Là QwenPaw?

QwenPaw là viết tắt của Qwen Personal Agent Workstation, đồng thời thể hiện trí tuệ của Qwen và hơi ấm của một Paw (bàn chân).
Chúng tôi hy vọng nó không phải là một công cụ lạnh lẽo, mà là một "bàn chân nhỏ" thông minh và ấm áp luôn sẵn sàng giúp đỡ — người bạn đồng hành trực quan nhất trong cuộc sống số của bạn.

---

## Được Xây Dựng Bởi

[Nhóm 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)

---

## Liên Hệ

| [Discord](https://discord.gg/eYMpfnkG8h)                     | [X (Twitter)](https://x.com/agentscope_ai)                   | [DingTalk](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) | [RedNote](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="DingTalk">](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="RedNote">](https://www.xiaohongshu.com/user/profile/691c18db0000000037032be9) |

---

## Theo Dõi Cập Nhật

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

Star QwenPaw trên GitHub để nhận thông báo ngay lập tức về các bản phát hành mới.

---

## Telemetry

QwenPaw thu thập dữ liệu sử dụng **ẩn danh** trong quá trình `qwenpaw init` để giúp chúng tôi hiểu cơ sở người dùng và ưu tiên cải tiến. Dữ liệu được gửi **mỗi phiên bản một lần** — khi bạn nâng cấp QwenPaw, telemetry được thu thập lại để chúng tôi có thể theo dõi mức độ áp dụng phiên bản.

**Những gì chúng tôi thu thập:**

- Phiên bản QwenPaw (ví dụ: 1.1.12)
- Phương pháp cài đặt (pip, Docker, hoặc ứng dụng desktop)
- Hệ điều hành và phiên bản (ví dụ: macOS 14.0, Ubuntu 22.04)
- Phiên bản Python (ví dụ: 3.13)
- Kiến trúc CPU (ví dụ: x86_64, arm64)
- Khả năng GPU (có/không)

**Những gì chúng tôi KHÔNG thu thập:** Không có dữ liệu cá nhân, không có tệp, không có thông tin đăng nhập, không có địa chỉ IP, không có thông tin nhận dạng.

Khi chạy `qwenpaw init` ở chế độ tương tác, bạn sẽ được hỏi có đồng ý tham gia hay không. Nếu bạn chọn `--defaults`, telemetry sẽ tự động được chấp nhận. Lời nhắc xuất hiện một lần mỗi phiên bản và không bao giờ ảnh hưởng đến chức năng của QwenPaw.

---

## Giấy Phép

QwenPaw được phát hành theo [Giấy phép Apache 2.0](LICENSE).

---

## Người Đóng Góp

Xin cảm ơn tất cả những người đã đóng góp:

<a href="https://github.com/agentscope-ai/QwenPaw/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=agentscope-ai/QwenPaw" alt="Người đóng góp" />
</a>
