---
title: "终端 API：创建、输入与回读"
description: "Halo HTTP API 终端接口：创建终端会话、发送输入、调整大小、回读输出和关闭终端会话。"
type: "reference"
audience: ["developer"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/developers/api/terminal.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# API：终端

Halo HTTP API 终端接口：创建终端会话、发送输入、调整大小、回读输出和关闭终端会话。

这些是 Halo 中可被用户查看和输入的终端会话：创建、发送输入、调整大小、回读输出和关闭。实时输出通过 [WebSocket](https://hello-halo.cc/docs/developers/api/websocket.html#terminal) 推送。终端只在 macOS 和 Windows 上提供，在 Linux 上每个终端接口都返回 `403`。

所有路径都相对于你的 Halo 地址，每个请求都要带上访问密码。示例中的 `$HALO_URL` 和 `$HALO_TOKEN` 按[快速上手](https://hello-halo.cc/docs/developers/quickstart.html)设置；地址、鉴权和错误约定见 [HTTP API 概览](https://hello-halo.cc/docs/developers/api/)。

| 操作 | 端点 |
| --- | --- |
| [打开终端会话](#post-api-terminal-create) | `POST /api/terminal/create` |
| [向终端会话发送按键](#post-api-terminal-input) | `POST /api/terminal/input` |
| [关闭终端会话](#post-api-terminal-kill) | `POST /api/terminal/kill` |
| [列出打开的终端会话](#get-api-terminal-list) | `GET /api/terminal/list` |
| [回读终端会话的缓冲输出](#post-api-terminal-replay) | `POST /api/terminal/replay` |
| [调整终端会话大小](#post-api-terminal-resize) | `POST /api/terminal/resize` |

## 打开终端会话 {#post-api-terminal-create}

`POST /api/terminal/create`

- Opens a session with the platform's default shell in the workspace's working folder. Optional body fields: `cwd` (start folder) and `title`. The shell itself cannot be chosen.
- Live output arrives over the WebSocket as `terminal:data` events.

**请求体**

```json
{
  "spaceId": "<spaceId>"
}
```

**响应**

```ts
{success:true,data:{id,title,shell,cwd,cols,rows,owner:"user",state:"running",…}} | {success:false,error}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/terminal/create" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"<spaceId>"}'
```

## 向终端会话发送按键 {#post-api-terminal-input}

`POST /api/terminal/input`

- Writes raw keystrokes to the session; `\r` is Enter. Returns as soon as the input is written, before the command has produced output. Read the output from `terminal:data` events or [`POST /api/terminal/replay`](#post-api-terminal-replay).
- The WebSocket message `terminal-input` does the same without an HTTP round trip per keystroke.

**请求体**

```json
{
  "sessionId": "<sessionId>",
  "data": "ls\r"
}
```

**响应**

```ts
{success:true} | {success:false,error:"No such terminal session",code:"TERMINAL_NOT_FOUND"}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/terminal/input" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>","data":"ls\r"}'
```

## 关闭终端会话 {#post-api-terminal-kill}

`POST /api/terminal/kill`

- Ends the shell process; anything still running in it stops. `TERMINAL_NOT_FOUND` means the session is already gone.

**请求体**

```json
{
  "sessionId": "<sessionId>"
}
```

**响应**

```ts
{success:true} | {success:false,error:"No such terminal session",code:"TERMINAL_NOT_FOUND"}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/terminal/kill" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>"}'
```

## 列出打开的终端会话 {#get-api-terminal-list}

`GET /api/terminal/list`

- Lists the terminal sessions on this computer, including the ones Halo's assistant opened (`owner: "ai"`). `aiTouched` turns true once the assistant has used a session.

**响应**

```ts
{success:true,data:[{id,title,shell,cwd,cols,rows,owner:"ai"|"user",aiTouched,state:"running"|"exited",exitCode,lastActivityAt,createdAt,spaceId?}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/terminal/list" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 回读终端会话的缓冲输出 {#post-api-terminal-replay}

`POST /api/terminal/replay`

- Returns the session's info and its buffered output as raw terminal data, ANSI escape codes included, so a terminal view can redraw itself after connecting.

**请求体**

```json
{
  "sessionId": "<sessionId>"
}
```

**响应**

```ts
{success:true,data:{info:{id,title,…},data:"<buffered output>"}} | {success:false,error,code:"TERMINAL_NOT_FOUND"}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/terminal/replay" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>"}'
```

## 调整终端会话大小 {#post-api-terminal-resize}

`POST /api/terminal/resize`

- `cols` and `rows` must be positive integers.

**请求体**

```json
{
  "sessionId": "<sessionId>",
  "cols": 120,
  "rows": 32
}
```

**响应**

```ts
{success:true} | {success:false,error,code?:"TERMINAL_NOT_FOUND"}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/terminal/resize" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>","cols":120,"rows":32}'
```