---
title: OpenCode TUI 实战指南
icon: mdi:monitor-dashboard
date: 2026-03-06
category:
  - AI
  - 开发工具
tag:
  - OpenCode
  - TUI
  - AI编程
---

# OpenCode TUI 实战指南

这篇文章基于 OpenCode 官方文档的 TUI 章节，聚焦终端交互界面的
高频用法：怎么聊、怎么调、怎么把会话真正用起来。

<!-- more -->

---

## 一、先启动 TUI

直接在当前目录启动：

```bash
opencode
```

或者指定项目目录启动：

```bash
opencode /path/to/project
```

进入后就能直接提问，例如：

```text
先给我快速总结一下这个仓库结构和技术栈。
```

---

## 二、两个最实用的输入能力

### 2.1 `@` 文件引用

在消息里用 `@` 引用文件，OpenCode 会做模糊匹配并把文件内容带入上下文。

```text
@src/.vuepress/config.ts 这个配置里有哪些容易踩坑的点？
```

适合代码审查、定位问题、讲解现有实现。

### 2.2 `!` Bash 命令

输入 `!` 开头的内容，会按 shell 命令执行并把输出注入会话。

```text
!git status
!npm run docs:build
```

这个能力非常适合“边看代码边验证”。

---

## 三、必须掌握的斜杠命令

### 3.1 会话与整理

```text
/new
/sessions
/compact
```

- `/new`：开新会话（清空当前上下文）。
- `/sessions`：快速切换历史会话。
- `/compact`：压缩上下文，长对话时很有用。

### 3.2 可视化与排障

```text
/details
/thinking
/models
```

- `/details`：显示或隐藏工具执行细节。
- `/thinking`：切换推理块显示（仅控制展示）。
- `/models`：查看可用模型并确认当前选择。

### 3.3 输出与分享

```text
/export
/share
/unshare
```

- `/export`：导出当前对话为 Markdown。
- `/share`：分享当前会话。
- `/unshare`：取消分享。

---

## 四、`undo` / `redo` 的正确理解

```text
/undo
/redo
```

这两个命令不仅会撤销或重做消息，也会回滚或恢复文件变更。

注意：它依赖 Git 管理改动，所以项目目录最好是一个 Git 仓库。

---

## 五、编辑器联动（很建议配）

`/editor` 和 `/export` 都依赖 `EDITOR` 环境变量。

Linux / macOS 示例：

```bash
export EDITOR="code --wait"
```

如果你使用 `vim` / `nvim` / `nano` 也可以直接设置对应命令。

推荐使用带 `--wait` 的 GUI 编辑器，这样 TUI 会等待你编辑完成再返回。

---

## 六、TUI 配置项（滚动最常用）

可以在配置文件中设置：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}
```

- `scroll_speed`：滚动速度（最小 `1`）。
- `scroll_acceleration.enabled`：类 macOS 滚动加速。

当加速开启时，会覆盖 `scroll_speed` 的效果。

---

## 七、一套我常用的 TUI 习惯

1. 先用 `@` 精准挂载关键文件，再提任务。
2. 单次只做一类改动，必要时 `/compact`。
3. 关键节点 `/export`，形成可复盘记录。
4. 大改前先确认 Git 状态，便于 `/undo` 使用。
5. 需要自动化时再切到 `opencode run`。

---

## 八、结语

TUI 的核心不是“会聊天”，而是把上下文、命令执行和文件改动放在同一条工作流里。

如果你平时就在终端里开发，OpenCode TUI 会比网页对话更顺手。

> 参考文档：
> https://opencode.ai/docs/zh-cn/tui/