浏览器窗口

浏览器窗口的分页查询、创建、修改名称、代理绑定与解绑、平台账号绑定与解绑、移动到窗口分组、读取已打开窗口保险库、打开与关闭，以及读取本机 CDP 连接信息。窗口标识统一使用 windowId，取自 /browser/list 的 data.data[].id。

分组本身的增删改查见 窗口分组。

在本页搜索

显示 10 / 10 个接口

GET/browser/list

窗口列表

按当前登录团队分页查询窗口，附带窗口绑定的代理、平台账号与插件，并叠加本机运行与占用状态。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
teamId	string | number	可选	团队 ID；缺省使用当前登录团队
page	number	可选	页码，默认 1
size	number	可选	每页数量，默认 20，服务端上限 1000
keyword	string	可选	关键词，模糊匹配窗口名称
groupId	number	可选	不传查询全部；0 查询未分组；正数查询指定分组；负数返回参数错误

注意事项

• opened 是服务端记录的打开状态，可能残留本账号上次未释放的 ON；判断窗口能否打开或是否在本机运行请读 runtimeState 或 effectiveOpened。
• runtimeState 按客户端按钮同样的规则计算：其他用户占用优先，其次看本机是否有运行实例。

响应字段

字段	类型	说明
data.count	number	匹配到的总条数
data.size	number	每页数量，回显请求值
data.page	number	当前页码，回显请求值
data.total	number	总页数
data.data	object[]	当前页记录
data.data[].id	number	窗口主键 ID，各窗口接口的 windowId 取该值
data.data[].name	string	窗口名称
data.data[].userId	number	归属用户 ID
data.data[].teamId	number	归属团队 ID
data.data[].groupId	number	窗口分组 ID，0 表示未分组
data.data[].seq	number	排序值
data.data[].platformId	string	绑定平台账号 ID 数组的 JSON 文本
data.data[].pluginId	string	安装插件 ID 数组的 JSON 文本
data.data[].proxyId	number	绑定代理 ID，0 表示未绑定
data.data[].remark	string	窗口描述
data.data[].uuid	string	窗口目录唯一标识
data.data[].languageFrame	string	界面语言，"0" 表示跟随 IP
data.data[].languageView	string	网页语言，auto/"0" 表示跟随 IP
data.data[].timezone	string	时区，auto/"0" 表示跟随 IP
data.data[].location	string	经纬度，逗号分隔，"0,0" 表示跟随 IP
data.data[].locationAssable	number	定位权限：0 禁止、1 询问、2 允许
data.data[].audioSwitch	string	音频开关：ON、OFF
data.data[].pictureSwitch	string	图片开关：ON、OFF
data.data[].videoSwitch	string	视频开关：ON、OFF
data.data[].screenPixel	string	分辨率 "宽,高"，"0,0" 表示全屏
data.data[].screenLocation	string	窗口打开位置
data.data[].opened	string	是否已打开：ON、OFF
data.data[].openedUserId	number	当前持有打开状态的用户 ID
data.data[].activeAt	string	最后活跃时间，未打开过为 null
data.data[].createdAt	string	创建时间 yyyy-MM-dd HH:mm:ss
data.data[].updatedAt	string	更新时间 yyyy-MM-dd HH:mm:ss
data.data[].userEmail	string	归属用户邮箱
data.data[].proxy	object	绑定的代理详情，未绑定为 null；字段同 /proxy/list 条目
data.data[].platforms	object[]	绑定的平台账号，字段同 /account/list 条目（含明文密码与 2FA 密钥）
data.data[].plugins	object[]	已安装插件
data.data[].effectiveOpened	string	叠加本机状态后的打开状态：ON、OFF；本机运行中或被其他用户占用时为 ON
data.data[].localRunning	boolean	窗口是否正在本机运行
data.data[].runtimeState	string	运行状态：local_running 本机运行中、occupied_by_other 被其他用户占用、closed 未打开

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 1,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 8001,
        "name": "示例环境-01",
        "userId": 1001,
        "teamId": 2001,
        "groupId": 0,
        "seq": 1,
        "platformId": "[5001,5002]",
        "pluginId": "[]",
        "proxyId": 0,
        "remark": "",
        "uuid": "7c2b5e9a41d84f10b6c3e0a95d824fb7",
        "languageFrame": "0",
        "languageView": "auto",
        "timezone": "auto",
        "location": "0,0",
        "locationAssable": 1,
        "audioSwitch": "ON",
        "pictureSwitch": "ON",
        "videoSwitch": "ON",
        "screenPixel": "1920,1080",
        "screenLocation": "LEFT",
        "opened": "OFF",
        "openedUserId": 1001,
        "activeAt": null,
        "createdAt": "2026-06-01 12:30:00",
        "updatedAt": "2026-06-01 12:30:00",
        "userEmail": "[email protected]",
        "proxy": null,
        "platforms": [
          {
            "id": 5001,
            "userId": 1001,
            "teamId": 2001,
            "platformUrl": "https://x.com/",
            "username": "demo_account",
            "password": "demo-password",
            "key2fa": "JBSWY3DPEHPK3PXP",
            "remark": "",
            "state": 0,
            "createdAt": "2026-01-15 10:00:00",
            "updatedAt": "2026-06-01 12:30:00",
            "userEmail": "[email protected]",
            "icon": "https://oss.nexbrowser.net/images/platform_icon/twitter.png",
            "bindScreen": [
              {
                "id": 8001,
                "uuid": "7c2b5e9a41d84f10b6c3e0a95d824fb7",
                "name": "示例环境-01"
              }
            ]
          }
        ],
        "plugins": [],
        "effectiveOpened": "OFF",
        "localRunning": false,
        "runtimeState": "closed"
      }
    ]
  }
}

