连接沙箱交互终端

先取得目标沙箱的短期终端令牌,再连接 WebSocket。该入口使用终端令牌恢复身份并重验当前授权,不把个人访问令牌放到 token 查询参数中。

GET https://api.moi.matrixorigin.cn/v5/agent-sandboxes/{sandbox_id}/terminal/ws

连接准备

  1. 从列表或创建结果取得沙箱 ID,回查目标阶段与实际可用性。

  2. 使用个人访问令牌和目标工作区请求终端令牌,保存 data.token 与 data.expires_at。

  3. 在令牌有效期内构造同一环境的 wss://…/agent-sandboxes/{sandbox_id}/terminal/ws?token=<URL-encoded-token>&cols=80&rows=24 并发起标准 WebSocket 握手。具体主机与前缀使用当前环境配置,令牌必须 URL 编码。

查询字段

类型

说明

token

string

该沙箱的有效签名终端令牌,绑定身份、角色候选和工作区。

cols

integer

初始列数;缺失、非有效 uint32 或 0 时使用 80。

rows

integer

初始行数;缺失、非有效 uint32 或 0 时使用 24。

有 Origin 时需同主机或命中部署允许列表;没有 Origin 的客户端也必须通过令牌与当前权限检查。签名服务、身份恢复或提供商未就绪时,不能只凭路由存在或 token 请求成功判断连接可用。

消息协议

方向/类型

载荷

作用

客户端 → 二进制消息

原始输入字节

写入终端。

客户端 → 文本消息

{"type":"resize","cols":120,"rows":30}

调整终端尺寸。

服务端 → 二进制消息

原始输出字节

终端输出,不保证是 UTF-8 或 JSON。

服务端 → 文本 JSON

{"type":"exit","code":0}

正常观察到终端进程结束;code 是实际退出码,0 仅为例子。

服务端 → 文本 JSON

{"type":"error","code":0,"message":"<localized message>"}

升级后服务错误;code:0 是当前消息结构的零值,不能当作进程成功。

客户端单条入站 WebSocket 消息最多 64 KiB。未知或无效文本不是命令执行 API;不要把 shell 命令装入虚构 JSON 字段。Go/Python 终端辅助对象能发送输入、调整尺寸和接收原始内容,但客户端仍须识别退出/错误,不把任意文本或连接关闭当成成功。

会话结束

连接最长 30 分钟,约每 30 秒重新绑定并检查当前授权;撤权、删除、服务错误或断开都会结束连接。终端 token 的 60 秒用于建立连接前有效性,已经建立的连接不因此保证有固定 60 秒或 30 分钟可用时间。断开时关闭本地连接,重新连接需重新检查状态和有效凭据;未取得 exit 消息时保留结果未知。

升级前失败按 HTTP 错误处理,升级后按消息与关闭处理。URL 中含敏感 token,避免记录完整 URL;不把外部命令执行或真实会话验收等同于本地握手测试。

最后更新于