陌阡博客

主题

OpenCode 详细攻略：开源版 Claude Code，免费模型与神级插件 ​

OpenCode 常被视为开源版的 Claude Code，核心优势在于提供开箱即用的免费模型，且对中国开发者友好，避免了原生工具可能遇到的限速或封号问题。它支持命令行、桌面端、VS Code 插件与云端协作四种运行形态，还能通过 MCP 与 Skills 扩展能力边界，配合 Oh My OpenCode 插件实现多智能体协同开发。本文从安装、模型接入、核心功能、技能扩展、插件实战到 GitHub 云端集成，整理一份完整的上手攻略。

1. OpenCode 概述与安装方式 ​

1.1 命令行版本安装（推荐） ​

命令行版本最稳定、功能最全，适合大多数开发者使用。

  1. 下载与安装：访问 Node.js 官网下载对应系统的安装包。

  2. 执行命令：打开终端（Terminal、PowerShell 或 VS Code Integrated Terminal），执行官方 npm 安装命令：

    bash
    npm install -g open-code

  3. 启动软件：输入 open code 即可直接启动。

  4. 验证配置：进入界面打招呼，若显示欢迎信息则说明配置成功。

1.2 桌面客户端安装 ​

  • 下载安装：在官网页面点击下载按钮，按向导一路点击"下一步"完成安装。
  • 使用方法：打开后选择一个文件夹作为项目根目录即可开始交互。
  • ⚠️ 注意：目前处于 Beta 测试阶段，存在较多 Bug，且功能仅为基础对话框，建议优先使用命令行版本。

1.3 VS Code 插件版安装 ​

此模式需先安装好命令行版本。

  • 安装插件：在 VS Code 扩展商店搜索 open code 并安装。
  • 启动服务：按快捷键 Ctrl+Shift+P 打开命令面板，输入 Open Code 回车。
  • 功能特点：
    • 自动关联左侧窗口打开的代码文件。
    • 选中代码后按 Ctrl+Alt+K 可快速粘贴到聊天窗口。
    • 本质上是命令行版本的图形化封装，核心逻辑仍在后台运行。

1.4 云端运行环境 ​

  • 应用场景：主要用于 GitHub 上的 Pull Request 或 Issue 自动修复。
  • 操作路径：具体配置将在下文"云端协作与 GitHub 集成"章节详细讲解。

2. 模型接入与配置指南 ​

OpenCode 内置了多款免费模型，同时也支持灵活接入外部顶级模型，实现按需分配。

2.1 使用内置免费模型 ​

无需额外配置即可直接使用，适合新手练习 AI 编程。

  • 查看列表：在终端输入命令 /models。
  • 筛选免费：寻找带有 free 标记的模型名称。
  • 推荐型号：
    • Gemini 1.5 Pro：编程能力强，响应速度快。
    • MiniMax 2.1：表现优异，零配置即可使用。
  • 操作示例：输入需求描述即可开始编程，系统会自动匹配最佳免费模型。

2.2 接入 Google 顶级模型（OpenGravity） ​

利用 OpenGravity 插件，可免费接入 Gemini 3 Pro 和 Claude Opus 4.5。

安装流程：

  1. 访问 OpenGravity 的 GitHub 首页。
  2. 复制提示词中的安装命令。
  3. 在 OpenCode 中输入该命令，等待自动安装完成。

配置登录：

  1. 复制登录命令，在新命令行窗口执行。
  2. 供应商选择 gravity，Project ID 直接回车。
  3. 登录谷歌账户，将生成的 URL 粘贴回命令行。
  4. 确认授权（输入 N 或根据提示操作）。

验证结果：重启 OpenCode 后输入 /models，可见新增的 gemini 3 pro 和 claude opus 4.5。

2.3 接入 GPT 系列模型 ​

OpenCode 已与相关厂商合作，支持直接使用 GPT 编程套餐。

  • 前提条件：拥有 ChatGPT Plus 及以上订阅。
  • 配置步骤：
    1. 在 OpenCode 中输入 /connect 找到 GPT 选项。
    2. 选择 chat gpt t 或相应模型标识。
    3. 在浏览器打开链接并继续登录。
  • 使用效果：登录后输入 /models 即可选择 GPT 系列模型进行开发。

2.4 接入 OpenRouter（通用方案） ​

