OpenCode 使用指南：从"小白入门"到"AI 编程效率翻倍"开篇腊月二十九，老赵刷到一个叫 OpenCode 的

开篇

腊月二十九，老赵刷到一个叫 OpenCode 的工具，GitHub 8 万+ stars，还是免费的。

老赵心想：又是哪个公司想割韭菜？免费的东西能好用？

抱着怀疑的态度，老赵花了半天折腾，结果——真香。

OpenCode 不是割韭菜工具，是一个能在终端用的开源 AI 编程助手，能写代码、改代码、查代码，还支持几十种 AI 模型。最骚的是，它还有个叫 Oh My OpenCode 的插件，装上后，OpenCode 从"单兵作战"变成了"团队协作"。

这篇文章从「安装配置 × 核心功能 × 实战场景」三视角拆解 OpenCode 的使用方法，帮你快速上手，看完能直接套用的开发工作流。

一、快速上手：三步从零到能跑

技术原理

OpenCode 是一个开源的 AI 编程助手，核心架构基于 TypeScript，支持多模态（终端、桌面、IDE 插件）。它的最大亮点是完全开源 + 多模型支持 + 可扩展的插件生态。

三大核心特性：

多模型支持：OpenAI、Anthropic、Google、智谱 AI、MiniMax 等 75+ 种模型
免费模型：OpenCode Zen 提供精选免费模型（GLM-4.7、MiniMax M2.1）
智能体系统：内置 Build、Plan、General、Explore 四种专业智能体

数据说话：OpenCode 在 GitHub上有8万+ stars。相比 Claude Code，它完全免费且对国内用户友好（不限速、不封号）。

实操案例：安装与配置

# Step 1：安装 OpenCode（推荐使用官方脚本）
curl -fsSL https://opencode.ai/install | bash

# 或者使用 npm 安装
npm install -g opencode-ai

# Step 2：配置 AI 模型
# 方式一：使用 OpenCode Zen（推荐，有免费模型）
opencode
# 在 TUI 界面中选择 opencode，然后运行 /connect

# 方式二：使用自己的 API Key
opencode
# /connect
# 选择你的提供商（OpenAI、Anthropic、Google 等）
# 粘贴 API Key

# Step 3：初始化项目
cd /path/to/your/project
opencode
# 运行 /init，让 OpenCode 分析项目结构

安装注意事项：

Windows 用户：需要用 WSL（Windows Subsystem for Linux）或 Docker
macOS/Linux 用户：直接安装即可
需要准备 API Key（如果不用免费模型）

落地步骤

安装阶段：选择适合你系统的安装方式（脚本/npm/Homebrew）
配置阶段：选择 AI 提供商，配置 API Key（或使用免费模型）
初始化阶段：在项目目录运行 /init，让 OpenCode 生成 AGENTS.md 配置文件
开发阶段：开始使用 OpenCode 进行日常开发工作

避坑指南

❌ 新手常犯：看到免费模型就只用免费，忽略付费模型的优势
✅ 正确做法：先尝试免费模型，评估效果后再决定是否升级付费
⚠️ 注意：OpenCode Zen 的免费模型有速率限制，高峰期可能较慢

二、核心功能：四个智能体 + 四种模式

技术原理

OpenCode 的核心架构是「智能体系统（Agent System）」，通过不同的智能体处理不同的任务类型。它有两个级别的智能体：

主智能体（Primary Agents）：你直接交互的主要助手

Build：默认主智能体，拥有所有工具权限（文件读写、bash 命令）
Plan：受限智能体，禁用文件编辑和 bash 命令，用于分析和规划

子智能体（Subagents）：主智能体可以调用的专业助手

General：通用目的智能体，用于研究和多步骤任务
Explore：只读智能体，用于快速探索代码库

四种模式：

Message Mode：标准对话模式，自然语言交互
Handoff Mode：新引入的模式，主智能体将任务"移交给"子智能体
Compress Mode：压缩模式，压缩对话历史
Parallelize Mode：并行模式，分叉多个子智能体并行工作

实操案例：智能体切换与协作

# 场景：你想添加一个新功能，但不确定如何实现

# Step 1：切换到 Plan 模式（按 Tab 键）
<TAB>  # 切换到 Plan 智能体

