agentic-browser

agentic-browser

为任何 AI Agent 配备真正的浏览器，并观察它的所有操作。

由 Davarion 构建并维护。

无需 API 密钥。无需额外付费。 agentic-browser 是一个工具，不是模型：它在你的电脑上运行，并使用你的 Agent 已有的大脑。可以是你在 Claude Code 中的 Claude Pro/Max 套餐、在 Codex 中使用的 ChatGPT 套餐、Cursor，或本地模型。无需注册，也无需向我们支付按 token 计费的费用。

人类用浏览器浏览网页，而 Agent 通常需要 API。agentic-browser 让任何 Agent 都能像人一样使用你安装的 Google Chrome。它将页面呈现为带像素坐标的精简文本，而不是截图；可见光标会显示每一次移动和点击。

Español · 使用场景 · 聊天观察器 · 架构 · 安全 · 免责声明

▶ 观看 15 秒演示 · ▶ 观看完整视频（1 分钟）

由 Agent 自行录制的真实运行过程：比价 · 网络调研 · 填写表单并在提交前停下。

为什么选择它

当前浏览器 Agent 的问题	agentic-browser
每次查看截图约耗费 1,000–1,500 个 token	文本快照：每个元素约 15 个 token。diff: true 只返回发生变化的内容
Agent 根据图像猜测坐标	每个元素都附带精确的中心坐标 @x,y。browser_element_at(x, y) 无需图像即可告知任意像素位置的内容
你看不到 Agent 正在做什么	红色光标会移向每个目标，点击时会显示涟漪并标注操作
被锁定在某个 Agent 框架中	MCP 服务和纯 HTTP/JSON API：Claude、GPT、Gemini、Hermes、OpenClaw、LangChain、n8n、curl……
精简版 Chromium 构建	你的真实 Chrome：扩展、编解码器、PDF、WebGPU、自动更新
又一个 API 密钥，又一笔账单	都没有。 可使用 Agent 已有的订阅；甚至可选的聊天观察器也能用你的 Claude 套餐运行

快速开始

一行命令（Claude Code）：

claude mcp add agentic-browser -- npx -y agentic-browser-mcp

其他 MCP 客户端：使用 "command": "npx", "args": ["-y", "agentic-browser-mcp"]。要求：Node ≥ 18 和 Chrome（或 Edge）。

从源代码运行

要求：Node ≥ 18 和 Google Chrome。

git clone https://github.com/davarion-tech/agentic-browser.git

cd agentic-browser && npm install

npm run doctor

npm test

在 MCP 客户端中使用

Claude Code：

claude mcp add agentic-browser -- node /absolute/path/to/agentic-browser/src/mcp.js

Claude Desktop、Cursor、Codex、Hermes、OpenClaw 或任何 MCP 客户端：请参阅 examples/mcp-config.json。

**Claude Code 斜杠命令（可选）：**将 skills/agentic-browser 复制到 ~/.claude/skills/。然后使用 /agentic-browser <task>，始终通过此浏览器完成任务，而不是使用其他内置浏览器工具。

接着可以向你的 Agent 提出类似这样的要求：

仅使用 agentic-browser 中的 browser_* 工具。打开 es.wikipedia.org，搜索“Chrome DevTools Protocol”，打开第一个结果，并总结第一段内容。不要截图。

在其他应用中使用（HTTP）

npm run http

curl -s -X POST http://127.0.0.1:8787/tools/browser_navigate -d "{\"url\":\"example.com\",\"snapshot\":true}"

GET /tools 会返回所有工具的 JSON Schema，可直接作为函数定义传递给任何 LLM API。examples/python_client.py 中提供了一个无依赖的 Python 客户端。

可选：聊天监视器

默认关闭。 安装 agentic-browser 只会让你的 Agent 在你要求时使用浏览器。监视器是一个独立进程，必须由你主动开启。

监视器会让 Agent 自己的消息标签页保持打开状态（WhatsApp Web、Telegram、Messenger 等）。等待期间不会消耗任何令牌；收到消息时，它会唤醒 Claude 来阅读消息并拟定回复。后续操作由代码强制执行的策略控制：

