这两年终端里的 AI 编程助手一个接一个冒出来，opencode 是其中我很喜欢的一个开源项目。它不是那种只会在编辑器里给你补全代码的插件，而是可以整包接手一个任务的 AI 编程 Agent：读仓库、改代码、跑命令、查报错、写测试，全程在终端里跟你协作。对于想摆脱单一厂商绑定、想在本地模型上省钱、或者想自己折腾一套可定制 AI 工作流的开发者来说，open code 几乎是最合适的骨架。
我把它当主力 Agent 用了挺长时间，这期间踩过不少坑，也摸索出一套从安装、配模型、进 IDE、到真实接项目的完整流程。下面这些内容，基本就是我日常在用的 opencode 标准使用指南，适合刚听说的新手，也适合已经装过但觉得不太好用、想把它调教得更顺手的人。
1. opencode 到底是什么，以及我为什么从 Claude Code 转过来
1.1 一句话说清 opencode 的定位
opencode 是一个开源的、终端优先的 AI 编码助手，核心能力和 Claude Code、Codex CLI 这一类工具类似：你给它一个任务，它会自己规划步骤，逐个读取项目文件，生成修改，执行命令，甚至根据测试结果自我修复。它跟你熟悉的 GitHub Copilot 完全不同，Copilot 是“你写一句它补一段”，opencode 是“你把需求丢给它，它把整件事跑完”。
它的项目背景也不错，来自开源社区里做 SST 框架的那批人，代码质量和对开发者体验的打磨都比较在线。底层技术上，opencode 支持多种大模型后端，不是绑定某一家 API 的封闭工具。你可以接 Anthropic、OpenAI、Google 的模型，也可以接国内厂商兼容 OpenAI 协议的接口，甚至直接接本地跑的 Ollama 模型。这个“模型自由”是我最看重的一点，后面我会专门讲怎么配置。
1.2 我为什么把主力 Agent 换成了它
我之前用 Claude Code 用了一段时间，体验确实惊艳，但有几个痛点很难忍。第一，它几乎是为 Claude 官方 API 深度优化的，你想换便宜模型或者国内模型，配置成本很高。第二，像 skills、记忆这类高级能力，官方版本要么没有，要么只在付费体系里玩得转。第三，它的配置格式偏私有，换到别的工具又要重新学一遍。
opencode 把这些事反过来了。它本身是开源项目，天然没有厂商绑定。配置文件就是一个 JSON，你定义 Provider、模型、API Base URL，想接哪家接哪家。skills 也是原生支持，不用像 oh-my-claudecode 那样去给别人的工具打补丁。memory 功能可以记住你在这个项目里的偏好。它还有 VSCode 插件、JetBrains 插件和桌面版，等于从终端到 IDE 都覆盖了。
所以我现在的日常是：小修改、重构、写单测，直接在终端里开 opencode 处理；看代码、查报错、做 Code Review，用 VSCode 插件在编辑器侧边栏里对话；复杂前端问题，我会配合 Playwright 让 opencode 自动复现和修复。整个工作流很顺手，下面逐步拆开讲。
2. 安装 opencode 与常见踩坑
2.1 各平台安装方式
opencode 安装方式挺多，我按推荐程度排一下：
- 官方安装脚本：
curl -fsSL https://opencode.ai/install | bash。这个脚本会把可执行文件装到~/.opencode/bin，并自动写入 shell 配置。macOS 和 Linux 上很省事。 - npm 安装：
npm install -g opencode-ai。如果你本来就有 Node.js 环境，这条路最快，后续升级也方便，npm update -g opencode-ai就行。 - Homebrew 安装：
brew install sst/tap/opencode。macOS 用户如果习惯用 brew，这个方式干净且好管理。 - Windows 用户：官方脚本和 npm 都能用，更建议直接用 npm，因为 Windows 下的脚本路径和权限问题相对多一些。装完如果提示找不到命令，看下一节。
需要注意，opencode 命令行工具依赖 Node.js 18 以上的运行环境，系统里没有 Node 的话，先装 Node 再装 opencode。装完之后验证一下版本：
opencode --version能输出版本号，就说明装好了。
2.2 “无法将‘opencode’项识别为 cmdlet”怎么处理
这个报错几乎可以排在我见过问题里的前三名，尤其 Windows 用户天天会遇到。搜索栏里那个无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称，本质就是系统 PATH 环境变量里没有 opencode 所在的目录，PowerShell 找不到这个命令。
解决办法分两步走。第一步，先确认 opencode 到底装到哪个目录了。用 npm 装的话，执行：
npm config get prefix假设返回的是C:\Users\你的用户名\AppData\Roaming\npm，那 opencode 的可执行文件就在这个目录下。用安装脚本装的话，位置一般在C:\Users\你的用户名\.opencode\bin。
第二步，把对应目录加进 PATH。Windows 上在开始菜单搜“环境变量”，打开“编辑系统环境变量”，在“用户变量”里找到 Path，编辑并新增上面那个目录，然后重启终端再试。macOS/Linux 上则检查.bashrc或.zshrc里有没有相关的 export 语句。
提示：改完 PATH 一定要开一个新终端窗口，别在旧窗口里反复试。旧窗口的环境变量快照不会自动更新，这是大多数人“明明配好了还是报错”的原因。
2.3 安装后先跑起来
装好之后，建议先找一个测试目录跑一遍opencode，快速确认它能正常启动并和模型通信。我第一次启动时卡在模型配置上，就是因为漏了这一步直接往大项目里冲，结果报错都不知道是环境问题还是模型问题。
mkdir ~/opencode-demo && cd ~/opencode-demo opencode启动后如果提示需要配置模型，先填一个最简单的 API Key 走通链路，再去研究多模型切换。这一步走通，后面所有功能才有基础。
3. 配置模型：免费模型、本地模型与 API 厂商
3.1 配置文件与模型注册
opencode 的配置核心是一个 JSON 文件，位置在~/.config/opencode/opencode.json（macOS/Linux）或%USERPROFILE%\.config\opencode\opencode.json（Windows）。第一次运行时它会自动生成，之后你手动改就行。
配置结构大概是这样的：
{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/ollama", "options": { "baseURL": "http://localhost:11434/api" }, "models": { "qwen2.5-coder:14b": {}, "deepseek-coder-v2": {} } }, "my-aliyun": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "你的阿里云百炼API Key" }, "models": { "qwen-max": {}, "qwen-plus": {} } } }, "model": "qwen-max", "theme": "dark" }这里npm字段指定的是 SDK 类型，@ai-sdk/ollama是本地 Ollama 用的，@ai-sdk/openai-compatible是兼容 OpenAI 协议的服务商通用的。只要你的模型服务商提供了 OpenAI 兼容接口，按上面这个格式填 baseURL 和 apiKey 就能用。国内不少服务商都支持这种接法，配置门槛很低。
不习惯手改 JSON 的话，也可以直接在 opencode 的 TUI 界面里按/models打开模型选择器，它会引导你添加 Provider。但我个人建议还是掌握 JSON 配置，因为一旦要管理多个项目、多个服务商，统一配置文件比界面点来点去高效得多。
3.2 不想给官方 API 充钱怎么用
官方模型虽然强，但很多人只是平时写着玩，或者预算有限，并不想一直按 token 付费。opencode 在这方面的宽容度很高，我试过三条“低成本路线”。
第一条是本地 Ollama 模型。电脑上装好 Ollama 之后，拉一个代码能力不错的模型，比如qwen2.5-coder:14b，配置写好 baseURL 为http://localhost:11434/api，opencode 就能直接用。本地模型的好处是免费、离线、隐私安全，坏处是速度和质量受硬件限制，16G 内存跑 14B 模型属于起步配置，只能做简单重构和解释代码，真要改复杂业务逻辑还是吃力。
第二条是各家服务商的免费额度。搜索热词里一直有“hy3-free 下线了吗”这类问题，其实就是有些人依赖模型聚合平台上的免费体验渠道。我的建议是：免费渠道当测试可以，别当主力。它们说下线就下线，你正改到一半，转头报unexpected server error. check server logs，心态直接崩。靠谱做法是用服务商的试用额度，或者选便宜的基础模型专门跑日常小任务。
第三条是“便宜模型干杂活，贵模型干重活”。opencode 支持在/models里随时切换，我平时把便宜模型设为默认，遇到复杂重构再切到更强的模型。比如简单补注释、改文案、写测试用例，用 qwen-plus 或者本地小模型完全够用；要设计架构、跨多个文件做大改动，再切到 Claude 或者更强的商业模型。这样一个月下来成本能压到非常低。
3.3 使用 ccswitch 统一管理模型配置
如果你同时在用 opencode、Claude Code、Codex 这类 Agent，每个工具的配置格式不一样，整天来回改还容易改错。社区里有个工具叫 ccswitch，专门用来集中切换这些 Agent 的模型配置，opencode 也能接入。
我现在的习惯是，把所有模型服务商的 API Key 和 baseURL 统一记在一个地方，ccswitch 负责把对应配置写到各个工具各自的配置文件里。这样换个模型，一条命令搞定，不用再打开三个 JSON 文件手动改。对于经常在多个项目里切换、不同项目用不同模型的人来说，这个组合很实用。
4. 把 opencode 放进 IDE、桌面端与高级技能
4.1 VSCode 插件和 JetBrains IDEA 插件怎么用
很多人习惯了图形界面，不想一直泡在终端里。opencode 官方提供了 VSCode 插件和 JetBrains 插件，装好之后，编辑器侧边栏会多出一个 Agent 面板，你可以在面板里和 opencode 对话，它会自动带上当前打开的文件内容、项目目录结构等信息。
VSCode 里直接在扩展市场搜 opencode 安装就行。JetBrains IDEA 用户在插件市场搜 opencode，安装后重启 IDE，侧边栏就会出现入口。这个面板特别适合处理“局部任务”：你可以选中一段代码，让它解释、找 bug、写单测、做风格调整，比从终端里手动描述文件路径方便很多。
需要注意插件的“自动执行命令”权限。默认情况下，opencode 可以调用终端命令，这在插件环境里是个安全隐患。我建议在 IDE 插件里把自动执行关掉，改成每执行一条命令之前都弹窗确认。改代码可以放开，但rm、git push、npm publish这类危险操作，保留人工确认。
4.2 opencode 桌面版与 Go、Java/Maven 项目的配置
opencode 官方还有桌面版，macOS 上体验不错，本质是把终端 Agent 装进一个独立窗口，适合不想切回原生终端的人。桌面版和 CLI 共用一份配置文件，所以在 CLI 里配置好的模型，桌面版直接可用。
至于热词里提到的opencode go、opencode mvn，其实是你在不同语言项目里使用 opencode 的常见姿势。Go 项目里跑opencode，它会自动识别go.mod，通过 LSP 索引项目结构，你让它“找到所有没有错误处理的函数”这类问题，它比凭空猜更靠谱。Java 项目则要注意 Maven 配置，比如项目依赖还没下载完，Agent 跑测试就会因为找不到类报错。我的习惯是，在 Maven 项目里先用mvn -q compile确认项目能编译，再开 opencode 让 AI 跑测试或改代码，否则 AI 会把编译环境问题当成业务代码问题，越修越乱。
提示：opencode 是接受“项目上下文”的，但它不是你项目的构建系统。项目本身如果连编译都过不了，别指望 AI 能替你解释清楚。先把工程问题解决，再交给 Agent。
4.3 skills 与 superpowers：为 opencode 装上可复用的技能包
opencode 支持 skills 机制，这是我和它配合效率提升最大的功能。你可以把它理解成给 Agent 定制“操作手册”：一个 skill 就是一组指令和提示词，告诉 opencode 在特定任务里该怎么做。比如我写了一个 “playwright-debug” 的 skill，里面写明：复现前端 bug 时先启动测试服务、用 Playwright 跑指定用例、截图保存到指定目录、再把报错信息拉回来分析。之后我只要对 opencode 说“用 playwright-debug 处理这个登录页跳转 bug”，它就会按这个流程执行，不用每次重新解释需求。
社区里的 superpowers 项目就是一组整理好的 skills 集合，可以直接装到 opencode 里使用，覆盖代码审查、测试生成、重构等常见场景。装法一般是把 skills 文件克隆到配置目录下的 skills 文件夹，然后在配置里声明启用。这些技能包的意义在于，它们把“资深工程师会怎么处理这件事”的经验沉淀成了可复用的代码，小白也能让 Agent 干出老手的活。
4.4 memory 机制：让 Agent 记住项目偏好
opencode 的 memory 功能解决了一个很实际的问题：AI 每次会话都是“失忆”的，你不说我每次都要重新解释一遍。比如某个项目里，测试命令是pnpm test而不是npm test，代码规范是不允许使用any类型，提交信息要用中文。以前我只能在每次对话开头重复一遍，现在我把这些写进 memory，opencode 在这个项目下会一直记得。
具体操作上，项目根目录的AGENTS.md或者 opencode 配置里的 memory 字段都可以用。它会变成 Agent 的“长期记忆”，每次启动自动加载。我强烈建议每个正式项目都维护一份这种文件，哪怕只有三行字，也比每次都跟 AI 重复一遍强。
5. 实际使用流程：接老项目、修前端 bug、跑回归
5.1 接手老项目的正确姿势
接手别人留下的老项目，最高成本是“理解现状”。我的做法是先在项目根目录运行opencode，第一轮对话不急着让它改任何东西，而是让它做三件事：读 README、列目录结构、看核心模块的入口文件。然后让它输出一份“当前项目的技术栈、模块划分、数据流向”的总结。
这个阶段推荐用只读模式，命令是opencode --read-only，或者直接在对话里跟它说“只分析，不要改”。这样既能拿到高质量的项目地图，又不会出现 AI 顺手替你改了几行代码的情况。等分析完，我再让它针对具体问题出修改方案，方案确认后才允许动手。整个过程像带了一个记忆力超强的新同事，先听他说懂了多少，再决定下一步。
5.2 真实场景：用 opencode 配合 Playwright 修前端 bug
分享一个我最近处理的具体案例。有个页面在特定浏览器宽度下，按钮被遮挡，用户点不到。这种 bug 人工排查要用 DevTools 反复调，但交给 opencode 配合 Playwright，我可以把流程做成半自动。
先在项目里配好 Playwright，并准备一个复现用例的脚本。然后我给 opencode 下达指令：
使用 playwright-debug skill，复现首页在 375px 宽度下的按钮遮挡问题。先跑测试，然后根据截图分析 CSS 定位问题，修复后重新跑测试确认。opencode 会依次执行：启动测试服务、用 Playwright 设置 375px 视口、打开页面、点击按钮、捕获截图和控制台报错，分析定位原因，修改样式文件，再跑一次用例验证。全过程它会一五一十地汇报在终端里，我只需要在关键节点确认改动是否合理。这个流程大大压缩了“复现→定位→验证”的循环时间，尤其是在布局类问题上，AI 对 CSS 的分析比我肉眼快得多。
5.3 让 Agent 安全地动手：权限与检查
open code 再怎么强，本质还是一个会犯错的新人。我坚持几条纪律：第一，危险命令必须手动确认，建议在配置里约束 opencode 才能执行的命令白名单；第二，每次修改后先git diff看改动，再提交，绝不让它自动往仓库里推代码；第三，大改动拆成小步骤，每步都让它说明意图，而不是一次性甩给它一个 1000 行的重构任务。
这样用下来，opencode 是在帮我干活，而不是制造一堆需要返工的垃圾改动。很多人觉得 Agent 不好用，不是因为模型不行，而是没有给它足够约束和反馈，又把太多操作权限放给了它。记住：高质量 AI 编程的秘诀是“强上下文 + 明确约束 + 人工兜底”。
6. 常见问题速查与几个我私藏的技巧
6.1 常见问题速查表
我整理了一份大家问得最多的问题表，基本都是我自己或者身边同事实际踩过的坑：
| 现象 | 常见原因 | 解决办法 |
|---|---|---|
| opencode 不是内部或外部命令 | 安装目录不在 PATH 里 | 找到安装目录并加入 PATH，重开终端 |
error: unexpected server error. check server logs | 模型服务商接口异常、Key 失效或余额不足 | 检查 API Key 和账户余额，切换模型，查看 opencode 服务日志 |
| 接入第三方模型后一直超时 | baseURL 填错或网络不通 | 先用 curl 验证接口连通性，再检查配置里的 baseURL |
| 改代码后测试还是挂 | Agent 未理解测试环境，或项目本身没编译 | 先手动跑通测试，再让 Agent 修；修复后重跑编译再验证 |
| 桌面版和终端配置不一致 | 配置文件路径被覆盖 | 确认两边读取的是同一个opencode.json |
| 模型切换后配置失效 | 新模型名称不在 models 列表里 | 在配置里补充模型声明，并在/models里重新选择 |
| 项目上下文太大，回答不准 | Agent 检索不到关键文件 | 用/files或 prompt 里显式指定文件路径，缩小检索范围 |
6.2 和 Claude Code、Codex CLI 怎么选
经常有人问 opencode、codex、claude code、还有更小众的 pi 到底哪个 agent 好用。我的判断依据是看你的核心诉求是什么：
| 工具 | 开源 | 模型自由度 | 生态/插件 | 上手难度 | 适合人群 |
|---|---|---|---|---|---|
| opencode | 是 | 高，任意 OpenAI 兼容模型 | 丰富，skills/memory/MCP 都支持 | 中等 | 想自定义、多模型切换、不想被绑定的人 |
| Claude Code | 否 | 低，主要走 Anthropic 模型 | 中 | 低 | 愿意付费、追求开箱即用顶配体验的人 |
| Codex CLI | 是 | 中，主要走 OpenAI 模型 | 中 | 中等 | 深度用 OpenAI 生态、看重 codex 云端任务的人 |
| pi | 是 | 高 | 中 | 中等 | 喜欢折腾终端 agent 的极客玩家 |
我不觉得有绝对的“最好”，只有“更适合”。如果你预算充足且不想折腾，Claude Code 的开箱体验确实顶级。如果你想要一个免费、可控、能接入自己模型体系、长期演进的工具，opencode 是这个赛道里我很看好的选择。
6.3 最后分享两个提高效率的小技巧
第一个是给 opencode 配置一个 shell 别名和自定义 prompt。我习惯在终端里直接用o代替opencode，并且在启动时自动带上一句话：比如“先看 AGENTS.md，再回答我的问题”。这样每次会话不用重复提醒，Agent 的第一反应就是按项目规范来。
第二个是把经常用的任务写成 skill。别怕写 skill 麻烦，你只要把每次给 Agent 的长指令里最稳定的那部分抽出来，存成 skill，下一次就是一条命令的事。我花了半天时间整理了五六个常用 skill，覆盖代码审查、单测生成、前端调试、提交信息生成，后续效率提升是肉眼可见的。
opencode 这种终端 Agent 的核心价值，我觉得不是“替你把代码写完”，而是把你从重复的机械劳动里解放出来，让你有更多精力放在设计、沟通和判断上。它像一个能听懂人话、会自己跑腿、但需要你把关的实习生，你得学会给它立规矩、配工具、划边界。把这些做好了，它就是你团队里最廉价又最能干的那个新人。
