# 连接沙箱交互终端

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

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

## 连接准备

1. 从列表或创建结果取得沙箱 ID，回查目标阶段与实际可用性。
2. 使用个人访问令牌和目标工作区请求[终端令牌](get-terminal-token.md)，保存 `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；不把外部命令执行或真实会话验收等同于本地握手测试。