• observe： 仅通知你。
• draft（默认）：撰写回复，但绝不发送。
• auto： 发送消息，但仅限允许列表中的对象。在所有模式下，敏感关键词、每小时限额和域名锁定均会生效。

npm run setup

npm run watcher

它使用你的 Claude 订阅（claude setup-token）或 API 密钥运行。请先阅读 docs/WATCHER.md 和 免责声明：许多平台禁止使用非官方机器人。

Agent 能看到什么

# Test bench
url: http://localhost:3000/
viewport 1280x800 scroll=0,0 docH=2090
[3] textbox "Search" ph="type something" @191,124
[4] button "Search" @339,124
[5] select "color" value="Red" opts=[*Red|Green|Blue] @429,124
[6] checkbox "I agree" {checked} @492,124
[10] button "Button in shadow DOM" @652,316
[f1:1] button "Button inside iframe" @214,217

1.3 版新增内容

演示聊天中的聊天监视器：它会为你拟定回复，并将索要银行账户信息的请求和钓鱼链接交由你处理。完整视频。

• 隐私遮罩。browser_cursor_style({ privacy: "whatsapp" }) 或 AGENT_PRIVACY=whatsapp 会模糊联系人、聊天标题和个人资料照片，让你在录制或分享 Agent 屏幕时不会暴露任何人的信息。预设包括：whatsapp、telegram、gmail，也可以使用你自己的 CSS 选择器。Agent 仍可读取所有内容。
• 仅监视你选择的聊天。 在聊天监视器中，contacts: ["Cliente demo"] 会将其他所有聊天排除在外：它们不会唤醒模型；而且在输入消息前，监视器会从页面读取当前打开聊天的标题，因此 Agent 无法在其他地方发送消息。适用于同时包含个人聊天的账号。
• 屏幕通知和每个事件单独录制片段。 对于每条新消息、草稿（“检查后按 Send”）、升级处理和拦截，监视器都会显示提示卡（启用隐私遮罩时不显示姓名）；设置 record: true 后，每个事件都会单独保存为视频。

1.2 版新功能

• 教一次，永久重放。 browser_teach_start 会在 你 于 Agent 的 Chrome 中执行任务时记录操作（点击、输入文本、选择选项、按 Enter）。记录会保存为由角色和名称组成的配方，而非像素，因此即使布局发生变化也能继续使用。browser_replay 可以用新值重复执行（{"search": "October invoices"}），无需感知每一步。密码绝不会被记录：重放时由用户输入。
• 浏览器中新增「Enseñar」（教学）按钮。 Agent 的 Chrome 左侧边缘有一个小标签，无需询问 Agent 即可开始录制。在横幅中为配方命名，按 Finish，然后告诉你的 Agent「重复 」。使用 AGENT_TEACH_BUTTON=0 可将其禁用。
• 清爽的页面。 Chrome 的翻译栏、搜索引擎选择、恢复页面气泡和权限提示均已关闭（权限会被拒绝）。每次导航后，都会通过点击可见的关闭或拒绝按钮关闭网站弹窗（语言选择、新闻简报、Cookie 横幅、「使用 Google 登录」），绝不接受、订阅或登录。browser_dismiss 可按需执行此操作；AGENT_AUTO_DISMISS=0 可关闭自动处理。
• 一次调用获取结构化数据。 browser_extract 会将最相关的表格或重复列表（产品、搜索结果、联系人）转换为 JSON 或 CSV 行，包含标题、链接、价格和图片。合并的表头也会得到正确处理。CSV 输出可安全地在 Excel 中打开。
• 实时 Token 计数器。 browser_cursor_style({ hud: true })（或 AGENT_HUD=1）会在页面角落显示已用 Token 数量，以及截图所需的 Token 数量。browser_stats 会返回相同数据。计算公式：Token ≈ 字符数 / 4；每次感知调用的单张截图 ≈ 宽度 × 高度 / 750。

工具

