自动化会话

自动化会话的创建与关闭、会话详情、标签页管理、当前页候选账号查询、保险库或调用方凭据填充，以及动作执行。同一条自动化链路的所有请求都要带同一个 X-Nex-Client-Id。

POST /automation/sessions/:sessionId/actions 支持的动作名称与字段见 自动化动作白名单。其中验证码动作还需要 X-Nex-Service-Context 请求头，取值见 服务与鉴权。

在本页搜索

显示 11 / 11 个接口

POST/automation/sessions

创建自动化会话

为一个浏览器窗口创建当前客户端独占的自动化会话，会话与 X-Nex-Client-Id 绑定。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
windowId	string	必填	浏览器窗口 ID
teamId	string	可选	团队 ID，缺省时使用当前登录团队
startIfNeeded	boolean	可选	为 true 时窗口未运行则先启动，默认 false

注意事项

• 窗口未运行且 startIfNeeded 不为 true 时返回 WINDOW_NOT_RUNNING。
• 会话记录创建时的账号与团队上下文，登录账号或团队变化后旧会话返回 UNAUTHORIZED。

响应字段

字段	类型	说明
data.clientId	string	会话归属客户端，取自 X-Nex-Client-Id
data.sessionId	string	会话 ID，后续接口的路径参数
data.teamId	string	会话所属团队 ID
data.windowId	string	会话绑定的窗口 ID
data.activePageId	string	当前活动标签页 ID，无标签页时缺省
data.tabs	object[]	当前标签页列表
data.tabs[].pageId	string	会话内稳定的标签页 ID
data.tabs[].title	string	页面标题，读取失败时为空串
data.tabs[].url	string	页面地址
data.tabs[].active	boolean	是否为本会话当前活动标签页
data.createdAt	number	会话创建时间戳，毫秒
data.lastActivityAt	number	最近一次活动时间戳，毫秒

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "clientId": "nex-doc-client-01",
    "sessionId": "a1f0c7d2-3b6e-4c58-9a1d-77e0b3c9f412",
    "teamId": "2001",
    "windowId": "8001",
    "activePageId": "page-1",
    "tabs": [
      {
        "pageId": "page-1",
        "title": "Example Domain",
        "url": "https://example.com/",
        "active": true
      }
    ],
    "createdAt": 1786000000000,
    "lastActivityAt": 1786000000000
  }
}

DELETE/automation/sessions

关闭客户端全部会话

释放当前 X-Nex-Client-Id 拥有的全部自动化会话，不关闭底层浏览器窗口。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

无参数

注意事项

• 适合在 MCP 客户端退出前调用，避免会话空转到空闲超时。

响应字段

字段	类型	说明
data.closed	boolean	固定为 true

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "closed": true
  }
}

GET/automation/sessions/:sessionId

自动化会话详情

读取当前客户端拥有的会话归属信息与实时标签页列表。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
sessionId	string	必填	自动化会话 ID

响应字段

字段	类型	说明
data.clientId	string	会话归属客户端，取自 X-Nex-Client-Id
data.sessionId	string	会话 ID，后续接口的路径参数
data.teamId	string	会话所属团队 ID
data.windowId	string	会话绑定的窗口 ID
data.activePageId	string	当前活动标签页 ID，无标签页时缺省
data.tabs	object[]	当前标签页列表
data.tabs[].pageId	string	会话内稳定的标签页 ID
data.tabs[].title	string	页面标题，读取失败时为空串
data.tabs[].url	string	页面地址
data.tabs[].active	boolean	是否为本会话当前活动标签页
data.createdAt	number	会话创建时间戳，毫秒
data.lastActivityAt	number	最近一次活动时间戳，毫秒

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "clientId": "nex-doc-client-01",
    "sessionId": "a1f0c7d2-3b6e-4c58-9a1d-77e0b3c9f412",
    "teamId": "2001",
    "windowId": "8001",
    "activePageId": "page-2",
    "tabs": [
      {
        "pageId": "page-1",
        "title": "Example Domain",
        "url": "https://example.com/",
        "active": false
      },
      {
        "pageId": "page-2",
        "title": "X",
        "url": "https://x.com/",
        "active": true
      }
    ],
    "createdAt": 1786000000000,
    "lastActivityAt": 1786000042000
  }
}

DELETE/automation/sessions/:sessionId

关闭自动化会话

释放一个自动化会话，不关闭底层浏览器窗口。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
sessionId	string	必填	自动化会话 ID

