版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

手打不易，如果转摘，请注明出处！
本文链接：
https://zhangxiaofan.blog.csdn.net/article/details/161698399

---

---

背景

随着AI技术的飞速发展，AI编程工具已成为开发者的必备神器。市面上涌现出众多AI编程助手，如OpenAI Codex、Claude Code、Cursor等，它们各有特色，但大多存在一个共同问题：不够开放。

要么是闭源商业产品（如Cursor），要么是协议不明确（如Claude Code），这让很多开发者在使用时心存顾虑：

• 能否用于商业项目？
• 能否自由修改和扩展？
• 能否集成到自己的产品中？

而OpenCode的出现，完美解决了这些问题。它不仅功能强大，更重要的是——真正开源。

本文将详细介绍OpenCode这款开源AI编程工具，包括它的开源优势、基础使用教程、核心功能特性，帮助开发者快速上手。

先说结论

OpenCode是目前GitHub上最受欢迎的开源AI编程工具，拥有169,839个Star（约17万），采用MIT开源协议，完全商业友好。

相比其他AI编程工具，OpenCode的核心优势在于：

一句话总结：OpenCode是真正的开源王者，Star数最高、协议最开放、社区最活跃，是开发者首选的AI编程工具。

OpenCode开源优势详解

GitHub数据一览

OpenCode的GitHub仓库数据令人印象深刻：

核心数据：

• 仓库地址：https://github.com/anomalyco/opencode
• Star数量：169,839（GitHub AI编程工具类目第一）
• Fork数量：20,320
• 开源协议：MIT License（完全开源，商业友好）
• 主要语言：TypeScript
• 创建时间：2025年4月30日
• 官网：https://opencode.ai

社区活跃度指标：

• 贡献者数量：100+ 位活跃贡献者
• 最近一周提交：182次（高度活跃）
• 开放Issue数量：6,605个（社区讨论热烈）
• 下载量：最新版本下载量超过30万次

为什么OpenCode是真正的开源？

MIT协议的商业自由：

MIT协议是最宽松的开源协议之一，它允许：

• ✅ 商业使用无限制
• ✅ 可自由修改和分发
• ✅ 可集成到商业产品中
• ✅ 无需付费授权
• ✅ 可私有化部署

对比其他工具的局限：

工具	协议类型	商业使用	私有部署	自由修改
OpenCode	MIT	✅ 无限制	✅ 支持	✅ 支持
Claude Code	无明确协议	⚠️ 受限	⚠️ 不明确	⚠️ 不明确
Cursor	闭源	❌ 商业产品	❌ 不支持	❌ 不支持
OpenAI Codex	Apache-2.0	✅ 支持	✅ 支持	✅ 支持（需声明）

社区活跃度对比：

OpenCode的社区活跃度远超其他工具：

• 每周182次提交 vs Claude Code（中等）vs Cursor（低）
• 100+贡献者 vs Cursor（闭源无贡献者）
• 6,605个开放Issue显示社区参与度极高

OpenCode的核心竞争力

1. Star数量领先
169,839个Star，远超Claude Code（13万）、OpenAI Codex（8.9万）、Cursor（3.3万），显示社区认可度最高。

2. 真正的开源
MIT协议，比Claude Code（无明确协议）和Cursor（闭源）更开放，真正实现"开源"二字。

3. 社区最活跃
每周182次提交，100+贡献者，远超Codex和Cursor，显示项目生命力旺盛。

4. 商业友好
MIT协议允许商业使用，而Cursor是商业闭源产品，Claude Code协议不明，OpenCode是最佳选择。

5. 插件生态丰富
支持 superpowers-zh 等技能框架，可扩展性强，社区驱动的插件开发。

6. 快速迭代
v1.15.13版本持续更新，响应社区需求迅速，每周都有新功能和优化。

OpenCode基础使用教程

安装步骤

OpenCode支持多种安装方式，适应不同开发者的需求。

方式一：官方安装包（推荐）

Windows安装：

1. 访问官网下载页面：https://opencode.ai/download
2. 选择Windows版本（.exe安装包）
3. 双击安装包，按照提示完成安装
4. 安装完成后，在命令行验证：

