OpenCode 完整介绍：开源AI编程代理的破局者

curl -fsSL https://opencode.ai/install | bash

您还可以使用以下命令安装它：

• 使用 Node.js

npm install -g opencode-ai

• 在 macOS 和 Linux 上使用 Homebrew

brew install anomalyco/tap/opencode

我们使用 opencode Tap 来获取最新版本。官方 brew install opencode 公式由 Homebrew 团队建议，维护频率较低。

• 在 Arch Linux 上使用 Paru

paru -S opencode-bin

Windows：

推荐：使用 WSL

为了在 Windows 上获得最佳体验，我们建议使用 Windows Subsystem for Linux (WSL)。它提供了更好的性能并与 opencode 的功能完全兼容。

• 使用 Chocolatey

  choco install opencode
  

• 使用 Scoop

  scoop install opencode
  

• 使用 npm

  npm install -g opencode-ai
  

• 使用 Mise

  mise use -g github:anomalyco/opencode
  

• 使用 Docker

  docker run -it --rm ghcr.io/anomalyco/opencode
  

目前正在支持在 Windows 上安装 opencode 时使用 Bun。

您还可以从 Releases 获取二进制文件。

配置：

借助 opencode，你可以通过配置 API 使用任意 LLM 提供商。

如果你刚开始使用 LLM 提供商，我们建议使用 OpenCode Zen。 这是经过 opencode 团队测试和验证的精选模型列表。

1. 在 TUI 中运行 /connect 命令，选择 opencode，然后前往 opencode.ai/auth。

   /connect
   

2. 登录，添加您的账单信息，然后复制您的详细 API 密钥。
3. 粘贴您的 API 密钥。

   ┌ API key
   
   │
   
   │
   
   └ enter
   

初始化

现在您已经配置了提供商，您可以导航到一个项目 你想继续工作。

cd /path/to/project

并运行 opencode。

opencode

接下来，通过运行以下命令来初始化项目的 opencode。

/init

这涉及 opencode 分析您的项目并在以下位置创建 AGENTS.md 文件 项目根。

提示 

您应该将项目的 AGENTS.md 文件提交到 Git。

这有助于 opencode 理解项目结构和使用的编码模式。

五、定制与扩展：Skills 系统（真正的“Agent”灵魂）

（一）、Skills 核心认知

1.1 定义

OpenCode 不只是工具，它是一个可以编程的AI执行框架。Skills 是让AI学会完成特定任务的教学包。

**Skills 是一种应用于 AI 编程工具（如 Claude Code、Codex 等）和智能助手的“技能插件”或“能力包”。**其本质是将特定的“经验”、“流程”和“知识”封装成可复用、可迁移的指令、脚本与资源文件。你可以将其理解为 AI 的“专业技能库”或“插件系统”。

官方skills仓库：https://github.com/anthropics/skills

1.2 它解决了什么痛点？

核心价值

• 提升稳定性与专业性：让 AI 在处理特定任务（如 PDF 处理、视频剪辑、代码审查）时表现得更专业、更稳定，减少“幻觉”。
• 降本增效：通过按需加载机制，减少无意义的 Token 消耗和重复的上下文输入，显著提升执行效率。
• 知识沉淀与共享：支持将领域知识沉淀为资产，通过 Git 等方式在团队间共享工作流程和最佳实践。

1.3 行业地位与标准

Skills 最初由 Anthropic 开发，现已成为 Agent Skills 开放标准，OpenCode、Claude Code、CodeX、Cursor、扣子（Coze）均已全面兼容。同一份技能文件夹可在多平台复用 。

（二）、Skills 长什么样？

每个 Skill 本质上是一个文件夹，必须包含以下结构：

my-skill/                # 文件夹名 = 技能名（必须与SKILL.md中name一致）
├── SKILL.md            # 唯一必需文件：指令 + YAML 前置元数据
├── references/         # 可选：参考文档、模板、规范手册（按需加载）
├── scripts/            # 可选：可执行脚本（Python/Bash/Node等）
└── assets/             # 可选：图片、模板资源

SKILL.md 完整规范（必读）

---
name: your-skill-name        # 必须：小写字母+数字+连字符，与目录名一致
description: 简要描述此技能的功能及何时使用它（至少20字符，第三人称）
license: MIT                 # 可选
compatibility: OpenCode >=1.1.36  # 可选
metadata:                   # 可选
  author: your-name
  version: "1.0"
allowed-tools: read write   # 可选：预批准工具（实验性）
---

# 技能名称

## 指令
[清晰、分步的操作流程，AI将严格遵循]

## 示例
[输入输出样例，帮助AI理解期望结果]

字段硬约束 ：

• name：1-64字符；仅小写字母、数字、连字符；不能首尾连字符；必须与父目录名完全一致 → 不符合则技能不被加载
• description：1-1024字符；必须用第三人称（✅“处理PDF文件” ❌“我可以帮你处理PDF文件”）

（三）、Skills 存放在哪里？（作用域与安装位置）

OpenCode 按以下优先级顺序搜索技能（项目技能 > 个人技能 > 插件技能）：

同名覆盖规则：项目技能 > 个人技能 > 插件技能。若.opencode/skills/与~/.config/opencode/skills/下有同名技能，前者生效 。

Windows 路径对照 ：

• 个人技能：C:\Users\你的用户名\.config\opencode\skills\
• 项目技能：你的项目\.opencode\skills\