响应字段

字段	类型	说明
data.closed	boolean	固定为 true

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "closed": true
  }
}

GET/automation/sessions/:sessionId/tabs

标签页列表

列出会话中的稳定 pageId；已关闭的页面会在本次调用中被清理。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
sessionId	string	必填	自动化会话 ID

响应字段

字段	类型	说明
data	object[]	标签页列表
data[].pageId	string	会话内稳定的标签页 ID
data[].title	string	页面标题，读取失败时为空串
data[].url	string	页面地址
data[].active	boolean	是否为本会话当前活动标签页

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "pageId": "page-1",
      "title": "Example Domain",
      "url": "https://example.com/",
      "active": true
    }
  ]
}

POST/automation/sessions/:sessionId/tabs

新建标签页

在会话中打开新标签页并设为活动页，可选同时导航到指定地址。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
sessionId	string	必填	自动化会话 ID
url	string	可选	可选初始地址；导航超时按会话的导航超时配置

响应字段

字段	类型	说明
data	object[]	新建后的完整标签页列表
data[].pageId	string	会话内稳定的标签页 ID
data[].title	string	页面标题，读取失败时为空串
data[].url	string	页面地址
data[].active	boolean	是否为本会话当前活动标签页

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "pageId": "page-1",
      "title": "X",
      "url": "https://x.com/",
      "active": false
    },
    {
      "pageId": "page-2",
      "title": "Example Domain",
      "url": "https://example.com/",
      "active": true
    }
  ]
}

POST/automation/sessions/:sessionId/tabs/select

选择活动标签页

只改变当前会话的活动标签页，不影响其他客户端的会话。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
sessionId	string	必填	自动化会话 ID
pageId	string	必填	目标标签页 ID；不存在返回 PAGE_NOT_FOUND

响应字段

字段	类型	说明
data	object[]	切换后的完整标签页列表
data[].pageId	string	会话内稳定的标签页 ID
data[].title	string	页面标题，读取失败时为空串
data[].url	string	页面地址
data[].active	boolean	是否为本会话当前活动标签页

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "pageId": "page-1",
      "title": "X",
      "url": "https://x.com/",
      "active": true
    },
    {
      "pageId": "page-2",
      "title": "Example Domain",
      "url": "https://example.com/",
      "active": false
    }
  ]
}

POST/automation/sessions/:sessionId/tabs/close

关闭标签页

关闭当前会话中的一个稳定 pageId，并返回关闭后的标签页列表。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
sessionId	string	必填	自动化会话 ID
pageId	string	必填	目标标签页 ID；不存在返回 PAGE_NOT_FOUND

响应字段

字段	类型	说明
data	object[]	关闭后的完整标签页列表
data[].pageId	string	会话内稳定的标签页 ID
data[].title	string	页面标题，读取失败时为空串
data[].url	string	页面地址
data[].active	boolean	是否为本会话当前活动标签页

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "pageId": "page-1",
      "title": "X",
      "url": "https://x.com/",
      "active": true
    }
  ]
}

POST/automation/sessions/:sessionId/account_candidates

列出可填充账号

列出当前页可用的登录条目，供多账号时选择；只读，不填充，不含密码与 2FA 密钥。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
sessionId	string	必填	自动化会话 ID
pageId	string	可选	目标标签页 ID，缺省使用活动标签页

注意事项

• 候选由保险库插件按目标页计算，与 /browser/accounts 返回的整个保险库不同。
• 调用会把目标标签页切为活动页；保险库会话不可用时返回 WINDOW_NOT_RUNNING。

响应字段

字段	类型	说明
data.windowId	string	会话绑定的窗口 ID
data.host	string	目标标签页的主机名
data.candidates	object[]	与当前页匹配的登录条目
data.candidates[].credentialId	string	条目 ID，作为 account_fill 的 accountId
data.candidates[].username	string	条目登录名
data.candidates[].name	string	条目名称

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "windowId": "8001",
    "host": "x.com",
    "candidates": [
      {
        "credentialId": "platform:5001",
        "username": "de**********nt",
        "name": "x.com"
      },
      {
        "credentialId": "local:2",
        "username": "op******01",
        "name": "x.com"
      }
    ]
  }
}

POST/automation/sessions/:sessionId/account_fill

填入窗口登录账号

