🚀 OpenCode 实战配置指南：从零到一把真正能干活的 AI 利刃

作者：Q 师傅

基于 3 个月真实项目经验，跨 6 个项目类型、解决 20+ 实际问题后的配置沉淀

2026-05-15

一、前言

OpenCode 是一个开源的 AI 编程助手（Claude Code 的开源平替），但它不像 IDE 插件那样开箱即用。要让 OpenCode 真正"能干重活"，需要正确配置 Skills、MCP 服务、插件三件套。

本文基于实际使用经验，记录完整配置方案、踩坑记录和最佳实践。

二、整体架构

OpenCode 利刃三件套
├── 📦 Skills（技能包）      → 告诉 AI 怎么干活
├── 🔌 MCP（模型上下文协议）  → 让 AI 能调用外部服务
└── ⚡ Plugins（插件）       → 扩展 OpenCode 本身能力

三、Skills 配置详解

3.1 什么是 Skills？

Skills 是 SKILL.md​ 文件，放在 ~/.config/opencode/skills/<技能名>/ 目录下。OpenCode 启动时自动发现并加载。每个 Skill 包含一段结构化指令，告诉 AI 在什么场景下用什么方式解决问题。

3.2 我的全局 Skills 清单

🧠 思维类

实战经验：

• ​brainstorming​ 是强制前置的 — SKILL.md 里写着 "MUST use before creative work"。AI 会主动追问需求细节，避免"写出来才发现不对"
• ​self-improvement 会自动记录踩坑，下次会话就不用再踩同一个坑。比如 Halo external-url 的错误就自动记住了

踩坑：不要安装大量不用的 skills，每个 skill 都会增加 AI 的上下文负担。只装确实需要的。

🛠️ 工具类

实战经验：

• ​find-skills​ + skill-creator 是黄金搭档：先搜有没有现成的，没有再自己创
• ​ontology 适合需要维护实体关系的项目（如设备管理系统里的设备 → 位置 → 维修记录）

📄 文档类

实战经验：

• ​document-pro 在处理中文 PDF 时效果很好（配合 pytesseract）
• ​frontend-design 自动避免"AI 风格"的千篇一律 UI

🔧 基础设施

实战经验：

• ​powershell-reliable​ 解决了一个大坑：PowerShell 的 &&​ 不支持、cd 坏掉了、复杂引号会炸——这个 skill 让 AI 用正确的姿势执行命令
• ​gstack（Garry Tan 的 96K star 项目）提供浏览器自动化能力，适合 QA 测试

⚡ Superpowers（插件式）

Superpowers 通过 opencode.json 的 plugin 机制安装：

{
  "plugin": [
    "oh-my-openagent@latest",
    "superpowers@git+https://github.com/obra/superpowers.git"
  ]
}

四、MCP 配置

MCP（Model Context Protocol）让 AI 能直接调用外部服务。

我的 MCP 配置

{
  "mcp": {
    "wordpress": {
      "type": "local",
      "command": ["npx", "-y", "wpmcp"],
      "environment": {
        "WORDPRESS_URL": "https://www.greatqiu.cn",
        "WORDPRESS_USERNAME": "admin",
        "WORDPRESS_PASSWORD": "eyJ0eXAi..."
      }
    }
  }
}

实战价值

踩坑记录

1. WordPress JWT Token 有效期约 30 天 — 过期后需要在 WP 后台生成新的 Application Password
2. Playwright "Browser is already in use" — 同一个浏览器实例不能同时跑多个操作，需要等待前一个完成
3. MCP 环境变量里的密码 — 注意安全，不要提交到 git

五、插件配置

oh-my-openagent

这个插件增强 OpenCode 的 agent 能力，提供更好的任务管理和子 agent 调度。

superpowers

Obra Superpowers 是通过 plugin 机制安装的技能包，包含：

• ​brainstorming — 动手前先想清楚
• ​writing-plans — 拆解任务为 2-5 分钟步骤
• ​subagent-driven-development — 并行子 agent 执行
• ​test-driven-development — 红绿重构 TDD
• ​systematic-debugging — 系统性调试
• ​verification-before-completion — 交付前验证

六、完整配置总览

~/.config/opencode/
├── opencode.json              # 主配置（MCP + 插件）
└── skills/
    ├── brainstorming/         # 需求探索（必须前置）
    ├── document-pro/          # PDF/DOCX 解析
    ├── find-skills/           # 搜索社区技能
    ├── frontend-design/       # 前端 UI 设计
    ├── gstack/                # 浏览器 QA
    ├── high-order-thinking/   # 四维决策
    ├── ontology/              # 知识图谱
    ├── powershell-reliable/   # Win PowerShell
    ├── self-improvement/      # 教训沉淀
    └── skill-creator/         # 创建自定义技能

七、实测效果

解决的问题类型

一个典型的高效会话

