opencode/packages/web/src/content/docs/zh-cn/tui.mdx

---
title: TUI
description: 使用 OpenCode 终端用户界面。
---

import { Tabs, TabItem } from "@astrojs/starlight/components"

OpenCode 提供了一个交互式终端界面（TUI），用于配合 LLM 处理您的项目。

运行 OpenCode 即可启动当前目录的 TUI。

```bash
opencode
```

或者您可以为指定的工作目录启动它。

```bash
opencode /path/to/project
```

进入 TUI 后，您可以输入消息进行提示。

```text
Give me a quick summary of the codebase.
```

---

## 文件引用

您可以使用 `@` 在消息中引用文件。这会在当前工作目录中进行模糊文件搜索。

:::tip
您还可以使用 `@` 来引用消息中的文件。
:::

```text "@packages/functions/src/api/index.ts"
How is auth handled in @packages/functions/src/api/index.ts?
```

文件的内容会自动添加到对话中。

---

## Bash 命令

以 `!` 开头的消息会作为 shell 命令执行。

```bash frame="none"
!ls -la
```

命令的输出会作为工具结果添加到对话中。

---

## 命令

使用 OpenCode TUI 时，您可以输入 `/` 后跟命令名称来快速执行操作。例如：

```bash frame="none"
/help
```

大多数命令还支持以 `ctrl+x` 作为前导键的快捷键，其中 `ctrl+x` 是默认前导键。[了解更多](/docs/keybinds)。

以下是所有可用的斜杠命令：

---

### connect

将提供商添加到 OpenCode。允许您从可用的提供商中选择并添加其 API 密钥。

```bash frame="none"
/connect
```

---

### compact

压缩当前会话。_别名_：`/summarize`

```bash frame="none"
/compact
```

**快捷键：** `ctrl+x c`

---

### details

切换工具执行详情的显示。

```bash frame="none"
/details
```

**快捷键：** `ctrl+x d`

---

### editor

