腾讯开源 BrowserSkill：让 AI Agent 不打扰地使用已登录浏览器

让 AI Agent 使用你的浏览器，而不会打断你的工作。

English · 中文

BrowserSkill 将 Cursor、Claude Code、Codex、OpenClaw、CodeBuddy、WorkBuddy、Pi、Hermes Agent、DeepSeek Harness 及其他 AI Agent 连接到你已经登录的浏览器。

需要 Agent 操作你已经打开的标签页？它必须明确借用该标签页，在任务完成后归还，并且不触碰你浏览器的其他部分。

[视频/嵌入内容：github.-.mp4]

• 复用真实登录状态：Agent 可以操作你已登录的网站，无需单独的测试账号。
• 持续工作不中断：浏览器任务会在独立、可见的 Agent Window 中运行，因此你可以继续使用自己的浏览器。
• 支持任意 Agent：任何能够调用 shell 的 Agent 都可通过 bsk CLI 使用 BrowserSkill，不绑定特定模型、Agent 框架或 harness。
• 内置人工介入机制：当任务遇到验证码、登录、确认对话框或其他仅限人工完成的步骤时，Agent 可以请求你接手，之后再继续执行。

在 Quick actions → Full-page screenshot 中截取长图，或者让 Agent 使用 bsk screenshot --session <id> --full-page --out page.png。有关页面支持、取消与导出的说明，请参阅全页截图指南。

BrowserSkill 包含两个本地运行时组件：bsk CLI/守护进程和浏览器扩展。

运行时	支持
操作系统	macOS（Apple Silicon 和 Intel）、Linux（x64 和 ARM64）、Windows x64
浏览器	支持 Chrome 和 Microsoft Edge；其他支持加载未打包 Chromium 扩展的 Chromium 浏览器预计也可使用；计划支持 Firefox

正在使用会在每条命令后清理后台进程的 Agent 沙箱？请按照沙箱化 Agent 设置，将守护进程保留在持久化主机环境中，并通过共享的 BSK_HOME 加上 BSK_AUTO_START=0 进行连接。普通本地使用默认保留自动启动。

通过你的 Agent 安装（推荐）

已经在使用 Cursor、Claude Code、Codex 或其他可调用 shell 的 Agent？只需复制下面这一行并发送给你的 Agent——它会为你安装 CLI 和 skill，然后引导你加载扩展：

Set up browser-skill on this machine by following https://raw.githubusercontent.com/Tencent/BrowserSkill/main/AGENT_INSTALL.md

手动安装

安装 CLI，然后从 Chrome Web Store 或 Edge Add-ons 安装扩展。

macOS / Linux（推荐——安装至 ~/.local/bin）：

curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"

Windows（PowerShell——安装至 ~/.local/bin）：

irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex

export 命令会让 CLI 在当前 Unix shell 中可用。正在运行的 Agent 可能需要在每次 shell 调用中设置相同的 PATH，或者使用已安装二进制文件的绝对路径。如果 Agent 在安装后仍保留旧 PATH，请重启 Agent。

在将使用它的终端或 Agent 环境中验证二进制文件：

2. 安装浏览器扩展

从浏览器的扩展商店安装 BrowserSkill：

在其他基于 Chromium 的浏览器上，请安装 Chrome Web Store 版本。

BrowserSkill 随附一个 skill，用于教会你的 Agent harness 如何使用 bsk。对于以下 harness，可一步完成安装：

Cursor |
Claude Code |
Codex |
OpenClaw |
CodeBuddy |
WorkBuddy |
Pi |
Hermes Agent
---|---|---|---|---|---|---|---

使用 Space 选择要安装到的 Agent harness，然后按 Enter 安装 skill。运行 bsk install-skill --list 可查看内部变体和安装路径。

若要进行非交互式安装，请指定目标 harness，例如 bsk install-skill --harness cursor --json。即使未检测到 harness，显式选择同样有效。仅使用 --yes 会安装到所有检测到的 harness；若没有检测到任何 harness，则会失败。

