OpenCode 中文教程

简体中文

English

简体中文

English

Appearance

界面与基础操作 ​

💡 一句话总结：掌握 @ 引用文件、! 执行命令、/ 斜杠命令，你就能驾驭 OpenCode。

📝 课程笔记 ​

本课核心知识点整理：

界面与基础操作学霸笔记

学完你能做什么 ​

  • 看懂 TUI 界面的每个区域
  • 用 @ 引用项目中的文件
  • 用 ! 执行系统命令
  • 用 / 调用斜杠命令
  • 记住最常用的快捷键

你现在的困境 ​

  • 打开了 OpenCode，但不知道界面各部分是干嘛的
  • 知道可以和 AI 对话，但不知道怎么让它读文件
  • 不知道有哪些快捷操作，只能打字交流

什么时候用这一招 ​

  • 当你需要：高效使用 OpenCode 完成日常任务
  • 而且不想：每次都打一大段话解释上下文

🎒 开始前的准备 ​

确保你已经完成以下事项：

核心思路 ​

TUI 界面导览 ​

启动 OpenCode 后，你会看到这样的界面：

┌─────────────────────────────────────────────────┐
│  OpenCode v1.0.0                    Build 模式  │  ← 状态栏/头部
├─────────────────────────────────────────────────┤
│                                                 │
│  AI: 你好！有什么我可以帮你的？                   │  ← 对话区
│                                                 │
├─────────────────────────────────────────────────┤
│  > 随便问点什么...                              │  ← 输入区
└─────────────────────────────────────────────────┘
区域作用
状态栏/头部显示版本、当前模式（Plan/Build）、Token 用量
侧栏会话列表（宽屏自动显示，窄屏隐藏）
对话区AI 回复和你的消息历史
输入区你输入消息的地方（不同模式有不同提示）
🆕 v1.1.57~v1.1.60 新增功能

1. 侧栏自动显示/隐藏（v1.1.57）

  • 宽屏（>120 列）时自动显示会话列表
  • 窄屏时自动隐藏，节省空间
  • 可通过 session.toggle.sidebar 命令手动切换

2. 输入框智能提示（v1.1.58）

  • 不同模式显示不同的占位符提示
  • 普通模式：随便问点什么...
  • Shell 模式：输入 shell 命令...
  • 评论总结模式：总结评论...

3. 隐藏会话头部（v1.1.60）

  • 可通过命令面板隐藏顶部状态栏
  • 适合需要更多对话空间的场景
  • 搜索 session.toggle.header 即可切换

核心操作三件套 ​

符号作用示例
@引用文件@src/main.ts 这个文件做了什么
!执行命令!ls -la 查看目录
/斜杠命令/help 查看帮助

跟我做 ​

第 1 步：启动 OpenCode 并进入项目 ​

为什么
在项目目录下启动，AI 才能看到你的代码文件。

bash
cd ~/your-project  # 换成你的项目路径
opencode

第 2 步：让 AI 介绍自己 ​

为什么
验证基础对话功能正常。

在输入区输入：

你好，请简单介绍一下你自己

按 Enter 发送。

你应该看到：AI 回复一段自我介绍

第 3 步：用 @ 引用文件 ​

为什么
这是 OpenCode 最强大的功能——让 AI 直接读取你的文件。

输入：

@package.json 这个文件描述了什么项目

💡 搜索补全

输入 @ 后会看到 Agent 列表（如 @explore）和文件夹。继续输入文件名的部分内容（如 @pack），才会搜索并显示匹配的具体文件，用方向键选择后按 Enter 确认。

你应该看到：AI 分析 package.json 的内容并回答

第 4 步：用 ! 执行命令 ​

为什么
让 AI 能看到命令的执行结果。

输入：

!ls -la

你应该看到：当前目录的文件列表显示在对话中

你也可以让 AI 执行命令：

帮我查看当前目录有哪些文件

AI 会自动调用相应的工具来执行。

第 5 步：用 / 调用斜杠命令 ​

为什么
斜杠命令是 OpenCode 的内置功能入口。

输入：

/help

你应该看到：所有可用斜杠命令的列表

常用斜杠命令速览：

命令作用
/help查看帮助
/new新建会话
/models切换模型
/theme切换主题
/exit退出

💡 界面自定义命令

在命令面板（Ctrl+X）中搜索：

  • session.toggle.sidebar - 切换侧栏显示
  • session.toggle.header - 切换头部显示

第 6 步：学会常用快捷键 ​

为什么
快捷键能让你操作更快。

快捷键作用
Tab切换 Plan/Build 模式
Ctrl+C中断当前操作
Ctrl+L清屏
Ctrl+XLeader 键（前缀键）
Ctrl+X N新建会话
Esc取消/返回
📦 什么是 Leader 键

Leader 键是一种快捷键组合方式。先按 Ctrl+X，松开后再按另一个键。

例如：Ctrl+X 然后 N = 新建会话

这样可以支持更多快捷键组合，而不会和系统快捷键冲突。

检查点 ✅ ​

全部通过才能继续

  • [ ] 用 @文件名 能引用到项目文件
  • [ ] 用 !命令 能执行系统命令
  • [ ] 用 /help 能看到帮助信息
  • [ ] Tab 键能切换 Plan/Build 模式

踩坑提醒 ​

现象原因解决
@ 后没有文件补全不在项目目录下cd 到项目目录重新启动
! 命令报权限错误OpenCode 拦截了危险命令确认命令安全后按 y 允许
快捷键不生效终端劫持了按键检查终端设置，或换一个终端

本课小结 ​

你学会了：

  1. TUI 界面的三个区域（状态栏、对话区、输入区）
  2. 核心操作三件套（@ 引用、! 执行、/ 命令）
  3. 最常用的快捷键

下一课预告 ​

下一课我们学习 如何复制内容。

你会学到：

  • 为什么 Ctrl+C 不能复制
  • Win/Mac 如何用鼠标复制
  • 怎样复制 AI 的长代码