---
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="/docs/opencode/official/00-getting-started/cli" />
  <Card title="快捷键" description="按自己的终端冲突情况调整 leader key 和高频动作。" href="/docs/opencode/official/01-customization/keybinds" />
  <Card title="主题" description="选择内置主题，或创建一套适合长期工作的 TUI 主题。" href="/docs/opencode/official/01-customization/themes" />
  <Card title="分享" description="理解 `/share`、`/unshare` 和团队协作里的敏感信息边界。" href="/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)