如需安装自己的说明，请使用 bsk install-skill --harness cursor --source ./SKILL.md。即使内容与内置 skill 相同，显式传入 --source 仍会将其视为自定义内容。除非添加 --force，否则会跳过现有安装。

守护进程启动、session start 和 doctor 仅会在受管 skill 的内容仍与上次安装版本一致时自动更新它们。本地编辑会被保留，自动更新则会暂停。对于没有内容基线的旧版安装，只有当其与当前内置 skill 完全一致时才会被自动纳入管理；这一过程会写入来源标记，但不会重写 SKILL.md。显式自定义安装即使内容相同，也始终保持自定义状态。

对于历史文件不同、本地已编辑或来源标记无法识别的情况，doctor 会显示 WARN，并说明原因及恢复选项。这些警告不会导致健康检查失败（--json 会报告 status: "warn" 和 ok: true）。并发安装或同步会被报告为延后处理，并在后续检查中重试。

若要将当前说明保留为显式自定义内容，请运行 bsk install-skill --harness cursor --source <existing-SKILL.md> --force，并将 <existing-SKILL.md> 替换为现有文件的路径。若要恢复内置 skill 并重新启用自动更新，请在不使用 --source 的情况下运行 bsk install-skill --harness cursor --force。第二条命令会覆盖现有说明。

其他支持 shell 的 Agent harness 也同样受支持。将 skill/SKILL.md 复制到你的 harness 的 skills 目录，并保存为 browser-skill/SKILL.md，即可手动安装 skill。DeepSeek Harness 则使用专用插件——请参阅 DeepSeek Harness plugin。

运行 bsk doctor 并按照其提示操作。打开扩展弹窗并确认它已连接。在测试浏览器使用前，解释所有警告并解决失败项。即使未安装 skill，Doctor 也可能通过（N/A）；请单独验证 skill 是否被发现。

启动一个新的 Agent 会话，确认 harness 中可使用 browser-skill，然后要求它打开 https://example.com 并总结页面内容。对于支持斜杠命令调用 skill 的 harness，例如：

/browser-skill open example.com and summarize what is on the page.

首次使用检查成功后，会读取页面并停止其 BrowserSkill 会话。如果缺少 skill，请在重试前检查目标 harness 和安装路径。

对于默认本地设置，请在更新前完成正在进行的浏览器任务：

如果 Windows 报告更新已暂存，请等待替换完成后再检查 bsk --version。

当该命令安装更新时，会使用默认启动设置重启正在运行的守护进程。如果你改用安装程序替换二进制文件，则请在任务结束后通过 bsk daemon restart 重启现有守护进程。

对于自定义端口、由主机管理的沙箱守护进程或远程服务器，请在其所属主机或监督程序中停止守护进程，运行 bsk update --yes --no-restart-daemon，然后以原有参数和 BSK_HOME 在该处启动它。管理守护进程时，请在 Agent 命令中设置 BSK_AUTO_START=0；参阅沙箱和远程设置指南。

通过浏览器商店更新扩展；对于未打包的开发构建，请重新构建并重新加载。商店上架可能会晚于 CLI 发布。使用 bsk --version 和 bsk status 检查 CLI、守护进程和扩展版本，然后运行 bsk doctor。全页截图等新功能需要相互匹配的构建版本。请单独更新 DSH 插件并重启其 profile。受管 CLI skill 会在守护进程启动、session start 或 doctor 时同步；本地编辑和自定义 skill 会得到保留。启动新的 Agent 会话以加载更新后的说明。

升级到 0.3.0：--unattended、tab borrow --no-confirm 和 BSK_REQUEST_HELP=off 不再绕过确认或禁用求助。请改为选择下文所述的对应扩展设置。请参阅变更内容。

扩展弹窗中有两项彼此独立的 Automation settings，且均默认启用。用户保存的浏览器设置对每一个会话都具有最终效力：

