连接沙箱交互终端¶
先取得目标沙箱的短期终端令牌,再连接 WebSocket。该入口使用终端令牌恢复身份并重验当前授权,不把个人访问令牌放到 token 查询参数中。
GET https://api.moi.matrixorigin.cn/v5/agent-sandboxes/{sandbox_id}/terminal/ws
连接准备¶
从列表或创建结果取得沙箱 ID,回查目标阶段与实际可用性。
使用个人访问令牌和目标工作区请求终端令牌,保存
data.token与data.expires_at。在令牌有效期内构造同一环境的
wss://…/agent-sandboxes/{sandbox_id}/terminal/ws?token=<URL-encoded-token>&cols=80&rows=24并发起标准 WebSocket 握手。具体主机与前缀使用当前环境配置,令牌必须 URL 编码。
查询字段 |
类型 |
说明 |
|---|---|---|
|
string |
该沙箱的有效签名终端令牌,绑定身份、角色候选和工作区。 |
|
integer |
初始列数;缺失、非有效 uint32 或 0 时使用 80。 |
|
integer |
初始行数;缺失、非有效 uint32 或 0 时使用 24。 |
有 Origin 时需同主机或命中部署允许列表;没有 Origin 的客户端也必须通过令牌与当前权限检查。签名服务、身份恢复或提供商未就绪时,不能只凭路由存在或 token 请求成功判断连接可用。
消息协议¶
方向/类型 |
载荷 |
作用 |
|---|---|---|
客户端 → 二进制消息 |
原始输入字节 |
写入终端。 |
客户端 → 文本消息 |
|
调整终端尺寸。 |
服务端 → 二进制消息 |
原始输出字节 |
终端输出,不保证是 UTF-8 或 JSON。 |
服务端 → 文本 JSON |
|
正常观察到终端进程结束;code 是实际退出码,0 仅为例子。 |
服务端 → 文本 JSON |
|
升级后服务错误;code:0 是当前消息结构的零值,不能当作进程成功。 |
客户端单条入站 WebSocket 消息最多 64 KiB。未知或无效文本不是命令执行 API;不要把 shell 命令装入虚构 JSON 字段。Go/Python 终端辅助对象能发送输入、调整尺寸和接收原始内容,但客户端仍须识别退出/错误,不把任意文本或连接关闭当成成功。
会话结束¶
连接最长 30 分钟,约每 30 秒重新绑定并检查当前授权;撤权、删除、服务错误或断开都会结束连接。终端 token 的 60 秒用于建立连接前有效性,已经建立的连接不因此保证有固定 60 秒或 30 分钟可用时间。断开时关闭本地连接,重新连接需重新检查状态和有效凭据;未取得 exit 消息时保留结果未知。
升级前失败按 HTTP 错误处理,升级后按消息与关闭处理。URL 中含敏感 token,避免记录完整 URL;不把外部命令执行或真实会话验收等同于本地握手测试。