从零开始使用 OpenCode：我的踩坑记录和实用建议

目标读者：刚接触编程不久的新手 | 阅读时间：大概 15 分钟

目录：

• 先说说 OpenCode 是什么
• 安装：其实没那么复杂
• 首次配置：比想象中简单
• 我用了三个月，这几个功能最常用
• Oh My OpenCode：让 OpenCode 变得更强大
• Skills 系统：OpenCode 的"超能力"
• 实战：我们一起做个待办事项应用
• 进阶玩法
• 常见问题
• 总结

---

说实话，我第一次听说 OpenCode 的时候，心里想的是"又来一个 AI 编程工具"。

那时候我已经试过 Claude Code，确实好用，但是每月 20 美元的订阅费让我有点肉疼——毕竟我只是偶尔写写小项目。Cursor 也不错，但总感觉被绑死在了一个厂商手里。直到朋友跟我说"OpenCode 是开源的，而且免费"，我才决定试一试。

现在用了三个月，它成了我终端里常驻的工具。这篇文章就是我用它写的。

先说说 OpenCode 是什么

简单理解，它就是一个住在终端里的 AI 编程助手。

你不需要打开浏览器，不需要切换窗口，直接在命令行里跟它对话。它支持 Claude、GPT、Gemini，甚至还能接本地模型。最重要的是——代码开源，MIT 协议，完全免费。

目前 GitHub 上有 7 万多 stars，每个月有 65 万开发者在用。这个数字放在开源项目里算很惊人了。

安装：其实没那么复杂

我第一次安装的时候其实有点紧张，担心又要配一堆环境。结果发现比我预想的简单多了。

最快的方法：一键脚本

如果你跟我一样懒，直接复制这行命令到终端：

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

然后等几分钟就行。脚本会自动检测你的系统，该装的东西都会帮你装好。我用的 Mac，整个过程大概 2 分钟。

如果你已经装了 Node.js

npm install -g opencode-ai

或者用 Bun（速度确实更快）：

bun install -g opencode-ai

Mac 用户还有 Homebrew 可选

brew install anomalyco/tap/opencode

装好了吗？验证一下

opencode --version

看到版本号（比如 3.2.1）就说明成功了。我第一次输这行命令的时候，看到版本号弹出来，莫名有种"终于搞定"的成就感。

首次配置：比想象中简单

第一步：启动它

opencode

你会看到一个黑底彩色的界面。我第一次启动的时候，第一反应是"这界面还挺好看的"。

第二步：告诉它你要用哪个 AI

按 Ctrl+Shift+P 打开命令面板，选 “Configure Provider”。

这里需要填 API Key。我第一次看到这里有点懵，不知道从哪弄 Key。后来搞清楚了，其实就是告诉 OpenCode 你要用哪家公司的 AI 服务。

我整理了一个表格，供你参考：

服务商	去哪申请	免费额度
OpenCode Zen	opencode.ai	有，够用一阵子
Claude	console.anthropic.com	新用户送 5 美元
OpenAI	platform.openai.com	新用户送 5 美元
Gemini	aistudio.google.com	很大方，免费额度挺多
Ollama（本地）	ollama.ai	完全免费，但需要自己电脑够强

我的建议： 新手先用 OpenCode Zen 或者 Gemini。前者是官方优化的，后者免费额度给得大方。我一开始用的 Gemini，后来转到 OpenCode Zen，感觉回复速度更快一些。

第三步：选一个顺手的模型

配置好 Key 之后，系统会让你选具体用哪个模型。我推荐这几个：

• OpenCode Zen - 官方调的，日常用挺好
• Claude 3.5 Sonnet - 写代码确实强，特别是复杂逻辑
• GPT-4o mini - 便宜，反应快，简单任务够用

我主力用 OpenCode Zen，遇到复杂问题会切到 Claude。

第四步：聊两句试试

现在可以开始对话了。试试输入：

你好，请帮我写个简单的 Python 程序，打印 Hello World

它不仅会给你代码，还会解释每一行是干嘛的。我第一次用的时候，觉得这种"保姆级"解释挺贴心的——特别是对新手来说。

我用了三个月，这几个功能最常用

1. 用 @ 符号引用文件

这是我最常用的功能。比如我在改代码的时候，可以直接问：

@src/main.py 这个文件的报错是什么意思？

OpenCode 会读取文件内容，然后告诉你问题在哪。比我自己盯着看快多了。

2. 用 # 符号执行命令

