OpenCode TUI 终端界面实战指南：像高手一样在终端里用 AI 编程

引言

OpenCode 作为一款开源 AI 编程助手，最吸引人的地方之一就是它的终端用户界面（TUI）。相比于传统的 Web 聊天界面，TUI 拥有极低的资源占用、流畅的交互体验和几乎为零的启动延迟，特别适合已经习惯了 Vim、Neovim、tmux 等终端工具的老派开发者。

不过，很多刚接触 OpenCode 的朋友只知道在终端里输入 opencode 回车，然后就盯着闪烁的光标发愣——不知道如何引用文件、如何切换模型、如何撤销错误修改。本文将以实战为导向，系统梳理 OpenCode TUI 的完整用法，从基础操作到进阶配置，帮助你像高手一样在终端里流畅地使用 AI 编程助手。

一、启动与基础操作

1.1 启动 TUI

在项目根目录下直接运行 opencode 即可进入 TUI：

opencode

也可以指定工作目录：

opencode /path/to/project

如果你的项目不在当前目录，还可以配合 --continue（继续上次会话）、--session（指定会话）、--model（指定模型）等参数启动：

opencode --continue
opencode --session 9a4b7c2d
opencode --model anthropic/claude-sonnet-4-20250514

1.2 提问与对话

进入 TUI 后，直接在输入框输入消息即可与 AI 对话。可以像这样简单提问：

Give me a quick summary of the codebase.

输入框支持多行输入，善用这个能力可以给 AI 提供更丰富的上下文。

1.3 使用 @ 引用文件

在消息中使用 @ 可以进行模糊搜索并引用项目中的文件，被引用的文件内容会自动加入对话上下文：

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

这个功能非常实用，比如你接手一个陌生项目，想快速了解某个模块的实现细节，@ 引用比让 AI 自己大海捞针找文件高效得多。配置了 References 后，@alias 还能直接引用整个目录作为上下文，或输入 @alias/ 来补全目录内的文件。

1.4 使用 ! 执行 Shell 命令

在消息开头输入 !，可以直接在 TUI 里执行 Shell 命令，命令输出会作为工具结果加入对话：

!ls -la
!git status
!cat composer.json | head -50

这在询问 AI 之前先确认现场环境非常有用，避免了反复在终端和 TUI 之间切换。

二、Slash 命令速查

在 TUI 中，输入 / 后跟命令名，即可快速执行相应动作。以下是常用的 Slash 命令：

| 命令 | 作用 | 快捷键 |
| --- | --- | --- |
| /help | 显示帮助对话框 | - |
| /init | 引导创建或更新 AGENTS.md | - |
| /connect | 添加模型提供商并配置 API Key | - |
| /models | 列出当前可用模型 | ctrl+x m |
| /new | 开启新会话 | ctrl+x n |
| /sessions | 列出并切换会话 | ctrl+x l |
| /compact | 压缩当前会话上下文 | ctrl+x c |
| /undo | 撤销上一条消息及文件改动 | ctrl+x u |
| /redo | 重做被撤销的消息 | ctrl+x r |
| /editor | 用外部编辑器撰写消息 | ctrl+x e |
| /export | 导出会话为 Markdown | ctrl+x x |
| /share | 分享当前会话 | - |
| /unshare | 取消分享 | - |
| /themes | 列出可用主题 | ctrl+x t |
| /details | 切换工具执行细节显示 | - |
| /thinking | 切换推理过程块的显示 | - |
| /exit | 退出 OpenCode | ctrl+x q |

2.1 会话管理

/new 用于开启全新会话，避免上下文串扰；/sessions 则用于在历史会话之间切换。长期项目建议按功能模块划分会话，例如"登录模块重构"、"支付流程调试"，这样每个会话的上下文都保持精简，既省 token 又提高准确率。

2.2 撤销与重做

这是最容易被忽视却最实用的功能。/undo 会移除最近一条用户消息、所有后续回复以及对应的文件改动；/redo 则将其恢复。反复使用 /undo 可以逐层回退。需要特别注意的是，这两个功能内部依赖 Git 管理文件变更，因此你的项目必须是 Git 仓库。

2.3 上下文压缩

当对话较长、上下文接近模型窗口上限时，使用 /compact（或 /summarize）可以对当前会话进行压缩，把历史内容提炼成摘要，从而继续深入对话。OpenCode 也支持自动压缩（可用 OPENCODE_DISABLE_AUTOCOMPACT 禁用）。

三、编辑体验优化

3.1 配置外部编辑器

/editor 命令会用外部编辑器撰写消息，适合撰写大段、需要精心组织的 Prompt。编辑器由 EDITOR 环境变量指定：

