opencode 最近在开发圈里热度涨得很快，身边不少朋友都在问它跟 Claude Code、Codex 到底有什么区别，值不值得切过来。我用了一段时间之后，最大的感受是：这玩意儿更像一个“开放版本”的终端 AI 编程代理，模型可以自己接，Skills 可以自己定义，甚至 IDE 插件、CLI、桌面端都有，折腾空间非常大。这篇就完整讲一下我从 0 到 1 用 opencode 的整个过程，包括安装、配置、上手、踩坑，希望能让初次接触的朋友少走点弯路。
1. opencode 整体认知：它到底是个什么工具
1.1 定位与核心能力
opencode 本质上是一个运行在终端里的 AI 编程代理（Agent），它能在你的项目目录里读代码、改代码、跑命令、查日志，并且以对话的方式和你协作。和 Claude Code 类似，它不仅仅是一个“代码补全工具”，而是一个能独立完成小任务、在遇到问题时主动询问你的“结对程序员”。
它的核心能力可以拆成几块：
- 项目感知：启动后会读取当前目录的代码结构、Git 状态、依赖信息，对话时能引用具体文件和行号。
- 多模型支持：不锁定某一家模型，可以接 Anthropic Claude、OpenAI GPT、本地模型（比如 Ollama 跑的开源模型）等，通过模型配置切换。
- Skills 机制：类似 Claude Code 的 skills，你可以把常用的提示词、脚本、工作流打包成一个 skill，让 opencode 随时调用。
- 工具调用：可以直接执行 Shell 命令、读写文件、并行调用任务，配合 Playwright 还能做前端页面的自动化测试和 bug 定位。
- IDE 集成：官方提供了 VS Code 插件和 JetBrains IDEA 插件，终端里写的逻辑在 IDE 里也能用。
我把它当成“可以自由换脑子的 Claude Code”。如果你之前用惯了 Claude Code，但被账号、限制、模型绑定烦到，opencode 这个“自由接线”的设计确实更贴心。
1.2 怎么正确理解 opencode 和同类工具的差异
经常有人拿 opencode 和 Claude Code、Codex 做对比。我的理解是这样的：Claude Code 是 Anthropic 官方出的，核心优势是跟 Claude 模型深度绑定，开箱即用；Codex 是 OpenAI 出的，偏向云沙箱环境，适合跑一些相对独立的任务；而 opencode 是开源社区搞的，最大的卖点是“可组合”和“可定制”。
也就是说，如果你追求“省心”，直接订阅 Claude Code 或 Codex 也可以；但如果你有多个模型账号，或者想用公司内部模型，又或者想把自己的工作流沉淀成 skill 复用，那 opencode 会更顺手。比如我手头有企业级 Claude 的 API，也有一个本地部署的模型，opencode 可以一套界面切换，不用在两个工具之间来回折腾。
还有一个容易被忽略的点：opencode 的命令行输出做得非常克制，错误信息也相对友好。它对“被接管”的恐惧感更低，你可以随时 Ctrl+C 打断，它也不会疯狂刷屏。这一点对于像我这样喜欢盯着终端看的人来说，体验提升是实打实的。
2. 安装与环境准备：从零把 opencode 跑起来
2.1 不同系统下的安装方式
opencode 的安装方式有好几种，我试下来最稳定的是直接用安装脚本，或者用包管理器。Windows、macOS、Linux 都有对应的渠道。
先说说我用的 macOS 环境：
curl -fsSL https://opencode.ai/install | bash它会自动下载二进制文件放到~/.opencode/bin，然后在 shell 配置里加一条 PATH。安装完重开终端，执行opencode --version就能看到版本号。
Windows 用户如果遇到“无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称”这个报错，绝大多数情况是 PATH 没配好。安装脚本会把 opencode .exe 放到%USERPROFILE%\.opencode\bin，你需要手动把这个路径加到系统环境变量里，然后重新打开终端。还有一个小坑：如果之前用其他方式装过旧版本，旧 bin 目录和新 bin 目录冲突也会导致命令找不到，这种直接把旧的残留目录删掉，确保当前只剩一个 opencode 可执行文件。
Linux 用户我建议直接用二进制包，从官方 release 页面下载对应架构的压缩包，解压后扔到/usr/local/bin或者~/.local/bin。如果你用的是 Arch Linux，AUR 里也有现成包，装起来更省事。执行完opencode没反应时，记得先检查一下当前终端的 PATH 里是否包含你放置二进制的目录。
2.2 初始化配置和第一条对话
装好之后直接敲opencode，它会进入交互式会话。首次运行会在项目根目录自动生成.opencode文件夹，里面是配置缓存和日志。这里有个比较重要的概念：opencode 的角色类似于“当前目录下的 Agent”，所以你的当前工作目录最好就是项目根目录。如果你在错误的目录启动，它看到的代码就是错的，改文件时也会改错位置。
我建议第一次使用前先跑一下：
opencode如果一切正常，你会看到它询问选择哪个模型。这个模型列表来自你的环境变量或者配置文件，不是说打开就有全部模型。最简单的做法是在终端里先设置：
export OPENCODE_MODEL=anthropic/claude-sonnet-4然后再启动 opencode。后续想永久生效就写进 shell 的 rc 文件里。
第一次对话我通常会这样问它：
帮我介绍一下这个项目的目录结构，以及核心模块的职责。它能比较准确地分析出来，并且引用具体文件。如果它给出的信息有偏差，不用慌，很可能是模型上下文没有吃到关键文件，你可以让它先读取一下README.md再继续。
2.3 关于“Linux 修改 json”和配置文件位置
很多人在网上搜“opencode linux 修改 json”，其实是在问 opencode 的配置文件在哪。不同版本存放路径略有区别，但一般会遵循 XDG 规范：
- Linux：
~/.config/opencode/opencode.json - macOS：
~/.config/opencode/opencode.json或者~/Library/Application Support/opencode/opencode.json - Windows：
%APPDATA%\opencode\opencode.json
这个文件用来配置模型提供商、API Key、默认参数等。比如我想加一个自定义的 OpenAI-compatible 服务，就可以在opencode.json里写：
{ "provider": { "myprovider": { "npm": "@ai-sdk/openai-compatible", "name": "My Provider", "options": { "baseURL": "https://api.example.com/v1", "apiKey": "{env:MY_API_KEY}" }, "models": { "my-model": { "name": "My Model" } } } } }这里{env:MY_API_KEY}表示从环境变量读取 API Key，不要把密钥直接写进文件里。我踩过这个坑，有一次不小心把密钥提交到仓库，结果几分钟之后就被别人扫走盗刷了一笔。所以强烈建议所有 API Key 都走环境变量。
3. 模型配置与 Skills：让 opencode 真正贴合你的工作流
3.1 模型选择与“go 订阅模型”到底指什么
热词里经常出现“opencode go 订阅模型选择”，这里说的“go”不是指 Golang，而是指 opencode 官方提供的订阅服务“opencode go”。它类似于一种打包的模型订阅，付完费用之后可以在 opencode 里直接使用多种主流模型，不需要分别去各家控制台申请 API Key，也不用自己维护多个供应商的额度。
在opencode里执行：
opencode go auth会弹出一个浏览器页面让你登录，登录完之后，模型列表里会出现opencode-go/...开头的一系列模型。你可以在启动时通过-m参数选择：
opencode -m opencode-go/claude-sonnet-4如果你是学生或者个人开发者，这个订阅的价值在于“一个入口用多个模型”，省去了挨个充值的麻烦。但如果你公司本来就有 Claude 和 GPT 的 API 额度，那自己配 provider 其实更灵活，成本可能也更低。
这里我需要提醒一句：订阅模型之前先看清楚套餐包含哪些模型，不同套餐的速率限制、上下文长度、并发数都不一样。曾经有朋友买了个基础套餐，结果跑大项目时频繁触发 rate limit，我还以为模型有问题。后来换成更高档位才解决。真别图便宜直接买最低档，先看自己日常有没有大文件、长上下文的场景。
3.2 免费模型怎么接
“opencode 免费模型”这个话题很火。如果你不想付费，opencode 也支持接免费的模型接口，比如：
- 本地用 Ollama 跑
qwen3-coder之类的开源模型。 - 一些云服务商提供免费额度，开头是
openrouter/free:model-name。
接 Ollama 比较简单。先在本地安装并启动 Ollama，拉一个模型：
ollama pull qwen3-coder:14b然后在 opencode 的配置文件里加入：
{ "provider": { "ollama": { "npm": "@ai-sdk/ollama", "name": "Ollama", "options": { "baseURL": "http://localhost:11434/api" }, "models": { "qwen3-coder:14b": { "name": "Qwen3 Coder 14B" } } } } }接着启动 opencode 的时候选择ollama/qwen3-coder:14b就能用了。
体验上，本地 14B 模型跑简单需求、改改小 bug 完全够用，但在大仓库里的理解能力比旗舰模型差不少，尤其重构类和跨文件调用分析，基本不太行。不过胜在免费、数据不出本机，适合对隐私敏感的场景。
3.3 Skills 的实战配置：把重复性工作封装成“技能”
热词里也有“opencode skills”。什么是 Skills？我理解它是给 opencode 预设好的指令模板，告诉它在某种场景下应该用什么方式工作。它不是一个简单的提示词短句，而是包含指令、示例、工作流说明的一个目录。
举个例子，我团队里经常需要给前端组件写 Storybook，纯人工写既啰嗦又容易漏。我在项目里建了一个 Skill，目录结构如下：
.opencode/skills/write-story/ ├── SKILL.md └── templates/ └── component.story.tsx.tmplSKILL.md内容大致是这样的：
# 写 Storybook 用例 当用户要求“给某个组件写 story”时，遵循以下步骤： 1. 读取组件源码和 prop 类型。 2. 找到同名 stories 目录下是否已有类似用例。 3. 参考 templates/component.story.tsx.tmpl 模板生成新的 story 文件。 4. 在终端运行 `npm run test:story` 验证。这样我在对话里只要说“给 Button 组件写 story”，opencode 就会调用这个 Skill，按流程处理。Skill 相当于把“人怎么做这件事”教给了 Agent，效果稳定了很多。
在这里要养成一个习惯：skill 里的指令要尽量具体，能给出文件路径就给路径，能给出明确的验证命令就给命令。Agent 不是你肚子里的蛔虫，它只能靠信息做推断。你写得越细，它的执行越稳。
4. 实操过程：从“接手老项目”到“修前端 bug”
4.1 入手老项目的正确姿势
热词里有一个“opencode 接手开发项目”，这个场景我太熟了。接到一个陌生仓库，短时间要改功能或者修 bug，最怕的就是一头扎进海量代码里找不到北。opencode 对这种场景的价值非常大，因为它能基于全项目索引快速定位。
我通常会在项目根目录启动 opencode，然后先让它执行：
帮我梳理一下这个项目： - 使用了哪些主要框架和语言 - 启动方式是什么 - 有没有测试命令 - 核心业务模块有哪些，入口在哪opencode 会读取 package.json、README、目录结构、关键配置文件，然后用几句话概括出来。这一步能帮你节省至少半小时的阅读时间。如果你觉得回答不够详细，可以追加问题，比如“用户登录相关代码在哪个目录”，它会顺着之前的分析往下查。
确认理解之后，再开始派单。举个例子，如果需求是“增加导出 Excel 功能”，你可以这样描述：
在用户列表页新增导出按钮，点击后调用 /api/user/export 接口，拿到文件流后下载并命名为“用户列表_日期.xlsx”。 请先找到用户列表页对应的组件和后端接口定义，再告诉我要改哪些文件。它会把涉及到的文件找出来，列出改动计划，你确认后再让它动手。这里有个经验：让 opencode 先列计划再改代码，比直接让它改要省心得多。因为模型对项目结构的理解是有上下限的，你先让它把计划说出来，相当于一次免费的代码评审。
4.2 Playwright 定位前端 bug 的骚操作
“opencode playwright 怎么测试前端 bug”也是高频问题。opencode 有一个内置 Playwright 工具，可以在浏览器里自动化操作页面，配合模型实现对前端问题的“眼见为实”。
比如，页面上的提交按钮点击后没反应，正常人工排查得打开 DevTools 看 Console、看 Network，很费时间。用 opencode 的场景是这样的：
opencode --playwright启动后它会有一个浏览器环境，你可以在对话里指示它：
打开本地开发服务器 http://localhost:3000/login，点击“登录”按钮，然后打开控制台，把报错信息贴给我。opencode 会通过 Playwright 执行操作，并读取控制台日志。它还能截图给你看页面状态。有一次我遇到一个只在特定分辨率下才出现的布局错乱，用对话生成截图对比不同 viewport，很快就确认了是响应式断点写错了。
这个能力对测试人员也很友好。你不需要学 Playwright 的 API，直接用自然语言描述“打开页面-点击-输入-验证”，它就能帮你完成。不过要注意，opencode 的 Playwright 操作有时会因为元素选择器识别不准而失败。我的经验是：先让它用locator的role或text去定位元素，比裸写 CSS 选择器稳定得多。
4.3 LSP 与代码导航的高效用法
“opencode 如何使用 lsp”这个话题，其实是在问 opencode 怎么做到精准跳转、引用查找。opencode 支持 LSP（Language Server Protocol），它可以借用语言服务器来获取项目的语义信息，而不是只依赖关键词搜索。
开启 LSP 之后，你在对话里问“这个函数被谁调用了”，它就可以基于语法树找到引用位置，而不是简单地 grep 字符串。这个能力在改公共方法、重命名变量时特别有用。
安装语言服务器属于可选项，取决于项目类型。TypeScript 项目一般用typescript-language-server，Python 用pyright。在配置文件里可以指定：
{ "lsp": { "typescript": { "command": "typescript-language-server", "args": ["--stdio"] } } }配完之后重新启动 opencode，对话提问时它会自动加载 LSP 信息。不过我不建议所有项目都硬上 LSP，那种超大 monorepo 项目首次索引可能要几十秒，反而拖慢速度。小中型项目开一下，体验提升很显著。
4.4 代码架构调整和批量重构
opencode 做批量重构也是一个强项。比如把整个项目里所有moment.js的用法替换成dayjs，或者把所有console.log改成统一封装的logger.info，这种机械但工作量巨大的任务，完全可以交给它。
我会先用一两个文件做示例，让它理解我的目标，然后询问它“还有哪些文件需要同步修改”，它会给出清单。确认清单无误后，再让它执行替换。这里最重要的原则是：小步提交 + 命令验证。每改完一批文件就运行一次编译或测试，发现问题能快速定位到具体代码块。
有一次我让它把 API 请求库从 axios 换成 fetch，它确实改得很完整，但漏掉了几个边界情况下的拦截器处理。原因是我在需求里没有明说“我的拦截器逻辑需要保留”，所以这一步模型是无辜的。后来我把需求描述改成“保留原有 request 封装的所有行为，包括 token 注入，统一错误提示”，它处理得就完美了。所以，清晰的验收标准比清晰的代码指令还重要。
5. 常见问题与避坑实录
5.1 终端报“无法将 opencode 项识别为 cmdlet”怎么办
这个报错主要出现在 Windows PowerShell 里，原因就是 opencode 不在 PATH 中。网上很多帖子只说“配置环境变量”，但没详细说明具体点。我实际处理过几次，步骤是：
- 打开“此电脑”右键属性 -> 高级系统设置 -> 环境变量。
- 找到用户变量里的
Path，编辑，新建一行输入%USERPROFILE%\.opencode\bin。 - 确定保存，然后退出当前 PowerShell，重新打开。
- 执行
opencode --version验证。
如果你是用 Scoop 之类的包管理器装的，那对应 bin 路径可能不一样，直接在装的时候会提示你。还有人在 Windows 上遇到opencode被 Microsoft Store 的别名干扰，比如系统自带的opencode是另一个应用，这会让你明明装好了却跑错程序。可以用where.exe opencode查看实际调用的路径。
5.2 “This model is not available in your country”错误
这也是热词里的常见报错，大意是当前模型在你的所在地区不可用。产生的原因很简单：模型提供商会根据访问 IP 判断服务区域，如果 IP 所在区域不在服务范围内，就拒绝访问。
这里我能给的安全解决方案有两个方向：
- 更换模型。如果你在 opencode 里用的是某个平台聚合的模型，可以换一个同平台支持的其它模型。比如从 claude 切到 gpt，或者切到开源模型，验证一下问题是否还在。
- 通过正规渠道开通模型可能支持的区域版本。有些模型在不同区域有不同版本，你可以在服务商页面查看文档，确认自己所在区域是否有对应入口，或者联系客户服务申请开通。
这里有一个实操排查技巧：先在opencode外单独用 curl 测试一下模型 API，如果 curl 返回同样错误，那必然是提供方限制；如果 curl 正常，只有 opencode 里报错，则要看配置是不是写错了地区参数或端点。别一看到 “country” 就以为是网络层面的问题，先检查配置更靠谱。
5.3 “Unexpected server error. Check server logs”怎么处理
有用户在热词里提到：
c:\windows\system32>opencode error: unexpected server error. check server logs这个报错一般跟 opencode 后端启动有关，常见原因有三个：
- 权限不足。有些系统目录下运行 opencode，写不了配置目录或临时文件。解决办法是不要在 C 盘系统目录直接跑，换到普通用户目录或者项目目录里。
- 端口冲突。opencode 自带一个本地服务，如果 80 或常用的本地端口被占用，就会报错。你可以观察终端日志里有没有
listen tcp: bind: An attempt was made to access a socket in a way forbidden by its access permissions，如果有，就在配置里改端口。 - 版本不一致。比如二进制文件是最新版，但配置里指向的插件或者模型 SDK 是旧版，这也是偶发的。解决办法是先升级 opencode 到最新版本，再删除
~/.config/opencode下的缓存文件夹重试，当然删除之前先备份自定义配置。
日志通常位于~/.local/share/opencode/log/下。排查时打开最新日志文件，找到error关键字，很快就能定位到根因。
5.4 热词中的其他疑问梳理
“ccswitch 配置 opencode”：这个工具本身是管理多个 AI 服务商配置的一个辅助工具，你可以在 opencode 里用类似的方式管理不同的 provider。配置方式就是把对应的 API 地址和密钥设到环境变量里，让 opencode 读取。
“opencode desktop”：opencode 除了终端版，还有桌面版，相当于把终端交互搬到了图形界面里。其实在 vscode 插件里也可以嵌入，功能相差不大，看个人习惯。
“opencode omo”：这个单词我查了下并不是 opencode 的官方组件，更多是网上用户自己的配置组合，如果遇到相关配置项，建议以官方文档为准。
“opencode pi”：可能存在两个含义，一是“PI”是某个模型名的缩写，二是指树莓派（Raspberry Pi）上运行 opencode。我确实在树莓派上试过 4GB 内存跑小模型，能用但体验一般，性能瓶颈主要在模型推理，不在 opencode 本身。如果你准备在树莓派上跑，建议选用 7B 以内的量化模型，否则基本没法用。
“opencode 2.0”：opencode 版本迭代比较快，社区里说 2.0 一般指代某个大版本更新，具体升级了哪些功能要以官方 changelog 为准。我的建议是跟新版本不要太激进，等一两个小版本稳定后再升级，避免被新 bug 影响。
6. 我的日常使用技巧与心得体会
6.1 善用 opencode 来学习陌生代码库
我入职一家新公司时，最头疼的是理解一个七八年历史的后端系统。后来我直接把仓库 clone 下来，用 opencode 去问“用户权限判断逻辑在哪些地方出现”“支付回调失败后重试机制是什么”，它都能给出行号以及相关代码片段。配合 IDE 插件，边看边点，比纯翻文档效率高不少。
但有一点要提醒：当它给出不确定的答案时，自己一定要去读一遍真实代码。模型可能因为上下文太长导致记忆混淆，所以重要结论必须人工二次确认，尤其是涉及资金、权限、数据删除这类高风险逻辑。
6.2 把 opencode 接入 CI 做自动化 Code Review
我现在会把 opencode 接到团队的自有 CI 流程里，当开发者提交 MR 后，用 opencode 生成初步审查意见，重点关注潜在 bug、边界条件、资源泄漏，以及和现有代码风格不一致的地方。它会输出类似 “这个函数可能会在数组为空时 panic” 这类判断，我们人工再复核一遍，能拦下不少低级问题。
实际接入用官方 CLI 命令就可以，比如：
opencode exec "review the diff between commit A and commit B, focus on correctness and error handling"注意这里要配置好模型和上下文。我不建议让它直接 review 整个项目，那样既慢又不精细，固定在 diff 范围内效果最好。
6.3 一些细节上的小建议
- 用好
.opencodeignore文件：类似.gitignore，可以把node_modules、dist、vendor等目录排除掉，避免 opencode 读取无意义的文件，能显著提升响应速度。 - 定期清理会话：opencode 的会话日志如果积累太多，也会占存储空间，可以在设置里找到历史清理功能，或者直接删除历史缓存。
- 多项目调度技巧：如果你同时开着两个 opencode 实例操作不同项目，一定要确认每个实例的工作目录是否正确。我就犯过在 A 项目里输入命令，结果改到了 B 项目文件的乌龙，因为两个终端窗口长得差不多。
- 模型温度调低一点：代码生成任务对随机性要求比较低，可以从配置中把
temperature调到 0.1 左右，输出会更稳定。这个没有统一默认值，修改模型配置就能设置。
最后再分享一个小技巧：opencode 的交互界面支持/命令，比如/help、/config、/session。如果在对话过程中不确定下一步怎么操作，直接输入/会弹出命令菜单，这是个很容易被忽略但非常实用的功能。我自己用过一段时间后，基本不手动翻文档了，所有操作提示在对话上下文里都有。
