Bỏ qua tới nội dung
Ông T.vn

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

10 phút đọcCập nhật

Bài này là một góc nhìn khác về vercel-labs/agent-desktop — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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: cho AI agent điều khiển app máy tính qua accessibility tree — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

agent-desktop là công cụ dòng lệnh (CLI) của Vercel Labs, cho phép AI agent nhìn và điều khiển ứng dụng desktop trên macOS, Windows, Linux thông qua accessibility tree của hệ điều hành. Mỗi lệnh trả về JSON, phần tử bấm được có một ref để agent thao tác. Cài bằng một lệnh npm, nhưng cần cấp quyền Accessibility trên macOS và cần một agent bên ngoài để điều khiển vòng lặp.

agent-desktop là một công cụ dòng lệnh (CLI) cho phép AI agent "nhìn" và điều khiển các ứng dụng trên máy tính của bạn: Finder, Slack, các cửa sổ cài đặt… Nó chạy trên macOS, Windows và Linux. Thay vì chụp ảnh màn hình rồi đoán chỗ cần bấm, nó đọc cây accessibility (thông tin mà hệ điều hành cung cấp cho phần mềm hỗ trợ người khuyết tật) và trả về dạng JSON.

Với mỗi phần tử có thể thao tác, công cụ gắn một mã gọi là ref. Agent chỉ cần nói "bấm vào ref này", rồi đọc lại giao diện để kiểm tra kết quả, và lặp lại. Vòng lặp đó nằm ở agent của bạn. agent-desktop không chứa mô hình AI nào bên trong, nó chỉ là đôi mắt và đôi tay.

Bài này hợp với bạn nếu đang dùng (hoặc muốn thử) một AI agent như Claude Code và muốn nó làm được việc trên app có giao diện đồ hoạ. Hiện repo có khoảng 22.971 sao và 1.700 fork, giấy phép Apache-2.0, viết bằng Rust và vẫn được cập nhật trong 3 tháng gần đây. Điểm đáng giá nhất: cách đọc cây accessibility thường chính xác và nhẹ hơn cách dựa vào ảnh chụp màn hình, và nó đi kèm sẵn cả chế độ MCP lẫn skill cho agent.

CLI

vercel-labs/agent-desktop

CLI viết bằng Rust giúp AI agent xem và thao tác app trên macOS, Windows, Linux qua accessibility tree, không cần chụp ảnh màn hình hay dò pixel.

★ 23kRustApache-2.0
Xem repo trên GitHub

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

A.Đọc giao diện thành JSON có ref

Lệnh snapshot trả về cây các phần tử của một app: cửa sổ, nút, mục danh sách, ô nhập… Phần tử nào thao tác được sẽ có ref_id dạng @s8f3k2p9:e8. Lợi ích thực tế: agent không phải đoán toạ độ pixel, nên ít bị lệch khi bạn đổi cỡ cửa sổ hay độ phân giải.

B.Thao tác trên ref

Có rất nhiều lệnh để hành động: click, double-click, right-click, type, set-value, clear, focus, select, toggle, check, expand, scroll… Ngoài ra có nhóm lệnh bàn phím và chuột (press, hover, drag, mouse-click…), nhóm quản lý app và cửa sổ (launch, list-windows, resize-window, minimize…), thông báo, clipboard và wait. Tổng cộng README ghi 61 tên lệnh, trong đó 57 lệnh dùng được. Bốn lệnh key-down, key-up, mouse-down, mouse-up hiện từ chối chạy.

C.Chạy "headless" theo mặc định

Các lệnh trên ref dùng accessibility API mà không di chuột thật và không cướp focus. Nghĩa là agent có thể làm việc trong lúc bạn vẫn dùng máy. Khi thật sự cần nhập liệu vật lý, bạn thêm cờ --headed (cờ toàn cục).

D.Phiên bản ref gắn với snapshot

Mỗi ref thuộc về một snapshot. Ghi @e8 trơn sẽ bị từ chối với lỗi INVALID_ARGS. Nếu giao diện đổi, lệnh trả STALE_REF hoặc AMBIGUOUS_TARGET, và agent cần chụp snapshot mới. Cơ chế này giúp tránh việc bấm nhầm vào phần tử đã thay đổi.

E.Xử lý app dày đặc

Với app nhiều thành phần như Slack, bạn lập bản đồ trước bằng snapshot --skeleton, rồi chỉ đào sâu một vùng bằng snapshot --root. Cách này giữ kết quả gọn, đỡ tốn token của agent.

F.Có MCP server và skill sẵn

agent-desktop mcp biến mọi lệnh thành MCP tool qua stdio (ví dụ desktop_snapshot, desktop_click). Ngoài ra trong binary có sẵn hướng dẫn dành cho agent qua agent-desktop skills get. Bạn cũng có thể cài skill vào agent harness.

