去年底我接手了一个半死不活的前端项目代码堆得像毛线团文档约等于没有我实在不想一行行去啃。群里有人丢给我一句话试试 opencode。当时我以为是某个新的代码编辑器结果它是一个跑在终端里的 AI 编程助手。这一试不要紧我的开发工作流就彻底回不去了后面连续几个项目我都是用它在终端里完成的。如果你最近也在关注 opencode在犹豫要不要从 Claude Code 或者 Codex 换过来或者说刚装上但不知道从哪下手这篇东西应该能帮你省下好几天摸索时间。opencode 是一个开源终端 AI 编程代理最大的特点是模型自由、配置灵活、上手路径短。它不像某些工具把你绑死在特定厂商上而是让你自己选模型、配服务、甚至接入本地模型。这篇文章我按是什么、怎么装、怎么配、怎么用、踩了什么坑的顺序来写里面所有步骤和配置都是我在实际项目中验证过的不是抄文档。1. opencode是什么一个用Go重写你终端工作流的AI编程Agent1.1 一句话定位如果你用过 Claude Code 或者 Codex CLI那 opencode 的理解成本几乎为零。它也是一个跑在终端里的 AI 编程助手你在命令行里启动它它会根据你的指令去读代码、改文件、执行命令、跑测试然后告诉你结果循环往复直到任务完成。但它和那几个工具又不太一样。opencode 是开源的GitHub 上仓库热度一直很高背后的团队是做 SST 那批人所以这个工具从出生起就带着很强的工程效率基因。它用 Go 语言写的发行物就是一个单二进制文件不依赖 Node 运行时也不强制你登录什么账号你在哪台机器上装都是一样的手感。很多朋友第一次打开 opencode 的界面会觉得它像个聊天工具实际上它远不止聊天。它的 TUI终端用户界面里有一个主对话窗口一个会话列表侧栏还有一个很实用的功能同一个问题你可以同时丢给多个模型让它们各自给出方案你再对比选优。这个功能在解决疑难 Bug 时特别好用相当于同时请了两位不同风格的工程师会诊。1.2 和Claude Code、Codex CLI、pi的对比像 opencode 这种终端 Agent 现在不少很多人都在纠结选哪个我用了几个月之后的感觉是这样的工具开源模型绑定上手难度界面体验适合场景opencode是自由配置中等TUI 精美功能全想自己掌控模型和配置的开发者Claude Code否早期/逐步开放主要面向 Claude低简洁稳定Anthropic 生态用户Codex CLI否闭源主要面向 OpenAI 系低简洁ChatGPT 重度用户pi是自由配置较高高度可定制喜欢折腾、追求极致定制的玩家注意上表的结论有个大前提工具迭代非常快半年后再看可能又是另一番局面。我的建议是不要听别人说哪个最好而是看哪个最贴合你的工作习惯。opencode 的强项在于中间路线——它不像 Claude Code 那样开箱即用零配置但也不像 pi 那样需要你搭积木一样拼出完整环境。你只需要配好模型服务它能给到接近商业工具的完整体验同时保留全部的灵活度。我也见过一些人问opencode codex pi 哪个 agent 好用这类问题其实很难有标准答案。我个人的经验是如果你是个人开发者、自媒体、独立作品集作者opencode 的性价比是最高的因为你只需要为模型 API 付费工具本身免费开源也不存在账号层面的封禁风险。而如果你所在团队已经全员 Anthropic 生态、统一了工作流那 Claude Code 的团队协作能力可能更省心。工具这东西适合自己的就是最好的。2. 从零安装到跑起第一个会话不同平台的路径和Windows专属坑2.1 三种安装方式按场景选opencode 的安装方式挺多我只讲实际用下来最靠谱的三种。macOS 和 Linux 上最省事的是用官方安装脚本curl -fsSL https://opencode.ai/install | bash我看到很多教程直接让你这么装但它有个隐患脚本安装的位置不一定在你的 PATH 里。装完提示命令找不到的话可以用 Homebrew 再装一遍brew install sst/tap/opencode如果你机器上已经有 Go 环境也可以从源码装顺便还能锁定特定版本go install github.com/sst/opencodelatestWindows 上的路子有点不一样。官方推荐用 Scoop装完之后会自动处理 PATHscoop install opencode如果你不想装 Scoop去 GitHub Releases 页面下载对应平台的压缩包解压后把 opencode.exe 放到一个固定目录再手动加进系统 PATH 也可以。我个人的建议是优先 Scoop因为后续升级只需要scoop update opencode一条命令比手动下载方便太多。2.2 无法将opencode项识别为cmdlet到底是怎么回事Windows 用户遇到最多的就是下面这条报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这条报错本身是无辜的它只是告诉你 PowerShell 在当前所有 PATH 目录里找不到 opencode 这个可执行文件。但为什么找不到原因通常是这几个第一你用浏览器下载了 zip解压之后忘了把 exe 所在目录加进 PATH。这种最常见解决办法是把解压出来的目录复制到C:\tools\这种固定位置然后去系统环境变量里把路径追加进去。第二你照着 macOS 的教程执行了curl ... | bash。PowerShell 对管道和 bash 脚本的处理方式跟 Linux 完全不同这段脚本在 PowerShell 里根本不会按预期执行看起来像执行了实际上什么都没装好。第三你装的时候终端是开着的装完后 PATH 没有刷新。关闭当前终端窗口重新开一个或者执行$env:Path [System.Environment]::GetEnvironmentVariable(Path, Machine) ; [System.Environment]::GetEnvironmentVariable(Path, User)强制刷新。排查思路其实很简单先在终端里输入Get-Command opencode如果能返回路径说明命令可用只是终端缓存问题如果提示找不到说明 PATH 没配好。也可以在文件管理器里找到 opencode.exe直接双击运行如果弹出一个终端界面说明程序本身没问题问题全在 PATH。2.3 第一个会话认证、选模型、界面认识装好之后在终端输入opencode就能进入 TUI。第一次启动它会引导你选择模型服务商这一步在后面的章节我会详细讲。如果你想跳过引导直接配也可以用命令行的非交互模式快速体验。比如opencode run 帮我看看当前目录下有哪些文件这个命令会直接在终端里执行一次对话并返回结果适合脚本化和 CI 场景。日常开发我建议还是进入 TUI因为它的体验比纯命令行好太多。进入 TUI 后你看到的界面大致分三个区域左侧是会话列表中间是对话主窗口底部是输入框。对话窗口里可以随时切换模型也可以同时问多个模型等它们都回答完再对比。快捷键方面你不需要背按?就能看到当前所有快捷键。第一次启动之后我建议做一件事随便问它一个关于当前项目的问题比如这个项目的技术栈是什么确认整个链路是通的。哪怕答案不完美至少证明安装、认证、模型调用都没问题后面再根据实际需要去调整配置。3. Provider接入与模型切换API Key、ccswitch和免费模型的理性用法3.1 配置文件里到底能配什么opencode 的配置目录在~/.config/opencode/Windows 上则是%USERPROFILE%\.config\opencode\。里面最重要的文件是opencode.json它控制模型服务商、模型列表、MCP 服务器、全局规则等几乎所有东西。文件开头建议加上$schema字段写配置文件时编辑器就能自动补全和提示{ $schema: https://opencode.ai/config.json, provider: { custom: { npm: ai-sdk/custom, name: My Custom Provider, options: { baseURL: https://api.example.com/v1, apiKey: {env:CUSTOM_API_KEY} }, models: { my-model: { name: My Model } } } } }不过对大多数用户来说根本不需要手写这种底层配置。opencode 内置了对主流服务商的支持你只要用opencode auth login登录认证就行。这条命令会带出一个交互式菜单列出当前支持的服务商选一个按提示粘贴 API Key 或者走 OAuth 流程认证信息会被保存在系统钥匙串里。如果你更喜欢环境变量opencode 也支持常见变量名比如ANTHROPIC_API_KEY、OPENAI_API_KEY、OPENROUTER_API_KEY、GEMINI_API_KEY等等。设置好一个就能在对应服务商下直接选模型。我推荐的做法是API Key 这种敏感信息不要写进opencode.json优先用系统钥匙串或者环境变量。既安全也方便后续引入 ccswitch 这类工具做集中管理。3.2 ccswitch让多模型切换变成一键操作在社区里搜索 opencode大概率会看到opencode 需要配合 ccswitch 使用的说法。ccswitch 是一个命令行小工具作用是集中管理多个 AI 服务的 API 配置然后通过环境变量或者配置文件的方式把当前选中的那组配置暴露给下游工具。它解决的问题很实在你同时用着 opencode、Codex CLI、Claude Code 等多个工具每个工具都要配一遍服务商信息切换模型服务商的时候一个一个去改实在太痛苦。我用它的方式是这样的在 ccswitch 里维护一个配置列表比如工作用 Anthropic 官方、测试用 OpenRouter 聚合、本地跑 Ollama每次切换只需要一行命令ccswitch use work-anthropic opencode这样 opencode 启动时读取到的就是当前激活的配置API 地址和 Key 都不用我手动改。配置转移方面如果换了一台新电脑只把 ccswitch 的配置目录拷过去所有工具就都恢复原样这对经常在多台机器之间换环境的人来说非常省事。需要说明的是opencode 本身不依赖 ccswitch但如果你同时使用多个 AI 编程工具你会感谢这个组合的。3.3 免费模型额度、开源模型和下线焦虑网上很多人在搜opencode 免费模型我得先泼一盆冷水免费的东西在 AI 编程这件事上从来不是免费的午餐。目前真正靠谱的免费途径就三类。第一类是云厂商的免费额度比如 Google AI Studio 给 Gemini 系列模型的免费层OpenRouter 上也有一批限额免费模型额度用完就停。这类服务稳定适合入门体验。第二类是本地开源模型配合 Ollama 跑 Qwen、Llama、DeepSeek 这些响应速度取决于你的显卡。本地模型胜在私密和无限量但代码生成质量跟顶级商业模型还有差距适合对隐私要求高的场景。第三类是某些社区里流传的免费中转源这类服务我不推荐绑定核心开发流程。原因很简单稳定性没保证随时可能 401。社区里很多人问hy3-free 是不是下线了其实就是这类源的真实写照——今天还能用明天就没了不是故事是很多人踩过的坑。我的建议是日常开发至少准备一个付费的、可靠的商业模型 API免费额度作为补充或者备胎。省下来的那点钱远不够弥补关键时刻掉链子浪费的时间。3.4 关于MCP配置以及那个被问烂的mvn搜索记录里经常能看到opencode mvn 配置如果你也是照着教程去搜的大概率是把mcp打成了mvn。MCP 全称 Model Context Protocol是让 Agent 接入外部工具的标准协议这才是你真正要找的东西。opencode 支持 MCP 服务器配置在opencode.json里加一个mcp字段就能启用。比如接入 Playwright 让 Agent 能用真实浏览器去验证前端效果{ mcp: { playwright: { type: local, command: [npx, playwright/mcplatest], enabled: true } } }配上之后Agent 就能在需要的时候自动启动浏览器、打开页面、截图、读取控制台报错这对前端 Bug 的定位效率提升是肉眼可见的。后面我会专门写一节讲怎么用 Playwright 调前端问题这里先记住一点MCP 是 opencode 扩展能力的关键入口学会配它你的 Agent 才不算浪费。4. 规则、记忆和Skills把opencode调教成你的专属结对程序员4.1 AGENTS.md用项目规则约束Agent行为如果你之前用过 Claude Code一定会熟悉CLAUDE.md在 opencode 里这个角色由AGENTS.md承担。它和 README 不同README 是给人看的AGENTS.md 是给 AI 看的。文件里可以写明项目结构、代码风格、常用命令、禁止事项等。只要把AGENTS.md放在项目根目录opencode 每次启动都会自动读取它并在后续所有对话中遵循里面的约束。比如我接手一个 Vue3 项目时会这样写# Project Rules - 这是一个 Vue 3 TypeScript Vite 项目 - 组件全部使用 script setup 语法 - 样式使用 Tailwind CSS禁止写全局 CSS - 提交信息遵循 Conventional Commits 规范 - 修改代码前必须先读懂相关目录结构不要盲目新增文件写这文件花了我十分钟但效果立竿见影Agent 生成的代码风格明显更贴近项目现有代码不会再出现一会儿 Options API 一会儿 Composition API 这种混乱情况。我强烈建议每个项目都维护一份 AGENTS.md这可能是投入产出比最高的一项配置。4.2 Memory跨会话记忆的正确打开方式opencode 有一个记忆功能可以把跨会话的信息存下来下次对话继续使用。比如你告诉过它这个项目的数据请求统一走src/api目录下的模块、生产环境构建命令是pnpm build:prod这类信息会被沉淀到记忆里。记忆功能好是好但也会带来一个副作用记忆不干净的话Agent 会被过时信息误导。我建议定期清理记忆。我自己的习惯是每完成一个里程碑就把旧的、不再适用的记忆删除只保留当前模块相关的约束。记忆不是垃圾桶别什么都往里丢。你存进去的每一句话都在影响 Agent 后续所有判断。4.3 Skills自己写一个代码审查技能Skills 是 opencode 里最像插件的东西它本质上是一个带说明文档的行为模板。比如我想让 Agent 在每次改动后做一次代码审查就创建~/.config/opencode/skills/code-review/SKILL.md内容大致是--- name: code-review description: 对当前改动做一次代码审查检查逻辑错误、安全隐患和代码风格问题。 --- 当你执行 code-review 时请按以下步骤操作 1. 使用 git diff 查看未提交的改动。 2. 逐个文件检查改动逻辑重点关注边界条件和异常处理。 3. 检查是否硬编码了敏感信息。 4. 给出修改建议标注严重级别。然后在对话里输入执行 code review它就会按这套流程走。你可以按自己的项目需求写大量类似的 skill数据库迁移、依赖升级、接口对接、测试用例生成都是很好的场景。Skill 的好处是把你希望 Agent 怎么做沉淀成文件而不是每次都重新口头叮嘱一遍换项目、换人、换机器都能复用。4.4 安装Superpowers这类技能包除了自己写 skill社区里也有现成的技能包可以装。很多人问opencode 安装 superpowers怎么弄其实思路和 Claude Code 时代类似superpowers 是一套技能集合里面包含了很多高质量 prompt 模板覆盖代码审查、测试生成、性能调试、重构等常见任务。opencode 支持 skills 机制后把技能包里的各个目录放进~/.config/opencode/skills/下重启 opencode 就能加载。你可以用/skills命令查看当前已加载的技能列表。前面提到的 oh-my-claudecode本质上也是类似思路的配置集合很多人之前用它来管理 Claude Code 的配置现在也会沿用同样的习惯给 opencode 配一套。这种配置即代码的方式挺符合开发者直觉一切都能放进仓库、能版本管理、能分享给队友。5. 实战工作流接手老项目、用Playwright调前端Bug、IDE侧车协作5.1 接手老项目先让Agent读再看前面我提到那个毛线团项目opencode 帮我做的就是先读后写。接手一个陌生项目时我会先让 Agent 做一次全库扫描式提问比如读完项目根目录的 README 和 AGENTS.md然后告诉我这个项目用什么技术栈、有哪些核心模块、入口文件在哪、有哪些已知的坑。这一步会消耗一些 token但非常值得。Agent 读完以后你对项目的整体认知就有了一个基本盘后面真正要改代码的时候能给 Agent 更精确的上下文指引。很多人在 Agent 上翻车不是工具不行而是上来就丢一个任务帮我改这个 bug但 Agent 连项目在哪、改哪个文件都不知道。让 Agent 先读代码就像医生先看病历再开药方这个顺序不能乱。opencode 的会话延续功能也值得提一下一次会话中断后下次可以用opencode --continue接着上次的上下文继续聊不会因为终端重启就前功尽弃。我在处理长任务时基本都会用到这个功能。5.2 用Playwright复现前端Bug前端最耗时间的环节不是改代码而是复现 Bug。传统方式是先打开页面、手动操作 N 步、打开控制台看报错然后把报错内容复制给 AI让它猜。现在有了 MCP 接入 Playwright这个流程可以整个交给 opencode。我在第 3.4 节给了配置示例配好之后你只需要描述现象打开首页点击登录按钮输入错误密码点击提交然后检查页面上是否出现错误提示把控制台报错截图发我。Agent 会用 Playwright 自动完成上述操作把页面状态、控制台日志和截图返回给你。这中间最难的部分不是工具而是你描述 Bug 的能力。描述得越具体Agent 定位就越快。我自己的模板是页面路径 前置操作步骤 期望行为 实际行为 环境信息浏览器版本、是否登录态五个要素缺一不可。这个工作流尤其适合那种只在生产环境出现、本地死活复现不了的诡异 Bug。你让 Agent 开着浏览器去生产环境跑一遍流程把真实报错抓回来比你在本地反复翻代码高效太多。5.3 VS Code和JetBrains插件TUI之外的第二入口opencode 虽然主场在终端但官方也提供了 VS Code 插件和 JetBrains 插件让你能在 IDE 里直接开一个 opencode 面板不用频繁切换窗口。我的实际体验是终端版适合专注模式全屏一个窗口没有编辑器分屏干扰IDE 插件适合边写边聊的模式左侧是代码右侧是 AI 对话看到哪段代码不理解直接丢给它。两者各有适用场景不是替代关系。需要提醒的是IDE 插件本质上是 TUI 的壳插件里跑的会话和终端里的会话是同一套底层。如果你在终端里开了一个会话不要同时在 IDE 插件里对同一个项目再开一个避免两个 Agent 同时改文件产生冲突。我遇到过一次两边同时对同一个文件做修改结果互相覆盖比人工合并还麻烦。5.4 桌面版与常规协作场景opencode 的桌面版opencode desktop其实就是把 TUI 包了一层桌面壳对不熟悉命令行的团队成员比较友好。产品经理或者测试同学想自己跑一个 Agent 查看项目情况不需要打开终端双击桌面的图标就能进入同样的界面。我自己的团队里前端开发用终端版设计偶尔要在本地起 dev server 看效果我就让 TA 用桌面版把环境拉起来Agent 帮忙启动、输出日志、定位启动报错省去了很多我帮你看看的低效沟通。这种协作方式的前提是 Agent 配置统一团队内最好共用一个配置文件至少也要在 AGENTS.md 里统一规范否则每个人调教出来的 Agent 行为会差很多。6. 一个月多平台实测那些踩过的坑和沉淀下来的习惯6.1 从一条server error开始排查我遇到过一次比较诡异的报错在 Windows 上跑opencode每次都提示error: unexpected server error. check server logs这条报错只说服务器出问题了但没说哪里有问题很让人头大。我的排查链路是这样的先确认不是模型服务商的问题同样的 key 在别的工具里能用再看日志opencode 日志默认写在数据目录下里面会记录每次请求的细节结果发现是因为我在opencode.json里配置的模型 ID 和实际 API 返回的模型 ID 不一致导致请求校验失败。这类问题的排查思路其实通用先缩小范围确定是工具本身的问题还是上游服务的问题然后看日志不要猜最后对照配置文档检查模型名、服务商名称这些容易出错的字符串。遇到 server error 别慌大多数时候不是服务器挂了而是配置对不上。6.2 版本更新快2.0前后的变化opencode 的版本迭代速度非常快社区里也很多人搜opencode 2.0。版本升级带来的体验提升是明显的但副作用是配置格式和某些命令可能会变。我第一次升级之后就遇到过配置文件格式不兼容的情况旧版的provider字段写法在新版里不再生效导致模型列表变空。这里给两个建议。第一升级前看一眼 CHANGELOG特别是大版本升级确认配置格式是否有破坏性变更。第二配置文件引入$schema字段这样每次打开编辑器都会校验格式错误能尽早暴露。别小看这两个习惯它们能帮你避开 80% 的升级后莫名其妙出问题。6.3 什么时候该用opencode什么时候别用用了一个多月我逐渐摸清了 opencode 的边界。它最适合的任务是有明确目标、涉及多个文件、需要反复试错的工程任务比如实现一个新接口、重构一个模块、升级依赖版本、定位一个跨模块的 Bug。这类任务让 Agent 来回跑比人肉高效得多。它不太适合的任务是需求本身非常模糊、需要大量业务判断的场景。比如把登录流程优化一下这句子信息量太低了Agent 无法判断你要优化交互还是性能给了方案你也未必满意。这种情况下花十分钟把需求想清楚再丢给它效果会好十倍。另外还有一个特别容易忽略的问题并发会话。opencode 可以同时开多个会话但每个会话都在消耗同一个 API 账号的额度。如果你一次性开五六个会话让它们同时干活很快会触发限流表面上看是工具卡了实际上是 API 侧把你限了。我现在的习惯是同时最多两个会话一个主任务一个临时查问题其他都排队。6.4 几个让我效率起飞的小习惯最后分享三个我用下来的实在习惯。第一个是给 Agent 立规矩。第一次进入某个项目时花几分钟写 AGENTS.md把项目约定写清楚。这个行为帮我节省的返工时间是最多的。第二个是善用/models快速切换模型。复杂任务用最强的模型简单问题切到一个便宜的模型成本能低不少。比如代码生成用 Claude 系格式化、解释报错这类简单任务用一个轻量模型就够了。第三个是定期清理会话和记忆。opencode 的 TUI 里会话多了之后会有点卡记忆太杂也会影响回答质量。我每周五收工前会把本周的会话归档、记忆清理一遍下周开工的时候环境是干净的。我在实际使用中发现opencode 这类工具真正考验人的不是会不会用而是会不会把需求讲清楚。它像一个能力很强但需要明确指令的结对程序员你给它越清晰的边界、越具体的上下文它给你的回报就越超出预期。如果你正准备上手我建议从一个小任务开始比如重构一个工具函数、给一个页面写测试跑通之后你自然会知道下一单该让它干什么。