# ===== 验证安装 =====
opencode --version

# ===== 预期输出 =====
OpenCode v1.15.13

macOS安装：

# ===== 使用Homebrew安装 =====
brew install opencode

# ===== 或者下载.dmg安装包 =====
# 从官网下载：https://opencode.ai/download
# 双击.dmg文件，拖拽到Applications文件夹

# ===== 验证安装 =====
opencode --version

Linux安装：

# ===== Debian/Ubuntu =====
wget https://opencode.ai/download/opencode_latest.deb
sudo dpkg -i opencode_latest.deb

# ===== Fedora/RHEL =====
wget https://opencode.ai/download/opencode_latest.rpm
sudo rpm -i opencode_latest.rpm

# ===== AppImage（通用） =====
wget https://opencode.ai/download/opencode_latest.AppImage
chmod +x opencode_latest.AppImage
./opencode_latest.AppImage

# ===== 验证安装 =====
opencode --version

方式二：通过配置文件安装插件

OpenCode支持通过配置文件安装增强插件，如superpowers-zh（中文增强版）。

步骤：

1. 创建或编辑 opencode.json 配置文件（全局或项目级）

{
  "plugin": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git"]
}

2. 重启OpenCode，插件会通过Bun自动安装并注册所有skills

3. 验证插件加载：

# ===== 在OpenCode中询问 =====
问AI："告诉我你有哪些 superpowers"

# ===== 预期输出 =====
AI会列出所有已加载的skills，包括：
- 头脑风暴（brainstorming）
- 编写计划（writing-plans）
- 测试驱动开发（test-driven-development）
等

方式三：手动安装

# ===== 克隆superpowers-zh仓库 =====
git clone https://github.com/jnMetaCode/superpowers-zh.git

# ===== 复制skills到项目目录 =====
cd your-project
mkdir -p .opencode/skills
cp -r superpowers-zh/skills/* .opencode/skills/

# ===== 验证安装 =====
# 在OpenCode中使用skill工具列出skills

方式四：使用npx一键安装

# ===== 进入项目目录 =====
cd /your/project

# ===== 使用npx安装 =====
npx superpowers-zh

# ===== 验证安装 =====
# 检查.opencode/skills目录是否创建成功
ls .opencode/skills

基本命令

OpenCode提供了丰富的命令行工具和交互式界面。

启动OpenCode

# ===== 启动交互式界面 =====
opencode

# ===== 启动并指定工作目录 =====
opencode --workdir /path/to/project

# ===== 启动并加载特定配置 =====
opencode --config /path/to/opencode.json

基本交互命令

在OpenCode交互式界面中，可以使用以下命令：

# ===== 查看帮助 =====
/help

# ===== 列出可用skills =====
use skill tool to list skills

# ===== 加载特定skill =====
use skill tool to load superpowers/brainstorming

# ===== 查看当前配置 =====
/config

# ===== 查看日志 =====
/logs

# ===== 退出OpenCode =====
/exit

文件操作命令

OpenCode支持丰富的文件操作：

# ===== 读取文件 =====
read /path/to/file

# ===== 编辑文件 =====
edit /path/to/file

# ===== 创建文件 =====
write /path/to/file

# ===== 搜索文件 =====
glob pattern="**/*.js"

# ===== 搜索内容 =====
grep pattern="function.*async"

配置详解

全局配置文件

全局配置文件位于：~/.config/opencode/opencode.json

{
  "plugin": [
    "superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git"
  ],
  "model": "default",
  "temperature": 0.7,
  "maxTokens": 4000,
  "logLevel": "info"
}

项目级配置文件

项目级配置文件位于：项目根目录/.opencode/opencode.json

{
  "plugin": [
    "project-specific-plugin"
  ],
  "workdir": "./src",
  "exclude": [
    "node_modules",
    "dist",
    "*.test.js"
  ]
}

Skill优先级

OpenCode的skill加载遵循优先级规则：

优先级	来源	说明
最高	项目skills	.opencode/skills/ 目录中的skills
中等	个人skills	~/.config/opencode/skills/ 目录中的skills
最低	Superpowers skills	通过插件加载的skills