# Step 2：让 Plan 分析项目并提出方案
"帮我分析一下这个 React 项目的代码结构，然后给出添加用户认证功能的建议"

# Plan 会返回详细的分析和实现建议，但不会修改任何文件

# Step 3：切换回 Build 模式（再按 Tab 键）
<TAB>  # 切换回 Build 智能体

# Step 4：让 Build 执行具体实现
"按照你刚才给出的建议，实现用户认证功能"

# Build 会直接修改文件、添加代码、运行测试

# 使用子智能体（@ 调用）
" @general 帮我搜索项目中所有与认证相关的文件"
" @explore 找出所有使用 useEffect 的组件"

落地步骤

理解智能体分工：Build（执行）、Plan（规划）、General（通用）、Explore（探索）
学会切换智能体：用 Tab 键在主智能体之间切换
使用 @ 调用子智能体：在消息中用 @ 前缀调用特定子智能体
选择合适的模式：根据任务类型选择 Message/Handoff/Compress/Parallelize

避坑指南

❌ 新手常犯：所有任务都用 Build 模式，导致不必要的文件修改
✅ 正确做法：规划和分析用 Plan，执行用 Build，探索用 Explore
⚠️ 注意：子智能体会创建独立的会话，可以用快捷键在主会话和子会话之间导航

三、实战场景：从"写 Bug"到"重构项目"

技术原理

OpenCode 的强大之处在于它能处理真实的项目开发场景，而不仅仅是代码补全。它有完整的项目索引能力，可以理解整个代码库的结构和上下文。

核心工作流：

项目索引：/init 扫描项目，生成 AGENTS.md
代码分析：理解现有代码结构、依赖关系、编码模式
功能开发：根据自然语言描述生成代码、修改代码
代码审查：自动检查代码质量、安全问题、性能隐患
文档生成：为项目生成或更新文档

实操案例 1：添加新功能（完整工作流）

# 场景：为一个 Next.js 项目添加用户评论功能

# Step 1：让 Plan 智能体分析需求
<TAB>  # 切换到 Plan
"为这个 Next.js 项目添加用户评论功能，需要：
1. 数据库表结构设计
2. API 路由实现
3. 前端组件开发
4. 评论与帖子的关联
请给出完整的实现方案，但不要修改任何文件。"

# Plan 会返回详细的实现建议，包括：
# - 数据库 schema（Prisma 或 SQL）
# - API 路由设计（REST 或 GraphQL）
# - React 组件结构
# - 集成方式

# Step 2：查看并确认方案
"方案看起来很完整，但我想确认一下：用户评论需要嵌套回复吗？"

# Plan 会补充说明

# Step 3：切换到 Build 执行实现
<TAB>  # 切换到 Build
"按照确认后的方案，实现用户评论功能。分步骤进行：
1. 先实现数据库迁移
2. 再创建 API 路由
3. 最后开发前端组件
每完成一步，告诉我，让我审查代码。"

# Build 会逐步实现，并在每步等待你的确认

# Step 4：代码审查
"实现完成后，帮我审查一下代码，检查：
1. SQL 注入风险
2. XSS 防护
3. 性能问题
4. 代码规范"

实操案例 2：调试和重构

# 场景：发现一个 Bug，需要定位和修复

# Step 1：用 Explore 智能体搜索相关代码
<TAB>  # 切换到 Plan 模式
" @explore 找出所有与用户认证相关的文件，特别关注：
1. login 函数
2. auth 中间件
3. token 验证逻辑"

# Explore 会返回文件列表和关键代码片段

# Step 2：分析问题
"根据找到的代码，分析可能导致登录失败的原因：
1. 异步处理不当
2. 错误处理缺失
3. token 过期检查有问题
请给出详细的根因分析和修复建议。"

# Step 3：执行修复
<TAB>  # 切换到 Build
"按照你的分析，修复这个 Bug。重点关注：
1. 添加适当的错误处理
2. 完善 token 刷新逻辑
3. 添加日志记录便于调试"

# Step 4：验证修复
"修复后，帮我检查一下是否还有其他潜在问题，特别是：
1. 并发登录场景
2. 记住我功能"

落地步骤

