Tự động hoá và SDK

Điều khiển một hồ sơ Orbe bằng mã của bạn, hoặc bằng trợ lý AI, qua một kênh điều khiển nội bộ nằm trong lõi Chromium. Cú nhấp, phím gõ và thao tác cuộn đi qua đúng đường sự kiện của người dùng thật, còn trang được đọc ở phía trình duyệt thay vì chạy script trong trang.

Vì không có lớp tự động hoá nào gắn thêm bên ngoài, trang web sẽ thấy:

• không có navigator.webdriver,
• không có phiên CDP (Chrome DevTools Protocol),
• không có cổng gỡ lỗi mở,
• không có script chèn vào và không có isolated world.

Điểm khác biệt

Cách thông thường để điều khiển trình duyệt là qua CDP, phát lại thao tác tức thời và máy móc. Orbe đi theo hướng khác vì làm chủ cả lõi trình duyệt bên dưới: thao tác nhập đi qua đường sự kiện thật, và trang được đọc ở phía trình duyệt.

Bắt đầu nhanh

SDK là một gói Python nhỏ đi kèm bộ cài. Bạn cần Python 3.9 trở lên trên máy Windows chạy Orbe. Cài gói một lần từ thư mục Orbe của bạn (PowerShell):

python -m pip install --force-reinstall (Get-ChildItem "$env:LOCALAPPDATA\Programs\Orbe\app\current\sdk\orbe-*.whl").FullName

Gói chỉ dùng thư viện chuẩn và tự tìm Orbe. Nếu bạn cài Orbe vào thư mục khác, hãy dùng thư mục đó thay cho %LOCALAPPDATA%\Programs\Orbe trong lệnh, và đặt ORBE_EXE là đường dẫn đầy đủ tới Orbe.exe trong app\current. Sau mỗi lần Orbe cập nhật, hãy chạy lại đúng lệnh này để lấy gói mới.

Sau đó nhập gói với tên orbe:

import orbe

# Mở hồ sơ, kết nối kênh và kiểm tra proxy —
# tất cả khi vào khối. Đóng sạch khi thoát khối.
with orbe.Trinh("my-profile") as t:
    t.goto("https://example.com/login")
    t.wait_for("Sign in")            # chờ tới khi chữ xuất hiện
    t.click("Sign in")               # nhấp phần tử mang chữ đó
    t.type("my-username", enter=True)  # gõ với nhịp như người, rồi Enter
    t.scroll(600)                    # một cử chỉ cuộn xuống như người
    print(t.read()[:200])            # đọc chữ đang hiển thị trên trang
    t.screenshot("after-login.png")  # chụp qua compositor

Muốn chạy từ trợ lý AI như Claude thay vì tự viết mã? Xem phần MCP.

Phiên Trinh Python

orbe.Trinh là phiên SDK công khai. Nó an toàn mặc định: kiểm tra proxy và dừng ở checkpoint luôn bật, không có công tắc để tắt, và đó là chủ ý, vì thứ đầu tiên một lượt chạy thiếu kỷ luật làm bạn mất là tài khoản. Chỉ có nhịp nghỉ an toàn cho tài khoản là có thể tắt, theo từng phiên.

orbe.Trinh(profile_id, *, headless=False, timeout=30.0,
           platform=None, pacing="on", on_rest=None, rotate=None, open_on_rotate_fail=False)

Tham số bắt buộc duy nhất là mã hồ sơ; các tham số còn lại là tuỳ chọn chỉ truyền theo tên:

Vòng đời

Điều hướng và chờ

Đọc trang

Thao tác như người

Chụp màn hình

An toàn mặc định

SDK công khai bọc mọi lệnh trong một lớp kỷ luật. Bạn không cần chọn bật, và việc kiểm tra proxy cùng việc dừng ở checkpoint bên dưới không thể tắt; nhịp nghỉ bật mặc định và có thể tắt theo từng phiên.