# Linux / macOS
export EDITOR=vim
export EDITOR="code --wait"   # GUI 编辑器需要 --wait 阻塞模式

# Windows CMD
set EDITOR=notepad
set EDITOR=code --wait

# Windows PowerShell
$env:EDITOR = "notepad"
$env:EDITOR = "code --wait"

常用编辑器选项：code（VS Code）、cursor、windsurf、nvim、vim、nano、notepad、subl。注意像 VS Code 这类 GUI 编辑器必须加 --wait 参数，否则命令不会等待编辑完成。

3.2 导出与分享会话

/export 会把当前对话导出为 Markdown 并在默认编辑器中打开，方便归档、整理或贴到周报里。/share 则生成一个分享链接（默认不会自动分享），可以把某个有价值的排障过程分享给团队成员：

/share

四、通过 tui.json 定制界面

TUI 的行为可以通过 tui.json（或 tui.jsonc）配置文件定制。它独立于 opencode.json——后者配置的是服务端/运行时行为，而 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"
    }
  }
}

4.1 滚动与鼠标

  • scroll_speed：控制 TUI 滚动速度，默认为 3，支持小数。
  • scroll_acceleration.enabled：开启后采用 macOS 风格的滚动加速，快速滑动时更快、慢速时更精准。开启后优先级高于 scroll_speed。
  • mouse：是否启用鼠标捕获，默认为 true。在纯终端环境或习惯用键盘操作时，可以设为 false 以保留终端原生的鼠标选择与滚动行为。

4.2 Attention 提醒

这是很贴心的功能：当 AI 需要提问、请求权限、会话出错或任务完成时，TUI 可以发出桌面通知和提示音（默认关闭）。在终端窗口失焦时，通知会提醒你回来处理：

"attention": {
  "enabled": true,
  "notifications": true,
  "sound": true,
  "volume": 0.4
}

sounds 字段还能针对 default、question、permission、error、done、subagent_done 等事件自定义音效文件，路径可以是绝对路径、file:// URL 或相对 tui.json 的相对路径。

4.3 命令面板与界面微调

按 ctrl+p 可以打开命令面板，例如搜索"username"即可切换是否在聊天消息中显示用户名，该设置会自动持久化。这些微调让 TUI 更贴合个人习惯。

五、配合 CLI 让工作流自动化

TUI 适合交互式使用，而 CLI 命令则适合脚本化和自动化场景，两者配合能极大提升效率。

5.1 非交互式运行

opencode run "Explain the use of context in Go"
opencode run --model anthropic/claude-sonnet-4 "修复 login.php 中的 SQL 注入漏洞" --file login.php

--file 可以附加文件作为上下文，--format json 输出原始 JSON 事件，方便被其他程序解析。

5.2 会话与统计

opencode session list
opencode session list --format json
opencode session delete <sessionID>
opencode stats --days 7 --models 5

opencode stats 能直观展示 token 用量和成本，--models 还能查看各模型的用量占比，对控制 API 预算非常有帮助。

5.3 升级与维护

opencode upgrade            # 升级到最新版
opencode upgrade v0.1.48    # 升级到指定版本
opencode uninstall          # 卸载并清理数据

uninstall 支持 --keep-config、--keep-data、--dry-run 等安全选项，可以先预览再决定是否清理。

六、实用技巧总结

最后总结几个实战中非常有用的小技巧：

先计划后编码：用 Tab 键切换到 Plan 模式，让 AI 先给出实现方案，确认后再切回 Build 模式执行，避免方向跑偏。

善用 @ 与 !：引用具体文件给足上下文，用 ! 先跑命令摸清环境，AI 的答案会准确得多。

定期 /compact：长会话及时压缩上下文，既能省钱又能避免"上下文淹没"导致的错误。

依赖 Git：/undo 和 /redo 依赖 Git，保持项目是 Git 仓库，犯错时可以一键回退。

合理分会话：按任务拆分会话，别让几十个问题挤在一个会话里。

配置 Attention：在 TUI 里执行长时间任务时开启桌面通知，切到浏览器也不会错过 AI 的提问。

结语

OpenCode 的 TUI 设计得相当克制而高效：没有花哨的界面，但每个细节——文件引用、Shell 集成、Slash 命令、自定义配置——都是为真实开发场景打磨过的。配合 CLI 命令使用，它既能充当交互式编程助手，又能成为自动化流水线中的一环。

掌握这些 TUI 技巧之后，你会发现终端不再是只用来跑命令的"黑框框"，而是变成了与 AI 协作的高效战场。如果你已经在使用 OpenCode，不妨从今天开始，试着用 /sessions 管理你的对话，用 /compact 控制上下文，用 tui.json 定制一个属于自己的界面——相信很快你也会爱上这种纯粹的终端工作流。

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客