OpenCode 最佳实践OpenCode VS Code 使用指南目录什么是 OpenCode 安装 OpenCo

OpenCode VS Code 使用指南

什么是 OpenCode

OpenCode 是一个开源的 AI 编程助手，支持在终端、桌面应用和 IDE 中使用。它可以帮助你：

编写代码 - 根据自然语言描述生成代码
解释代码 - 理解现有代码的功能和逻辑
重构代码 - 改进代码质量和结构
调试问题 - 帮助诊断和解决 bug
添加功能 - 根据需求实现新特性

OpenCode 在 GitHub 上拥有超过 140,000 Stars，被超过 650万 开发者使用。

安装 OpenCode

方式一：使用官方安装脚本（推荐）

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

方式二：使用 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

方式三：使用 Homebrew（macOS/Linux）

brew install anomalyco/tap/opencode

提示：建议使用 OpenCode 官方 tap 获取最新版本。官方的 brew install opencode 由 Homebrew 团队维护，更新频率较低。

Windows 安装

推荐方式：使用 WSL（Windows Subsystem for Linux）

# 使用 Chocolatey
choco install opencode

# 使用 Scoop
scoop install opencode

# 使用 NPM
npm install -g opencode-ai

VS Code 扩展安装

自动安装（推荐）

打开 VS Code
打开集成终端（Ctrl + ~）
在终端中运行：
```
opencode
```
扩展会自动安装

手动安装

打开 VS Code
按 Ctrl+Shift+X 打开扩展市场
搜索 "OpenCode"
点击 Install 安装

支持的 IDE

OpenCode 扩展支持以下 IDE 及其分支：

✅ Visual Studio Code
✅ Cursor
✅ Windsurf
✅ VSCodium
✅ 任何支持终端的 IDE

基本使用方法

1. 初始化项目

在项目根目录运行：

cd /path/to/your/project
opencode

然后运行：

/init

这会分析你的项目结构并创建 AGENTS.md 文件（建议将此文件提交到 Git）。

2. 配置 AI 模型

运行连接命令选择提供商：

/connect

推荐选项：

OpenCode Zen - 官方验证的模型（推荐新手使用）
Anthropic Claude - 强大的编程模型
OpenAI GPT - ChatGPT Plus/Pro 用户可直接使用
GitHub Copilot - 使用 Copilot 账号登录
本地模型 - 支持 Ollama 等本地部署

3. 开始对话

初始化完成后，直接输入你的需求即可：

# 询问代码解释
请解释一下 @src/main.js 的功能

# 添加新功能
帮我添加一个用户登录功能

# 重构代码
请重构这个函数，使其更易读

文件引用技巧：使用 @ 键快速模糊搜索项目中的文件

快捷键

快捷键	macOS	Windows/Linux	功能
快速启动	`Cmd + Esc`	`Ctrl + Esc`	在分屏终端视图中打开 OpenCode
新建会话	`Cmd + Shift + Esc`	`Ctrl + Shift + Esc`	启动新的 OpenCode 终端会话
插入文件引用	`Cmd + Option + K`	`Alt + Ctrl + K`	插入文件引用，如 `@File#L37-42`

配置说明

全局配置

位置：~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "share": "manual",
  "tools": {
    "write": true,
    "bash": true
  }
}

项目级配置

在项目根目录创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "instructions": ["docs/guidelines.md", ".cursor/rules/*.md"],
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"]
    }
  }
}

TUI 配置（界面相关）

位置：~/.config/opencode/tui.json 或项目根目录 tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "scroll_speed": 3,
  "mouse": true
}

配置优先级（从低到高）

远程配置 - 组织默认设置
全局配置 - ~/.config/opencode/opencode.json
自定义配置 - OPENCODE_CONFIG 环境变量
项目配置 - 项目根目录 opencode.json
管理配置 - 企业级强制设置（最高优先级）

免费模型推荐

根据官方文档，OpenCode 提供了以下 免费模型：

🆓 免费模型列表

模型名称	推荐指数	说明
GPT 5 Nano	⭐⭐⭐⭐⭐ (5/5)	官方永久免费，轻量级任务，速度快
Big Pickle	⭐⭐⭐⭐ (4/5)	限时免费，性能强劲但数据用于模型改进
Qwen3.6 Plus Free	⭐⭐⭐⭐ (4/5)	限时免费，阿里通义千问系列
Nemotron 3 Super Free	⭐⭐⭐ (3/5)	限时免费，NVIDIA 模型，适合代码生成
MiniMax M2.5 Free	⭐⭐⭐ (3/5)	限时免费，国产大模型

📊 详细推荐指数说明

⭐⭐⭐⭐⭐ GPT 5 Nano - 强烈推荐

优势：永久免费、速度极快、适合轻量任务
适用场景：代码补全、简单重构、会话标题生成
隐私：数据不会被用于训练
限制：模型能力相对较弱，不适合复杂任务

⭐⭐⭐⭐ Big Pickle / Qwen3.6 Plus Free

优势：性能强劲，接近付费模型水平
适用场景：复杂编程任务、代码审查、架构设计
⚠️ 注意：限时免费期间，数据可能被用于改进模型
建议：适合非敏感项目使用

⭐⭐⭐ Nemotron 3 Super Free / MiniMax M2.5 Free

