本节课我们将一起探讨如何上手OpenCode，主要分为四个递进的部分，建议按顺序学习：

💡 一句话理解：@ 引用文件、! 执行命令、/ 调用功能——掌握这三板斧，你就能驾驭 。

一、快速上手

这一部分帮你在 15 分钟内从零开始使用 OpenCode。

1.1 认识界面

在项目目录下运行 opencode 启动后，你会看到一个终端用户界面（TUI）。这个界面由 SST 团队精心打造，分为三个功能区域：

┌─────────────────────────────────────────────────────────────────┐
│  OpenCode v1.x.x                              Build 模式  ⚡     │  ← ① 状态栏
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  You: @src/main.ts 这个文件是做什么的？                           │
│                                                                 │
│  AI: 这是项目的入口文件，主要做了以下几件事...                      │  ← ② 对话区
│      1. 初始化配置                                               │
│      2. 启动 HTTP 服务器                                         │
│      ...                                                        │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  > 在这里输入你的消息...                                          │  ← ③ 输入区
└─────────────────────────────────────────────────────────────────┘

三个区域的作用

为什么要在项目目录下启动？

这是一个关键点：OpenCode 会以启动时的目录作为工作根目录。

• 在项目目录启动：@ 能引用项目文件，AI 能理解项目结构
• 在随便一个目录启动：AI 看不到你的代码，只能泛泛而谈

# ✅ 正确做法 cd ~/my-project
opencode

# ❌ 错误做法 cd ~
opencode  # AI 能看到你整个 home 目录，但找不到具体项目 

💡 最佳实践：养成习惯，先 cd 到项目目录，再启动 OpenCode。

1.2 核心三板斧：@、!、/

这三个符号是 OpenCode 的灵魂。记住它们，你就掌握了 80% 的日常操作。

@ 引用文件——让 AI 看到你的代码

@ 是 OpenCode 最强大的功能。它让 AI 能够直接读取你的项目文件，而不是让你手动复制粘贴代码。

基础用法：

@package.json 这个项目是做什么的？

当你输入 @ 时，OpenCode 会：

1. 识别出你要引用文件
2. 读取文件内容
3. 把内容作为上下文发送给 AI

文件选择器：

输入 @ 后按 Tab 键，会弹出一个模糊搜索选择器：

┌─────────────────────────────────┐
│ 🔍 输入文件名搜索...             │
├─────────────────────────────────┤
│ > src/main.ts                   │
│   src/utils/helper.ts           │
│   src/components/Button.tsx     │
│   package.json                  │
│   tsconfig.json                 │
└─────────────────────────────────┘

用方向键选择，Enter 确认。支持模糊匹配，输入 btn 就能找到 Button.tsx。

进阶技巧：

⚠️ 注意：引用超大文件（几千行）会消耗大量 Token。建议用行号引用只取需要的部分。

! 执行命令——让 AI 看到命令输出

! 让你可以在对话中直接执行 shell 命令，命令输出会自动加入 AI 的上下文。

基础用法：

!git status 

执行后，AI 会看到类似这样的输出：

On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  modified:   src/main.ts
  modified:   src/utils.ts

现在 AI 知道了你修改了哪些文件，可以给出更精准的建议。

实用场景：

💡 更自然的方式：你也可以直接用自然语言让 AI 执行命令：

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

AI 会自动调用 bash 工具执行 ls 命令。! 是给你直接控制用的，自然语言是让 AI 自主决定。

⚠️ 安全机制：

OpenCode 会拦截可能有危险的命令（如 rm -rf）。当检测到危险命令时：

⚠️ 该命令可能有风险：rm -rf node_modules
确认执行？[y/N]

按 y 确认，按 n 或直接回车取消。这是为了防止 AI 误操作删除重要文件。

/ 斜杠命令——OpenCode 的内置功能

/ 开头的命令是 OpenCode 的内置功能入口，类似于 Slack 或 Discord 的斜杠命令。

使用方式：

/help 

输入 / 后会弹出命令列表，可以用方向键选择或继续输入筛选。

常用命令一览：

别名支持：

很多命令有别名，用哪个都行：

1.3 两种工作模式：Plan 与 Build

OpenCode 有两种内置的工作模式，代表两种不同的工作哲学。理解它们是高效使用 OpenCode 的关键。

模式对比

切换方式

按 Tab 键即可在两种模式间切换。右下角状态栏会显示当前模式。

设计哲学

这种设计非常聪明，它解决了一个常见问题：AI 还没理解清楚就开始乱改代码。

推荐工作流：