需求分析：用 Plan 模式先理解需求，不要急于上手就改代码
代码搜索：用 Explore 模式快速定位相关文件和代码片段
逐步实现：用 Build 模式分步实现，每步确认
代码审查：每次完成后让 AI 审查，及时发现潜在问题

避坑指南

❌ 新手常犯：一次性让 AI 实现整个功能，不审查就上线
✅ 正确做法：分步骤执行，每步确认后再继续，用 Plan 先规划
⚠️ 注意：可以用 /undo 命令撤销 AI 的修改，不要怕改错

四、Oh My OpenCode：从"助手"到"团队"

技术原理

Oh My OpenCode（简称 OMO）是 OpenCode 的增强插件，类似于 Oh My Zsh 对于 Zsh 的增强。它为 OpenCode 添加了更多强大功能：

核心增强功能：

多 AI 模型协作：同时调用多个 AI 模型协同工作
增强的智能体系统：frontend-ui-ux-engineer、oracle、librarian、document-writer 等专业智能体
后台任务管理：可以并行执行多个任务，不阻塞主对话
Skills 系统：可以创建自定义技能（Skills），封装常用工作流

安装 OMO 的好处：

OpenCode 变成完整的 AI 开发团队
可以让不同的 AI 模型协作（比如一个写代码，一个审查，一个生成文档）
后台任务可以持续运行，不影响主对话

实操案例：多模型协作

# 场景：开发一个 Vue 组件，同时需要代码审查和文档生成

# Step 1：安装 Oh My OpenCode（安装后自动启用）
# 访问 https://github.com/code-yeongyu/oh-my-opencode 按照文档安装

# Step 2：配置多个模型
# 在 opencode.json 中配置不同提供商的 API Keys

{
  "provider": {
    "openai": {
      "apiKey": "sk-..."
    },
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  },
  "agent": {
    "coder": {
      "model": "openai/gpt-4",
      "description": "用 GPT-4 写代码"
    },
    "reviewer": {
      "model": "anthropic/claude-sonnet-4",
      "description": "用 Claude Sonnet 审查代码"
    },
    "doc-writer": {
      "model": "anthropic/claude-haiku-4",
      "description": "生成技术文档"
    }
  }
}

# Step 3：使用多模型协作

# 让 coder 写代码
" @coder 为我写一个 Vue3 的用户列表组件，使用 TypeScript，包含以下功能：
1. 数据获取（使用 useQuery）
2. 分页
3. 搜索
4. 每行操作（编辑、删除）"

# 让 reviewer 审查代码
" @reviewer 审查刚才写的组件，检查：
1. TypeScript 类型安全
2. Vue 3 最佳实践
3. 性能问题
4. 可访问性（a11y）"

# 让 doc-writer 生成文档
" @doc-writer 为这个组件生成技术文档，包括：
1. Props 说明
2. 使用示例
3. API 参考链接
4. 注意事项"

# 三个智能体并行工作，你可以在不同会话中查看结果

落地步骤

安装 OMO：按照官方文档安装 Oh My OpenCode
配置智能体：为不同的任务配置专门的智能体
定义工作流：创建常用的工作流模板（Skills）
多模型协作：充分利用不同 AI 模型的优势

避坑指南

❌ 新手常犯：所有任务都用同一个模型，忽略不同模型的专长
✅ 正确做法：GPT-4 擅长代码生成，Claude 擅长推理和审查，合理分配任务
⚠️ 注意：后台任务会增加 API 调用成本，注意监控用量

结尾

三个月后，老赵的同事问他："你最近写代码怎么这么快了？"

老赵笑了笑："因为我有了 AI 开发团队。"

OpenCode + Oh My OpenCode，就像给你的电脑装了个虚拟团队。你要做的，就是学会指挥这个团队，而不是自己一个人单打独斗。

以前写一个功能要半天，现在 30 分钟搞定。以前代码 Review 要等同事，现在 AI 帮你审查。以前写文档像挤牙膏，现在 AI 一键生成。

关键是——你愿意尝试吗？

OpenCode 不是魔法，但用好了，开发效率提升 2-3 倍是真实的。就像当年 Git 刚出来时，很多人觉得"太复杂没必要"，现在呢？

你在 OpenCode 的使用中有哪些困惑？配置问题、智能体选择、还是 Oh My OpenCode 的使用？评论区交流，我们一起讨论。