优势：免费使用，可尝试不同模型特性
适用场景：日常编码、学习探索
⚠️ 注意：同样是限时免费，数据收集政策适用

💡 使用建议

日常使用：首选 GPT 5 Nano 作为默认模型，永久免费且响应快
复杂任务：切换到 Big Pickle 或 Qwen3.6 Plus Free，但避免处理敏感代码
生产环境：建议使用付费模型（如 Claude Sonnet 4.5、GPT 5.4），确保稳定性和隐私
本地部署：如果有隐私要求，可使用 Ollama 配置本地免费模型

🔒 隐私提醒

免费模型（除 GPT 5 Nano 外）：

在限时免费期间，你的对话数据可能被用于改进模型
不适合处理敏感代码或商业机密

GPT 5 Nano：

✅ 数据不会被保留或用于训练
✅ 可以放心使用

🚀 如何启用

# 在 OpenCode 中运行
/connect
# 选择 "OpenCode Zen"
# 然后运行
/models
# 选择上述免费模型即可

常用命令

命令	功能
`/help`	显示帮助信息
`/init`	初始化项目
`/connect`	连接 AI 提供商
`/undo`	撤销上一次的更改（可多次撤销）
`/redo`	重做撤销的更改
`/share`	分享当前会话链接
`/editor`	在默认编辑器中打开文件
`/export`	导出当前会话
`clear`	清空对话历史

使用技巧

1. Plan 模式（规划模式）

按 Tab 键切换到 Plan 模式，此时 OpenCode 只会生成实施计划而不会实际修改代码。

使用流程：

Tab - 切换到 Plan 模式
描述你想要的功能
审查 OpenCode 生成的计划
Tab - 切换回 Build 模式
输入"开始实施"或 "Go ahead"

2. 添加图片

直接将图片拖拽到终端中，OpenCode 可以扫描并分析图片内容。

请参照这张设计图实现界面 [拖拽图片到此处]

3. 使用 Agent（智能体）

创建自定义 Agent 处理特定任务：

// opencode.json
{
  "agent": {
    "code-reviewer": {
      "description": "代码审查专家",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一位资深代码审查员，关注安全性、性能和可维护性。",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

使用方式：

@code-reviewer 请审查这个函数的代码质量

4. 自定义命令

配置常用命令模板：

// opencode.json
{
  "command": {
    "test": {
      "template": "运行完整的测试套件并生成覆盖率报告，重点关注失败的测试并提供修复建议。",
      "description": "运行测试",
      "agent": "build"
    },
    "component": {
      "template": "创建一个名为 $ARGUMENTS 的 React 组件，使用 TypeScript，包含正确的类型和基本结构。",
      "description": "创建组件"
    }
  }
}

使用：

/test
/component UserCard

5. 权限控制

配置哪些操作需要用户确认：

{
  "permission": {
    "edit": "ask",      // 编辑文件前询问
    "bash": "ask",      // 执行命令前询问
    "write": "allow"    // 允许直接写入
  }
}

如何打开 opencode.json 文件

opencode.json 是 OpenCode 的配置文件，分为全局配置和项目级配置两种。

配置文件位置

类型	Mac/Linux 路径	Windows 路径
全局配置	`~/.config/opencode/opencode.json`	`%USERPROFILE%\.config\opencode\opencode.json`
项目配置	`./opencode.json`（项目根目录）	`.\opencode.json`（项目根目录）
TUI 配置	`~/.config/opencode/tui.json`	`%USERPROFILE%\.config\opencode\tui.json`

注意：~ 表示用户主目录，Mac 上是 /Users/用户名/，Windows 上是 C:\Users\用户名\

Mac 系统打开方法

方法一：使用终端命令（推荐）

# 打开全局配置文件
open ~/.config/opencode/opencode.json

# 或使用 VS Code 打开
code ~/.config/opencode/opencode.json

# 如果文件不存在，先创建目录
mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json
open ~/.config/opencode/opencode.json

方法二：使用 Finder

打开 Finder
按 Cmd + Shift + G 打开"前往文件夹"对话框
输入路径：~/.config/opencode
双击 opencode.json 文件，会使用默认编辑器打开

方法三：使用 OpenCode 命令

在 OpenCode 终端中运行：

/editor ~/.config/opencode/opencode.json

Windows 系统打开方法

方法一：使用 PowerShell（推荐）

# 打开全局配置文件
notepad $env:USERPROFILE\.config\opencode\opencode.json

# 或使用 VS Code 打开
code $env:USERPROFILE\.config\opencode\opencode.json

# 如果文件不存在，先创建目录
New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.config\opencode
New-Item -ItemType File -Force -Path $env:USERPROFILE\.config\opencode\opencode.json
notepad $env:USERPROFILE\.config\opencode\opencode.json

方法二：使用 CMD

# 打开全局配置文件
notepad %USERPROFILE%\.config\opencode\opencode.json

# 或使用 VS Code 打开
code %USERPROFILE%\.config\opencode\opencode.json

方法三：使用资源管理器

打开 文件资源管理器
在地址栏输入：%USERPROFILE%\.config\opencode
按回车键进入目录
双击 opencode.json 文件打开

方法四：使用 OpenCode 命令