会话

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

# Different sessions
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# Or via environment variable
AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"

# List active sessions
agent-browser session list
# Output:
# Active sessions:
# -> default
#    agent1

# Show current session
agent-browser session

# Generate a stable worktree-scoped session id
agent-browser session id --scope worktree --prefix next-dev-loop

# Inspect daemon, launch, and restore status
agent-browser session info --json

会话隔离¶

每个会话都拥有自己独立的内容：

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

共享浏览器中的标签页固定¶

完全隔离仅在每个会话启动自己的浏览器时生效。当多个会话改为通过 --cdp 共享同一个 Chrome 时，只有标签页选择将它们区分开。每个会话都会记住自己绑定到哪个标签页（通过 CDP target ID，并在守护进程重启后持久保留），因此重启后的守护进程会重新挂接到该会话自身的标签页，而不是采用最近激活的那个。

添加 --pin-tab（或设置 AGENT_BROWSER_PIN_TAB=1）来让绑定更严格：

agent-browser --session agent1 --cdp 9222 --pin-tab open https://site-a.com
agent-browser --session agent2 --cdp 9222 --pin-tab open https://site-b.com

使用 --pin-tab 时，如果某个会话所绑定的标签页已被关闭，该会话会收到 tab_gone 错误，而不是静默地在另一个会话的标签页上执行操作；运行 tab new <url> 或从 tab list 中选择一个标签页即可恢复。JSON 输出中包含 "code": "tab_gone"、data.targetId 以及可选的、经过清理的 data.lastUrl。批量输出使用 result 返回相同的恢复对象。该标志按会话保持粘性；传入 --no-pin-tab 可再次关闭。详见 CDP 模式。

在固定标签页的会话运行期间，其他会话无法通过 tab <ref> 占用该固定标签页（会返回 tab_locked），显式执行 close 才会释放固定。

复用 Chrome 配置文件¶

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

# List available Chrome profiles
agent-browser profiles

# Reuse your default Chrome profile's login state
agent-browser --profile Default open https://gmail.com

# Use a named profile (by display name or directory name)
agent-browser --profile "Work" open https://app.example.com

# Or via environment variable
AGENT_BROWSER_PROFILE=Default agent-browser open https://gmail.com

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

持久化配置文件¶

如果你希望使用自定义配置目录在浏览器重启后保持状态，请将路径传给 --profile：

# Use a persistent profile directory
agent-browser --profile ~/.myapp-profile open myapp.com

# Login once, then reuse the authenticated session
agent-browser --profile ~/.myapp-profile open myapp.com/dashboard

# Or via environment variable
AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com

该配置目录会存储：

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

从浏览器导入身份认证信息¶

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

步骤 1： 以远程调试方式启动 Chrome：

# 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： 连接并保存已认证状态：

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

步骤 3： 在后续会话中使用已保存的认证信息：

# Load auth at launch
agent-browser --state ./my-auth.json open https://app.example.com/dashboard

# Or load into an already-launched session
agent-browser open about:blank
agent-browser state load ./my-auth.json
agent-browser open https://app.example.com/dashboard

已保存的 localStorage 和 sessionStorage 是通过 Chrome DevTools 写入的，而不是通过页面 JavaScript；并且仅在页面处于已保存的源上时才会写入。如果某个源重定向到其他位置或加载失败，则该源的存储会被跳过，其余部分仍会加载，并且 state load 会将其列在 skippedOrigins 下。对于在启动时使用 --state 和 --restore 的情况，session info 会将其列在 restoreSkippedOrigins 下。

将 --session <id> --restore 结合使用，导入的认证信息便会在重启后自动持久化：

SESSION="$(agent-browser session id --scope worktree --prefix myapp)"
agent-browser --session "$SESSION" --restore --state ./my-auth.json open https://app.example.com/dashboard
# From now on, state auto-saves/restores for this session

状态文件以明文形式包含会话令牌。请将它们加入 .gitignore，并在不再需要时删除。如需静态加密，请参阅下文状态加密。

会话持久化¶

将 --restore 与固定的 --session 配合使用，即可在浏览器重启后自动保存和恢复 Cookies 及 localStorage：