POST/browser/create

创建浏览器窗口

按客户端「创建窗口」弹窗的默认值批量建窗，每个窗口单独申请一份独立指纹。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
count	number	可选	创建数量，默认 1，单次上限 50，超限直接返回业务失败
name	string	可选	窗口名；缺省为「环境-」加 5 位数字；count>1 时自动追加 -01、-02 序号后缀
groupId	number	可选	窗口分组 ID，0 表示未分组
remark	string	可选	窗口描述
proxyId	number	可选	绑定的代理 ID，0 表示不绑定
accountIds	number[] | string	可选	绑定的平台账号 ID，数组或逗号分隔文本
pluginIds	string[] | string	可选	安装的插件 ID，数组或逗号分隔文本
startupUrl	string	可选	窗口启动页
screen	object	可选	窗口字段覆盖项，键同 /browser/list 条目
preference	object	可选	偏好设置覆盖项
fingerprint	object	可选	指纹覆盖项，可指定 osType、osVersion、coreVersion 等

注意事项

• 未传的字段一律沿用客户端默认值。
• 全部窗口都失败时接口返回业务失败，msg 逐行汇总失败原因（服务端原文优先，换行分隔）。

响应字段

字段	类型	说明
data.rows	object[]	逐个窗口的创建结果
data.rows[].seq	number	本次批量中的序号，从 1 开始
data.rows[].name	string	实际使用的窗口名
data.rows[].success	boolean	该窗口是否创建成功
data.rows[].id	string	窗口 ID，成功时返回
data.rows[].uuid	string	窗口目录唯一标识，成功时返回
data.rows[].error	string	失败原因，成功时缺省
data.rows[].code	string	失败时的稳定错误码，如 WINDOW_CREATE_FAILED；未登记错误码的失败不含该字段
data.rows[].params	object	错误码的插值参数，仅部分失败行返回
data.success	number	成功行数
data.failed	number	失败行数
data.total	number	总行数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "rows": [
      {
        "seq": 1,
        "name": "自动化环境-01",
        "success": true,
        "id": "8002",
        "uuid": "9f1c7f6f0b1c42f6a0c9d3b2e5a7c418"
      },
      {
        "seq": 2,
        "name": "自动化环境-02",
        "success": true,
        "id": "8003",
        "uuid": "b3d5a1c8e47f4a02b6d9c0f8a2e14d73"
      }
    ],
    "success": 2,
    "failed": 0,
    "total": 2
  }
}

POST/browser/proxy

绑定或解绑窗口代理

为一个或多个已关闭的窗口绑定代理；proxyId 传 0 表示解绑。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowIds	string[]	必填	一个或多个窗口 ID
proxyId	string | number	必填	代理 ID；传 0 移除绑定。缺省返回参数错误

注意事项

