最近这两个月我几乎每天都在用 opencode 写代码。本来只是看它上了 GitHub 热榜想装来试试水结果它直接成了我终端里最常用的工具之一。如果你还没用过 opencode简单说它是一个开源的、跑在终端里的 AI 编程智能体你可以像跟同事对话一样告诉它“这个页面有个 bug帮我查一下”它会自己读项目、写代码、跑测试甚至调 Playwright 去复现前端问题。它跟 Claude Code、Codex 是一类东西但它是开源的而且模型不受绑定官方模型、本地模型、免费模型都能接。这篇文章我打算把 opencode 的安装、配置、核心玩法、实战案例和常见坑一次性讲清楚。适合谁看如果你在用或者正在纠结 Claude Code、Codex、pi 这类 agent或者你一直想找一个不绑死单一模型的终端编程助手那这篇应该能帮你省不少时间。1. opencode 到底是什么它解决了我什么痛点1.1 用一句话定位 opencodeopencode 是一个终端里的 AI 编程智能体它提供了一套交互式的 TUI文本界面你输入一句任务它会把任务拆成步骤然后调用工具去完成。这里的“工具”包括读写文件、执行 shell 命令、运行测试、搜索代码等等和你在 IDE 里用 Copilot 那种“补全下一行代码”的辅助完全不是一个量级。它更像一个坐在你旁边、会自己动手翻仓库的同事。我最初吸引我的是它的定位不离开终端。我本身是重度终端用户日常开发已经习惯了 Vim 和 tmux打开一个 IDE 反而觉得重。opencode 装好之后直接在项目目录里敲一下opencode就进了一个全屏终端工作区左边是对话区右边是文件 diff下方可以执行命令。它还会主动调用外部工具比如读一个文件前先看文件大小、用 ripgrep 搜索关键字、跑npm test来验证自己的修改这些都是真实可复现的操作不是模型在脑内幻想。另外它还接入了模型切换能力。你可以用同一个会话切到不同模型而不是每次换模型都要重新搭环境。这种做法对想对比模型效果的人来说特别友好。我最近在几个项目里实测下来opencode 2.0 的 TUI 明显比早期版本顺滑命令面板、diff 预览、上下文管理都做得更成熟了这也是我决定把它写成一篇完整教程的原因。1.2 对比opencode、Claude Code、Codex怎么选先说结论没有绝对最好的 agent只有更匹配你工作流的工具。我用过 Claude Code 和 OpenAI 的 Codex也看过 pi 的演示下面这张表是我个人的主观体验供你参考。工具是否开源模型绑定核心亮点适合谁opencode是不绑定可接多种模型TUI 体验好支持 skills、memory配置灵活喜欢终端操作、想自主控制模型的人Claude Code否有开源部分主要绑定 Anthropic 模型和 Claude 模型能力结合深复杂推理强Claude 生态重度用户Codex否主要绑定 OpenAI 模型与 OpenAI API 结合好执行代码能力稳OpenAI 生态重度用户pi不确定/各有说法多为某一家模型交互简洁喜欢极简风格的人我为什么最后长期用 opencode因为它是这几个里面唯一一个让我能自由接本地模型的。我可以在内网环境、没有外网 API 的情况下用 Ollama 跑一个 7B 的代码模型照样实现自动化改代码、写测试。这种自由度是商业化产品很难给的。当然如果你只依赖 Claude 或 GPT 的顶级推理能力且预算充足那 Claude Code 和 Codex 也没问题。1.3 谁适合用 opencode如果你满足下面任意一条我建议你试试日常开发在终端里完成习惯 Vim/Neovim 或 JetBrains 系 IDE 的内置终端。有多个模型账号比如自己买了 OpenAI API公司又有 Anthropic 的 key不想被工具锁死。希望 AI 能真正帮你跑命令、读日志、改文件而不是只能生成一段代码让你自己粘贴。对数据敏感希望代码分析尽量在本地完成或者至少能把模型切成内网可访问的私有部署。如果你是刚接触命令行的新手也不是不能用但最好先会基本的文件操作和 git 流程。因为 opencode 再怎么智能它改完代码后你还是得看懂 diff、处理冲突。它更像一个能力很强的实习生你既要会派活也要会验收。2. 安装与基础配置从零开始跑起来2.1 三种安装方式总有一种适合你opencode 的安装路径还挺多。我这里列三种我实际用过的按推荐程度排序。第一种用官方一键脚本安装。macOS 和 Linux 用户直接在终端执行官方文档里的安装命令它会自动下载最新二进制写到你的用户目录下然后告诉你把某个路径加入 PATH。安装完成后重新打开一个终端运行opencode --version能输出版本号就说明成功。这个方法最简单适合大多数用户。第二种用 Go 自带的命令安装。如果你本机装了 Go 环境可以直接执行go install github.com/sst/opencodelatestopencode 本身是用 Go 写的所以go install相当自然装的就是当前 release 版本。装完之后二进制一般会出现在$GOPATH/bin或$HOME/go/bin下记得确保这个目录在 PATH 里。热词里很多人搜“opencode go”大概率就是在找这种安装方式。第三种用包管理器安装。比如 macOS 用户可以用brew install opencode这种命令Windows 用户则可以用scoop或winget。不过包管理器里的版本可能比官方 Release 慢一两个小版本如果你不追新倒也没差。另外官方还有桌面版opencode desktop不想在终端里折腾的人可以直接装桌面客户端。我试下来它的底层引擎和 TUI 是一样的只是包了一层图形界面适合把 opencode 当“独立应用”用的人。但我个人还是推荐从 TUI 入门因为桌面版有些高级配置项还是得看命令行日志。2.2 首次启动与模型接入在项目目录下直接运行opencode会进入首次引导界面。它会让你选一个默认模型并要求填 API Key。如果暂时不想填也可以选“跳过”进入之后再通过命令配置。opencode 的配置文件默认放在~/.config/opencode/文件名通常是opencode.json或config.json具体以你本机版本为准。它的核心逻辑就是配置多个 provider然后在会话里随时切换。下面是我自己的一个简化示例{ provider: { anthropic: { apiKey: env:ANTHROPIC_API_KEY }, openai: { apiKey: env:OPENAI_API_KEY } } }这里我用了env:前缀意思是 API Key 从环境变量里读而不是把明文写在配置文件里。这样做的好处是不小心把配置分享出去时不会泄露密钥。如果你在团队里用更应该在.gitignore里把配置文件排除掉或者用密钥管理工具注入环境变量。启动之后进入 TUI 主界面用/能调出命令面板。我常用的命令有/new开一个新会话/context手动把某些文件加进上下文/models切换模型/tokens查看当前上下文占用比例。你版本里如果没有这些命令在命令面板里搜一下关键词就行。2.3 免费模型怎么接两条安全可行的路线热词里“opencode 免费模型”搜索量很高说明大家都不想一开始就花冤枉钱。我实测下来有两条免费路线是稳定可用的而且不涉及任何灰色操作。第一条本地模型。以前我觉得本地模型只能玩玩后来发现对很多日常任务完全够用。先装 Ollama然后拉一个代码模型比如ollama pull qwen2.5-coder:7b然后在 opencode 配置里加一个 provider把 endpoint 指向http://localhost:11434模型名填qwen2.5-coder:7b。这样 opencode 就完全在本地跑不需要任何外部 API也不用担心限流。它的优点是免费、离线、数据不外传缺点是 7B 这种规模的模型处理复杂重构时会有点吃力更适合用来解释代码、生成测试、做全局搜索。第二条云端免费额度。不少平台注册后会送一定额度的 API 调用你把它的 endpoint 和 key 填进 provider 就行。不过这类免费源稳定性参差我见过有人用某个免费模型源用了一个月突然返回 503所有自动化脚本跟着挂掉。所以我的建议是免费模型可以做头脑风暴、写单元测试、解释报错这类容错率高的任务关键生产代码还是用付费的强模型比较稳。热词里有人问“hy3-free 下线了吗”这种事其实挺常见免费服务说下线就下线与其纠结某个源不如多配置几个备胎。3. 核心玩法拆解模型切换、skills、memory3.1 /models 切换模型的正确姿势opencode 最吸引人的一点就是它可以在同一个会话里切换模型。你正在用 Claude 写代码突然觉得某个问题 GPT 可能更擅长直接打开/models切换就行。但这里面有一个很容易踩的坑切换模型之后上下文不会完全无缝衔接。不同模型对上下文的组织方式不一样特别是系统提示和工具调用历史的格式。如果在一个长会话里频繁切换后一个模型可能读不懂前一个模型留下的“思维链”回答质量会明显下降。我的经验是尽量在任务开始时就把模型选好不要在任务中间反复横跳。如果确实需要切换最好先把当前进度和关键结论复制出来作为新的任务描述重新开一个会话。另外我还喜欢用“轻量模型做探索重量模型做实现”的组合打法。比如让一个便宜、快速的本地模型先读一遍项目结构找出相关文件生成一个大致的修改方案然后再切到 GPT-4 或 Claude 这种强模型让它基于方案写出具体代码。这样能省一点 API 费用效率也更高。3.2 skills 机制让 opencode 学会你的专属技能skills 是 opencode 一个非常有用的扩展机制。你可以把它理解成“预置的技能包”每个 skill 由一个说明文档和若干示例脚本组成告诉 agent 在遇到特定任务时应该怎么做。比如你可以写一个code-review.md技能里面写清楚你们团队的代码规范、需要检查哪些点再附一个脚本让它自动列出本次改动的文件。之后只要说“帮我 code review”opencode 就会自动加载这个技能按你的规则执行。这个机制和 Anthropic 的 Agent Skills 格式是兼容的所以网上很多现成的技能包可以直接用。热词里提到的“oh-my-claudecode”本身是一套给 Claude Code 用的增强配置里面有大量 skills 和 agent 规则我可以直接把它的 skills 目录复制或软链到 opencode 的项目目录.opencode/skills/下大部分都能正常识别。我自己写 skill 的时候一般会在项目根目录建一个.opencode/skills/技能名/SKILL.md里面用 Markdown 写清楚技能名称、描述、适用场景和执行步骤。opencode 在每次任务规划时会读取这些描述判断是否需要调用这个技能。写完之后在会话里输入opencode会自动重新加载不需要重启。如果你写了技能但 agent 一直不调用先检查描述是否足够具体最好带上关键词比如“当用户提到代码审查或 code review 时必须使用这个技能”。3.3 memory 持久化跨会话记住项目背景默认情况下opencode 每次新会话都是一张白纸但很多项目背景信息是反复需要的比如“这个项目是微服务架构API 统一走网关前端用 Vue 3测试用 Vitest”。如果每次都要重新交代一遍太浪费上下文。opencode 支持 memory 机制可以把这类背景信息持久化下来。我的用法是在项目根目录放一个opencode.md或者在全局配置里加一段 memory 内容把项目常用的命令、技术栈、目录结构和注意事项写清楚。agent 每次启动新会话时会把这部分内容作为潜台词自动加载。这就像给助手写了一份入职文档它每天上班前先读一遍自然不需要你反复唠叨。需要注意memory 不是越长越好。写太多无关信息反而会挤占上下文窗口影响真正任务的体现。我一般控制在 20 行以内只写“必要但易忘”的事情。除了项目级 memoryopencode 也能记住一些用户偏好比如“永远不要主动删除文件”“改代码前先跑一遍测试”“提交信息用英文”等。把这类偏好写进全局配置它能长期遵守。4. 实战拿 opencode 接手一个前端项目并修 bug4.1 新手也能快速接手一个老项目很多同学不敢让 AI 直接接触老项目觉得它肯定搞不定。我的实测结论是只要项目不是特别冷门opencode 的表现比大部分人想象中好。我第一次用它接手一个历史遗留前端项目时直接在新会话里输入了这样的指令先读 README.md、package.json 和 src 目录结构告诉我这个项目怎么启动 然后帮我把它跑起来如果启动有问题就根据报错自己排查。opencode 会先列出当前目录找到 README 和 package.json读取里面的 scripts 命令然后尝试启动开发服务器。它看到端口被占用时会去查是谁占用的需不需要换端口执行npm install失败时会看报错尝试修复依赖。这个过程是透明的每一步它都会在对话里给出解释你也可以随时打断它。我的建议是让 AI 接手老项目之前先把 git 状态弄干净至少提交一次当前改动。这样即使 AI 改坏了你也可以随时git checkout回滚。另外在任务描述里明确“先不要改代码只做调查”等你把项目结构搞清楚了再进入修改阶段。4.2 用 Playwright 复现前端 bug有一次我的任务是修复一个登录表单 bug输入用户名和密码后点击登录页面没有任何提示控制台也没有报错。这种问题自己排查要开 DevTools、加断点、反复试很费时间。我给 opencode 的自然语言指令是这个登录表单用户名输入 admin密码随意输入点登录按钮后没有任何提示。 帮我用 Playwright 写一个复现脚本运行它并抓取浏览器控制台的所有报错信息。opencode 会先检查项目里有没有安装 Playwright没有的话就安装然后写一个reproduce.spec.ts脚本启动浏览器、访问本地开发服务器、填写表单、点击按钮、监听 console 和 pageerror 事件。脚本跑完后它会把控制台输出拿回来分析。那次的问题最终定位到某段旧代码里事件绑定用的元素选择器在新版页面里不存在导致点击事件被静默吞掉。这里有一个技巧让 AI 把复现脚本保存下来不要跑完就删。后续修改代码后可以反复跑同一个脚本做回归验证。opencode 不会主动清理文件但如果你不说明它可能生成到临时目录。最好在任务里带上“脚本保存到tests/reproduce/目录”这种明确要求。4.3 定位根因与自动修 bug拿到控制台报错或者 Playwright 的失败结果之后可以让 opencode 去源码里搜索相关代码根据报错信息找到登录按钮的事件绑定代码分析为什么点击后没有触发请求。 先不要改给我看定位过程和候选修复方案。它会用 ripgrep 搜索事件绑定的关键词比如login、handleSubmit、addEventListener再结合上下文判断问题原因。最后生成一个 diff 供你确认。我习惯让它用git diff展示改动而不是直接覆盖文件。虽然这样多了一步但能避免它在一堆相关重构里夹带无关修改。等确认 diff 没问题再让它继续跑测试或 Playwright 脚本做验证。如果你接手的项目是 Maven 工程也别忘了让 opencode 读取pom.xml。AI 对依赖的理解直接影响它改代码的准确性我通常会在任务描述里补充一句“先读一下 pom.xml确认项目用的框架版本再分析代码”。4.4 IDE 插件联动VSCode / JetBrains 里的推荐用法很多人问“opencode 有没有 VSCode 插件”“IDEA 里能不能用”。我的看法是opencode 本身是 TUI 工具最稳妥的用法就是在 IDE 的内置终端里直接跑它。VSCode 的Ctrl \ 打开终端输入opencode左边是编辑器右边就能和它对话体验已经很接近一个 IDE 插件了。JetBrains 系也一样AltF12 打开终端直接跑命令。当然官方和社区也有对应的 VSCode / IDEA 插件它们做的事情其实就是在 IDE 侧边栏嵌入一个终端面板方便你点击复制、查看 diff。如果你已经装好了 opencode这类插件不是必须的。真要说有什么好处可能是它能把 opencode 的会话和当前打开的文件关联起来方便快速把文件路径加入上下文。但这个功能我自己用得不多因为直接在会话里拖拽路径也很快。我个人的习惯是在 VSCode 里配置一个快捷键按下之后自动打开终端并执行opencode省去每次敲命令的工夫。JetBrains 也可以用类似方式配置 External Tool。这样既保留 IDE 的代码跳转、重构能力又能享受 opencode 的 agent 能力。5. 高频问题排查报错都在这里找答案5.1 Windows 下“无法将 opencode 项识别为 cmdlet”怎么办这个报错在热词里出现了很多次典型提示是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。原因基本只有一个opencode 的安装目录没有被写进系统的 PATH 环境变量。尤其是用go install或 npm 方式安装后二进制文件在某个目录但终端不知道去哪找。解决办法分三步重新打开一次终端因为环境变量在终端启动时读取新安装的 PATH 不会自动生效。确认安装目录。如果是go install执行go env GOPATH看看bin目录是不是在 PATH 里如果是一键安装脚本它通常会提示你添加路径把那个路径拷贝到环境变量里。懒得改 PATH 的话直接用绝对路径运行比如C:\Users\你的用户名\go\bin\opencode.exe或者用npx opencode这种基于 npm 的临时命令。改完 PATH 重新打开终端执行opencode --version验证一下。5.2 “unexpected server error”排查流程有些同学在 C 盘的 Windows 终端里运行 opencode会遇到error: unexpected server error. Check server logs这个报错通常不是 opencode 本身崩溃而是它背后的模型服务端返回了异常。我遇到过的可能原因有API Key 失效、模型名称填错、免费模型服务限流、本地 Ollama 服务没启动。排查顺序我建议按下面这张表来现象排查动作一键脚本安装后所有模型都报错先检查网络是否能访问模型 endpoint再检查 API Key 环境变量是否已加载某个模型报错其他模型正常大概率是模型名或 endpoint 配置错了在配置里核对一下免费模型之前能用突然报错先去该服务商的控制台看配额和状态免费源下线不是新鲜事直接切换备胎Ollama 本地模型报错执行ollama list确认模型存在再用 curl 访问localhost:11434确认服务活着opencode 提供了 debug 模式遇到问题时可以用类似opencode --debug的方式启动把日志输出到终端能更快定位。在社区提问时带上 debug 日志和配置文件记得打码 key会让别人更容易帮你。5.3 配合 CC Switch 管理多套配置“opencode go 需要配合 cc switch 等工具”这个说法我在热词里看到了实际上的逻辑是很多人在同一台机器上同时用 Claude Code、opencode 和其他 agent每套工具都有自己的 API 配置来回切换很烦。CC Switch 这类配置切换器就是干这个的它能把不同场景的 API Key 配置打包一键切换。opencode 本身也支持通过环境变量指定配置所以你可以用脚本或者 CC Switch 类的工具来管理。我的做法是保留一个基础的~/.config/opencode/config.json里面只放公共配置把不同模型的 Key 通过环境变量注入。比如OPENAI_API_KEY、ANTHROPIC_API_KEY在.zshrc里按需加载或者放到项目的.env文件里opencode 会自动读取。这样切换团队项目时只要切换一组环境变量即可不需要改配置文件。5.4 安装 superpowers 技能包时容易踩的坑superpowers 是一套社区里很火的 agent 技能包安装后能让 opencode 拥有项目规划、调试、代码审查等更强的方法论。安装方法并不复杂把仓库里的 skills 目录软链到 opencode 的项目 skills 目录就行。但我第一次装完发现superpowers 里的某些技能“存在但 agent 从来不用”。排查下来发现是 frontmatter 格式不兼容。具体来说superpowers 原本主要面向 Claude Code它某些技能文件头里写的字段 opencode 不认导致 opencode 在加载技能描述时忽略了这个技能。解决办法也很简单打开SKILL.md看看 frontmatter 里的name和description是否符合 opencode 的规范。如果不确定把description写得直白一点比如“Use this skill when the user asks to plan a project or create an implementation plan.”。改完后重开会话让 opencode 重新扫描 skills 目录。另外superpowers 更新很频繁每次拉取新版本都可能引入新的 frontmatter 写法。我建议不要直接软链整个仓库而是把你要用的几个技能拷贝出来手工调整后再放进自己的 skills 目录。这样以后更新不会把你的定制改动冲掉。6. 写在最后我的日常操作流最后分享一个我现在的固定工作流也算给大家一个参考。接到一个新需求时我会先把 git 分支切好然后运行 opencode让它在项目里读一遍关键文档给出一个实施计划。确认计划没问题后我让它把计划拆成 TODO 列表我再手动把 TODO 里的每一项当作独立任务发给它一个一个完成。每完成一项我都要看一眼 diff再用它的测试脚本跑一遍验证。最后提交代码的时候我会把 opencode 的会话摘要当作 commit message 的底稿但一定会自己改一遍。用了一段时间后我最大的体会是opencode 不是来替代写代码的人的它是来把机械劳动、搜索劳动、测试劳动包掉的。它最大的价值不是“自动写出 100 行代码”而是当你面对一个陌生项目、一个诡异 bug、一堆堆旧代码时它愿意不厌其烦地翻文件、跑测试、试错而你只需要在旁边判断方向验收结果。如果你也想试试建议从一个小项目开始让它先做一次代码审查或者写一组测试用例感受一下它的工作方式。等熟悉了它的脾气再慢慢把更核心的编码任务交给它。就这样祝你也玩得顺手。 
长河君 · 2026/9/8 19:19:33 · 阅读 1.2k opencode 完全指南：终端 AI 编程智能体的安装、配置与实战
最近这两个月我几乎每天都在用 opencode 写代码。本来只是看它上了 GitHub 热榜想装来试试水结果它直接成了我终端里最常用的工具之一。如果你还没用过 opencode简单说它是一个开源的、跑在终端里的 AI 编程智能体你可以像跟同事对话一样告诉它“这个页面有个 bug帮我查一下”它会自己读项目、写代码、跑测试甚至调 Playwright 去复现前端问题。它跟 Claude Code、Codex 是一类东西但它是开源的而且模型不受绑定官方模型、本地模型、免费模型都能接。这篇文章我打算把 opencode 的安装、配置、核心玩法、实战案例和常见坑一次性讲清楚。适合谁看如果你在用或者正在纠结 Claude Code、Codex、pi 这类 agent或者你一直想找一个不绑死单一模型的终端编程助手那这篇应该能帮你省不少时间。1. opencode 到底是什么它解决了我什么痛点1.1 用一句话定位 opencodeopencode 是一个终端里的 AI 编程智能体它提供了一套交互式的 TUI文本界面你输入一句任务它会把任务拆成步骤然后调用工具去完成。这里的“工具”包括读写文件、执行 shell 命令、运行测试、搜索代码等等和你在 IDE 里用 Copilot 那种“补全下一行代码”的辅助完全不是一个量级。它更像一个坐在你旁边、会自己动手翻仓库的同事。我最初吸引我的是它的定位不离开终端。我本身是重度终端用户日常开发已经习惯了 Vim 和 tmux打开一个 IDE 反而觉得重。opencode 装好之后直接在项目目录里敲一下opencode就进了一个全屏终端工作区左边是对话区右边是文件 diff下方可以执行命令。它还会主动调用外部工具比如读一个文件前先看文件大小、用 ripgrep 搜索关键字、跑npm test来验证自己的修改这些都是真实可复现的操作不是模型在脑内幻想。另外它还接入了模型切换能力。你可以用同一个会话切到不同模型而不是每次换模型都要重新搭环境。这种做法对想对比模型效果的人来说特别友好。我最近在几个项目里实测下来opencode 2.0 的 TUI 明显比早期版本顺滑命令面板、diff 预览、上下文管理都做得更成熟了这也是我决定把它写成一篇完整教程的原因。1.2 对比opencode、Claude Code、Codex怎么选先说结论没有绝对最好的 agent只有更匹配你工作流的工具。我用过 Claude Code 和 OpenAI 的 Codex也看过 pi 的演示下面这张表是我个人的主观体验供你参考。工具是否开源模型绑定核心亮点适合谁opencode是不绑定可接多种模型TUI 体验好支持 skills、memory配置灵活喜欢终端操作、想自主控制模型的人Claude Code否有开源部分主要绑定 Anthropic 模型和 Claude 模型能力结合深复杂推理强Claude 生态重度用户Codex否主要绑定 OpenAI 模型与 OpenAI API 结合好执行代码能力稳OpenAI 生态重度用户pi不确定/各有说法多为某一家模型交互简洁喜欢极简风格的人我为什么最后长期用 opencode因为它是这几个里面唯一一个让我能自由接本地模型的。我可以在内网环境、没有外网 API 的情况下用 Ollama 跑一个 7B 的代码模型照样实现自动化改代码、写测试。这种自由度是商业化产品很难给的。当然如果你只依赖 Claude 或 GPT 的顶级推理能力且预算充足那 Claude Code 和 Codex 也没问题。1.3 谁适合用 opencode如果你满足下面任意一条我建议你试试日常开发在终端里完成习惯 Vim/Neovim 或 JetBrains 系 IDE 的内置终端。有多个模型账号比如自己买了 OpenAI API公司又有 Anthropic 的 key不想被工具锁死。希望 AI 能真正帮你跑命令、读日志、改文件而不是只能生成一段代码让你自己粘贴。对数据敏感希望代码分析尽量在本地完成或者至少能把模型切成内网可访问的私有部署。如果你是刚接触命令行的新手也不是不能用但最好先会基本的文件操作和 git 流程。因为 opencode 再怎么智能它改完代码后你还是得看懂 diff、处理冲突。它更像一个能力很强的实习生你既要会派活也要会验收。2. 安装与基础配置从零开始跑起来2.1 三种安装方式总有一种适合你opencode 的安装路径还挺多。我这里列三种我实际用过的按推荐程度排序。第一种用官方一键脚本安装。macOS 和 Linux 用户直接在终端执行官方文档里的安装命令它会自动下载最新二进制写到你的用户目录下然后告诉你把某个路径加入 PATH。安装完成后重新打开一个终端运行opencode --version能输出版本号就说明成功。这个方法最简单适合大多数用户。第二种用 Go 自带的命令安装。如果你本机装了 Go 环境可以直接执行go install github.com/sst/opencodelatestopencode 本身是用 Go 写的所以go install相当自然装的就是当前 release 版本。装完之后二进制一般会出现在$GOPATH/bin或$HOME/go/bin下记得确保这个目录在 PATH 里。热词里很多人搜“opencode go”大概率就是在找这种安装方式。第三种用包管理器安装。比如 macOS 用户可以用brew install opencode这种命令Windows 用户则可以用scoop或winget。不过包管理器里的版本可能比官方 Release 慢一两个小版本如果你不追新倒也没差。另外官方还有桌面版opencode desktop不想在终端里折腾的人可以直接装桌面客户端。我试下来它的底层引擎和 TUI 是一样的只是包了一层图形界面适合把 opencode 当“独立应用”用的人。但我个人还是推荐从 TUI 入门因为桌面版有些高级配置项还是得看命令行日志。2.2 首次启动与模型接入在项目目录下直接运行opencode会进入首次引导界面。它会让你选一个默认模型并要求填 API Key。如果暂时不想填也可以选“跳过”进入之后再通过命令配置。opencode 的配置文件默认放在~/.config/opencode/文件名通常是opencode.json或config.json具体以你本机版本为准。它的核心逻辑就是配置多个 provider然后在会话里随时切换。下面是我自己的一个简化示例{ provider: { anthropic: { apiKey: env:ANTHROPIC_API_KEY }, openai: { apiKey: env:OPENAI_API_KEY } } }这里我用了env:前缀意思是 API Key 从环境变量里读而不是把明文写在配置文件里。这样做的好处是不小心把配置分享出去时不会泄露密钥。如果你在团队里用更应该在.gitignore里把配置文件排除掉或者用密钥管理工具注入环境变量。启动之后进入 TUI 主界面用/能调出命令面板。我常用的命令有/new开一个新会话/context手动把某些文件加进上下文/models切换模型/tokens查看当前上下文占用比例。你版本里如果没有这些命令在命令面板里搜一下关键词就行。2.3 免费模型怎么接两条安全可行的路线热词里“opencode 免费模型”搜索量很高说明大家都不想一开始就花冤枉钱。我实测下来有两条免费路线是稳定可用的而且不涉及任何灰色操作。第一条本地模型。以前我觉得本地模型只能玩玩后来发现对很多日常任务完全够用。先装 Ollama然后拉一个代码模型比如ollama pull qwen2.5-coder:7b然后在 opencode 配置里加一个 provider把 endpoint 指向http://localhost:11434模型名填qwen2.5-coder:7b。这样 opencode 就完全在本地跑不需要任何外部 API也不用担心限流。它的优点是免费、离线、数据不外传缺点是 7B 这种规模的模型处理复杂重构时会有点吃力更适合用来解释代码、生成测试、做全局搜索。第二条云端免费额度。不少平台注册后会送一定额度的 API 调用你把它的 endpoint 和 key 填进 provider 就行。不过这类免费源稳定性参差我见过有人用某个免费模型源用了一个月突然返回 503所有自动化脚本跟着挂掉。所以我的建议是免费模型可以做头脑风暴、写单元测试、解释报错这类容错率高的任务关键生产代码还是用付费的强模型比较稳。热词里有人问“hy3-free 下线了吗”这种事其实挺常见免费服务说下线就下线与其纠结某个源不如多配置几个备胎。3. 核心玩法拆解模型切换、skills、memory3.1 /models 切换模型的正确姿势opencode 最吸引人的一点就是它可以在同一个会话里切换模型。你正在用 Claude 写代码突然觉得某个问题 GPT 可能更擅长直接打开/models切换就行。但这里面有一个很容易踩的坑切换模型之后上下文不会完全无缝衔接。不同模型对上下文的组织方式不一样特别是系统提示和工具调用历史的格式。如果在一个长会话里频繁切换后一个模型可能读不懂前一个模型留下的“思维链”回答质量会明显下降。我的经验是尽量在任务开始时就把模型选好不要在任务中间反复横跳。如果确实需要切换最好先把当前进度和关键结论复制出来作为新的任务描述重新开一个会话。另外我还喜欢用“轻量模型做探索重量模型做实现”的组合打法。比如让一个便宜、快速的本地模型先读一遍项目结构找出相关文件生成一个大致的修改方案然后再切到 GPT-4 或 Claude 这种强模型让它基于方案写出具体代码。这样能省一点 API 费用效率也更高。3.2 skills 机制让 opencode 学会你的专属技能skills 是 opencode 一个非常有用的扩展机制。你可以把它理解成“预置的技能包”每个 skill 由一个说明文档和若干示例脚本组成告诉 agent 在遇到特定任务时应该怎么做。比如你可以写一个code-review.md技能里面写清楚你们团队的代码规范、需要检查哪些点再附一个脚本让它自动列出本次改动的文件。之后只要说“帮我 code review”opencode 就会自动加载这个技能按你的规则执行。这个机制和 Anthropic 的 Agent Skills 格式是兼容的所以网上很多现成的技能包可以直接用。热词里提到的“oh-my-claudecode”本身是一套给 Claude Code 用的增强配置里面有大量 skills 和 agent 规则我可以直接把它的 skills 目录复制或软链到 opencode 的项目目录.opencode/skills/下大部分都能正常识别。我自己写 skill 的时候一般会在项目根目录建一个.opencode/skills/技能名/SKILL.md里面用 Markdown 写清楚技能名称、描述、适用场景和执行步骤。opencode 在每次任务规划时会读取这些描述判断是否需要调用这个技能。写完之后在会话里输入opencode会自动重新加载不需要重启。如果你写了技能但 agent 一直不调用先检查描述是否足够具体最好带上关键词比如“当用户提到代码审查或 code review 时必须使用这个技能”。3.3 memory 持久化跨会话记住项目背景默认情况下opencode 每次新会话都是一张白纸但很多项目背景信息是反复需要的比如“这个项目是微服务架构API 统一走网关前端用 Vue 3测试用 Vitest”。如果每次都要重新交代一遍太浪费上下文。opencode 支持 memory 机制可以把这类背景信息持久化下来。我的用法是在项目根目录放一个opencode.md或者在全局配置里加一段 memory 内容把项目常用的命令、技术栈、目录结构和注意事项写清楚。agent 每次启动新会话时会把这部分内容作为潜台词自动加载。这就像给助手写了一份入职文档它每天上班前先读一遍自然不需要你反复唠叨。需要注意memory 不是越长越好。写太多无关信息反而会挤占上下文窗口影响真正任务的体现。我一般控制在 20 行以内只写“必要但易忘”的事情。除了项目级 memoryopencode 也能记住一些用户偏好比如“永远不要主动删除文件”“改代码前先跑一遍测试”“提交信息用英文”等。把这类偏好写进全局配置它能长期遵守。4. 实战拿 opencode 接手一个前端项目并修 bug4.1 新手也能快速接手一个老项目很多同学不敢让 AI 直接接触老项目觉得它肯定搞不定。我的实测结论是只要项目不是特别冷门opencode 的表现比大部分人想象中好。我第一次用它接手一个历史遗留前端项目时直接在新会话里输入了这样的指令先读 README.md、package.json 和 src 目录结构告诉我这个项目怎么启动 然后帮我把它跑起来如果启动有问题就根据报错自己排查。opencode 会先列出当前目录找到 README 和 package.json读取里面的 scripts 命令然后尝试启动开发服务器。它看到端口被占用时会去查是谁占用的需不需要换端口执行npm install失败时会看报错尝试修复依赖。这个过程是透明的每一步它都会在对话里给出解释你也可以随时打断它。我的建议是让 AI 接手老项目之前先把 git 状态弄干净至少提交一次当前改动。这样即使 AI 改坏了你也可以随时git checkout回滚。另外在任务描述里明确“先不要改代码只做调查”等你把项目结构搞清楚了再进入修改阶段。4.2 用 Playwright 复现前端 bug有一次我的任务是修复一个登录表单 bug输入用户名和密码后点击登录页面没有任何提示控制台也没有报错。这种问题自己排查要开 DevTools、加断点、反复试很费时间。我给 opencode 的自然语言指令是这个登录表单用户名输入 admin密码随意输入点登录按钮后没有任何提示。 帮我用 Playwright 写一个复现脚本运行它并抓取浏览器控制台的所有报错信息。opencode 会先检查项目里有没有安装 Playwright没有的话就安装然后写一个reproduce.spec.ts脚本启动浏览器、访问本地开发服务器、填写表单、点击按钮、监听 console 和 pageerror 事件。脚本跑完后它会把控制台输出拿回来分析。那次的问题最终定位到某段旧代码里事件绑定用的元素选择器在新版页面里不存在导致点击事件被静默吞掉。这里有一个技巧让 AI 把复现脚本保存下来不要跑完就删。后续修改代码后可以反复跑同一个脚本做回归验证。opencode 不会主动清理文件但如果你不说明它可能生成到临时目录。最好在任务里带上“脚本保存到tests/reproduce/目录”这种明确要求。4.3 定位根因与自动修 bug拿到控制台报错或者 Playwright 的失败结果之后可以让 opencode 去源码里搜索相关代码根据报错信息找到登录按钮的事件绑定代码分析为什么点击后没有触发请求。 先不要改给我看定位过程和候选修复方案。它会用 ripgrep 搜索事件绑定的关键词比如login、handleSubmit、addEventListener再结合上下文判断问题原因。最后生成一个 diff 供你确认。我习惯让它用git diff展示改动而不是直接覆盖文件。虽然这样多了一步但能避免它在一堆相关重构里夹带无关修改。等确认 diff 没问题再让它继续跑测试或 Playwright 脚本做验证。如果你接手的项目是 Maven 工程也别忘了让 opencode 读取pom.xml。AI 对依赖的理解直接影响它改代码的准确性我通常会在任务描述里补充一句“先读一下 pom.xml确认项目用的框架版本再分析代码”。4.4 IDE 插件联动VSCode / JetBrains 里的推荐用法很多人问“opencode 有没有 VSCode 插件”“IDEA 里能不能用”。我的看法是opencode 本身是 TUI 工具最稳妥的用法就是在 IDE 的内置终端里直接跑它。VSCode 的Ctrl \ 打开终端输入opencode左边是编辑器右边就能和它对话体验已经很接近一个 IDE 插件了。JetBrains 系也一样AltF12 打开终端直接跑命令。当然官方和社区也有对应的 VSCode / IDEA 插件它们做的事情其实就是在 IDE 侧边栏嵌入一个终端面板方便你点击复制、查看 diff。如果你已经装好了 opencode这类插件不是必须的。真要说有什么好处可能是它能把 opencode 的会话和当前打开的文件关联起来方便快速把文件路径加入上下文。但这个功能我自己用得不多因为直接在会话里拖拽路径也很快。我个人的习惯是在 VSCode 里配置一个快捷键按下之后自动打开终端并执行opencode省去每次敲命令的工夫。JetBrains 也可以用类似方式配置 External Tool。这样既保留 IDE 的代码跳转、重构能力又能享受 opencode 的 agent 能力。5. 高频问题排查报错都在这里找答案5.1 Windows 下“无法将 opencode 项识别为 cmdlet”怎么办这个报错在热词里出现了很多次典型提示是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。原因基本只有一个opencode 的安装目录没有被写进系统的 PATH 环境变量。尤其是用go install或 npm 方式安装后二进制文件在某个目录但终端不知道去哪找。解决办法分三步重新打开一次终端因为环境变量在终端启动时读取新安装的 PATH 不会自动生效。确认安装目录。如果是go install执行go env GOPATH看看bin目录是不是在 PATH 里如果是一键安装脚本它通常会提示你添加路径把那个路径拷贝到环境变量里。懒得改 PATH 的话直接用绝对路径运行比如C:\Users\你的用户名\go\bin\opencode.exe或者用npx opencode这种基于 npm 的临时命令。改完 PATH 重新打开终端执行opencode --version验证一下。5.2 “unexpected server error”排查流程有些同学在 C 盘的 Windows 终端里运行 opencode会遇到error: unexpected server error. Check server logs这个报错通常不是 opencode 本身崩溃而是它背后的模型服务端返回了异常。我遇到过的可能原因有API Key 失效、模型名称填错、免费模型服务限流、本地 Ollama 服务没启动。排查顺序我建议按下面这张表来现象排查动作一键脚本安装后所有模型都报错先检查网络是否能访问模型 endpoint再检查 API Key 环境变量是否已加载某个模型报错其他模型正常大概率是模型名或 endpoint 配置错了在配置里核对一下免费模型之前能用突然报错先去该服务商的控制台看配额和状态免费源下线不是新鲜事直接切换备胎Ollama 本地模型报错执行ollama list确认模型存在再用 curl 访问localhost:11434确认服务活着opencode 提供了 debug 模式遇到问题时可以用类似opencode --debug的方式启动把日志输出到终端能更快定位。在社区提问时带上 debug 日志和配置文件记得打码 key会让别人更容易帮你。5.3 配合 CC Switch 管理多套配置“opencode go 需要配合 cc switch 等工具”这个说法我在热词里看到了实际上的逻辑是很多人在同一台机器上同时用 Claude Code、opencode 和其他 agent每套工具都有自己的 API 配置来回切换很烦。CC Switch 这类配置切换器就是干这个的它能把不同场景的 API Key 配置打包一键切换。opencode 本身也支持通过环境变量指定配置所以你可以用脚本或者 CC Switch 类的工具来管理。我的做法是保留一个基础的~/.config/opencode/config.json里面只放公共配置把不同模型的 Key 通过环境变量注入。比如OPENAI_API_KEY、ANTHROPIC_API_KEY在.zshrc里按需加载或者放到项目的.env文件里opencode 会自动读取。这样切换团队项目时只要切换一组环境变量即可不需要改配置文件。5.4 安装 superpowers 技能包时容易踩的坑superpowers 是一套社区里很火的 agent 技能包安装后能让 opencode 拥有项目规划、调试、代码审查等更强的方法论。安装方法并不复杂把仓库里的 skills 目录软链到 opencode 的项目 skills 目录就行。但我第一次装完发现superpowers 里的某些技能“存在但 agent 从来不用”。排查下来发现是 frontmatter 格式不兼容。具体来说superpowers 原本主要面向 Claude Code它某些技能文件头里写的字段 opencode 不认导致 opencode 在加载技能描述时忽略了这个技能。解决办法也很简单打开SKILL.md看看 frontmatter 里的name和description是否符合 opencode 的规范。如果不确定把description写得直白一点比如“Use this skill when the user asks to plan a project or create an implementation plan.”。改完后重开会话让 opencode 重新扫描 skills 目录。另外superpowers 更新很频繁每次拉取新版本都可能引入新的 frontmatter 写法。我建议不要直接软链整个仓库而是把你要用的几个技能拷贝出来手工调整后再放进自己的 skills 目录。这样以后更新不会把你的定制改动冲掉。6. 写在最后我的日常操作流最后分享一个我现在的固定工作流也算给大家一个参考。接到一个新需求时我会先把 git 分支切好然后运行 opencode让它在项目里读一遍关键文档给出一个实施计划。确认计划没问题后我让它把计划拆成 TODO 列表我再手动把 TODO 里的每一项当作独立任务发给它一个一个完成。每完成一项我都要看一眼 diff再用它的测试脚本跑一遍验证。最后提交代码的时候我会把 opencode 的会话摘要当作 commit message 的底稿但一定会自己改一遍。用了一段时间后我最大的体会是opencode 不是来替代写代码的人的它是来把机械劳动、搜索劳动、测试劳动包掉的。它最大的价值不是“自动写出 100 行代码”而是当你面对一个陌生项目、一个诡异 bug、一堆堆旧代码时它愿意不厌其烦地翻文件、跑测试、试错而你只需要在旁边判断方向验收结果。如果你也想试试建议从一个小项目开始让它先做一次代码审查或者写一组测试用例感受一下它的工作方式。等熟悉了它的脾气再慢慢把更核心的编码任务交给它。就这样祝你也玩得顺手。