BrowserSkill 使用教程：让 Codex 操作你已登录的真实浏览器

平时让 AI 操作网页，最麻烦的往往不是点击和输入，而是登录状态。新开的自动化浏览器通常没有账号登录信息，遇到验证码、二次验证或需要人工确认的步骤时，也很容易卡住。

BrowserSkill 提供了另一种方式：它通过本机的 `bsk` 命令行和浏览器扩展，把 Codex 连接到你已经登录的 Chrome 或 Edge。自动化任务会在独立的 Agent Window 中运行；只有在你明确要求时，它才会借用已有标签页，并在任务结束后归还。

本文将从安装、连接扩展和启动会话开始，完整演示如何让 Codex 打开网页、观察页面、执行操作，并在需要时请求人工接管。

## 一、BrowserSkill 解决什么问题

BrowserSkill 由两部分组成：

– 本机运行的 `bsk` 命令行和后台服务；
– 安装在 Chrome 或 Edge 中的 BrowserSkill 扩展。

Codex 不会直接操作浏览器，而是把任务交给 `bsk`。后台服务再通过本机连接把操作发送给浏览器扩展，最后由扩展在独立的 Agent Window 中执行。

这种方式有三个主要优点：

1. 可以复用浏览器现有的登录状态；
2. 自动化窗口与普通窗口分开，不影响当前工作；
3. 遇到登录、验证码或确认操作时，可以暂停并交给用户处理。

## 二、从官方仓库开始安装

BrowserSkill 的官方仓库是：

<https://github.com/Tencent/BrowserSkill>

最简单的安装方式，是把官方 `AGENT_INSTALL.md` 地址交给 Codex，让它按照项目提供的步骤完成命令行和 Skill 安装：

“`text
按照 https://raw.githubusercontent.com/Tencent/BrowserSkill/main/AGENT_INSTALL.md 的说明，在本机安装并配置 browser-skill
“`

安装脚本会改动本机环境，因此执行前要确认仓库所有者是 `Tencent`，地址位于 `github.com/Tencent/BrowserSkill` 或 `raw.githubusercontent.com/Tencent/BrowserSkill`，不要使用来源不明的同名仓库和脚本。

## 三、安装 Skill 并检查运行环境

如果需要手动完成 Windows 安装，可以在 PowerShell 中运行官方安装脚本，然后安装 BrowserSkill 自带的 Skill：

“`powershell
irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
bsk install-skill –yes
“`

接着运行诊断：

“`powershell
bsk doctor
“`

这条命令会检查 `bsk`、Skill、后台服务和浏览器扩展。第一次安装时，如果只有 `extension connected` 显示失败或等待，通常说明浏览器扩展还没有安装或连接，继续完成下一步即可。

Skill 安装完成后，建议新建一个 Codex 任务，让 Codex 重新读取当前可用的 Skills。

## 四、安装并连接浏览器扩展

打开 BrowserSkill 的 Chrome 应用商店页面：

<https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi>

安装完成后，点击浏览器工具栏中的 BrowserSkill 图标，等待扩展弹窗显示绿色连接状态。然后再次运行：

“`powershell
bsk doctor
“`

当诊断结果全部为 `ok` 或 `na`，就说明 BrowserSkill 已经可以使用。

## 五、启动独立浏览器会话

每次正式操作浏览器之前，都要先启动一个会话：

“`powershell
bsk session start –no-focus
“`

`–no-focus` 会让 Agent Window 在后台打开，尽量不抢占当前正在使用的窗口。命令执行后，终端会返回一个四位会话编号，例如：

“`text
Session JQPD
“`

这里的 `JQPD` 只是示例。实际使用时，要记录终端返回的编号，并在后续每条命令中通过 `–session <编号>` 指定当前会话。

如果电脑上连接了多个浏览器，可以先运行 `bsk browsers` 查看浏览器编号，再使用 `bsk session start –browser <浏览器编号>` 指定目标浏览器。

