# agent-desktop: cho AI agent điều khiển app máy tính — hướng dẫn cài đặt và dùng

> agent-desktop là một CLI viết bằng Rust, cho AI agent "dùng máy tính": đọc giao diện ứng dụng dưới dạng JSON rồi click, gõ phím lên từng phần tử. Công cụ chạy trên macOS, Windows và Linux, cài bằng một lệnh npm. Phần cài khá đơn giản, nhưng bạn cần một agent (như Claude Code) để điều khiển nó.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-29 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/agent-desktop-ai-agent-dieu-khien-ung-dung-may-tinh

agent-desktop là một công cụ dòng lệnh (CLI) giúp AI agent nhìn thấy và điều khiển các ứng dụng trên máy tính của bạn, trên macOS, Windows và Linux. Thay vì chụp ảnh màn hình rồi đoán vị trí nút bấm, nó đọc "cây accessibility" của hệ điều hành và trả về JSON. Mỗi phần tử có thể bấm sẽ có một mã tham chiếu gọi là ref.

Repo này dành cho ai? Dành cho người đang dùng hoặc xây AI agent và muốn agent làm được việc trên ứng dụng desktop. Ví dụ: mở Finder, bấm nút, điền ô nhập, đọc nội dung cửa sổ. Dev mới cũng dùng được, vì cài chỉ cần npm. Nhân viên văn phòng thì nên có người hỗ trợ lần đầu, vì công cụ này nói chuyện với agent chứ không có giao diện bấm chuột.

Điểm đáng giá nhất: agent-desktop không chứa mô hình AI nào bên trong. Vòng lặp "nhìn, làm, kiểm tra lại" nằm ở agent của bạn, còn agent-desktop chỉ làm đôi mắt và đôi tay. Repo hiện có khoảng 22.696 sao và 1.683 fork, giấy phép Apache-2.0.

```repo
- repo | vercel-labs/agent-desktop
- kind | CLI
- desc | agent-desktop là công cụ dòng lệnh giúp AI agent nhìn và thao tác ứng dụng desktop trên macOS, Windows, Linux qua cây accessibility, không cần ảnh chụp màn hình.
- stars | 23k
- lang | Rust
- license | Apache-2.0
```

## agent-desktop làm được gì

- **Đọc giao diện bằng JSON, không cần ảnh chụp.** Lệnh `snapshot` trả về cây các phần tử của một ứng dụng. Agent không phải "nhìn ảnh rồi đoán", nên ít nhầm vị trí hơn.
- **Mỗi phần tử có một ref.** Agent chỉ cần nói "bấm vào ref này". Ref gắn với đúng lần snapshot đó, nên khi giao diện đổi, công cụ báo lỗi thay vì bấm nhầm.
- **Nhiều nhóm lệnh.** README ghi 61 tên lệnh, trong đó 57 lệnh dùng được. Có nhóm quan sát (`snapshot`, `find`, `get`, `screenshot`), nhóm thao tác (`click`, `type`, `set-value`, `toggle`, `scroll`), bàn phím và chuột (`press`, `hover`, `drag`), quản lý app và cửa sổ (`launch`, `list-windows`, `resize-window`), thông báo, clipboard và `wait`.
- **Chạy ngầm theo mặc định.** Thao tác qua ref dùng API accessibility, không di chuyển con trỏ chuột và không cướp focus. Nếu cần nhập liệu vật lý thì thêm cờ `--headed`.
- **Xử lý app có giao diện dày.** Với app nhiều phần tử như Slack, bạn lập bản đồ trước bằng `snapshot --skeleton`, rồi đào sâu vào một vùng bằng `--root`.
- **Phục vụ agent sẵn.** Có kèm skill, có chế độ MCP server (`agent-desktop mcp`), và có thư viện C cho ai muốn gọi trực tiếp trong chương trình.
- **Kiểm soát lỗi rõ ràng.** Mỗi lệnh in một "phong bì" JSON. Lỗi có mã như `STALE_REF` hay `AMBIGUOUS_TARGET`, kèm gợi ý có nên thử lại không.

