jackwener/opencli 保姆级部署教程：把任意网站变成 CLI 供 AI 智能体操作

一句话定位：GitHub 开源项目 jackwener/opencli 是一个面向 AI 智能体的通用浏览器自动化 CLI——把任意网站变成确定性命令行接口，让 AI 智能体通过你已登录的 Chrome 浏览器直接导航、点击、填表单、提取数据、截图，是 agent-browser 的开源替代品。

slogan：Convert any website into a CLI & run Browser Use on your logged-in Chrome.

仓库地址：https://github.com/jackwener/opencli · 许可证：Apache-2.0 · ⭐ 30,798 · npm 包：@jackwener/opencli

▲ 图 1：OpenCLI 官方 README 顶部展示的全部徽章——中文/英文文档入口、npm 版本、Chrome Web Store 扩展安装、Node.js 版本要求、Apache-2.0 许可证（来源：官方 README shields.io 徽章）

一、项目简介

OpenCLI 是一个通用型浏览器自动化命令行工具，同时是 agent-browser 的开源替代方案。它要解决的核心问题是：网站给人类看的是图形界面，给 AI 智能体用的却没有确定性接口——每个站点都要单独写适配器、单独维护登录态。OpenCLI 把这层抽象做成一个统一的 CLI 表面：你已经在 Chrome 里登录了小红书、B 站、知乎、Twitter、LinkedIn……AI 智能体就能直接复用这套登录态，通过命令行对这些站点做导航、读取、点击、填表单、抓数据，而不需要你重新登录、也不需要把 Cookie 交给任何第三方。

OpenCLI 提供三种自动化层次，对应同一套命令面：

• 内置适配器：对 B 站、知乎、小红书、Reddit、HackerNews、Twitter/X 等站点提供开箱即用的确定性命令（如 opencli bilibili hot），无需自己写适配器。
• AI 智能体直操作任意网站：在 Claude Code、Cursor 等 AI 智能体里安装 opencli-browser 技能，智能体就能通过 opencli browser 原语操作你登录的任意页面——导航、读 DOM 快照、点击、填表单、拦截网络响应、等待元素出现。
• 写新适配器：用 opencli browser 配合 opencli-adapter-author 技能，从站点侦察、字段解码、编码到 opencli adapter test 端到端完成。

项目以 Apache-2.0 许可证开源，当前 Star 数已超过 3 万，npm 包名为 @jackwener/opencli，完整代码与文档托管在 GitHub 仓库。

二、功能特点 / 核心能力

三、环境要求

• Node.js：通过 npm 安装时要求 Node.js >= 20.18.1（旧版 Node 会缺 fetch 启动崩溃）。
• 浏览器：Chrome 或 Chromium 桌面浏览器，需安装 OpenCLI 的 Browser Bridge 扩展（从 Chrome Web Store 安装，或从 GitHub Releases 手动加载解压包）。
• 操作系统：macOS / Windows / Linux 均可；macOS 与 Windows 推荐用官方 OpenCLIApp 桌面应用（带系统托盘、登录保活、Web→Markdown、诊断面板）。
• 可选依赖：下载 B 站视频需先安装 yt-dlp（brew install yt-dlp）；小宇宙音频下载需在 ~/.opencli/xiaoyuzhou.json 配置本地凭据。
• 网络：本机 Chrome 能正常访问目标站点即可；CLI 与扩展之间通过本机 localhost 通信，不需公网回连。

四、保姆级部署步骤

4.1 方式 A：桌面应用 OpenCLIApp（macOS / Windows 推荐）

官方提供带系统托盘的桌面应用，内置 OpenCLI 运行时、托管 opencli 命令、并提供设置、诊断、升级、浏览器登录保活、Web→Markdown 面板：

1. 访问官方下载页 https://opencli.info/download，下载最新 OpenCLIApp。
2. 安装后首次打开，进入应用的 System 页面，点击安装或修复 opencli 命令行。

4.2 方式 B：npm 全局安装（CLI-only / CI / 服务器）

先确认 Node 版本满足要求：

node --version
# 必须 >= 20.18.1

然后全局安装官方包：

npm install -g @jackwener/opencli

4.3 安装 Browser Bridge 浏览器扩展

OpenCLI 通过一个轻量扩展 + 本地守护进程连接 Chrome，守护进程会在需要时自动启动。

推荐：Chrome Web Store 一键安装——在 Chrome Web Store 的 OpenCLI 页面点击「添加至 Chrome」。

手动安装（无外网商店时）：

1. 从 GitHub Releases 页面下载最新的 opencli-extension-v{版本}.zip。
2. 解压后打开 Chrome 的 chrome://extensions，右上角开启「开发者模式」。
3. 点击「加载已解压的扩展程序」，选择解压后的文件夹。

