会话#

运行多个相互隔离的浏览器实例：

bash

# 不同会话
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# 或通过环境变量
AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"

# 列出活动会话
agent-browser session list
# Output:
# Active sessions:
# -> default
#    agent1

# 显示当前会话
agent-browser session

# 生成稳定的、按 worktree 作用域划分的会话 ID
agent-browser session id --scope worktree --prefix next-dev-loop

# 查看守护进程、启动和恢复状态
agent-browser session info --json

会话隔离#

每个会话都有自己的：

浏览器实例
Cookies 和存储
导航历史
认证状态

Chrome 配置文件复用#

复用现有登录状态最简单的方法是：把 Chrome 配置文件名传给 --profile。agent-browser 会把该配置文件复制到临时目录（只读快照），并使用你现有的 cookies 和会话启动 Chrome。

bash

# 列出可用的 Chrome 配置文件
agent-browser profiles

# 复用默认 Chrome 配置文件的登录状态
agent-browser --profile Default open https://gmail.com

# 使用命名配置文件（按显示名称或目录名称）
agent-browser --profile "Work" open https://app.example.com

# 或通过环境变量
AGENT_BROWSER_PROFILE=Default agent-browser open https://gmail.com

详情	说明
支持的浏览器	Chrome, Chrome Canary, Chromium, Brave
复制内容	Cookies、local storage、扩展状态（为加快速度，会排除缓存目录）
原始配置文件	永不修改（只读快照）
清理	浏览器关闭时删除临时副本
Windows 注意事项	如果 Chrome 正在运行，请先关闭 Chrome 再使用 `--profile <name>`

持久化配置文件#

如果想使用一个在浏览器重启后仍保留状态的自定义配置文件目录，请把路径传给 --profile：

bash

# 使用持久化配置文件目录
agent-browser --profile ~/.myapp-profile open myapp.com

# 只登录一次，然后复用已认证会话
agent-browser --profile ~/.myapp-profile open myapp.com/dashboard

# 或通过环境变量
AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com

该配置文件目录会存储：

Cookies 和 localStorage
IndexedDB 数据
Service workers
浏览器缓存
登录会话

从浏览器导入认证#

如果你已经在 Chrome 中登录了某个站点，可以抓取那个认证状态并在 agent-browser 中复用。这是绕过登录流程、OAuth、SSO 或 2FA 的最快方式。

步骤 1： 使用远程调试启动 Chrome：

bash

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

在这个 Chrome 窗口中登录你的目标站点。

--remote-debugging-port 会在 localhost 上暴露完整的浏览器控制能力。任何本地进程都可以连接。仅应在受信任的机器上使用，并在完成后关闭 Chrome。

步骤 2： 连接并保存认证状态：

bash

agent-browser --auto-connect state save ./my-auth.json

步骤 3： 在未来的会话中使用已保存的认证：

bash

# 启动时加载认证
agent-browser --state ./my-auth.json open https://app.example.com/dashboard

# 或加载到已启动的会话中
agent-browser open about:blank
agent-browser state load ./my-auth.json
agent-browser open https://app.example.com/dashboard

结合 --session <id> --restore，即可让导入的认证在重启后自动持久化：

bash

SESSION="$(agent-browser session id --scope worktree --prefix myapp)"
agent-browser --session "$SESSION" --restore --state ./my-auth.json open https://app.example.com/dashboard
# 从现在开始，这个会话会自动保存/恢复状态

状态文件以明文包含会话 token。请把它们加入 .gitignore，并在不再需要时删除。如需静态加密，请参见下面的状态加密。

会话持久化#

将 --restore 与稳定的 --session 一起使用，可以在浏览器重启之间自动保存和恢复 cookies 以及 localStorage：

bash

# 为这个 worktree 自动保存/加载状态
SESSION="$(agent-browser session id --scope worktree --prefix twitter)"
agent-browser --session "$SESSION" --restore open twitter.com