注意：
① 同名skill会被高优先级的覆盖
② 项目skills适合团队共享的工作流
③ 个人skills适合个人习惯的开发模式

配置国产AI模型

OpenCode支持配置多种国产AI模型，包括DeepSeek、通义千问（Qwen）、智谱GLM等。通过灵活的provider配置，开发者可以根据需求选择最适合的模型。

DeepSeek模型配置

DeepSeek是国内领先的AI模型提供商，提供高性价比的推理模型。

配置步骤：

1. 获取API Key：访问 https://platform.deepseek.com/ 注册并获取API Key

2. 设置环境变量：

# ===== Windows（PowerShell） =====
$env:DEEPSEEK_API_KEY="your-deepseek-api-key"

# ===== macOS/Linux =====
export DEEPSEEK_API_KEY="your-deepseek-api-key"

3. 在 opencode.jsonc 中添加provider配置：

{
  "provider": {
    "zj-deepseek-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "DeepSeek API",
      "options": {
        "baseURL": "https://api.deepseek.com/v1",
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      },
      "models": {
        "deepseek-v4-pro": {
          "name": "zj-deepseek-v4-pro-max",
          "description": "思考模式,最大上下文 1M,最大输出 384K,3元_6元/百万tokens",
          "limit": {
            "context": 1000000,
            "output": 384000
          },
          "options": {
            "reasoning_effort": "max",
            "thinking": {
              "type": "enabled"
            }
          }
        },
        "deepseek-v4-flash": {
          "name": "zj-deepseek-v4-flash-max",
          "description": "思考模式,最大上下文 1M,最大输出 384K,1元_2元/百万tokens",
          "limit": {
            "context": 1000000,
            "output": 384000
          },
          "options": {
            "reasoning_effort": "max",
            "thinking": {
              "type": "enabled"
            }
          }
        }
      }
    }
  }
}

注意：
① DeepSeek支持"思考模式"，通过 thinking.type: "enabled" 开启
② reasoning_effort: "max" 表示最大推理强度
③ 1M上下文长度适合处理大型代码文件

通义千问（Qwen）模型配置

通义千问是阿里云推出的大语言模型，提供稳定的API服务。

配置步骤：

1. 获取API Key：访问 https://dashscope.console.aliyun.com/ 注册并获取API Key

2. 设置环境变量：

# ===== Windows（PowerShell） =====
$env:DASHSCOPE_API_KEY="your-dashscope-api-key"

# ===== macOS/Linux =====
export DASHSCOPE_API_KEY="your-dashscope-api-key"

3. 在 opencode.jsonc 中添加provider配置：

{
  "provider": {
    "zj-qwen-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Qwen API",
      "options": {
        "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "{env:DASHSCOPE_API_KEY}"
      },
      "models": {
        "qwen3.6-plus": {
          "name": "zj-qwen3.6-plus",
          "description": "最大上下文 991K,最大输出 64K,2元_12元/百万tokens"
        }
      }
    }
  }
}

注意：
① Qwen使用阿里云DashScope API，需要阿里云账号
② 兼容OpenAI API格式，易于集成
③ 适合处理中等规模的代码文件

智谱GLM模型配置

智谱GLM是清华系AI公司智谱AI推出的大语言模型，在国内具有领先地位。

配置步骤：

1. 获取API Key：访问 https://open.bigmodel.cn/ 注册并获取API Key

2. 设置环境变量：

# ===== Windows（PowerShell） =====
$env:GLM_API_KEY="your-glm-api-key"

# ===== macOS/Linux =====
export GLM_API_KEY="your-glm-api-key"

3. 在 opencode.jsonc 中添加provider配置：

{
  "provider": {
    "zj-glm-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "GLM API",
      "options": {
        "baseURL": "https://open.bigmodel.cn/api/paas/v4",
        "apiKey": "{env:GLM_API_KEY}"
      },
      "models": {
        "glm-5.1": {
          "name": "zj-glm-5.1",
          "description": "最大上下文 200k,最大输出 128K,6元_24元/百万tokens"
        }
      }
    }
  }
}

