open-browser-use

Open Browser Use

概述

Open Browser Use 将 MV3 Chrome 扩展、本地原生消息传递主机、命令行、SDK，以及可选的 stdio MCP 服务连接起来，让 Agent 能够自动化操作真实的 Chrome 配置文件。它并非专为 Codex.app 设计；请根据你所使用的 Agent 运行时调整命令、MCP 配置和 SDK 示例。

核心工作流

1. 使用 open-browser-use ping 或 obu ping 检查设置。如果因缺少设置而失败，请阅读 references/installation.md。
2. 从已连接的目标中选择正确的浏览器／配置文件。在发出浏览器命令前，请先参阅下文的“浏览器和配置文件处理”。
3. 在打开或认领标签页之前，为当前 Agent 任务选择一个唯一的浏览器会话 ID。如果可用，优先使用周边运行时的对话／会话 ID；否则，创建一个简短的唯一 ID，例如 obu-<task-slug>-<timestamp>。此任务中的每条 Open Browser Use 命令都使用同一个 ID。
4. 在打开或认领标签页之前，为当前浏览器任务组命名。使用简短的任务标签，后接 - OBU；如果没有更合适的任务标签，则使用 Task - OBU。
5. 在打开新标签页之前，运行 user-tabs / user_tabs，检查任务是否要从现有标签页继续，包括 ✅ Open Browser Use 或更早的 handoff 任务组中的标签页。如果 URL／标题／组明显与当前任务相符，请认领该标签页并从中继续，而不是打开重复标签页。在验证或接受本地更改时，这也包括用户已打开的开发服务器标签页（例如 localhost、127.0.0.1 或 *.local / *.test 主机）：请认领并复用该标签页，而不是再打开同一应用的另一个副本。
6. 对于简单检查或一次性操作，请使用命令行：info、tabs、user-tabs、history、open-tab、navigate、cdp 和 call。
7. 如果用简短的逐行操作计划就能满足需求，无需编写 SDK 代码，则使用 open-browser-use run / obu run 进行命令行级别的多步编排。
8. 如果周边 Agent 运行时支持本地 MCP 服务，请配置 obu mcp，并直接调用公开的浏览器工具。使用 MCP 工具 run_action_plan 进行相同的逐行编排。请阅读 references/sdk-and-protocol.md。
9. 对于较大型的多步工作流、事件订阅、更丰富的控制流，或周边 Agent 运行时已在运行代码时，请使用 JavaScript、Python 或 Go SDK。请阅读 references/sdk-and-protocol.md。
10. 在结束浏览器操作前，请使用 open-browser-use finalize-tabs --session-id "$OBU_SESSION_ID" --keep '<json-array>'、MCP 工具 finalize_tabs，或 SDK 方法 finalizeTabs / finalize_tabs / FinalizeTabs，释放会话标签页或保留这些标签页。
11. 如果设置完成后通信失败，请阅读 references/troubleshooting.md。

操作规则

• 将浏览器视为用户的真实 Chrome 配置文件。不要检查 Cookie、密码、会话存储或无关的浏览器数据。
• 安装扩展、为用户打开 Chrome、启用扩展权限、上传本地文件、读取／写入剪贴板数据、提交表单、购买、删除、发送或进行其他对外可见的更改之前，先征得用户同意。
• 不要假定 Codex.app 辅助工具、Node REPL 全局变量或捆绑的插件 UI 可用。请使用已安装的 open-browser-use / obu CLI 或已发布的 SDK。
• 不要猜测标签页 ID。先列出标签页，再使用 tabs、user-tabs、open-tab 或 SDK 调用返回的 ID。
• 对于现有用户标签页，优先使用 claim-tab / claimUserTab。认领标签页应基于当前的 user-tabs 结果，以及 URL、标题、最近访问时间或分组等可见证据。
• 对于后续任务，打开标签页前先检查 user-tabs，并复用 ✅ Open Browser Use 中或之前交接分组里的匹配标签页。如果某个交付标签页仍是面向用户的结果，可以将其认领到新的任务会话中、在其中继续操作，并在完成后再次将其标记为 deliverable。这样可以让针对同一页面的重复工作收敛到同一个活动标签页。
• 不要仅仅因为某些交付标签页位于 ✅ Open Browser Use 中，就认领无关的标签页。如果有多个标签页都可能匹配，优先选择最近访问且 URL／标题完全匹配的标签页；如果无法确定，请询问用户。
• 验证或接受本地代码更改时，优先复用用户已经打开的开发服务器标签页（主机、端口和应用匹配，例如 localhost:<port>），而不是打开新标签页。根据主机、端口以及路径或标题进行匹配；如果有多个标签页都可能匹配，或者无法确定，请询问用户，而不要打开重复标签页。
• 仅当用户或运行时明确提供 socket 时才使用 --socket。否则，让 CLI 和 SDK 自动发现活动 socket 注册表。
• 对于 Agent 任务，不要依赖 CLI 的回退会话 obu-cli。始终为 CLI 和 MCP 命令传入每个任务唯一的 --session-id，或在 SDK 客户端中设置 sessionId / session_id / SessionID。此回退会话仅供快速手动使用，在不同 Agent 会话之间可能复用过时的任务分组。
• 只有在使用相同的显式 --session-id 时，直接 CLI 子命令和 open-browser-use run 才能共享同一浏览器会话。结束浏览器操作前，请先完成该会话。
• 仅当没有更安全的便捷命令或 SDK 封装时，才使用 call --method <method> --params '<json>'。

