ovoBrowser 本地 API 使用教程

ovoBrowser 本地 API 用于在本机管理浏览器环境、分组、标签、代理、回收站和浏览器进程。接口只监听 127.0.0.1，不需要 Token、Bearer Token 或 x-api-key。

1. 启动方式

桌面端自动启动

账号登录成功后，本地 API 会自动启动，并保存当前端口。下次保存会话恢复成功后也会自动启动。默认地址：

http://127.0.0.1:50325

实际端口以客户端「API & MCP」页面为准。Google、GitHub、账号密码登录和邀请注册最终都会建立同一种登录会话，所以成功进入账号后都会启动本地 API。

如果在客户端中手动停止服务，当前端口会立即关闭；下次登录或会话恢复成功时仍会自动启动。

CLI 模式

先在桌面端成功登录一次并保持登录状态，然后执行：

& "C:\Program Files\ovoBrowser\ovoBrowser.exe" --cli --api-port 50325

程序路径以实际安装位置为准。--api-port 可省略，省略时使用已保存端口。CLI 复用操作系统安全存储中的账号会话，不接收命令行账号密码或 Token。

“保持登录状态”表示没有在桌面端点击退出登录，而且保存会话仍然有效。若已退出登录、会话过期或应用数据被清除，需要重新打开桌面端登录；Google/GitHub 登录也在桌面端完成。

2. 调用规则

• 所有接口都使用 POST，参数放在 JSON Body 中。

• 请求头使用 Content-Type: application/json。

• 环境定位推荐使用 id；多数接口也支持 seq 环境序号。

• 分页参数 page 从 0 开始，pageSize 范围为 1-100。

• 账号、Cookie、2FA 密钥和代理密码属于敏感信息，不要写入公共日志。

成功响应：

{"success":true,"data":{}}

失败响应：

{"success":false,"msg":"失败原因"}

3. 接口总览

4. 健康检查

curl --location 'http://127.0.0.1:50325/health' \
  --header 'Content-Type: application/json' \
  --data '{}'

返回 data.running=true 表示端口已经启动。再调用环境列表可确认账号会话和工作区已经恢复。

5. 分组 API

分组用于单选归类：一个环境最多属于一个分组，通过 groupId 绑定。

分组列表

curl --location 'http://127.0.0.1:50325/group/list' \
  --header 'Content-Type: application/json' \
  --data '{}'

data.list 是分组数组，_count.profiles 是分组中的环境数量。

新增分组

curl --location 'http://127.0.0.1:50325/group/create' \
  --header 'Content-Type: application/json' \
  --data '{"name":"电商账号","color":"#3478F6"}'

编辑分组

id 和 groupId 都可以定位分组。除定位字段外，只传需要变化的字段。

curl --location 'http://127.0.0.1:50325/group/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"分组ID","name":"重要电商账号","color":"#16A34A"}'

删除分组

curl --location 'http://127.0.0.1:50325/group/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"分组ID"}'

删除分组不会删除环境，原分组下的环境会变成未分组。系统默认分组不能删除。

6. 标签 API

标签用于多选标记：一个环境最多绑定 20 个标签，通过 tagIds 数组绑定。

标签列表

curl --location 'http://127.0.0.1:50325/tag/list' \
  --header 'Content-Type: application/json' \
  --data '{}'

新增标签

curl --location 'http://127.0.0.1:50325/tag/create' \
  --header 'Content-Type: application/json' \
  --data '{"name":"高优先级","color":"#F97316"}'

编辑标签

curl --location 'http://127.0.0.1:50325/tag/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"标签ID","name":"VIP","color":"#A855F7"}'

删除标签

curl --location 'http://127.0.0.1:50325/tag/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"标签ID"}'

删除标签会解除它与所有环境的关联，但不会删除环境。

7. 代理 API

环境可以先创建可复用代理再传 proxyId，也可以在创建或更新环境时直接传 proxy。两种方式不能同时使用。

代理列表

curl --location 'http://127.0.0.1:50325/proxy/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"search":""}'

响应返回当前代理密码 password 和 hasPassword，不会返回服务端密文。

新增代理

curl --location 'http://127.0.0.1:50325/proxy/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "name":"Tokyo Proxy",
    "protocol":"SOCKS5",
    "host":"proxy.example.com",
    "port":1080,
    "username":"proxy-user",
    "password":"proxy-password"
  }'

编辑代理

id 和 proxyId 都可以定位代理。省略 password 保留原密码，传 null 清除密码。

curl --location 'http://127.0.0.1:50325/proxy/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"代理ID","host":"new-proxy.example.com","port":1080,"password":"new-password"}'

修改协议、主机、端口、用户名或密码后，检测状态会重置为 UNCHECKED。

8. 创建环境

完整字段说明

accounts 每一项：

内联 proxy：

完整创建示例

curl --location 'http://127.0.0.1:50325/browser/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "name":"完整环境示例",
    "platform":"windows",
    "remark":"通过本地 API 创建",
    "groupId":"分组ID",
    "tagIds":["标签ID1","标签ID2"],
    "accounts":[
      {
        "platform":"google",
        "username":"[email protected]",
        "password":"account-password",
        "totpSecret":null,
        "openOnStart":true,
        "remark":"主账号"
      }
    ],
    "cookies":[
      {
        "name":"session_id",
        "value":"cookie-value",
        "domain":".example.com",
        "path":"/",
        "secure":true,
        "httpOnly":true,
        "sameSite":"Lax"
      }
    ],
    "startupUrls":[
      "https://example.com/login",
      "https://example.com/dashboard"
    ],
    "fingerprint":{
      "timezone":"Asia/Shanghai",
      "acceptLanguage":"zh-CN,zh,en"
    },
    "proxy":{
      "type":"HTTP",
      "host":"proxy.example.com",
      "port":8080,
      "username":"proxy-user",
      "password":"proxy-password"
    }
  }'

