Chuyển đến nội dung

Profile, đồng bộ cookie, secret và 2FA

Phần lớn công việc đáng tự động hóa đều nằm sau một bước đăng nhập. Có ba cách để một trình duyệt hosted ở trạng thái đã đăng nhập mà không cần đặt mật khẩu trong code của bạn: đăng nhập một lần và giữ phiên trong một profile, chép cookie bạn đã có vào profile bằng đồng bộ cookie, hoặc để một lượt chạy agent gõ thông tin đăng nhập từ các secret mà mô hình không bao giờ thấy, kể cả mã 2FA.

Profile

Profile lưu cookie, localStorage và IndexedDB của một phiên dưới một cái tên. Khởi động phiên với profile: { name: "shop-account", persist: true } để nạp profile và lưu lại khi phiên kết thúc, hoặc với profile: "shop-account" để nạp ở chế độ chỉ đọc. Trừ khi bạn truyền identity hoặc fingerprint, profile còn mang theo danh tính riêng: cùng một thiết bị, và cùng một IP dân cư chừng nào IP đó còn online. Quy tắc đầy đủ nằm ở Profile: đăng nhập một lần; từ SDK, xem persistent context trên một profile cloud.

Để xem một profile chứa gì, không kèm giá trị:

bash
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account
# {
#   "name": "shop-account",
#   "cookies": 42,
#   "domains": ["example.com", "shop.example.com"],
#   "bytes": 18211,
#   "storage": "Local Storage,IndexedDB",
#   "updatedAt": "2026-10-02T09:20:11.000Z"
# }

domains liệt kê tối đa 50 site, đã sắp xếp, không có dấu chấm ở đầu. bytes là kích thước sau khi nén. storage cho biết loại lưu trữ site được lưu kèm (Local Storage, IndexedDB); trường này trống với profile chỉ chứa cookie được import. Tên không tồn tại trả về 404 NOT_FOUND.

Không endpoint nào trả về giá trị cookie. Nội dung của profile chỉ được mở trên server của chúng tôi: để gộp một lần import, để đếm những gì nó chứa, và trên server đang chạy một phiên dùng profile đó.

Nếu bạn đã đăng nhập ở đâu đó (trình duyệt của chính bạn, một Clearcote local, một script Playwright), hãy chép các cookie đó vào một profile cloud, và mọi phiên trên profile đó sẽ bắt đầu ở trạng thái đã đăng nhập:

bash
curl -X PUT https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account/cookies \
  -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{
    "mode": "merge",
    "cookies": [
      { "name": "session_id", "value": "…", "domain": "shop.example.com", "path": "/",
        "secure": true, "httpOnly": true, "sameSite": "Lax", "expires": 1798761600 }
    ]
  }'
# { "name": "shop-account", "cookies": 42, "imported": 1, "domains": ["example.com", "shop.example.com"],
#   "bytes": 18211, "updatedAt": "…" }
  • Mọi định dạng cookie phổ biến. Định dạng CDP (Network.getCookies, Network.Cookie / CookieParam) và định dạng Playwright (context.cookies(), phần cookies của file storage state) đều dùng được nguyên trạng; có thể dùng url thay cho domain. Không có expires, expires: -1 (mọi giá trị đến 0) hoặc session: true nghĩa là session cookie, và cookie đã hết hạn sẽ bị bỏ qua. sameSite là Lax, Strict hoặc None, không phân biệt hoa thường, và None cần secure: true.
  • Được kiểm tra như Chrome kiểm tra. Một cookie mà Chrome sẽ từ chối (có ; trong giá trị, sameSite: "None" mà không có secure, một cookie __Secure- hoặc __Host- vi phạm quy tắc của loại đó, một path không bắt đầu bằng /) khiến toàn bộ lần import trả về 400, với thông báo nêu tên cookie đó.
  • Được lưu gồm name, value, domain (chuyển thành chữ thường), path (mặc định /), secure, httpOnly, sameSite (chỉ khi bạn gửi) và expires (không có với session cookie). Các trường khác, chẳng hạn partitionKey, bị bỏ đi.
  • mode: "merge" (mặc định) thêm cookie của bạn và thay thế các cookie có cùng tên, domain và path. mode: "replace" làm cho cookie của profile đúng bằng danh sách bạn gửi. Dù cách nào, localStorage và IndexedDB của profile vẫn được giữ.
  • Giới hạn: tối đa 5000 cookie mỗi request, và 5000 cookie trong profile sau khi gộp (400 TOO_MANY); tên tối đa 256 ký tự, giá trị tối đa 4096, path tối đa 1024; toàn bộ profile tối đa 3.5 MB sau khi nén (413 TOO_LARGE); 60 lần import mỗi 10 phút.
  • Profile chưa tồn tại sẽ được tạo. Trong khi một phiên lưu vào profile (persist: true) đang khởi động hoặc đang chạy, lần import sẽ bị từ chối với 409 PROFILE_IN_USE: phiên đó sẽ ghi đè lên nó khi kết thúc.
  • Session cookie được import (không có thời hạn) được nạp vào các phiên tiếp theo như mọi cookie khác. Một phiên lưu profile sẽ bỏ chúng đi, như trình duyệt thật làm khi khởi động lại, nên hãy import lại nếu bạn còn cần chúng sau đó.