1. 切换到 Plan 模式（按 Tab）
2. 让 AI 分析代码：分析一下这个模块的架构
3. 讨论方案：我想加个缓存功能，怎么实现？
4. 满意后切换到 Build 模式（按 Tab）
5. 让 AI 执行：按我们讨论的方案实现

💡 为什么叫 "Plan" 和 "Build"？

这借鉴了软件工程的经典思想：先规划，再执行。Plan 模式让你可以放心地让 AI 探索整个代码库，因为它不会意外修改任何文件。当你对方案满意后，再切到 Build 模式执行。

进阶：@general 子代理

除了 Plan 和 Build，OpenCode 还有一个通用子代理，可以用 @general 调用：

@general 找出所有处理用户认证的 API 端点

@general 是一个多面手，适合复杂的多步骤任务。它有完整的工具访问权限，可以并行执行多个子任务。

1.4 第一次使用：跟我做

现在让我们把上面学的串起来，完成一次完整的使用流程。

步骤 1：启动 OpenCode

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

步骤 2：让 AI 认识你的项目

@package.json @README.md 介绍一下这个项目

AI 会读取这两个文件，然后给出项目概览。

步骤 3：用 Plan 模式探索

按 Tab 切换到 Plan 模式（看右下角确认）。

分析一下 src 目录的代码结构，告诉我主要模块有哪些

因为是 Plan 模式，AI 只会分析和报告，不会修改任何文件。

步骤 4：切换到 Build 模式执行任务

按 Tab 切换回 Build 模式。

帮我在 src/utils 下创建一个 logger.ts，实现一个简单的日志工具

AI 会创建文件并写入代码。

步骤 5：验证并撤销（可选）

如果对结果不满意：

/undo 

文件会被恢复到 AI 修改前的状态。

二、效率进阶

掌握了基础操作后，这一部分帮你提升效率，解决日常使用中的痛点。

2.1 复制的正确姿势

🚨 这是新手最常见的困惑：为什么按 Ctrl+C 程序退出了？！

为什么 Ctrl+C 不是复制？

这是终端世界和图形界面世界的文化冲突。

在 1970 年代的 Unix 系统中，Ctrl+C 被定义为中断信号（SIGINT），用来终止正在运行的程序。这个约定沿用至今，几乎所有终端程序都遵守。

OpenCode 中 Ctrl+C 的实际行为：

这其实很合理：和终端的行为保持一致，程序员会很熟悉。但对于习惯图形界面的用户，确实需要适应。

四种复制方式

OpenCode 提供了多种复制方式，适应不同场景：

方式一：鼠标拖选（最直觉）

操作：用鼠标拖选文字 → 松开 → 完成

没错，就这么简单。你不需要按任何键。在松开鼠标的一瞬间，OpenCode 会自动把选中的内容复制到剪贴板，并显示 Copied to clipboard 提示。

这是 OpenCode 专门为现代用户设计的"隐藏技能"，Mac 和 Windows 通用。

⚠️ 已知问题：在某些终端（如 Windows Terminal 的特定版本）可能不工作。如果遇到问题，用下面的保底方式。

方式二：键盘快捷键（最快）

操作：Ctrl+X → 松开 → Y

这会复制 AI 最后一条完整回复到剪贴板。当你只想要 AI 刚说的那段话（比如一大段代码），这比鼠标拖选快得多。

记忆口诀：Y = Yank，这是 Vim 编辑器中"复制"的术语。

方式三：命令复制（最全）

操作：输入 /copy 回车

这会把整个对话历史（你说的话 + AI 说的话）都复制到剪贴板。适合你想把对话分享给同事或保存到文档的场景。

方式四：系统原生选择（保底）

如果上面的方法都不工作，可以绕过 OpenCode，直接使用终端的原生选择功能：

这种方式适用于：

• OpenCode 卡死没反应时
• 通过 SSH 远程使用时
• 需要精确复制报错信息时

退出程序的正确姿势

既然 Ctrl+C 有可能退出程序，那正确的退出方式是什么？

💀 Windows 用户注意：用 Ctrl+C 强制退出可能导致鼠标乱码问题。这是因为 OpenCode 开启了鼠标监听模式，强制退出时没来得及关闭，终端会把鼠标坐标当成文字显示。

解决方法：关闭终端窗口重新打开。预防方法：用 Ctrl+D 退出。

2.2 会话管理

为什么需要多个会话？

想象一下这个场景：

