Computer Control API

advanced 🤖 Thân thiện với LLM 2 phút · 439 từ Cập nhật: 2026-06-27 Tiếng Việt

Điều khiển từ xa các máy tính đã đăng ký — xếp hàng lệnh, chụp ảnh màn hình, chạy script trên máy từ xa.

Đọc bài viết này ở định dạng: 📄 Văn bản thuần ⚡ JSON 🤖 Định dạng LLM

Computer Control API

Computer Control API cho phép bạn điều khiển từ xa các máy tính đã đăng ký. Một agent nhỏ (screen-remote-agent) chạy trên máy đích, poll các lệnh, thực thi chúng và gửi kết quả trở lại. Điều này cho phép tự động hóa GUI điều khiển bởi LLM.

Kiến trúc

┌─────────────┐  queue cmd   ┌──────────┐  poll   ┌─────────────────┐
│ LLM Agent   │ ───────────▶ │ Synapse  │ ◀───── │ screen-remote   │
│ (user-side) │              │  Server  │ ──────▶│ (on target PC)  │
└─────────────┘              └──────────┘ result  └─────────────────┘
                                     ▲
                                     │
                              ┌─────────────┐
                              │  Human UI   │
                              │ (browser)   │
                              └─────────────┘

Endpoint phía người dùng (Mind Key hoặc JWT)

GET /computers/list

Liệt kê tất cả máy tính đã đăng ký.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/list

GET /computers/:id

Lấy thông tin chi tiết của một máy tính.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001

POST /computers/install-code

Tạo một mã cài đặt để đăng ký máy tính mới.

curl -X POST https://synapse.schaefer.zone/computers/install-code \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"computer_name": "office-mac"}'

Phản hồi: { "install_code": "ic_xyz789", "expires_at": "..." }

POST /computers/:id/commands

Xếp hàng một lệnh để agent từ xa thực thi.

curl -X POST https://synapse.schaefer.zone/computers/comp_001/commands \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "payload": {}
  }'

Phản hồi: { "command_id": "cmd_001", "status": "queued" }

GET /computers/:id/command (qua query)

Xếp hàng một lệnh qua GET (cho các trường hợp đơn giản).

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/computers/comp_001/command?type=screenshot"

GET /computers/:id/commands

Liệt kê các lệnh gần đây của một máy tính.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/computers/comp_001/commands?limit=50"

GET /computers/:id/commands/:cid

Lấy trạng thái + kết quả của một lệnh cụ thể.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/commands/cmd_001

GET /computers/:id/screenshot

One-shot: xếp hàng lệnh chụp ảnh màn hình và đợi tối đa 30 giây để nhận kết quả.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/screenshot > screenshot.png

POST /computers/:id/disable

Vô hiệu hóa một máy tính (thu hồi token, vẫn giữ bản ghi cho mục đích kiểm toán).

curl -X POST -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/disable

DELETE /computers/:id

Xóa vĩnh viễn một máy tính.

curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001

Endpoint phía agent (Computer Token)

Các endpoint này được sử dụng bởi screen-remote-agent chạy trên máy đích. Chúng sử dụng Computer Token (trả về bởi /computers/register), không phải Mind Key.

POST /computers/register

Đổi mã cài đặt lấy Computer Token.

curl -X POST https://synapse.schaefer.zone/computers/register \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ic_xyz789",
    "computer_name": "office-mac",
    "platform": "darwin",
    "platform_release": "14.5.0",
    "python": "3.12.4"
  }'

Phản hồi: { "computer_id": "comp_001", "computer_token": "ct_..." }

Hãy lưu `computer_token` — nó chỉ hiển thị một lần và là bắt buộc cho tất cả các endpoint phía agent.

GET /computers/me/poll

Long-poll các lệnh mới. Agent gọi endpoint này trong một vòng lặp.

curl -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \
     "https://synapse.schaefer.zone/computers/me/poll?wait=30"

Trả về ngay lập tức nếu có lệnh đang chờ, hoặc sau wait giây nếu không.

POST /computers/me/commands/:cid/result

Gửi kết quả thực thi của một lệnh.

curl -X POST https://synapse.schaefer.zone/computers/me/commands/cmd_001/result \
  -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done",
    "result": { "screenshot_b64": "iVBORw0KG..." }
  }'

Các loại lệnh

Loại	Payload	Mô tả
`screenshot`	`{}`	Chụp màn hình dạng PNG (base64)
`click`	`{x, y}`	Nhấp tại tọa độ
`move`	`{x, y}`	Di chuyển chuột đến tọa độ
`type`	`{text}`	Nhập văn bản tại vị trí con trỏ
`key`	`{keys: ["Ctrl","c"]}`	Nhấn tổ hợp phím
`scroll`	`{deltaX, deltaY}`	Cuộn wheel
`drag`	`{fromX, fromY, toX, toY}`	Kéo và thả

Mẫu phổ biến: Tự động hóa GUI điều khiển bởi LLM

# LLM agent workflow
1. List computers: GET /computers/list
2. Take screenshot: GET /computers/:id/screenshot
3. Analyze screenshot (vision model)
4. Queue click: POST /computers/:id/commands {type:"click", payload:{x,y}}
5. Wait for result: GET /computers/:id/commands/:cid
6. Take new screenshot to verify
7. Repeat until task done

Bước tiếp theo

Browser Proxy — dịch vụ riêng cho tự động hóa trình duyệt
Hướng dẫn Self-Hosted Agents