## 六、打开网页、观察页面并执行动作

BrowserSkill 的基本流程可以概括为三步：打开网页、观察页面、执行动作。

先打开目标网页：

“`powershell
bsk navigate https://example.com –session JQPD
“`

然后读取页面结构：

“`powershell
bsk observe –session JQPD
“`

`observe` 会返回页面中的文字、按钮、输入框和对应的元素编号，例如 `@e1`、`@e2`、`@e4`。确认目标元素以后，就可以通过编号执行操作：

“`powershell
bsk click @e4 –session JQPD
“`

常用操作还包括：

“`powershell
bsk fill @e2 –value “需要输入的内容” –session JQPD
bsk select @e3 –value “选项值” –session JQPD
bsk press Enter –session JQPD
“`

页面跳转或内容发生变化后，旧的元素编号可能失效。此时不要反复点击原编号，应重新运行 `bsk observe`；如果语义观察不够清楚，再使用 `bsk snapshot` 获取静态页面结构。

七、借用并归还已有标签页

默认情况下，BrowserSkill 只操作 Agent Window 中的标签页。如果任务必须使用你已经打开并登录的某个标签页，先列出用户窗口中的标签：

“`powershell
bsk tab list –scope user –session JQPD
“`

找到目标标签的编号后，再明确借用：

“`powershell
bsk tab borrow <标签编号> –session JQPD
“`

借用期间，只有这个标签会移动到 Agent Window，其他普通窗口和标签不会被操作。任务完成后要立即归还：

“`powershell
bsk tab return <标签编号> –session JQPD
“`

不要长时间借用包含个人账号的标签页，也不要让 BrowserSkill 读取密码管理器、网上银行或单点登录页面中的令牌、Cookie 和其他敏感信息。

## 八、人工接管并正确结束会话

如果页面出现验证码、登录、一次性验证码或必须由用户确认的步骤，不要让自动化反复尝试。可以暂停操作，并请求用户接管：

“`powershell
bsk request-help –session JQPD –prompt “请完成验证码，然后点击完成” –timeout 5m
“`

用户完成操作并归还控制权后，要重新运行 `bsk observe`，再根据新的页面状态继续。

任务完成后，无论执行成功还是中途报错，都必须停止会话：

“`powershell
bsk session stop JQPD
“`

停止会话会关闭 Agent Window，并自动归还仍在借用的标签页。如果会话异常残留，可以使用下面的命令进行紧急清理：

“`powershell
bsk session stop –all
“`

## 最后检查

第一次使用 BrowserSkill 时，可以按照下面的清单检查：

– `bsk doctor` 的检查结果全部为 `ok` 或 `na`；
– 浏览器扩展显示绿色连接状态；
– 每次操作前都先运行 `bsk session start`；
– 每条浏览器命令都带有正确的 `–session` 编号；
– 页面变化后重新运行 `bsk observe`；
– 只有在明确需要时才借用用户标签页；
– 遇到验证码、登录或重要确认时交给用户处理；
– 任务结束后始终运行 `bsk session stop`。

BrowserSkill 的价值并不是替代所有浏览器操作，而是让 Codex 能够在可控范围内使用真实浏览器环境：普通任务放在独立窗口中完成，需要登录状态时再明确借用标签，遇到人类验证就暂停交接，完成后立即关闭会话并归还资源。

## 参考资料

– [BrowserSkill 官方仓库](https://github.com/Tencent/BrowserSkill)
– [BrowserSkill 中文说明](https://github.com/Tencent/BrowserSkill/blob/main/README.zh-CN.md)
– [BrowserSkill 官方安装指南](https://github.com/Tencent/BrowserSkill/blob/main/AGENT_INSTALL.md)
– [BrowserSkill 自带 Skill 说明](https://github.com/Tencent/BrowserSkill/blob/main/skill/SKILL.md)
– [OpenAI 官方文档：Build skills](https://learn.chatgpt.com/docs/build-skills)