OpenCode 实战教程：从零配置到免费接入顶级 AI 模型

📚 分类: AI 编程工具 / 开源工具配置 ⏱️ 预计耗时: 30-45 分钟 🎯 难度: 入门 🔧 环境要求: Windows / macOS / Linux，Node.js 18.0+，Git 2.30+

你将学到什么

完成本教程后，你将能够：

[ ] 在本地环境中安装并启动 OpenCode（4 种方式任选）
[ ] 免费接入 Google Gemini 3 Pro 和 Claude 4.5 Opus 等顶级模型
[ ] 安装并使用神级插件 Oh My Opencode 提升效率
[ ] 配置 Agent Skills、MCP 协议和 Subagnet 多智能体协作
[ ] 解决新手最常见的 6 个报错问题

最终效果

你将在终端中成功运行 OpenCode，并能够：

在任意项目目录下输入 opencode 启动 AI 编程助手
通过 /model 命令自由切换不同 AI 模型（包括免费模型）
使用 /skill run 执行自定义的 AI 技能（如自动生成 React 组件）
让多个 AI 子智能体（Subagent）分工协作完成复杂任务

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求版本	验证命令
Node.js	≥ 18.0	`node -v`
Git	≥ 2.30	`git --version`
终端模拟器	推荐 WezTerm / Alacritty / Kitty	-
内存	≥ 4GB（推荐 8GB+）	`free -h`（Mac/Linux）或任务管理器（Windows）

1. 安装 Node.js（如果尚未安装）

bash

# 方法一：使用 nvm（推荐，可管理多个版本）
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
$ nvm install 20               // 安装 Node.js 20.x LTS 版本
$ nvm use 20                   // 切换使用

# 方法二：直接下载安装包
# 访问 https://nodejs.org 下载 v18+ 的安装包，双击安装即可

✅ 验证：执行 node -v，应显示 v18.0.0 或更高版本。

第 1 步：选择并安装 OpenCode（推荐 CLI 版）

🎯 目标：在终端中安装 OpenCode 命令行工具，并验证安装成功。

OpenCode 提供 4 种运行形态，本教程以 命令行 CLI 版（官方推荐，最稳定完整）为例。如果你偏好图形界面，可参考文末的「进阶技巧」。

📝 操作：

根据你的操作系统选择一种方式：

bash

# 方式一：一键脚本安装（推荐，自动处理依赖）
$ curl -fsSL https://opencode.ai/install | bash

# 方式二：npm 全局安装（如果已安装 Node.js）
$ npm install -g opencode-ai@latest

# 方式三：macOS 用户使用 Homebrew
$ brew install anomalyco/tap/opencode

# 方式四：Arch Linux 用户
$ sudo pacman -S opencode        # 稳定版
$ paru -S opencode-bin           # 最新版（来自 AUR）

💡 提示：如果遇到权限错误（EACCES: permission denied），在命令前加 sudo（Mac/Linux），或以管理员身份运行终端（Windows）。

✅ 验证：

bash

$ opencode --version
# 预期输出：v1.4.3（或更新的版本号）

如果看到版本号，说明安装成功。

第 2 步：启动 OpenCode 并初始化项目

🎯 目标：进入你的项目目录，首次启动 OpenCode 并完成项目初始化。

📝 操作：

bash

# 1. 进入你的项目目录（如果还没有项目，先创建一个）
$ mkdir my-awesome-project && cd my-awesome-project

# 2. 启动 OpenCode
$ opencode

首次启动时，OpenCode 会自动检查环境。你会看到类似以下的 TUI（终端用户界面）：

┌─────────────────────────────────────────────────────────┐
│  OpenCode v1.4.3                                        │
│  Type /help for commands                                │
│                                                         │
│  ⚡ No project context found.                           │
│  Try /init to set up your project.                      │
└─────────────────────────────────────────────────────────┘

在 OpenCode 的对话界面中输入：

text

/init

OpenCode 会分析你的项目结构，并在项目根目录创建一个 AGENTS.md 文件。

✅ 验证：

bash

$ ls -la AGENTS.md
# 预期输出：-rw-r--r--  1 user  staff  1234 Jun  1 16:00 AGENTS.md

💡 提示：AGENTS.md 文件用于存储项目上下文和编码规范。建议将它提交到 Git 仓库，以便团队成员共享。

🤔 为什么要这样做？ /init 命令让 AI 了解你的项目结构（语言、框架、目录布局），后续的代码生成和修改会更精准。相当于给 AI 一个"项目说明书"。

第 3 步：查看可用的免费模型

🎯 目标：了解 OpenCode 自带的免费模型，并学会切换模型。

📝 操作：

在 OpenCode 对话界面中输入：