工具	用途
browser_snapshot	**主要感知工具。**显示元素及其 ref、角色、名称、状态和中心坐标 @x,y。diff: true 仅返回变更
browser_find	按文本查找页面上的元素，包括屏幕外的元素
browser_element_at	将像素坐标映射到元素（角色、文本、是否可点击、DOM 路径），无需图像
browser_cursor	查看 Agent 光标的位置及其下方的内容
browser_click / browser_move	按 ref 或 x,y 执行可见元素的点击或悬停（按钮、双击、修饰键）
browser_type / browser_press	输入真实键盘内容：clear、submit，以及 Control+L 等快捷键
browser_scroll / browser_drag	鼠标滚轮；拖放
browser_select / browser_upload	<select> 选项；文件输入框
browser_navigate / browser_history / browser_tabs	导航和标签页
browser_read / browser_eval	可读取文本（包装为不可信内容）；任意 JS（仅在设置 AGENT_ALLOW_EVAL=1 时可用）
browser_extract	将表格或重复列表转换为 JSON 或 CSV 行（标题、url、价格、图像等）。file 可将其保存到磁盘
browser_teach_start / browser_teach_stop	记录用户执行一次的任务，并将其保存为可重复使用的操作方案
browser_recipes / browser_replay	列出或显示操作方案；使用新的 params 重放方案，几乎不消耗 token
browser_stats	比较本次会话已用 token 与截图等效用量
browser_dismiss	关闭遮挡页面的弹窗（仅关闭或拒绝，绝不接受）。在 browser_navigate 后自动运行
browser_batch	按顺序在一次调用中执行多个操作，遇到第一个错误时停止。每个操作可节省一个 Agent 轮次
browser_wait / browser_watch	等待指定时间、文本或选择器。页面变更时，browser_watch 会以 零 token 消耗暂停（例如出现新消息或标题变为“(3) Inbox”）
browser_request_human	通过页面横幅将控制权交给正在查看页面的用户（用于登录、2FA、CAPTCHA 或需要做出决定的情况）
browser_console / browser_events / browser_trace	JS 控制台和错误；对话框、下载和新标签页；每个操作的审计记录
browser_cursor_style	显示或隐藏光标、光标轨迹或实时 token 计数器（hud）
browser_record_start / browser_record_stop	将活动标签页录制为视频，视频包含红色光标，可用于制作演示片段，无需 OBS。如果 PATH 中有 ffmpeg，则生成 MP4（H.264），否则生成 WebM。返回路径、时长和大小
browser_screenshot	最后手段：截取页面或单个 ref 的 JPEG

大多数操作都支持 snapshot: true，并会在同一响应中返回新的页面状态，从而每个步骤节省一个 Agent 轮次。

**可靠性功能：**如果元素可被唯一识别，重新渲染后 ref 仍然有效。如果模态框遮挡目标，点击时会发出警告（occluded）。会遍历开放的 shadow DOM 和 iframe。操作结果会报告新标签页、对话框和下载。连续三次重复相同调用时会触发循环警告。

配置