你正在修复一个 bug，和 AI 讨论了很久，上下文里全是关于这个 bug 的信息。突然老板让你临时处理另一个紧急任务。你直接在同一个会话里开始新任务，AI 会把两件事的上下文混在一起，给出莫名其妙的回答。

多会话的好处：

核心操作

新建会话

/new 

或按 Ctrl+X → N（先按 Ctrl+X，松开，再按 N）。

💡 命名技巧：

/new 重构用户登录模块

带上任务名称，日后在会话列表中一眼就能找到。

切换会话

/sessions 

或按 Ctrl+X → L。会弹出会话列表：

┌─────────────────────────────────────────────┐
│ 会话列表                                     │
├─────────────────────────────────────────────┤
│ > 重构用户登录模块      (3 条消息)  10分钟前  │
│   修复支付接口 bug      (15 条消息) 1小时前   │
│   分析项目架构          (8 条消息)  昨天      │
└─────────────────────────────────────────────┘

用 ↑ ↓ 选择，Enter 切换。

撤销操作（重要！）

/undo 

这是一个救命功能。当 AI 改错了代码，/undo 可以恢复到修改前的状态。

工作原理：

/undo 会同时：

1. 移除对话中的最后一轮（你的消息 + AI 的回复）
2. 恢复 AI 修改的所有文件

⚠️ 依赖 Git：/undo 通过 Git 来追踪文件变化。如果项目不是 Git 仓库，只能撤销对话，不能恢复文件。

初始化 Git 仓库：

git init
git add .
git commit -m "init" 

这样 /undo 就能完整工作了。

压缩对话

/compact 

当对话变得很长时，会：

1. 消耗大量 Token（费钱）
2. AI 可能开始遗忘早期的上下文

/compact 会让 AI 总结当前对话的要点，然后清理掉详细的历史消息，只保留摘要。

什么时候用 /compact vs /new？

导出对话

/export 

将对话导出为 Markdown 文件。适合：

• 保存重要的技术讨论
• 分享给同事
• 存档备查

2.3 快捷键系统

OpenCode 有 60+ 快捷键，但日常只需掌握核心的 15 个。

Leader 键机制（必须理解）

这是 OpenCode 快捷键的核心机制。如果你只记住一件事，记住这个。

什么是 Leader 键？

Leader 键是一个前缀键，默认是 Ctrl+X。它不直接触发功能，而是开启一个"等待窗口"，等你按下后续的字母键。

操作方式（三步法）：

┌─────────────────────────────────────────────────────────┐
│                                                         │
│   第 1 步         第 2 步           第 3 步              │
│   按下 Ctrl+X  →  松开所有键   →    按下字母键           │
│                                                         │
│   ⚠️ 关键：第 2 步必须松开！不是同时按住三个键！         │
│                                                         │
└─────────────────────────────────────────────────────────┘

举例：

为什么这样设计？

终端程序的快捷键空间很有限，很多组合键被终端本身或操作系统占用了。Leader 键机制让 OpenCode 可以支持大量快捷键，而不会和其他程序冲突。

这个设计借鉴自 Vim 编辑器和 Emacs 编辑器，程序员会很熟悉。

💡 练习技巧：刚开始可以故意放慢：按 Ctrl+X 后，心里默数"1"，再按字母键。熟练后自然会快。

第一梯队：每天必用

这 8 个快捷键覆盖了 90% 的日常操作：

关于换行：

写多行提示词时，需要换行而不是发送。有几种方式：

• Ctrl+J（推荐，最通用）
• Shift+Enter
• Ctrl+Enter
• Alt+Enter

如果 Shift+Enter 不工作（直接发送了），说明你的终端不发送修饰键，改用 Ctrl+J。

关于 Ctrl+C：

这和终端的标准行为一致。

第二梯队：效率提升

第三梯队：程序员福利

如果你用过终端或 Emacs，这些 Readline 风格的快捷键你会很熟悉：

OpenCode 完全兼容 Readline，你在终端中的肌肉记忆可以直接迁移。

快捷键速记口诀

回车发送，Ctrl+J 换行
上箭头翻历史（输入框要空）
新建 N，列表 L，撤销 U，模型 M，复制 Y Escape 中断，Tab 切模式
Ctrl+C 不是复制！

三、个性定制

这一部分帮你配置 OpenCode，让 AI 永久记住你的偏好。

3.1 规则文件：让 AI 永久记住你的偏好

厌倦了每次都说"用中文回复"？创建一个规则文件，一劳永逸。

什么是规则文件？

规则文件是一个 Markdown 文件，里面写着你希望 AI 遵守的规则。OpenCode 会在每次对话时自动读取这个文件，把内容加到系统提示词里。