浏览器和配置文件处理

有些用户会使用多个受支持的浏览器（例如 Google Chrome、Google Chrome Beta 或 BitBrowser），也可能在其中使用多个配置文件。即使浏览器／配置文件已关闭，已安装的目标仍会显示，因此请根据 CONNECTED 状态（而非已安装目标的数量）判断是否需要询问 Agent 此任务应操作哪个目标。

1. 执行任何浏览器命令之前，先列出已安装的浏览器／配置文件目标：

   open-browser-use profiles --connected
   

   列包括 BROWSER、DIRECTORY（稳定的配置文件 ID，例如 Default、 Profile 1）、DISPLAY NAME（用户在浏览器头像菜单中看到的名称）、 VERSION 和 CONNECTED（该目标的主机当前是否可访问）。可通过 --json 获取 JSON 输出，其中包含稳定的 target，例如 chrome:Default、chrome-beta:Default 或 bitbrowser:<instance>:Default。

2. 如果用户已指定浏览器／配置文件，请使用该目标。如果它未连接，请让用户先打开它，再重试。不要悄悄改用其他已连接的目标。

3. 如果用户未指定目标，请统计已连接的目标数。如果恰好有一个目标已连接，即使列表中还有其他已安装但未连接的目标，也无需询问，直接继续。将该已连接目标的选择器传递给后续命令，确保任务固定使用该目标。

4. 如果有多个目标已连接，请在执行第一个浏览器命令之前询问用户要使用哪一个。列出每个已连接目标的浏览器名称、目录名称和显示名称，以便用户识别。

5. 如果没有目标已连接，请让用户先打开一个，再运行浏览器命令。若列表中有多个已安装目标，请询问用户想打开哪一个；若恰好列出一个，则直接说明其名称。如果没有已安装目标，请按照安装指南操作。

6. 选定目标后，在任务剩余部分的每个 CLI／MCP 命令中传递 --browser <selector>，并在需要时传递 --profile <selector>。 浏览器选择器可以是 chrome、chrome-beta、bitbrowser 等 ID、浏览器显示名称或 BitBrowser 实例 ID。配置文件选择器可以是目录名称（Default、Profile 1）或显示名称（Eva、cookiy.com），且不区分大小写。任务进行期间不要切换浏览器／配置文件。

7. 如果 --browser／--profile 与任何运行中的主机都不匹配，CLI 会显示当前已连接的目标。请让用户打开选定的浏览器／配置文件，然后重试；不要悄悄改用其他目标。

8. 对于 MCP，请在服务启动时锁定浏览器／配置文件：

   [mcp_servers.open_browser_use]
   command = "obu"
   args = ["mcp", "--session-id", "obu-<task-id>", "--browser", "<browser>", "--profile", "<profile>"]
   

   不要将浏览器／配置文件作为单个工具调用的参数传递——MCP 服务会将启动时的选择器应用于每次调用。

9. 不要在互不相关的任务之间记住用户选择的浏览器／配置文件。后续任务可能需要使用不同的目标；请再次询问，不要自行假设。

常见 CLI 操作

