企业官网建设流程全解析

如何安装 agent-browser 让 Archon 的 E2E 浏览器测试工作流可用？

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

如果你的 Archon 工作流跑到了archon-validate-pr这类带 E2E 浏览器测试阶段的节点就失败，原因通常是缺少agent-browser——这是 Archon 工作流中用来驱动浏览器的可选外部依赖（由 Vercel Labs 维护），核心 Archon 功能本身并不依赖它。这篇指南的目标很简单：在目标环境中装好agent-browser并验证它能正常打开页面，让依赖它的 E2E 工作流节点可以正常调用。

先确认一下哪些资源会用到它：

先判断你属于哪种运行环境

官方文档 e2e-testing.md 按平台区分了三种情况，动手前先确认你在哪一边：

• Archon 跑在 Docker 里：agent-browser已在官方镜像中预装，无需任何操作。
• macOS / Linux 原生运行 Archon：按下一节的命令安装即可。
• Windows：agent-browser存在一个已知 bug，daemon 因 Unix domain socket 不兼容而无法启动，需要在 WSL 中运行，见本文末尾的可选分支。

Docker 环境：无需安装

Archon 的 Docker 镜像已经内置了agent-browser。docker.md 中说明镜像内含：

• Browser tooling：agent-browser（Vercel Labs）——通过 CDP 驱动浏览器，使 E2E 测试工作流可用，使用系统自带的 Chromium（AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium）。

Dockerfile 中可以看到镜像构建时固定安装了agent-browser@0.22.1，并通过符号链接把 native 二进制放到/usr/local/bin/agent-browser；指向系统 Chromium 的做法也避免了约 400MB 的 Chrome for Testing 下载。所以如果你在 Docker 部署 Archon，直接跑 E2E 工作流即可，不需要再执行任何安装步骤。

macOS / Linux：安装与验证

1. 全局安装 CLI 并下载浏览器引擎

# Install globally npm install -g agent-browser # Download browser engine (Chrome for Testing) agent-browser install

两条命令分工明确：第一条安装agent-browserCLI 本身，第二条下载它要驱动的浏览器引擎（Chrome for Testing）。注意第二条会下载浏览器文件，属于网络下载操作，需要可用的网络环境。

2. 验证安装

agent-browser --version # Expected: prints version number (e.g., 0.x.x) # Quick smoke test — opens a page and closes agent-browser open https://example.com agent-browser close

判断标准：agent-browser --version能打印出版本号（文档给出的预期形如0.x.x，不是固定值），smoke test 能打开一个页面并正常关闭，即说明安装成功，E2E 工作流节点调用agent-browser时可以连上。

3. daemon 起不来时怎么办

macOS / Linux 原生安装后如果 daemon 无法启动，按文档先清理残留的旧 daemon 进程再重试：

# Kill stale daemons and retry pkill -f daemon.js agent-browser open http://localhost:3090

pkill -f daemon.js会杀掉本机所有匹配daemon.js的进程，请确认该进程确实来自agent-browser再执行，避免误杀其他服务。第二条命令中的http://localhost:3090是本地开发环境 Archon 服务的默认地址。

可选分支：Windows 下的 WSL 方案

Windows 上 daemon 直接起不来是已知问题，文档给出的绕法是：agent-browser跑在 WSL 里，开发服务器留在 Windows 侧运行。详细步骤见 e2e-testing-wsl.md，前置条件为：

• WSL2 且已安装 Ubuntu（用wsl --list --verbose检查）；
• WSL 内安装agent-browser：npm install -g agent-browser；
• 安装 Playwright chromium：agent-browser install --with-deps（需要 sudo）。

WSL 环境下与原生安装有两个关键差异，直接影响后续命令能否跑通：

1. localhost从 WSL2 不可达——WSL 内访问 Windows 侧服务必须用 Windows 宿主机 IP。文档示例中该地址为172.18.64.1，这是示例系统的值，需要你用ipconfig | findstr "IPv4" | findstr "WSL"或cat /etc/resolv.conf | grep nameserver查出自己机器的实际地址并替换；
2. Vite 必须绑定0.0.0.0——默认只绑localhost的话 WSL 访问不到，因此前端启动命令需要带--host参数：

# Backend (Hono on port 3090) - already binds to 0.0.0.0 by default bun run dev:server & # Frontend (Vite on port 5173) - needs --host flag cd packages/web && bun x vite --host 0.0.0.0 &

之后所有agent-browser命令都从 Windows 终端发起，用wsl -d Ubuntu --前缀调用，例如：

# Open a page wsl -d Ubuntu -- agent-browser open http://172.18.64.1:5173

若agent-browser open报 "Daemon failed to start"，同样是清理残留 daemon 后重试：wsl -d Ubuntu -- pkill -f daemon.js。

不安装 agent-browser 时的行为

如果确实不打算装agent-browser：所有非 E2E 工作流可以正常运行；但依赖它的 E2E 工作流节点在 agent 尝试调用agent-browser时会失败。文档同时说明，AI agent 是通过 prompt 被要求"在连接失败 2 次后停止并只输出 code-review 报告"的——这是提示词层面的约定而非自动化工作流逻辑，实际表现取决于所用模型对指令的遵循程度，不要把它当作确定性的降级机制。

安装完成后的确认

回到最初的判断标准：

• agent-browser --version能打印版本号；
• agent-browser open/agent-browser close的 smoke test 正常执行；
• 之前失败的 E2E 工作流节点（如archon-validate-pr的 E2E 阶段）再次运行时可以正常调用浏览器，而不是报agent-browser: command not found。

第三条的报错对应关系可以在 troubleshooting.md 的 "E2E Testing / agent-browser" 一节查到：agent-browser: command not found的解法就是本文的两条安装命令，daemon 无法启动则按平台分别走清理进程或 WSL 方案。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon