File size: 9,251 Bytes

3e05655

---
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"
/theme
```

**快速鍵：** `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` 是分開的。

`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` - 控制差異呈現方式。`"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 工作階段中保持記憶