通过 OpenRouter 可以接入市面上几乎所有类型的大模型。

  • 获取 Key：前往 OpenRouter 官网点击 Get API 创建密钥。
  • 配置 OpenCode：
    1. 输入 /connect 找到 open router。
    2. 填写复制的 API Key。
  • 优势：国内用户也可方便获取额度，几乎囊括所有模型供应商。

3. 核心功能深度解析 ​

OpenCode 不仅是一个对话窗口，更具备完整的开发工作流管理能力。

3.1 Session 会话管理 ​

每次对话都是一个独立的 Session，支持并行开发和任务隔离。

  • 新建会话：输入 /new 命令创建新上下文。
  • 并行开发：
    • 场景示例：为一个游戏增加"计时器"功能和"画笔颜色调整"功能。
    • 操作：在执行第一个需求时，输入 /new 开启第二个 Session 处理另一需求。
    • 状态监控：输入 /c 可查看当前 Session 状态（转圈符号表示后台运行中）。
    • 切换：在不同 Session 间互相切换查看进度。
  • 优势：避免上下文污染，提高复杂任务的并发处理能力。

3.2 对话记录共享与导出 ​

便于团队协作或复盘代码修改过程。

  • 网页分享：输入 /share 生成唯一网页链接并自动复制到剪贴板，内容包含 AI 对话记录与文件修改详情；输入 /unshare 可使链接失效。
  • 文件导出：输入 /export 将对话记录保存为本地文件。

3.3 时间线与代码回退 ​

强大的版本控制能力，允许随时回退代码状态。

  • 查看历史：输入 /timeline 查看当前 Session 内的所有对话节点。
  • 回退操作：
    1. 选择任意历史对话时间点。
    2. 使用 rewind 功能（或类似回退命令）。
    3. 代码和聊天内容将恢复到该时刻状态。
  • 价值：试错成本低，可随时撤销错误修改或重新尝试不同方案。

3.4 交互式开发流程 ​

OpenCode 在任务规划上展现出极高的智能化水平。

  • 反向询问：开始编码前，AI 会主动询问需求细节（如是否需要完整程序、必须实现的功能、环境变量设置等）。
  • 分步计划：列出详细的开发计划（To-Do List），每完成一步标记为完成。
  • 对比界面：命令行版本拥有优秀的代码比对界面，能清晰展示变更内容。
  • 一次成型：在测试案例中，未出现返工情况，一次性完成需求开发。

4. MCP 与 Skills 技能扩展 ​

通过 MCP（Model Context Protocol）和 Skills 文件夹，可以极大扩展 OpenCode 的能力边界。

4.1 Skills 技能包迁移 ​

Skill 本质上是带有目录结构的说明书，用于指导 AI 工作。

  • 迁移方法：
    1. 找到原有 .claude 目录下的 skills 文件夹。
    2. 重命名为 .opencode，并在项目中建立 skills 子文件夹。
    3. 将技能文件夹直接复制进去。
  • 激活方式：
    1. 在终端输入 open code 启动。
    2. 询问"你有哪些 Skills"，系统会列出已加载的技能。
    3. 遇到相关需求时，AI 会自动调用这些文档辅助工作。

4.2 MCP 配置详解 ​

MCP 分为本地执行和远程调用两种模式，配置文件位置为 ~/.config/open-code/open-code.json。

  • 本地模式（Local）：
    • 配置示例：设置 type 为 local。
    • 参数：指定 command 为本地可执行脚本（如 xh）。
    • 启用：添加 enable: true。
  • 远程模式（Remote）：
    • 配置示例：设置 type 为 remote。
    • 参数：填写 url 地址（如 Context7 的接口地址）。
    • 认证：在 header 中填写 API Key。
  • 验证配置：重启软件后输入 /mcp，查看是否识别到新配置的工具。

5. Oh My OpenCode 插件实战 ​

这是一个集成了工具链、MCP 和智能体的超级插件，旨在最大化 AI 编程潜力。

5.1 插件安装与初始化 ​

  • 安装方式：复制 GitHub 首页的 install 提示词，在 OpenCode 中粘贴执行。
  • 配置问卷：
    • 询问是否有 Claude 订阅（回答 No）。
    • 询问是否有 GPT 订阅（回答 Yes，用于替代模型）。
    • 确认后自动完成安装。
  • 模型调整：
    • 修改 ~/.config/open-code/open-code.json 中的模型配置。
    • 例如：将主智能体 Sisyphus 的模型替换为 gpt-4o。

