OpenCode 安装与 Skill 配置实战指南

OpenCode 是什么

OpenCode 是一个命令行驱动的 AI 编程辅助工具，主打开箱即用。你不需要在编辑器里装插件，也不用折腾复杂的本地模型部署，只要装个 npm 包，就能直接和 AI 对话写代码。

它的核心优势有两个：一是内置了几个免费模型，比如 Big Pickle，不用填 API Key 就能用；二是支持 Skill 扩展机制，你可以给 AI “装插件”，让它具备特定领域的知识或执行能力。

安装与首次运行

全局安装

确保你的系统已经装好了 Node.js（建议 18 或更高版本），然后在终端里执行：

复制npm i -g opencode-ai

这条命令会把 opencode 命令安装到全局，之后在任何目录下都能直接调用。

启动对话

安装完成后，输入：

复制opencode

你会看到一个交互式提示符，这时候就可以开始提问了。不过别急着问，先选个合适的模型。

模型选择

在 OpenCode 内部输入 /models，会列出所有可用的模型。目前分为两类：

免费模型（无需密钥）：

• Big Pickle：官方默认推荐，对中文支持不错，代码补全和生成效果稳定，适合日常使用。
• Ling 2.6 Flash Free
• MiniMax M2.5 Free
• Nemotron 3 Super Free

付费/自定义模型（需要 API Key）：

• OpenCode Zen（官方订阅版）
• OpenAI、Anthropic、Google 等第三方模型

如果你只是想试试看，直接用 Big Pickle 就够了。选好后，AI 就会用这个模型来回答你后续的问题。

Skill 是什么？为什么需要它？

Skill 是 OpenCode 的扩展机制。你可以把它理解为“AI 的技能包”。默认情况下，AI 只会通用编程知识。但如果你经常处理数据库迁移、前端组件生成或者 DevOps 脚本，就可以写一个对应的 Skill，让 AI 在相关问题上表现得更专业。

比如，你加载了一个“React 组件生成”Skill，当你问“帮我写一个带搜索的用户列表组件”，AI 不仅会生成 JSX，还会自动包含状态管理、防抖逻辑，甚至附上单元测试模板——这些都是 Skill 里预设好的行为。

Skill 的目录结构

OpenCode 通过固定的目录结构来识别 Skill。它支持两种作用域：项目级和全局级。

项目级 Skill

只对当前项目生效。适合团队协作时共享特定领域的辅助逻辑。

目录结构如下：

复制你的项目/
└── .opencode/
    └── skills/
        └── your-skill-name/
            ├── SKILL.md
            ├── scripts/      # 可选
            ├── references/   # 可选
            └── assets/       # 可选

关键文件是 SKILL.md，里面用 Markdown 描述这个 Skill 的用途、触发条件和行为规范。OpenCode 会读取这个文件来决定是否激活该 Skill。

全局 Skill

对所有项目生效。适合个人常用的通用技能，比如“生成 Git 提交信息”或“解释正则表达式”。

存放路径因系统而异：

• macOS / Linux: ~/.config/opencode/skills/
• Windows: C:\Users\<你的用户名>\.config\opencode\skills\

注意：Windows 路径中的 .config 是隐藏文件夹，你可能需要在文件资源管理器里开启“显示隐藏文件”才能看到。

Windows 下配置全局 Skill 实战

下面以 Windows 为例，演示如何添加一个全局 Skill。

第一步：创建目录

1. 打开文件资源管理器，进入你的用户目录（通常是 C:\Users\你的名字）。
2. 如果看不到 .config 文件夹，点击顶部菜单“查看” → 勾选“隐藏的项目”。
3. 如果没有 .config，就手动新建一个文件夹，命名为 .config（注意前面有个点）。
4. 进入 .config，再依次创建 opencode 和 skills 文件夹。

最终路径应该是：C:\Users\你的名字\.config\opencode\skills

第二步：放入 Skill

从官方仓库（如 https://github.com/anthropics/skills）或社区平台（如 https://skillsmp.com/zh）下载一个 Skill 包。假设你下载的是 skill-react-component.zip，解压后得到一个文件夹叫 react-component。

把这个整个文件夹复制到刚才创建的 skills 目录里。

第三步：验证加载

回到终端，重新启动 OpenCode：

复制opencode

然后输入命令：

复制skill list

如果输出里出现了 react-component，说明加载成功。

第四步：触发使用

现在你可以问一些和 React 相关的问题，比如：

“用 TypeScript 写一个带分页的表格组件，支持排序和筛选。”

如果 Skill 设计得当，AI 会自动调用 react-component 里的模板，生成结构完整、符合最佳实践的代码，而不是随便糊一个基础版本。

注意事项

• SKILL.md 必须存在：没有这个文件，OpenCode 不会识别该目录为 Skill。
• 不要混用作用域：项目级 Skill 不会影响其他项目，全局 Skill 对所有项目可见。根据需求选择。
• 模型影响效果：即使是同一个 Skill，在 Big Pickle 和 OpenCode Zen 上的表现可能不同。复杂任务建议用更强的模型。
• 权限问题：在 Windows 上，如果遇到权限错误，可以尝试以管理员身份运行终端再安装。

总结

OpenCode 的价值不在于它本身多强大，而在于它提供了一个轻量、可扩展的框架。通过 Skill 机制，你可以逐步积累自己的“AI 工具箱”，让编程助手越来越懂你的工作流。

从安装到配置，整个过程其实就几步：装包、选模型、放 Skill、验证。剩下的，就是去社区找现成的 Skill，或者自己写一个。毕竟，最好的 AI 助手，是那个最了解你习惯的。