OpenCode 界面与基础操作实战教程：掌握 @、!、/ 三大核心功能
📚 分类: AI 编程工具 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode（建议版本 v1.1.60+）并配置好 AI 模型 🌐 原文来源: 官方文档站
你将学到什么
完成本教程后，你将能够：
- [ ] 识别 OpenCode 终端界面的各个功能区域
- [ ] 使用
@符号引用项目文件，让 AI 读取并分析你的代码 - [ ] 使用
!符号执行系统命令，让 AI 看到运行结果并辅助调试 - [ ] 使用
/斜杠命令调用 OpenCode 的内置功能（如帮助、切换主题） - [ ] 掌握最常用的快捷键，提升操作效率
最终效果
你将能够在 OpenCode 中，通过三种核心操作（@、!、/）与 AI 进行高效协作。AI 将能直接读取你的代码、执行命令并查看结果，就像一位经验丰富的编程伙伴坐在你身边。
前置准备
在开始前，请确认你的环境满足以下条件：
| 检查项 | 要求 | 验证命令 |
|---|---|---|
| OpenCode 已安装 | 最新稳定版 | opencode --version |
| AI 模型已连接 | 能正常对话 | 启动后输入任意文字看 AI 是否回复 |
1. 进入你的项目目录
OpenCode 的强大之处在于它能感知你项目中的文件。因此，你需要在一个项目目录下启动它。
# 假设你的项目在 ~/my-awesome-project 下
$ cd ~/my-awesome-project
# 确保目录下有文件（例如 package.json）
$ ls✅ 验证：ls 命令应该能列出你项目中的文件和文件夹。
第 1 步：启动 OpenCode 并认识界面
🎯 目标：启动 OpenCode，并熟悉它的四个主要界面区域。
📝 操作：
在项目目录下，直接输入命令启动：
$ opencode启动后，你将看到一个类似下面的终端界面。我们把它分为四个核心区域来认识：
┌─────────────────────────────────────────────────┐
│ OpenCode v1.1.60 Plan 模式 │ ← 状态栏/头部
├─────────────────────────────────────────────────┤
│ │
│ AI: 你好！我是你的 AI 编程助手。 │ ← 对话区
│ 请告诉我你想做什么？ │
│ │
├─────────────────────────────────────────────────┤
│ > 随便问点什么... │ ← 输入区
└─────────────────────────────────────────────────┘🤔 为什么要认识这些区域？ 了解界面布局是高效操作的第一步。OpenCode 的界面主要分为四个部分：
| 区域 | 作用 |
|---|---|
| 状态栏/头部 | 显示版本号、当前模式（Plan/Build）、Token 用量等状态信息。 |
| 侧栏 | 显示你的会话历史列表。宽屏（>120列）时自动显示，窄屏时自动隐藏。 |
| 对话区 | 你和 AI 的聊天记录都显示在这里。 |
| 输入区 | 你在这里输入文字、命令或代码，与 AI 交流。 |
💡 提示：如果你的屏幕较窄，侧栏会自动隐藏，以给对话区腾出更多空间。
✅ 验证：屏幕上出现了类似上图的结构，并且光标在输入区 > 符号后闪烁，说明启动成功。
第 2 步：进行第一次对话
🎯 目标：验证 AI 对话功能是否正常。
📝 操作：
在输入区输入以下文字，然后按 Enter 键发送：
你好，请简单介绍一下你自己✅ 验证：你应该看到 AI 在对话区回复一段自我介绍，例如“你好！我是你的 AI 编程助手...”。这表示 AI 模型已成功连接并可以正常工作。
第 3 步：使用 @ 引用文件
🎯 目标：学会使用 @ 符号，让 AI 直接读取并分析你项目中的文件。这是 OpenCode 最核心的功能之一。
📝 操作：
假设你的项目根目录下有一个 package.json 文件。在输入区输入：
@package.json 这个文件描述了什么项目💡 提示：输入 @ 后，系统会自动弹出文件搜索补全列表。继续输入文件名的一部分（如 pack），列表会缩小范围，用方向键选择文件后按 Enter 确认。
🤔 为什么要用 @？ 当你问 AI “这个文件做了什么”时，如果不引用文件，AI 只能进行泛泛而谈。使用 @ 相当于把文件的完整内容作为上下文发送给 AI，让它能给出基于你项目代码的精准回答。
✅ 验证：AI 会回复 package.json 文件的内容摘要，并告诉你这个项目使用了哪些依赖、脚本和元信息。
⚠️ 常见错误： 如果输入 @ 后没有出现文件补全列表，说明你可能没有在项目目录下启动 OpenCode。请先 cd 到项目目录，然后重新启动。
第 4 步：使用 ! 执行命令
🎯 目标：学会使用 ! 符号，让 AI 执行系统命令并看到结果。
📝 操作：
在输入区输入以下命令，查看当前目录的文件列表：
!ls -la✅ 验证：AI 会执行 ls -la 命令，并将命令的输出结果（文件列表、权限等）显示在对话中。
你也可以让 AI 帮你做更复杂的事，比如：
帮我查看当前目录下最大的三个文件是什么AI 会理解你的意图，并自动调用相应的命令工具来执行。
⚠️ 常见错误： 如果 ! 命令报错“权限错误”，说明 OpenCode 出于安全考虑拦截了该命令。你需要确认命令是安全的（例如，不是 rm -rf / 这种危险命令），然后按 y 键允许执行。
第 5 步：使用 / 斜杠命令
🎯 目标：学会使用 / 符号调用 OpenCode 的内置功能。
📝 操作：
在输入区输入以下命令，查看帮助信息：
/help✅ 验证：AI 会显示所有可用的斜杠命令列表，例如：
| 命令 | 作用 |
|---|---|
/help | 查看帮助 |
/new | 新建会话 |
/models | 切换 AI 模型 |
/theme | 切换界面主题 |
/exit | 退出 OpenCode |
💡 提示：斜杠命令是快速执行特定操作的好方法，比如你可以用 /new 快速开启一个全新的对话，而不用退出再重进。
第 6 步：掌握常用快捷键
🎯 目标：学习最常用的快捷键，让操作更流畅。
📝 操作：
以下是最常用的几个快捷键，你可以现在就尝试一下：
| 快捷键 | 作用 |
|---|---|
Tab | 在 Plan（计划）和 Build（构建）模式间切换 |
Ctrl + C | 中断 AI 当前正在执行的操作（例如生成代码时） |
Ctrl + L | 清空对话区 |
Ctrl + X | Leader 键。这是一个“前缀键”，按下后松开，再按其他键执行特定命令 |
Ctrl + X 然后按 N | 新建一个会话（等同于 /new） |
Esc | 取消当前操作或返回上一级菜单 |
🤔 什么是 Leader 键？Ctrl + X 是一个“前缀键”，它本身不执行操作，而是告诉 OpenCode：“下一个按键是快捷键组合的一部分”。例如，Ctrl + X 后按 N 就是“新建会话”的命令。这种方式可以扩展出大量快捷键，而不会与系统或其他应用的快捷键冲突。
✅ 验证：
- 按
Tab键，观察状态栏的模式从 “Plan” 变为 “Build”（或反之）。 - 按
Ctrl + X，然后迅速按N，观察是否会创建一个新的空白对话。
进阶技巧（可选）
自定义界面
你可以通过命令面板（按 Ctrl + X 后松开，再按其他键）来调整界面显示，以获得更舒适的工作空间。
session.toggle.sidebar：切换侧栏的显示/隐藏。session.toggle.header：切换顶部状态栏的显示/隐藏。
常见问题 (FAQ)
Q1: 为什么我输入 @ 后没有文件补全列表？A: 最常见的原因是你没有在项目目录下启动 OpenCode。请确保执行 opencode 命令时，你的终端当前路径是包含代码文件的项目根目录。
Q2: 为什么快捷键 Ctrl + C 不能复制文字？A: 在 OpenCode 的终端界面中，Ctrl + C 被用于“中断当前操作”。要复制文字，你需要使用鼠标选中文本，然后：
- Mac: 按
Cmd + C - Windows/Linux: 按
Ctrl + Shift + C
Q3: 为什么 ! 命令执行后，AI 说它被拦截了？A: 这是 OpenCode 的安全机制，用于防止 AI 执行潜在的危险命令。请仔细检查你要执行的命令是否安全。如果确认安全，按 y 键允许执行即可。
总结
恭喜你完成了本教程！🎉
回顾一下我们今天学到的核心内容：
- 界面认知：掌握了 OpenCode 的四个核心区域（状态栏、侧栏、对话区、输入区）。
- 核心操作三件套：
@引用文件：让 AI 读取并分析你的项目代码。!执行命令：让 AI 运行系统命令并查看结果。/斜杠命令：快速调用 OpenCode 的内置功能。
- 快捷键：学会了
Tab、Ctrl + C、Ctrl + L和Ctrl + X（Leader 键）等常用快捷键。