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

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

8 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 — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

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

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.

CLI

vercel-labs/agent-desktop

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.

★ 23kRustApache-2.0
Xem repo trên GitHub

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

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

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

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

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

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

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

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

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

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

Terminal
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.Cấp quyền Accessibility trên macOS

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

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

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

Terminal
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 ở đó.

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

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

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

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

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

A.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:

Terminal
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

B.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:

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

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:

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

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

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

VII.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ử.

3.9/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, 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.

Chuyển nhanh tới mục

  1. I.agent-desktop làm được gì
  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.Kiểm tra trạng thái và quyền
    3. C.Cấp quyền Accessibility trên macOS
    4. D.Nối với 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.Thử vòng lặp nhìn, bấm, kiểm tra
    2. B.Cho agent thao tác app có nhiều phần tử
    3. C.Dùng làm MCP server cho trợ lý AI
    4. D.Nhập chữ nhạy cảm mà không lộ ra tham số lệnh
  6. VI.Lỗi hay gặp và cách xử lý
  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ỏ.