借用标签页前确认	允许请求人工协助	行为
开启	开启	借用需要批准；求助请求显示现有 UI。
开启	关闭	借用需要批准；求助请求返回 disabled。
关闭	开启	借用跳过确认；求助请求显示现有 UI。
关闭	关闭	借用跳过确认；求助请求返回 disabled。

设置会自动保存到浏览器 profile，并适用于现有和新建会话。关闭确认会释放待处理的借用确认；关闭求助会将待处理的求助请求以 disabled 结束。重新开启任一设置后，将恢复后续操作的相应行为，包括使用旧版 --unattended 标志创建的会话。已完成的借用不会撤销，已结束的求助请求也不会重新打开。允许求助会使 request-help 可用；这并不要求每个浏览器操作都请求许可。任务授权和主机审批仍然适用。

使用 bsk session start 启动任务；添加 --no-focus 可避免聚焦 Agent Window。若要进行无人值守操作，请在扩展中关闭相应设置。--unattended、tab borrow --no-confirm 和 BSK_REQUEST_HELP=off 为兼容性仍可接受，但已弃用，且无法覆盖这些开关。CLI 使用这些输入时会记录提示；守护进程也会针对继承的环境设置记录提示。过去仅依赖这些输入来避免等待的脚本，现在必须使用浏览器设置。session start --json 和 session list --json 会报告浏览器的有效 interaction 策略。

当求助功能被禁用时，request-help 会返回 disabled，而不会确认任何人工操作。该 skill 会指导 Agent 重新观察，并利用现有登录状态、已授权输入和可用工具，在授权范围内尽合理努力完成步骤。在任务授权和主机规则允许的情况下，具备图像理解能力的模型可尝试图形化验证。仅支持手机扫码的 QR 验证、面部验证、不可获取的短信验证码，以及针对纯文本模型的纯图像 CAPTCHA，仍可能导致任务受阻。disabled 结果既不表示任务完成，也不会授予额外权限。

如果偏好设置加载失败，运行时会保留已知值；若没有可用的有效值，则默认两项均开启。它不会写入回退默认值，也不会阻止会话创建。后续读取和存储事件可以恢复设置。弹窗会报告读取失败并阻止保存；写入失败不会被视为成功。浏览器断开连接会产生错误，而不是基于命令行标志或环境变量返回本地 disabled 结果。

tab borrow --timeout 60s 控制的是确认等待时间，而非是否需要确认。协议 1.3 保留了与协议 1.0–1.2 的连接兼容性。在分阶段升级期间，普通会话和默认标签页借用仍可用。弹窗会标识较旧的守护进程，而 bsk status 会报告协议差异。自定义借用等待时间要求守护进程和扩展均为协议 1.2 或更高版本；若不支持，则只有该操作会返回升级错误。较旧的守护进程可能仍具有较短的默认借用等待时间。

当前 CLI 对 request-help 要求守护进程协议 1.3，因为旧版守护进程可能在不咨询浏览器的情况下于本地响应。这一限制不会断开浏览器连接，也不会停止其他操作。请更新 CLI、正在运行的守护进程和扩展，以完整执行上述设置。新版扩展始终会对其接收到的请求执行已保存的设置。较旧的 CLI 可能会在联系守护进程之前，因 BSK_REQUEST_HELP=off 而在本地退出；混合版本安装会保留这类旧行为，仅更新扩展无法改变这一点。

可在服务器上运行 Agent，并使用内置认证服务或兼容网关将其与你的本地浏览器配对。请参阅远程浏览器连接。

正在使用 DeepSeek Harness（dsh）？BrowserSkill 附带一个 f

Let AI agents use your browser without interrupting your work.

English · 中文

BrowserSkill connects Cursor, Claude Code, Codex, OpenClaw, CodeBuddy, WorkBuddy, Pi, Hermes Agent, DeepSeek Harness, and other AI agents to your already logged-in browser.