注意：
① GLM-5.1是智谱AI最新一代模型，代码生成能力强
② 适合需要高质量输出的复杂编程任务
③ 相比DeepSeek和Qwen，价格稍高但质量更优

多模型配置示例

开发者可以同时配置多个国产AI模型，根据不同任务选择不同模型：

完整配置示例：

{
  "provider": {
    // ===== DeepSeek配置 =====
    "zj-deepseek-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "DeepSeek API",
      "options": {
        "baseURL": "https://api.deepseek.com/v1",
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      },
      "models": {
        "deepseek-v4-pro": {
          "name": "zj-deepseek-v4-pro-max",
          "description": "思考模式,最大上下文 1M,最大输出 384K,3元_6元/百万tokens",
          "limit": {
            "context": 1000000,
            "output": 384000
          }
        }
      }
    },
    // ===== 通义千问配置 =====
    "zj-qwen-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Qwen API",
      "options": {
        "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "{env:DASHSCOPE_API_KEY}"
      },
      "models": {
        "qwen3.6-plus": {
          "name": "zj-qwen3.6-plus",
          "description": "最大上下文 991K,最大输出 64K,2元_12元/百万tokens"
        }
      }
    },
    // ===== 智谱GLM配置 =====
    "zj-glm-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "GLM API",
      "options": {
        "baseURL": "https://open.bigmodel.cn/api/paas/v4",
        "apiKey": "{env:GLM_API_KEY}"
      },
      "models": {
        "glm-5.1": {
          "name": "zj-glm-5.1",
          "description": "最大上下文 200k,最大输出 128K,6元_24元/百万tokens"
        }
      }
    }
  }
}

OpenCode核心功能特性

Skills系统

Skills是OpenCode的核心特性，它允许开发者定义和加载预定义的工作流方法论。

什么是Skills？

Skills是一组预定义的工作流程和方法论，帮助AI更好地完成特定任务。每个skill包含：

• 触发条件：在什么情况下使用这个skill
• 工作流程：具体的执行步骤
• 最佳实践：推荐的做法和注意事项

常用Skills列表

OpenCode通过superpowers-zh插件提供了丰富的skills：

Skill名称	用途	触发场景
头脑风暴 (brainstorming)	需求分析→设计规格	创建功能、构建组件前
编写计划 (writing-plans)	把规格拆成可执行步骤	多步骤任务开始前
执行计划 (executing-plans)	按计划逐步实施	有书面计划需要执行时
测试驱动开发 (test-driven-development)	严格TDD：先写测试再写代码	实现功能或修复bug前
系统化调试 (systematic-debugging)	四阶段调试法	遇到bug、测试失败时
请求代码审查 (requesting-code-review)	派遣审查agent检查代码	完成重要功能后
接收代码审查 (receiving-code-review)	技术严谨处理审查反馈	收到代码审查反馈后
完成前验证 (verification-before-completion)	证据先行，必须跑验证	宣称工作完成前

如何使用Skills？

方法一：自动触发

Skills会在合适的时机自动触发。例如，当你说"我想创建一个新功能"时，brainstorming skill会自动激活。

方法二：手动加载

# ===== 在OpenCode中手动加载skill =====
use skill tool to load superpowers/brainstorming

# ===== 或者直接说明意图 =====
"我要实现一个用户认证功能，请使用brainstorming skill帮我分析需求"

创建自定义Skill

开发者可以创建自己的skill，满足特定需求。

创建个人Skill：

# ===== 创建skill目录 =====
mkdir -p ~/.config/opencode/skills/my-skill

# ===== 创建SKILL.md文件 =====

创建 ~/.config/opencode/skills/my-skill/SKILL.md：

---
name: my-skill
description: 当 [条件] 时使用 - [功能描述]
---

# 我的Skill

## 触发条件
- 条件1：具体说明
- 条件2：具体说明

## 工作流程
1. 步骤1：具体说明
2. 步骤2：具体说明

## 最佳实践
- 实践1：具体说明
- 实践2：具体说明

## 注意事项
注意：
① 第一点说明
② 第二点说明

创建项目Skill：