G.Bảo vệ dữ liệu nhập

type, set-value và clipboard-set hỗ trợ --stdin để truyền văn bản qua pipe, không để lộ trong tham số tiến trình. Ngoài CLI, repo còn có thư viện C (libagent_desktop_ffi) cho ai muốn gọi trực tiếp từ chương trình của mình.

II.Cần chuẩn bị gì

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

  • macOSmacOS 13 trở lên, chip Intel hoặc Apple Silicon (dùng AX API).
  • WindowsWindows 10 bản 1809 trở lên, x64 hoặc ARM64 (dùng UI Automation).
  • LinuxUbuntu 24.04 trở lên, x86_64 hoặc aarch64, X11 hoặc Wayland (dùng AT-SPI).

Về cách cài, README dùng npm, nên bạn cần có npm trên máy. README không nói rõ phiên bản Node tối thiểu. Gói npm đã gồm sẵn file chạy cho x64 và ARM64. Ngoài ra Bun, Yarn, pnpm cũng cài được cùng gói đó, và macOS/Linux có thể dùng Homebrew.

Trên macOS bạn phải cấp quyền Accessibility cho ứng dụng terminal (hoặc chương trình chạy lệnh). README có lệnh hướng dẫn từng bước cho việc này. Tư liệu không nhắc tới API key hay GPU, vì công cụ không có mô hình AI bên trong. Tuy vậy bạn cần một AI agent riêng để ra quyết định.

Snapshot, nội dung clipboard, ảnh chụp màn hình, kết quả lệnh và file gỡ lỗi có thể chứa dữ liệu riêng tư trên máy bạn (tin nhắn, mật khẩu, số liệu khách hàng). Đừng đưa chúng lên log công khai hay nơi chia sẻ. Khi nhập thông tin nhạy cảm, hãy dùng --stdin và chạy bước đó thành một lệnh riêng.

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

  1. Cài góiChạy npm install -g agent-desktop để có lệnh agent-desktop
  2. Kiểm tra trạng tháiChạy agent-desktop status để xem nền tảng và quyền
  3. Cấp quyềnTrên macOS, chạy permissions --guide để được dẫn cấp quyền Accessibility
  4. Thử snapshotChụp cây giao diện của một app như Finder
  5. Nối với agentCài skill, thêm vào AGENTS.md hoặc cấu hình MCP

A.Cài gói bằng npm

Mở terminal (macOS: Terminal; Windows: PowerShell; Linux: terminal của bạn). Chạy lệnh dưới đây ở bất kỳ thư mục nào vì đây là cài toàn cục:

Terminal
npm install -g agent-desktop

Nếu bạn dùng macOS hoặc Linux và quen Homebrew, README nói cũng có thể cài bằng brew install agent-desktop. README ghi rõ hiện chưa có gói Scoop chính thức cho Windows. Nếu không muốn dùng JavaScript launcher, bạn có thể tải file nén đúng nền tảng ở trang GitHub Releases của repo, và để file helper nằm cạnh file thực thi.

Terminal
brew install agent-desktop

B.Xem trạng thái

Lệnh sau cho biết nền tảng, quyền hiện có và các bề mặt được hỗ trợ:

Terminal
agent-desktop status

Nếu máy báo không tìm thấy lệnh, hãy đóng và mở lại terminal để nó nạp lại đường dẫn.

C.Cấp quyền Accessibility (macOS)

Chỗ này người mới hay vấp nhất. Chạy lệnh sau và làm theo hướng dẫn trên màn hình:

Terminal
agent-desktop permissions --guide

Bạn sẽ cấp quyền Accessibility cho chương trình đang chạy lệnh. Không cấp quyền thì công cụ không đọc được giao diện app.

D.Chụp thử một snapshot

Mở app Finder rồi chạy:

Terminal
agent-desktop snapshot --app Finder -i

Cờ --app chọn app, còn -i chỉ lấy các phần tử tương tác được. Kết quả là một khối JSON, trong đó các phần tử có ref_id.

E.Nối với AI agent của bạn

Có ba cách theo README. Cách một: cài skill vào agent harness:

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

Cách hai: dán đoạn sau vào file AGENTS.md của dự án để agent tự đọc hướng dẫn trước khi dùng:

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 ba: chạy như MCP server. Thêm đoạn này vào cấu hình MCP của agent:

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

Về cách build từ mã nguồn, README chính chỉ liệt kê lệnh test và clippy cho nhà phát triển. Hướng dẫn cài từ release và từ nguồn nằm ở trang Installation trên trang tài liệu của dự án, và file CONTRIBUTING.md trong repo.

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

