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

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

8 phút đọcCập nhật
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

Tóm tắt nhanh

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.

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.

CLI

vercel-labs/agent-desktop

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.

★ 23kRustApache-2.0
Xem repo trên GitHub

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

A.Đọ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.

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

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

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

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

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

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

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.

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

  1. Cài góiChạy npm install -g 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ền macOSChạy agent-desktop permissions --guide
  4. Cho agent biết cách dùngCài skill hoặc thêm đoạn vào AGENTS.md
  5. Thử nhanhChụp snapshot một ứng dụng rồi bấm thử một ref

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

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

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

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

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

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

C.Cho agent biết cách dùng

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

Terminal
agent-desktop skills get desktop
agent-desktop skills get platform

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

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

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

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

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

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

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

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ỉ lấy một vùng. Cách này giúp JSON nhỏ hơn và agent bớt rối.

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

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

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

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

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

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

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

E.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'.

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

4.8/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à 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.

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ó mã tham chiếu
    2. B.Thao tác theo ref
    3. C.Chạy ngầm theo mặc định
    4. D.Có sẵn máy chủ MCP và skill
    5. E.Báo lỗi có cấu trúc
    6. F.Thư viện C
  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à cấp quyền
    3. C.Cho agent biết cách dùng
    4. D.Dùng như máy chủ MCP (tuỳ chọn)
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Dev cho agent thao tác app không có API
    2. B.Ứng dụng đông nút: lập bản đồ rồi đào sâu
    3. C.Nhân viên văn phòng: gõ nội dung dài hoặc nhạy cảm
    4. D.Cắm vào agent qua MCP
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Bị từ chối vì thiếu quyền
    2. B.Lỗi INVALID_ARGS khi dùng ref trần
    3. C.STALE_REF hoặc AMBIGUOUS_TARGET
    4. D.Nhiều cửa sổ cùng lúc
    5. E.Lỗi ref trên PowerShell
  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ỏ.