agent-browser

会话

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

# 不同的会话
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
# 输出：
# 活动会话：
# -> default
#    agent1

# 显示当前会话
agent-browser session

会话隔离

每个会话都有独立的：

  • 浏览器实例
  • Cookie 和存储
  • 导航历史记录
  • 认证状态

持久化配置文件

默认情况下，关闭浏览器后浏览器状态将丢失。使用 --profile 可以在重启之间持久化状态：

# 使用持久化配置文件目录
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

配置文件目录存储以下内容：

  • Cookie 和 localStorage
  • IndexedDB 数据
  • 服务工作线程
  • 浏览器缓存
  • 登录会话

会话持久化

使用 --session-name 可自动保存和恢复浏览器重启期间的 Cookie 与 localStorage：

# 为 "twitter" 会话自动保存/加载状态
agent-browser --session-name twitter open twitter.com

# 登录一次，状态将自动持久化
agent-browser --session-name twitter click "#login"

# 或通过环境变量
export AGENT_BROWSER_SESSION_NAME=twitter
agent-browser open twitter.com

状态文件存储在 ~/.agent-browser/sessions/ 目录中，并在守护进程启动时自动加载。

会话名称规则

会话名称必须仅包含字母数字字符、连字符和下划线：

# 有效的会话名称
agent-browser --session-name my-project open example.com
agent-browser --session-name test_session_v2 open example.com

# 无效（将被拒绝）
agent-browser --session-name "../bad" open example.com    # 路径遍历攻击
agent-browser --session-name "my session" open example.com # 包含空格
agent-browser --session-name "foo/bar" open example.com    # 包含斜杠

状态加密

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

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

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

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

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

状态自动过期

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

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

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

状态管理命令

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

# 显示状态摘要（Cookie、源、域名）
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 头部：

# 头部作用域仅限 api.example.com
agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

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

# 导航到另一个域名 - 不发送头部
agent-browser open other-site.com

用途包括：

  • 跳过登录流程 - 通过头部进行认证
  • 切换用户 - 每个会话使用不同的认证令牌
  • 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_SESSION_NAME自动保存/加载状态持久化名称
AGENT_BROWSER_ENCRYPTION_KEYAES-256-GCM 加密使用的 64 位十六进制密钥
AGENT_BROWSER_STATE_EXPIRE_DAYS自动删除超过 N 天的状态（默认值：30）