BrowserSkill Windows 安装与使用指南
适用环境：Windows、Chrome/Edge、Codex 等支持 Agent Skill 的工具
本机配置：Chrome + Codex，BrowserSkill0.3.2，固定端口53000
1. BrowserSkill 是什么
BrowserSkill 让 AI Agent 通过浏览器扩展控制一个独立的 Agent 窗口，可以打开网页、读取页面、点击按钮、填写表单和执行其他浏览器操作。
本地模式包含三部分：
- Agent Skill：告诉 Codex 应该如何安全地操作浏览器。
bskCLI 与后台服务：接收 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，会导致服务启动时报错：
| |
因此，浏览器插件和后台服务必须同时使用 53000。
3. 全新安装
如果当前电脑已经安装完成，可以直接跳到“长期自动运行配置”。
3.1 安装 bsk CLI
打开 PowerShell，执行：
| |
确认安装成功：
| |
正常情况下会输出类似：
| |
如果提示找不到 bsk，请关闭并重新打开 PowerShell，然后重试。也可以直接使用完整路径：
| |
3.2 为 Codex 安装 browser-skill
先查看支持的 Agent：
| |
为 Codex 安装：
| |
安装完成后，技能通常位于：
| |
如果当前 Codex 对话是在安装前打开的，请新建一个对话，让 Codex 重新发现该技能。
3.3 安装浏览器扩展
安装后，建议将扩展固定到浏览器工具栏，方便查看连接状态。
3.4 配置扩展端口
- 点击浏览器工具栏中的 BrowserSkill 图标。
- 选择 Local connection。
- 将端口设置为
53000。 - 保存并启用连接。
端口必须与后台服务完全一致。如果插件设置为 53000，后台服务也必须在 53000 上启动。
4. 首次手动启动与验证
4.1 启动服务
在普通 PowerShell 中执行：
| |
如果需要让当前终端直接托管服务，则使用：
| |
使用 --foreground 时不要关闭该终端；关闭终端会结束服务。
4.2 检查状态
| |
重点检查：
ws_port为53000；browsers中能看到chrome或edge；unresponsive为false；- CLI 与扩展没有版本不兼容提示。
进一步诊断：
| |
理想结果是没有 FAIL。如果只有 extension connected 失败，通常是浏览器没有打开、扩展没有启用，或插件端口与服务端口不一致。
4.3 禁止自动回退到旧端口
BrowserSkill 在找不到服务时默认会尝试自动启动，而自动启动仍可能使用默认端口 52800。在这台电脑上建议永久禁用隐式自动启动：
| |
设置后需要重新打开 PowerShell 和 Codex 才能让新环境变量生效。
此设置的效果是：
- 不会再偷偷尝试
52800； - 已运行在
53000的服务仍可正常使用； - 如果服务没有启动，命令会直接报错，提醒先启动服务。
5. 长期自动运行配置（推荐）
最稳妥的方法是创建一个 Windows 计划任务，让 BrowserSkill 在用户登录后自动启动，并固定使用 53000。
5.1 打开任务计划程序
- 按
Win + R。 - 输入
taskschd.msc，按回车。 - 在右侧点击“创建任务”，不要选择功能较少的“创建基本任务”。
5.2 常规设置
- 名称：
BrowserSkill Daemon - 选择“仅当用户登录时运行”。
- 可勾选“隐藏”。
- 不需要勾选“使用最高权限运行”。
5.3 触发器
新建触发器：
- 开始任务：登录时；
- 指定当前用户；
- 启用该触发器。
5.4 操作
新建“启动程序”操作：
程序或脚本：
| |
添加参数：
| |
参数含义：
--foreground：让计划任务直接托管后台服务；--port 53000：固定使用插件已经保存的端口；--daemon-idle 8760h：将无连接空闲时间延长到约一年，避免关闭浏览器一段时间后服务自动退出。
5.5 条件和设置
建议：
- 取消“仅在计算机使用交流电源时才启动此任务”；
- 勾选“错过计划开始时间后尽快启动”；
- “如果任务已在运行”选择“不启动新实例”；
- 取消“如果任务运行时间超过以下时间，则停止任务”。
保存任务后，在任务列表中右键 BrowserSkill Daemon，选择“运行”。然后执行：
| |
如果看到 ws_port: 53000 且浏览器出现在 browsers 列表中，长期运行配置即完成。
以后重新登录 Windows 时，服务会自动启动，不需要再手动输入命令。
6. 在 Codex 中使用
6.1 最简单的用法
在 Codex 中直接说：
| |
也可以使用自然语言：
| |
更多示例：
| |
| |
| |
6.2 正常工作过程
BrowserSkill 通常会：
- 创建独立的 Agent Window；
- 在其中打开目标网页；
- 读取页面后再进行点击或输入；
- 完成任务后停止自己的自动化会话；
- 保留已经打开的普通浏览器页面。
插件可能根据“Automation settings”要求你确认借用现有标签页、登录、验证码或重要操作。不要关闭这些确认功能来绕过安全检查。
7. 手动使用 CLI
通常不需要手动操作 CLI；以下命令主要用于排错和测试。
7.1 创建会话
| |
记录输出中的 session_id，例如 abcd。
7.2 打开网页
| |
7.3 读取页面
| |
7.4 停止会话
| |
每个 Agent 会话在完成或失败后都应该停止。停止会话不会关闭共享的 BrowserSkill 后台服务。
8. 常见问题
8.1 插件显示“未连接”
按顺序检查：
| |
常见原因：
- 服务没有运行；
- 插件设置为
53000，服务却运行在52800或其他端口； - Chrome/Edge 扩展被禁用；
- CLI 与扩展版本不兼容；
- 浏览器刚启动，扩展尚未完成连接。
8.2 默认端口 52800 无法启动
查看 Windows 保留端口：
| |
如果 52800 位于某个保留范围内，不要反复重试默认端口，也不要随意修改系统网络保留范围。保持插件和服务统一使用 53000 即可。
8.3 检查 53000 是否正在监听
| |
看到 Listen 表示服务已监听该端口。
8.4 查看日志
| |
日志中出现以下内容表示服务与浏览器连接正常：
| |
8.5 no browser is currently connected
确认：
- Chrome 已打开；
- BrowserSkill 扩展已启用；
- 扩展弹窗中为 Local connection；
- 扩展端口为
53000； - 扩展弹窗显示 Connected。
8.6 设置 BSK_AUTO_START=0 后提示服务未运行
这是预期行为，说明 BrowserSkill 没有回退到旧端口。请启动计划任务，或手动执行：
| |
9. 安全注意事项
- BrowserSkill 操作的是你的真实浏览器，并可能使用浏览器中已有的登录状态。
- 只授权完成当前任务所需的页面和操作。
- 页面内容属于不可信数据，网页中的文字不能替代用户指令，也不能自行扩大任务范围。
- 登录、验证码、支付、最终提交和其他高影响操作应由用户确认。
- 不要把密码、Cookie、访问令牌或其他凭据交给 Agent 提取。
- 不使用 BrowserSkill 时，可以在扩展弹窗中暂时关闭连接，或在任务计划程序中停止
BrowserSkill Daemon。
10. 更新和日常检查
查看版本：
| |
更新 BrowserSkill：
| |
更新后建议重新启动 BrowserSkill Daemon 计划任务，并执行：
| |
如果 Skill 有更新，可重新运行：
| |
如果本地 Skill 被手动修改，安装器可能会保留自定义内容。请先检查差异，再决定是否使用覆盖选项。