在项目的 .opencode/skills/ 目录中创建skill，团队成员可以共享使用。

插件架构

OpenCode的插件架构允许开发者扩展功能。

插件配置

{
  "plugin": [
    "plugin-name@git+https://github.com/user/plugin-repo.git",
    "another-plugin@npm:package-name"
  ]
}

插件推荐

oh-my-openagent
https://github.com/code-yeongyu/oh-my-openagent

@mohak34/opencode-notifier
https://github.com/mohak34/opencode-notifier

插件优先级

• 项目级插件 > 全局插件
• 后加载的插件会覆盖先加载的同名插件

工具映射

OpenCode提供了丰富的工具集，支持各种开发操作。

工具类型	工具名称	功能说明
文件操作	read, write, edit	读取、创建、编辑文件
搜索工具	glob, grep	文件搜索、内容搜索
代码分析	lsp_*	LSP相关工具（定义跳转、引用查找等）
执行工具	bash	执行bash命令
子代理	task	派遣子代理完成特定任务
Skill工具	skill	加载和列出skills

实战案例：使用OpenCode开发一个简单功能

场景描述

假设我们需要开发一个用户登录功能，包括：

• 用户输入用户名和密码
• 验证用户身份
• 返回登录结果

使用brainstorming skill分析需求

步骤1：启动OpenCode并加载skill

# ===== 启动OpenCode =====
opencode

# ===== 加载brainstorming skill =====
"我要实现用户登录功能，请使用brainstorming skill帮我分析需求"

步骤2：AI会自动引导你分析需求

OpenCode会询问：

• 登录方式（用户名/密码、OAuth、手机号等）
• 安全要求（加密、Session管理、Token等）
• 错误处理（用户不存在、密码错误、网络异常等）
• 数据存储（数据库类型、表结构等）

步骤3：生成设计规格

AI会根据你的回答生成详细的设计规格，包括：

• 功能需求列表
• 技术选型建议
• 数据结构设计
• API接口设计
• 安全考虑事项

使用writing-plans skill编写实施计划

步骤1：加载writing-plans skill

"请使用writing-plans skill，根据刚才的设计规格编写实施计划"

步骤2：AI会生成详细的实施计划

计划会包括：

1. 创建数据库表结构
2. 实现用户模型
3. 实现登录验证逻辑
4. 实现错误处理
5. 编写单元测试
6. 集成测试

使用test-driven-development skill实现功能

步骤1：加载TDD skill

"请使用test-driven-development skill实现用户登录功能"

步骤2：AI会按照TDD流程实现

// ===== 步骤1：先写测试 =====
describe('UserLogin', () => {
  test('should return success with valid credentials', () => {
    const result = login('testuser', 'password123');
    expect(result.success).toBe(true);
    expect(result.token).toBeDefined();
  });

  test('should return error with invalid credentials', () => {
    const result = login('testuser', 'wrongpassword');
    expect(result.success).toBe(false);
    expect(result.error).toBe('Invalid credentials');
  });
});

// ===== 步骤2：运行测试（预期失败） =====
// ===== 步骤3：编写最小实现代码 =====
function login(username, password) {
  // 实现登录逻辑
  if (username === 'testuser' && password === 'password123') {
    return { success: true, token: 'generated-token' };
  }
  return { success: false, error: 'Invalid credentials' };
}

// ===== 步骤4：运行测试（预期通过） =====
// ===== 步骤5：重构优化代码 =====

使用verification-before-completion skill验证完成

步骤1：加载验证skill

"请使用verification-before-completion skill验证登录功能是否完成"

步骤2：AI会执行验证步骤

• ✅ 运行单元测试，确认通过
• ✅ 运行集成测试，确认通过
• ✅ 检查代码质量（LSP diagnostics）
• ✅ 验证API接口是否正常工作
• ✅ 检查安全考虑是否到位

步骤3：生成验证报告

AI会提供详细的验证报告，包括：

• 测试覆盖率
• 代码质量指标
• 功能完整性检查
• 安全性评估

常见问题与故障排查

插件未加载

问题现象：
配置了插件但skills未生效。

排查步骤：