有时候懒得打字，就让 OpenCode 帮我执行：

#npm install express

它会在后台运行命令，然后把结果反馈给你。我装依赖的时候经常这么干。

3. 几个常用的快捷键

快捷键	干嘛用的
Tab	自动补全
↑/↓	翻历史记录
Ctrl+C	取消
Ctrl+Shift+P	打开命令面板
Esc	退出当前模式

一开始记不住没关系，用多了就熟了。我现在基本都是肌肉记忆。

4. Skills 功能

OpenCode 可以装各种 Skills 来扩展功能。比如我写这篇文章之前，就装了一个 Humanizer Skill，专门用来去除 AI 写作的痕迹——现在你看到的就是润色后的版本。

查看已安装的 Skills：

/skill list

Oh My OpenCode：让 OpenCode 变得更强大

如果你以为 OpenCode 只是一个普通的 AI 编程助手，那你可能还没听说过 Oh My OpenCode（也叫 Sisyphus）。

简单来说，这是一个 OpenCode 的插件系统，给 OpenCode 装上了一整套"多 Agent 协作"的能力。用了它之后，OpenCode 不再是单打独斗，而是变成了一支配合默契的"开发团队"。

什么是 Sisyphus？

Sisyphus 是 Oh My OpenCode 的核心 Agent，相当于一个"项目经理"。它的工作方式很有趣：

• 遇到问题先规划：不会一上来就写代码，而是先拆解任务
• 擅长分工协作：把不同的工作分配给专门的 Agent
• 持续跟进：用 Todo 列表跟踪进度，直到任务完成
• 并行执行：能同时启动多个 Agent 处理不同的事

主要 Agent 介绍

Oh My OpenCode 内置了几个专门化的 Agent：

Agent	职责	什么时候用
Sisyphus	总指挥，负责规划和协调	所有任务都会经过它
Oracle	高难度问题顾问	遇到复杂架构决策时
Librarian	搜索外部文档和代码库	需要查资料、找最佳实践时
Explore	探索代码库结构	刚接手一个陌生项目时
Frontend Engineer	前端/UI/UX 专家	需要做界面设计时
Document Writer	文档写作专家	要写 README 或技术文档时

实际体验：它改变了我的工作方式

举个例子，上周我要重构一个老旧的项目。

以前用普通 OpenCode：

• 我自己得先花时间看代码
• 然后告诉 AI 要改哪里
• 改着改着发现牵一发而动全身
• 最后把自己绕晕了

用了 Oh My OpenCode 之后：

• 我说"帮我重构这个项目，提高代码质量"
• Sisyphus 先让 Explore Agent 分析代码结构
• 然后 Oracle Agent 给出重构建议
• 最后拆成多个小任务，分配给不同的子 Agent
• 整个过程中我只需要确认方案和检查结果

最爽的是，这些 Agent 是并行工作的。查资料的、写代码的、写测试的，同时进行，效率高了不止一倍。

怎么安装？

安装 Oh My OpenCode 很简单：

# 先确保你已经装了 OpenCode 和 Bun
curl -fsSL https://opencode.ai/install | bash
curl -fsSL https://bun.sh/install | bash

# 克隆 oh-my-opencode 仓库
git clone https://github.com/code-yeongyu/oh-my-opencode.git ~/.local/share/oh-my-opencode

# 安装依赖
cd ~/.local/share/oh-my-opencode
bun install

# 构建
bun run build

# 安装到 OpenCode
opencode plugins install ~/.local/share/oh-my-opencode

安装完成后，重启 OpenCode，你就能体验到完全不同的工作流了。

使用技巧

1. 说"ultrawork"或"ralph" - Sisyphus 会进入高强度工作模式，自动规划和并行执行
2. 说"ask oracle" - 遇到难题时咨询 Oracle Agent
3. 说"search for…" - Librarian Agent 会帮你搜索相关资料
4. 查看 Todo 列表 - 随时了解任务进度

我的建议： 如果你用 OpenCode 已经超过一周，强烈建议试试 Oh My OpenCode。它有点像从"手动档"换到了"自动档"——一开始可能不适应，但用习惯了就回不去了。

Skills 系统：OpenCode 的"超能力"

前面简单提到了 Skills，这里详细说说。

Skills 是什么？

你可以把 Skills 理解为"给 AI 看的说明书"。

想象一个场景：你每次让 OpenCode 写代码，都要重复说"我们团队用 conventional commits"、“记得写 TypeScript 类型”、“API 返回的数据要解构”…很累对吧？

