close

agent-desktop

Mã nguồn mở bởi vercel-labs

agent-desktop là công cụ dòng lệnh giúp AI agent như Claude Code hay Codex tự thao tác ứng dụng trên máy tính macOS, Windows và Linux. Công cụ đọc cấu trúc giao diện mà hệ điều hành cung cấp cho các phần mềm trợ năng, nên agent biết đâu là nút bấm, đâu là ô nhập liệu mà không phải chụp màn hình rồi đoán vị trí.

agent-desktop dùng để làm gì?

  • Cho AI agent đọc danh sách nút bấm, ô nhập liệu, menu của một ứng dụng dưới dạng JSON
  • Bấm nút, gõ chữ, chọn mục, cuộn trang theo mã số (ref) của từng phần tử
  • Mở, đóng ứng dụng và chuyển, thu nhỏ, đổi kích thước cửa sổ
  • Đọc và ghi clipboard, xem và đóng thông báo hệ thống
  • Cung cấp toàn bộ lệnh dưới dạng công cụ MCP cho các agent hỗ trợ MCP

Cần biết trước khi dùng

  • Lưu ýKhông tìm thấy docker-compose hay Dockerfile ở thư mục gốc: chưa thể gắn nút Deploy tự động.
  • Lưu ýTino chưa kiểm thử dự án này.

Kiểm tra tự động ngày 23/11/2026 từ dữ liệu GitHub, OSV.dev và docker-compose. Đây không phải chứng nhận bảo mật; Tino không phát triển hay bảo trì repo này.

agent-desktop là gì?

Cách phổ biến để AI điều khiển máy tính là chụp màn hình, cho model phân tích ảnh rồi đoán toạ độ cần nhấn. agent-desktop đi theo hướng khác: đọc cây trợ năng (accessibility tree) của ứng dụng, chính là dữ liệu mà hệ điều hành cung cấp cho phần mềm đọc màn hình. Trên macOS là AX API, trên Windows là UI Automation, trên Linux là AT-SPI.

Lệnh snapshot trả về cây giao diện dạng JSON, mỗi phần tử thao tác được có một ref như @s8f3k2p9:e8. Agent dùng ref đó để click, gõ chữ, rồi chạy snapshot lần nữa để kiểm tra kết quả. Nếu giao diện đã đổi, lệnh trả lỗi STALE_REF và agent phải đọc lại, thay vì bấm nhầm.

Bên trong agent-desktop không có model AI. Vòng lặp quan sát, thao tác, kiểm tra nằm ở agent bạn đang dùng, nên công cụ chạy được với Claude Code, Codex hay bất kỳ agent nào gọi được lệnh shell. Theo README, các thao tác mặc định chạy ngầm: không di chuyển con trỏ, không đổi cửa sổ đang dùng; cần nhập thật thì thêm cờ --headed.

Dự án có từ tháng 2/2026, do lập trình viên Lahfir viết, hiện nằm dưới tổ chức Vercel Labs. Bản 1.0 phát hành cuối tháng 10/2026 và thêm hỗ trợ Linux; nhiều lỗi theo từng nền tảng vẫn đang được sửa.

Nên dùng khi

  • Bạn muốn giao cho AI agent các việc lặp lại trên ứng dụng desktop không có API, như điền form trong phần mềm, sắp xếp file trong Finder
  • Bạn đang dùng Claude Code, Codex hoặc agent hỗ trợ MCP và muốn agent tự kiểm tra kết quả trên giao diện
  • Bạn cần tự động hoá giao diện trên cả macOS, Windows và Linux bằng cùng một bộ lệnh

Không nên dùng khi

  • Ứng dụng không công bố cây trợ năng, như game, phần mềm tự vẽ giao diện bằng canvas: agent-desktop không thấy gì trong các ứng dụng này
  • Máy có dữ liệu nhạy cảm mà bạn không muốn agent đọc: snapshot, clipboard, thông báo và ảnh chụp đều chứa nội dung trên màn hình, và agent có quyền thao tác như người dùng
  • Bạn cần tự động hoá trang web: FAQ của dự án khuyên dùng agent-browser cho việc này
  • Máy Windows 11 cài mới đang bật Smart App Control: theo tài liệu cài đặt, tính năng này chặn file chạy chưa ký của agent-desktop
  • Bạn định chạy trong SSH hoặc container trên Linux không có phiên đồ hoạ: công cụ sẽ không thấy ứng dụng nào

Tính năng chính

  • 60 tên lệnh, chia nhóm quan sát, thao tác theo ref, bàn phím và chuột, ứng dụng và cửa sổ, thông báo, clipboard, phiên làm việc
  • Mỗi lệnh in ra một khối JSON, kèm mã lỗi và gợi ý có nên thử lại hay không
  • Thao tác chạy ngầm mặc định, cờ --headed để nhập bằng chuột và bàn phím thật
  • Máy chủ MCP qua stdio bằng lệnh agent-desktop mcp
  • Hướng dẫn cho agent đi kèm trong file chạy: agent-desktop skills get desktop
  • Thư viện C (libagent_desktop_ffi) để gọi trực tiếp trong chương trình
  • Hỗ trợ macOS 13+, Windows 10 1809+, Ubuntu 24.04+ trên x64 và ARM64