Phản hồi cho biết số cookie của profile sau lần import (cookies) và số cookie của bạn được nhận (imported: cookie đã hết hạn và cookie trùng bị loại ra), đồng thời liệt kê 50 domain đầu tiên của profile, đã sắp xếp.

Từ máy của bạn, với SDK

Lệnh clearcote đọc cookie từ nơi bạn đang có chúng và chỉ upload các domain bạn chỉ định:

bash
# a local Clearcote profile folder (the user_data_dir of launch_persistent_context)
clearcote cloud profile sync shop-account --from-profile ./profiles/shop --domain example.com

# a browser that is running with a CDP endpoint, for example clearcote serve
clearcote cloud profile sync shop-account --from-cdp http://127.0.0.1:9222 --domain example.com

# a Playwright storage-state file: context.storage_state(path="state.json")
clearcote cloud profile sync shop-account --from-file state.json --domain example.com --domain example-cdn.net

# sign in by hand: opens a local Clearcote window on a throwaway profile at the URL,
# you sign in and press Enter, and the cookies for the chosen domains are uploaded
clearcote cloud profile sync shop-account --login https://shop.example.com/login --domain example.com
  • --domain (lặp lại nếu cần nhiều domain) chọn các cookie mà trình duyệt sẽ gửi tới domain đó: cookie của chính nó, của các subdomain và của các domain cha (--domain shop.example.com cũng lấy cookie .example.com, nhưng không bao giờ lấy cookie đặt trên một hậu tố trơn như .com). Không có --domain hay --all-domains thì lệnh từ chối chạy, để không có gì vô tình upload mọi cookie trong một profile.
  • --all-domains upload tất cả. Chỉ dùng cho profile được tạo riêng cho đúng công việc này.
  • --replace gửi mode: "replace"; mặc định là gộp.
  • Từ code, profiles.sync(name, …) nhận cùng các lựa chọn: đúng một trong from_profile, from_cdp, from_file hoặc login_url (Node: fromProfile, fromCdp, fromFile, loginUrl), rồi domains=[…] hoặc all_domains=True (allDomains: true), và replace=True. Hàm trả về phản hồi import ở trên, và ném ValueError (một Error trong Node) mà không upload gì khi không có cookie nào khớp.
from clearcote import launch_persistent_context
from clearcote.cloud import Cloud

cloud = Cloud()

# the same as the command line
cloud.profiles.sync("shop-account", from_file="state.json", domains=["example.com"])

# or upload cookies you have in hand, here from a local profile you signed in with
# (cloud=False: this folder is on your machine, whatever CLEARCOTE_CLOUD says)
ctx = launch_persistent_context("./profiles/shop", cloud=False)
cookies = ctx.cookies("https://shop.example.com")       # only this site's cookies
ctx.close()
cloud.profiles.import_cookies("shop-account", cookies)  # mode="merge"

Khi còn hiệu lực, một cookie có giá trị ngang mật khẩu: ai giữ session cookie thì được đăng nhập dưới tên bạn. Chỉ upload các domain mà công việc cần, không gì khác. Một số site gắn lần đăng nhập với thiết bị hoặc IP đã dùng để đăng nhập và đăng xuất cookie bị sao chép; với những site đó, hãy đăng nhập một lần bên trong một phiên hosted với persist: true.

Secret và 2FA

Một lượt chạy agent có thể gõ những giá trị mà mô hình không bao giờ thấy: mật khẩu, số tài khoản và mã hiện tại từ một ứng dụng xác thực TOTP. Đặt chúng trong secrets và tham chiếu tới chúng trong task bằng {{name}}:

import os
from clearcote.cloud import Cloud

