使用 TUI

OpenCode TUI 是日常使用的主入口。它不是一个普通聊天框，而是项目控制台：你在同一个终端里给任务、引用文件、运行 shell、切模型、看工具详情、撤销改动、切换会话和调整界面。

TUI 的工作链路

运行 opencode 会在当前目录启动 TUI：

opencode

也可以指定工作目录：

opencode /path/to/project

进入以后，不要把它当“问答窗口”。更准确的动作链是：

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. 用 @ 给上下文

在消息里输入 @ 可以对当前工作目录做模糊文件搜索，并把文件内容加入对话。

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

更稳的写法是把范围和动作一起限制住：

只阅读 @src/auth.ts 和 @src/routes/login.ts。
判断登录失败时错误是在哪里被吞掉的。
先解释，不要修改。

2. 用 ! 把命令输出带回对话

以 ! 开头的消息会作为 shell 命令执行，命令输出会进入当前会话。

!git status --short
!pnpm test
!pnpm run lint

适合直接运行的通常是只读命令、测试、类型检查、lint 和项目自带诊断脚本。不适合直接放开的命令包括删除文件、强制回滚、全仓库格式化、发布部署、修改全局配置和生产数据写入。

3. 用 / 控制会话

斜杠命令是 TUI 的控制层。新手不用背全量命令，但要知道它们分成几类。

官方默认 leader key 是 ctrl+x，很多命令可以通过快捷键触发。完整快捷键不要在这里硬背，后续用 keybinds 页面按自己的终端冲突情况调整。

4. /undo 依赖 Git，不是万能保险

/undo 会移除最近一条用户消息、后续响应以及对应文件改动；/redo 可以重做已撤销的消息和文件改动。官方说明这依赖 Git 管理文件变化，所以项目需要是 Git 仓库。

最低限度的安全顺序是：

任务前看 git status
  ↓
限定本轮可修改范围
  ↓
任务后看 diff
  ↓
不满意再 /undo 或手动回滚

如果工作区本来就是脏的，不要让 agent 直接大范围修改。先让它只读解释当前改动，确认哪些是用户已有改动，哪些是本轮允许触碰的文件。

5. 用 /editor 写长消息

/editor 和 /export 都会使用 EDITOR 环境变量里指定的编辑器。短提示词直接在 TUI 输入即可，长任务、复杂约束、分步骤需求更适合用外部编辑器写完再提交。

Linux / macOS 示例：

export EDITOR=nano
export EDITOR=vim
export EDITOR="code --wait"

Windows CMD 示例：

set EDITOR=notepad
set EDITOR=code --wait

Windows 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 配置分开。

{
  "$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
}

常用项先记住这些：

如果要加载自定义 TUI 配置路径，可以设置：

export OPENCODE_TUI_CONFIG=/path/to/tui.json

7. 命令面板和用户名显示

TUI 还提供命令面板，官方文档写的是 ctrl+p。你可以在命令面板里搜索设置项，例如隐藏或显示聊天消息里的用户名。

用户名显示设置会自动保存，并在 TUI 会话之间保持记忆。这个能力适合公开演示、录屏或团队共享屏幕前做轻量清理。

接下来去哪

官方资料

• OpenCode TUI：https://opencode.ai/docs/tui
• OpenCode Keybinds：https://opencode.ai/docs/keybinds
• OpenCode Themes：https://opencode.ai/docs/themes
• OpenCode Share：https://opencode.ai/docs/share