1. brainstorming → 澄清需求（避免写偏）
2. find-skills → 检查有没有现成的技能
3. 没有现成的 → skill-creator 创建临时 skill
4. 干活（借助 powershell-reliable 等基础设施 skill）
5. self-improvement → 记录踩坑
6. 验证（gstack QA 或 Playwright）

八、避坑总结

九、总结

OpenCode 的威力不在于它本身，而在于你怎么配置它。Skills + MCP + Plugins 三件套配好，它就从一个"能写代码的 AI"变成了"一个真正能干活的全能助理"。

核心原则：

1. Skills 求精不求多 — 每个 skill 都要有明确的触发场景
2. MCP 选真的需要的 — 不要为了装而装
3. self-improvement 是最重要的 skill — 它会让你每次会话都比上次更聪明

本文由 OpenCode AI (Sisyphus - Claude Opus 4.7) 基于真实项目经验编写

一、从零开始 vs 站在巨人肩膀

❌ 旧模式：从零开始

需求 → 自己搭框架 → 自己写CRUD → 自己写API → 自己搞后台
→ 3个月后还在折腾基础功能 → 遇到bug自己修
→ 一个人干一个团队的活

✅ 新模式：站在巨人肩膀

选平台（带 CLI / API / MCP）→ 声明式配置
→ AI 直接调 API 完成业务
→ 1周出功能，1个月出产品
→ 只写业务逻辑，不写基础设施

二、我的"带 CLI/API"平台选择清单

🔥 主力平台

💡 选择标准

一个平台值不值得用，看三个指标：

1. 有没有 CLI → 能不能在终端里操控？

   • ✅ wp post list​、halo post list
   • ❌ 只能点鼠标的就算了

2. 有没有 API → AI 能不能直接调？

   • ✅ RESTful API + Token 鉴权
   • ❌ 只有前端页面的就算了

3. 有没有 MCP / SDK → AI 能不能原生集成？

   • ✅ WordPress MCP（最佳！AI 直接管理站点）
   • ✅ Halo Console API（IP 直连绕过 WAF）
   • ❌ 只能人肉操作的就放弃

三、全局 Skills vs 项目 Skills 的划分

全局 Skills（一次安装，到处可用）

~/.config/opencode/skills/
├── brainstorming/          # 思维方式 → 任何项目都需要
├── powershell-reliable/   # 基础设施 → Windows 都需要
├── self-improvement/      # 学习能力 → 永远需要
└── ...

原则：跟具体技术栈无关的能力放全局。

项目 Skills（跟着项目走）

项目根目录/.opencode/skills/
├── halo-cli/              # Halo CMS 专属操作
├── halo-cli-auth/         # Halo 登录认证
├── halo-cli-content/      # Halo 文章管理
└── ...

原则：跟特定平台绑定的能力放项目里。

实际例子：Halo 项目的 Skills 分工

halo/skills/
├── halo-cli/              # 入口路由：判断用哪个子skill
├── halo-cli-auth/         # PAT Token 管理、登录
├── halo-cli-content/      # 文章、单页发布
├── halo-cli-operations/   # 主题、插件、附件管理
├── halo-cli-search/       # 站内搜索
├── halo-cli-moderation/   # 评论、通知管理
├── halo-cli-shared/       # 公共配置（JSON输出、destructive操作约定）
├── halo-theme-dev/        # 主题开发（Thymeleaf模板）
├── openspec-*             # 实验性功能探索/提案/应用/归档

每个 skill 只负责一件事，组合起来就是一个完整的 Halo 运维助手。

四、实战案例：用平台 API 解决问题的效率对比

案例 1：发布一篇文章

案例 2：排查服务器 500 错误

案例 3：OCR 文档双发

五、搭建自己的"巨人肩膀"平台库

我的经验公式

开发效率 = 平台 API 完善度 × AI 集成深度 × (1 - 手动操作次数)

选平台决策树

这个平台有 CLI 吗？
├── 有 → 有 API 吗？
│        ├── 有 → 有 MCP 吗？
│        │        ├── 有 → 🔥 首选（如 WordPress MCP）
│        │        └── 无 → ⭐ 可用（如 Halo Console API）
│        └── 无 → ⚠️ 能用但不理想
└── 无 → ❌ 换一个（手动操作 = 效率杀手）

推荐平台组合

六、总结

选平台就是选未来。 一个带 CLI/API 的平台，让 AI 直接操作业务层，而不是陪你写基础设施代码。

站在巨人肩膀上的三个层次：

1. 🌍 选对平台 — 带 CLI/API/MCP 的优先
2. 🏗️ 配好 Skills — 全局 + 项目分层管理
3. 🤖 AI 做执行 — 你只做决策，脏活累活交给 AI

本文由 OpenCode AI 基于 Q 师傅 的真实项目经验整理
接上篇《OpenCode 实战配置指南》

‍