# ===== 检查OpenCode日志 =====
opencode run --print-logs "hello" 2>&1 | grep -i superpowers

# ===== 检查配置文件 =====
cat ~/.config/opencode/opencode.json

# ===== 确认Bun已安装 =====
bun --version

# ===== 手动重新加载插件 =====
# 删除插件缓存
rm -rf ~/.config/opencode/plugins/*
# 重启OpenCode

解决方案：
① 确保opencode.json配置正确
② 确保运行最新版本的OpenCode
③ 确保Bun已正确安装
④ 检查网络连接（插件需要从Git仓库下载）

Skills未找到

问题现象：
使用skill工具时提示skill不存在。

排查步骤：

# ===== 列出所有可用skills =====
use skill tool to list skills

# ===== 检查skill目录 =====
ls ~/.config/opencode/skills/
ls .opencode/skills/

# ===== 检查SKILL.md文件格式 =====
cat ~/.config/opencode/skills/my-skill/SKILL.md

解决方案：
① 确保skill目录结构正确
② 确保SKILL.md文件包含有效的YAML frontmatter
③ 确保skill名称在frontmatter中正确定义
④ 检查skill描述是否清晰（影响自动触发）

性能优化建议

提升OpenCode响应速度：

1. 合理配置exclude规则

{
  "exclude": [
    "node_modules",
    "dist",
    "build",
    "*.test.js",
    "*.spec.js",
    ".git"
  ]
}

2. 使用项目级配置

将通用配置放在全局，项目特定配置放在项目级，避免重复加载。

3. 定期清理缓存

# ===== 清理插件缓存 =====
rm -rf ~/.config/opencode/plugins/*

# ===== 清理临时文件 =====
rm -rf ~/.config/opencode/tmp/*

4. 选择合适的模型

根据任务复杂度选择合适的AI模型，简单任务使用快速模型，复杂任务使用高级模型。

总结

通过本文的介绍，我们详细了解了OpenCode这款开源AI编程工具。整个过程涵盖了从开源优势分析、基础使用教程、核心功能特性到实战案例等多个环节。

OpenCode的核心优势：

1. 真正的开源王者：169,839个Star，GitHub AI编程工具类目第一，社区认可度最高

2. MIT协议的商业自由：完全开源，商业友好，可自由修改、分发和集成到商业产品中

3. 活跃的社区生态：100+贡献者、每周182次提交、6,605个开放Issue，显示项目生命力旺盛

4. 插件化架构：支持superpowers-zh等技能框架，可扩展性强，社区驱动的插件开发

5. 快速迭代能力：v1.15.13持续更新，响应社区需求迅速，每周都有新功能和优化

6. Skills系统：预定义的工作流方法论，帮助AI更好地完成特定任务，提升开发效率

适用场景：

• ✅ 个人开发者：免费使用，无需付费授权
• ✅ 商业项目：MIT协议允许商业使用，无法律风险
• ✅ 团队协作：项目级skills可共享工作流程
• ✅ 企业集成：可私有化部署，集成到内部系统
• ✅ 定制开发：可自由修改源码，满足特定需求

对比其他工具的选择建议：

场景	推荐工具	原因
商业项目开发	OpenCode	MIT协议，商业友好
个人学习探索	OpenCode	完全开源，免费使用
企业内部部署	OpenCode	可私有化部署，无限制
快速原型开发	OpenCode/Claude Code	功能强大，快速上手
商业产品购买	Cursor	闭源商业产品，有官方支持

希望本文的实践能够为有类似需求的开发者提供一些参考和启发！！！

相关资源：

• OpenCode官网：https://opencode.ai
• OpenCode文档：https://opencode.ai/docs/
• GitHub仓库：https://github.com/anomalyco/opencode
• Superpowers-zh项目：https://github.com/jnMetaCode/superpowers-zh
• 插件生态：awesome-opencode

下一步行动：

1. 安装OpenCode，体验基础功能
2. 加载superpowers-zh插件，尝试不同的skills
3. 创建自定义skill，满足特定需求
4. 加入社区，参与贡献和讨论

让我们一起拥抱开源，用OpenCode提升开发效率！！！