OpenCode使用系列课程连载（1）——入门基础篇（极简版）
Excerpt
OpenCode使用系列课程连载（1）——入门基础篇（极简版）哈喽大家好～ 本期咱们不讲复杂理论，只讲OpenCode日常能用得上的基础操作，参考官方教程逻辑，一步步教大家轻松上手，新手也能快速搞定，不用怕看不懂！话不多说，直接上干货～
一、初识OpenCode：它能帮你省多少事
不用记复杂定义！简单说，OpenCode就是一款开源AI编程小助手，能帮你写代码、改bug、分析项目，支持多种AI模型，免费能用，还能本地运行，不用怕隐私泄露，日常编程能省不少事。这里给新手宝子们补充下，OpenCode和热门的Claude Code核心差异很明显，用表格对比更直观，一眼就能看懂，方便大家选对工具：
| 对比维度 | OpenCode | Claude Code |
|---|---|---|
| 开源与成本 | 完全开源免费（MIT许可证），无订阅费，仅需支付所用模型API费用 | 商业闭源工具，有免费版（有限次数），专业版、团队版需付费订阅 |
| 模型支持 | 不绑定任何模型，支持75+种（含Claude、GPT、本地模型），输/models可切换 | 仅支持自身系列模型（如Claude Opus 4.5），无法切换外部模型 |
| 隐私与部署 | 支持本地部署，代码、数据存本地，可离线使用，隐私性强 | 以云端服务为主，数据在云端处理，适合企业合规需求，隐私可控性较弱 |
| 操作门槛 | 主打终端操作，适合命令行用户，新手跟着教程可快速上手 | 以Web界面为主，终端版偏辅助，无需复杂配置，上手更省心但灵活性不足 |
简单总结：Claude Code像“成品旗舰机”，到手即用、稳定高效；OpenCode像“开源组 装机”，自由灵活、隐私可控，新手想免费试用、追求灵活度，选OpenCode更合适。
二、快速安装：Windows/Linux两步搞定
优先推荐包管理器安装（更便捷、不易出错），新手直接跟着输命令就行，遇到问题看后面的简单解决办法～
2.1 Windows系统（首选Scoop包管理器）
仅保留Scoop包管理器安装方式，步骤简单、不易出错，全程在PowerShell执行即可：
1. 若未安装Scoop，先执行安装命令（直接复制）：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser;
2. 添加存储桶并安装OpenCode（多行命令，直接复制）：
scoop bucket add extras;
2.2 Linux系统
Linux系统最推荐curl一键安装，无需额外安装包管理器，一行命令直达，适配所有Linux发行版，新手首选、高效便捷，官方也主推此方式：
2.2.1 curl一键安装（首选，最推荐）
打开终端，直接复制执行以下命令，一键完成安装，自动适配系统架构、配置环境变量，无需手动处理依赖：
curl -fsSL https://opencode.ai/install | bash
2.2.2 npm包管理器（备用）
适合已安装Node.js（需v18.0.0及以上版本）的用户，npm随Node.js自动安装，安装步骤简单，适配所有Linux发行版：
1. 验证Node.js和npm：输node -v和npm -v，能显示版本号即正常；
2. 全局安装OpenCode：
npm install -g opencode-ai
3. 若遇权限问题，前置sudo：
sudo npm install -g opencode-ai
2.3 安装验证与常见问题
验证：输opencode --version，能显示版本号，就是装成功了。
常见问题（只讲最常遇到的，好记）：
1. 权限不够：Linux/Mac前置sudo（比如）：
sudo npm install -g opencode-ai
Windows用管理员身份打开PowerShell；
2. 脚本不能执行（Windows）：管理员打开PowerShell，输：
set-ExecutionPolicy RemoteSigned
选Y就行；
3. 包管理器未安装：按照对应方式先安装包管理器，再执行OpenCode安装命令。
三、核心入门：进入界面+认识操作
这步最关键，学会就能开始用。
3.1 两种启动方式（重点记常用款）
1. 普通启动：打开终端，直接输：
opencode
就能打开交互式界面；
2. 项目启动（最常用）：先输：
cd 你的项目目录
（比如）：
cd ~/golang-demo
再输opencode，自动关联当前项目。
3.2 界面3个核心区域
打开后就3个部分，不用复杂配置，这里用plaintext字符示意图直观展示，再记清功能即可：
┌─────────────────────────────────────────────────────────────┐
│ 顶部状态栏：当前模型(GPT-3.5) | 会话ID: abc-123 | Build模式 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 中间交互区（核心区） │
│ > 请输入指令或命令（例如：@ src/test.go /init /connect） │
│ AI: 已加载 src/test.go，分析结果如下：... │
│ ...（代码块/建议/错误提示等多行输出） │
│ │
├─────────────────────────────────────────────────────────────┤
│ 底部操作栏：Tab=切换模式 | Ctrl+X U=undo | Ctrl+X R=redo | /h 帮助 │
└─────────────────────────────────────────────────────────────┘
1. 顶部状态栏：显示当前AI模型、会话状态、工作模式（Build/Plan），无需额外配置；
2. 中间交互区：核心操作区，输入指令、查看AI回复、加载/编辑文件、执行命令均在此完成；
3. 底部操作栏：常驻显示高频快捷键与命令入口，忘记操作时可快速查看，提升操作效率。
3.3 4个必记常用操作
1. @：输@ 文件名（比如@ src/test.go），加载目标文件；
2. 执行命令：输! 命令（比如查看目录：! ls；运行代码：! go run test.go）；
3. 项目初始化：输/init（重点！在OpenCode界面直接使用，自动分析项目并生成AGENTS.md文件）；
4. 退出工具：输/exit，快速退出OpenCode。
3.4 补充操作：undo/redo（撤销/重做）
新手实操中难免误操作，undo（撤销）和redo（重做）是必备补救技巧，操作简单，记住命令和快捷键就能快速纠错，适配OpenCode所有操作场景：
1. 撤销操作（undo）：
- 命令方式：在OpenCode界面内直接输：
/undo
- 快捷键方式：先按ctrl+x（Leader键），再按u（即 ctrl+x u）；
- 功能说明：撤销对话中最后一条操作，包括用户输入的指令、AI的响应，以及操作过程中产生的文件更改，相当于“回到上一步”。
2. 重做操作（redo）：
- 命令方式：在OpenCode界面内直接输：
/redo
- 快捷键方式：先按ctrl+x（Leader键），再按r（即 ctrl+x r）；
- 功能说明：仅在使用/undo撤销操作后可用，能恢复被撤销的操作，若未执行过撤销，输入该命令无效。
3. 新手提醒：
- 撤销/重做仅对当前会话有效，退出OpenCode后再重新进入，无法恢复之前的撤销/重做记录；
- 若操作涉及文件更改，撤销时会同步恢复文件至操作前状态，内部通过Git管理文件更改，无需额外操作；
- 快捷键需先按Leader键ctrl+x，松开后再按对应字母，不要同时按下，避免操作失效。
四、基础功能：模式切换+模型连接
4.1 模式切换：Tab键一键切换
就2种模式，不用记复杂原理，重点结合新手日常编程场景，记准什么时候用、怎么用，避免用错场景导致误操作，切换时只需按Tab键一键切换，非常便捷：
1. Build模式（默认模式）：核心用于“动手操作”，是日常开发最常用的模式，只要涉及代码的编写、修改、保存，都用它。
具体使用场景：比如让AI帮你写一段Golang代码（如之前实操中的加法函数）、修改已有的代码文件（比如优化src/add.go的逻辑）、删除文件中的冗余代码、保存AI生成的代码到本地，这些需要“改变文件内容”的操作，都必须在Build模式下进行。
它相当于“可编辑模式”，支持所有写入、修改类操作，打开OpenCode后默认进入该模式，新手日常开发全程用它基本没问题。
2. Plan模式：核心用于“查看分析”，仅能浏览、分析代码，无法对文件做任何修改，适合不想误改文件的场景，相当于“只读模式”。
具体使用场景：比如刚接手一个陌生的Golang项目，想让AI分析项目结构、查看某个代码文件（如src/main.go）的逻辑但不想不小心改动代码；或者检查AI生成的代码是否符合规范，只看不动；又或者担心误操作删除、修改重要文件，此时切换到Plan模式，就能放心查看、让AI分析。
切换到Plan模式后，哪怕不小心输入了修改指令，也不会对文件造成任何影响，能有效避免误操作。
补充提醒：两种模式切换无门槛，按一下Tab键即可切换；顶部状态栏会实时显示当前模式（Build/Plan），新手可以随时查看，避免用错模式。
4.2 模型连接与切换
4.2.1 新手入门：连接模型（1种就够）
1. 打开OpenCode后，输：
/connect 模型名称
（比如）：
/connect GPT-3.5
2. 跟着提示输API密钥（网上搜“OpenAI API密钥获取”，新手也能快速找到），验证通过即可。
4.2.2 模型切换：简单便捷
无需复杂操作，在OpenCode界面内直接输：
/models
即可调出模型列表，用上下键选择目标模型，按Enter就能完成切换，无需重新连接模型。
五、项目与会话：简单管理不丢工
5.1 会话管理：2个命令保住成果
不用记复杂操作，重点保成果：
1. 保存会话：输：
/save
自动保存当前操作，下次可恢复；
2. 恢复会话：进入项目后，输：
opencode --continue
直接回到上次操作。
5.2 项目初始化：两种方式任选
5.2.1 界面内初始化（推荐）
1. 进入项目目录：
cd 你想放项目的目录
（比如）：
cd ~/projects
2. 打开OpenCode：
opencode
3. 直接输：
/init
工具会自动分析项目，生成AGENTS.md文件（记录项目结构和编码规范），完成初始化；
5.2.2 终端初始化（备用）
1. 输：
cd 你想放项目的目录
（比如）：
cd ~/projects
2. 输：
opencode init 项目名
（比如）：
opencode init golang-demo
按Enter用默认配置，自动生成项目结构（适配Golang开发）。
六、新手实操：Golang版一步到位
跟着走一遍Golang项目实操，重点演示界面内/init命令使用，不用自己想命令，新手也能轻松搞定：
1. 进入项目：
cd ~/golang-demo
（换成你的Golang项目目录）；
2. 打开OpenCode：
opencode
3. 界面内初始化项目：
/init
（自动生成AGENTS.md，帮助AI理解项目结构）；
4. 连接模型：
/connect GPT-3.5
（跟着输API密钥）；
5. 让AI写代码：在交互区输“写一个简单的加法函数，保存到src/add.go，符合Golang编码规范”；
6. 查看代码：
@ src/add.go
7. 切换模型（可选）：输：
/models
在弹出的列表中选择其他模型（如Llama 3），按Enter完成切换；
8. 运行代码：
! go run src/add.go
9. 保存会话：
/save
10. 退出：
/exit
七、新手必看小提醒
就5条，好记不啰嗦，避坑更高效：
1. 重点记：进入OpenCode界面后，直接输/init就能完成项目初始化，不用在终端额外操作；
2. /init命令会生成AGENTS.md文件，建议提交到版本控制，帮助AI快速理解项目；
3. 输命令时， 注意路径别输错，复制路径粘贴更稳妥；
4. 每次操作完记得输/save，避免丢工作；
5. 切换模型直接输/models，调出列表选择即可，不用记复杂命令。
八、核心命令汇总表（新手必备）
整理全文高频核心命令，按类别划分，方便快速查找、复制使用，新手可直接对照操作：
| 命令类别 | 具体命令 | 用途说明（新手重点） |
|---|---|---|
| Linux安装 | `curl -fsSL https://opencode.ai/install | bash 、npm install -g opencode-a` |
| 启动方式 | opencode 、cd 项目目录 && opencode | 1. 普通启动，直接打开交互式界面；2. 项目启动，关联当前项目（最常用） |
| 核心操作 | @ 文件名、 ! 命令 、/init 、/exit 、/undo 、/redo | 1. 加载目标文件；2. 执行终端命令；3. 项目初始化（重点）；4. 退出工具；5. 撤销上一步；6. 重做被撤销操作 |
| 模型操作 | /connect 模型名称 、/models | 1. 连接目标AI模型（如/connect GPT-3.5）；2. 切换模型，调出列表选择即可 |
| 会话/项目管理 | /save 、opencode --continue、 opencode init 项目名 | 1. 保存当前会话；2. 恢复上次会话；3. 终端初始化项目（备用） |
| 验证/问题解决 | opencode --version 、set-ExecutionPolicy RemoteSigned | 1. 验证OpenCode是否安装成功；2. Windows解决脚本无法执行问题 |
