CLI WebSocket 桥接
CLI WebSocket 桥接是一项默认关闭的动态功能。开启后,扩展与本机上的 @opentiny/webmcp-cli 通过 127.0.0.1:18999 保持连接,可以做两件事:
- 在侧边栏操作本机:为当前会话指定一个本地文件夹,让 AI 在这个目录里查看文件、运行构建或执行其他命令。
- 让外部 Agent 操作浏览器:把桥接作为 MCP Server 配置到 Claude Desktop、Cursor 等工具后,这些工具可以调用扩展里的浏览器能力。
功能卡片位于配置页「功能管理」中。卡片底部显示「所有网页」。本功能不往网页里注入内容,开关只决定侧边栏是否出现桥接入口、以及本地命令是否可用。
使用前需要本机已安装 Node.js,以便通过 npx 运行 CLI。桥接只监听本机回环地址,并生成一个随机 Token 用于配对。
WARNING
接通后,AI 可以在你的电脑上执行 shell 命令。请只在受信任的开发环境开启,并妥善保管 Token。更换 Token 后,需要重新执行 CLI 设置命令,并更新已经配置到第三方 Agent 的 MCP 配置。
开启功能
- 打开配置页:侧边栏左下角的设置齿轮,或悬浮球右键菜单中的「设置」。
- 在「功能管理」中找到 CLI WebSocket 桥接 卡片。
- 打开卡片右上角的开关。
开关写入扩展存储后实时生效。开启后,侧边栏顶部会出现 WS 状态徽章,输入区会出现本地工作空间按钮。关闭后这两处入口一起消失,无需刷新页面。

连接本地 CLI
开启功能后,将鼠标移到侧边栏顶部的 WS 徽章上,会展开「本地WebSocket桥接」面板。徽章文案表示当前连接状态:
| 徽章 | 含义 |
|---|---|
| WS 待连接 | 插件已开启,本地桥接尚未配对成功 |
| WS 探测中... | 正在尝试连接 127.0.0.1:18999 |
| WS 已连接 | 配对完成,可以执行本地命令、选择工作文件夹 |
面板里可以看到服务地址 ws://127.0.0.1:18999(点击即可复制)和协议版本。尚未连上时,面板会提示本地桥接服务未启动,并提供重新连接。
配对时无需先在终端中手动启动并保持服务常驻运行。按下面的步骤做一次即可:
在桥接面板点击复制CLI设置命令。剪贴板中的命令形如
npx @opentiny/webmcp-cli@latest --mode wxt token set <Token>,其中的 Token 就是扩展当前使用的连接凭据。
在本机终端执行这条命令。CLI 内部会自动终止旧守护进程释放端口,把 Token 写入本地配置并拉起
127.0.0.1:18999上的常驻桥接服务。徽章变为 WS 已连接,面板状态变为「已连接」。之后再运行 CLI,不必重复输入 Token。

面板里还可以处理凭据本身:展开「连接凭据(Token)」后,能查看当前 Token、保存自定义凭据,或重新生成随机凭据。重新生成会立刻换一套 Token 并复制到剪贴板,原先的 CLI 配置和 MCP 配置会失效,需要用新 Token 再配一次。
长时间停在「WS 待连接」时,先确认终端里的设置命令已经成功执行,再在面板中点击重新连接。扩展里的 Token 与 CLI 里保存的 Token 不一致时,重新复制设置命令并执行即可。
TIP
面板底部的「本地手动调试命令(高级)」分两行给出,Windows 与 macOS / Linux 相同。第一行是 npx @opentiny/webmcp-cli@latest --mode wxt stop,第二行是 npx @opentiny/webmcp-cli@latest --mode wxt server --token <Token>。依次执行可先停止旧服务释放端口,再单独挂起前台 WebSocket 桥接服务以便调试和查看实时日志(支持 Ctrl+C 手动停止)。两行之间不用 &&,也不经过 cmd /c,因此 Windows PowerShell 5.1 与 Git Bash 都可以直接粘贴。日常配对用上面的设置命令即可。
绑定本地工作空间
桥接连上之后,对话输入区会出现工作空间按钮。还没有绑定文件夹时,按钮就叫「工作空间」;绑定之后,按钮上显示该文件夹的名称。将鼠标移到按钮上可查看完整路径,点击路径可以复制。
| 状态 | 命令在哪里执行 |
|---|---|
| 默认隔离 | ~/.robot-wxt/workspaces/<当前会话 ID>/。目录在第一次执行命令时由 CLI 创建,不同会话彼此分开 |
| 已绑定目录 | 你为这个会话选中的本地文件夹 |
选择文件夹:
- 确认徽章已经是 WS 已连接。选择文件夹会通过本地 CLI 打开系统的文件夹对话框,未连接时无法选出目录。
- 点击工作空间按钮,或在弹出的面板里点击选择本地文件夹。
- 选中后,该会话之后的本地命令都在这个目录下执行。面板标记为「已绑定目录」。
还没有进入某个会话时选出的文件夹,会作为新会话的预设:之后新建的会话若没有单独绑定,会沿用这个目录。已经在某个会话里改过的文件夹,只对这个会话生效。
面板中的恢复默认只去掉当前这一层绑定。在会话里点它时,没有新会话预设会回到该会话的隔离目录;已经设过预设则回到预设目录。要清掉预设,需要在还没有进入会话时再点一次恢复默认。更改文件夹用来换成另一个目录。

