会话与登录 / Sessions & Auth

一次登录，后续运行直接是登录态；多个 agent 各开一个隔离浏览器， 互不打架。这一页讲三件事：把会话状态存下来跨运行复用、用 --session 并行跑多个浏览器、以及会话守护进程卡住时怎么干净地复位它。

跨运行保存登录态

登录一次，把 cookies 和 localStorage 存进一个文件，之后的运行加载它就直接是登录态—— 不用每次都重新走一遍登录表单。用 state save 保存；启动时用 --state 带上， 或用 state load 把状态注入当前会话再继续：

# 登录一次，保存 cookies + localStorage + 登录状态
$ chrome-use state save ./auth.json

# 启动时带上状态，开局就是登录态
$ chrome-use --state ./auth.json open https://app.example.com

# 或把已保存的状态注入当前会话，再继续操作
$ chrome-use state load ./auth.json
$ chrome-use open https://app.example.com/dashboard

怎么先干净地登录、再把会话存下来，见 登录与凭证——那一页从登录流程的角度讲了同一个 state save。

状态文件是一份普通 JSON，包含 cookies、两种 storage 和来源列表：

{
  "cookies": [...],
  "localStorage": {...},
  "sessionStorage": {...},
  "origins": [...]
}

自动存取：--session-name

不想手动 save/load，就用 --session-name（或环境变量 AGENT_BROWSER_SESSION_NAME）——同名会话的状态会自动保存、并在后续运行时自动恢复：

$ AGENT_BROWSER_SESSION_NAME=my-app chrome-use open https://app.example.com
# 之后用同一个 name 再跑，状态自动恢复

用 --session 并行跑多个浏览器

每个 --session <name> 是一个相互隔离的浏览器——各自独立的 cookies、 LocalStorage / SessionStorage、IndexedDB、缓存、历史记录和标签页。适合测多用户流程或并行抓取：

$ chrome-use --session a open https://app.example.com
$ chrome-use --session b open https://app.example.com
$ chrome-use --session a fill @e1 "alice@test.com"
$ chrome-use --session b fill @e1 "bob@test.com"

想给当前 shell 设一个默认会话，用 AGENT_BROWSER_SESSION=myapp；省略 --session 时命令都落到默认会话。会话不需要时用 close 关掉，用 session list 看还有哪些活跃会话：

$ AGENT_BROWSER_SESSION=myapp chrome-use open https://example.com

# 关掉指定会话
$ chrome-use --session auth close

# 列出活跃会话
$ chrome-use session list

跨会话拿指定标签：targetId 收养

每个会话有自己的标签组、各自分配 t<N> 序号（同一个物理标签在 A 会话是 t8、 在 B 会话是 t1），所以 t<N> 不是跨会话稳定的句柄。要从另一个会话拿到某个具体标签 （比如某会话把表单填了一半、句柄却死了），用稳定的 CDP targetId：

# 重新同步实时标签，每行打印 target: <id>
$ chrome-use tab list --full --session B

# 收养那个确切的标签，不刷新，状态保留
$ chrome-use tab <targetId> --session B

tab list 每次调用都重新发现实时标签集，所以新会话能看到别的会话开的标签（以及被重新挂上的标签）， 而不只是自己的。按 targetId 收养会让 B 会话落到那个搁浅的标签上而不重新加载它， 半填的表单因此得以保留。

复位卡住的守护进程状态

每个会话跑一个后台守护进程 worker 来持有页面句柄。这个守护进程也是 boa JS 引擎的落脚点—— 引擎跑在页面外面，script 才能扛住整页硬跳转不丢状态。 如果某个会话开始出问题——命令打到错的标签、 refs/句柄看起来陈旧，或者你在会话中途升级了 chrome-use 导致旧 worker 残留—— 直接重启守护进程，别去 pgrep/kill 手动找 PID：

# 列出运行中的会话守护进程（含 relay 状态）
$ chrome-use daemon status

# 杀掉所有会话守护进程 worker
$ chrome-use daemon restart

极少数情况：把会话交接给用户（session handoff / resume）

session handoff 是逃生口，不是登录方式。只在某一步 agent 真的做不到时才用——解不了的图形/行为验证码、拿不到的短信/验证器码、硬件密钥轻触、银行"在手机上确认"。先尝试自主完成，实在不行才交接：

$ chrome-use session handoff   # 最后手段：标记会话归用户；告诉用户具体要做什么
# …… 用户做那件 agent 真做不了的事 ……
$ chrome-use session resume    # 取回控制——务必等用户确认做完再执行

相关页面