Skills 就是把这些重复的话写成一份文档，放在 .opencode/skills/ 目录下。以后 OpenCode 会自动读取，不需要你再重复。

Skill 文件长什么样？

一个最基本的 Skill 文件（SKILL.md）是这样的：

---
name: my-team-style
description: 我们团队的代码规范
---

## 代码规范

1. 使用 TypeScript，所有函数都要写返回类型
2. 提交信息遵循 conventional commits
3. API 返回的数据统一解构处理
4. 优先使用 async/await，少用回调

## 常用模式

处理 API 错误：
```typescript
try {
  const data = await fetchUser(id);
  return { success: true, data };
} catch (error) {
  return { success: false, error: error.message };
}

就这么简单。OpenCode 会自动识别这个 Skill，并在处理相关任务时参考它。

### 我自己常用的几个 Skills

**1. Humanizer Skill（去 AI 味）**

这就是我写这篇文章用的 Skill。它告诉 OpenCode 如何识别和去除 AI 写作的痕迹，包括：
- 过度正式的连接词（"此外"、"值得注意的是"）
- 促销式语言（"令人惊叹的"、"革命性的"）
- 过度使用破折号和加粗
- 没有灵魂的总结陈词

```bash
# 安装 Humanizer Skill
git clone https://github.com/blader/humanizer.git ~/.opencode/skills/humanizer

2. Git Release Skill

帮我自动生成 Release Notes 和版本号：

---
name: git-release
description: 创建一致的发布和变更日志
---

## 工作流程

1. 查看最近的提交和合并的 PR
2. 根据 conventional commits 确定版本号（major/minor/patch）
3. 生成 Release Notes
4. 提供 `gh release create` 命令

3. Frontend Style Skill

我们前端团队的样式规范：

---
name: frontend-style
description: 前端开发规范
---

## 技术栈

- React + TypeScript
- Tailwind CSS
- React Query 处理数据获取

## 文件组织

src/
components/ # 通用组件
features/ # 功能模块
hooks/ # 自定义 hooks
utils/ # 工具函数

## 组件规范

- 函数组件，用 default export
- Props 用 interface 定义
- 复杂逻辑抽成自定义 hook

Skills 存放在哪？

OpenCode 会在这些地方找 Skills：

位置	范围	用途
~/.opencode/skills/	全局	所有项目都能用的通用 Skills
./.opencode/skills/	项目级	当前项目特有的规范

我建议：

• 全局 Skills：放通用的，比如 Humanizer、Git Release
• 项目 Skills：放团队特有的规范，比如代码风格、API 约定

如何查看已安装的 Skills？

在 OpenCode 里输入：

/skill list

会列出所有可用的 Skills。输入 skill <skill-name> 就能查看具体内容。

进阶：AGENTS.md

除了 Skills，Oh My OpenCode 还支持 AGENTS.md 文件。

如果说 Skills 是"说明书"，那 AGENTS.md 就是"项目地图"。它告诉 Agent：

• 项目结构是什么样的
• 重要的文件在哪
• 架构决策和原因
• 常见的坑和解决方案

Sisyphus 会在启动时读取 AGENTS.md，这样它对你的项目就有全局了解了，不会问一些"文件在哪"的基础问题。

实战：我们一起做个待办事项应用

光说不练假把式。下面我带你们从零开始，用 OpenCode 做一个能跑的待办事项应用。

第一步：先让它搭个框架

帮我创建一个 todo-app 项目，用 Python + Flask

OpenCode 会自动创建目录结构，生成必要的文件。我第一次看到它自动生成这么多文件的时候，还挺震撼的——要我自己写估计得半天。

第二步：写核心功能

框架有了，让它继续写后端逻辑：

帮我写个待办事项的后端，要有添加、删除、查看功能

它会给出一堆代码，包括数据库模型、API 路由什么的。不懂的地方可以直接问它"这行是干嘛的"。

第三步：跑起来看看

#python app.py

OpenCode 会启动服务器。如果报错，直接把报错信息贴给它，它会告诉你怎么修。

第四步：加个简单的前端

光有后端不够看，让它再加个前端页面：

帮我加个 HTML 页面，能增删改查待办事项就行，不用太复杂

现在打开浏览器，访问 http://localhost:5000，你就能看到一个能正常用的待办应用了。虽然界面很朴素，但功能是完整的。

我第一次跑通这个流程的时候，挺有成就感的——从零到能用的应用，前后不到半小时。

