---
title: "使用 TUI"
description: "說明 OpenCode 終端介面的基本操作、常見狀態和新手第一次使用的檢查點。"
verifiedAt: "2026-05-09"
---

OpenCode TUI 是日常使用的主入口。它不是一個普通聊天框，而是專案控制台：你在同一個終端裡給任務、引用檔案、執行 shell、切模型、看工具詳情、撤銷改動、切換會話和調整介面。

> [!NOTE]
> **這一篇用 12 分鐘換什麼**：你會知道第一次進入 TUI 後該看哪些控制點，哪些命令可以直接用，哪些動作必須先確認，怎麼把 TUI 調到適合長期使用的狀態。

## TUI 的工作鏈路

執行 `opencode` 會在當前目錄啟動 TUI：

```bash
opencode
```

也可以指定工作目錄：

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

進入以後，不要把它當“問答視窗”。更準確的動作鏈是：

```mermaid
flowchart LR
    Prompt["輸入任務"] --> Context["@ 引用檔案"]
    Context --> Shell["! 執行命令"]
    Shell --> Control["/ 控制會話"]
    Control --> Inspect["檢視 details / diff"]
    Inspect --> Decide["繼續 / 撤銷 / 壓縮 / 分享"]

    style Context fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style Shell fill:#dcfce7,stroke:#22c55e
    style Control fill:#fef3c7,stroke:#f59e0b
    style Decide fill:#fee2e2,stroke:#ef4444
```

這也是 TUI 和一次性 CLI `run` 的主要區別：TUI 讓你持續觀察 agent 讀了什麼、跑了什麼、改了什麼。

## 1. 用 `@` 給上下文

在訊息裡輸入 `@` 可以對當前工作目錄做模糊檔案搜尋，並把檔案內容加入對話。

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

更穩的寫法是把範圍和動作一起限制住：

```text
只阅读 @src/auth.ts 和 @src/routes/login.ts。
判断登录失败时错误是在哪里被吞掉的。
先解释，不要修改。
```

> [!IMPORTANT]
> **不要讓模型在大儲存庫裡自由猜上下文**：先給關鍵檔案，再讓它說明還需要看哪些檔案。這樣比“你自己找找問題”更可控。

## 2. 用 `!` 把命令輸出帶回對話

以 `!` 開頭的訊息會作為 shell 命令執行，命令輸出會進入當前會話。

```bash
!git status --short
!pnpm test
!pnpm run lint
```

適合直接執行的通常是隻讀命令、測試、型別檢查、lint 和專案自帶診斷指令碼。不適合直接放開的命令包括刪除檔案、強制回復、全儲存庫格式化、釋出部署、修改全域性配置和生產資料寫入。

> [!WARNING]
> **不要寫“需要什麼命令你隨便跑”**。更好的做法是：先讓 OpenCode 列出準備執行的命令、原因和影響範圍；會修改環境的命令確認後再執行。

## 3. 用 `/` 控制會話

斜槓命令是 TUI 的控制層。新手不用背全量命令，但要知道它們分成幾類。

| 類別 | 命令 | 用途 |
| --- | --- | --- |
| 幫助 | `/help` | 檢視幫助對話方塊 |
| 連線 | `/connect` | 新增 provider 和 API key |
| 專案初始化 | `/init` | 建立或更新 `AGENTS.md` |
| 模型 | `/models` | 檢視可用模型 |
| 觀察 | `/details` | 開關工具執行詳情 |
| 上下文 | `/compact`、`/summarize` | 壓縮當前會話 |
| 會話 | `/new`、`/sessions` | 新建、恢復或切換會話 |
| 編輯 | `/editor`、`/export` | 用外部編輯器寫長訊息，或匯出當前對話 |
| 變更控制 | `/undo`、`/redo` | 撤銷或重做上一輪訊息和檔案改動 |
| 分享 | `/share`、`/unshare` | 分享或取消分享當前會話 |
| 介面 | `/themes`、`/thinking` | 切主題，或控制 thinking/reasoning 塊顯示 |
| 退出 | `/exit`、`/quit`、`/q` | 退出 TUI |

官方預設 leader key 是 `ctrl+x`，很多命令可以透過快捷鍵觸發。完整快捷鍵不要在這裡硬背，後續用 keybinds 頁面按自己的終端衝突情況調整。

## 4. `/undo` 依賴 Git，不是萬能保險

