ByteFisher

钓鱼爱好者的编程世界

VSCode 中搭建 OpenCode AI 编程助手完整指南

发表于 分类于 ， 阅读次数： Valine：

在 AI 编程工具蓬勃发展的今天，开源免费的 OpenCode 凭借其强大的功能和灵活的扩展性，已经成为超过 500 万开发者的首选。作为一个拥有 12 万 + GitHub Stars 的开源项目，OpenCode 提供了终端、桌面应用和 IDE 多种使用方式。本文将详细介绍如何在 VSCode 中搭建和使用 OpenCode，帮助你快速上手这款强大的 AI 编程助手。

一、什么是 OpenCode

OpenCode 是一个开源的 AI 编程助手，由 Anomaly 公司开发和维护。它具有以下核心特性：

  • 多平台支持：可在终端、桌面应用和 IDE 中使用
  • LSP 自动启用：自动加载项目的语言服务器
  • 多会话并行处理：支持同时开启多个 AI 会话
  • 75 + LLM 提供商：支持 OpenAI、Claude、Gemini 等主流模型
  • 隐私优先：不存储任何代码或上下文数据
  • 免费开源：完全免费使用，社区活跃

与其他商业 AI 编程工具（如 GitHub Copilot、Cursor）相比，OpenCode 的最大优势在于开源免费和可自托管，让你完全掌控自己的数据和成本。

二、环境准备

在开始安装 OpenCode 之前，我们需要准备好必要的开发环境。

2.1 系统要求

操作系统 版本要求 推荐方案
Windows 10/11 推荐使用 WSL2
macOS 12+ 直接安装
Linux 主流发行版 直接安装

2.2 必备工具

确保你的系统中已安装以下工具：

1
2
3
4
5
6
7
8
# 检查 Node.js 版本（需要 18+）
node -v

# 检查 Git 版本
git --version

# 检查 VSCode 版本
code --version

如果未安装，请前往对应官网下载安装：

2.3 推荐终端

OpenCode 在终端中运行效果最佳，推荐使用以下终端：

终端 平台 特点
WezTerm 跨平台 现代化、高性能
Alacritty 跨平台 极致轻量
Ghostty macOS/Linux 苹果风格
Kitty Linux/macOS 功能丰富
Windows Terminal Windows Windows 原生

三、安装 OpenCode

OpenCode 提供多种安装方式，以下是详细步骤。

3.1 方式一：官方一键脚本（推荐）

在终端中执行以下命令：

1
curl -fsSL https://opencode.ai/install | bash

3.2 方式二：npm 全局安装

如果你已经安装了 Node.js，可以使用 npm 安装：

1
npm install -g opencode-ai

3.3 方式三：Windows 包管理器

使用 Chocolatey：

1
choco install opencode

使用 Scoop：

1
scoop install opencode

3.4 方式四：macOS Homebrew

1
brew install anomalyco/tap/opencode

3.5 验证安装

安装完成后，验证是否成功：

1
opencode --version

如果显示版本号，说明安装成功。

四、配置 AI 模型

安装完成后，需要配置 AI 模型提供商才能使用。

4.1 使用 OpenCode Zen（推荐新手）

OpenCode Zen 是官方推荐的模型套餐，经过专门优化，非常适合编程任务。

步骤：

  1. 在终端中执行：

    1
    /connect

  2. 选择 opencode

  3. 浏览器会自动打开 opencode.ai/auth，登录账号

  4. 添加付款方式并获取 API Key

  5. 回到终端粘贴 API Key 即可

4.2 使用其他模型提供商

如果你想使用其他 AI 模型，可以选择：

提供商 模型 配置方式
OpenAI GPT-4o, o1 API Key
Anthropic Claude 3.5 API Key
Google Gemini 2.0 API Key
Azure OpenAI 企业配置
Ollama 本地模型 本地运行

配置示例（使用 OpenAI）：

1
2
3
4
5
6
7
# 设置环境变量
export OPENAI_API_KEY="your-api-key"

# 或在 opencode 中配置
/opencode
/set provider openai
/set model gpt-4o

4.3 使用本地模型（Ollama）

如果你想完全离线使用，可以配置 Ollama：

1
2
3
4
5
6
7
8
9
10
# 先安装 Ollama
brew install ollama  # macOS
# 或访问 https://ollama.com 下载

# 拉取编程模型
ollama pull codellama

# 在 opencode 中配置
/set provider ollama
/set model codellama

五、VSCode 集成 OpenCode

5.1 安装 VSCode 扩展

方式一：图形界面

  1. 打开 VSCode
  2. 按 Ctrl+Shift+X 打开扩展市场
  3. 搜索 “OpenCode”
  4. 点击安装

方式二：命令行

1
code --install-extension anomalyco.opencode

5.2 扩展配置

安装完成后，按以下步骤配置：

  1. 按 Ctrl+, 打开设置
  2. 搜索 “OpenCode”
  3. 配置以下选项：
设置项 说明 推荐值
API Key 你的 API Key 必填
Model 使用的模型 gpt-4o
Theme 主题风格 dark

5.3 快捷键设置

推荐设置一个方便唤起 OpenCode 的快捷键：

  1. 按 Ctrl+K Ctrl+S 打开快捷键设置
  2. 搜索 “OpenCode: Open”
  3. 双击设置快捷键，推荐：Ctrl+Shift+O

