中文
文档
TUI 终端界面

TUI

使用 OpenCode 终端用户界面。

OpenCode 提供了一个交互式终端界面（即 TUI），让你能借助 LLM 来处理你的项目。

运行 OpenCode 会为当前目录启动 TUI。

opencode

或者你也可以为指定的工作目录启动它。

opencode /path/to/project

进入 TUI 后，你就可以向它发送消息进行提示。

Give me a quick summary of the codebase.

文件引用

你可以在消息中使用 @ 来引用文件。这会在当前工作目录中执行模糊文件搜索。

提示： 你也可以在消息中使用 @ 来引用文件。

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

文件的内容会被自动添加到对话中。

已配置的引用也会出现在 @ 自动补全中。输入 @alias 将引用根目录添加为上下文，或输入 @alias/ 来自动补全该引用内部的文件。

Compare our setup with @docs/README.md

Bash 命令

以 ! 开头的消息会执行一条 shell 命令。

!ls -la

命令的输出会作为工具结果添加到对话中。

命令

使用 OpenCode TUI 时，你可以输入 / 后跟命令名来快速执行操作。例如：

/help

大多数命令也有键盘快捷键，默认以 ctrl+x 作为前导键。了解更多。

以下是所有可用的斜杠命令：

connect

向 OpenCode 添加一个 provider。允许你从可用的 provider 中选择并添加它们的 API key。

/connect

compact

压缩当前会话。别名：/summarize

/compact

快捷键： ctrl+x c

details

切换工具执行详情的显示。

/details

editor

打开外部编辑器来撰写消息。使用你 EDITOR 环境变量中设置的编辑器。了解更多。

/editor

快捷键： ctrl+x e

exit

退出 OpenCode。别名：/quit、/q

/exit

快捷键： ctrl+x q

export

将当前对话导出为 Markdown 并在你的默认编辑器中打开。使用你 EDITOR 环境变量中设置的编辑器。了解更多。

/export

快捷键： ctrl+x x

help

显示帮助对话框。

/help

init

引导式设置，用于创建或更新 AGENTS.md。了解更多。

/init

models

列出可用的模型。

/models

快捷键： ctrl+x m

new

开始一个新会话。别名：/clear

/new

快捷键： ctrl+x n

redo

重做先前撤销的消息。仅在使用 /undo 之后可用。

提示： 任何文件改动也会被恢复。

在内部，这使用 Git 来管理文件改动。所以你的项目必须是一个 Git 仓库。

/redo

快捷键： ctrl+x r

sessions

列出并在会话之间切换。别名：/resume、/continue

/sessions

快捷键： ctrl+x l

share

分享当前会话。了解更多。

/share

themes

列出可用的主题。

/themes

快捷键： ctrl+x t

thinking

切换对话中思考/推理块的可见性。启用后，对于支持扩展思考的模型，你可以看到模型的推理过程。

注意： 此命令只控制思考块是否显示——它不会启用或禁用模型的推理能力。要切换实际的推理能力，请使用 ctrl+t 在不同的模型变体之间循环切换。

/thinking

undo

撤销对话中的最后一条消息。会移除最近的一条用户消息、所有后续响应以及任何文件改动。

提示： 所做的任何文件改动也会被还原。

在内部，这使用 Git 来管理文件改动。所以你的项目必须是一个 Git 仓库。

/undo

快捷键： ctrl+x u

unshare

取消分享当前会话。了解更多。

/unshare

编辑器设置

/editor 和 /export 命令都使用你 EDITOR 环境变量中指定的编辑器。

Linux/macOS

# 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 等。

Windows (CMD)

set EDITOR=notepad
 
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
set EDITOR=code --wait

要使其永久生效，请使用 系统属性 > 环境变量。

Windows (PowerShell)

$env:EDITOR = "notepad"
 
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
$env:EDITOR = "code --wait"

要使其永久生效，请将这一行添加到你的 PowerShell 配置文件中。

常见的编辑器选项包括：

  • code - Visual Studio Code
  • cursor - Cursor
  • windsurf - Windsurf
  • nvim - Neovim 编辑器
  • vim - Vim 编辑器
  • nano - Nano 编辑器
  • notepad - Windows 记事本
  • subl - Sublime Text

注意： 某些编辑器（如 VS Code）需要以 --wait 标志启动。

某些编辑器需要命令行参数才能以阻塞模式运行。--wait 标志会使编辑器进程一直阻塞，直到关闭。

配置

你可以通过 tui.json（或 tui.jsonc）来自定义 TUI 行为。

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 主题。了解更多 。
  • keybinds - 自定义键盘快捷键。了解更多 。
  • leader_timeout - 控制 OpenCode 在前导键之后等待多长时间。默认为 2000 。
  • scroll_acceleration.enabled - 启用 macOS 风格的滚动加速，实现平滑、自然的滚动。启用后，滚动速度会随着快速滚动手势而提高，并在较慢的移动时保持精确。此设置优先于 scroll_speed，启用时会覆盖它。
  • scroll_speed - 控制使用滚动命令时 TUI 的滚动速度（最小值：0.001 ，支持小数值）。默认为 3 。注意：如果 scroll_acceleration.enabled 设为 true，此项会被忽略。
  • diff_style - 控制 diff 渲染。"auto" 会自适应终端宽度，"stacked" 始终显示单列布局。
  • mouse - 启用或禁用 TUI 中的鼠标捕获（默认：true ）。禁用时，会保留终端原生的鼠标选择/滚动行为。
  • attention - 配置 TUI 的桌面通知和声音。默认禁用。

使用 OPENCODE_TUI_CONFIG 来加载自定义的 TUI 配置路径。

Attention

TUI 可以在出现问题、权限请求、会话错误以及会话完成时请求注意（attention）。通过 attention.enabled 来启用它；内置事件触发时会播放声音，而非子代理事件仅在终端失焦时才请求桌面通知。

  • enabled - 启用所有 attention 通知和声音。默认为 false 。
  • notifications - 启用 attention 时，允许由终端中转的桌面通知。默认为 true 。
  • sound - 启用 attention 时，允许 attention 声音。默认为 true 。
  • volume - 默认声音音量，从 0 到 1 。默认为 0.4 。
  • sound_pack - 要使用的音效包 ID。默认为 opencode.default 。
  • sounds - 为 default 、question 、permission 、error 、done 或 subagent_done 覆盖声音文件。路径可以是绝对路径、file:// URL，或相对于 tui.json 的路径。

自定义

你可以使用命令面板（ctrl+p）来自定义 TUI 视图的各个方面。这些设置在重启后会保留。

用户名显示

切换你的用户名是否出现在聊天消息中。通过以下方式访问：

  • 命令面板：搜索 "username" 或 "hide username"
  • 该设置会自动保留，并在多次 TUI 会话之间被记住
Windows (WSL)CLI 命令行