OpenCode 最佳实践

OpenCode VS Code 使用指南

目录

1. [什么是 OpenCode](#什么是 OpenCode "#%E4%BB%80%E4%B9%88%E6%98%AF-opencode")
2. [安装 OpenCode](#安装 OpenCode "#%E5%AE%89%E8%A3%85-opencode")
3. [VS Code 扩展安装](#VS Code 扩展安装 "#vscode-%E6%89%A9%E5%B1%95%E5%AE%89%E8%A3%85")
4. 基本使用方法
5. 快捷键
6. 配置说明
7. [如何打开 opencode.json 文件](#如何打开 opencode.json 文件 "#%E5%A6%82%E4%BD%95%E6%89%93%E5%BC%80-opencodejson-%E6%96%87%E4%BB%B6")
8. 免费模型推荐
9. 常用命令
10. 使用技巧
11. 故障排除

---

什么是 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 扩展安装

自动安装（推荐）

1. 打开 VS Code

2. 打开集成终端（Ctrl + ~）

3. 在终端中运行：

   opencode

4. 扩展会自动安装

手动安装

1. 打开 VS Code
2. 按 Ctrl+Shift+X 打开扩展市场
3. 搜索 "OpenCode"
4. 点击 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
}

配置优先级（从低到高）

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

---

免费模型推荐

根据官方文档，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

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

💡 使用建议

1. 日常使用 ：首选 GPT 5 Nano 作为默认模型，永久免费且响应快
2. 复杂任务 ：切换到 Big Pickle 或 Qwen3.6 Plus Free，但避免处理敏感代码
3. 生产环境：建议使用付费模型（如 Claude Sonnet 4.5、GPT 5.4），确保稳定性和隐私
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 只会生成实施计划而不会实际修改代码。

使用流程：

1. Tab - 切换到 Plan 模式
2. 描述你想要的功能
3. 审查 OpenCode 生成的计划
4. Tab - 切换回 Build 模式
5. 输入"开始实施"或 "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

1. 打开 Finder
2. 按 Cmd + Shift + G 打开"前往文件夹"对话框
3. 输入路径：~/.config/opencode
4. 双击 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

方法三：使用资源管理器

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

方法四：使用 OpenCode 命令

在 OpenCode 终端中运行：

/editor %USERPROFILE%\.config\opencode\opencode.json

---

快速定位项目级配置

如果要在当前项目中打开 opencode.json：

Mac/Linux:

open ./opencode.json
# 或
code ./opencode.json

Windows:

notepad .\opencode.json
# 或
code .\opencode.json

---

配置文件示例

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

---

故障排除

扩展无法自动安装

检查清单：

1. ✅ 确保在 VS Code 集成终端中运行 opencode
2. ✅ 确认 IDE CLI 已安装：
   • VS Code: code 命令
   • Cursor: cursor 命令
   • Windsurf: windsurf 命令
   • VSCodium: codium 命令
3. ✅ 如果 CLI 未安装，按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows/Linux），搜索 "Shell Command: Install 'code' command in PATH"
4. ✅ 确保 VS Code 有安装扩展的权限

常见问题

Q: OpenCode 会存储我的代码吗？ A: 不会。OpenCode 是隐私优先的，不会存储任何代码或上下文数据。

Q: 是否需要额外订阅 AI 服务？ A: 不需要。OpenCode 包含免费模型，或可以连接你现有的订阅（如 ChatGPT Plus、GitHub Copilot）。

Q: 可以使用本地模型吗？ A: 可以。支持通过 Ollama 等方式连接本地模型。

Q: 如何查看当前配置？ A: 运行命令：

opencode debug config

---

更多资源

• 📖 官方文档
• 💬 Discord 社区
• 🐙 GitHub 仓库
• 🐦 X/Twitter

---

希望这份指南对你有帮助！如有问题，欢迎随时提问。