• Cảnh báo ngoài giờ. Tự động hoá không bao giờ bị dừng vì giờ trong ngày. Khi hồ sơ làm việc ngoài khung giờ quen thuộc — mặc định 7:00–23:00 theo múi giờ của proxy (không có proxy thì theo múi giờ IP của bạn, hoặc quốc gia của hồ sơ nếu không tra được); khi có gợi ý nền tảng thì TikTok 8:00–24:00, YouTube và Google 6:00–24:00, Twitter 7:00–24:00, Facebook, Instagram và Shopee 7:00–23:00 — Orbe cảnh báo một lần mỗi phiên rồi chạy tiếp, ví dụ: "Outside usual active hours 7:00–23:00 (Asia/Ho_Chi_Minh); it is now 23:00. Automation continues — accounts active at unusual hours are more likely to be reviewed." SDK in dòng này ra stderr dưới dạng [orbe] warning: …, máy chủ MCP gửi nó như một thông báo cảnh báo, và Workflow Editor hiện nó thành dòng ! trong kết quả chạy. Cảnh báo chỉ xuất hiện khi nhịp nghỉ đang bật.
• Giới hạn proxy bên khác. Hồ sơ ngoài hạn mức 20 hồ sơ mở không có proxy; tìm cờ proxy_disabled trong danh sách hồ sơ, kết quả mở hồ sơ và các dòng kết quả lô / lịch của Local API và MCP.
• Kiểm tra proxy trước khi mở. Nếu hồ sơ có proxy mà không kết nối được, sai quốc gia hoặc thiết lập chưa đủ, Orbe không mở — chạy trên sai IP tốn kém hơn một lượt chưa bao giờ bắt đầu. Hồ sơ không có proxy mở thẳng bằng IP của bạn.
• Phát hiện checkpoint / captcha. Sau mỗi bước làm thay đổi trạng thái, Orbe đọc trang (chờ cho trang ổn định) và nếu thấy checkpoint hoặc thử thách — trong chữ hoặc trong URL — nó dừng lại, chụp ảnh và báo. Orbe không bao giờ cố giải hay vượt qua checkpoint.

Nhịp nghỉ an toàn cho tài khoản

Tự động hoá của Orbe nghỉ như người: cứ khoảng 1 trong 8 thao tác (nhấp, gõ, cuộn, điều hướng) sẽ có một quãng nghỉ 3–20 giây. Một lệnh có thể chạy lâu hơn thời gian di chuột; đó là chủ ý, không phải treo.

Khi đang nghỉ, máy chủ MCP gửi thông điệp tiến độ resting N s (account-safety pacing); SDK in dòng đó ra stderr, hoặc gọi hàm on_rest(seconds) của bạn trong Python.

Nhịp nghỉ bật mặc định. Bạn có thể tắt cho một phiên hoặc một flow:

• Python — orbe.Trinh(profile_id, pacing="off");
• ngôn ngữ khác — orbe-sdk.cmd <profile-id> --pacing off;
• MCP — open với "pacing": "off";
• Workflow Editor — nút Pacing: On cạnh nút Run, lưu theo từng flow; tắt đi sẽ hỏi bạn xác nhận.

Xử lý khi bị chặn

Khi lớp kỷ luật dừng một lệnh, SDK ném lỗi kỷ luật và công cụ MCP trả về BLOCKED (…) — kèm thông báo tiếng Anh và, với checkpoint, cụm từ khớp, URL và ảnh chụp. Hãy bắt lỗi và xử lý; đừng thử lại một cách mù quáng. Mỗi hàng dưới đây là một điều kiện chặn riêng:

import orbe

try:
    with orbe.Trinh("my-profile") as t:
        t.goto("https://example.com")
        t.click("Post")
except orbe.Blocked as e:
    # Bị chặn. str(e) là thông báo tiếng Anh mô tả điều kiện;
    # lỗi checkpoint còn kèm cụm từ khớp, URL và ảnh chụp.
    notify_me(str(e))          # cần có người xem hồ sơ này
    # KHÔNG thử lại cùng thao tác trong vòng lặp

orbe.RateLimited và orbe.OutsideHours vẫn còn để mã cũ bắt chúng tiếp tục chạy, nhưng Orbe không còn ném chúng nữa: không có giới hạn số thao tác, và không có gì bị chặn vì giờ trong ngày.

Khi không lấy được IP mới

Khi rotate bật (hoặc hồ sơ đã tích Rotate IP on open), việc đổi IP thất bại sẽ ném orbe.RotateFailed và trình duyệt không mở. Đây không phải lỗi chặn của lớp kỷ luật — nó kế thừa orbe.OrbeError, không phải orbe.Blocked. Nó mang .reason và .retry_after:

