LowHow 文档

中文

English

中文

English

深色模式

OpenCode TUI 实战教程：从零开始掌握终端界面 ​

📚 分类: 开发工具 / AI 辅助编程 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode、一个 Git 仓库（推荐）、支持终端的操作系统（macOS / Linux / Windows）

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 启动并进入 OpenCode 的终端用户界面（TUI）
  • [ ] 使用 @ 引用文件和 ! 执行 Bash 命令
  • [ ] 掌握 / 命令和快捷键，高效管理对话和配置
  • [ ] 自定义 TUI 的外观、行为和通知
  • [ ] 使用 EDITOR 环境变量编辑长消息

最终效果 ​

你将能够熟练地在一个功能丰富的终端界面中与 LLM（大语言模型）协作，处理你的项目代码。你可以在 TUI 中发起对话、引用文件、执行 Shell 命令、管理会话、并自定义界面主题和通知。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求验证命令
OpenCode已安装opencode --version
Git已安装（推荐）git --version
终端支持 TUI任意现代终端（iTerm2, Windows Terminal, Konsole 等）

1. 确认 OpenCode 安装 ​

首先，确认你已经安装了 OpenCode。如果未安装，请访问 OpenCode 官方安装文档 进行安装。

bash
$ opencode --version    // 验证 OpenCode 版本

✅ 验证：如果看到类似 opencode 0.x.x 的输出，说明安装成功。

2. 准备一个项目（可选但推荐） ​

为了体验 TUI 的全部功能（如文件引用、Git 操作），建议在一个已有的 Git 仓库中操作。

bash
# 进入你的项目目录
$ cd /path/to/your/project

✅ 验证：确保当前目录是一个 Git 仓库。

bash
$ git status
# 应该显示 On branch main 或类似信息

第 1 步：启动 TUI ​

🎯 目标：成功启动 OpenCode 的交互式终端界面。

📝 操作：

在终端中，进入你的项目目录，然后运行以下命令：

bash
# 启动当前目录的 TUI
$ opencode

或者，你也可以指定一个工作目录：

bash
# 为指定目录启动 TUI
$ opencode /path/to/your/project

✅ 验证： 执行后，终端界面会切换到一个全新的、美观的交互式界面。你会看到类似以下内容：

  • 界面顶部显示 OpenCode 标志和版本号。
  • 界面底部有一个输入框，等待你输入消息。
  • 屏幕上可能会显示欢迎信息或帮助提示。

💡 提示：如果 TUI 启动后界面显示异常（如乱码），请检查你的终端是否支持 Unicode 和 True Color。

第 2 步：发送你的第一条消息 ​

🎯 目标：在 TUI 中与 LLM 进行第一次交互。

📝 操作：

在底部的输入框中输入你的问题或指令，然后按 Enter 键。

例如，输入：

Give me a quick summary of the codebase.

✅ 验证： 你会看到 LLM 开始生成回复。回复会显示在输入框上方的对话区域中。

🤔 为什么要这样做？ TUI 的核心功能就是让你通过文本与 LLM 交互。LLM 会分析你的项目上下文（如果允许）并给出回答。

第 3 步：使用 @ 引用文件 ​

🎯 目标：学会如何将特定文件的内容作为上下文提供给 LLM。

📝 操作：

在输入消息时，输入 @ 符号，然后输入文件名的一部分。TUI 会自动弹出一个模糊搜索列表，帮助你找到需要的文件。

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

✅ 验证：

  • 当你输入 @ 后，应该能看到一个文件搜索列表。
  • 选择文件后，该文件的内容会自动附加到你的消息中，作为 LLM 的上下文。
  • LLM 的回复会基于你引用的文件内容进行分析。

💡 提示：文件搜索是基于当前工作目录进行的，支持模糊匹配。你可以输入文件名的一部分来快速定位。

第 4 步：使用 ! 执行 Bash 命令 ​

🎯 目标：学会在 TUI 中直接执行 Shell 命令。

📝 操作：

在输入框中，以 ! 开头输入任何你想执行的 Shell 命令。

! ls -la

✅ 验证：

  • 命令会立即执行。
  • 命令的输出会作为“工具结果”显示在对话中。
  • LLM 可以基于命令的输出结果进行后续分析或操作。

⚠️ 常见错误：

  • 如果命令执行失败（例如，权限不足），TUI 会显示错误信息。请检查命令是否正确，或使用 sudo（需要配置）。
  • 某些交互式命令（如 top）可能无法在 TUI 中正常工作。

第 5 步：使用 / 命令和快捷键 ​

🎯 目标：掌握 TUI 的核心命令和快捷键，高效管理会话。

📝 操作：

在输入框中，输入 / 后跟命令名称，然后按 Enter。

例如，要查看帮助：

/help

✅ 验证： 你会看到一个帮助对话框，列出了所有可用的命令及其快捷键。

核心命令速查表 ​

命令描述快捷键
/help显示帮助对话框Ctrl+X H
/new开始新会话Ctrl+X N
/undo撤销最后一条消息Ctrl+X U
/redo重做撤销的消息Ctrl+X R
/exit退出 OpenCodeCtrl+X Q
/compact压缩当前会话Ctrl+X C
/models列出可用模型Ctrl+X M
/sessions列出并切换会话Ctrl+X L
/share分享当前会话Ctrl+X S
/export导出会话为 MarkdownCtrl+X X
/editor打开外部编辑器Ctrl+X E
/details切换工具执行详情Ctrl+X D
/themes列出可用主题Ctrl+X T
/init创建/更新 AGENTS.mdCtrl+X I