打开外部编辑器来编写消息。使用 `EDITOR` 环境变量中设置的编辑器。[了解更多](#editor-setup)。

```bash frame="none"
/editor
```

**快捷键：** `ctrl+x e`

---

### exit

退出 OpenCode。_别名_：`/quit`、`/q`

```bash frame="none"
/exit
```

**快捷键：** `ctrl+x q`

---

### export

将当前对话导出为 Markdown 并在默认编辑器中打开。使用 `EDITOR` 环境变量中设置的编辑器。[了解更多](#editor-setup)。

```bash frame="none"
/export
```

**快捷键：** `ctrl+x x`

---

### help

显示帮助对话框。

```bash frame="none"
/help
```

**快捷键：** `ctrl+x h`

---

### init

创建或更新 `AGENTS.md` 文件。[了解更多](/docs/rules)。

```bash frame="none"
/init
```

**快捷键：** `ctrl+x i`

---

### models

列出可用模型。

```bash frame="none"
/models
```

**快捷键：** `ctrl+x m`

---

### new

开始新的会话。_别名_：`/clear`

```bash frame="none"
/new
```

**快捷键：** `ctrl+x n`

---

### redo

重做之前撤销的消息。仅在使用 `/undo` 后可用。

:::tip
所有文件更改也会被恢复。
:::

在内部，这使用 Git 来管理文件更改。因此您的项目**需要是一个 Git 仓库**。

```bash frame="none"
/redo
```

**快捷键：** `ctrl+x r`

---

### sessions

列出会话并在会话之间切换。_别名_：`/resume`、`/continue`

```bash frame="none"
/sessions
```

**快捷键：** `ctrl+x l`

---

### share

分享当前会话。[了解更多](/docs/share)。

```bash frame="none"
/share
```

**快捷键：** `ctrl+x s`

---

### themes

列出可用主题。

```bash frame="none"
/themes
```

**快捷键：** `ctrl+x t`

---

### thinking

切换对话中思考/推理块的可见性。启用后，您可以看到支持扩展思考的模型的推理过程。

:::note
此命令仅控制思考块是否**显示** — 它不会启用或禁用模型的推理能力。要切换实际的推理能力，请使用 `ctrl+t` 循环切换模型变体。
:::

```bash frame="none"
/thinking
```

---

### undo

撤销对话中的最后一条消息。移除最近的用户消息、所有后续响应以及所有文件更改。

:::tip
所做的任何文件更改也会被还原。
:::

在内部，这使用 Git 来管理文件更改。因此您的项目**需要是一个 Git 仓库**。

```bash frame="none"
/undo
```

**快捷键：** `ctrl+x u`

---

### unshare

取消分享当前会话。[了解更多](/docs/share#un-sharing)。

```bash frame="none"
/unshare
```

---

## 编辑器设置

`/editor` 和 `/export` 命令都使用 `EDITOR` 环境变量中指定的编辑器。

<Tabs>
  <TabItem label="Linux/macOS">
    ```bash
    # Example for nano or vim
    export EDITOR=nano
    export EDITOR=vim

    # For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
    # include --wait
    export EDITOR="code --wait"
    ```

    要使其永久生效，请将其添加到您的 shell 配置文件中；
    `~/.bashrc`、`~/.zshrc` 等。

  </TabItem>

  <TabItem label="Windows (CMD)">
    ```bash
    set EDITOR=notepad

    # For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
    # include --wait
    set EDITOR=code --wait
    ```

    要使其永久生效，请使用**系统属性** > **环境变量**。

  </TabItem>

  <TabItem label="Windows (PowerShell)">
    ```powershell
    $env:EDITOR = "notepad"

    # For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
    # include --wait
    $env:EDITOR = "code --wait"
    ```

    要使其永久生效，请将其添加到您的 PowerShell 配置文件中。

  </TabItem>
</Tabs>

常用的编辑器选项包括：

- `code` - Visual Studio Code
- `cursor` - Cursor
- `windsurf` - Windsurf
- `nvim` - Neovim 编辑器
- `vim` - Vim 编辑器
- `nano` - Nano 编辑器
- `notepad` - Notepad（Windows 记事本）
- `subl` - Sublime Text

:::note
某些编辑器（如 VS Code）需要以 `--wait` 标志启动。
:::

某些编辑器需要命令行参数才能以阻塞模式运行。`--wait` 标志使编辑器进程阻塞直到关闭。

---

## 配置

您可以通过 `tui.json`（或 `tui.jsonc`）自定义 TUI 行为。

```json title="tui.json"
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+p"
  },
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": false
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4,
    "sound_pack": "opencode.default",
    "sounds": {
      "error": "./sounds/error.mp3"
    }
  }
}
```

这与 `opencode.json` 是分开的；`opencode.json` 用于配置服务器和运行时行为。

`keybinds` 会与内置默认值合并，因此你只需要配置想要修改的快捷键。

### 选项

- `theme` - 设置 UI 主题。[了解更多](/docs/themes)。
- `keybinds` - 自定义键盘快捷键。[了解更多](/docs/keybinds)。
- `leader_timeout` - 控制按下 leader key 后 OpenCode 等待后续按键的时间。默认为 `2000`。
- `scroll_acceleration.enabled` - 启用 macOS 风格的滚动加速，让滚动更平滑自然。启用后，快速滚动时速度会增加，慢速移动时仍保持精确。**此设置优先于 `scroll_speed`，启用时会覆盖它。**
- `scroll_speed` - 控制使用滚动命令时 TUI 的滚动速度（最小值：`0.001`，支持小数）。默认为 `3`。**注意：如果 `scroll_acceleration.enabled` 设置为 `true`，则此设置会被忽略。**
- `diff_style` - 控制 diff 的显示方式。`"auto"` 会根据终端宽度自适应，`"stacked"` 始终显示单列布局。
- `mouse` - 在 TUI 中启用或禁用鼠标捕获（默认：`true`）。禁用后，终端原生的鼠标选择和滚动行为会保留下来。
- `attention` - 配置 TUI 桌面通知和声音。默认禁用。

使用 `OPENCODE_TUI_CONFIG` 可以加载自定义的 TUI 配置文件路径。

### Attention

当 OpenCode 需要你处理问题、批准权限请求、查看会话错误，或想告知会话已完成时，TUI 可以通过声音和桌面通知提醒你。设置 `attention.enabled` 后会启用这些提醒；内置事件触发时会播放声音。桌面通知只会在终端窗口未聚焦时发送，并且不会用于 subagent 事件。

- `enabled` - 开启 Attention 的所有通知和声音。默认为 `false`。
- `notifications` - 启用 Attention 后，允许 TUI 通过终端发送桌面通知。默认为 `true`。
- `sound` - 启用 Attention 后，允许播放提示音。默认为 `true`。
- `volume` - 默认提示音音量，范围从 `0` 到 `1`。默认为 `0.4`。
- `sound_pack` - 要使用的 sound pack ID。默认为 `opencode.default`。
- `sounds` - 为 `default`、`question`、`permission`、`error`、`done` 或 `subagent_done` 指定自定义声音文件。路径可以是绝对路径、`file://` URL，或相对于 `tui.json` 的路径。

---

## 自定义

您可以使用命令面板（`ctrl+x h` 或 `/help`）自定义 TUI 视图的各个方面。这些设置在重启后仍会保留。

---

#### 用户名显示

切换您的用户名是否显示在聊天消息中。通过以下方式访问：

- 命令面板：搜索 "username" 或 "hide username"
- 该设置会自动保存，并在各个 TUI 会话中保持记忆