run = Cloud().runs.create(
    "Sign in with {{email}} and {{password}}. If a code is asked for, enter {{otp}}. "
    "Then open Orders and read the number of the latest order.",
    url="https://shop.example.com/login",
    secrets={
        "email": "me@example.com",
        "password": {"value": os.environ["SHOP_PASSWORD"]},
        "otp": {"totp": os.environ["SHOP_TOTP_SECRET"]},
    },
    schema={"type": "object", "properties": {"order": {"type": "string"}}, "required": ["order"]},
    profile={"name": "shop-account", "persist": True},   # next time it starts signed in
)
print(run["status"], run["result"]["output"])
Tab này chạy trên máy của bạn.
TrườngKiểuÝ nghĩa
"name": "value"stringMột giá trị thường, được gõ trên host của url của lượt chạy (và các subdomain của nó).
valuestringGiá trị, từ 1 đến 1024 ký tự.
totpbase32 stringMột secret 2FA thay cho giá trị: khóa thiết lập hiển thị cạnh mã QR (chữ A–Z và chữ số 2–7, tối đa 128; dấu cách và chữ thường đều được). Lượt chạy sẽ gõ mã hiện tại.
digits6 | 8Chỉ cho TOTP. Mặc định 6.
period30 | 60Chỉ cho TOTP, tính bằng giây. Mặc định 30.
domainsstring[]Các host mà nó được phép gõ vào: 1 đến 10 tên host như example.com (ít nhất hai nhãn; không có scheme, path, port hay *), mỗi host bao gồm cả các subdomain của nó. Mặc định: host của url.
  • Một secret là một string, { value, domains? } hoặc { totp, domains?, digits?, period? }. Tối đa 20 secret mỗi lượt chạy. Tên bắt đầu bằng một chữ cái và gồm chữ cái, chữ số và _, dài tối đa 32 ký tự.
  • Một {{name}} trong task mà không có trong secrets sẽ trả về 400 (unknown secret "name"). Một secret không có domains trên lượt chạy không có url cũng vậy: không có host nào để gắn nó vào. Hãy viết tham chiếu đúng như {{name}}, không có dấu cách.
  • Secret mà task không hề nhắc tới vẫn được chấp nhận; trường warnings trong phản hồi tạo lượt chạy sẽ ghi chú điều đó.
  • Chú ý host. Mặc định, secret được gắn với host của url và các subdomain của nó: https://shop.example.com/login bao gồm shop.example.com, không bao gồm login.example.com. Nếu form đăng nhập nằm trên một host khác (single sign-on, một identity provider), hãy liệt kê host đó trong domains.
  • Mã TOTP tuân theo RFC 6238 với SHA-1, đúng như các ứng dụng xác thực sử dụng. Mã được tính ngay lúc được gõ, nên luôn là mã hiện tại.
  • Secret thuộc về một lượt chạy. Chúng không được lưu cùng profile và không được giữ lại sau lượt chạy: hãy gửi lại với lượt chạy tiếp theo (hoặc chạy lượt tiếp theo trên một profile đã đăng nhập và bỏ qua bước đăng nhập).

Mô hình thấy gì

Trước khi Jet bắt đầu, mỗi {{name}} trong task được thay bằng một placeholder ngẫu nhiên như CCSECRET_password_k3x9qa, và task được thêm một câu nói rằng placeholder phải được gõ đúng như đã viết. Đó là tất cả những gì mô hình nhận được. Khi Jet gõ một placeholder, lớp trình duyệt trên server sẽ thay vào giá trị thật, hoặc mã TOTP hiện tại, ngay tại thời điểm đó, và chỉ khi host của trang là một trong các domains của secret hoặc là subdomain của một trong số đó (với một trường nằm trong iframe, thì cả host của frame). Trên bất kỳ host nào khác, bước đó dừng lại với needs_input (“secret password is not allowed on other.example”) và không có gì được gõ.

Mọi thứ trả về đều được làm sạch theo cùng cách: trong detail, markdown, text của từng bước, JSON output và các sự kiện, giá trị của secret, mã TOTP hiện tại của nó và placeholder của nó đều hiển thị là {{name}}. Một hệ quả: nếu trang hiển thị một secret (ví dụ địa chỉ email sau khi đăng nhập) và schema của bạn yêu cầu nó, bạn sẽ nhận được {{email}}, chứ không phải địa chỉ đó.

Mô hình bảo mật