好处：

• 不用每次对话都重复相同的要求
• 规则可以很详细，用 Markdown 格式组织
• 修改后立即生效，不需要重启

最快的创建方式

直接在 OpenCode 里让 AI 帮你创建：

帮我创建 ~/.config/opencode/AGENTS.md，内容是：
- 始终使用简体中文回复
- 代码注释也用中文
- 不要客套话，直接给方案

搞定。 下一条消息 AI 就会遵守这些规则。

两个作用域

两者会合并生效。如果有冲突，项目规则会覆盖全局规则。

热加载

规则文件是热加载的。修改后不需要重启 OpenCode，也不需要新建会话，下一条消息就会遵守新规则。

这意味着你可以让 AI 帮你修改规则文件，然后立即验证效果。

懒人方案：/init

如果你不知道该写什么规则，让 AI 分析项目自动生成：

/init 

AI 会分析项目的技术栈、代码风格、构建命令等，自动生成一份 AGENTS.md。

实用规则模板

## 沟通风格 
- 始终使用简体中文回复
- 直接输出方案，禁止客套话（"好的"、"我明白了"等）
- 不确定时先问，不要瞎猜

## 代码规范 
- 使用 2 空格缩进
- 变量名用 camelCase
- 函数名用动词开头（如 getUserById）
- 禁止使用 any 类型

## 工作习惯 
- 改代码前先阅读相关文件
- 每次只做最小必要的修改
- 修改后自行运行测试验证

关于 AGENTS.md vs CLAUDE.md

OpenCode 同时支持两种文件名：

• AGENTS.md — OpenCode 的标准名称，也是一个开放标准，被多种 AI 工具支持
• CLAUDE.md — 兼容 Claude Code

如果两个文件都存在，只会读取 AGENTS.md。建议统一使用 AGENTS.md。

3.2 环境管理：模型、统计、凭证

查看可用模型

opencode models

列出所有已配置的模型。输出格式是 提供商/模型名：

anthropic/claude-sonnet-4 openai/gpt-4o
zhipuai/glm-4 ollama/deepseek-r1:7b

只看某个厂商的模型：

opencode models anthropic

刷新模型缓存：

如果你刚添加了新的 API Key，或者下载了新的 Ollama 模型，需要刷新缓存：

opencode models --refresh

设为默认模型：

编辑 ~/.config/opencode/opencode.json：

{
  "model": "anthropic/claude-sonnet-4" }

查看使用统计

opencode stats

显示你的 Token 消耗和费用统计：

┌─────────────────────────────────────────────────┐
│                   OVERVIEW                      │
├─────────────────────────────────────────────────┤
│ Sessions                                    948 │
│ Messages                                 30,575 │
│ Days                                        29 │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│                 COST & TOKENS                   │
├─────────────────────────────────────────────────┤
│ Total Cost                             $1232.56 │
│ Input                                    530.6M │
│ Output                                     9.9M │
│ Cache Read                               703.0M │
└─────────────────────────────────────────────────┘

关键指标：

只看最近几天：

opencode stats --days 7    # 最近 7 天 opencode stats --days 1    # 今天 

看哪个模型最烧钱：

opencode stats --models 5  # 消耗最高的 5 个模型 

只看当前项目（需要在 Git 仓库中）：

opencode stats --project "" 

管理登录凭证

查看已登录的账号：

opencode auth list

退出某个账号：

opencode auth logout 

然后选择要退出的提供商。

⚠️ 安全提示：凭证以明文存储在 ~/.local/share/opencode/auth.json，不要把这个文件上传到公开仓库。

四、速查手册

核心操作速查

斜杠命令速查

快捷键速查

基础操作

Leader 键组合（Ctrl+X → 字母）

常见问题排错

上手检查清单

完成以下操作，你就真正掌握了 OpenCode：

•  在项目目录启动 OpenCode
•  用 @文件名 让 AI 分析一个文件
•  用 !ls 查看目录
•  按 Tab 切换 Plan/Build 模式
•  用 /new 新建会话
•  用 Ctrl+X → L 切换回旧会话
•  用 Ctrl+X → U 撤销一次操作
•  创建 ~/.config/opencode/AGENTS.md 规则文件
•  用鼠标拖选复制一段文字

你现在已经掌握了 OpenCode 日常使用的完整知识体系。从界面认知到核心操作，从效率技巧到个性配置，再到速查手册——这些知识足以让你在日常开发中得心应手。去写代码吧，让 AI 成为你的得力助手。