Có ba mốc để biết mọi thứ ổn:

  1. agent-desktop status 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.
  2. Lệnh agent-desktop snapshot --app Finder -i trả về một JSON có "ok": true, "command": "snapshot", có snapshot_id, ref_count và cây tree chứa các phần tử có ref_id.
  3. Chạy thử một thao tác rồi chụp lại để xác nhận:
Terminal
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i

Hãy thay @s8f3k2p9:e8 bằng ref thật trong snapshot của bạn, vì ref khác nhau theo từng snapshot. Nếu bạn dùng PowerShell, phải đặt ref trong dấu nháy đơn, ví dụ '@s8f3k2p9:e8', vì @token trần là toán tử splatting.

Nếu cấu hình MCP, bạn có thể hỏi agent liệt kê tool. Các tool mang tên như desktop_snapshot, desktop_click, desktop_session_start.

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

Công cụ này là phần "tay mắt"; agent của bạn mới là phần "đầu óc". Dưới đây là vài tình huống bám đúng khả năng trong README.

Đừng bắt AI đoán chỗ cần bấm trên ảnh chụp. Hãy đưa nó danh sách phần tử có mã rõ ràng.

Ông T

A.Dev kiểm thử giao diện app trên máy

Bạn là lập trình viên đang làm một app desktop và muốn agent tự bấm thử các nút. Bạn dặn agent theo vòng lặp: chụp snapshot, bấm ref, chụp lại để kiểm tra. Với app có nhiều cửa sổ, lệnh trả AMBIGUOUS_TARGET kèm danh sách id cửa sổ trong error.details, và bạn chọn bằng --window-id. Kết quả: agent đi qua được một kịch bản bấm nút và biết rõ nó có thành công không, nhờ dữ liệu có cấu trúc.

B.Nhân viên văn phòng gom việc lặp lại trong Slack

Bạn dùng một app nhiều thành phần như Slack và muốn agent lấy thông tin từ một vùng cụ thể. Theo README, bạn lập bản đồ trước rồi đào sâu:

Terminal
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ỉ đọc vùng có ref e3. Kết quả gọn hơn nhiều so với đọc cả cây. Nhờ vậy agent nhanh hơn và tốn ít ngữ cảnh hơn.

C.Chủ shop nhập liệu mà không để lộ nội dung

Giả sử bạn cần agent điền một đoạn văn bản nhạy cảm vào một ô nhập trong app quản lý bán hàng. README cho phép truyền văn bản qua --stdin cho type, set-value và clipboard-set, để nội dung không nằm trong tham số tiến trình. Hãy chạy các bước bí mật thành lệnh riêng, không gộp trong batch, vì README lưu ý JSON của batch sẽ xuất hiện trong tham số tiến trình. Kiểm tra các cờ chính xác bằng agent-desktop type --help trước khi dùng.

D.Người dùng Claude Code hay agent khác qua MCP

Bạn đã có agent hỗ trợ MCP và muốn nó mở app, đọc thông báo, đọc clipboard. Bạn thêm cấu hình MCP như ở phần cài đặt. Các lệnh như list-apps, list-windows, list-notifications, clipboard-get sẽ xuất hiện thành tool. Bạn có thể nhờ agent: "liệt kê các cửa sổ đang mở, rồi chụp snapshot của app trình duyệt". Kết quả mỗi lần gọi là một JSON gọn, agent đọc được ngay.

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

A.Lệnh trả INVALID_ARGS khi dùng ref

Nguyên nhân thường là ghi ref thiếu phần snapshot, ví dụ @e8. Hãy dùng ref đầy đủ như @s8f3k2p9:e8, lấy từ chính snapshot bạn vừa chụp.

B.STALE_REF hoặc AMBIGUOUS_TARGET

Giao diện đã đổi sau khi chụp, hoặc có nhiều đích khớp. Cách xử lý theo README: chụp snapshot mới và dùng ref mới. Nếu có nhiều cửa sổ, chọn một id trong error.details và truyền vào --window-id. Chỉ nên thử lại lệnh lỗi khi error.disposition.retry là safe.

C.Không đọc được app trên macOS

Khả năng cao là chưa cấp quyền Accessibility. Chạy agent-desktop permissions --guide và làm theo, sau đó agent-desktop status để kiểm tra lại. Nếu vừa cấp quyền mà chưa ăn, thử mở lại terminal.

D.PowerShell báo lỗi cú pháp với ref

Trong PowerShell, @ đứng đầu là toán tử splatting. Hãy đặt ref trong dấu nháy đơn: '@s8f3k2p9:e8'.

E.Snapshot quá dài, agent bị rối