## Cần chuẩn bị gì

Theo README, bạn cần một trong các hệ điều hành sau:

- **macOS:** 13 trở lên, chip Intel hoặc Apple Silicon.
- **Windows:** Windows 10 bản 1809 trở lên, x64 hoặc ARM64.
- **Linux:** Ubuntu 24.04 trở lên, x86_64 hoặc aarch64, dùng X11 hoặc Wayland.

Để cài bằng cách đơn giản nhất, bạn cần npm (đi kèm Node.js). README cũng nói Bun, Yarn, pnpm cài được cùng gói. Trên macOS và Linux còn có Homebrew. Trên macOS, bạn phải cấp quyền Accessibility cho công cụ. README chưa nêu yêu cầu về API key hay GPU, vì công cụ không chứa mô hình AI.

```note
Ảnh snapshot, nội dung clipboard, ảnh chụp màn hình và file debug có thể chứa thông tin riêng tư trên màn hình của bạn. Đừng đăng chúng lên log công khai hoặc đưa lên mạng.
```

## Cài đặt từng bước

```steps
- Cài gói | Dùng npm cài agent-desktop toàn cục
- Kiểm tra trạng thái | Chạy status để xem nền tảng và quyền
- Cấp quyền (macOS) | Chạy permissions --guide để được hướng dẫn cấp quyền Accessibility
- Nối với agent | Cài skill, hoặc bật chế độ MCP
```

### Cài gói bằng npm

Mở Terminal (macOS/Linux) hoặc PowerShell (Windows), rồi chạy:

```bash
npm install -g agent-desktop
```

Cờ `-g` nghĩa là cài toàn cục, để gõ `agent-desktop` ở thư mục nào cũng chạy được. Gói đã kèm sẵn bản chạy cho x64 và ARM64. Trên macOS và Linux bạn cũng có thể dùng Homebrew:

```bash
brew install agent-desktop
```

README ghi chưa có gói Scoop chính thức cho Windows. Nếu không muốn dùng JavaScript, bạn tải bản đóng gói phù hợp ở trang GitHub Releases và để file phụ trợ nằm cạnh file chạy.

### Kiểm tra trạng thái và quyền

```bash
agent-desktop status
```

Lệnh này in ra nền tảng, quyền và những bề mặt được hỗ trợ.

### Cấp quyền Accessibility trên macOS

```bash
agent-desktop permissions --guide
```

Lệnh này dẫn bạn từng bước cấp quyền Accessibility. Chưa cấp quyền thì công cụ không đọc được giao diện app.

### Nối với agent của bạn

Cách 1, cài skill vào agent (lệnh theo README):

```bash
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
```

Cách 2, thêm đoạn sau vào file `AGENTS.md` của dự án:

```markdown
Use `agent-desktop` to see and operate desktop apps. Before the first use, run
`agent-desktop skills get desktop` and `agent-desktop skills get platform`, and follow them.
```

Cách 3, dùng như MCP server. Thêm vào cấu hình MCP của agent:

```json
{ "mcpServers": { "agent-desktop": { "command": "agent-desktop", "args": ["mcp"] } } }
```

Lúc này mỗi lệnh trở thành một tool MCP, tên như `desktop_snapshot`, `desktop_click`.

Nếu muốn tự build từ mã nguồn, README chỉ dẫn sang trang Installation trên trang chủ dự án, nên bạn xem ở đó.

## Kiểm tra đã chạy được chưa

Chạy lại lệnh trạng thái:

```bash
agent-desktop status
```

Nếu nó in ra thông tin nền tảng, quyền và các bề mặt được hỗ trợ mà không báo lỗi, bạn đã cài xong. Sau đó thử vòng lặp mẫu của README, ví dụ với Finder trên macOS:

```bash
agent-desktop snapshot --app Finder -i
```