Need the agent to touch a tab you already have open? It must borrow that tab explicitly, return it when the task is done, and leave the rest of your browser alone.

github.-.mp4

• Reuse real login state : Agents can work with sites you are already signed into, without separate test accounts.
• Keep working uninterrupted : browser tasks run in a separate, visible Agent Window, so you can keep using your own browser.
• Support any Agent : any Agent that can call a shell can use BrowserSkill through the bsk CLI, with no lock-in to a specific model, Agent framework, or harness.
• Built-in human-in-loop : when a task hits captcha, login, confirmation dialogs, or other human-only steps, the Agent can ask you to take over and then continue afterwards.

Capture a long image in Quick actions → Full-page screenshot , or let an Agent use bsk screenshot --session <id> --full-page --out page.png. See the full-page screenshot guide for page support, cancellation and export.

BrowserSkill has two local runtime pieces: the bsk CLI/daemon and the browser extension.

Runtime	Support
Operating systems	macOS (Apple Silicon and Intel), Linux (x64 and ARM64), Windows x64
Browsers	Chrome and Microsoft Edge are supported; other Chromium-based browsers are expected to work when they support unpacked Chromium extensions; Firefox is planned

Using an agent sandbox that reaps background processes after each command? Follow the sandboxed agent setup to keep the daemon in a persistent host environment and connect with a shared BSK_HOME plus BSK_AUTO_START=0. Ordinary local use keeps automatic startup by default.

Install with your Agent (recommended)

Already using Cursor, Claude Code, Codex, or another shell-capable agent? Just copy this one line and send it to your agent — it will install the CLI and skill for you, then walk you through loading the extension:

Set up browser-skill on this machine by following https://raw.githubusercontent.com/Tencent/BrowserSkill/main/AGENT_INSTALL.md

Manual install

Install the CLI, then install the extension from the Chrome Web Store or Edge Add-ons.

