OpenCode Guide
Navigate: Menu

Intro (入门)

Usage (使用指南)

Configure (详细配置)

Develop (开发)

终端界面 (TUI)

使用 OpenCode 的终端用户界面（Terminal User Interface）。
OpenCode 提供了一个交互式的终端界面（TUI），让你可以和 LLM 一起在项目中工作。
运行 OpenCode 会为当前目录启动 TUI：
opencode
也可以为指定的工作目录启动：
opencode /path/to/project
进入 TUI 后，你可以直接输入提示消息：
Give me a quick summary of the codebase.

文件引用（File references）

你可以在消息中使用 @ 来引用文件，它会在当前工作目录进行模糊搜索：
How is auth handled in @packages/functions/src/api/index.ts ?
被引用的文件内容会自动加入到对话中。

Bash 命令

在消息开头使用 ! 来执行 shell 命令：
!ls -la
命令的输出会作为工具结果加入对话。

命令（Commands）

在 OpenCode TUI 中，输入 / 后跟命令名称可以快速执行操作，例如：
/help
大多数命令也支持使用 ctrl+x 作为默认前缀键（leader key）。了解更多按键绑定
以下是所有可用的斜杠命令：

connect

添加一个 AI 提供商，选择可用提供商并输入 API Key。
/connect

compact

压缩当前会话。（别名：/summarize）
/compact
快捷键： ctrl+x c

details

切换工具执行细节的显示。
/details
快捷键： ctrl+x d

editor

使用外部编辑器编写消息（使用环境变量 EDITOR 中设置的编辑器）。
/editor
快捷键： ctrl+x e

exit

退出 OpenCode。（别名：/quit、/q）
/exit
快捷键： ctrl+x q

export

将当前对话导出为 Markdown 并用默认编辑器打开（使用 EDITOR 变量）。
/export
快捷键： ctrl+x x

help

显示帮助对话框。
/help
快捷键： ctrl+x h

init

创建或更新 AGENTS.md 文件。了解更多
/init
快捷键： ctrl+x i

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
快捷键： ctrl+x s

themes

列出可用主题。
/theme
快捷键： ctrl+x t

undo

撤销对话中的最后一条消息（移除最近的用户消息、后续所有回复以及文件变更）。
内部使用 Git 管理文件变更，因此项目必须是一个 Git 仓库。
/undo
快捷键： ctrl+x u

unshare

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

编辑器设置（Editor setup）

/editor 和 /export 命令会使用环境变量 EDITOR 中指定的编辑器。
# 示例：nano 或 vim
export EDITOR=nano
export EDITOR=vim

# 对于 GUI 编辑器（如 VS Code、Cursor 等），建议加上 --wait
export EDITOR="code --wait"
建议写入 shell 配置文件（~/.bashrc、~/.zshrc 等）使其永久生效。
常用编辑器选项：
  • code — Visual Studio Code
  • cursor — Cursor
  • windsurf — Windsurf
  • nvim — Neovim
  • vim — Vim
  • nano — Nano
  • notepad — Windows Notepad
  • subl — Sublime Text
部分编辑器需要 --wait 等参数才能阻塞式等待关闭。

配置（Configure）

你可以通过 OpenCode 配置文件自定义 TUI 行为。
{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}
文件名：opencode.json

可用选项

  • scroll_acceleration：启用 macOS 风格的滚动加速度（快速滚动时加速，慢速时精确）。启用后会覆盖 scroll_speed。
  • scroll_speed：控制滚动命令的速度（最小值 1）。Unix 默认 1，Windows 默认 3。注意：如果启用了 scroll_acceleration，此项会被忽略。

自定义（Customization）

你可以通过命令面板（ctrl+x h 或 /help）自定义 TUI 的多种显示设置，这些设置会跨重启保存。

用户名显示

切换聊天消息中是否显示你的用户名。
  • 通过命令面板搜索 “username” 或 “hide username”
  • 设置会自动持久化，在所有 TUI 会话中记住