OpenCode使用教程
📝 核心概念
OpenCode 不仅仅是一个代码补全工具，而是一个AI编程代理（Agent）。它能理解你的整个项目，自主规划任务，并直接执行代码修改。它的核心优势在于：
- 模型中立：不绑定任何AI厂商，支持超75家模型提供商。
- 终端优先：在终端里运行，启动快，资源占用低。
- 本地优先：代码和对话历史默认存储在本地，支持离线部署。
📦 第一步：安装与环境准备
在安装前，请确保你的电脑上有 Node.js 18 或更高版本。
1. 主要安装方式
- npm（最常用）：在终端执行
npm install -g opencode-ai。 - 一键安装脚本（适合新手）：执行
curl -fsSL https://opencode.ai/install | bash。 - 包管理器：
- macOS/Linux (Homebrew)：
brew install sst/tap/opencode - Windows (Scoop)：
scoop install opencode - Windows (WSL)：如果遇到兼容性问题，推荐在WSL环境中运行。
- Snap (Linux)：
sudo snap install opencode --classic
- macOS/Linux (Homebrew)：
2. 验证安装
安装完成后，运行 opencode --version，如果出现版本号即表示成功。
🔑 第二步：配置AI模型（最关键的一步）
OpenCode本身免费，但需要你自行配置AI模型的API Key。
方式一：环境变量（最快）
在终端中设置环境变量，例如：
- Claude (Anthropic)：
export ANTHROPIC_API_KEY="你的密钥" - OpenAI：
export OPENAI_API_KEY="你的密钥" - Google Gemini：
export GEMINI_API_KEY="你的密钥" - Windows PowerShell：使用
$env:变量名 = "值"格式
方式二：交互式登录（更直观）
在终端运行 opencode auth login，然后根据提示选择你的AI提供商（如Anthropic, OpenAI等），并输入API Key。
方式三：配置文件（最灵活）
配置文件位置：
- macOS / Linux:
~/.config/opencode/opencode.json - Windows:
C:\Users\<你的用户名>\.config\opencode\opencode.json
一个配置文件的示例：
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"deepseek": {
"api": "openai-compatible",
"name": "DeepSeek",
"options": {
"baseURL": "https://api.deepseek.com/v1"
},
"models": {
"deepseek-chat": {}
}
}
}
}
你可以通过修改 baseURL 和 models 来接入不同的模型，甚至是通过AI网关或本地模型（如Ollama）。
🚀 第三步：基本使用与核心命令
- 启动：在项目目录终端输入
opencode。 - 初始化（首次必做）：在OpenCode界面中输入
/init。它会扫描项目，生成AGENTS.md文件作为后续对话的上下文。 - 开始对话：直接在界面输入自然语言指令，比如“解释一下这个
auth.js文件的作用”。
核心斜杠命令 (/)
/init：初始化项目配置/add：将特定文件添加到上下文，供AI分析，支持通配符如*.ts/models：查看并切换当前使用的AI模型/undo：撤销AI上一次的修改操作/share：生成当前对话的公开分享链接/compact：压缩对话历史，在对话过长或跑题时使用/web：让AI联网搜索最新信息/review：让AI对代码进行审查
🛠️ 第四步：核心工作流与高级功能
1. Plan / Build 双模式
这是OpenCode提高效率的核心机制。
- Plan模式（规划）：AI只分析代码并生成修改计划，不会修改任何文件。适合进行代码审查或复杂功能的前期设计。
- Build模式（构建）：AI根据确定的计划，直接执行代码的创建和修改。
最佳实践：先让AI在Plan模式下生成计划并确认无误后，再按 Tab键 切换到Build模式执行。这种“先规划后执行”的策略能显著提升代码质量。
2. 强大的内置工具
OpenCode内置了丰富的工具，让AI能深度操作系统。你可以在项目根目录的 opencode.json 文件中通过 permission 字段精细控制每个工具的权限（allow允许, deny禁止, ask询问）。
- 文件操作类：
read（读取文件）、edit（修改文件）、write（创建新文件） - 检索与查询类：
grep（正则搜索内容）、glob（匹配文件路径） - 终端与网络类：
bash（执行终端命令）、webfetch（获取网页内容）
💡 第五步：实用技巧与场景
- 修复Bug：直接说“修复
api/users.ts里的类型错误”，OpenCode会自动定位并修改。 - 添加功能：例如“给Express项目加个用户注册接口，需要邮箱验证和密码加密”，它会生成路由、控制器等一系列文件。
- 国内用户：如果没有稳定的网络环境，推荐使用国产模型如DeepSeek或通义千问，或者使用Ollama运行本地模型。
- 模型对比：OpenCode完全开源免费，而Claude Code是闭源且需要订阅的。OpenCode支持超75家模型提供商，Claude Code仅支持自家模型。
📚 更多资源
- 官方文档：https://opencode.ai/docs
- GitHub仓库：项目已积累超17万星标
浙公网安备 33010602011771号