Cách cài đặt agent-desktop

  1. Cài bằng npm Cần Node.js 18 trở lên. Gói npm có sẵn file chạy cho macOS, Windows, Linux trên x64 và ARM64. Lệnh status cho biết nền tảng, quyền đã cấp và những gì đọc được.
    npm install -g agent-desktop
    agent-desktop status
  2. Cấp quyền Trợ năng trên macOS Lệnh mở Cài đặt hệ thống kèm hướng dẫn cấp quyền Accessibility. Muốn chụp màn hình thì cấp thêm Screen Recording. Windows không cần cấp quyền với ứng dụng chạy cùng mức quyền với terminal.
    agent-desktop permissions --guide
  3. Hoặc cài bằng Homebrew (macOS, Linux) Bản Homebrew có thể ra chậm hơn npm một chút. Nâng cấp bằng brew upgrade agent-desktop.
    brew install agent-desktop
    agent-desktop version
  4. Cài skill cho AI agent Thêm hướng dẫn sử dụng agent-desktop vào agent của bạn qua skills.sh. Cách khác là thêm vào AGENTS.md một dòng dặn agent chạy agent-desktop skills get desktop và agent-desktop skills get platform trước lần dùng đầu.
    npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop

Lệnh chép từ README của dự án. Đọc kỹ trước khi chạy và đối chiếu với README mới nhất, vì lệnh có thể đổi theo phiên bản.

Cấu hình quan trọng

MụcÝ nghĩa
AGENT_DESKTOP_SESSIONChọn phiên làm việc; ref lấy trong phiên nào thì phải dùng đúng phiên đó (tương đương cờ --session)

Cách tích hợp và sử dụng

  1. Đọc giao diện một ứng dụngChạy agent-desktop snapshot --app Finder -i để lấy danh sách phần tử thao tác được, mỗi phần tử có một ref.
  2. Thao tác theo refChạy agent-desktop click @s8f3k2p9:e8 với ref vừa lấy. Ref phải ghi đủ mã snapshot; ghi tắt @e8 sẽ báo lỗi INVALID_ARGS. Trong PowerShell, đặt ref trong dấu nháy đơn.
  3. Đọc lại để kiểm traChạy snapshot lần nữa để xem kết quả. Gặp STALE_REF hoặc AMBIGUOUS_TARGET nghĩa là giao diện đã đổi: lấy snapshot mới rồi dùng ref mới.
  4. Giao việc cho agentSau khi cài skill, chỉ cần mô tả việc cần làm cho Claude Code hay Codex, ví dụ viết ghi chú trong TextEdit rồi lưu vào Documents; agent tự gọi các lệnh trên.
  5. Giữ kín dữ liệuKhông đăng snapshot, ảnh chụp, file trace hay nhật ký của agent lên nơi công khai vì chúng chứa nội dung màn hình.

Cập nhật và sao lưu

Cài bằng npm thì nâng cấp bằng cách cài lại gói; cài bằng Homebrew thì dùng brew upgrade agent-desktop; cài từ file nén trên GitHub Releases thì thay cả file chạy lẫn file helper cùng một bản phát hành.

Công cụ không lưu dữ liệu riêng cần sao lưu. README không nêu vị trí thư mục cấu hình.

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

agent-desktop có tốn phí không?

Không. Mã nguồn theo giấy phép Apache-2.0, dùng cho cá nhân và thương mại. Công cụ không gọi model AI nào; bạn chỉ tốn token của agent đang dùng. Riêng công cụ phụ tuỳ chọn JEV gửi mô tả màn hình cho nhà cung cấp model bạn cấu hình.

agent-desktop có chiếm chuột và bàn phím của tôi không?

Mặc định là không: thao tác chạy ngầm, không di chuyển con trỏ và không đổi cửa sổ đang dùng. Chỉ khi thêm cờ --headed, hoặc một số thao tác cần nhập thật theo trang nền tảng, công cụ mới dùng chuột và bàn phím thật.

Có cài agent-desktop lên VPS được không?

Chỉ khi VPS có giao diện đồ hoạ và bạn chạy công cụ ngay trong phiên đồ hoạ đó. Theo tài liệu, chạy qua SSH hoặc trong container không có phiên đồ hoạ thì công cụ không thấy ứng dụng nào. Thông thường bạn cài trên máy cá nhân, nơi agent đang chạy.

agent-desktop có điều khiển được trình duyệt web không?

Công cụ đọc được cửa sổ trình duyệt như một ứng dụng, nhưng không dùng để tự động hoá nội dung trang web. FAQ của dự án khuyên dùng agent-browser cho việc đó.

Ứng dụng liên quan

Miễn trừ trách nhiệm

Tino không phát triển, không sở hữu và không liên kết với agent-desktop hay nhóm phát triển vercel-labs. Tên, logo và nhãn hiệu thuộc về chủ sở hữu tương ứng; việc nhắc tới chỉ để mô tả, không có nghĩa là dự án xác nhận hay hợp tác với Tino.

agent-desktop được phân phối theo giấy phép Apache-2.0 của nhóm phát triển. Tino không bảo đảm về tính năng, bảo mật hay mức độ phù hợp của phần mềm; bạn tự chịu trách nhiệm khi cài đặt, cấu hình và sử dụng.

Lệnh cài và thông tin trên trang lấy từ tài liệu công khai của dự án tại thời điểm cập nhật và có thể đã thay đổi. Đọc tài liệu chính thức và sao lưu dữ liệu trước khi chạy trên máy chủ thật.