这只限制命令从哪个目录开始执行,不限制命令正文里访问的路径。执行目录不能包含 ..。会话已经绑定文件夹时,绝对路径的执行目录还必须落在这个文件夹里面;停在默认隔离目录时,不校验绝对路径。像 cat ../other/secret 这样写在命令里的路径,不会因此被拦住,要不要确认仍由防护模式和白名单决定。
在对话中执行本地命令
连接并确认工作目录之后,直接用自然语言描述任务即可,例如「在当前工作目录生成一份项目周报 PPT」或「运行 pnpm test,把失败信息贴出来」。
AI 通过工具 execute_host_bash 在宿主机上执行命令。这个工具只出现在主对话中。执行前会先按 配置 里的防护模式和白名单做判断:
- 判定为可直接执行的命令会立刻运行,结果回到对话里。
- 需要确认的命令会停下来,卡片标题为「安全拦截确认:是否允许执行该 Bash 命令?」。
- 允许本次执行:只放行这一次,相同命令下次仍要确认。
- 始终允许该 Bash 命令:把这一条命令写入免审批白名单,之后相同命令直接执行。多行脚本、命令替换(反引号或
$()),或用>覆盖文件时,没有这一项。 - 拒绝执行:终止这次命令,并把拒绝原因交回给 AI。
- 命中系统红线的命令不会执行,也不会出现确认框。
TIP
「始终允许该 Bash 命令」写入的是这一条命令,不会把整个本地命令工具设为免审。希望用通配一次放行一类命令,仍可在 CLI 桥接设置里添加,例如 npm run *。这组选项也不同于 安全护栏 里其他工具的「允许此类工具」「允许全部工具」。

单次命令默认大约 30 秒超时,输出过长时会被截断,对话里会带上相应提示。
接入第三方 Agent
桥接面板中的复制MCP配置会复制一份带当前 Token 的 MCP Server 配置。Token 写在环境变量 ROBOT_WXT_BRIDGE_TOKEN 里,不会出现在启动参数中。把这段 JSON 配置到 Claude Desktop、Cursor 等宿主后,即可从这些工具遥控当前浏览器。
配置形态如下(<Token> 换成面板里复制出来的实际值;直接用「复制MCP配置」则无需手改):
{
"mcpServers": {
"tiny-robot": {
"command": "npx",
"args": ["-y", "@opentiny/webmcp-cli@latest", "--mode", "wxt", "mcp"],
"env": {
"ROBOT_WXT_BRIDGE_TOKEN": "<Token>"
}
}
}
}第三方 Agent 调用浏览器能力时,扩展侧的桥接需要处于已连接状态。重新生成 Token 之后,要重新复制配置并更新宿主。

配置
在「功能管理」里点击 CLI WebSocket 桥接卡片上的设置,或在桥接面板里点击安全护栏与白名单配置,都会打开「CLI 桥接与命令安全配置」。
本页有两项:智能体安全防护模式、免审批命令白名单。点击模式卡片或增删规则后立即保存,没有保存按钮。修改会作用于之后发起的命令;已经停在「等待确认」的那一次,仍要在对话里允许或拒绝。
这里的防护只管宿主机命令,与配置页「安全护栏」里的全局模式、单工具策略相互独立。安全护栏的说明见 安全护栏。