5.2 七大智能体体系 ​

插件内置了分工明确的智能体团队，每个都有专属模型。

  • Sisyphus（西西弗斯）：主智能体，负责规划与调度（推荐使用最强模型）。
  • Oracle（先知）：架构设计、代码评审。
  • Librarian（图书管理员）：文献查阅。
  • Explorer（探索者）：网络搜索。
  • Frontend Engineer（前端工程师）：使用 Gemini 3 Pro 等前端强模型。
  • Documentation Writer（文档编写者）：文档生成。
  • Multimodal（多模态）：处理图片/PDF 信息。

5.3 核心工作模式 ​

  • 普通模式：输入 @智能体名称 指定特定专家干活。
  • UltraWork 模式：
    • 触发：输入魔法词 W 或 ultra work。
    • 机制：全潜能调用，将任务拆分为 To-Do List，多个智能体并行执行。
    • 案例：构建宠物商店应用，自动分配 UI、逻辑、动画任务，最终生成清晰界面与交互。
  • RalphLoop 模式：
    • 触发：输入 /ralloo。
    • 用途：强制长时间循环，针对高难度任务持续工作。
    • 场景：使用 Spring 4 标准重构项目，直到所有测试用例通过。

6. 云端协作与 GitHub 集成 ​

OpenCode 可直接集成到 GitHub 工作流中，实现自动化代码审查与修复。

6.1 仓库准备 ​

  • 上传代码：将本地项目推送到 GitHub，设为公开仓库（Public）。
  • 触发指令：在仓库代码文件夹中执行安装命令。

6.2 模型与密钥配置 ​

  • 选择提供商：安装过程中选择 API 提供商（如 Google）。
  • 提交配置文件：将准备好的配置文件提交至 GitHub。
  • 设置 Secrets：
    1. 进入仓库 Settings > Secrets and Variables > Actions。
    2. 添加密钥变量（如 GOOGLE_API_KEY）。
    3. 值从 Google AI Studio 获取并填入。

6.3 自动化工作流演示 ​

  • 模拟 Bug：用户在 Issue 中提出导航栏重复功能问题。
  • 执行修复：
    1. 在 Issue 下评论 /open code 指令。
    2. 触发 GitHub Actions，OpenCode 在云端运行。
    3. 自动分析代码并生成修复方案。
  • 合并代码：
    1. 检查生成的 Pull Request（PR）。
    2. 查看 File Changes，确认修改无误。
    3. 点击 Merge 按钮完成合并，Issue 自动关闭。

7. 自定义命令与智能体 ​

OpenCode 支持高度自定义，允许定义专属命令和角色。

7.1 自定义命令（Commands） ​

  • 创建位置：在配置文件夹中新建 commands 目录。
  • 文件格式：使用 Markdown 文件命名。
  • 配置内容：
    • 指定模式：build 或 plan。
    • 命令描述：明确该命令的作用。
    • 实际指令：定义具体的执行逻辑。
  • 使用方式：输入 /命令名 即可运行。

7.2 自定义智能体（Agents） ​

  • 创建位置：在配置文件夹中新建 agents 目录。
  • 文件定义：Markdown 格式，包含以下字段：
    • 描述：智能体的职能。
    • 类型：primary（主智能体，可按 Tab 切换）或 sub-agent（子智能体，后台调度）。
    • 模型：指定该智能体使用的 LLM。
  • 应用场景：
    • 定义 Code Reviewer 智能体，专门负责代码审查。
    • 切换到主智能体时，可自动调用后台子智能体协助完成任务。

8. 常见坑与排查 ​

以下是使用 OpenCode 过程中可能遇到的常见问题与建议排查方向：

问题现象可能原因解决方案
客户端无法启动处于 Beta 测试期 Bug 较多建议改用命令行版本，稳定性更高
模型连接失败API Key 错误或网络限制检查 OpenRouter API Key 有效期，使用代理网络
GitHub Action 报错环境变量缺失确认 Repository Secrets 已正确填入且名称一致
MCP 配置不生效JSON 格式错误检查配置文件逗号、引号，确保无多余字符
技能未加载目录结构错误确认 .opencode/skills 目录存在且包含有效文件
插件安装卡住网络超时耐心等待或重试，确保复制的命令完整
📖本文阅读--次|📊全站访问--次|👥访客--人