Kết quả mong đợi là một đoạn JSON có `"ok": true`, `"command": "snapshot"`, một `snapshot_id` và cây các phần tử, trong đó phần tử bấm được có `ref_id` dạng `@s8f3k2p9:e8`. Phần ref phía sau mỗi lần sẽ khác nhau.

## Dùng vào việc thật

### Thử vòng lặp nhìn, bấm, kiểm tra

Bối cảnh: bạn là dev mới, muốn hiểu agent-desktop hoạt động ra sao. Chạy ba lệnh theo README:

```bash
agent-desktop snapshot --app Finder -i
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i
```

Lệnh đầu liệt kê các phần tử tương tác của Finder, mỗi phần tử có ref. Lệnh hai bấm vào một ref lấy từ snapshot đó. Lệnh ba chụp lại để xác nhận kết quả. Bạn sẽ thấy cây giao diện đã đổi theo thao tác.

> Agent không đoán vị trí trên ảnh, nó bấm đúng phần tử bằng mã ref.
>
> — Ông T

### Cho agent thao tác app có nhiều phần tử

Bối cảnh: bạn muốn agent làm việc trong một app dày giao diện như Slack. Snapshot toàn bộ sẽ rất dài, nên làm hai bước theo README:

```bash
agent-desktop snapshot --skeleton --app Slack -i --compact
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact
```

Lệnh đầu cho bản đồ tổng quát. Lệnh hai chỉ đào vào một vùng bạn chọn bằng ref. Kết quả gọn hơn nhiều, agent đỡ tốn lượt đọc.

### Dùng làm MCP server cho trợ lý AI

Bối cảnh: bạn đã dùng một trợ lý AI có hỗ trợ MCP và muốn nó thao tác app trên máy. Thêm cấu hình MCP như ở phần cài đặt, rồi nhắn cho agent một câu mẫu:

```
Dùng agent-desktop để chụp snapshot ứng dụng Finder, tìm phần tử tên Documents rồi bấm vào nó. Sau đó chụp lại để xác nhận.
```

Agent sẽ gọi các tool như `desktop_snapshot` và `desktop_click`, nhận JSON và tự quyết bước tiếp theo.

### Nhập chữ nhạy cảm mà không lộ ra tham số lệnh

Bối cảnh: agent cần điền một đoạn văn bản vào ô nhập và bạn không muốn nó nằm trong tham số tiến trình. README cho các lệnh `type`, `set-value` và `clipboard-set` nhận cờ `--stdin`, tức là truyền chữ qua đường ống. README khuyên chạy các bước có bí mật thành lệnh riêng, đừng gộp vào `batch`. Chi tiết cú pháp, bạn xem bằng `agent-desktop type --help`.

## Lỗi hay gặp và cách xử lý

- **Báo `INVALID_ARGS` khi dùng `@e8`.** Ref phải gắn với snapshot, dạng `@s8f3k2p9:e8`. Hãy chép đủ cả phần snapshot id.
- **Báo `STALE_REF` hoặc `AMBIGUOUS_TARGET`.** Giao diện đã đổi so với lúc chụp. Chụp snapshot mới rồi dùng ref mới.
- **Báo `AMBIGUOUS_TARGET` vì app có nhiều cửa sổ.** Xem danh sách window id trong `error.details` của snapshot, rồi truyền một id qua `--window-id`.
- **Không đọc được giao diện trên macOS.** Rất có thể chưa cấp quyền. Chạy `agent-desktop permissions --guide` để làm theo hướng dẫn.
- **Lỗi trên PowerShell khi dùng ref.** Ký tự `@` đầu chuỗi là toán tử splatting. Hãy đặt ref trong dấu nháy đơn, ví dụ `'@s8f3k2p9:e8'`.
- **Lệnh `key-down`, `key-up`, `mouse-down`, `mouse-up` không chạy.** README nói bốn lệnh này từ chối chạy cho đến khi có daemon giải phóng phím hoặc nút đang giữ. Đây là giới hạn đã biết, không phải lỗi cài đặt.

