会话与登录 / Sessions & Auth

登录是自动化里最容易卡住的一步。这一页讲清楚三条稳妥的路子：直接用 snapshot → fill → click → wait 驱动登录表单、把账号收进 chrome-use auth 凭证保险库一键回填、以及处理 Sign in with Google / OAuth 与 Bitwarden 密码和 passkey。 目标是让 agent 用真实浏览器完成登录，而不是把密码留在 shell history 里。

基础登录流程

最直接的方式：打开登录页，用 snapshot -i 读出表单里的可交互元素， 挑出邮箱、密码、提交按钮对应的 @ref，逐个 fill 再 click，最后用 wait --url 确认已经跳到登录后的页面。

$ chrome-use open https://app.example.com/login
$ chrome-use snapshot -i

# 从快照里挑出邮箱 / 密码 / 提交按钮的 @ref，然后：
$ chrome-use fill @e3 "user@example.com"
$ chrome-use fill @e4 "hunter2"
$ chrome-use click @e5
$ chrome-use wait --url "**/dashboard"
$ chrome-use snapshot -i

凭证保险库（auth save / login）

对于要反复登录的站点，把凭证一次性存进本地保险库，之后一条命令就能自动回填并提交。 --password-stdin 让密码从标准输入读取，不进 shell history。

# 保存一份凭证（密码从 stdin 读入，输入后按 Ctrl+D 结束）
$ chrome-use auth save my-app --url https://app.example.com/login \
    --username user@example.com --password-stdin

# 之后一条命令：打开登录页、回填、点击、等待表单完成
$ chrome-use auth login my-app

Sign in with Google / OAuth

点站点自己的 Google 登录按钮，然后 snapshot -i：即使 GSI 的 “Continue as <user>” 按钮位于跨源 iframe 里，它也会拿到一个可点击的 @ref（Chrome 125+）。如果弹出的是账号选择弹窗，切到那个弹窗去驱动即可—— relay 会跟着你点击打开的弹窗走。

# 触发 OAuth 流程
$ chrome-use open https://app.example.com/auth/google

# 等跳到 Google，再读一次快照
$ chrome-use wait --url "**/accounts.google.com**"
$ chrome-use snapshot -i

# 填 Google 账号，逐步推进
$ chrome-use fill @e1 "user@gmail.com"
$ chrome-use click @e2
$ chrome-use wait 2000
$ chrome-use snapshot -i
$ chrome-use fill @e3 "password"
$ chrome-use click @e4

# 等它跳回业务站点
$ chrome-use wait --url "**/app.example.com**"

从 Bitwarden 取密码与 passkey

当你需要真正的用户名 / 密码（或 passkey），而不是复用 cookie 时，姊妹工具 bitwarden-use（bwu） 能从 Bitwarden / Vaultwarden 保险库读出它们，让 agent 用凭证登录，而不只是走 OAuth。 bwu get <item> 返回密码（以及 2FA 验证码），bwu fido2 get 取出 passkey 私钥，用于接受 FIDO2 / WebAuthn passkey 的站点。

# 安装一次
$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/bitwarden-use/main/install.sh | sh

# 取某个条目的密码（及 2FA），直接 pipe 进输入框
$ bwu get github.com | chrome-use fill '#password' --stdin

# 站点需要 FIDO2 / WebAuthn passkey 时，取出 passkey 私钥
$ bwu fido2 get

处理两步验证（2FA）

遇到需要短信 / TOTP / 硬件密钥的第二步时，最省心的办法是让人来完成这一步，脚本在旁边等它跳转。 默认走扩展驱动你真实 Chrome 时窗口本来就可见，直接由你补第二步即可；把控制权正式交回用户用 session handoff（见 会话与持久化），交接后 agent 会拒绝对该会话的驱动命令，直到你交还。 只有在 --launch 另开浏览器时才需要 --headed 让那个窗口可见，再配一个较长的 --timeout 等登录后的 URL。

# 显示浏览器窗口，先用凭证登录
$ chrome-use open https://app.example.com/login --headed
$ chrome-use snapshot -i
$ chrome-use fill @e1 "user@example.com"
$ chrome-use fill @e2 "password123"
$ chrome-use click @e3

# 在窗口里手动完成 2FA，脚本等它跳转（最多 120s）
$ chrome-use wait --url "**/dashboard" --timeout 120000

HTTP Basic 与 Cookie 认证

不是所有站点都走表单。对 HTTP Basic Auth，导航前先设好凭证； 需要手动注入会话时，可以直接设置 cookie。

# HTTP Basic：导航前设置用户名 / 密码
$ chrome-use set credentials username password
$ chrome-use open https://protected.example.com/api

# 手动设置认证 cookie
$ chrome-use cookies set session_token "abc123xyz"
$ chrome-use open https://app.example.com/dashboard

登录一次，之后免登录

登录成本很高，别每次都重来。登录成功后把 cookie 和 localStorage 存成一份 state 文件，后续用 --state 加载即可以“已登录”状态启动。要跳过整套 OAuth / 2FA，这是最实用的一招。

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

# 之后的运行直接带着登录态启动
$ chrome-use --state ./auth.json open https://app.example.com

安全注意事项

登录不可避免地碰凭证和会话令牌。几条底线：

• 别把 state 文件提交进仓库 —— 里面是明文会话令牌，加进 .gitignore，不用了就删。
• 凭证走环境变量或保险库 —— 用 auth save / bwu / --stdin / 环境变量，而不是把密码写死在命令里。
• 加密静态存储 —— 设置 AGENT_BROWSER_ENCRYPTION_KEY 让存下来的会话状态加密。
• 用完清理 —— chrome-use cookies clear 加删掉临时 state 文件；CI 里干脆不落盘、跑完 close。