.retry_after là số giây nguyên khi reason là cooldown, còn lại là None. Truyền open_on_rotate_fail=True để mở bằng IP hiện tại.

Ngôn ngữ khác Mọi ngôn ngữ

Mọi ngôn ngữ đều có thể điều khiển cùng phiên đó qua một giao thức dòng nhỏ. Bộ cài thêm cầu nối orbe-sdk.cmd vào thư mục Orbe của bạn; hãy chạy nó như tiến trình con với mã hồ sơ và trao đổi mỗi dòng một đối tượng JSON qua stdin/stdout (nếu chạy chỉ với mã hồ sơ và không có đầu vào, nó không làm gì). Thử nhanh từ Command Prompt: (echo {"cmd":"open"}& echo {"cmd":"close"}) | "%LOCALAPPDATA%\Programs\Orbe\orbe-sdk.cmd" <profile-id>. Nếu bạn cài Orbe ở nơi khác, hãy dùng thư mục đó.

"%LOCALAPPDATA%\Programs\Orbe\orbe-sdk.cmd" <profile-id> [--rotate on|off] [--open-on-rotate-fail]

→ {"cmd":"open","url":"https://example.com"}   ← {"ok":true,"result":null}
→ {"cmd":"goto","url":"https://example.com"}    ← {"ok":true,"result":"<tab_id>"}
→ {"cmd":"wait_for","text":"Sign in"}           ← {"ok":true,"result":true}
→ {"cmd":"click","text":"Sign in"}              ← {"ok":true,"result":true}
→ {"cmd":"screenshot"}                           ← {"ok":true,"result":{"png_b64":"…"}}
→ {"cmd":"close"}                                ← {"ok":true,"result":null}

Các lệnh giống hệt SDK: open · goto · wait · wait_for · click · click_xy · type · scroll · scroll_until · read · elements · screenshot · close. Một lệnh thất bại trả về {"ok":false,"error":"…"} và không bao giờ làm sập cầu nối. --rotate on|off và --open-on-rotate-fail đặt trên dòng lệnh sau mã hồ sơ (không nằm trong lệnh open); việc đổi IP thất bại trả về {"ok":false,"code":"RotateFailed","error":"…","reason":"…","retry_after":…}. stdout chỉ chứa giao thức JSON; thông tin chẩn đoán đi ra stderr. Hãy đọc kết quả từng dòng và ghép với thứ tự bạn đã gửi.

Local API cho công cụ của bạn

Orbe còn chạy một Local API để script và công cụ của bạn gọi — chỉ trên máy này (127.0.0.1), không bao giờ mở ra mạng. API bật mặc định, ở một cổng ngẫu nhiên chọn khi cài Orbe. Quản lý trong Settings → Local API (mục Local API ở thanh bên mở trang này):

• Enable Local API for external tools — tắt đi nếu bạn không dùng công cụ bên ngoài;
• Port và Apply — đổi cổng;
• Copy URL — địa chỉ, http://127.0.0.1:<port>/orbe/v1;
• Copy key — mọi yêu cầu phải gửi khoá này trong header X-Orbe-Key; thiếu hoặc sai khoá sẽ nhận 401. Hãy coi khoá như mật khẩu — ai có nó đều điều khiển được các hồ sơ của bạn.

Local API điều khiển hồ sơ qua cùng kênh nội bộ với SDK — không CDP, không cổng gỡ lỗi; yêu cầu CDP sẽ bị từ chối kèm lỗi.

MCP — dùng Orbe từ trợ lý AI MCP

Orbe có sẵn một máy chủ MCP cung cấp các thao tác tương tự dưới dạng công cụ, để trợ lý như Claude Code, Cursor hay Codex có thể làm việc trong một hồ sơ bằng ngôn ngữ tự nhiên. Nó cũng không để lại dấu vết như SDK: không CDP, không script trong trang, không cổng gỡ lỗi.

Cài đặt

Trên máy có Orbe (Windows), trong Command Prompt. Máy chủ MCP được tích hợp sẵn trong Orbe.exe, nên không cần cài thêm gì:

