docs/tools/browser.mdx
控制 Chromium 浏览器进行网页导航、元素交互和内容提取。支持 JavaScript 渲染的动态页面，使用精简 DOM 快照让 Agent 高效理解页面结构。
该命令会自动完成：
- 安装 `playwright` Python 包（旧系统自动降级兼容版本）
- 在 Linux 上安装系统依赖
- 下载 Chromium 浏览器（Linux 服务器自动使用无头精简版）
- 自动检测国内网络并使用镜像加速
Linux 服务器还需安装系统依赖：
```bash
sudo playwright install-deps chromium
```
如果系统较旧（如 Ubuntu 18.04，glibc < 2.28），需安装兼容版本：
```bash
pip install playwright==1.28.0
python -m playwright install chromium
```
国内网络下载 Chromium 较慢，可设置镜像加速：
```bash
export PLAYWRIGHT_DOWNLOAD_HOST=https://registry.npmmirror.com/-/binary/playwright
python -m playwright install chromium
```
Agent 使用浏览器的典型流程：
navigate — 打开目标 URLsnapshot — 获取页面精简 DOM，交互元素自动编号（ref）click / fill / select — 通过 ref 编号操作元素snapshot — 再次快照验证操作结果| 操作 | 说明 | 关键参数 |
|---|---|---|
navigate | 打开 URL | url |
snapshot | 获取页面结构化文本（主要方式） | selector（可选） |
click | 点击元素 | ref 或 selector |
fill | 填入文本 | ref 或 selector，text |
select | 下拉选择 | ref 或 selector，value |
scroll | 滚动页面 | direction（up/down/left/right） |
screenshot | 截图保存到工作区 | full_page |
wait | 等待元素或超时 | selector，timeout |
press | 按键（Enter、Tab 等） | key |
back / forward | 浏览器前进/后退 | - |
get_text | 获取元素文本内容 | selector |
evaluate | 执行 JavaScript | script |
浏览器会根据运行环境自动选择模式：
| 环境 | 模式 |
|---|---|
| macOS / Windows | 有头模式（显示浏览器窗口） |
| Linux 桌面（有 DISPLAY） | 有头模式 |
| Linux 服务器（无 DISPLAY） | 无头模式（headless） |
可在 config.json 中手动覆盖：
{
"tools": {
"browser": {
"headless": true
}
}
}
只需登录一次目标网站，Agent 后续可直接使用。提供两种方式：
开箱即用，登录信息保存在 ~/.cow/browser_profile。无需任何配置。
如需关闭持久化模式，每次都用纯净环境：
{
"tools": {
"browser": {
"persistent": false
}
}
}
让 Agent 连接独立启动的真实 Chrome（而非 Playwright 自带的 Chromium），获得完整浏览器指纹，适合反爬严格的网站。
启动 Chrome 时加上调试端口和独立用户目录：
<Tabs> <Tab title="macOS"> ```bash "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \ --remote-debugging-port=9222 \ --user-data-dir="$HOME/.cow/chrome-cdp" ``` </Tab> <Tab title="Linux"> ```bash google-chrome \ --remote-debugging-port=9222 \ --user-data-dir="$HOME/.cow/chrome-cdp" ``` </Tab> <Tab title="Windows"> ```powershell & "C:\Program Files\Google\Chrome\Application\chrome.exe" ` --remote-debugging-port=9222 ` --user-data-dir="$env:USERPROFILE\.cow\chrome-cdp" ``` </Tab> </Tabs>在 config.json 中配置端点：
{
"tools": {
"browser": {
"cdp_endpoint": "http://localhost:9222"
}
}
}