text

/models

系统会列出所有可用的模型，类似这样：

Available Models:
  ├── minimax-m2.1-free         [Free]   ← 免费模型
  ├── gemini-3-pro              [Free]   ← 免费模型
  ├── claude-4.5-opus           [API Key Required]
  ├── gpt-4o                    [API Key Required]
  └── ollama:deepseek-coder     [Local]

切换到一个免费模型试试：

text

/model minimax-m2.1-free

✅ 验证：切换后，OpenCode 的提示符会变为 [minimax-m2.1-free] >，表示当前正在使用该模型。

第 4 步：免费接入 Google Gemini 3 Pro

🎯 目标：获取 Google Gemini API 密钥，并在 OpenCode 中配置使用。

📝 操作：

4.1 获取 API 密钥

打开浏览器，访问 Google AI Studio
使用你的 Google 账号登录
点击 "Get API key" 按钮
点击 "Create API key" → 选择或创建一个项目
复制生成的 API 密钥（一串类似 AIzaSy... 的字符串）

4.2 在 OpenCode 中配置

在 OpenCode 对话界面中输入：

text

/connect google

系统会提示你粘贴 API 密钥。粘贴后按回车确认。

✅ 验证：

text

/model gemini-3-pro

如果输出 Switched to gemini-3-pro 且没有报错，说明配置成功。

⚠️ 常见错误：如果提示 API key not valid，请检查：

密钥是否完整复制（不要漏掉开头或结尾字符）
Google AI Studio 账号是否已激活（可能需要绑定支付方式，但 Gemini 有免费额度）
尝试重新生成一个新的 API 密钥

第 5 步：接入 Claude 4.5 Opus（付费，但有免费额度）

🎯 目标：获取 Anthropic API 密钥，接入公认最强的代码模型 Claude 4.5 Opus。

⚠️ 注意：Claude 4.5 Opus 是付费模型（$15/百万输入 token），但新用户可获得 $5 免费额度，足够完成本教程的测试。

📝 操作：

5.1 获取 API 密钥

访问 Anthropic Console
注册账号并登录（注意：Anthropic 目前仅支持部分地区，如美国、欧洲等）
在左侧菜单点击 "API Keys"
点击 "Create Key"，输入名称（如 opencode-test）
复制生成的 API 密钥（以 sk-ant- 开头）

5.2 在 OpenCode 中配置

text

/connect anthropic

粘贴 API 密钥并确认。

✅ 验证：

text

/model claude-4.5-opus

如果输出 Switched to claude-4.5-opus，说明配置成功。

💡 提示：如果你暂时无法获取 Anthropic API 密钥，可以先使用 Gemini 3 Pro（免费）完成后续步骤，功能体验基本一致。

第 6 步：安装神级插件 Oh My Opencode

🎯 目标：安装 Oh My Opencode（OMO）插件，获得一键模型切换、终极工作模式等高级功能。

📝 操作：

方式一：AI 自动安装（推荐）

在 OpenCode 对话界面中输入以下指令，让 AI 自动完成安装：

text

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

OpenCode 会自动下载并配置 OMO 插件。等待几秒钟，看到 Installation complete 即表示成功。

方式二：手动安装

如果自动安装失败，可以手动操作：

bash

# 使用 npm 全局安装插件
$ npm install -g oh-my-opencode

# 编辑 OpenCode 配置文件
$ nano ~/.config/opencode/opencode.jsonc

在配置文件中添加插件配置：

json

{
  "plugin": [
    "oh-my-opencode"
  ]
}

保存文件后，重启 OpenCode。

✅ 验证：

在 OpenCode 中输入：

text

/opus

如果输出 Switched to claude-4.5-opus，说明 OMO 插件工作正常（/opus 是 OMO 提供的一键切换命令，等价于 /model claude-4.5-opus）。

第 7 步：使用 OMO 的核心功能

🎯 目标：体验 OMO 插件提供的效率提升功能。

📝 操作：

7.1 一键模型切换

text

# 切换到 Claude 4.5 Opus
/opus

# 切换到 Gemini 3 Pro
/gemini

# 切换到免费模型
/free

7.2 启用终极工作模式

text

# 启动终极工作模式（所有代理同时激活，直到任务完成）
ultrawork

或者使用缩写：

text

ulw

7.3 使用预设 Agent 模板

text

# 使用代码审查 Agent
/agent code-review

# 使用测试生成 Agent
/agent test-generator

# 使用文档生成 Agent
/agent doc-writer

✅ 验证：执行上述命令后，OpenCode 会启动相应的 AI 代理，你可以看到类似 [Code Review Agent] Analyzing your code... 的输出。

