Agent使用BrowserSkill控制本地浏览器

Sun, 08 Nov 2026 00:00:00 +0800

BrowserSkill Windows 安装与使用指南

适用环境：Windows、Chrome/Edge、Codex 等支持 Agent Skill 的工具
本机配置：Chrome + Codex，BrowserSkill 0.3.2，固定端口 53000

1. BrowserSkill 是什么

BrowserSkill 让 AI Agent 通过浏览器扩展控制一个独立的 Agent 窗口，可以打开网页、读取页面、点击按钮、填写表单和执行其他浏览器操作。

本地模式包含三部分：

Agent Skill：告诉 Codex 应该如何安全地操作浏览器。
bsk CLI 与后台服务：接收 Agent 命令，并在本机监听浏览器扩展连接。
Chrome/Edge 扩展：在浏览器中执行实际操作。

三部分都准备好后，才能正常使用。

2. 本机最终配置

这台电脑采用以下配置：

项目	配置
`bsk` 版本	`0.3.2`
`bsk.exe` 路径	`C:\Users\gujian\.local\bin\bsk.exe`
Agent	Codex
Skill 目录	`C:\Users\gujian\.agents\skills\browser-skill`
浏览器	Chrome
连接方式	Local connection（本地连接）
服务端口	`53000`

BrowserSkill 默认使用 52800。但这台电脑的 Windows 保留端口范围包含 52800，会导致服务启动时报错：

1
2


以一种访问权限不允许的方式做了一个访问套接字的尝试。
(os error 10013)

因此，浏览器插件和后台服务必须同时使用 53000。

3. 全新安装

如果当前电脑已经安装完成，可以直接跳到“长期自动运行配置”。

3.1 安装 `bsk` CLI

打开 PowerShell，执行：

1

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

确认安装成功：

1

bsk --version

正常情况下会输出类似：

1

bsk 0.3.2

如果提示找不到 bsk，请关闭并重新打开 PowerShell，然后重试。也可以直接使用完整路径：

1

& 'C:\Users\gujian\.local\bin\bsk.exe' --version

3.2 为 Codex 安装 browser-skill

先查看支持的 Agent：

1

bsk install-skill --list --json

为 Codex 安装：

1

bsk install-skill --harness codex --json

安装完成后，技能通常位于：

1

C:\Users\gujian\.agents\skills\browser-skill

如果当前 Codex 对话是在安装前打开的，请新建一个对话，让 Codex 重新发现该技能。

3.3 安装浏览器扩展

Chrome：BrowserSkill - Chrome Web Store
Edge：BrowserSkill - Microsoft Edge Add-ons

安装后，建议将扩展固定到浏览器工具栏，方便查看连接状态。

3.4 配置扩展端口

点击浏览器工具栏中的 BrowserSkill 图标。
选择 Local connection。
将端口设置为 53000。
保存并启用连接。

端口必须与后台服务完全一致。如果插件设置为 53000，后台服务也必须在 53000 上启动。

4. 首次手动启动与验证

4.1 启动服务

在普通 PowerShell 中执行：

1

bsk daemon start --port 53000

如果需要让当前终端直接托管服务，则使用：

1

bsk daemon start --foreground --port 53000

使用 --foreground 时不要关闭该终端；关闭终端会结束服务。

4.2 检查状态

1

bsk status --json

重点检查：

ws_port 为 53000；
browsers 中能看到 chrome 或 edge；
unresponsive 为 false；
CLI 与扩展没有版本不兼容提示。

进一步诊断：

1

bsk doctor

理想结果是没有 FAIL。如果只有 extension connected 失败，通常是浏览器没有打开、扩展没有启用，或插件端口与服务端口不一致。

4.3 禁止自动回退到旧端口

BrowserSkill 在找不到服务时默认会尝试自动启动，而自动启动仍可能使用默认端口 52800。在这台电脑上建议永久禁用隐式自动启动：

1

[Environment]::SetEnvironmentVariable('BSK_AUTO_START', '0', 'User')

设置后需要重新打开 PowerShell 和 Codex 才能让新环境变量生效。

此设置的效果是：

