agent-browser-google-chrome-linux

通过 agent-browser 控制用户已登录的 Chrome（Linux）

agent-browser

如果尚未安装，请先安装一次：

npm i -g agent-browser

不要运行 agent-browser install——它会下载一个没有用户会话的测试版 Chromium，这样就违背了此技能的目的。

运行任何 agent-browser 命令之前，请先通过 CLI 加载实际工作流内容：

agent-browser skills get core             # workflows, common patterns, troubleshooting
agent-browser skills get core --full      # include full command reference and templates

CLI 提供的技能内容始终与已安装的版本匹配，因此说明不会过时。

核心限制

出于安全考虑，Chrome 禁止在默认的 user-data-dir（~/.config/google-chrome）上启用远程调试。你会在 /tmp/chrome.log 中看到此错误：

DevTools remote debugging requires a non-default data directory. Specify this using --user-data-dir.

**解决方法：**将用户的配置文件复制到非默认目录，结束所有 Chrome 进程，再从副本启动并指定调试端口，然后通过 CDP 连接 agent-browser。

第 0 步：找到正确的 DISPLAY

每个人的 Linux 环境都不一样。启动 Chrome 之前，先找到用户桌面会话运行所在的 X 显示：

# Option A: check what the user's shell already has
echo $DISPLAY

# Option B: scan running processes for an X display
ps aux | grep -oP 'DISPLAY=\S+' | sort -u

# Option C: list /tmp/.X11-unix sockets (each one is a display)
ls /tmp/.X11-unix/
# X0 → :0, X1 → :1, etc.

# Option D: look at who's logged into the X session
who | grep '(:[0-9]'

常见值包括 :0、:1 或 :10。使用你找到的值，并在下方命令中替换 DISPLAY=:1。如果你使用的是 Kasm/VNC 环境，通常是 :1，但请先确认。

如果 echo $DISPLAY 返回了内容，那就是正确的值。如果为空，你很可能处于没有 X 转发的 SSH 会话中——请查看 X11-unix 套接字，或向用户确认。

操作步骤（按顺序运行，每次都要执行）

进行完整设置之前，先检查 Chrome 是否已在调试端口上运行——如果是，可以直接连接：

# Quick check: is port 9222 already listening?
curl -s -m 2 http://127.0.0.1:9222/json/version | head -2

如果返回 {"Browser": "Chrome/...，说明 Chrome 已启动并启用了远程调试。运行下方“验证”部分中的单行命令——如果打开的是目标网站（而非登录页面），就说明一切就绪，可以跳过其余步骤。

如果端口未在监听，或打开的是登录页面，请继续执行完整操作步骤：

# 1. Kill ALL Chrome processes (any leftover holds the SingletonLock)
pkill -9 -f 'google-chrome\|/opt/google/chrome/chrome'
sleep 3
pgrep -af chrome | grep -v 'crashpad\|chrome-devtools\|grep'  # confirm empty

# 2. Verify the user's session is fresh in their profile
ls -la ~/.config/google-chrome/Default/Cookies   # check mtime is recent

# 3. Copy profile to a non-default location, strip the lock files
rm -rf /tmp/chrome-debug-profile
cp -a ~/.config/google-chrome /tmp/chrome-debug-profile
rm -f /tmp/chrome-debug-profile/Singleton{Lock,Cookie,Socket}

# 4. Launch Chrome with debug port on the display the user can see
#    Replace :1 with the DISPLAY value you found in Step 0
DISPLAY=:1 nohup google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug-profile \
  --no-sandbox --no-first-run --no-default-browser-check \
  'https://target-url-to-load-immediately' \
  >/tmp/chrome.log 2>&1 &
disown

# 5. Confirm port is listening (3-7s after launch)
sleep 6
curl -s -m 3 http://127.0.0.1:9222/json/version | head -2
# Expect: {"Browser": "Chrome/...

# 6. Connect agent-browser to the running Chrome
agent-browser --session <name> connect 9222
agent-browser --session <name> get url   # sanity check

从这里开始，每条 agent-browser --session <name> ... 命令都会控制用户能看到的同一个 Chrome 窗口。

各项标志的作用

标志	原因
DISPLAY=:1	指定用户会话所在的 X 显示——使用第 0 步找到的正确值
--remote-debugging-port=9222	agent-browser 连接的 CDP 端点
--user-data-dir=/tmp/chrome-debug-profile	Chrome 的“非默认数据目录”规则所要求
--no-sandbox	许多容器／编码环境所必需（没有可用的 SUID 沙盒）
--no-first-run --no-default-browser-check	跳过会阻止初始渲染的欢迎对话框
disown	确保父 Shell 退出后，后台任务仍会运行

注意事项

1. /tmp 会在会话之间被清空。 Coder/沙箱环境有时会清理 /tmp。如果 /tmp/chrome-debug-profile 的大小相比上次使用时大幅缩减（例如从 168M 降到 59M），说明会话已损坏——请从 ~/.config/google-chrome 重新复制。

2. 用户必须先在某处登录。 只有当用户在 ~/.config/google-chrome 中有有效会话时，重新复制才会生效。如果 Cookie 已过期或失效，你会进入无法继续操作的登录页面——请让用户先在常用的 Chrome 中重新验证身份，然后再重新复制。

3. 多个 Chrome 实例 ≠ 多个调试端口。 如果用户运行另一个 google-chrome（不带标志），它会加入现有实例。只有第一个带有 --remote-debugging-port 的实例会绑定端口。务必先运行 pkill。

4. 旧的单实例文件会阻止启动。 执行 cp -a 后，务必从副本中运行 rm -f Singleton{Lock,Cookie,Socket}，否则 Chrome 会拒绝启动。

5. 不要尝试通过调试版 Chrome 登录。 会阻止自动登录的网站（MFA 提示、CAPTCHA、OAuth 流程、无头浏览器检测）也会在这里阻止你。此方法通过借用用户已在常用 Chrome 中建立的会话，完全绕过了这一问题。

6. agent-browser 可能会消失。 agent-browser 是通过 npm 全局安装的，nvm/tmp 清理可能会将其删除。使用 npm i -g agent-browser 重新安装（约 5 秒），然后再次运行 connect 9222——Chrome 的会话会独立保留。

7. 切勿运行 agent-browser install。 agent-browser install 会下载单独的测试版 Chromium，其中没有用户配置文件或 Cookie。务必使用系统的 google-chrome 二进制文件。

8. 初始页面空白或正在加载。 Chrome 启动后需要 3-7 秒，CDP 才会响应。连接前务必先运行 sleep 6，然后运行 curl /json/version。

验证

启动后，确认整个流程正常：

agent-browser --session <name> connect 9222 && \
  agent-browser --session <name> get url

• 目标网站上的真实 URL → 表示已成功进入。
• 登录或身份验证页面 → 复制的会话已过期或失效。请让用户先在常用的 Chrome 中重新验证身份，然后再重新复制。

何时不应使用此方法

如果目标网站不需要身份验证，请跳过配置文件复制，直接启动一个全新的空配置文件：

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/fresh-chrome --no-sandbox &

仅当无法自动登录网站时，才需要执行复制用户配置文件的操作——例如遇到 MFA、CAPTCHA、OAuth 流程，或登录页面上的无头浏览器检测。