# Auto-save/load state for this worktree
SESSION="$(agent-browser session id --scope worktree --prefix twitter)"
agent-browser --session "$SESSION" --restore open twitter.com

# Login once, then state persists automatically
agent-browser --session "$SESSION" --restore click "#login"

# Optional validation prevents a bad restore from overwriting the previous good state
agent-browser --session "$SESSION" --restore --restore-check-text Dashboard open twitter.com

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

当配置了 --restore 或其他恢复键时，状态会在浏览器关闭时（显式 close、空闲超时或守护进程关闭）保存，并且还会在浏览器打开期间定期保存，因此您手动关闭的浏览器窗口仍会留下最近的保存记录。单独的会话 ID 只能隔离守护进程，并不能启用持久化；如果没有恢复键，关闭时会丢弃临时的浏览器状态和打开的标签页。定期自动保存会等待命令执行完毕，然后按 AGENT_BROWSER_AUTOSAVE_INTERVAL_MS 的间隔最多保存一次（默认 30000；设置为 0 表示仅在关闭时保存）。配置了持久化的空闲会话会按相同间隔继续保存，因此页面自身产生的更改（Token 刷新、后台请求）也会被捕获。默认情况下，守护进程在一小时内没有收到命令或仪表盘输入后会退出；--idle-timeout <time> 或 AGENT_BROWSER_IDLE_TIMEOUT_MS 可调整此设置，0 表示禁用。有头浏览器、Safari/iOS WebDriver 以及用户附加的浏览器不受默认超时限制；提供商拥有的云浏览器则不在豁免范围内。状态保存遵循 --restore-save 策略。

恢复键规则¶

会话名称和恢复名称仅接受 Unicode 字母、数字、连字符和下划线。例如，café-東京_7 有效，而 my session 因包含空格而被拒绝。

使用 agent-browser session id 生成有效的键：

# Valid generated key
agent-browser session id --scope worktree --prefix my-project

# Invalid (will be rejected)
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）：

# Generate a 256-bit key (64 hex characters)
openssl rand -hex 32

# Set the encryption key
export AGENT_BROWSER_ENCRYPTION_KEY=<your-64-char-hex-key>

# State files are now encrypted automatically
agent-browser --session secure-session --restore open example.com

# List states shows encryption status
agent-browser state list

状态自动过期¶

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

# Set expiration (default: 30 days)
export AGENT_BROWSER_STATE_EXPIRE_DAYS=7

# Manually clean old states
agent-browser state clean --older-than 7

状态管理命令¶

# List all saved states
agent-browser state list

# Show state summary (cookies, origins, domains)
agent-browser state show my-session-default.json

# Rename a state file
agent-browser state rename old-name new-name

# Clear states for a specific session name
agent-browser state clear my-session

# Clear all saved states
agent-browser state clear --all

# Manual save/load (for custom paths)
agent-browser state save ./backup.json
agent-browser state load ./backup.json

已认证会话¶

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

# Headers scoped to api.example.com only
agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

# Requests to api.example.com include the auth header
agent-browser snapshot -i --json
agent-browser click @e2

# Navigate to another domain - headers NOT sent
agent-browser open other-site.com

适用于：

跳过登录流程 - 通过标头进行身份验证
切换用户 - 每个会话使用不同的认证 Token
API 测试 - 访问受保护的端点
安全性 - 标头限定于来源，不会泄露

多个来源¶

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

全局标头¶

用于所有域上的标头：

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

环境变量¶

变量	描述
`AGENT_BROWSER_SESSION`	浏览器会话 ID（默认："default"）
`AGENT_BROWSER_NAMESPACE`	守护进程套接字和恢复状态目录的命名空间
`AGENT_BROWSER_PIN_TAB`	将会话固定到其绑定的标签页（严格标签页绑定）
`AGENT_BROWSER_RESTORE`	自动保存/加载状态持久化键
`AGENT_BROWSER_RESTORE_SAVE`	恢复保存策略：`auto`、`always` 或 `never`
`AGENT_BROWSER_AUTOSAVE_INTERVAL_MS`	定期会话自动保存之间的最小毫秒数（默认：30000，`0` 禁用）
`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）

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 agen/agent-browser