Với app lớn, dùng --skeleton và --compact để lấy bản đồ, rồi --root để đào vào một vùng. Đừng chụp toàn bộ cây nếu không cần.

VII.Có nên dùng không

Điểm mạnh. Cách đọc qua accessibility tree cho dữ liệu có cấu trúc, ref rõ ràng và cơ chế báo lỗi STALE_REF giúp agent bớt làm sai. Chạy mặc định không chiếm chuột, hỗ trợ ba hệ điều hành, có sẵn MCP và skill, giấy phép Apache-2.0, và dự án vẫn đang được cập nhật.

Giới hạn. Công cụ không có mô hình AI, nên bạn vẫn cần một agent bên ngoài và phải tự lo phần đó. Bốn lệnh giữ phím/giữ chuột (key-down, key-up, mouse-down, mouse-up) hiện từ chối chạy. Mỗi nền tảng có chỗ chạy headless, chỗ cần --headed, và chỗ bị từ chối. Ứng dụng nào ít hỗ trợ accessibility sẽ cho ít thông tin hơn; README không nói chi tiết về trường hợp này, nên bạn nên thử trên app của mình trước. Windows chưa có gói Scoop chính thức, Linux yêu cầu từ Ubuntu 24.04 trở lên.

Khi nào chọn cách khác. Nếu việc của bạn chỉ trong trình duyệt web, nên xem công cụ chuyên cho trình duyệt. Nếu bạn chỉ cần tự động hoá đơn giản trên một app, một script riêng có thể đủ. Còn nếu bạn muốn agent làm việc trên app desktop thật mà không phụ thuộc ảnh chụp màn hình, agent-desktop là một lựa chọn đáng thử, nhất là khi bạn bắt đầu bằng những việc nhỏ và kiểm tra kết quả sau từng bước.

4.2/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn khô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à README không nhắc tới phí nào cho công cụ. Tuy vậy bạn cần một AI agent riêng để điều khiển nó, và chi phí của agent đó (nếu có) tuỳ nhà cung cấp; tư liệu chưa có thông tin về việc này.

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

Tư liệu không yêu cầu GPU hay API key cho agent-desktop, vì bên trong nó không có mô hình AI. Vòng lặp quyết định nằm ở agent của bạn.

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

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

agent-desktop khác gì cách dùng ảnh chụp màn hình?

agent-desktop không chụp ảnh rồi dò pixel. Nó đọc accessibility tree của app và trả về JSON, trong đó mỗi phần tử thao tác được có một ref. Agent hành động trên ref và đọc lại giao diện để kiểm tra.

Dữ liệu trên máy có an toàn không?

README cảnh báo snapshot, clipboard, ảnh chụp màn hình, kết quả lệnh và file gỡ lỗi có thể chứa nội dung riêng tư, nên đừng đưa lên log hay nơi chia sẻ công khai. Có thể dùng --stdin để truyền văn bản mà không để lộ trong tham số tiến trình. Tư liệu chưa nêu thêm chi tiết về mô hình bảo mật.

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

Có ba cách theo README: cài skill bằng npx skills add, dán hướng dẫn vào AGENTS.md, hoặc chạy agent-desktop mcp làm MCP server qua stdio. Danh sách agent cụ thể được kiểm chứng chưa có trong tư liệu.

Cài từ mã nguồn thì làm sao?

README chính chỉ nói về cài bằng npm, Homebrew và tải bản release. Cách build từ mã nguồn nằm ở trang Installation của tài liệu dự án và file CONTRIBUTING.md trong repo.

Chuyển nhanh tới mục

  1. I.agent-desktop làm được gì
    1. A.Đọc giao diện thành JSON có ref
    2. B.Thao tác trên ref
    3. C.Chạy "headless" theo mặc định
    4. D.Phiên bản ref gắn với snapshot
    5. E.Xử lý app dày đặc
    6. F.Có MCP server và skill sẵn
    7. G.Bảo vệ dữ liệu nhập
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Cài gói bằng npm
    2. B.Xem trạng thái
    3. C.Cấp quyền Accessibility (macOS)
    4. D.Chụp thử một snapshot
    5. E.Nối với AI agent của bạn
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Dev kiểm thử giao diện app trên máy
    2. B.Nhân viên văn phòng gom việc lặp lại trong Slack
    3. C.Chủ shop nhập liệu mà không để lộ nội dung
    4. D.Người dùng Claude Code hay agent khác qua MCP
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Lệnh trả INVALID_ARGS khi dùng ref
    2. B.STALE_REF hoặc AMBIGUOUS_TARGET
    3. C.Không đọc được app trên macOS
    4. D.PowerShell báo lỗi cú pháp với ref
    5. E.Snapshot quá dài, agent bị rối
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.