Profile、Cookie 同步、密钥与 2FA
大多数值得自动化的工作都需要先登录。要让托管浏览器处于登录状态,又不把密码写进代码,有三种方式:登录一次,把会话保存在 Profile 中;用 Cookie 同步把你已有的 cookie 复制进 Profile;或者让智能体任务根据模型永远看不到的密钥(secret)完成登录输入,包括 2FA 验证码。
Profile
Profile 以一个名称保存会话的 cookie、localStorage 和 IndexedDB。用 profile: { name: "shop-account", persist: true } 启动会话,会加载它并在会话结束时保存回去;用 profile: "shop-account" 启动,则以只读方式加载。除非你传入 identity 或 fingerprint,Profile 还会自带身份:同一台设备,以及只要该 IP 仍在线就保持不变的同一个住宅 IP。完整规则见Profile:只需登录一次;通过 SDK 使用时,请参阅云端 Profile 上的持久化上下文。
查看 Profile 中有哪些内容(不含具体值):
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 按排序列出最多 50 个站点,不带开头的点。bytes 是压缩后的大小。storage 列出随 Profile 一起保存的站点存储(Local Storage、IndexedDB);只包含导入 cookie 的 Profile 中该字段为空。名称不存在时返回 404 NOT_FOUND。
没有任何端点会返回 cookie 的值。Profile 的内容只会在我们的服务器上打开:合并导入时、统计其内容时,以及在运行使用它的会话的服务器上。
Cookie 同步
如果你已经在别处登录(你自己的浏览器、本地的 Clearcote、Playwright 脚本),把这些 cookie 复制到云端 Profile,之后在该 Profile 上的每个会话启动时都已处于登录状态:
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": "…" }- 支持任何常见的 cookie 格式。CDP 格式(
Network.getCookies、Network.Cookie/CookieParam)和 Playwright 格式(context.cookies()、storage state 文件中的cookies)都可以直接使用;可以用url代替domain。没有expires、expires: -1(任何不大于 0 的值)或session: true表示会话 cookie,已经过期的 cookie 会被跳过。sameSite为Lax、Strict或None,不区分大小写,且None需要secure: true。 - 按 Chrome 的规则检查。只要有一个 Chrome 会拒绝的 cookie(值中含
;、sameSite: "None"但没有secure、违反规则的__Secure-或__Host-cookie、路径不以/开头),整个导入就会返回400,错误信息中会指出是哪个 cookie。 - 保存的字段为
name、value、domain(转为小写)、path(默认/)、secure、httpOnly、sameSite(仅当你发送了它时)和expires(会话 cookie 没有此字段)。其他字段,例如partitionKey,会被丢弃。 mode: "merge"(默认)添加你的 cookie,并替换名称、域名和路径都相同的 cookie。mode: "replace"让 Profile 的 cookie 与你发送的列表完全一致。无论哪种方式,Profile 的 localStorage 和 IndexedDB 都会保留。- 限制:每次请求最多 5000 个 cookie,合并后 Profile 中最多 5000 个(
400 TOO_MANY);名称最长 256 个字符,值最长 4096,路径最长 1024;整个 Profile 压缩后最多 3.5 MB(413 TOO_LARGE);每 10 分钟最多导入 60 次。 - 尚不存在的 Profile 会被创建。当一个保存到该 Profile 的会话(
persist: true)正在启动或运行时,导入会被拒绝并返回409 PROFILE_IN_USE:那个会话结束时会把导入的内容覆盖掉。 - 导入的会话 cookie(没有过期时间)会像其他 cookie 一样加载到之后的会话中。保存该 Profile 的会话会丢弃它们,就像真实浏览器重启时一样,因此如果之后还需要,请重新导入。
响应会给出导入后 Profile 中的 cookie 数(cookies)以及接收了你的多少个 cookie(imported:过期的 cookie 和重复项不计入),并按排序列出其前 50 个域名。
在你的机器上使用 SDK
clearcote 命令从 cookie 所在的位置读取,并且只上传你指定的域名:
# 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(指定多个时重复使用)选取浏览器会发送给该域名的 cookie:它自己的、其子域名的以及其父域名的(--domain shop.example.com也会带上.example.com的 cookie,但绝不会带上.com这类纯后缀上的 cookie)。既没有--domain也没有--all-domains时,命令会拒绝运行,以免意外上传 Profile 中的所有 cookie。--all-domains上传全部内容。只在专为这一项工作创建的 Profile 上使用。--replace发送mode: "replace";默认为合并。- 在代码中,
profiles.sync(name, …)接受相同的选择:from_profile、from_cdp、from_file或login_url中恰好一个(Node:fromProfile、fromCdp、fromFile、loginUrl),然后是domains=[…]或all_domains=True(allDomains: true),以及replace=True。它返回上面所述的导入响应;没有任何 cookie 匹配时,它不会上传任何内容,并抛出ValueError(Node 中为Error)。
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"cookie 在有效期内与密码同样重要:持有会话 cookie 的人就是以你的身份登录的。只上传这项工作需要的域名,别的一概不传。有些站点会把登录绑定到登录时所用的设备或 IP,并让复制过去的 cookie 失效;对于这类站点,请改为在托管会话中用 persist: true 登录一次。
密钥与 2FA
智能体任务可以输入模型永远看不到的值:密码、账号,以及 TOTP 身份验证器的当前验证码。把它们放在 secrets 中,并在任务描述里用 {{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"])| 字段 | 类型 | 含义 |
|---|---|---|
"name": "value" | string | 普通值,在任务 url 的主机(及其子域名)上输入。 |
value | string | 值,1 到 1024 个字符。 |
totp | base32 string | 代替值的 2FA 密钥:即二维码旁边显示的设置密钥(字母 A–Z 和数字 2–7,最多 128 个;可以包含空格和小写字母)。任务运行时输入当前的验证码。 |
digits | 6 | 8 | 仅限 TOTP。默认 6。 |
period | 30 | 60 | 仅限 TOTP,单位为秒。默认 30。 |
domains | string[] | 允许输入它的主机:1 到 10 个主机名,例如 example.com(至少两级标签;不含协议、路径、端口或 *),每个都包含其子域名。默认:url 的主机。 |
- 密钥可以是字符串、
{ value, domains? }或{ totp, domains?, digits?, period? }。 每个任务最多 20 个。名称以字母开头,由字母、数字和_组成,最长 32 个字符。 - 任务描述中的
{{name}}如果不在secrets中,会返回400(unknown secret "name")。在没有url的任务中使用没有domains的密钥也是如此:没有可以绑定的主机。引用请严格写成{{name}},不要加空格。 - 允许传入任务描述中从未提到的密钥;创建响应中的
warnings会注明这一点。 - 注意主机。默认情况下,密钥绑定到
url的主机及其子域名:https://shop.example.com/login覆盖shop.example.com,但不覆盖login.example.com。如果登录表单位于另一个主机(单点登录、身份提供商),请把它列在domains中。 - TOTP 验证码遵循使用 SHA-1 的 RFC 6238,与身份验证器应用一致。验证码在输入的那一刻才计算,因此总是当前有效的那个。
- 密钥只属于一个任务。它们不会随 Profile 保存,任务结束后也不会保留:下一个任务需要再次发送(或者在已登录的 Profile 上运行下一个任务,跳过登录)。
模型能看到什么
Jet 启动之前,任务描述中的每个 {{name}} 都会被替换为随机占位符,例如 CCSECRET_password_k3x9qa,并且任务描述中会加上一句话,说明占位符必须按原样输入。模型得到的就只有这些。当 Jet 输入占位符时,服务器上的浏览器层会在那一刻换入真实值或当前的 TOTP 验证码,而且仅当页面的主机是该密钥的 domains 之一或其子域名时才会这样做(对于 iframe 中的字段,框架的主机也必须符合)。在其他任何主机上,该步骤会以 needs_input 停止(“secret password is not allowed on other.example”),不会输入任何内容。
返回的所有内容都会以同样的方式清理:在 detail、markdown、每个步骤的 text、output JSON 以及事件中,密钥的值、其当前 TOTP 验证码和占位符都显示为 {{name}}。由此带来的一个结果是:如果页面显示了某个密钥(比如登录后的邮箱地址),而你的 schema 要求提取它,你得到的是 {{email}},而不是地址本身。
安全模型
什么保护什么,以及边界在哪里:
- 你的 API 密钥就是你的账户。凭它可以用你的余额启动浏览器、使用你的 Profile、读取你的任务。请把它放在服务器上,绝不要放进浏览器或你分发的应用中。
- Profile 是私有且加密的。每个 Profile 都加密存储(AES-256-GCM,每个客户一个密钥),并且只在我们的服务器上打开:合并导入时、统计其内容时,以及在运行使用它的会话的服务器上。其他客户的同名 Profile 是另一个 Profile。没有任何端点会返回 cookie 的值(当然,在该 Profile 上运行的会话可以通过 CDP 读取它自己的 cookie)。
- Cookie 同步只上传你选择的内容。只有你能向自己的 Profile 导入,且受上述限制(5000 个 cookie、3.5 MB),也绝不能导入到正在启动或运行中的会话要保存的 Profile。域名的选择在你这一侧完成:
clearcote cloud profile sync和profiles.sync()会拒绝上传整个 cookie 库,除非你传入--all-domains/all_domains=True。 - 密钥在任务开始前一直处于封存状态。它们以同样的方式加密,保存在任务的设置中,只有在服务器领取该任务时才会打开。它们只交给那台服务器一次,存储的设置随即被删除。在服务器上,它们只保存在内存中,并通过标准输入传给 Jet 进程:绝不会出现在环境变量、命令行、日志或事件中。如果服务器领取任务时已无法打开它们,任务会以
failed结束,session.endReasonsecrets_unreadable。 - 模型永远不会收到密钥。它使用的是占位符,真实值只会在你允许的主机上输入。试图诱导智能体在别处输入你密码的页面(提示词注入)只会得到一个被拒绝的步骤,而不是密码。
- 输出会被清理。在任务返回或存储的所有内容中,值、TOTP 验证码和占位符都会被替换为
{{name}}。 - Jet 与服务器自身的凭据隔离运行。每个任务都是一个独立进程,拥有明确且最小化的环境:服务器的密钥和代理凭据绝不会传给它或浏览器。浏览器仍受托管环境的防护:不能访问本地文件,不能访问私有网络。
以及这些措施覆盖不到的地方:
- 你登录的站点会收到这个值。这正是目的所在;请谨慎选择
domains。 - 页面可能会显示它。值输入到普通字段后,页面就会显示它。Jet 会在模型读取页面之前把输入的值换回占位符,但只限于它以输入时的原样(或 URL 编码形式)出现的地方:页面若以改动后的形式显示它,例如重新排版或部分遮挡,就无法拦截。密码字段永远不会被读取。
- 录像会记录屏幕。普通字段中的值会出现在视频中。对于不希望留档的登录,请保持
record关闭。 - 任务描述不是机密。它随任务一起存储,并显示在仪表盘和任务列表中。绝不要把值直接写进任务描述;请始终使用
{{name}}。 - 链接就是钥匙。人工交接链接或控制链接能让持有者在过期前以登录状态操控浏览器。只把它发给需要操作的人。