ovoBrowser CLI 模式使用说明

ovoBrowser CLI 模式用于在命令行中以后台方式启动桌面客户端和本地自动化 API。它复用桌面端安全存储中最近一次登录的账号会话，不要求用户把邮箱、密码、Refresh Token 或 API Key 写进命令行。

一、适用场景

• 开机脚本或本机任务调度器启动 ovoBrowser API；

• 在不打开主窗口的情况下运行 Playwright、Puppeteer、Selenium 或自有脚本；

• 为本机工具固定 API 端口；

• 让已经登录过的账号以后台方式提供环境、代理和浏览器生命周期接口。

CLI 模式仍然是桌面客户端的一种启动方式，不是独立的云端服务，也不会绕过账号权限、团队权限、环境配额或本机安全边界。

二、首次使用前提

1. 正常打开 ovoBrowser 桌面客户端；

2. 登录需要用于自动化的账号；

3. 确认客户端能够正常进入主界面；

4. 彻底退出客户端；

5. 再从命令行使用 --cli 启动。

账号登录凭据保存在操作系统安全存储中。CLI 不支持也不建议使用以下参数：

--username
--password
--token
--api-key

如果登录已过期、账号已退出或安全存储被清除，请重新用桌面界面登录一次。

三、找到程序路径

如果安装时使用默认目录，可从桌面快捷方式的“目标”字段复制 ovoBrowser.exe 的完整路径。下面使用占位路径：

$OvoBrowserExe = "C:\Program Files\ovoBrowser\ovoBrowser.exe"

实际路径必须以当前电脑的安装位置为准。

四、启动 CLI 模式

使用上次保存的 API 端口：

& $OvoBrowserExe --cli

指定端口：

& $OvoBrowserExe --cli --api-port 50325

也可以使用等号写法：

& $OvoBrowserExe --cli --api-port=50325

端口必须是 1–65535 的整数。服务只监听 127.0.0.1，不会监听局域网地址或公网地址。

CLI 启动后：

• 主窗口默认不显示；

• 客户端仍在后台运行，并保留托盘入口；

• 隐藏的渲染进程会恢复安全存储中的账号会话；

• API 端口会被启动，并将 enabled=true 和当前端口保存到本机配置；

• 下次正常启动桌面客户端时，只要上次仍为启用状态，就会自动恢复该端口。

五、输出启动状态

输出可读文本：

& $OvoBrowserExe --cli --api-port 50325 --cli-print

输出单行 JSON：

& $OvoBrowserExe --cli --api-port 50325 --cli-json

JSON 字段示例：

{
  "success": true,
  "mode": "cli",
  "running": true,
  "host": "127.0.0.1",
  "port": 50325,
  "url": "http://127.0.0.1:50325",
  "pid": 12345,
  "account": "stored-session"
}

部分 Windows 安装环境不会把 GUI 程序的标准输出保留在当前终端中。无论终端是否显示文本，都应通过健康检查确认服务状态。

六、确认端口和账号会话可用

先检查端口：

$BaseUrl = "http://127.0.0.1:50325"
Invoke-RestMethod -Method Post -Uri "$BaseUrl/health" -ContentType "application/json" -Body "{}"

成功响应：

{
  "success": true,
  "data": {
    "running": true,
    "version": "0.4.3"
  }
}

然后检查账号会话和工作区是否恢复完成：

Invoke-RestMethod -Method Post -Uri "$BaseUrl/browser/list" -ContentType "application/json" -Body '{"page":0,"pageSize":1}'

/health 成功只表示端口已经监听；/browser/list 成功才表示隐藏客户端已经恢复账号会话并可处理账号数据。刚启动时可等待几秒后重试。

七、与登录后自动启动的关系

账号通过密码登录、注册、Google/GitHub 登录、邀请注册或保存会话恢复成功后，本地 API 都会自动启动。实际规则如下：

• 登录成功后会启动 API，并保存 enabled=true 和当前端口；

• 客户端下次启动时可根据已保存状态提前恢复端口，账号会话恢复后还会再次确认服务正在运行；

• 在“API & MCP”页面点击“停止服务”会立即关闭当前端口，但下一次成功登录或会话恢复仍会自动启动；

• 使用 --cli 也会显式启动端口并保存为启用状态；

• 客户端彻底退出后，API 进程和端口会一起关闭。

八、已经有客户端实例时

ovoBrowser 使用单实例运行。如果桌面客户端已经打开，再执行：

& $OvoBrowserExe --cli --api-port 51234

命令会交给现有实例处理，并把本地 API 启动或切换到指定端口，不会再启动第二套账号进程。切换端口后，调用方必须更新 baseUrl。

九、停止 CLI 服务

CLI 模式与桌面客户端使用同一个进程。可使用以下方式停止：

• 从系统托盘退出 ovoBrowser；

• 再次打开主窗口，在“API & MCP”页面点击“停止服务”；

• 正常退出 ovoBrowser 进程。

不要使用强制结束进程作为日常停止方式；正常退出会关闭浏览器内核和本地 API，并完成必要清理。

十、Postman 配置

1. 导入 ovoBrowser-Local-API.postman_collection.json；

2. 打开集合 Variables；

3. 把 baseUrl 改为 CLI 使用的地址，例如 http://127.0.0.1:50325；

4. 先运行“健康检查”；

5. 再运行“环境列表”，确认账号会话已经恢复；

6. 按需调用环境和代理接口。

Postman 不需要 Bearer Token、API Key 或 x-api-key。本地 API 只允许当前电脑访问。

十一、常见问题

Connection refused

CLI 进程没有运行、端口写错、端口被占用，或程序启动失败。检查命令中的 --api-port，并确认健康检查地址一致。

健康检查成功，但环境列表提示客户端未就绪

隐藏客户端还在恢复登录会话，先等待几秒重试。如果持续失败，正常打开桌面客户端，确认账号没有退出且能进入主界面。

端口已被占用

换一个未占用端口，例如：

& $OvoBrowserExe --cli --api-port 51234

登录已过期

CLI 不接收账号密码。请正常打开客户端重新登录，退出后再运行 CLI。

执行命令后主窗口没有出现

这是 CLI 模式的预期行为。可从托盘打开主窗口，或直接调用健康检查。

十二、安全建议

• 只监听和调用 127.0.0.1；

• 不要用端口映射、反向代理或隧道把本地 API 暴露到局域网或公网；

• 不要把代理密码、Cookie、账号密码或完整 API 响应写入公共日志；

• 不要在命令行参数、批处理文件或任务计划程序中保存登录密码；

• 自动化结束后关闭不再使用的环境；

• 团队账号只授予脚本真正需要的权限。

十三、参数速查

相关文档：

• API文档.md

• ovobrowser-api调用代码示例/postman/ovoBrowser-Local-API.postman_collection.json

• ovobrowser-api调用代码示例/README.md