macOS / Linux (recommended — installs to ~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"

Windows (PowerShell — installs to ~/.local/bin):

irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex

The export makes the CLI available in the current Unix shell. A running agent may need the same PATH setting in each shell call, or the installed binary's absolute path. Restart the agent if it retains an old PATH after installation.

Verify the binary in the terminal or agent environment that will use it:

2. Install the browser extension

Install BrowserSkill from your browser's store:

On other Chromium-based browsers, install the Chrome Web Store build.

BrowserSkill ships a skill that teaches your agent harness how to use bsk. For these harnesses, install it in one step:

Cursor |
Claude Code |
Codex |
OpenClaw |
CodeBuddy |
WorkBuddy |
Pi |
Hermes Agent
---|---|---|---|---|---|---|---

Use Space to select the Agent harness you want to install into, then press Enter to install the skill. Run bsk install-skill --list to see internal variants and install paths.

For non-interactive installation, specify the intended harness, for example bsk install-skill --harness cursor --json. Explicit selection also works when the harness is not detected. --yes alone installs into every detected harness and fails when none are detected.

To install your own instructions, use bsk install-skill --harness cursor --source ./SKILL.md. An explicit --source stays custom even if its contents match the bundled skill. Existing installations are skipped unless you add --force.

Daemon startup, session start, and doctor automatically update managed skills only when their contents still match the last installed version. Local edits are preserved and automatic updates pause. An older installation without a content baseline is enrolled automatically only if it exactly matches the current bundled skill; this writes the source marker without rewriting SKILL.md. Explicit custom installations stay custom even when their contents match.

For differing historical files, local edits, or an unrecognized source marker, doctor shows WARN with the reason and recovery options. These warnings do not make the health check fail (--json reports status: "warn" and ok: true). A concurrent install or sync is reported as deferred and retried on a later pass.

To keep your current instructions as an explicit customization, run bsk install-skill --harness cursor --source <existing-SKILL.md> --force, replacing <existing-SKILL.md> with the path to your existing file. To restore the bundled skill and resume automatic updates, run bsk install-skill --harness cursor --force without --source. This second command overwrites the existing instructions.

Other shell-capable agent harnesses are supported too. Copy skill/SKILL.md into your harness's skills directory as browser-skill/SKILL.md to install the skill manually. DeepSeek Harness uses a dedicated plugin instead — see DeepSeek Harness plugin.

Run bsk doctor and follow its hints. Open the extension popup and confirm it is connected. Explain any warnings and resolve failures before testing browser use. Doctor can pass with no skill installed (N/A); verify skill discovery separately.

Start a new Agent session, confirm browser-skill is available in the harness, and ask it to open https://example.com and summarize the page. For harnesses with slash-command skill invocation, for example:

/browser-skill open example.com and summarize what is on the page.

A successful first-use check reads the page and stops its BrowserSkill session. If the skill is missing, check the target harness and install path before retrying.

For the default local setup, finish active browser tasks before updating:

If Windows reports a staged update, wait for the replacement to finish before checking bsk --version.

When it installs an update, this command restarts a running daemon with default startup settings. If you replaced the binary using the installer instead, restart the existing daemon with bsk daemon restart after tasks finish.

For a custom port, host-managed sandbox daemon, or remote server, stop the daemon in its owning host or supervisor, run bsk update --yes --no-restart-daemon, and start it there with its original flags and BSK_HOME. Set BSK_AUTO_START=0 in agent commands while managing it; see the sandbox and remote setup guides.

Update the extension through its browser store; for an unpacked development build, rebuild and reload it. Store availability may lag the CLI release. Check the CLI, daemon and extension versions with bsk --version and bsk status, then run bsk doctor. New features such as full-page screenshots need matching builds. Update the DSH plugin separately and restart its profile. Managed CLI skills synchronize on daemon startup, session start, or doctor; local edits and custom skills are preserved. Start a new agent session to load updated instructions.

Upgrading to 0.3.0: --unattended, tab borrow --no-confirm, and BSK_REQUEST_HELP=off no longer bypass confirmation or disable help. Choose the corresponding extension settings described below. See what changed.

The extension popup has two independent Automation settings , both enabled by default. The user's saved browser settings are authoritative for every session:

Confirm before borrowing tabs	Allow requests for human help	Behavior
On	On	Borrowing requires approval; help requests show the existing UI.
On	Off	Borrowing requires approval; help requests return disabled.
Off	On	Borrowing skips confirmation; help requests show the existing UI.
Off	Off	Borrowing skips confirmation; help requests return disabled.

Settings save automatically for the browser profile and apply to existing and new sessions. Turning confirmation off releases pending borrow confirmations; turning help off finishes pending help requests as disabled. Turning either back on restores its behavior for subsequent operations, including sessions created with the legacy --unattended flag. Completed borrows are not undone, and finished help requests are not reopened. Allowing help makes request-help available; it does not require every browser action to ask for permission. Task authorization and host approvals still apply.

Start tasks with bsk session start; add --no-focus to avoid focusing the Agent Window. For unattended operation, turn off the corresponding settings in the extension. --unattended, tab borrow --no-confirm, and BSK_REQUEST_HELP=off remain accepted for compatibility but are deprecated and cannot override the switches. The CLI logs a notice when these inputs are used; the daemon also logs a notice for its inherited environment setting. Scripts that relied on these inputs alone to avoid waiting must now use the browser settings. session start --json and session list --json report the browser's effective interaction policy.

When help is disabled, request-help returns disabled without confirming any human action. The skill directs the agent to re-observe and make reasonable efforts to complete authorized steps using existing login state, authorized inputs, and available tools. Where task authorization and host rules allow, models with image understanding may attempt graphical verification. Phone-only QR scans, face verification, unavailable SMS codes, and image-only CAPTCHAs for text-only models may remain blocked. A disabled result neither completes the task nor grants additional permission.

If preference loading fails, the runtime retains known values or defaults to both enabled when no valid value is available. It does not write fallback defaults or block session creation. Later reads and storage events can recover the settings. The popup reports read failures and prevents saving; failed writes are not treated as successful. A disconnected browser produces an error, not a local disabled result based on command-line flags or environment variables.

tab borrow --timeout 60s controls the confirmation wait, not whether confirmation is required. Protocol 1.3 retains connection compatibility with protocols 1.0–1.2. Ordinary sessions and default tab borrowing remain available during staggered upgrades. The popup identifies older daemons, while bsk status reports protocol differences. Custom borrowing waits require both daemon and extension protocol 1.2 or later; only that operation returns an upgrade error when unsupported. Older daemons may still have shorter default borrowing waits.

The current CLI requires daemon protocol 1.3 for request-help, because older daemons can answer locally without consulting the browser. This restriction does not disconnect the browser or stop other operations. Update the CLI, running daemon, and extension for full enforcement of the settings above. New extensions always enforce their saved settings on requests they receive. An older CLI may exit locally for BSK_REQUEST_HELP=off before contacting the daemon; mixed-version installations retain such legacy behavior, which updating only the extension cannot change.

Run an Agent on a server and pair it with your local browser using the built-in authentication service, or a compatible gateway. See remote browser connections.

Using DeepSeek Harness (dsh)? BrowserSkill ships a first-class dsh plugin on npm as @wxg-prc-cpg/browser-skill-dsh-plugin. It gives the agent native browser_* tools and a live view of its browser sessions in the Web UI. The plugin runs bsk on the agent's behalf.

Install the bsk CLI and connect the browser extension first. Then add the plugin to a dsh profile and start it (replace web with your profile name):

dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
dsh --profile web

The plugin includes the browser-skill skill, so bsk install-skill is not needed for dsh. Installed plugins do not update automatically. To upgrade this plugin:

dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest

Restart the profile after upgrading. See the plugin README for usage and configuration.

BrowserSkill is a local bridge between your agent harness and your browser.

flowchart TB
  subgraph Harness["Agent Harness"]
    Agent["Cursor / Claude Code / Codex / OpenClaw"]
  end

  subgraph Local["Your Machine"]
    CLI["bsk CLI"]
    Daemon["bsk daemon"]
    Extension["BrowserSkill extension"]
  end

  subgraph Browser["Browser Profile"]
    AgentWindow["Agent Window"]
    UserWindows["Your normal browser windows"]
  end

  Agent -->|"shell: bsk ..."| CLI
  CLI -->|"local IPC"| Daemon
  Daemon -->|"WebSocket on 127.0.0.1"| Extension
  Extension -->|"automates"| AgentWindow
  Extension -.->|"borrow tab only when asked"| UserWindows

  style AgentWindow fill:#fff4e6,stroke:#f59e0b,stroke-width:2px,color:#111827
  style UserWindows fill:#f8fafc,stroke:#cbd5e1,color:#334155

Loading

The agent never talks to the browser directly. It asks the bsk CLI to perform a browser task; the local daemon routes that request to the extension; the extension runs it in an Agent Window. DeepSeek Harness takes the same path through the plugin: the agent calls injected browser_* tools, and the plugin invokes bsk on its behalf.

The scroll-to primitive reference covers its CLI, protocol and plugin entry points, visible bounds and interruption behavior.

The repository is a Cargo + pnpm workspace:

• crates/bsk-cli — bsk CLI and local daemon
• crates/bsk-protocol — shared wire types and JSON schemas
• apps/extension — browser extension
• packages/ui and packages/i18n — shared extension UI support, including English, Simplified Chinese and Korean localization
• packages/dsh-plugin-browserskill — DeepSeek Harness plugin (@wxg-prc-cpg/browser-skill-dsh-plugin)
• evals/browser — deterministic local pages and agent-neutral browser capability evaluation

MIT