Cái gì bảo vệ cái gì, và giới hạn nằm ở đâu:

  1. API key của bạn chính là tài khoản của bạn. Nó có thể khởi động trình duyệt bằng số dư của bạn, dùng profile của bạn và đọc các lượt chạy của bạn. Hãy giữ nó trên server, không bao giờ đặt trong trình duyệt hay trong ứng dụng bạn phát hành.
  2. Profile là riêng tư và được mã hóa. Mỗi profile được lưu ở dạng mã hóa (AES-256-GCM, với một khóa riêng cho từng khách hàng) và chỉ được mở trên server của chúng tôi: để gộp một lần import, để đếm những gì nó chứa, và trên server đang chạy một phiên dùng profile đó. Profile cùng tên của một khách hàng khác là một profile khác. Không endpoint nào trả về giá trị cookie (tất nhiên, một phiên trên profile có thể đọc cookie của chính nó qua CDP).
  3. Đồng bộ cookie chỉ upload những gì bạn chọn. Chỉ bạn mới import được vào profile của mình, trong các giới hạn ở trên (5000 cookie, 3.5 MB), và không bao giờ vào profile mà một phiên đang khởi động hoặc đang chạy đang lưu vào. Việc chọn domain diễn ra ở phía bạn: clearcote cloud profile sync và profiles.sync() từ chối upload toàn bộ kho cookie trừ khi bạn truyền --all-domains / all_domains=True.
  4. Secret được niêm phong cho đến khi lượt chạy bắt đầu. Chúng được lưu mã hóa theo cùng cách, bên trong cấu hình của lượt chạy, và chỉ được mở khi một server nhận lượt chạy. Chúng được giao cho server đó một lần, và cấu hình đã lưu bị xóa ngay lúc đó. Trên server, chúng nằm trong bộ nhớ và được chuyển tới tiến trình Jet qua standard input: không bao giờ qua biến môi trường, dòng lệnh, log hay sự kiện. Nếu không thể mở chúng nữa khi một server nhận lượt chạy, lượt chạy kết thúc với trạng thái failed và session.endReason secrets_unreadable.
  5. Mô hình không bao giờ nhận được secret. Nó làm việc với placeholder, và giá trị thật chỉ được gõ trên các host bạn cho phép. Một trang tìm cách dụ agent gõ mật khẩu của bạn ở nơi khác (prompt injection) sẽ nhận được một bước bị từ chối, chứ không phải mật khẩu.
  6. Đầu ra được làm sạch. Giá trị, mã TOTP và placeholder được thay bằng {{name}} trong mọi thứ mà một lượt chạy trả về hoặc lưu lại.
  7. Jet chạy tách biệt khỏi thông tin xác thực của chính server. Mỗi lượt chạy là một tiến trình riêng với môi trường tường minh và tối thiểu: key của server và thông tin xác thực proxy không bao giờ được truyền cho nó hay cho trình duyệt. Trình duyệt vẫn giữ các lớp bảo vệ của môi trường hosted: không có file local, không có mạng riêng.

Và những gì cơ chế này không bao quát:

  • Site bạn đăng nhập sẽ nhận được giá trị. Đó chính là mục đích; hãy chọn domains cẩn thận.
  • Trang có thể hiển thị nó. Sau khi một giá trị được gõ vào một trường thông thường, trang sẽ hiển thị nó. Jet đổi giá trị đã gõ trở lại thành placeholder trước khi mô hình đọc trang, nhưng chỉ ở những chỗ nó xuất hiện đúng như đã gõ (hoặc ở dạng URL-encoded): một trang hiển thị nó đã bị biến đổi, ví dụ định dạng lại hoặc che một phần, sẽ không bị bắt. Trường mật khẩu không bao giờ được đọc.
  • Bản ghi hình cho thấy màn hình. Giá trị trong một trường thông thường sẽ xuất hiện trong video. Hãy tắt record với những lần đăng nhập bạn không muốn lưu lại.
  • Task không phải là bí mật. Nó được lưu cùng lượt chạy và hiển thị trong dashboard và danh sách lượt chạy. Đừng bao giờ viết giá trị trực tiếp vào task; luôn dùng {{name}}.
  • Link là chìa khóa. Một link bàn giao hoặc link điều khiển cho phép bất kỳ ai có nó điều khiển trình duyệt, ở trạng thái đã đăng nhập, cho đến khi hết hạn. Chỉ gửi nó cho người cần thao tác.

Cập nhật 5 thg 10, 2026 · SDK 0.70.5 · trình duyệt r63

Trang này có hữu ích không?