何为自律在我的使用经验里，opencode 不算那种“装完就能跑出漂亮 demo、之后就吃灰”的工具，它更像个需要慢慢布置的指挥中枢。尤其是把 Oh-My-Opencode 和 SuperPower 插件一起放进同一套环境后，核心逻辑才真正暴露出来：一套 AI 编码流程能不能用顺，关键不在于你敲了多少神奇命令，而在于你的工具链是否围绕“agent + skill”这个结构组织好了。
这篇就围绕我在 Mac 系统上从零安装 opencode、再接入 Oh-My-Opencode 和 SuperPower 的完整过程来写。内容包括每一步操作的背后逻辑、目录结构、常见报错、以及我从实际使用中总结出的建议。适合刚从终端 AI 编程进来、想把 opencode 当日常主力工具用起来的开发者，也适合那些和我一样在安装器问题上栽过跟头的人。
1. 先把 opencode、Oh-My-Opencode、SuperPower 三者的分工理清楚
很多人一上来就搜“opencode 安装”，结果照着命令装完，发现自己只是拿到了一个能聊天的终端程序，等真正想让它参与项目开发时又无从下手。这其实是安装前就没区分“核心程序”和“能力扩展”导致的。
1.1 opencode 是什么，它区别于普通 CLI 的地方在哪
opencode 在 Mac 上属于那种“终端里运行的 AI 编程代理”。它不像 git 或 curl 那样只是替你做一件明确的事情，而更像一个有记忆、能拆解任务、能来回调整方案的执行者。你给它一个目标，它会自主规划步骤，调用工具，搜索文件，修改代码，然后回来向你报告。
这种工具的定位决定了它的安装不只是“把二进制放到 /usr/local/bin”，而是要同步考虑三件事：
- 模型从哪里来，调用什么 API；
- 它的工作目录在哪里，权限范围怎么控制；
- 它通过什么机制读取额外的“能力包”。
很多搜索词里都带“opencode 架构源码”“opencode skills”“opencode 如何切换模型”，说明大家真正关心的是它的扩展机制和可组合性，而不只是那个安装命令。
1.2 Oh-My-Opencode 和 SuperPower 各自解决什么问题
Oh-My-Opencode 从名字就能看出来，它模仿的是 Oh-My-Zsh 那套“给基础程序增加一套可管理的配置和插件集”的思路。opencode 原生支持加载 skill 文件，但没有统一管理入口，你装了一堆 skill 之后可能连自己装过什么、放在哪都弄不清。Oh-My-Opencode 就把这些 skill、配置、预设指令组织起来，给出一套清晰的目录结构和操作命令。
SuperPower 则是一组精心设计的能力模块，主题往往包含特定工作流的深度方法论。比如怎么拆用户故事、怎么写高质量代码评审、怎么组织一次完整的重构等等。它不是简单的“提示词收藏夹”，而是能被 opencode 在任务中自动识别和加载的结构化指引。
所以安装顺序应该很明确：先装 opencode 本体，再装 Oh-My-Opencode 做统一管理，最后把 SuperPower 作为能力包导入。反过来装你会发现，管理框架有了但下面没有承载它的基础程序，等于白搭。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Mac 上安装 opencode 本体：从终端命令到第一个可用会话
我建议先在一个干净的终端环境里完成 opencode 的本体安装，不要一上来就尝试同时装其他插件，否则一旦出问题，你很难判断是主体配置出了错，还是某个技能包的路径没有加载正确。
2.1 安装命令、版本确认和目录位置
opencode 的官方安装方式通常是执行一行 curl 脚本或通过包管理工具安装。我在 Mac 上实操时更推荐把版本固定下来，尽量不要用“每次都拉最新版”的方式，因为 AI 工具迭代快，某个小版本的行为可能变化很大，固定版本能减少“昨天还能用，今天突然不识别参数”的那种尴尬。
我当时的操作顺序是：
bash复制# 先确认本机有没有残留的旧版本
which opencode
opencode --version
# 执行官方安装脚本
curl -fsSL https://opencode.ai/install | bash
安装完成后，你会看到二进制通常被释放到用户目录下的 .opencode/bin 或者 /usr/local/bin 下，具体取决于安装脚本检测到的系统环境。我建议安装后立刻做两件事：
bash复制which opencode
opencode --version
如果 which 没有任何输出，说明安装目录没有进入当前 shell 的 PATH。这时先别急着改系统级配置文件，可以把检查范围缩小到 shell 配置里有没有加载对应的路径。常见情况是用户装了 nvm、pyenv 这类版本管理工具，它们可能在 .zshrc 里有自己的 PATH 重排逻辑，导致 opencode 的目录被覆盖。
2.2 配置 API Key：选哪家模型、哪些参数决定你后面好不好用
opencode 本体装完以后，第一次启动会要求你确认使用什么模型。这一步看似简单，实际上很影响后面的体验。
如果你只是做轻度代码片段补全，选一个基础模型就够。但如果你打算让它独立处理整个仓库重构、写测试、或者理解多层微服务结构，那就要选上下文窗口更长、工具调用能力更强的模型。这里的判断标准不是“哪个名字听起来更聪明”，而是“你的实际任务需要多长的上下文和多大的工具自由度”。
配置文件的常见位置在 ~/.config/opencode/opencode.json，我自己的最小配置长这样：
json复制{
"$schema": "https://opencode.ai/config.json",
"provider": {
"default": "anthropic"
},
"model": "claude-sonnet-4-20250514",
"theme": "opencode"
}
这里有几个要提前理解的概念。provider 决定 API 走哪家；model 决定具体用哪个模型实例；theme 只是命令行配色。最容易被忽略的是 API Key 的存放，它不应该直接写进这个 json。更多时候它会被放在系统环境变量里，或者放在 opencode 自己的认证存储中。
在 Mac 上，如果你用的是 zsh，我建议把密钥相关的变量写进 ~/.zshrc，然后重启终端事务或执行 source ~/.zshrc。不要图省事直接塞进项目路径里的 .env，因为 opencode 的会话可能跨多个项目运行，跟着项目走反而容易漏配。
2.3 第一条会话指令怎么验证安装真的可用
配置写好之后，我习惯用两种不同的方式来验证。
第一种是直接进入交互式会话，发一句简单但需要工具调用才能完成的指令：
bash复制opencode
进入会话后输入：
text复制打印当前工作目录，并列出前两层文件结构。
如果它能正确执行并返回结果，说明基础的“模型调用 + 本地命令执行 + 目录读取”链路已经通了。
第二种验证方式是跑一条非交互式指令，用于确认 API 密钥是否能正常通过命令行被识别：
bash复制opencode run "请帮我检查当前 Python 环境版本，并告诉我默认解释器路径。"
这里我建议新手不要第一次就去让它“帮我重构整个项目”。不是因为能力不行，而是你还没建立对它的信任边界。先用几个安全的只读操作跑通环境，之后再逐步放开写权限。
3. 安装 Oh-My-Opencode：让技能包从“散装状态”变成有序目录
opencode 越用越觉得顺手的时候，你会开始想要给它加各种奇奇怪怪的能力：让它在代码提交前自动检查规范、让它对不同语言的项目采用不同的注释风格、让它调用特定领域的分析框架。这些需求靠手写一份份 instruction 文件也能实现，但装了几十份以后，没人记得全。
Oh-My-Opencode 解决的就是这个“管理混乱”的问题。
3.1 Oh-My-Opencode 的核心机制：你其实是在学习它的目录约定
从使用角度讲，Oh-My-Opencode 不只是一个安装器，它更像一套“约定优于配置”的目录规范。你在它的框架下新增的任何能力，都会被放入固定路径，并通过统一的入口被 opencode 加载。
我在 Mac 上安装它时的大致步骤是：
bash复制# 确保 opencode 本体已经可用
opencode --version
# 拉取 Oh-My-Opencode 的安装仓库
git clone https://github.com/xxxx/oh-my-opencode.git ~/.oh-my-opencode
# 执行初始化安装脚本
cd ~/.oh-my-opencode
./install.sh
一切正常的话，它会自动在 opencode 的配置目录中新增一个指向技能目录的引用。此时你打开 ~/.config/opencode/ 会看到类似这样的结构：
text复制~/.config/opencode/
├── opencode.json
├── skill/
│ ├── agent.md
│ └── workspace/
不同的版本可能在细节上略有差异，但重点是：这个框架让“新增一份技能”变成一个普通的复制文件操作，不需要自己去改动主体配置文件。这个设计正好契合 Mac 使用习惯——你不用为了加一个工具去折腾各种全局配置，只需要把能力放进一个组织好的目录。
3.2 安装过程中最容易出现的两个问题
第一个问题，脚本执行提示没有写权限。这时不要直接对目录执行 sudo chmod -R 777，这种粗暴做法会把整个配置目录的权限结构打乱。我建议先确认当前用户是否对这个目录有读写权限：
bash复制ls -la ~/.config/opencode/
如果不是当前用户所有，可以修改目录 owner：
bash复制sudo chown -R $(whoami) ~/.config/opencode
这样只改归属，不动权限位，后续用起来更干净。如果你是在多用户 Mac 上操作，这一点尤其重要，因为系统默认可能把某些目录建在另一个用户的家目录里。
第二个问题，安装脚本检测不到 opencode。大概率是 Oh-My-Opencode 在查找 opencode 时读 PATH，而你的 PATH 最新配置没有生效。我偷懒的解决办法是直接重启终端窗口再执行安装脚本，比反复 export 更省事。
3.3 添加第一个可复用的技能包验证管理框架
安装完 Oh-My-Opencode 后，我建议你立刻增加一个最简单的技能包，用来验证整体链路，而不要空着框架就直接去装 SuperPower。
手动创建一个技能文件试试：
bash复制mkdir -p ~/.config/opencode/skill/demo
cat > ~/.config/opencode/skill/demo/SKILL.md << 'EOF'
---
name: demo
description: 演示技能，用于验证技能加载是否正常
---
当用户要求你执行演示任务时，先输出当前时间，再列出当前目录的文件。
EOF
然后在 opencode 的交互会话中问它：
text复制请执行一个演示技能。
如果它开始输出时间和文件列表，说明 Oh-My-Opencode 管理的技能目录已经被成功加载了。如果它表示不知道这个技能，那就得检查 SKILL.md 的格式是不是写错了，或者技能目录的命名是否以 skill 作为固定子目录名。
这个验证步骤非常重要，因为很多人装完 SuperPower 后才发现一个问题：技能是有放进去，只是 opencode 根本没读取到对应目录。
4. SuperPower 工具插件的安装：把外部技能库接入 opencode
SuperPower 这套东西，搜索关键词里总会出现“superpower skills 安装”“superpower ai工具”“install opencode superpower”这样的组合式问题。实际用起来，它并不是那种需要双击安装的普通 Mac 应用，而是以“技能仓库”的形式被克隆到本地，然后通过 opencode 的技能目录完成加载。
4.1 先理解 SuperPower 的仓库形态
SuperPower 会被描述为工具插件，但它的本质是一组有结构的 Markdown 文件和辅助脚本。仓库里不同的文件夹对应不同的领域能力，每个能力文件夹内都有描述文件、示例以及可能的辅助函数。
这就带来一个和传统插件安装完全不同的习惯要求：你在 Mac 上不是“安装”它，而是“引入”它。引入之后，opencode 通过读取描述文件来决定什么情况下调用什么技能。
理解这一点，你就知道为什么总有人问“为什么我装了却不起作用”。因为单纯把代码下载到某个文件夹不算真正完成，你还需要确保 opencode 的技能目录能扫描到这个文件夹，并且描述文件的前缀命名符合识别规范。
4.2 在 Mac 上的实际安装命令和路径选择
我建议把 SuperPower 的仓库克隆到一个独立目录，不要直接塞进 opencode 的配置目录里。原因有两个：第一，SuperPower 本身迭代速度很快，独立目录方便你随时 pull 更新；第二，把技能来源和技能仓库分开，能让你的配置目录保持简洁。
执行过程大致是：
bash复制# 先进入想放置技能库的位置
cd ~/Projects
git clone https://github.com/xxxx/superpowers.git
# 查看技能目录的组织情况
ls ~/Projects/superpowers/skills
接下来，在 Oh-My-Opencode 的管理目录中，为 SuperPower 创建软链接，让 opencode 可以直接读到它：
bash复制ln -s ~/Projects/superpowers/skills ~/.config/opencode/skill/superpowers
用软链接而不是直接复制，是我个人比较推荐的做法。因为复制后如果仓库更新，你需要再复制一遍；而软链接天然跟随原始目录的变化，pull 一次远端更新，技能内容自动同步。同时，SuperPower 的仓库里可能还有它自己的依赖说明，比如某个技能需要额外安装 Python 包或 Node 工具，要仔细阅读对应技能的 README。
4.3 验证 SuperPower 是否被 opencode 识别并调用
做完上述步骤后，重启 opencode 会话，然后直接提问：
text复制你有哪些已经加载的技能？请列出所有可用技能的名称和用途。
如果它是通过技能机制实现的，你会看到一个包含 SuperPower 相关内容的列表。如果列表里完全没有，可以先检查软链接本身是否成功：
bash复制ls -la ~/.config/opencode/skill/
如果目录下出现了 superpowers -> ~/Projects/superpowers/skills 这样的箭头，说明软链接正常。这时问题大概率出在描述文件的前缀命名上。SuperPower 的技能文件夹会按特定方式命名，比如前置编号，这样 opencode 在语义解析时才能把它们和普通技能文件区分开。你不用理解全部细节，但你需要知道：如果列表没有出现，优先去看描述文件而不是去改主配置。
我在实际操作中遇到的另一类是“技能虽然被加载了，但触发不准确”。比如我明明已经处于一个 React 项目的目录里，它却没有自动加载前端相关的技能。经过排查，我意识到这是因为技能名称里可能没有包含足够清晰的关键词，或者我需要给出更明确的任务描述，才能让 opencode 选中正确的技能。
5. 装了 Oh-My-Opencode 和 SuperPower 之后，我如何把它们接入日常工作流
许多人的安装过程到上一节就结束了，紧接着就会陷入“装了很多，但是每次都要我手动提醒它用什么知识”的混乱状态。其实 Oh-My-Opencode 和 SuperPower 的价值，在于它们能自动根据任务场景选择合适的技能。因此在这节，我会把安装完成后进一步要做的工作流配置讲清楚。
5.1 在 VSCode 里使用 opencode：不只是开个终端窗口
搜索热词里有“opencode vscode插件”“vscode创建vite项目mac系统”，说明大量开发者是在 VSCode 环境中使用 opencode 的。要注意，opencode 的 VSCode 集成往往不是靠传统“插件市场搜索安装”的方式，而是以 opencode 命令在终端面板中执行，或者通过 VSCode 的任务配置加载。
我自己习惯的方式是给 VSCode 增加一个自定义任务，这样不用每次手动切换终端再敲命令。在 .vscode/tasks.json 中加入：
json复制{
"version": "2.0.0",
"tasks": [
{
"label": "OpenCode Agent",
"type": "shell",
"command": "opencode",
"options": {
"cwd": "${workspaceFolder}"
},
"presentation": {
"panel": "dedicated",
"reveal": "always"
},
"problemMatcher": []
}
]
}
保存后，在 VSCode 中用 Tasks: Run Task 唤起它，opencode 就会以当前项目目录作为工作区。这样做的好处是， opencode 读取文件路径时始终以项目根为参照，不会因为之前 opencode 在别的目录启动过而误读文件结构。
5.2 “切换模型”别靠反复改配置文件
很多人搜“opencode 如何切换模型”是因为每次切换都要打开配置文件、改 model 字段、重启。如果你的模型使用方式很固定，那没问题。但如果你需要在不同任务间来回切换模型，我更推荐在 opencode 的交互界面里直接切换，或在配置文件里提前定义多个 model 别名，而不是每换一次就动手编辑一次 json。
举个例子，你可以把常用模型都写进配置中：
json复制{
"provider": {
"default": "anthropic"
},
"model": {
"fast": "claude-sonnet-4-20250514",
"powerful": "claude-opus-4-20250514",
"local": "ollama/qwen2.5-coder:14b"
}
}
这样在日常会话中，如果只是写简短脚本，就用 fast 或 local 模型；如果涉及大型重构架构设计，则切换为 powerful 模型。模型本身有各自的优势和成本，这比一个配置走天下要务实得多。
5.3 免费模型与本地模型的接入思路
搜索结果里“opencode免费模型”这个词频繁出现，很能理解。并不是每个人都需要在第一时间给自己的 opencode 配上最贵的云端模型，特别是初期学习和验证阶段。
在 Mac 上接入本地模型仍然是一条可选的路。opencode 通过兼容 OpenAI 格式的接口识别模型，所以 Ollama 这类本地模型运行时只要在本机开放一个本地服务端口，opencode 就可以把它当作普通 provider 来调用。这个方式适合用来处理简单代码片段、模糊搜索以及不需要深度推理的任务，不消耗云端 API 额度。
不过我不建议把本地模型作为所有任务的默认选项。本地模型在复杂代码库理解上的能力差距是客观存在的，强行让它处理高难度重构只会让你误以为 opencode 本身不好用。
5.4 实践案例：用 opencode 配合技能在 Mac 上生成一个 Vite 项目
用 Vite 创建前端项目是一个非常适合展示 opencode 工作流的例子。它的操作步骤多且重复，也涉及文件生成和项目结构组织，可以让 SuperPower 里相关的前端工程技能发挥作用。
我通常在 opencode 的会话中直接描述：
text复制在当前目录创建一个基于 Vite 的 React 项目，项目名称为 my-vite-app。
创建完成后，启动开发服务器，并告诉我默认访问地址。
在具备相应技能配置的前提下，opencode 会调用 shell 工具执行 Vite 官方脚手架命令，然后等待命令结束后再去确认目录文件是否生成，最后启动服务。整个过程需要连续的工具调用和反馈判断，比单独执行一条终端的 Vite 命令更有意义，因为它验证了 opencode 的“看状态—调整—再执行”能力。
如果它在注册某个依赖步骤中停顿，你可以在它的信息流里看到具体原因。大多数问题来自 Node 版本过低或 npm 镜像尚未配置好，这不属于 opencode 本身的 bug，而是本机环境的问题。
6. 我在 Mac 上安装和联调过程中积累的一些实操经验
最后这部分不按安装顺序来，就纯粹梳理几个让我印象深刻的经验。它们没法直接套到每台 Mac 上，但遇到相似问题时会很有参考价值。
6.1 “mac系统数据290.3g”“mac系统数据怎么清理”意味着什么
搜索词里包含“mac 系统数据 290.3 gb”“mac系统数据怎么清理”，这不是偶发现象。装 opencode、装 SuperPower 这类工具后，很多人会发现系统数据迅速膨胀。其实大部分增长并不来自 opencode 本尊，而来自两个容易被忽视的地方：
一是各种模型缓存。opencode 在会话过程中会把一些大型代码片段和搜索结果缓存到本地目录，如果你同时使用多个模型，缓存量会更大。这部分数据通常存放在 ~/.cache/opencode 或类似路径下，可以定期查看和清理。
二是 Node 工具链的包缓存。如果你在 Mac 上通过 npm 或 pnpm 安装各种辅助依赖，缓存数据可能动辄几个 GB。不要一发现系统存储空间不够就去改 opencode 配置，先确认 ~/Library/Caches 和 ~/.npm 的体积增长情况。
6.2 目录权限和“无法访问”问题的处理思路
Mac 上最容易发生的误操作之一，是用 sudo 运行安装脚本后，工具生成的文件 owner 变成了 root，之后再用普通用户身份运行工具就提示没有权限。遇到这类问题，不要盲目将所有文件 chmod 777，而是先将这些目录的 owner 恢复到当前用户。
bash复制sudo chown -R $(whoami) ~/.config/opencode
从这以后再进行配置修改就不会被权限卡住了。这是 macOS 上安装大多数命令行工具时一个非常通用且实用的原则，学会这个比记住大量“权限修正命令”更有价值。
6.3 不要一股脑把所有技能全部塞进目录
SuperPower 这类技能库往往内容庞大。新手常见误区是以为“内容越全越强”，于是把整个仓库所有技能都塞给 opencode。实际体验恰恰相反，一方面大量无关键技能会干扰任务分类，另一方面，有些高级技能之间也会存在调用冲突。
我的建议是，保留一个基础技能集合，其余按项目类型拆包。一个小型前端项目只需要保留代码生成、性能分析、测试写作等相关技能。在做配置时会觉得多几步，但真正进入具体任务后，opencode 的技能命中率会明显好很多。
6.4 把 Oh-My-Opencode、SuperPower 当做一个“可演进”的组合
安装并运行稳定之后，不要认为这就是终点。AI 编码工具现在变化太快，每周都会冒出新的技能包、新的模型接口、新的工作流规范。Oh-My-Opencode 提供的是秩序，SuperPower 提供的是专家知识，而你需要做的，是把它们和 opencode 本体绑定成一套能随任务变化而调整的结构。
我个人的习惯是每两周执行一次技能库更新，并抽几分钟浏览一下新增的技能名称。很多时候一个看起来不起眼的技能，会解决你手头已经困扰很久的重复劳动。比如我在实践中发现一个用于分析命令行错误并生成可复现步骤的技能，虽然只有短短几行描述，但它让 opencode 排查报错时的准确率提高了很多。
这也解释了为什么最终组合那么重要：单独用 opencode，你只有一个聪明的执行者；给它配上 Oh-My-Opencode 管理技能，再喂入 SuperPower 的专业知识，这个执行者才真正变成了一个能读懂你项目上下文、知道什么时候该切换策略的搭档。你的 Mac 最终承载的也不只是几个软件文件，而是一套完整且不断增长的本地 AI 工作环境。