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

> agent-desktop là công cụ dòng lệnh (CLI) viết bằng Rust, giúp AI agent xem và điều khiển ứng dụng desktop trên macOS, Windows và Linux thông qua accessibility tree thay vì nhận diện ảnh. Mỗi lệnh trả về JSON, mỗi phần tử bấm được có một mã tham chiếu (ref). Cài bằng một lệnh npm, nhưng cần cấp quyền Accessibility trên macOS và phải có agent (như Claude Code) để điều khiển.

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

agent-desktop là một công cụ dòng lệnh (CLI) cho phép AI agent "nhìn" và thao tác các ứng dụng trên máy tính của bạn: Finder, Slack, trình duyệt, phần mềm văn phòng… Nó chạy trên macOS, Windows và Linux. Thay vì chụp màn hình rồi đoán chỗ cần bấm, nó đọc cây accessibility của hệ điều hành và trả về JSON.

Cách làm này gọn hơn so với kiểu "nhìn ảnh rồi bấm toạ độ". Mỗi phần tử có thể thao tác được gắn một mã ref. Agent bấm hoặc gõ vào ref đó, đọc lại giao diện để kiểm tra kết quả, rồi lặp lại. Bản thân agent-desktop không chứa mô hình AI nào. Vòng lặp nằm ở agent của bạn, ví dụ Claude Code.

Repo này hợp với lập trình viên mới và người làm tự động hoá muốn cho AI làm việc trên ứng dụng desktop. Hiện có khoảng 22.971 sao và 1.700 fork, giấy phép Apache-2.0, và vẫn được cập nhật trong 3 tháng gần đây. Điểm đáng giá nhất là bộ công cụ có sẵn: lệnh CLI, máy chủ MCP và bộ hướng dẫn (skill) đi kèm.

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

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

### Đọc giao diện thành JSON có mã tham chiếu

Lệnh `snapshot` trả về cây giao diện của một ứng dụng. Mỗi nút bấm, ô nhập, mục danh sách có một `ref_id`. Agent không phải đoán toạ độ trên màn hình, nên ít bấm nhầm hơn.

### Thao tác theo ref

README liệt kê 61 tên lệnh, trong đó 57 lệnh hoạt động được. Chúng gồm click, double-click, right-click, type, set-value, select, toggle, scroll, press, drag, launch, đóng ứng dụng, quản lý cửa sổ, clipboard và thông báo. Bạn có thể xem từng lệnh bằng `agent-desktop <command> --help`.

### Chạy ngầm theo mặc định

Các thao tác theo ref dùng accessibility API, không di chuyển con trỏ chuột và không cướp focus. Bạn vẫn dùng máy bình thường trong lúc agent làm việc. Khi cần nhập liệu vật lý, thêm cờ `--headed`.

### Có sẵn máy chủ MCP và skill

`agent-desktop mcp` biến mọi lệnh thành công cụ MCP qua stdio, như `desktop_snapshot` hay `desktop_click`. Ngoài ra repo có skill để cài vào agent harness.

### Báo lỗi có cấu trúc

Mỗi lệnh in một "phong bì" JSON gồm `ok`, `command`, `data` và lỗi nếu có. Lỗi như `STALE_REF` hay `AMBIGUOUS_TARGET` cho agent biết phải chụp lại cây giao diện.

### Thư viện C

Mỗi bản phát hành có `libagent_desktop_ffi`, để chương trình của bạn gọi trực tiếp mà không qua CLI.

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

Theo README, hệ điều hành hỗ trợ gồm:

- **macOS:** macOS 13 trở lên, 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, X11 hoặc Wayland.

Cài bằng npm thì cần có npm (Node.js) trên máy. Bun, Yarn, pnpm cũng cài được cùng gói. Trên macOS và Linux còn có thể dùng Homebrew. Trên macOS, bạn phải cấp quyền Accessibility cho công cụ.

README không nhắc tới API key hay GPU. Công cụ này không chứa mô hình AI. Chi phí mô hình (nếu có) nằm ở agent bạn dùng. Bạn cũng cần một agent như Claude Code để điều khiển nó, hoặc tự gõ lệnh bằng tay để thử.

```note
Snapshot, clipboard, ảnh chụp màn hình và log có thể chứa nội dung riêng tư trên màn hình của bạn. Đừng đưa chúng vào log công khai hay upload lên chỗ công cộng.
```

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