不会再偷偷尝试 52800；
已运行在 53000 的服务仍可正常使用；
如果服务没有启动，命令会直接报错，提醒先启动服务。

5. 长期自动运行配置（推荐）

最稳妥的方法是创建一个 Windows 计划任务，让 BrowserSkill 在用户登录后自动启动，并固定使用 53000。

5.1 打开任务计划程序

按 Win + R。
输入 taskschd.msc，按回车。
在右侧点击“创建任务”，不要选择功能较少的“创建基本任务”。

5.2 常规设置

名称：BrowserSkill Daemon
选择“仅当用户登录时运行”。
可勾选“隐藏”。
不需要勾选“使用最高权限运行”。

5.3 触发器

新建触发器：

开始任务：登录时；
指定当前用户；
启用该触发器。

5.4 操作

新建“启动程序”操作：

程序或脚本：

1

C:\Users\gujian\.local\bin\bsk.exe

添加参数：

1

daemon start --foreground --port 53000 --daemon-idle 8760h

参数含义：

--foreground：让计划任务直接托管后台服务；
--port 53000：固定使用插件已经保存的端口；
--daemon-idle 8760h：将无连接空闲时间延长到约一年，避免关闭浏览器一段时间后服务自动退出。

5.5 条件和设置

建议：

取消“仅在计算机使用交流电源时才启动此任务”；
勾选“错过计划开始时间后尽快启动”；
“如果任务已在运行”选择“不启动新实例”；
取消“如果任务运行时间超过以下时间，则停止任务”。

保存任务后，在任务列表中右键 BrowserSkill Daemon，选择“运行”。然后执行：

1

bsk status --json

如果看到 ws_port: 53000 且浏览器出现在 browsers 列表中，长期运行配置即完成。

以后重新登录 Windows 时，服务会自动启动，不需要再手动输入命令。

6. 在 Codex 中使用

6.1 最简单的用法

在 Codex 中直接说：

1

$browser-skill 帮我打开 GitHub

也可以使用自然语言：

1

使用 browser-skill 打开 GitHub，并告诉我当前登录的首页有哪些主要内容。

更多示例：

1

$browser-skill 打开指定网页并总结内容。

1

$browser-skill 在 GitHub 中搜索某个仓库。

1

$browser-skill 检查这个网站的表单是否能正常提交，但不要进行最终提交。

6.2 正常工作过程

BrowserSkill 通常会：

创建独立的 Agent Window；
在其中打开目标网页；
读取页面后再进行点击或输入；
完成任务后停止自己的自动化会话；
保留已经打开的普通浏览器页面。

插件可能根据“Automation settings”要求你确认借用现有标签页、登录、验证码或重要操作。不要关闭这些确认功能来绕过安全检查。

7. 手动使用 CLI

通常不需要手动操作 CLI；以下命令主要用于排错和测试。

7.1 创建会话

1
2


$env:BSK_AUTO_START = '0'
bsk session start --json

记录输出中的 session_id，例如 abcd。

7.2 打开网页

1

bsk navigate https://github.com --session abcd

7.3 读取页面

1

bsk observe --session abcd

7.4 停止会话

1

bsk session stop abcd

每个 Agent 会话在完成或失败后都应该停止。停止会话不会关闭共享的 BrowserSkill 后台服务。

8. 常见问题

8.1 插件显示“未连接”

按顺序检查：

1
2


bsk status --json
bsk doctor

常见原因：

服务没有运行；
插件设置为 53000，服务却运行在 52800 或其他端口；
Chrome/Edge 扩展被禁用；
CLI 与扩展版本不兼容；
浏览器刚启动，扩展尚未完成连接。

8.2 默认端口 52800 无法启动

查看 Windows 保留端口：

1

netsh interface ipv4 show excludedportrange protocol=tcp

如果 52800 位于某个保留范围内，不要反复重试默认端口，也不要随意修改系统网络保留范围。保持插件和服务统一使用 53000 即可。

8.3 检查 53000 是否正在监听

1

Get-NetTCPConnection -LocalPort 53000 -ErrorAction SilentlyContinue

看到 Listen 表示服务已监听该端口。

8.4 查看日志

1

