前言
AI 编程工具层出不穷，OpenCode 凭借开源免费、多模型兼容及项目级上下文感知等优势，成为开发者提升效率的新选择。它不仅是代码补全工具，更是能理解项目架构的 AI 编码代理，支持终端、桌面应用及 IDE 扩展等多种方式，对接多种 LLM 模型，兼顾便捷性与隐私性。
本文结合官方文档与实践经验，从安装配置、核心操作、实战技巧等维度，带你快速上手 OpenCode。
一、适用场景与核心优势
1. 适用人群
- 编程新手：自然语言描述需求即可生成代码，降低入门门槛；
- 资深开发者：处理重复编码、重构老项目、编写文档，聚焦核心业务；
- 开发团队：支持会话分享与代码审查，统一规范，提升协作效率；
- 隐私敏感用户：支持本地模型部署，代码无需上传云端。
2. 核心特性
| 特性 | 说明 |
|---|---|
| 完全开源 | 支持二次开发，无商业绑定，社区活跃 |
| 多模型兼容 | 对接 GPT-4o、Claude 3、GLM-4.7 等 75+ 模型 |
| 多端适配 | 终端 TUI、桌面应用、VSCode 扩展 |
| 项目级上下文 | 深度扫描结构，理解整体架构 |
| 双模式工作流 | Plan（规划）+Build（构建），减少逻辑偏差 |
| 轻量高效 | 低延迟，支持本地部署 |
二、环境准备与安装
OpenCode 支持 Windows、macOS、Linux 全平台。推荐通用安装脚本，也可根据环境选择专属方式。
前置条件
- 终端要求：推荐 WezTerm、Alacritty 等现代终端，Windows 用户优先使用 WSL；
- 密钥准备：需准备 LLM 提供商 API 密钥，新手可先用 OpenCode Zen。
1. 通用安装脚本
打开终端执行以下命令：
curl -fsSL https://opencode.ai/install | bash
2. 各平台专属方式
Node.js 生态安装
适合已配置 Node.js 环境的开发者：
# npm
npm install -g opencode-ai
# bun
bun install -g opencode-ai
# pnpm
pnpm install -g opencode-ai
# yarn
yarn global add opencode-ai
macOS/Linux：Homebrew 安装
brew install anomalyco/tap/opencode
Arch Linux 安装
sudo pacman -S opencode
# AUR 最新版
paru -S opencode-bin
Windows 安装（非 WSL）
# Chocolatey
choco install opencode
# Scoop
scoop install opencode
# NPM
npm install -g opencode-ai
注意：Windows 上通过 Bun 安装的支持目前仍在开发中。
Docker 安装
docker run -it --rm ghcr.io/anomalyco/opencode
3. 验证安装
输入以下命令，显示版本号即成功：
opencode --version
三、基础配置：API 密钥与模型对接
核心配置是对接 LLM 模型的 API 密钥。
1. 新手配置：OpenCode Zen
- 选择
opencode选项，终端提示前往授权地址：opencode.ai/auth； - 浏览器登录并添加账单信息，复制生成的 API 密钥；
- 回到终端粘贴密钥并按回车。
在 TUI 中输入连接命令：
/connect
启动界面：
opencode
2. 进阶配置：自定义第三方模型
如需使用 GPT-4o、Claude 3 等，在 /connect 后选择对应提供商，输入官方 API 密钥即可。
小技巧：建议将 API 密钥存入项目本地配置，避免全局泄露。
四、项目初始化
配置完成后，需对项目进行初始化，让 OpenCode 理解项目结构。
- 输入初始化命令：
/init
- 启动 OpenCode 并导航至项目根目录：
cd /path/to/your/project
重要提示：务必将生成的
AGENTS.md提交到 Git 仓库，便于团队协作或后续复用。
五、核心功能实战：Plan+Build 双模式
OpenCode 的核心是 Plan（规划）+Build（构建）双工作流。先由 AI 出方案，再执行编码，显著提升一次性通过率。
模式切换
- 按 Tab 键 切换 Plan 和 Build 模式，右下角显示指示器；
- Plan 模式：只读分析，生成实施计划；
- Build 模式：执行编码，自动修改文件。
实战 1：新增功能（复杂场景）
示例需求：实现用户删除笔记后标记为软删除，新增回收站页面。
- 切换到 Plan 模式，确认右下角显示 Plan；
- 描述需求：
当用户删除笔记时，在数据库中将该笔记标记为 deleted 状态（软删除）；新增一个回收站页面，展示所有标记为 deleted 的笔记；在回收站页面，用户可以点击恢复按钮将笔记恢复为正常状态，也可以点击永久删除按钮彻底删除笔记。
- 切换到 Build 模式，执行指令：
按照计划执行，完成所有修改。
小技巧：可直接将设计图拖放到终端，OpenCode 会自动识别图片内容作为参考。
实战 2：直接修改（简单场景）
适合单行修改或轻量操作。直接在 Build 模式下输入指令，使用 @ 符号引用文件路径：
给 @packages/functions/src/settings.ts 中的/settings 路由添加身份验证，参考 @packages/functions/src/notes.ts 中/notes 路由的鉴权逻辑。
实战 3：代码解释与撤销重做
遇到陌生代码库，可让 OpenCode 讲解逻辑：
解释 @packages/functions/src/api/index.ts 中的认证逻辑，说明每一步的作用。
若生成代码不符合预期，可使用命令回滚：
- 撤销：
/undo - 重做：
/redo
实战 4：会话分享
输入 /share 生成对话链接，同事打开即可查看完整的需求分析与代码修改过程。
六、高频实用命令
Slash 斜杠命令是核心操作方式，无需鼠标：
| 命令 | 核心功能 | 适用场景 |
|---|---|---|
/connect | 配置 LLM 模型 API 密钥 | 首次使用 / 切换模型 |
/init | 初始化项目，生成 AGENTS.md | 新项目接入 |
/undo | 撤销上一步修改 | AI 代码不符合预期 |
/redo | 重做最近一次撤销 | 误操作撤销 |
/share | 生成对话链接 | 团队协作 |
/add | 添加指定文件到上下文 | 聚焦特定文件 |
/compact | 压缩上下文历史 | Token 接近上限 |
/review | 代码审查 | 提交前查错 |
/web | 联网搜索资料 | 查询外部信息 |
七、高级玩法：定制化
1. 自定义模型参数
在配置面板调整参数以平衡效果与速度：
- 温度参数（Temperature）：0-1 区间，生产环境推荐 0.2-0.4；
- 最大生成长度（Max Tokens）：前端组件建议设 2048；
- 上下文扫描范围：大型项目建议选「当前文件夹」。
2. 自定义 Agent 代理
创建自定义 Agent 实现专属功能，如安全检测专家。
- 在项目根目录创建
.opencode/prompts/文件夹； - 创建
security.md写入系统提示词：
你是一名资深网络安全专家，专门检查代码中的 SQL 注入、XSS 漏洞等安全问题，发现问题后给出详细的修复方案，不直接修改代码。
- 在终端输入
/run security调用。
八、VSCode 集成
习惯 VSCode 的开发者可安装官方插件实现无缝操作：
- 打开扩展市场，搜索 OpenCode 并安装；
- 重启 VSCode，底部终端启动使用；
- 可在
keybindings.json中绑定快捷键（如Ctrl+'）快速唤起。
优势：可将左侧文件树的文件拖放到终端，OpenCode 会自动识别并添加到上下文。
九、避坑指南
- Windows 卡顿：优先使用 WSL，原生终端部分功能支持有限；
- API 密钥失败：检查密钥有效性及额度，国内用户注意网络环境；
- 无法理解项目：确认已执行
/init且AGENTS.md存在； - 代码规范不符：在
AGENTS.md中补充编码规范； - Token 消耗快：使用
/compact压缩上下文，简单任务用轻量模型。
十、总结
OpenCode 作为一款开源 AI 编码代理，旨在解放程序员双手，聚焦核心业务。掌握 Plan+Build 双模式和 Slash 命令体系，就能应对绝大多数开发工作。后续随着社区完善，功能将更加强大。参考官方文档获取最新功能和更新内容。