• 窗口处于打开状态时该行失败，error 为「窗口正在运行，请关闭窗口后再修改代理」；全部失败时接口返回业务失败并汇总错误信息。
• 兼容旧调用：windowIds 也可写成 windowId，单值或数组同样接受。

响应字段

字段	类型	说明
data.rows	object[]	逐个窗口的绑定结果
data.rows[].windowId	string	窗口 ID
data.rows[].proxyId	string | number	本次写入的代理 ID
data.rows[].success	boolean	该窗口是否绑定成功
data.rows[].error	string	失败原因，成功时缺省
data.rows[].code	string	失败时的稳定错误码，如 WINDOW_RUNNING_PROXY_LOCKED、WINDOW_PROXY_BIND_FAILED
data.rows[].params	object	错误码的插值参数，仅部分失败行返回
data.success	number	成功行数
data.failed	number	失败行数
data.total	number	总行数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "rows": [
      {
        "windowId": "8001",
        "proxyId": 6001,
        "success": true
      }
    ],
    "success": 1,
    "failed": 0,
    "total": 1
  }
}

POST/browser/account

绑定或解绑窗口平台账号

给已关闭的窗口选择平台账号。`accountIds` 传入要绑定的账号 ID 列表；传入 `[]` 表示不选择账号。本次写入会整组替换原绑定。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowIds	string[]	必填	一个或多个窗口 ID；也可以用 windowId 传单个 ID 或 ID 数组
accountIds	number[]	必填	平台账号 ID 列表。传入一个或多个账号 ID 表示绑定；传入 [] 表示不选择账号。缺省返回参数错误

注意事项

• 实际写入窗口的 platformId 是 JSON 数组文本：绑定为 accountIds 的 JSON 文本，不选择账号为 "[]"。
• 窗口正在运行时返回业务失败「窗口正在运行，请关闭窗口后再修改平台账号」；写入失败时 msg 优先使用服务端原文。成功时 data 为 null。

响应字段

字段	类型	说明
data	null	无返回数据，成功以 code=0 表示

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": null
}

POST/browser/group

移动窗口到分组

把一个或多个窗口移动到指定窗口分组；groupId 传 0 表示移出分组。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowIds	string[]	必填	一个或多个窗口 ID；也可以用 windowId 传单个 ID 或 ID 数组
groupId	string | number	必填	目标分组 ID；传 0 移出分组。缺省返回参数错误

注意事项

• 分组只是窗口元数据，窗口处于打开状态时同样可以移动，无需先关闭。
• 全部失败时接口返回业务失败并汇总错误信息。

响应字段

字段	类型	说明
data.rows	object[]	逐个窗口的移动结果
data.rows[].windowId	string	窗口 ID
data.rows[].groupId	number	本次写入的分组 ID
data.rows[].success	boolean	该窗口是否移动成功
data.rows[].error	string	失败原因，成功时缺省
data.rows[].code	string	失败时的稳定错误码，如 WINDOW_GROUP_MOVE_FAILED
data.rows[].params	object	错误码的插值参数，仅部分失败行返回
data.success	number	成功行数
data.failed	number	失败行数
data.total	number	总行数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "rows": [
      {
        "windowId": "8001",
        "groupId": 5002,
        "success": true
      }
    ],
    "success": 1,
    "failed": 0,
    "total": 1
  }
}

POST/browser/name

修改窗口名称

修改单个窗口的名称，只接受窗口 ID 和新名称，不改动窗口的其他配置。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowId	string | number	必填	要改名的窗口 ID
name	string	必填	新的窗口名称，首尾空格会被去掉；为空返回参数错误

注意事项

• 只接受 windowId 和 name 两个字段，多传其他字段返回业务失败。
• 名称只是窗口元数据，窗口处于打开状态时同样可以改名，无需先关闭。
• 写入失败时 msg 优先使用服务端原文，否则为「窗口名称修改失败」。

响应字段

字段	类型	说明
data.windowId	string	窗口 ID
data.name	string	实际写入的窗口名称

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "windowId": "8001",
    "name": "店铺 A"
  }
}

GET/browser/accounts

查询窗口可填充账号

读取已打开窗口里可以自动填登录的账号，包括已绑定的平台账号，以及用户自己保存的密码。用户名已脱敏，密码和 2FA 密钥不会出现在响应里。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowId	string | string[]	必填	窗口数字 ID，支持单值、逗号分隔文本或重复传参；不接受窗口 uuid