4.4 体检与验证

安装完 CLI 与扩展后，在终端跑一次官方体检：

opencli doctor

再跑几条命令确认链路通：

opencli list
opencli hackernews top --limit 5
opencli bilibili hot --limit 5

4.5 给 Chrome 配置文件起别名（可选）

如果你有多个 Chrome 配置文件，每个文件会跑独立的扩展实例，可以列出并重命名：

opencli profile list
opencli profile rename <contextId> work
opencli profile use work
opencli --profile work browser main state

只有一个已连接配置文件时 OpenCLI 会自动使用它；多个且未设默认时会主动让你选择而不是乱猜。

五、配置说明

OpenCLI 的行为主要通过环境变量调整，全部为可选项，不设也能跑：

本地守护进程监听 localhost:19825，可通过 curl localhost:19825/status 查状态、curl localhost:19825/logs 看日志。

六、使用方法

6.1 给 AI 智能体安装技能

在 Claude Code、Cursor 等 AI 智能体里，一键安装官方全部技能：

npx skills add jackwener/opencli

也可以只装需要的某一个：

npx skills add jackwener/opencli --skill opencli-adapter-author
npx skills add jackwener/opencli --skill opencli-autofix
npx skills add jackwener/opencli --skill opencli-browser
npx skills add jackwener/opencli --skill opencli-usage

四个技能的分工：

6.2 AI 智能体如何操作网站

装好 opencli-browser 后，AI 智能体就能在你登录的浏览器里完成：导航到任意 URL、通过结构化 DOM 快照读取页面内容（不是截图）、点击按钮/填表单/选下拉/按键、从页面或拦截的网络响应中提取数据、等待元素或文本出现。你只需用自然语言说想做什么，智能体内部自己拼 opencli browser 命令。

浏览器命令必须带 --session <名称> 来指定页面作用域：

opencli browser open https://example.com --session research
opencli browser network --static --session research
opencli browser chrome describe
opencli browser close --session research

6.3 常用命令示例

opencli list search --site github
opencli hackernews top --limit 5
opencli bilibili hot --limit 5
opencli xiaohongshu download "https://www.xiaohongshu.com/search_result/<id>?xsec_token=..." --output ./xhs
opencli bilibili download BV1xxx --output ./bilibili
opencli twitter download elonmusk --limit 20 --output ./twitter
opencli bilibili hot -f json
opencli bilibili hot -f csv

6.4 安装社区插件

opencli plugin install github:user/opencli-plugin-my-tool
opencli plugin list
opencli plugin update --all
opencli plugin uninstall my-tool

七、常见问题 FAQ

问一：提示 "Extension not connected" 怎么办？
答：先确认已从 Chrome Web Store 安装了 OpenCLI 扩展，并且在 chrome://extensions 里它是启用状态。再跑一次 opencli doctor 体检。

问二：提示 "attach failed: Cannot access a chrome-extension:// URL" 怎么办？
答：通常是 Chrome 里另一个扩展在拦截扩展页面。临时禁用其他扩展再试，或换一个干净的 Chrome 配置文件专门跑 OpenCLI。

问三：命令返回空数据或 "Unauthorized"？
答：说明你在 Chrome 里登录目标站点的会话过期了。切到 Chrome 窗口手动登录一次目标站点，再回来重跑命令——OpenCLI 复用的就是你 Chrome 里的登录态，不会替你保管账号密码。

问四：启动就崩、报缺 fetch 或 Node API 错误？
答：OpenCLI 要求 Node.js >= 20.18.1。先 node --version，过低就升级 Node（用 nvm / fnm 或官方安装包），再重跑 npm install -g @jackwener/opencli。

问五：守护进程异常怎么排查？
答：查状态 curl localhost:19825/status、看日志 curl localhost:19825/logs。守护进程会在需要时自动启动，重启 Chrome 后它会自动重连。

▲ 图 2：OpenCLI 官方 README 末尾的 Star History 星标增长曲线（来源：star-history.dera.page 官方徽章，仓库 jackwener/opencli）

相关链接

• 项目仓库：jackwener/opencli
• 发布下载：GitHub Releases 页面
• npm 包：@jackwener/opencli
• Chrome Web Store 扩展：OpenCLI Browser Bridge
• 桌面应用下载：https://opencli.info/download
• 中文文档：README.zh-CN.md
• 适配器作者技能：skills/opencli-adapter-author/SKILL.md
• 浏览器操作技能：skills/opencli-browser/SKILL.md
• 扩展指南：Extending OpenCLI
• 插件指南：Plugins Guide