claude mcp add orbe -- "%LOCALAPPDATA%\Programs\Orbe\app\current\Orbe.exe" --mcp

Nếu bạn cài Orbe vào thư mục khác, hãy dùng Orbe.exe trong app\current của thư mục đó — đường dẫn này luôn trỏ tới phiên bản hiện tại sau mỗi lần cập nhật. Bạn điều khiển máy chủ qua các công cụ orbe, không phải bằng tên.

Công cụ

Hai công cụ cuối cho phép trợ lý dựng một flow cho người dùng thay vì điều khiển trực tiếp trình duyệt: nó đọc list_blocks, viết flow, rồi submit_flow đưa vào Workflow Editor dưới dạng bản nháp để xem lại — không bao giờ tự chạy. Xem Dựng bằng AI.

Có thể mở nhiều hồ sơ cùng lúc; công cụ nào để trống profile sẽ nhắm vào hồ sơ mở gần nhất.

Trợ lý nên làm việc thế nào

1. open → goto → wait một đoạn chữ đặc trưng trước khi thao tác.
2. read để biết trang có gì; screenshot khi bố cục hoặc hình ảnh quan trọng.
3. Nhấp theo chữ trên phần tử — cách đáng tin nhất. Với biểu tượng không có chữ, hãy đọc toạ độ từ ảnh chụp rồi nhấp x,y.
4. Để gõ vào một ô: click vào ô trước, rồi type.
5. Để tới thứ nằm bên dưới màn hình, dùng scroll_until, đừng đoán bằng nhiều lệnh scroll.
6. Sau mỗi thao tác quan trọng, read hoặc wait để xác nhận trang đã đổi — đừng mặc định là thành công.
7. close khi xong.

Quy tắc cho trợ lý

• Đừng trộn công cụ tự động hoá khác vào hồ sơ Orbe — Playwright, Puppeteer, Selenium hay bất cứ thứ gì gắn vào qua CDP. Chỉ cần gắn một lần là để lại đúng loại dấu vết mà Orbe sinh ra để tránh.
• Di chuyển như người. Nhịp thời gian đã được mô phỏng sẵn; phần việc của bạn là đừng bắn hàng chục thao tác liên tiếp mà không đọc trang.
• Đừng nhập mật khẩu hay bí mật mà người dùng chưa đưa cho bạn trong phiên này.

Công thức mẫu

Bản chạy được đầy đủ của các ví dụ này nằm trên trang này, trong examples/ — login_then_post.py, fill_form.py, scrape_list.py và fleet_multi_profile.py (nhiều hồ sơ cùng lúc) — mỗi tệp chỉ dùng orbe và thư viện chuẩn, thông tin đăng nhập đọc từ biến môi trường. Các đoạn dưới đây cho thấy dạng chung.

Đăng nhập, rồi xác nhận

import orbe

with orbe.Trinh("my-profile") as t:
    t.goto("https://example.com/login")
    t.wait_for("Password")
    t.click("Email")
    t.type("me@example.com")
    t.click("Password")
    t.type("...", enter=True)
    if t.wait_for("Your feed", timeout=20):
        print("logged in")
    else:
        t.screenshot("login-stuck.png")   # để bạn xem bằng tay

Tới thứ nằm bên dưới màn hình

with orbe.Trinh("my-profile") as t:
    t.goto("https://example.com/long-page")
    if t.scroll_until("Load more"):
        t.click("Load more")

Nhấp một phần tử chính xác bằng elements()

with orbe.Trinh("my-profile") as t:
    t.goto("https://example.com")
    for el in t.elements():
        if el["type"] == "button" and "Follow" in (el["text"] or ""):
            t.click_xy(el["x"] + el["w"] // 2, el["y"] + el["h"] // 2)
            break

Orbe không làm gì

Tự động hoá chỉ gỡ dấu vết tự động hoá; nó không thay đổi cách một nền tảng đánh giá tài khoản. Orbe cho mỗi tài khoản một máy trông như thật và nhất quán, IP riêng và thao tác nhập như người — nhưng cách bạn chăm sóc tài khoản vẫn là phần việc của bạn. Công cụ nào hứa chắc chắn không bị khoá thì không trung thực với bạn.

Xem thêm Bắt đầu và Proxy.