第 8 步：创建并使用自定义 Agent Skill

🎯 目标：创建一个自动生成 React 组件的 Skill，体验 OpenCode 的 AI 技能开发。

📝 操作：

8.1 创建 Skill

在 OpenCode 中输入：

text

/skill create react-component

OpenCode 会打开一个编辑器，输入以下内容：

typescript

// skill: react-component
// description: 创建一个 React 函数组件
// author: Your Name
// version: 1.0.0

// 定义技能输入参数的接口
interface SkillInput {
  componentName: string;      // 组件名称
  props: string[];            // 组件属性列表
  useTypescript: boolean;     // 是否使用 TypeScript
}

// 技能的主函数
export default async function skill(input: SkillInput) {
  // 解构输入参数
  const { componentName, props, useTypescript } = input;
  
  // 根据是否使用 TypeScript 确定文件扩展名
  const fileExtension = useTypescript ? 'tsx' : 'jsx';
  
  // 生成文件名
  const fileName = `${componentName}.${fileExtension}`;
  
  // 生成组件代码
  const componentCode = `
import React from 'react';

${useTypescript ? `interface ${componentName}Props {
  ${props.map(prop => `${prop}: any;`).join('\n')}
}` : ''}

const ${componentName} = (${useTypescript ? `{${props.join(', ')}}: ${componentName}Props` : `{${props.join(', ')}}`}) => {
  return (
    <div className="${componentName.toLowerCase()}">
      <h1>${componentName}</h1>
    </div>
  );
};

export default ${componentName};
`;
  
  // 将生成的代码写入文件
  await opencode.fs.writeFile(fileName, componentCode.trim());
  
  // 返回结果信息
  return `成功创建组件 ${componentName}，文件路径：${fileName}`;
}

保存并退出编辑器（在 nano 中按 Ctrl+X，然后 Y，回车）。

8.2 使用 Skill

text

/skill run react-component --componentName=UserProfile --props=name,email,avatar --useTypescript=true

✅ 验证：执行后，你应该看到输出 成功创建组件 UserProfile，文件路径：UserProfile.tsx。检查项目目录：

bash

$ cat UserProfile.tsx
# 应该看到生成的 React 组件代码

🤔 为什么要这样做？ Agent Skills 让你可以将重复的开发任务（如创建组件、生成 API 路由、编写测试）自动化。一次编写，多次复用，极大提升效率。

进阶技巧（可选）

1. 使用桌面客户端版

如果你不习惯命令行操作，可以安装桌面版：

bash

# macOS
$ brew install --cask opencode-desktop

# 或访问 https://opencode.ai/download 下载安装包

桌面版与 CLI 版共享配置，你之前配置的 API 密钥和插件会自动同步。

2. 配置多智能体协作（Subagent）

编辑 ~/.config/opencode/opencode.jsonc，添加：

json

{
  "subagents": [
    {
      "name": "frontend-developer",
      "model": "gemini-3-pro",
      "systemPrompt": "你是一位前端开发专家，专注于 HTML、CSS 和 JavaScript 开发。"
    },
    {
      "name": "backend-developer",
      "model": "claude-4.5-opus",
      "systemPrompt": "你是一位后端开发专家，专注于 Node.js 和数据库开发。"
    }
  ]
}

重启 OpenCode 后，你可以：

text

/delegate frontend-developer "创建一个登录页面"
/delegate backend-developer "创建用户认证 API"

3. 配置 MCP 协议连接外部工具

MCP（Model Context Protocol）让 AI 可以调用外部服务，如 Cloudflare Workers：

json

// ~/.config/opencode/opencode.jsonc
{
  "mcp": {
    "cloudflare": {
      "type": "remote",
      "url": "https://mcp.cloudflare.com/mcp",
      "enabled": true
    }
  }
}

重启后，输入 /mcps 查看已加载的 MCP 服务器。

常见问题 (FAQ)

Q1: 安装时提示 EACCES: permission denied 怎么办？A: 这是权限不足。解决方案：

bash

# macOS/Linux：使用 sudo
$ sudo npm install -g opencode-ai@latest

# 或者修改 npm 全局目录（推荐，更安全）
$ mkdir ~/.npm-global
$ npm config set prefix '~/.npm-global'
$ echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
$ source ~/.bashrc
$ npm install -g opencode-ai@latest

Q2: macOS 提示"无法打开，因为无法验证开发者"？A: 移除隔离属性：

bash

$ sudo xattr -r -d com.apple.quarantine /usr/local/bin/opencode

Q3: Windows 提示"在此系统上禁止运行脚本"？A: 以管理员身份打开 PowerShell，执行：

powershell

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

输入 Y 确认。