把保险库条目或调用方提供的凭据填入当前页可见登录字段；只填不提交，响应不含密码或 2FA 密钥。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
sessionId	string	必填	自动化会话 ID
accountId	string	可选	保险库条目 ID，可取自 account_candidates 的 credentialId 或 /browser/accounts 的 accountId
username	string	可选	按登录名在当前页匹配的条目中选择，未传 accountId 时使用
credentials	object	可选	保险库之外的登录凭据，仅本次使用
credentials.username	string	可选	登录名
credentials.password	string	可选	登录密码，原样使用，保留首尾空格
credentials.totp	string	可选	2FA 密钥，由插件生成验证码
credentials.totpCode	string	可选	已生成的一次性验证码，原样填入
pageId	string	可选	目标标签页 ID，缺省使用活动标签页

注意事项

• 条目选择由保险库插件按当前打开的页面完成：只有与页面匹配的登录条目才会被考虑。
• 匹配到多条且未指定 accountId 或 username 时返回 INVALID_ARGUMENT，data.candidates 列出候选条目（credentialId、username、name），data.code 为插件结果码（如 ambiguous、noMatch）；改传 accountId 重试即可。
• credentials 只用于本次填充，不入库、不回显、不写日志，错误信息中也不会出现这些值。
• 保险库会话不可用（窗口未打开或插件未就绪）时返回 WINDOW_NOT_RUNNING。
• 不再接收 usernameTarget、passwordTarget、totpTarget；由保险库插件选择当前页可见登录字段。
• 保险库密码与 2FA 密钥只在插件内使用，不会出现在请求体或响应中。本接口只填不提交。

响应字段

字段	类型	说明
data.windowId	string	会话绑定的窗口 ID
data.accountId	string	插件实际填充的条目 ID
data.platformName	string	条目名称
data.username	string	插件返回的条目登录名
data.filled	string[]	实际填写的凭据项：username、password、totp
data.submitted	boolean	固定为 false，本接口不提交表单

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "windowId": "8001",
    "accountId": "5001",
    "platformName": "x.com",
    "username": "de**********nt",
    "filled": [
      "username",
      "password"
    ],
    "submitted": false
  }
}

POST/automation/sessions/:sessionId/actions

执行自动化动作

从固定白名单选择一个动作并进入会话的串行执行队列，动作清单见页面下方。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
sessionId	string	必填	自动化会话 ID
action	string	必填	动作名称，取值见「自动化动作」白名单；不在白名单返回 ACTION_NOT_ALLOWED
pageId	string	可选	目标标签页 ID，缺省使用活动标签页
params	object	可选	动作专属参数
params.timeout	number	可选	通用超时，范围 1..120000 毫秒
params.snapshot	string | boolean	可选	操作后回传快照的粒度：none 不回传、refs 只回传元素引用、full 完整快照；交互类动作默认 refs，snapshot 动作默认 full；false 等同 none，true 等同 full
X-Nex-Service-Context	header	可选	验证码动作必填，取自业务接口响应的 contextId
X-Nex-Request-Deadline	header	可选	验证码动作可选，毫秒时间戳形式的请求期限

注意事项

• data 的三个字段按动作类型出现：读取类动作用 result，快照类动作用 snapshot，截图与下载用 artifacts。
• captchaInspect、captchaRefresh、captchaApply 必须带 X-Nex-Service-Context 请求头；执行前后都会复核登录与团队，发生变化时返回 UNAUTHORIZED。
• 调用方在动作排队期间断开连接时，验证码动作不会再派发到页面。
• 已登记错误码的失败统一归为 INVALID_ARGUMENT，msg 为中文；data 中不含服务端业务码。

响应字段

字段	类型	说明
data.result	any	动作返回值，形态随动作而定（文本、布尔、数组等）
data.result.path	string	screenshot 动作：截图文件本机路径
data.result.region	object	screenshot 动作：截图区域在视口 CSS 像素坐标系中的 x、y、width、height，可换算回点击坐标
data.snapshot	string	页面结构快照文本；导航与交互类动作默认只含元素引用段，可用 params.snapshot 调整
data.artifacts	object[]	产物列表，截图与下载类动作返回
data.artifacts[].kind	string	产物类型：screenshot、download、trace
data.artifacts[].path	string	产物本机路径
data.artifacts[].mimeType	string	产物 MIME 类型
data.artifacts[].size	number	产物字节数
data.artifacts[].base64	string	产物 Base64 内容，按动作参数决定是否返回

响应示例

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