```steps
- Cài gói | Chạy npm install -g agent-desktop
- Kiểm tra trạng thái | Chạy agent-desktop status để xem nền tảng và quyền
- Cấp quyền macOS | Chạy agent-desktop permissions --guide
- Cho agent biết cách dùng | Cài skill hoặc thêm đoạn vào AGENTS.md
- Thử nhanh | Chụp snapshot một ứng dụng rồi bấm thử một ref
```

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

Mở terminal (Terminal trên macOS, PowerShell trên Windows) rồi chạy:

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

Lệnh này cài agent-desktop toàn cục. Gói đã gồm file chạy gốc cho x64 và ARM64. Trên macOS và Linux, bạn có thể dùng Homebrew:

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

README ghi rõ chưa có gói Scoop chính thức cho Windows. Nếu không muốn dùng JavaScript launcher, hãy tải bản đóng gói đúng nền tảng ở trang GitHub Releases và để file helper cạnh file chạy.

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

```bash
agent-desktop status                # platform, permissions, supported surfaces
agent-desktop permissions --guide   # macOS: walks you through the Accessibility grant
```

`status` cho biết nền tảng, quyền và các bề mặt được hỗ trợ. `permissions --guide` dành cho macOS và sẽ dẫn bạn từng bước cấp quyền Accessibility. Chỗ người mới hay vấp là quên cấp quyền này nên các lệnh sau không đọc được giao diện.

### Cho agent biết cách dùng

Binary mang theo hướng dẫn khớp đúng phiên bản:

```bash
agent-desktop skills get desktop
agent-desktop skills get platform
```

Bạn có thể cài skill vào agent harness:

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