变量	默认值
AGENT_HEADLESS	0	1 = 无窗口（服务器、CI）
AGENT_CDP_URL	—	连接到使用 --remote-debugging-port=9222 --user-data-dir=… 启动的 Chrome
AGENT_PROFILE	~/.agentic-browser/profile	持久化的 Agent 配置文件（Cookie 和登录状态在重启后仍然保留）
AGENT_DOWNLOADS	~/.agentic-browser/downloads	下载文件夹
AGENT_SPEED	normal	日常工作用 fast（光标移动 ≤ 250 ms，按键之间无延迟），录制用 demo（速度较慢，便于跟随）
AGENT_CURSOR_SPEED	来自 AGENT_SPEED	光标每移动 100 px 所需的毫秒数；0 = 立即移动
AGENT_VIEWPORT	窗口大小	使用窗口时，Chrome 会最大化打开，页面使用实际窗口大小。1280x800 可固定窗口大小（无头模式始终使用 1280×800）
AGENT_TOOLS	all	core（13 个核心工具）或以逗号分隔的列表。工具越少，提示词令牌越少
AGENT_AUTO_DISMISS	1	0 会停止在每次导航后关闭网站弹窗
AGENT_TEACH_BUTTON	1	0 会隐藏悬浮的 "Enseñar" 按钮
AGENT_HUD	0	1 会从一开始显示实时令牌计数器
AGENT_PRIVACY	—	从一开始启用隐私遮罩：whatsapp、telegram、gmail 和/或以逗号分隔的 CSS 选择器
AGENT_RECIPES	~/.agentic-browser/recipes	保存教学配方（JSON）的位置
AGENT_EXPORTS	~/.agentic-browser/exports	browser_extract 写入文件的位置
AGENT_READONLY	0	1 会禁用所有会更改页面的工具
AGENT_ALLOWED_ORIGINS	—	域名允许列表，例如 wikipedia.org,localhost（包含子域名）
AGENT_DIALOGS	dismiss	alert/confirm/prompt：dismiss（自 1.1.0 起为默认值：不会单独接受 confirm("Delete?")）或 accept。对话框文本会作为事件传递给 Agent
AGENT_TRACE	~/.agentic-browser/trace.jsonl	每次工具调用的审计日志
AGENT_CHROME	自动检测	浏览器路径。任何 Chromium 浏览器均可：Chrome、Edge（会自动回退到它）、Brave、Chromium
AGENT_HTTP_PORT / AGENT_TOKEN	8787 / 自动生成	HTTP 端口和必需的 Bearer 令牌。若未设置 AGENT_TOKEN，系统会在 ~/.agentic-browser/http-token 中生成一个（可通过 AGENT_TOKEN_FILE 配置路径）。来自网页的请求会被拒绝
AGENT_NO_SANDBOX	0	1 会在无沙箱模式下启动 Chrome。仅适用于以 root 身份运行的 Linux 或无法启动沙箱的容器；这会降低隔离性
AGENT_ALLOW_EVAL	0	1 会启用 browser_eval（默认关闭：它可以读取 Cookie 并外传数据）
AGENT_UPLOAD_DIRS	下载文件夹	browser_upload 可从中上传文件的文件夹；Windows 使用 ; 分隔，macOS/Linux 使用 : 分隔
AGENT_RECORDINGS	~/.agentic-browser/recordings	browser_record_stop 保存视频的位置
AGENT_FFMPEG	ffmpeg	用于 MP4 录制的 ffmpeg 路径；none 会强制回退到 WebM

限制

• Canvas、WebGL 和地图： DOM 不会描述其中绘制的内容。使用带 ref 的 browser_screenshot，只需为该区域付费。
• 封闭的 shadow root 不会公开其子元素。
• Chrome 自身的界面（地址栏、菜单、权限提示）不属于 DOM。请改用 browser_navigate、browser_tabs 和环境变量。
• 无法解决 CAPTCHA，也无法规避机器人检测。 Agent 应调用 browser_request_human。
• 较新的 Chrome 版本会阻止对默认个人配置文件进行远程调试。Agent 使用自己的配置文件；请先在那里登录一次。

路线图

根据对浏览器 Agent 最常见的抱怨（引用过时、令牌膨胀、弹窗、多 Agent 冲突、提示词注入、可观测性）：

• 为 Agent 自有账户提供参考聊天监视器：收到新消息时以零令牌唤醒，并根据代码强制执行的策略回复（默认草稿、允许列表、敏感关键词、速率限制、域名锁定）。参见 docs/WATCHER.md。
• 教学模式和配方回放、结构化提取、实时令牌计数器、关闭弹窗和 browser_batch（1.2）。
• 在同一配置文件中支持多 Agent 会话，并提供标签页所有权和租约。
• browser_batch：一次调用执行多个操作。
• 隐藏文本检测（使用 CSS 隐藏的指令），作为提示词注入信号。
• 会话回放：轨迹加上光标的 GIF/视频。

法律声明

根据 MIT License 发布。按原样提供，不提供任何保证。**您需对自己及 Agent 如何使用本软件承担全部责任。**这包括遵守法律以及您自动化操作的网站的服务条款。请阅读完整的免责声明。

由 Davarion 制作。与 Google 无关。“Google Chrome”是 Google LLC 的商标。