使用 TUI

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

TUI 的工作鏈路

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

opencode

也可以指定工作目錄：

opencode /path/to/project

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

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. 用 @ 給上下文

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

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

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

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

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

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

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

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

3. 用 / 控制會話

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

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

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

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

最低限度的安全順序是：

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

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

5. 用 /editor 寫長訊息

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

Linux / macOS 示例：

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

Windows CMD 示例：

set EDITOR=notepad
set EDITOR=code --wait

Windows 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 配置分開。

{
  "$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
}

常用项先记住这些：

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

export OPENCODE_TUI_CONFIG=/path/to/tui.json

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

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

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

接下來去哪

官方資料

• OpenCode TUI：https://opencode.ai/docs/tui
• OpenCode Keybinds：https://opencode.ai/docs/keybinds
• OpenCode Themes：https://opencode.ai/docs/themes
• OpenCode Share：https://opencode.ai/docs/share