`/undo` 會移除最近一條使用者訊息、後續響應以及對應檔案改動；`/redo` 可以重做已撤銷的訊息和檔案改動。官方說明這依賴 Git 管理檔案變化，所以專案需要是 Git 儲存庫。

最低限度的安全順序是：

```text
任务前看 git status
  ↓
限定本轮可修改范围
  ↓
任务后看 diff
  ↓
不满意再 /undo 或手动回滚
```

如果工作區本來就是髒的，不要讓 agent 直接大範圍修改。先讓它只讀解釋當前改動，確認哪些是使用者已有改動，哪些是本輪允許觸碰的檔案。

## 5. 用 `/editor` 寫長訊息

`/editor` 和 `/export` 都會使用 `EDITOR` 環境變數裡指定的編輯器。短提示詞直接在 TUI 輸入即可，長任務、複雜約束、分步驟需求更適合用外部編輯器寫完再提交。

Linux / macOS 示例：

```bash
export EDITOR=nano
export EDITOR=vim
export EDITOR="code --wait"
```

Windows CMD 示例：

```bat
set EDITOR=notepad
set EDITOR=code --wait
```

Windows PowerShell 示例：

```powershell
$env:EDITOR = "notepad"
$env:EDITOR = "code --wait"
```

VS Code、Cursor、VSCodium、Windsurf、Zed 等 GUI 編輯器通常需要 `--wait`，否則編輯器一開啟，OpenCode 可能就認為訊息已經結束。

## 6. 用 `tui.json` 調整介面

TUI 行為透過 `tui.json` 或 `tui.jsonc` 配置，和 `opencode.json` 的 server / runtime 配置分開。

```json title="tui.json"
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "keymap": {
    "leader": "ctrl+x",
    "leader_timeout": 2000
  },
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": false
  },
  "diff_style": "auto",
  "mouse": true
}
```

常用项先记住这些：

| 配置项 | 作用 |
| --- | --- |
| `theme` | 设置 TUI 主题 |
| `keymap` | 自定义快捷键（旧的 `keybinds` 字段已弃用，将在 v2.0 移除）|
| `scroll_speed` | 控制滚动速度，支持小数，默认 `3` |
| `scroll_acceleration.enabled` | 启用滚动加速；启用后会覆盖 `scroll_speed` |
| `diff_style` | 控制 diff 渲染，`auto` 会按终端宽度适配，`stacked` 使用单列 |
| `mouse` | 控制是否捕获鼠标；关闭后保留终端原生选择和滚动 |

如果要加载自定义 TUI 配置路径，可以设置：

```bash
export OPENCODE_TUI_CONFIG=/path/to/tui.json
```

> [!TIP]
> **先改少數高頻項**：主題、leader key、滑鼠捕獲和 diff 樣式最值得先調。不要一開始複製完整配置，否則以後很難看出自己到底改了什麼。

## 7. 命令面板和使用者名稱顯示

TUI 還提供命令面板，官方文件寫的是 `ctrl+p`。你可以在命令面板裡搜尋設定項，例如隱藏或顯示聊天訊息裡的使用者名稱。

使用者名稱顯示設定會自動儲存，並在 TUI 會話之間保持記憶。這個能力適合公開演示、錄屏或團隊共享螢幕前做輕量清理。

## 接下來去哪

<Cards>
  <Card title="CLI 入口" description="理解 TUI、run、serve、web、attach 和 auth/models 的邊界。" href="/zh-Hant/docs/opencode/official/00-getting-started/cli" />
  <Card title="快捷鍵" description="按自己的終端衝突情況調整 leader key 和高頻動作。" href="/zh-Hant/docs/opencode/official/01-customization/keybinds" />
  <Card title="主題" description="選擇內建主題，或建立一套適合長期工作的 TUI 主題。" href="/zh-Hant/docs/opencode/official/01-customization/themes" />
  <Card title="分享" description="理解 `/share`、`/unshare` 和團隊協作裡的敏感資訊邊界。" href="/zh-Hant/docs/opencode/official/00-getting-started/share" />
</Cards>

## 官方資料

- OpenCode TUI：[https://opencode.ai/docs/tui](https://opencode.ai/docs/tui)
- OpenCode Keybinds：[https://opencode.ai/docs/keybinds](https://opencode.ai/docs/keybinds)
- OpenCode Themes：[https://opencode.ai/docs/themes](https://opencode.ai/docs/themes)
- OpenCode Share：[https://opencode.ai/docs/share](https://opencode.ai/docs/share)