# 只登录一次，然后状态自动持久化
agent-browser --session "$SESSION" --restore click "#login"

# 可选校验可防止错误恢复覆盖之前的有效状态
agent-browser --session "$SESSION" --restore --restore-check-text Dashboard open twitter.com

状态文件存储在 ~/.agent-browser/sessions/ 中，并会在导航前自动加载。默认 --restore-save auto 策略下，如果恢复或校验失败，就会跳过自动保存。

恢复键规则#

会话名和恢复名只能包含字母数字字符、连字符和下划线。可使用 agent-browser session id 生成合法 key：

bash

# 有效的生成 key
agent-browser session id --scope worktree --prefix my-project

# 无效（会被拒绝）
agent-browser --session "../bad" --restore open example.com    # path traversal
agent-browser --session "my session" --restore open example.com # spaces
agent-browser --session "foo/bar" --restore open example.com    # slashes

状态加密#

使用 AES-256-GCM 加密已保存的状态文件（cookies、localStorage）：

bash

# 生成 256 位密钥（64 个十六进制字符）
openssl rand -hex 32

# 设置加密密钥
export AGENT_BROWSER_ENCRYPTION_KEY=<your-64-char-hex-key>

# 状态文件现在会自动加密
agent-browser --session secure-session --restore open example.com

# 列出状态时会显示加密状态
agent-browser state list

状态自动过期#

自动删除旧状态文件，防止累积：

bash

# 设置过期时间（默认：30 天）
export AGENT_BROWSER_STATE_EXPIRE_DAYS=7

# 手动清理旧状态
agent-browser state clean --older-than 7

状态管理命令#

bash

# 列出所有已保存状态
agent-browser state list

# 显示状态摘要（cookies、来源、域名）
agent-browser state show my-session-default.json

# 重命名状态文件
agent-browser state rename old-name new-name

# 清除某个特定会话名的状态
agent-browser state clear my-session

# 清除所有已保存状态
agent-browser state clear --all

# 手动保存/加载（用于自定义路径）
agent-browser state save ./backup.json
agent-browser state load ./backup.json

已认证会话#

使用 --headers 为特定来源设置 HTTP 头：

bash

# 只作用于 api.example.com 的 headers
agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

# 发送到 api.example.com 的请求会包含认证头
agent-browser snapshot -i --json
agent-browser click @e2

# 导航到其他域名时不会发送这些 headers
agent-browser open other-site.com

适用于：

跳过登录流程 - 通过 headers 完成认证
切换用户 - 每个会话使用不同的认证 token
API 测试 - 访问受保护的端点
安全性 - headers 只作用于来源，不会泄漏

多个来源#

bash

agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'

全局 headers#

对所有域名生效的 headers：

bash

agent-browser set headers '{"X-Custom-Header": "value"}'

环境变量#

变量	说明
`AGENT_BROWSER_SESSION`	浏览器会话 ID（默认：`"default"`）
`AGENT_BROWSER_NAMESPACE`	守护进程 socket 和恢复状态目录的命名空间
`AGENT_BROWSER_RESTORE`	自动保存/加载状态的持久化 key
`AGENT_BROWSER_RESTORE_SAVE`	恢复保存策略：`auto`、`always` 或 `never`
`AGENT_BROWSER_RESTORE_CHECK_URL`	恢复后的状态必须匹配的 URL 模式
`AGENT_BROWSER_RESTORE_CHECK_TEXT`	恢复后的状态必须包含的页面文本
`AGENT_BROWSER_RESTORE_CHECK_FN`	恢复后的状态必须满足的 JavaScript 表达式
`AGENT_BROWSER_SESSION_NAME`	旧版自动保存/加载状态持久化名称
`AGENT_BROWSER_ENCRYPTION_KEY`	AES-256-GCM 加密用的 64 字符十六进制密钥
`AGENT_BROWSER_STATE_EXPIRE_DAYS`	自动删除早于 N 天的状态（默认：30）