export OBU_SESSION_ID="obu-docs-scan-$(date +%Y%m%d%H%M%S)"
open-browser-use ping --session-id "$OBU_SESSION_ID"
open-browser-use info --session-id "$OBU_SESSION_ID"
open-browser-use name-session --session-id "$OBU_SESSION_ID" --name "Task - OBU"
open-browser-use tabs --session-id "$OBU_SESSION_ID"
open-browser-use user-tabs --session-id "$OBU_SESSION_ID"
open-browser-use history --session-id "$OBU_SESSION_ID" --query "example" --limit 20
open-browser-use open-tab --session-id "$OBU_SESSION_ID" --url https://example.com
open-browser-use navigate --session-id "$OBU_SESSION_ID" --tab-id <tab-id> --url https://example.com
open-browser-use cdp --session-id "$OBU_SESSION_ID" --tab-id <tab-id> --method Runtime.evaluate --params '{"expression":"document.title"}'
open-browser-use finalize-tabs --session-id "$OBU_SESSION_ID" --keep '[]'

如需在不编写 SDK 代码的情况下进行 CLI 层级的编排，请使用逐行的操作计划：

open-browser-use run --session-id "$OBU_SESSION_ID" -c '
name-session "Docs scan - OBU"
open-tab https://docs.browser-use.com
wait-load domcontentloaded
page-info
finalize-tabs []
'

每行操作共享同一个会话／轮次。open-tab 和 claim-tab 会设置默认标签页，供后续针对标签页的操作使用，例如 wait-load、page-info、navigate、cdp、move-mouse 和 wait-file-chooser。

如果可用，请使用 obu 作为简短别名。

MCP 用法

对于能够通过 stdio 启动本地 MCP 服务的运行时，请使用：

[mcp_servers.open_browser_use]
command = "obu"
args = ["mcp", "--session-id", "obu-<task-or-conversation-id>"]

每个 Agent 任务或对话都使用一个新的 --session-id 值。如果运行时具有稳定的对话／会话 ID，请从中派生 MCP 的 --session-id。

MCP 服务会提供多种工具，包括 user_tabs、open_tab、claim_tab、 navigate、wait_load、page_info、cdp、history、run_action_plan、 finalize_tabs 和不受限制的 call。

如果运行时希望执行与 open-browser-use run 所支持格式相同的简洁操作计划，而不想为每项浏览器操作分别启动 shell 命令，请使用 run_action_plan。

标签页生命周期

• 会话标签页是 Open Browser Use 为当前 Agent 工作流创建或认领的标签页。
• 每个 Agent 任务或对话使用一个唯一的会话 ID。不要在无关任务之间共用备用会话 obu-cli。
• 任务会话组应根据任务命名，格式为 <short task> - OBU。备用名称使用 Task - OBU。
• 开始相关的后续任务时，先列出所有用户标签页，并检查 tabGroup、title 和 url，然后再创建任何新内容。将现有的匹配交付物或交接标签页（或用户已打开的本地开发服务器页面）认领到当前会话；只有在没有合适标签页时才打开新标签页。
• 默认不保留任何标签页：open-browser-use finalize-tabs --session-id "$OBU_SESSION_ID" --keep '[]'。
• 仅当用户在本轮结束后仍需要该实时页面时才保留标签页。提取所需内容后，移除研究、来源、搜索、中间、重复、空白、错误和登录/导航标签页。
• 当标签页本身就是面向用户的输出或用户要求打开的页面时，将其状态设为 status: "deliverable" 并予以保留，例如创建或编辑的文档、仪表板、结账/购物车、已提交的表单结果，或用户明确要求直接查看的页面。
• 仅当任务仍在进行中，且用户或后续轮次需要从当前任务组继续时，才保留 status: "handoff" 状态的标签页，例如等待用户输入、登录、审批、付款、CAPTCHA 或尚未完成的工作流页面。
• 交接标签页留在任务会话组中。交付物标签页移至共享的 ✅ Open Browser Use 标签页组。
• 将最终整理作为本轮最后一次 Open Browser Use 浏览器操作。最终整理后不要再调用 Open Browser Use 浏览器工具；如果还需要进行浏览器操作，应先完成，然后再根据最终标签页处置方案整理一次。

文件选择器、下载和剪贴板

• 文件上传使用拦截式文件选择器流程：开始等待，在页面中触发选择器，然后使用 set-file-chooser-files 或对应 SDK 设置绝对本地路径。
• 可通过 SDK 通知处理程序或 waitForDownload 和 downloadPath 等 Browser Use 方法监控下载。
• 剪贴板辅助工具通过当前受控标签页操作，应视为敏感的用户操作。

参考资料

• references/installation.md：一次性 CLI 和浏览器扩展设置，包括需要用户配合的情况。
• references/sdk-and-protocol.md：JavaScript、Python、Go、socket 和 JSON-RPC 的使用详情。
• references/troubleshooting.md：连接失败、过期 socket、扩展/本地主机检查以及权限问题。