5.4 界面介绍

VSCode 扩展包含以下组件：

  • 侧边栏会话窗口：显示 AI 对话内容
  • 代码编辑区：直接在代码上协作
  • 状态栏提示：显示当前模式和状态

六、快速开始

6.1 项目初始化

1
2
3
4
5
# 进入你的项目目录
cd your-project

# 启动 opencode
opencode

首次运行需要初始化：

1
/init

这会自动分析项目结构并生成 AGENTS.md 文件。

提示：建议将 AGENTS.md 提交到 Git，这能帮助 AI 更好地理解项目规范。

6.2 核心交互命令

命令 功能
/init 初始化项目
/connect 连接 AI 提供商
/share 分享当前会话
/undo 撤销修改
/redo 重做修改
Tab 切换 Plan/Build 模式

七、实战案例

7.1 案例一：让 AI 解释代码

当你面对陌生的代码时，可以直接提问：

1
How does authentication work in @src/auth/login.ts?

技巧：使用 @ 符号可以快速引用项目中的文件。

7.2 案例二：添加新功能

步骤：

  1. 按 Tab 切换到 Plan 模式（查看右下角状态）

  2. 描述你的需求：

    1
    2
    3
    4
    我们需要在用户管理模块添加一个"忘记密码"功能：
    1. 用户输入注册邮箱
    2. 系统发送重置链接到邮箱
    3. 用户点击链接设置新密码

  3. AI 会生成详细的实现计划

  4. 确认计划后，再次按 Tab 切换到 Build 模式

  5. 执行：

    1
    Sounds good! Go ahead and make the changes.

7.3 案例三：重构代码

直接让 AI 重构指定代码：

1
2
Can you refactor this function to use async/await?
@src/api/user.ts

如果结果不满意，使用 /undo 撤销。

7.4 案例四：修复 Bug

提供错误信息和上下文：

1
2
3
4
5
I'm getting this error:
Error: Cannot read property 'name' of undefined
at UserService.getProfile (src/services/user.ts:45)

Can you find and fix the issue?

八、进阶配置

8.1 自定义配置文件

创建 ~/.opencode/config.yaml 进行自定义配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 模型设置
model: gpt-4o
temperature: 0.7
max_tokens: 4000

# 默认提供商
provider: openai

# 界面主题
theme: dark

# 格式化工具
formatters:
  prettier: true
  eslint: true

# LSP 配置
lsp:
  typescript: typescript-language-server
  python: pyright

8.2 代码格式化集成

OpenCode 支持保存时自动格式化：

1
2
3
4
5
formatters:
  on_save: true
  prettier:
    ext: [.js, .ts, .jsx, .tsx]
  eslint: true

8.3 自定义命令

创建常用 Prompt 别名：

1
2
3
4
commands:
  explain: "请详细解释这段代码的功能"
  test: "为以下代码编写单元测试"
  docs: "为以下代码生成文档注释"

九、竞品对比

特性 OpenCode GitHub Copilot Cursor Windsurf
开源 ✅ ❌ ❌ ❌
价格 免费/付费 付费 付费 付费
自托管 ✅ ❌ ❌ ❌
模型选择 75+ 仅 OpenAI 多 多
Plan 模式 ✅ ❌ ✅ ✅
终端支持 ✅ ❌ ❌ ❌
多会话 ✅ ❌ ✅ ✅
隐私安全 高 中 中 中
GitHub Stars 120K+ - - -

选择建议

场景 推荐工具
预算有限 OpenCode
生态完善 GitHub Copilot
智能交互 Cursor
专业团队 Windsurf

十、常见问题

10.1 安装问题

Q：npm 安装失败

1
2
3
4
A：检查 Node.js 版本，确保是 18+
node -v  # 如果版本过低，升级 Node.js
nvm install 20
nvm use 20

Q：权限报错

1
2
A：使用管理员权限或配置 npm 路径
sudo npm install -g opencode-ai

10.2 配置问题

Q：API Key 无效

1
2
A：检查 Key 格式和账户余额
确保已在对应提供商官网获取正确格式的 Key

Q：模型响应慢

1
2
A：尝试其他提供商或使用代理
/set provider openai  # 切换提供商

10.3 使用问题

Q：回答不准确

1
2
3
4
A：提供更多上下文信息
- 使用 @ 引用相关文件
- 描述具体场景和需求
- 提供示例代码

Q：修改不符合预期

1
2
A：多使用 Plan 模式先审核计划
按 Tab 切换到 Plan 模式，确认后再执行

10.4 网络问题

Q：国内访问慢

1
2
3
A：配置代理或使用国内节点
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

十一、总结

OpenCode 作为一款免费开源的 AI 编程助手，在功能上完全不输商业产品。其优势总结如下：

  • ✅ 完全免费：无需付费即可使用强大功能
  • ✅ 开源透明：代码完全开放，社区活跃
  • ✅ 灵活配置：支持 75+ AI 模型
  • ✅ 隐私安全：不存储任何用户数据
  • ✅ 多平台：终端、桌面、IDE 全面支持

无论你是个人开发者还是团队，OpenCode 都是一个值得尝试的 AI 编程伙伴。赶快安装体验吧！

相关链接：

如果你喜欢这篇文章，欢迎在评论区分享你的使用体验！