安全防护模式
三张卡片中,标记「当前生效模式」的卡片是当前启用的防护模式。默认是智能沙箱。
| 模式 | 页面标记 | 行为 |
|---|---|---|
| 宽松模式 | Full access | 除系统红线外,命令直接执行 |
| 智能沙箱(推荐,默认) | Sandboxed | 只读命令和白名单命令直接执行;会修改文件、删除内容,或未加入白名单的命令,执行前等待确认 |
| 严格审查 | Strict | 只有命中白名单的命令直接执行,其余命令(含 ls 这类只读命令)都要确认 |
智能沙箱下会直接放行的只读命令包括 ls、pwd、cat、grep、echo,以及 git status、git diff、git log、git show 等查看类 Git 操作。find 在不带删除或外部执行参数时也按只读处理。默认白名单已经放行 npm run *、pnpm run * 和 pnpm test,这些不用确认。白名单以外的 npm / pnpm 命令(如 npm install)、会改仓库的 Git 操作、rm,以及用 > 覆盖文件的命令,默认需要确认。
以下情况任何模式、任何白名单都不会放行:
- 删除根目录或用户主目录,例如
rm -rf /、rm -rf ~ - 关机、重启
- 格式化磁盘,或向磁盘设备写入
- 读取、改写 SSH 凭证
- 对
/etc、/usr、/bin等系统目录做危险写入
另外,命令替换(反引号或 $())不能靠白名单免确认。用 > 覆盖文件时,宽松模式以外仍会要求确认,即使整条命令写进了白名单。
免审批命令白名单
白名单中的命令在智能沙箱和严格审查下都会直接执行,不再弹出确认框。每条规则单独添加,支持 * 与 ?:
*只匹配单条命令内部的内容,不匹配&&、||、;、管道|或换行这些分隔符。npm run *可以匹配npm run build,不能单靠这一条放行npm run build && rm -rf dist。?匹配一个字符,同样不匹配上面的分隔符。- 一条命令里用
&&等连起来时,每一段都需要是只读命令或各自命中白名单;也可以把整条连在一起的命令写成一条白名单规则。
页面提供一组常用模板,点击即可加入(已存在的规则不会重复添加):git status、git diff、pnpm test、npm run *、pnpm run *、cargo check、pytest。也可以在输入框写下规则,按回车或点击添加规则。每条规则右侧的删除只去掉这一条;清空白名单会删掉全部规则。
初次安装时的默认规则是:
npm run *
pnpm run *
pnpm test
git status
git diff清空白名单后会保持为空,不会自动回到上面这几条。需要恢复时,用模板或手动把规则加回去。白名单为空时,非只读命令按当前防护模式决定是否等待确认。
常见问题
- 侧边栏没有 WS 徽章,也没有工作空间按钮:在「功能管理」中确认 CLI WebSocket 桥接已经开启。
- 一直停在「WS 待连接」:在终端执行面板里复制的 CLI 设置命令,然后点击重新连接。本机需要能运行
npx。若刚更换过 Token,用新命令再执行一次。 - 对话提示「未连接到本地 CLI 桥接服务」:先让徽章变为 WS 已连接,再发送任务。
- 点了工作空间却选不出文件夹:文件夹对话框由本地 CLI 打开,请先完成上面的配对。
- 改成宽松模式后,有的命令仍然不执行:系统红线在任何模式下都会拦截。若改的是「安全护栏」页的宽松模式,本地命令不受那一页影响,需要在本功能的设置里调整。
- 确认过一次,同类命令下次仍要确认:当时选的是「允许本次执行」。选「始终允许该 Bash 命令」会把这一条写入白名单。多行脚本、命令替换或覆盖重定向不能从对话里加入白名单,需要在设置里写规则,或每次单独允许。
- 白名单写了
npm run *,连在一起的命令仍要确认:*不匹配&&、管道和换行这些分隔符。需要免确认时,为另外一段单独加规则,或把整条命令写成一条规则。 - 命令未在预期的工作目录中执行:看输入区工作空间按钮上的文件夹名。每个会话可以单独绑定;没有绑定时在
~/.robot-wxt/workspaces/<会话 ID>/中执行。 - 清掉白名单后想回到最初的几条规则:本页没有一键恢复。把默认规则重新添加进去即可。防护模式要回到默认,点选「智能沙箱」。