Computer use

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Điều khiển app desktop local từ một agent qua accessibility tree, screenshot, và các hành động UI an toàn.

CLI orca computer cho phép một agent kiểm tra và điều khiển app desktop native - liệt kê app đang chạy, đọc accessibility tree, click control, đặt giá trị, gõ text, cuộn, và chụp screenshot. Dùng nó khi một task cần thao tác hệ điều hành hoặc một app bên thứ ba thay vì terminal hay trình duyệt built-in.

Thiết lập lần đầu

Kiểm tra runtime và quyền:

orca status --json
orca computer permissions --json
orca computer capabilities --json

Nếu permissions báo thiếu gì đó, cấp quyền Accessibility (và Screen Recording trên macOS) cho Orca Computer Use trong System Settings, rồi chạy lại permissions --json để xác nhận.

Snapshot → hành động → snapshot

Mọi tương tác theo cùng một vòng lặp: đọc state hiện tại của app, hành động trên một element cụ thể, rồi đọc lại state để xác nhận kết quả.

orca computer list-apps --json
orca computer get-app-state --app com.spotify.client --json
orca computer click --app com.spotify.client --element-index 42 --json

Chỉ số element giới hạn theo kết quả get-app-state mới nhất và có thể thưa (sparse). Trong output --json, đọc tree từ result.snapshot.treeText. Đừng tự bịa chỉ số từ elementCount. Refresh state sau khi điều hướng, đổi focus, cuộn, hoặc bất kỳ lần re-render nào của app trước khi dùng lại một chỉ số.

App nhiều cửa sổ

orca computer list-windows --app com.microsoft.edgemac --json
orca computer get-app-state --app com.microsoft.edgemac --window-id <id> --json
orca computer click --app com.microsoft.edgemac --window-id <id> --element-index 12 --json

Ưu tiên --window-id ổn định khi id được liệt kê không phải none; nếu không, dùng --window-index.

Chọn một app

Ưu tiên bundle ID trả về từ list-apps:

orca computer get-app-state --app com.microsoft.edgemac --json

Tên app hoạt động khi không mơ hồ (--app Spotify). Chỉ dùng --app pid:<number> khi cả bundle ID lẫn tên đều trùng nhau.

Các hành động khả dụng

orca computer click --app <app> --element-index <i> --json
orca computer set-value --app <app> --element-index <i> --value "text" --json
orca computer type-text --app <app> --text "text" --json
orca computer press-key --app <app> --key Return --json
orca computer hotkey --app <app> --key CmdOrCtrl+A --json
orca computer paste-text --app <app> --text "text" --json
orca computer scroll --app <app> --element-index <i> --direction down --json
orca computer drag --app <app> --from-x 100 --from-y 100 --to-x 300 --to-y 300 --json
orca computer perform-secondary-action --app <app> --element-index <i> --action <name> --json

Ưu tiên các hành động ngữ nghĩa (click, set-value, perform-secondary-action) hơn type-text hay press-key thô - chúng nhắm thẳng vào element accessibility và sống sót qua các lần đổi focus mà bàn phím không chịu được.

Khi việc nhắm theo accessibility thất bại, fallback cẩn thận sang toạ độ:

orca computer click --app com.apple.Safari --x 120 --y 340 --json
orca computer drag --app <app> --from-element-index 3 --to-element-index 9 --json

Input nhạy cảm

Truyền secret qua stdin để chúng không lọt vào shell history:

printf '%s' "$TEXT" | orca computer set-value \
  --app com.apple.Safari --element-index 7 --value-stdin --json

--text-stdin hoạt động tương tự cho type-text và paste-text.

Screenshot

get-app-state trả về một accessibility tree và, mặc định, một screenshot. Với --json, byte ảnh được ghi ra đĩa và đường dẫn trả về trong screenshot.path thay vì nhúng trong response. Truyền --no-screenshot khi không cần pixel (nhanh hơn, payload nhỏ hơn). Truyền --restore-window để đưa một cửa sổ bị ẩn hoặc minimize hiện ra trước khi chụp.

Dùng từ một agent

Skill computer-use có sẵn đóng gói cùng bề mặt lệnh này kèm hướng dẫn an toàn. Cài nó vào thư mục skill của agent:

npx skills add https://github.com/stablyai/orca --skill computer-use

Xem Skills registry & MCP để biết cách skill được nhận diện.

Bước tiếp theo

Orca CLI overview - phần còn lại của bề mặt CLI (worktree, terminal, trình duyệt).
Skills registry & MCP - phân phối CLI này tới agent.

Phuc Tran

Software Engineer | Learning Claude