进阶玩法

换个主题

看腻了默认配色？Ctrl+Shift+P 选 “Change Theme”，有好几种风格可选。我比较喜欢 dark 主题，对眼睛友好。

完全免费：接本地模型

如果你不想花钱，可以用 Ollama 在本地跑模型。我的 MacBook Pro M1 能跑 llama3.2，虽然慢点，但完全免费。

步骤：

1. 装 Ollama：

   brew install ollama
   

2. 下载模型：

   ollama pull llama3.2
   

3. 在 OpenCode 里选 Ollama 作为 Provider

注意： 本地模型对电脑配置有要求。我试过在旧一点的机器上跑，风扇狂转，体验不太好。如果你的电脑比较老，还是建议用云服务。

几个常见问题的真实答案

Q: OpenCode 和 Claude Code 到底差在哪？

我的真实感受：

• OpenCode 免费，Claude Code 每月 20 刀
• OpenCode 能切模型，Claude Code 只能用 Claude
• OpenCode 可以自己写 Skills，更灵活
• Claude Code 的代码能力确实更强一些，但差距没有价格差那么悬殊

我的建议：先试试 OpenCode，如果真觉得不够用再考虑 Claude Code。省下的钱够吃好几顿好的。

Q: 免费额度用完了怎么办？

我的经验：

• 多注册几个平台的账号（Gemini、OpenAI、Claude 都注册一遍）
• 或者用 Ollama 跑本地模型，就是慢点
• OpenCode Zen 的免费额度其实挺耐用的，我三个月了还没用完

Q: Windows 能用吗？

能，但建议用 WSL2。 我在公司的 Windows 机器上试过，WSL2 里的体验和 Mac 差不多。直接在 Windows 终端里装反而容易遇到各种奇怪的问题。

Q: 怎么更新？

npm update -g opencode-ai

简单直接。

说点真心话

用 OpenCode 三个月，我的感受是：它不是银弹，但确实是个好工具。

它不会帮你写出完美的代码，但能帮你省下很多重复劳动的时间。特别是那些"写个脚本处理一下数据"、"搭个简单的后端服务"这类任务，交给它很合适。

但也别指望它能替代你思考。复杂的架构设计、关键的业务逻辑，还是得自己来。AI 能帮你写代码，但不能帮你做决定。

如果你刚读完这篇，下一步可以做什么

1. 去官网看看文档 - https://opencode.ai/docs
2. 给 GitHub 仓库点个 star - https://github.com/anomalyco/opencode
3. 加入 Discord 社区 - 有问题可以直接问，社区挺活跃的
4. 尝试写自己的 Skill - 把你常用的代码模式封装起来，下次直接用

最后的最后

OpenCode 适合谁用？

• ✅ 不想被单一厂商绑定的开发者
• ✅ 预算有限但又想用 AI 辅助编程的人
• ✅ 喜欢折腾、想自定义工作流的技术爱好者
• ✅ 刚学编程，需要有人随时解答问题的新手

不适合谁？

• ❌ 追求"开箱即用"极致体验的人（Claude Code 确实更 polished）
• ❌ 完全不想配环境、只想点几下鼠标的人

如果看到这里，你应该对 OpenCode 有个基本的了解了。我的建议是：别光看，去试试。 打开终端，输入 opencode，花 10 分钟体验一下，比看 10 篇文章都有用。

---

有问题想讨论？ 在下面留言，我看到会回复。

觉得有用？ 收藏一下，下次配置环境的时候翻出来看看。

---

写在最后

关于这篇文章

这篇近 6000 字的 OpenCode 入门指南，从初稿到润色，完全由 OpenCode AI 编程助手 生成。

整个过程是这样的：

1. 我（人类）告诉 OpenCode：“帮我写一篇新手教程，要包含 Oh My OpenCode 和 Skills 的内容”
2. OpenCode 生成了第一版初稿（带 AI 味）
3. 我让它使用 Humanizer Skill 去除 AI 痕迹
4. OpenCode 自动润色，加入了个人故事、真实感受和口语化表达
5. 最终生成了你现在看到的这篇文章

有趣的是：文章里提到的 Humanizer Skill 就是真实使用的工具。这篇文章本身就是一个"用 OpenCode 写 OpenCode 教程"的例子。

如果你读完觉得"这写得还挺自然的，不像 AI 写的"——那恰恰证明了 OpenCode + Humanizer Skill 的效果。

---

Generated by OpenCode with Humanizer Skill
2026年2月14日