使用已有代理时，删除 proxy 整段，改传 "proxyId":"已有代理ID"。不使用代理时，proxy 和 proxyId 都不要传。

Cookie 格式

推荐使用 cookies 直接传 JSON 数组。Cookie 常用字段：name、value、domain、path、secure、httpOnly、expirationDate、sameSite。

如果使用 cookieData，它必须是字符串，可放浏览器扩展导出的 JSON 文本、Netscape cookies.txt，或请求头文本 a=1; b=2。

没有 domain 的 Cookie 启动时只能根据首个启动网址推断域名，建议显式填写 domain。

9. 更新环境

更新接口只修改发送的字段；省略字段保持不变。定位支持 id、profileId、seq、serialNumber、serial_number。

覆盖规则：

• accounts 整组覆盖，[] 清空全部账号；

• tagIds 整组覆盖，[] 清空全部标签；

• cookies 或 cookieData 替换 Cookie，null 清空；

• startupUrls 替换全部启动网址，[] 清空；

• groupId:null 解除分组；

• proxy:null 或 proxyId:null 解除代理。

curl --location 'http://127.0.0.1:50325/browser/update' \
  --header 'Content-Type: application/json' \
  --data '{
    "id":"环境ID",
    "name":"更新后的环境",
    "remark":"完整更新示例",
    "groupId":"分组ID",
    "tagIds":["标签ID"],
    "accounts":[
      {
        "platform":"google",
        "username":"[email protected]",
        "password":"new-password",
        "openOnStart":false
      }
    ],
    "cookies":[
      {
        "name":"session_id",
        "value":"new-cookie-value",
        "domain":".example.com",
        "path":"/"
      }
    ],
    "startupUrls":["https://example.com/dashboard"],
    "proxyId":"已有代理ID"
  }'

修改运行中环境的代理、Cookie、启动网址或指纹后，先关闭环境，再重新打开。

10. 查询环境

环境列表

curl --location 'http://127.0.0.1:50325/browser/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"name":"","groupId":"分组ID","tagId":"标签ID"}'

不需要的筛选字段直接删除。data.list 是环境数组，data.totalNum 是总数；环境对象包含 group 和 tags。

环境详情

curl --location 'http://127.0.0.1:50325/browser/detail' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

详情返回 group、tags、fingerprint、proxy、accountCount、hasCookieData。环境所有者还会收到 cookieData。

11. 删除、回收站和彻底删除

删除环境到回收站

curl --location 'http://127.0.0.1:50325/browser/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

如果环境正在运行，会先关闭浏览器，再移入回收站。此操作可恢复。

回收站列表

curl --location 'http://127.0.0.1:50325/browser/recycle/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"search":"","sort":"desc"}'

列表中的环境 id 可用于恢复或彻底删除。

恢复环境

curl --location 'http://127.0.0.1:50325/browser/restore' \
  --header 'Content-Type: application/json' \
  --data '{"id":"回收站环境ID"}'

恢复必须使用环境 ID，不能只传环境序号。

彻底删除环境

单个：

curl --location 'http://127.0.0.1:50325/browser/delete/permanent' \
  --header 'Content-Type: application/json' \
  --data '{"id":"回收站环境ID"}'

批量：

curl --location 'http://127.0.0.1:50325/browser/delete/permanent' \
  --header 'Content-Type: application/json' \
  --data '{"ids":["环境ID1","环境ID2"]}'

ids 最多 500 个。只会删除已经在回收站中的环境，data.purged 是实际删除数量。

彻底删除不可恢复，环境配置、账号和 Cookie 都会永久删除。

12. 打开、查询和关闭环境

打开环境

curl --location 'http://127.0.0.1:50325/browser/open' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID","headless":false}'

headless 必须是 JSON 布尔值。响应返回 pid、ws、http、headless；ws 可交给 Playwright 或 Puppeteer。

运行状态

curl --location 'http://127.0.0.1:50325/browser/active' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

无参数调用 /browser/active 时返回全部运行环境。运行列表：

curl --location 'http://127.0.0.1:50325/browser/running' \
  --header 'Content-Type: application/json' \
  --data '{}'

PID 和 CDP 端口

curl --location 'http://127.0.0.1:50325/browser/pids' \
  --header 'Content-Type: application/json' \
  --data '{"ids":["环境ID1","环境ID2"]}'

curl --location 'http://127.0.0.1:50325/browser/pids/all' \
  --header 'Content-Type: application/json' \
  --data '{}'

curl --location 'http://127.0.0.1:50325/browser/ports' \
  --header 'Content-Type: application/json' \
  --data '{}'

关闭环境

curl --location 'http://127.0.0.1:50325/browser/close' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

关闭全部：

curl --location 'http://127.0.0.1:50325/browser/close/all' \
  --header 'Content-Type: application/json' \
  --data '{}'

关闭全部会影响当前所有工作窗口，执行前请保存页面内容。

13. Postman 使用

导入帮助中心提供的 https://www.postman.com/ovo-desktop-api/workspace/ovodesktop-api-example/collection/57777046-8485fa5f-3e60-4da9-8b59-538ae4703339?action=share&source=copy-link&creator=57777046：

1. 在集合 Variables 中确认 baseUrl；

2. 运行「健康检查」；

3. 运行「环境列表」确认会话已恢复；

4. 每个请求都带用途、字段说明、完整 JSON Body 和 cURL 示例；

5. 如需完整演示，按文件夹顺序运行即可，无需理解环境序号或手工维护复杂变量；

6. 执行「彻底删除环境」前，确认目标是允许永久删除的测试环境。

14. 常见错误