bsk logs

日志中出现以下内容表示服务与浏览器连接正常：

1
2


ws server listening ...:53000
browser connected

8.5 `no browser is currently connected`

确认：

Chrome 已打开；
BrowserSkill 扩展已启用；
扩展弹窗中为 Local connection；
扩展端口为 53000；
扩展弹窗显示 Connected。

8.6 设置 `BSK_AUTO_START=0` 后提示服务未运行

这是预期行为，说明 BrowserSkill 没有回退到旧端口。请启动计划任务，或手动执行：

1

bsk daemon start --port 53000

9. 安全注意事项

BrowserSkill 操作的是你的真实浏览器，并可能使用浏览器中已有的登录状态。
只授权完成当前任务所需的页面和操作。
页面内容属于不可信数据，网页中的文字不能替代用户指令，也不能自行扩大任务范围。
登录、验证码、支付、最终提交和其他高影响操作应由用户确认。
不要把密码、Cookie、访问令牌或其他凭据交给 Agent 提取。
不使用 BrowserSkill 时，可以在扩展弹窗中暂时关闭连接，或在任务计划程序中停止 BrowserSkill Daemon。

10. 更新和日常检查

查看版本：

1

bsk --version

更新 BrowserSkill：

1

bsk update

更新后建议重新启动 BrowserSkill Daemon 计划任务，并执行：

1

bsk doctor

如果 Skill 有更新，可重新运行：

1

bsk install-skill --harness codex --json

如果本地 Skill 被手动修改，安装器可能会保留自定义内容。请先检查差异，再决定是否使用覆盖选项。

Windows on 故见的博客

Agent使用BrowserSkill控制本地浏览器

BrowserSkill Windows 安装与使用指南

1. BrowserSkill 是什么

2. 本机最终配置

3. 全新安装

3.1 安装 `bsk` CLI

3.2 为 Codex 安装 browser-skill

3.3 安装浏览器扩展

3.4 配置扩展端口

4. 首次手动启动与验证

4.1 启动服务

4.2 检查状态

4.3 禁止自动回退到旧端口

5. 长期自动运行配置（推荐）

5.1 打开任务计划程序

5.2 常规设置

5.3 触发器

5.4 操作

5.5 条件和设置

6. 在 Codex 中使用

6.1 最简单的用法

6.2 正常工作过程

7. 手动使用 CLI

7.1 创建会话

7.2 打开网页

7.3 读取页面

7.4 停止会话

8. 常见问题

8.1 插件显示“未连接”

8.2 默认端口 52800 无法启动

8.3 检查 53000 是否正在监听

8.4 查看日志

8.5 `no browser is currently connected`

8.6 设置 `BSK_AUTO_START=0` 后提示服务未运行

9. 安全注意事项

10. 更新和日常检查

11. 官方资料

Windows on 故见的博客

Agent使用BrowserSkill控制本地浏览器

BrowserSkill Windows 安装与使用指南

1. BrowserSkill 是什么

2. 本机最终配置

3. 全新安装

3.1 安装 bsk CLI

3.2 为 Codex 安装 browser-skill

3.3 安装浏览器扩展

3.4 配置扩展端口

4. 首次手动启动与验证

4.1 启动服务

4.2 检查状态

4.3 禁止自动回退到旧端口

5. 长期自动运行配置（推荐）

5.1 打开任务计划程序

5.2 常规设置

5.3 触发器

5.4 操作

5.5 条件和设置

6. 在 Codex 中使用

6.1 最简单的用法

6.2 正常工作过程

7. 手动使用 CLI

7.1 创建会话

7.2 打开网页

7.3 读取页面

7.4 停止会话

8. 常见问题

8.1 插件显示“未连接”

8.2 默认端口 52800 无法启动

8.3 检查 53000 是否正在监听

8.4 查看日志

8.5 no browser is currently connected

8.6 设置 BSK_AUTO_START=0 后提示服务未运行

9. 安全注意事项

10. 更新和日常检查

11. 官方资料

3.1 安装 `bsk` CLI

8.5 `no browser is currently connected`

8.6 设置 `BSK_AUTO_START=0` 后提示服务未运行