Hoặc 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.
```

### Dùng như máy chủ MCP (tuỳ chọn)

Nếu agent của bạn hỗ trợ MCP, thêm cấu hình này:

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

README không nói file cấu hình MCP nằm ở đâu. Bạn xem tài liệu của agent đang dùng để biết chỗ dán.

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

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

```bash
agent-desktop status
```

Nếu cài đúng, nó in thông tin nền tảng, quyền và các bề mặt được hỗ trợ. Sau đó thử vòng lặp quan sát, thao tác, quan sát lại theo README:

```bash
agent-desktop snapshot --app Finder -i      # interactive elements, each with a ref
agent-desktop click @s8f3k2p9:e8            # act on a ref from that snapshot
agent-desktop snapshot --app Finder -i      # observe again to verify
```

Kết quả mong đợi là một JSON có `"ok": true`, tên ứng dụng, `snapshot_id` và cây giao diện với các `ref_id`. Lưu ý mã `@s8f3k2p9:e8` chỉ là ví dụ. Bạn phải lấy ref thật từ snapshot của chính mình. Trên PowerShell, hãy đặt ref trong dấu nháy đơn, ví dụ `'@s8f3k2p9:e8'`, vì `@` trần là toán tử splatting.

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

### Dev cho agent thao tác app không có API

Bạn là lập trình viên và có một phần mềm nội bộ không có API. Cài skill cho agent, rồi giao việc bằng lời. Agent sẽ tự chạy `snapshot`, chọn ref, `click` hoặc `type`, rồi snapshot lại để kiểm tra. Kết quả là một quy trình tự động hoá chạy trên giao diện thật mà không cần viết bộ nhận diện ảnh.

> Agent không đoán toạ độ trên ảnh, nó bấm đúng phần tử có mã ref.
>
> — Ông T

### Ứng dụng đông nút: lập bản đồ rồi đào sâu

Với app dày giao diện như Slack, README khuyên lập bản đồ trước rồi mới đào vào từng vùng:

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

Lệnh đầu cho cái nhìn tổng quát, lệnh sau chỉ lấy một vùng. Cách này giúp JSON nhỏ hơn và agent bớt rối.

### Nhân viên văn phòng: gõ nội dung dài hoặc nhạy cảm

Khi cần agent điền một đoạn văn bản vào ô nhập, các lệnh `type`, `set-value` và `clipboard-set` nhận `--stdin` để truyền văn bản qua pipe, giữ nó khỏi tham số tiến trình. Hãy chạy các bước có bí mật thành lệnh riêng. Văn bản trong batch JSON thì vẫn hiện trong tham số tiến trình.

### Cắm vào agent qua MCP

Bạn dùng một agent hỗ trợ MCP. Thêm cấu hình MCP ở trên, khởi động lại agent, rồi nhờ nó "mở Finder và liệt kê các thư mục trong cửa sổ Downloads". Agent sẽ gọi `desktop_snapshot` và trả lời dựa trên JSON nhận được. README không đưa prompt mẫu, nên đây chỉ là ví dụ minh hoạ.

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

### Bị từ chối vì thiếu quyền

Trên macOS, nếu chưa cấp quyền Accessibility thì không đọc được giao diện. Chạy `agent-desktop permissions --guide` và làm theo, rồi chạy `agent-desktop status` để kiểm tra.

### Lỗi INVALID_ARGS khi dùng ref trần

Bạn gõ `@e8` thay vì ref đầy đủ. Ref thuộc về snapshot của nó, nên phải ghi dạng `@s8f3k2p9:e8` với mã snapshot thật.

### STALE_REF hoặc AMBIGUOUS_TARGET

Giao diện đã đổi nên ref cũ không còn đúng. Hãy chụp snapshot mới và dùng ref mới. Chỉ thử lại lệnh lỗi khi `error.disposition.retry` là `safe`.

### Nhiều cửa sổ cùng lúc

Ứng dụng có nhiều cửa sổ sẽ trả `AMBIGUOUS_TARGET`. Danh sách id cửa sổ nằm trong `error.details`. Chọn một cái bằng `--window-id`.

### Lỗi ref trên PowerShell

Nếu quên dấu nháy thì PowerShell hiểu `@token` là splatting. Hãy viết `'@s8f3k2p9:e8'`.

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

**Điểm mạnh:** đọc giao diện có cấu trúc, chạy ngầm, hỗ trợ ba hệ điều hành, có CLI, MCP, skill và thư viện C, giấy phép Apache-2.0, repo còn được cập nhật.

**Giới hạn:** nó chỉ là "tay và mắt". Bạn vẫn cần một agent có mô hình AI. Mỗi bản build chỉ chạy trên đúng một hệ điều hành. Bốn lệnh `key-down`, `key-up`, `mouse-down`, `mouse-up` hiện từ chối chạy. Windows chưa có gói Scoop chính thức. Ứng dụng nào không công bố accessibility tree tốt thì mức hỗ trợ có thể khác nhau. README có nhắc mỗi trang nền tảng liệt kê điều gì chạy ngầm, điều gì cần `--headed`, điều gì bị từ chối.

Nếu bạn chỉ cần điều khiển trình duyệt web, hãy xem công cụ chuyên cho trình duyệt. Nếu chưa có agent nào để điều khiển, hãy bắt đầu bằng việc chạy thử bằng tay vài lệnh `snapshot` để hiểu cách nó hoạt động.

## 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 và cài được qua npm. README không nói về chi phí. Công cụ này không có mô hình AI bên trong, nên chi phí mô hình (nếu có) phụ thuộc agent bạn dùng.

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

README không nhắc tới GPU hay API key. Vì không có mô hình bên trong và không dựa trên nhận diện ảnh, nên phần cài đặt của chính nó không đòi hỏi những thứ đó. Agent bạn dùng có thể có yêu cầu riêng.

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

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

### Khác gì cách chụp màn hình rồi cho AI bấm?

agent-desktop đọc cây accessibility của hệ điều hành và trả JSON có ref cho từng phần tử, không dùng ảnh hay khớp điểm ảnh. Agent bấm vào ref, rồi đọc lại giao diện để kiểm tra. Các thao tác theo ref chạy ngầm, không di chuyển con trỏ và không cướp focus.

### Dữ liệu của tôi có an toàn không?

README cảnh báo snapshot, clipboard, ảnh chụp màn hình, đầu ra lệnh và artifact debug có thể chứa nội dung riêng tư. Hãy giữ chúng khỏi log công khai và nơi upload. README cũng cho phép truyền văn bản qua --stdin để không lộ trong tham số tiến trình.

### Dùng với Claude Code hay agent khác thế nào?

Có hai cách: cài skill bằng npx skills add, hoặc thêm hướng dẫn vào AGENTS.md. Ngoài ra chạy agent-desktop mcp để dùng như máy chủ MCP qua stdio. README không đề cập riêng agent cụ thể nào.

### Có hỗ trợ Linux không?

Có, trên Ubuntu 24.04 trở lên, x86_64 hoặc aarch64, X11 hoặc Wayland, dùng AT-SPI. Có thể cài bằng npm hoặc Homebrew. Từng nền tảng có trang tài liệu riêng ghi rõ điều gì chạy ngầm, điều gì cần --headed.