注意事项

• 本接口只读，不负责给窗口选账号。选择或取消平台账号请用 POST /browser/account：传入 accountIds 绑定，传入 [] 表示不选择账号。
• 密码与 2FA 密钥只在 /automation/sessions/:sessionId/account_fill 的填表路径内使用，不经本接口外发。
• 账号条目还有一个恒为空串的 platformId 字段，请用 platformUrl 或 platformName 识别平台。

响应字段

字段	类型	说明
data	object[]	逐个窗口的查询结果
data[].windowId	string	窗口 ID
data[].windowName	string	窗口名称，成功时返回
data[].success	boolean	该窗口是否查询成功
data[].error	string	失败原因，成功时缺省
data[].code	string	失败时的稳定错误码；窗口未打开、保险库会话不可用时为 VAULT_SESSION_UNAVAILABLE
data[].accounts	object[]	绑定的平台账号（脱敏视图）
data[].accounts[].accountId	string	平台账号 ID
data[].accounts[].platformName	string	平台名，按 platformUrl 主机名推导
data[].accounts[].platformUrl	string	平台站点链接
data[].accounts[].username	string	脱敏后的登录名
data[].accounts[].remark	string	条目来源，固定中文：平台账户 或 自定义密码
data[].accounts[].hasPassword	boolean	是否存有密码
data[].accounts[].has2fa	boolean	2FA 密钥是否可用于生成验证码

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "windowId": "8001",
      "windowName": "示例环境-01",
      "success": true,
      "accounts": [
        {
          "accountId": "5001",
          "platformName": "x.com",
          "platformUrl": "https://x.com/",
          "username": "de**********nt",
          "remark": "平台账户",
          "hasPassword": true,
          "has2fa": true
        }
      ]
    }
  ]
}

POST/browser/open

打开浏览器窗口

按窗口 ID 启动一个或多个浏览器环境，并尽力补充 CDP 连接端点。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
teamId	string	必填	当前团队 ID；缺省返回业务失败
ids	string[]	必填	窗口 ID 数组

注意事项

• 传入单个窗口时 data 为该窗口对象；传入多个窗口时 data 为 rows 批量结构。
• 本机已有运行实例时直接复用并返回 alreadyRunning=true，不重复申请服务端占用。
• 服务端记录窗口已打开、但本机没有运行实例时（被其他设备或其他用户占用，或本账号上次未释放），该行失败「重新打开失败：请刷新窗口列表后重试」；可先用 /browser/list 的 runtimeState 判断。
• 服务端返回本人已占用（-1838）时不会自动把窗口状态回滚为关闭。
• 缺少 teamId 或窗口 ID 时返回业务失败「请先在 AI Agent 中重新选择窗口，当前本地缺少窗口启动配置」。
• 窗口已启动但 CDP 端点解析失败时不回滚窗口，改为在该行补 cdpError 字段。
• 兼容旧调用：ids 也可写成 windowId 或 id，单值或数组同样接受。

响应字段

字段	类型	说明
data.ok	boolean	内核启动结果
data.id	string	窗口 ID
data.windowId	string	窗口 ID，与 data.id 取值相同
data.key	string	本机运行实例标识
data.profileDir	string	窗口 profile 目录
data.running	boolean	窗口是否处于运行中
data.success	boolean	本行是否成功
data.alreadyRunning	boolean	调用前窗口是否已在运行
data.actualKernelVersion	string	实际使用的内核版本，读取不到时为 null
data.syncNotice	string	档案同步提示（固定中文），仅启动时有提示才返回
data.syncNoticeCode	string	syncNotice 对应的稳定提示码
data.ws	string	CDP WebSocket 地址
data.cdpEndpoint	string	CDP WebSocket 地址，与 data.ws 取值相同
data.http	string	CDP HTTP 地址
data.cdpHttpEndpoint	string	CDP HTTP 地址，与 data.http 取值相同
data.cdpPort	number	CDP 端口
data.devToolsActivePortPath	string	DevToolsActivePort 文件路径
data.cdpError	string	CDP 端点解析失败时的原因
data.rows	object[]	传入多个窗口时的逐行结果，字段同上
data.success	number	成功行数
data.failed	number	失败行数
data.total	number	总行数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "ok": true,
    "id": "8001",
    "windowId": "8001",
    "key": "8001",
    "profileDir": "C:\\Users\\demo\\AppData\\Roaming\\NexBrowser\\profiles\\8001",
    "running": true,
    "success": true,
    "alreadyRunning": false,
    "ws": "ws://127.0.0.1:9222/devtools/browser/6f1c-42f6-a0c9",
    "http": "http://127.0.0.1:9222",
    "cdpEndpoint": "ws://127.0.0.1:9222/devtools/browser/6f1c-42f6-a0c9",
    "cdpHttpEndpoint": "http://127.0.0.1:9222",
    "cdpPort": 9222,
    "devToolsActivePortPath": "C:\\Users\\demo\\AppData\\Roaming\\NexBrowser\\profiles\\8001\\DevToolsActivePort"
  }
}