Q4: 如何更新 OpenCode？A: 根据安装方式选择：

bash

# npm 安装
$ npm update -g opencode-ai@latest

# Homebrew 安装
$ brew upgrade opencode

# 一键脚本安装
$ curl -fsSL https://opencode.ai/install | bash

Q5: OpenCode 会上传我的代码吗？A: 默认不会。只有当你使用云端模型（如 Claude、Gemini）时，代码才会被发送到对应的 AI 提供商处理。如果你非常注重隐私，可以使用本地模型（如通过 Ollama 运行 DeepSeek-Coder）。

Q6: 如何卸载 OpenCode？A:

bash

# npm 安装
$ npm uninstall -g opencode-ai

# Homebrew 安装
$ brew uninstall opencode

# 一键脚本安装
$ rm -rf ~/.opencode
$ rm -f /usr/local/bin/opencode

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

安装 OpenCode：通过 npm、Homebrew 或一键脚本，在 2 分钟内完成安装
接入 AI 模型：免费接入 Gemini 3 Pro，付费接入 Claude 4.5 Opus（有免费额度）
安装 Oh My Opencode：获得一键模型切换、终极工作模式等效率功能
创建 Agent Skills：编写可复用的 AI 技能，自动化重复开发任务
高级特性：了解 Subagent 多智能体协作和 MCP 协议扩展

下一步

如果你想继续深入，建议学习：

📖 OpenCode 官方文档：深入了解所有命令和配置选项
📖 Oh My Opencode 文档：探索更多插件功能
📖 Agent Skills 开发指南：学习编写更复杂的 AI 技能

💡 练习任务：尝试创建一个自定义 Skill，让它能自动生成一个 Express.js 的 REST API 路由。这是巩固知识的最佳方式。

yaml


## 相关文档

- [OpenCode AI 编程助手安装实战教程](/docs/huan-jing-da-jian/opencode-ai-bian-cheng-zhu-shou-an-zhuang-shi-zhan-jiao-cheng.html)
- [OpenCode 备用安装方式实战教程](/docs/huan-jing-da-jian/opencode-bei-yong-an-zhuang-fang-shi-shi-zhan-jiao-cheng.html)

OpenCode 实战教程：从零配置到免费接入顶级 AI 模型 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 安装 Node.js（如果尚未安装） ​

第 1 步：选择并安装 OpenCode（推荐 CLI 版） ​

第 2 步：启动 OpenCode 并初始化项目 ​

第 3 步：查看可用的免费模型 ​

第 4 步：免费接入 Google Gemini 3 Pro ​

4.1 获取 API 密钥 ​

4.2 在 OpenCode 中配置 ​

第 5 步：接入 Claude 4.5 Opus（付费，但有免费额度） ​

5.1 获取 API 密钥 ​

5.2 在 OpenCode 中配置 ​

第 6 步：安装神级插件 Oh My Opencode ​

方式一：AI 自动安装（推荐） ​

方式二：手动安装 ​

第 7 步：使用 OMO 的核心功能 ​

7.1 一键模型切换 ​

7.2 启用终极工作模式 ​

7.3 使用预设 Agent 模板 ​

第 8 步：创建并使用自定义 Agent Skill ​

8.1 创建 Skill ​

8.2 使用 Skill ​

进阶技巧（可选） ​

1. 使用桌面客户端版 ​

2. 配置多智能体协作（Subagent） ​

3. 配置 MCP 协议连接外部工具 ​

常见问题 (FAQ) ​

总结 ​

下一步 ​

OpenCode 实战教程：从零配置到免费接入顶级 AI 模型

你将学到什么

最终效果

前置准备

1. 安装 Node.js（如果尚未安装）

第 1 步：选择并安装 OpenCode（推荐 CLI 版）

第 2 步：启动 OpenCode 并初始化项目

第 3 步：查看可用的免费模型

第 4 步：免费接入 Google Gemini 3 Pro

4.1 获取 API 密钥

4.2 在 OpenCode 中配置

第 5 步：接入 Claude 4.5 Opus（付费，但有免费额度）

5.1 获取 API 密钥

5.2 在 OpenCode 中配置

第 6 步：安装神级插件 Oh My Opencode

方式一：AI 自动安装（推荐）

方式二：手动安装

第 7 步：使用 OMO 的核心功能

7.1 一键模型切换

7.2 启用终极工作模式

7.3 使用预设 Agent 模板

第 8 步：创建并使用自定义 Agent Skill

8.1 创建 Skill

8.2 使用 Skill

进阶技巧（可选）

1. 使用桌面客户端版

2. 配置多智能体协作（Subagent）

3. 配置 MCP 协议连接外部工具

常见问题 (FAQ)

总结

下一步