自动化会话

自动化会话的创建与关闭、会话详情、标签页管理、窗口绑定账号填充，以及动作执行。同一条自动化链路的所有请求都要带同一个 X-Nex-Client-Id。

POST /automation/sessions/:sessionId/actions 支持的动作名称与字段见 自动化动作白名单。

在本页搜索

显示 10 / 10 个接口

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_fill

填入窗口绑定账号

把窗口绑定账号填入可见登录字段；只填不提交，请求与响应都不传出密码或 2FA 密钥。

鉴权Bearer API KeyX-Nex-Client-Id

请求参数

字段	类型	是否必填	说明
sessionId	string	必填	自动化会话 ID
accountId	string	可选	保险库条目 ID；窗口只有一条可填充凭据时可省略，多条时必填
pageId	string	可选	目标标签页 ID，缺省使用活动标签页

注意事项

• 不再接收 usernameTarget、passwordTarget、totpTarget；由保险库插件选择当前页可见登录字段。
• 窗口保险库有多条凭据时必须传 accountId，否则返回 INVALID_ARGUMENT。
• 密码与 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 毫秒

注意事项

• data 的三个字段按动作类型出现：读取类动作用 result，快照类动作用 snapshot，截图与下载用 artifacts。

响应字段

字段	类型	说明
data.result	any	动作返回值，形态随动作而定（文本、布尔、数组等）
data.snapshot	string	页面结构快照文本，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
  }
}