OpenCode for VS Code 操作手册
1. 简介与核心优势
OpenCode 是一款开源、免费且支持多模型的 AI 编程助手，旨在为开发者提供高效、可控的编码体验 。
核心优势：
开源免费：代码完全开源，无隐藏费用 。
多模型支持：支持 75+ 种 AI 模型，包括 Claude、GPT、Gemini、DeepSeek 以及本地模型（如 Ollama） 。
深度 IDE 集成：专为 VS Code 及 Cursor 等分支设计，通过快捷键和终端实现无缝操作 。
上下文感知：能够自动读取当前文件、选中代码甚至整个项目结构，提供精准的代码建议 。
双模式工作流：通过 Plan（规划）和 Build（构建）模式区分代码分析与实际修改，确保操作安全 。
2. 安装与配置
2.1 安装 OpenCode CLI
OpenCode 的核心是一个命令行工具，你需要先安装它。
前置条件：确保你的系统已安装 Node.js 。
通过 npm 安装（推荐）：
bash
npm install -g opencode-ai
macOS / Linux 通过脚本安装：
bash
curl -fsSL https://opencode.ai/install | bash
验证安装：
bash
opencode --version
2.2 在 VS Code 中集成 OpenCode
OpenCode 的 VS Code 集成采用“自动发现”机制，无需手动下载插件，直接在 VS Code 终端操作即可 。
打开你的项目文件夹。
按下 Ctrl+` （Mac：Cmd+）打开 VS Code 的集成终端 。
在终端中输入以下命令启动 OpenCode：
bash
opencode
首次运行：系统会自动检测到你在 VS Code 集成终端中运行 OpenCode，并提示你安装配套的 VS Code 扩展。点击确认或等待自动安装 。
手动安装（备选）：
如果未能自动安装，可以直接在 VS Code 扩展商店中搜索“OpenCode”进行安装 。
2.3 配置 AI 模型（获取 API Key）
OpenCode 本身不提供免费的模型，你需要配置自己的 API Key 。
新手推荐（OpenCode Zen）：在 OpenCode 终端中输入 /connect，选择 opencode，按照提示登录获取官方托管的简化版 API Key 。
国内用户推荐（DeepSeek）：DeepSeek 在国内可直接访问且性价比高 。
访问平台注册并创建 API Key。
在 OpenCode 终端中输入 /connect，选择 DeepSeek 并粘贴你的 Key。
本地模型：假设已有本地模型，直接配置即可使用。
配置完成后，输入 /models 可以查看并选择你想要使用的具体模型 。
参考配置如下：（配置地址：C:\Users\%USERNAME%\.config\opencode\opencode.json，文件需要新建)
{
"provider": {
"kspmas": {
"npm": "@ai-sdk/openai-compatible",
"name": "starflow",
"options": {
"baseURL": "http://kspmas.ksyun.com/v1",
"apiKey": "你的-金山云-API-Key"
},
"models": {
"deepseek-v3.2": { "name": "deepseek-v3.2" }
}
}
}
}
环境调试：
$env:LOG_LEVEL = "debug"; opencode
配置成功截图：
3. 基础使用
3.1 启动与初始化
在 VS Code 中打开项目文件夹。
打开集成终端（Ctrl+`）。
输入 opencode 启动。
或者右上角方块按钮直接点击
首次进入项目时，建议运行 /init。这会让 OpenCode 分析项目结构，生成 AGENTS.md 文件，帮助 AI 更好地理解你的项目上下文 。
3.2 快捷键与快速启动
安装扩展后，可以利用快捷键在 VS Code 中快速唤起 OpenCode：
快速启动/聚焦：Ctrl+Esc （Mac：Cmd+Esc） — 在分割终端视图中打开 OpenCode，或聚焦到已有会话 。
新建会话：Ctrl+Shift+Esc （Mac：Cmd+Shift+Esc） — 即使已有会话也创建新的 OpenCode 终端 。
插入文件引用：Alt+Ctrl+K （Mac：Cmd+Option+K） — 方便地在提问中引用特定文件或代码行（例如 @File#L37-42） 。
3.3 核心工作模式：Plan vs Build
OpenCode 通过按 Tab 键在两种模式间切换 ：
Plan Mode（规划模式）：只读模式。AI 会分析你的代码并提供修改方案或建议，但不会实际更改任何文件。适合在重构或添加复杂功能前讨论方案 。
Build Mode（构建模式）：可写模式（默认）。AI 会根据你的指令直接创建、修改或删除文件 。
3.4 常用命令速查
在 OpenCode 终端中，通过 / 开头使用各种命令：
|
命令 |
功能 |
|
/help |
显示帮助信息 |
|
/models |
查看或切换当前使用的 AI 模型 |
|
/connect |
配置或切换 AI 服务提供商 |
|
/init |
初始化项目，生成项目上下文文件 |
|
/new |
开启一个新的对话会话 |
|
/undo |
撤销 AI 上次对代码的修改 |
|
/share |
分享当前的对话会话 |
|
/compact |
压缩对话历史，以节省 Token 消耗 |
4. 进阶技巧与最佳实践
4.1 上下文管理：如何高效引用文件
OpenCode 的上下文感知能力是其核心优势，但需要合理利用以避免超出 Token 限制 。
自动感知：OpenCode 会自动将你在编辑器中当前打开的标签页或选中的代码作为上下文发送给 AI 。
手动引用：使用快捷键 Alt+Ctrl+K （Mac：Cmd+Option+K）可以精确地插入文件路径和行号。
最小权限原则：不要直接添加整个大项目（add .），而是只通过 /add 命令添加与当前任务密切相关的特定文件或目录 。
4.2 代码生成实战
OpenCode 支持多种代码生成方式 ：
注释驱动：在编辑器中写好注释描述功能（例如 // 实现一个防抖函数），按 Tab 或等待 AI 自动补全。
需求描述驱动：选中一段代码或空白区域，通过命令面板或右键菜单选择 OpenCode: Generate Code from Prompt，输入详细需求，AI 会生成完整的函数或组件。
4.3 个性化设置（Settings.json）
你可以通过 VS Code 的设置（Ctrl+,）搜索 opencode，或直接编辑 settings.json 进行更精细的配置 ：
json
{ // 设置默认模型 "opencode.defaultModel": "claude-3.5-sonnet", // 设置 API 密钥（建议使用工作区设置避免全局泄露） "opencode.apiKey.deepseek": "sk-xxxxxxxxxxx", // 设置温度参数（值越小越严谨） "opencode.temperature": 0.3, // 设置上下文扫描范围（项目/文件夹/文件） "opencode.contextScanScope": "currentFolder"}
5. 常见问题排查
5.1 扩展未自动安装
如果在终端输入 opencode 后未提示安装扩展 ：
确保你是在 VS Code 的集成终端中运行的命令，而非系统终端。
确保 VS Code 的 code 命令已安装并加入 PATH。
在 VS Code 中打开命令面板（Ctrl+Shift+P），搜索 “Shell Command: Install ‘code’ command in PATH” 并执行。
5.2 “command not found” 错误
这说明 opencode 命令未安装或未添加到系统环境变量 。
重新打开终端：有时新安装后需要重启终端。
手动刷新配置：Linux/macOS 执行 source ~/.zshrc（或 ~/.bashrc）。
确认安装：再次运行 npm install -g opencode-ai 确保安装成功。
浙公网安备 33010602011771号