（四）、Skills 安装：四大主流路径全解

根据你的使用习惯和场景，选择以下任意一种即可。不是都要装。

路径一：原生手动安装（最基础，无需插件）

适合场景：你已从 GitHub 下载了现成技能文件夹，或想手工创建自己的第一个技能。

操作步骤：

1. 确定作用域（二选一）：

   # 全局安装（所有项目可用）
   mkdir -p ~/.config/opencode/skills/<your-skill-name>
   
   # 项目安装（仅当前项目）
   mkdir -p .opencode/skills/<your-skill-name>
   

2. 放入 SKILL.md 文件：

   # 将编写好的SKILL.md放入该目录
   cp /path/to/your/SKILL.md ~/.config/opencode/skills/<your-skill-name>/
   

3. 重启 OpenCode，技能自动发现 。

优点：零依赖，完全可控。
注意：目录名必须与SKILL.md中name字段完全一致，且文件名必须全大写SKILL.md 。

路径二：@pi0/skills —— 跨工具通用安装器（强烈推荐）

适合场景：从 GitHub 一键拉取现成技能，支持 26+ 种 AI 工具（OpenCode、Claude Code、Cursor等）。

安装与使用：

# 直接安装GitHub仓库中的所有技能（自动识别当前工具为OpenCode）
npx skills add vercel-labs/agent-skills

# 仅安装特定技能
npx skills add anthropics/skills --skill skill-creator --skill pdf-processing

# 安装到全局目录（所有项目可用）
npx skills add anthropics/skills -g

# 安装前预览有哪些技能
npx skills add anthropics/skills --list

安装位置规则：

• 不加-g → 安装到 当前项目 .opencode/skills/
• 加-g → 安装到 全局 ~/.config/opencode/skills/

优点：一行命令完成下载+放置，自动处理目录结构，无需手动复制。
官方技能仓库：https://github.com/anthropics/skills（含 PDF处理、Excel、skill-creator等）。

路径三：skill-creator —— 元技能安装（AI引导创建）

适合场景：你不清楚如何编写SKILL.md，希望通过对话让AI帮你生成。

安装 skill-creator（二选一）

方法A：通过@pi0/skills一键安装（推荐）

npx skills add anthropics/skills --skill skill-creator -g

方法B：手动放置

1. 下载官方skills仓库：https://github.com/anthropics/skills
2. 将 skills/skill-creator 整个文件夹复制到：

   # 全局技能目录
   ~/.config/opencode/skills/skill-creator/
   

使用验证

重启 OpenCode，提问：

使用 skill-creator 帮我创建一个新的 Skill，目标是：管理待办事项清单

AI 将通过对话引导你完成技能名称、触发词、指令步骤的定义，自动生成标准 SKILL.md 并放入正确目录 。

优点：零门槛，新手友好，生成的技能格式规范。

路径四：插件式安装（高级技能管理）

适合场景：你需要按需加载、多模型格式适配、技能连招编排等企业级能力。主要有两个插件：

1. @zenobius/opencode-skillful —— 轻量级技能管理

特性 ：

• 懒加载：技能不预占上下文，仅在使用skill_use时注入
• 多模型格式：可为 Claude、GPT 分别配置 XML/JSON/Markdown 输出格式
• 安全资源访问：通过skill_resource读取参考文件

安装：

npm install @zenobius/opencode-skillful@1.2.2-next.2

编辑 ~/.config/opencode/config.json：

{
  "plugins": ["@zenobius/opencode-skillful"]
}

重启生效。获得三个核心工具：skill_find、skill_use、skill_resource 。

2. Superpowers —— 工作流级技能连招

特性 ：

• 技能编排：头脑风暴 → 写方案 → 执行 → 验证，形成完整工作流
• 上下文压缩恢复：会话清理后自动重新注入技能
• Claude Code 技能自动适配 OpenCode

安装：

# 克隆仓库
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers

# 创建插件软链接
mkdir -p ~/.config/opencode/plugin
ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js

# Windows PowerShell：
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugin\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugin\superpowers.js" -Force

使用 ：

# 查找技能
use find_skills tool

# 加载技能
use use_skill tool with skill_name: "superpowers:brainstorming"

（五）、安装后验证

方法1：直接询问AI 在 OpenCode 中输入：

我能使用什么skills？

AI 会列出当前已发现的所有技能及其描述 。

方法2：查看日志（插件场景）

opencode run "test" --print-logs --log-level DEBUG | grep skill

查找 discovered skill、loading plugin 等关键词 。

六、总结

核心价值：OpenCode 是开源、模型无关的 AI 编程代理，核心优势在于多模型自由切换、多专业化代理协同工作，且通过 Plan/Build 双模式分离 “思考” 与 “执行”，兼顾效率与代码安全，适配个人开发到企业合规部署的全场景。

部署与使用：支持本地安装（一键脚本 / 包管理器）、Docker 容器化（开发 / 生产环境差异化配置）、K8s 部署（进阶自动化集成）三种主流方式，所有部署均需完成/connect配置模型、/init初始化项目两大核心步骤，确保 AI 适配项目上下文。

定制化核心：Skills 系统是 OpenCode 的灵魂，通过标准化文件夹封装任务规则，支持手动安装、一键拉取、AI 生成、插件管理四种方式，可将通用 AI 编程助手定制为符合团队规范的专属工具，实现一次封装、随处复用。