🤔 为什么要这样做？/ 命令和快捷键是 TUI 的“瑞士军刀”。它们让你无需记住复杂的菜单操作，就能快速完成会话管理、模型切换、配置调整等任务。

第 6 步：配置外部编辑器 ​

🎯 目标：设置 EDITOR 环境变量，以便使用你喜欢的编辑器编写长消息。

📝 操作：

/editor 和 /export 命令会使用 EDITOR 环境变量中指定的编辑器。你需要根据你的操作系统进行配置。

macOS / Linux：

bash
# 终端编辑器示例：nano 或 vim
$ export EDITOR=nano
$ export EDITOR=vim

# GUI 编辑器示例：VS Code（需要 --wait 参数）
$ export EDITOR="code --wait"

Windows (CMD)：

cmd
> set EDITOR=notepad

> set EDITOR=code --wait

Windows (PowerShell)：

powershell
> $env:EDITOR="notepad"

> $env:EDITOR="code --wait"

✅ 验证： 配置完成后，在 TUI 中输入 /editor，你应该能看到你指定的编辑器被打开，并显示一个待编辑的消息模板。

💡 提示：

  • 要使配置永久生效，请将 export 命令添加到你的 shell 配置文件（如 ~/.bashrc、~/.zshrc）或 Windows 环境变量中。
  • --wait 参数对于 GUI 编辑器至关重要，它能让编辑器进程在关闭前阻塞终端，确保消息能被正确读取。

第 7 步：自定义 TUI 配置 ​

🎯 目标：通过 tui.json 文件自定义 TUI 的外观、行为和通知。

📝 操作：

TUI 的配置文件是 tui.json（或 tui.jsonc），它独立于 opencode.json（用于配置服务器和运行时行为）。

在你的项目根目录或 OpenCode 配置目录中创建 tui.json 文件，并添加以下内容：

json
{
  "$schema": "https://opencode.ai/tui.json",   // 可选：提供代码补全和校验
  "theme": "opencode",                          // 设置 UI 主题
  "leader_timeout": 2000,                       // 快捷键超时时间（毫秒）
  "keybinds": {                                 // 自定义键盘快捷键
    "leader": "ctrl+x",
    "command_list": "ctrl+p"
  },
  "scroll_speed": 3,                            // 滚动速度（最小值：0.001）
  "scroll_acceleration": {
    "enabled": false                            // 启用滚动加速
  },
  "diff_style": "auto",                         // 差异显示风格：auto 或 stacked
  "mouse": true,                                // 启用鼠标捕获
  "attention": {                                // 桌面通知和声音配置
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4,
    "sound_pack": "opencode.default",
    "sounds": {
      "error": "./sounds/error.mp3"             // 自定义错误提示音
    }
  }
}

✅ 验证：

  • 重新启动 TUI，你的配置会生效。
  • 尝试修改 theme 为其他可用主题（如 catppuccin），观察界面变化。
  • 尝试启用 scroll_acceleration，感受滚动效果的变化。

⚠️ 常见错误：

  • tui.json 和 opencode.json 是不同的文件，请勿混淆。
  • 如果配置文件格式错误（如缺少逗号），TUI 可能会使用默认配置并显示错误信息。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 自定义快捷键：在 keybinds 中，你可以覆盖任何内置快捷键。例如，将 leader 键改为 ctrl+z。
  2. 使用 OPENCODE_TUI_CONFIG 环境变量：你可以通过设置 OPENCODE_TUI_CONFIG 变量来指定一个自定义的 tui.json 文件路径，实现不同项目使用不同配置。
  3. 探索 attention 功能：启用后，当 OpenCode 需要你处理问题或会话完成时，TUI 会通过桌面通知和声音提醒你，即使终端窗口未聚焦。

常见问题 (FAQ) ​

Q1: 启动 TUI 后界面显示乱码或格式错乱？A: 请检查你的终端是否支持 Unicode 和 True Color。尝试更换终端（如 iTerm2, Windows Terminal）或调整终端的字体设置。

Q2: 如何修改端口号？A: 端口号是 OpenCode 服务端的配置，不在 tui.json 中。请修改 opencode.json 文件中的 port 字段。

Q3: 如何退出 TUI？A: 在输入框中输入 /exit 或按 Ctrl+X Q。

Q4: 如何查看所有可用的主题？A: 在 TUI 中输入 /themes 命令。

Q5: undo 和 redo 命令是如何工作的？A: 它们使用 Git 来管理文件更改。因此，你的项目必须是一个 Git 仓库，并且 undo 会撤销最近一条用户消息及其所有后续响应和文件更改。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 启动与交互：学会了如何启动 TUI 并发送第一条消息。
  2. 上下文增强：掌握了使用 @ 引用文件和 ! 执行 Bash 命令的技巧。
  3. 高效管理：熟悉了 / 命令和快捷键，能够快速管理会话、切换模型、撤销操作等。
  4. 个性化定制：学会了配置 EDITOR 环境变量和 tui.json 文件，打造属于自己的工作环境。

© 2026 LowHow