Chỉ thử lại lệnh lỗi khi `error.disposition.retry` có giá trị `safe`.

## Có nên dùng không

Điểm mạnh: đọc giao diện có cấu trúc nên chính xác hơn nhìn ảnh. Chạy ngầm, không chiếm chuột của bạn. Hỗ trợ cả ba hệ điều hành, có MCP và skill, giấy phép Apache-2.0 và repo vẫn được cập nhật trong vài tháng gần đây.

Giới hạn: nó chỉ là đôi mắt và đôi tay, bạn vẫn cần một agent để ra quyết định. Nó phụ thuộc vào API accessibility của hệ điều hành, nên app nào hiển thị ít thông tin accessibility thì agent sẽ thấy ít. Mỗi nền tảng có chỗ chạy ngầm được, chỗ cần `--headed`, chỗ bị từ chối, và README chỉ dẫn sang trang riêng của từng nền tảng. Linux hiện yêu cầu Ubuntu 24.04 trở lên.

Nếu bạn chỉ cần tự động hoá một thao tác lặp lại cố định, một công cụ macro hoặc script đơn giản có thể hợp hơn. Nếu việc cần làm nằm trên trang web, hãy tìm công cụ chuyên cho trình duyệt. Còn nếu bạn muốn agent thao tác app desktop một cách có kiểm soát, agent-desktop là lựa chọn đáng thử.

## Câu hỏi thường gặp

### agent-desktop có miễn phí không?

Repo dùng giấy phép Apache-2.0, nên bạn dùng mã nguồn được. README không nhắc phí cho chính công cụ. Chi phí cho mô hình AI (nếu có) nằm ở agent bạn dùng, vì agent-desktop không chứa mô hình nào.

### Có cần GPU hoặc API key không?

README không yêu cầu GPU hay API key cho agent-desktop. Công cụ chỉ đọc cây accessibility và gửi thao tác. Agent điều khiển nó có thể có yêu cầu riêng, tư liệu chưa nói rõ phần đó.

### Chạy trên Windows được không?

Được. README ghi hỗ trợ Windows 10 bản 1809 trở lên, x64 hoặc ARM64, qua UI Automation. Cài bằng npm. Hiện chưa có gói Scoop chính thức. Khi dùng PowerShell nhớ đặt ref trong dấu nháy đơn.

### Dữ liệu trên màn hình của tôi có an toàn không?

README cảnh báo snapshot, nội dung clipboard, ảnh chụp màn hình, kết quả lệnh và file debug có thể chứa nội dung riêng tư. Bạn nên giữ chúng khỏi log công khai và đừng tải lên mạng. Tư liệu chưa nói thêm về chính sách dữ liệu khác.

### Khác gì các công cụ computer use dựa trên ảnh chụp màn hình?

agent-desktop không dùng ảnh chụp hay so khớp điểm ảnh. Nó đọc cây accessibility của hệ điều hành và trả về JSON có ref cho từng phần tử. Agent thao tác trên ref rồi đọc lại giao diện để kiểm tra kết quả.

### Có dùng được với Claude Code hay trợ lý hỗ trợ MCP không?

Có đường nối qua MCP: lệnh `agent-desktop mcp` phục vụ mọi lệnh thành tool MCP qua stdio. README cũng có lệnh cài skill bằng `npx skills add` và gợi ý thêm đoạn hướng dẫn vào AGENTS.md. Tên cụ thể từng agent được hỗ trợ, README chưa liệt kê.

### Tôi có thể gọi nó từ chương trình của mình không?

Có. Mỗi bản phát hành kèm thư viện C `libagent_desktop_ffi`, để chương trình gọi agent-desktop ngay trong tiến trình. README có ví dụ bằng Python với ctypes, và trỏ tới tài liệu C library trên trang chủ dự án.