GET/browser/connection_info

浏览器连接信息

读取运行中浏览器的 CDP 连接信息；不传窗口时返回全部已打开窗口。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowId	string | string[]	可选	窗口 ID，支持单值、逗号分隔文本或重复传参；不传返回全部运行中的窗口

注意事项

• 只返回运行中的窗口，未运行的窗口会被过滤掉；没有窗口运行时 data 为空数组。

响应字段

字段	类型	说明
data	object[]	运行中的窗口连接信息
data[].id	string	窗口 ID
data[].windowId	string	窗口 ID，与 data[].id 取值相同
data[].key	string	本机运行实例标识
data[].profileDir	string	窗口 profile 目录
data[].running	boolean	固定为 true
data[].success	boolean	固定为 true
data[].ws	string	CDP WebSocket 地址
data[].cdpEndpoint	string	CDP WebSocket 地址，与 data[].ws 取值相同
data[].http	string	CDP HTTP 地址
data[].cdpHttpEndpoint	string	CDP HTTP 地址，与 data[].http 取值相同
data[].cdpPort	number	CDP 端口
data[].devToolsActivePortPath	string	DevToolsActivePort 文件路径

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "id": "8001",
      "windowId": "8001",
      "key": "8001",
      "profileDir": "C:\\Users\\demo\\AppData\\Roaming\\NexBrowser\\profiles\\8001",
      "running": true,
      "success": true,
      "ws": "ws://127.0.0.1:9222/devtools/browser/6f1c-42f6-a0c9",
      "http": "http://127.0.0.1:9222",
      "cdpEndpoint": "ws://127.0.0.1:9222/devtools/browser/6f1c-42f6-a0c9",
      "cdpHttpEndpoint": "http://127.0.0.1:9222",
      "cdpPort": 9222,
      "devToolsActivePortPath": "C:\\Users\\demo\\AppData\\Roaming\\NexBrowser\\profiles\\8001\\DevToolsActivePort"
    }
  ]
}

POST/browser/close

关闭浏览器窗口

关闭一个或多个运行中的浏览器窗口，并返回批量结果。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
ids	string[]	必填	一个或多个窗口 ID；缺省返回业务失败
teamId	string	可选	可选团队 ID，用于释放服务端的窗口打开状态

注意事项

• 关闭会等待该窗口的退出档案同步结束后再返回；行内还可能带 uploadStatus、releaseStatus、pointerStatus 等分阶段状态。
• 窗口本就未运行时该行返回 success=false 且 error 为 "Browser is not running: <id>"。
• 兼容旧调用：ids 也可写成 windowId 或 id，单值或数组同样接受。

响应字段

字段	类型	说明
data.rows	object[]	逐个窗口的关闭结果
data.rows[].id	string	窗口 ID
data.rows[].key	string	本机运行实例标识
data.rows[].success	boolean	该窗口是否关闭成功
data.rows[].error	string	失败原因，成功时缺省
data.rows[].released	boolean	服务端窗口占用是否已释放，启用档案同步时返回
data.rows[].syncStatus	string	退出档案同步结果：uploaded、skipped、blocked、failed，启用档案同步时返回
data.rows[].syncReason	string	同步未完成时的机器可读原因，如 upload-error
data.success	number	成功行数
data.failed	number	失败行数
data.total	number	总行数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "rows": [
      {
        "id": "8001",
        "key": "8001",
        "success": true
      }
    ],
    "success": 1,
    "failed": 0,
    "total": 1
  }
}