最近一段时间终端里的 AI 编程 Agent 真是卷疯了。Codex CLI 刚火完Claude Code 又拉高了不少人的阈值而我最终长期留在身边的反而是 opencode。这个名字一看就不像正经产品但它恰恰解决了我最烦的几个点不想被某个 IDE 绑架、不想被单一模型锁死、想自定义一套属于自己的 Agent 工作流。这篇东西不是官方文档的复述是我自己在 Mac 和 Windows 两台机器上折腾 opencode 的真实记录包括安装、编辑器集成、Skills、LSP、Playwright 调试前端以及一堆你大概率会撞上的报错。无论你是第一次知道 opencode还是已经在用但想挖更多玩法都可以照着文章里的步骤走一遍。1. 为什么我最后选了 opencode 而不是别家 Agent1.1 opencode 到底是什么它和 Claude Code、Codex CLI 有什么本质区别先说结论opencode 是一个开源的、跑在终端里的 AI 编程助手不绑定某个大模型你可以把它理解成“AI 编程 Agent 的通用外壳”。它提供交互式 TUI文本界面也提供命令行一次性调用。你问它代码问题它能读仓库、改文件、执行命令、跑测试然后自己看结果再修正。很多人第一次听到名字会以为 opencode 是某家大厂出的产品。我在搜索引擎里看到有人专门搜“opencode 是哪家公司的”严格来说它属于开源社区驱动的一个项目不走闭源商业路线。正因为如此它可以支持 OpenAI 系、Anthropic 系、Google 系模型还能接本地模型比如 Ollama这点和 Claude Code 这种“围绕自家模型深度绑定”的工具思路完全不同。如果你用过 Claude Code会发现它的交互非常顺滑但底层模型几乎被锁死在 Claude 上Codex CLI 则明显偏 OpenAI 阵营优先把 GPT/ChatGPT 系列模型的使用体验做到最好。而 opencode 的态度是你带模型来我给你一套完整 Agent 框架。 这就是它和前面两者的本质区别——它是“模型的搬运工 Agent 指挥官”不是某个模型商的“御用终端”。1.2 它到底能帮你解决什么问题我日常用 opencode 最多的场景有这么几个接手不熟悉的老项目让它先扫一遍仓库结构、解释模块依赖、定位某个 bug 可能藏在哪里。批量修改和重构比如给整个项目的日志统一加 trace_id、把某类接口从 callback 改成 Promise这类重复性劳动交给它很靠谱。排查编译错误和运行时异常它拿到控制台堆栈后能自己去看代码上下文给出修复建议甚至直接改。写测试和修前端问题结合 Playwright 工具链它可以在本地起服务、打开页面、截图、抓控制台报错。适合谁来用简单说只要你已经能用命令行写代码、不排斥用终端做开发就适合。前端、后端、算法、iOS 都可以用因为它本身就是拿“语言服务器 工具链”把各种项目类型都串起来。对完全零基础的新手我建议先会基本 Git 操作再上 Agent否则遇到它给你改错文件时会比较慌。2. 安装 opencode 与基础配置2.1 三条安装路径npm、Homebrew、curlopencode 的安装方式很友好但不代表你不会踩坑。最常用的三种方式我实测都能用# 方式一npm 全局安装 npm install -g opencode-ai # 方式二macOS 使用 Homebrew brew install sst/opencode/opencode # 方式三官方安装脚本 curl -fsSL https://opencode.ai/install | bash安装完先跑一下opencode --version能输出版本号就说明成功了。如果你有代理或镜像源npm 安装遇到网络超时的话可以把 registry 切到国内镜像比如npm config set registry https://registry.npmmirror.com但注意这只解决 npm 包的下载问题不代表后面调用模型 API 就能避开网络问题。模型 API 能不能连通取决于你选择的模型服务商。另外热词里有人搜“opencode cli download”其实官方 GitHub Releases 页面也会发布各平台的二进制包Windows 用户可以直接下载 exe 放进 PATH效果和 npm 安装一样。我更推荐 npm 或官方脚本因为后续升级方便。2.2 Windows 下“无法将 opencode 项识别为 cmdlet”是怎么回事这是我在热词榜里看到出现频率最高的问题也是新手最容易卡住的一步。报错长这样opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个问题的本质是opencode 的可执行文件确实安装了但它的目录不在 PowerShell 或 cmd 的 PATH 环境变量里。 Windows 上 npm 全局包的目录默认在%APPDATA%\npm也就是C:\Users\你的用户名\AppData\Roaming\npm如果这个目录没加入 PATH系统就找不到 opencode。解决办法分两步。先在 PowerShell 里执行npm config get prefix你会看到类似C:\Users\xxx\AppData\Roaming\npm的路径。然后打开“编辑系统环境变量”把 Path 变量里追加这一行保存后重新打开终端。懒得点界面的话也可以用 PowerShell 命令[Environment]::SetEnvironmentVariable(Path, $env:Path ;$env:APPDATA\npm, User)改完一定要新开一个终端窗口再执行Get-Command opencode能返回路径就说明识别到了。如果你用的是 nvm-windowsnpm 全局目录可能在C:\Users\xxx\AppData\Roaming\nvm\v版本号\node_modules下面解决思路一样找到路径加 PATH 就行。这里我多说一句很多同学看到报错第一反应是“重新安装”其实没必要。装一遍和装三遍结果完全一样PATH 没配好装十遍也白搭。2.3 登录、模型订阅与免费模型的取舍第一次在终端输入opencode它会启动交互界面然后引导你选择 Provider 并填入 API Key。支持的 Provider 列表很长常见的有 OpenAI、Anthropic、Google、Mistral、Groq以及 Ollama 这类本地模型。热词里频繁出现“opencode go 订阅模型选择”“opencode go 套餐”说明很多人注意到了官方提供的订阅方案。opencode 本身是开源的但官方也提供面向个人开发者的订阅计划好处是可以直接用官方账户登录不需要自己申请各家模型平台的 Key费用统一结算用起来省心。如果你已经有 OpenAI 或 Anthropic 的 Key也可以不订阅直接走自带 Key 的方式。对于想先白嫖试用的同学我的建议是用 Ollama 跑本地小模型。比如ollama pull qwen2.5-coder:14b opencode --model ollama/qwen2.5-coder:14b本地模型的好处是免费、离线、不担心数据出域缺点也很明显——规模小的模型在复杂代码推理上的能力不如云端大模型。我的真实体验是本地 14B 模型适合做“代码解释、单元测试辅助、简单脚本生成”让它接手大型重构或者跨模块 Bug 排查会有点力不从心。配置模型时还有一个高频问题你填写的模型名必须和 Provider 实际提供的 ID 一致。比如 OpenAI 的模型不要只写gpt-4o可能要写全gpt-4o-2024-11-20之类。拿不准的时候在 opencode 里用/models命令刷新模型列表。3. 把 opencode 嵌入日常开发环境3.1 VSCode 插件边写代码边对话我一开始是纯终端流后来发现 VSCode 插件版更符合多数人的习惯。在扩展市场搜 “opencode”安装后按CmdShiftPWindows 是CtrlShiftP输入 “opencode: Open”会在侧边栏打开一个面板。你可以在面板里发起对话也可以选中一段代码右键发送给它。这个插件的核心价值不是“多一个聊天框”而是它直接复用了 VSCode 打开的项目上下文。Agent 能看到你当前打开的文件、选中的代码、编辑器诊断面板里的报错。比如你看到一个红线错误不用复制粘贴选中后直接问“为什么这个变量报错”它能结合 LSP 信息给出答案。我踩过一个小坑如果你同时在终端窗口和 VSCode 插件里各开一个 opencode 会话并且都用同一个项目的同一个模型两个会话可能会同时修改同一个文件造成变更冲突。尽量保持“同一时刻一个项目只有一个活跃会话”特别是执行自动修改任务的时候。3.2 JetBrains IDEA 插件喜欢 JetBrains 系 IDE 的同学也不用慌IDEA 插件市场同样有 opencode。热词榜里有人搜 “opencode jetbrains idea 插件”说明这个需求不少。安装后一般会在底部工具窗口出现一个 opencode 标签页。它的体验和 VSCode 插件类似但针对 Java、Kotlin 项目似乎更顺手一些因为 JetBrains 自带的语言服务器和项目模型比较细腻Agent 拿到的符号信息更准确。我自己的习惯是日常用 VSCode 写前端用 IDEA 写后端两边都装 opencode。它们共享同一套 CLI 配置不需要分别设置模型。唯一要注意的是JetBrains 插件的版本更新可能滞后于 CLI如果插件提示“opencode binary not found”检查一下系统环境变量 PATH确认命令行里能跑opencode。3.3 终端里的三个高效用法虽然插件很方便但老手最后还是会回到终端因为命令行能脚本化、能管道。这三个用法我几乎每天用# 1. 一次性问题不进入交互界面 opencode 解释一下 src/utils/date.ts 里 formatDate 的实现 # 2. 给一段 stdin 内容让 Agent 根据上下文处理 git diff | opencode 帮我 review 这段改动指出潜在问题 # 3. 只读模式禁止 Agent 改文件适合让 AI 先给方案 opencode --read-only 分析这个项目怎么加缓存层一次性调用很适合放在自己的 shell 别名里。比如我在~/.zshrc里加了alias aiopencode --read-only这样临时问问题、快速解释报错都不用进 TUI。交互界面里则要记住几个关键命令/help看所有命令/model切换模型/context查看当前传入 Agent 的上下文文件/undo用来回滚上一次 Agent 修改。特别是/undo非常救命建议新上手的人先记牢。4. 进阶玩法Skills、LSP 与 Playwright 前端联调4.1 Skills给 Agent 写一份“团队规范手册”opencode 支持 Skills 机制这就是热词里“opencode skills”所指的东西。通俗讲Skills 就是一系列 Markdown 指令文件你把它放到一个特定目录Agent 在执行任务时能读取这些文件来调整自己的行为风格。在 Linux/macOS 上默认配置目录是~/.config/opencode/skills/在 Windows 上通常在%USERPROFILE%\.config\opencode\skills\。每个 Skill 是一个子文件夹里面有一个SKILL.md。举个例子我想让 Agent 帮我写 Go 代码时严格遵循项目规范就创建go-style/SKILL.md# Go Code Review Rules - 对所有导出的函数必须写注释且以函数名开头 - 错误处理必须显式不允许忽略 error 返回 - 使用标准库优先第三方依赖需要解释理由 - 禁止使用 global variable 保存状态然后在会话里用/skills go-style唤醒它Agent 后续的回复和改动都会遵循这些规则。这比你在 prompt 里反复强调有效得多尤其适合开源项目和多人协作团队。把 Skill 文件提交到 Git 仓库团队所有人就都能共享同一套“行为准则”。4.2 LSP让 Agent 拥有“编译器视觉”opencode 另一个让人上瘾的功能是内置 LSPLanguage Server Protocol集成。LSP 这个东西你可以把它理解成“编辑器和语言服务器之间的翻译协议”。VSCode 的智能感知、跳转定义、错误提示背后就是 LSP 在干活。opencode 直接把这一层能力接给了 Agent意味着你问它某一类型定义在哪、某个函数在哪里被调用它不是靠猜而是通过语言服务器得到准确答案。使用上不需要额外开启它会在打开项目时自动识别语言并启动对应的语言服务器。比如 TypeScript 项目会启动typescript-language-serverPython 项目会启动pyright。这些服务的依赖需要你提前装好不然 Agent 可能只能做文本层面的搜索。我建议在一个巨大的 Monorepo 里如果 opencode 明显变卡可以在配置里关掉 LSP或者限制作用的 workspace。后面我会贴配置示例。曾经有次我在一个前端仓库里让 Agent 分析路由结构LSP 扫描了几万行代码内存占用直接飙到几个 G后来我改成只让它读src/pages目录瞬间快了很多。4.3 用 Playwright 帮 Agent 长出手和眼睛热词榜里有“opencode playwright 怎么测试前端bug”这是个很实用的场景。默认情况下Agent 是看不到浏览器的但你可以让它写 Playwright 脚本跑起来后把页面截图和控制台报错拿给你看等于给 Agent 接上了“手”和“眼睛”。我常用的套路是直接在 opencode 会话里下指令用 Playwright 打开 http://localhost:3000/login 点击登录按钮不要填任何表单 把页面控制台console的所有报错抓下来 然后把当前页面截图保存到 /tmp/bug.pngAgent 会自动在项目里创建一个临时测试脚本通过 npm 安装playwright依赖如果没有的话然后执行脚本再把结果反馈给我。这个过程里你要留意它会不会改变了项目里的 package.json。为了不污染项目我一般建议它把脚本写在/tmp或者项目根目录下.agents/文件夹里跑完就删。使用前确保本地已经安装了浏览器运行时npx playwright install chromium如果没有装Agent 执行脚本时通常会报Executable doesnt exist这个错很常见不是 opencode 的问题。对于前端开发者这个组合基本上等于拥有了一个“能自己报 bug 并附上截图”的自动化测试助手。5. 配置管理JSON、切换器和常见报错5.1 用 JSON 文件统一管理配置opencode 的核心配置文件是opencode.json。Linux 和 macOS 下路径是~/.config/opencode/opencode.jsonWindows 下是%USERPROFILE%\.config\opencode\opencode.json。热词里有人搜“opencode linux修改json”说明大家都绕不开这个文件。我的配置长这样{ provider: { default: openai, openai: { api_key: sk-xxxxxxxx, base_url: https://api.openai.com/v1, model: gpt-4o }, ollama: { base_url: http://localhost:11434/v1, model: qwen2.5-coder:14b } }, lsp: { enabled: true }, theme: dark, skills: { paths: [~/.config/opencode/skills] } }注意几点第一base_url可以填兼容 OpenAI 协议的本地服务地址这也是接入某些私有网关或本地服务的通用方式第二修改 JSON 后已经打开的 opencode 会话不会自动加载全部配置重开一次最稳妥第三不要把自己的 API Key 明文提交到 Git 仓库我都是配合环境变量注入。5.2 配合 CC Switch 等模型管理工具要注意什么如果你同时用 Claude Code、Codex CLI、opencode 好几个工具那你一定会遇到“模型 Key 管理混乱”的问题。热词里的 CC Switch 就是专门解决这个痛点的桌面工具它可以把不同模型服务商的 API Key 和 Base URL 集中管理一键切换。opencode 本身不依赖 CC Switch它自己有完整的 provider 配置体系。但两个工具配合使用时有一个容易踩的坑CC Switch 在切换某个配置后通常是通过修改环境变量比如ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY来影响模型的调用地址。而 opencode 的配置里如果显式写了api_key和base_url会优先读自己的 JSON不理会环境变量导致你切了 CC Switchopencode 还是走旧的地址。我的做法是在 opencode 的 JSON 里只写 provider 名称不写具体的 key让它从环境变量读取。这样 CC Switch 切到哪套配置opencode 就跟着走哪套。如果你只是想“一次配置多工具复用”记得保持两级配置互相不冲突。5.3 网上热度最高的几个报错一次说清把热词里出现的报错整理成了一张表这些都是真实出现过的排障记录报错/现象可能原因排查与解决无法将 opencode 识别为 cmdlet安装成功但 PATH 没配置好检查 npm prefix 目录加入用户 PATHthis model is not available in your country模型服务商对该地区不开放查看服务商区域支持列表换用可用模型或使用本地 OllamaError: unexpected server error. check server logs服务端临时故障 / API Key 失效 / 网络异常先重试再检查 Key 和网络最后看日志model not found模型名与 Provider 实际 ID 不一致用/models刷新列表核对模型名Executable doesnt exist缺少 Playwright 浏览器运行时执行npx playwright install chromiumopencode 启动卡死LSP 扫描超大项目临时关闭 LSP或限制工作目录关于this model is not available in your country这个报错网上会看到一些“改配置绕过”的说法这里我不建议也不展开。合规、稳妥的做法是换另一个在你所在地区合法的服务提供商或者选用本地开源模型。你会发现问题立刻消失而且数据隐私还能更好一点。日志方面默认存放在~/.local/share/opencode/log/Linux/macOSWindows 在%USERPROFILE%\.local\share\opencode\log。真的遇到看不懂的服务器错误直接看最新日志比到处搜索快得多。6. opencode、Codex CLI、Claude Code、Pi 到底该选谁6.1 四款终端 Agent 的横向对比既然热词里这么多人问“opencode codex claude code”“opencode codex pi 哪个 agent 好用”我就按照自己实际体验画个对比表方便你直接拍板工具模型绑定开源编辑器集成上手成本适合谁opencode多模型 自定义是VSCode / JetBrains / 终端中想自己掌控模型和流程的开发者Claude Code以 Claude 为主否官方工具终端为主低Claude 重度用户Codex CLI以 OpenAI 系为主开源终端 VSCode 扩展低OpenAI 生态用户Pi多模型部分开源终端/桌面端低想要极简对话式 AI 助手的人这里多说一句“Pi”。Pi 更偏“常驻型 AI 伙伴”它可以完成不少对话和自动化任务但作为一个面向工程级的代码修改 Agent它的能力和聚焦度目前不如 opencode 这类专门为开发者设计的工具。如果你是代码调试为主我更建议 opencode如果你只是想要一个能在终端陪你聊天、顺便写点小脚本的工具Pi 会更轻巧。6.2 我的真实选择建议我的原则是复杂度高的项目用 opencode测试性强的场景直接上 Codex CLI需要深度上下文理解的项目用 Claude Code。它们不是非此即彼的关系完全可以共存。我给新手的方案是一开始只装 opencode 一个用 OpenAI 兼容接口或本地 Ollama 跑通一个最简单的“改 bug”流程。接着把 VSCode 插件装好在侧边栏体验 Agent 读代码的感觉。等熟悉了交互模式和配置文件再试着加 Skills、接 Playwright。这时候你会发现 claude code 或 codex 无非是换了一层皮核心套路你已经门儿清了。另外工具选型别只看热度榜。搜索的时候看到很多人讨论“opencode 2.0”“opencode omo”“opencode desktop”这说明项目迭代非常快。建议你定期关注官方 changelog不要用一个月前的印象评价现在的版本。7. 最后说点私房经验如果你现在正准备从零开始接触 opencode我送你一条我最深的体会不要一次性把配置搞得太复杂。我刚开始的时候既想接本地模型又想挂 Playwright还想写一堆 Skills结果连续两个晚上都在折腾配置文件正儿八经的代码一行没写。后来我把所有配置删了只留下一个默认模型认认真真用它改了一天需求反而收获最大。还有一点遇到 Agent 给出离谱修改时先冷静用/undo回退再让它给出解释。不要直接否定它也不要全盘接受它。把它当成一个非常聪明但偶尔走神的实习生你负责把关它负责干活这个关系会舒服很多。工具永远是工具最后做决策的还是我们自己。希望这篇记录能帮你少踩几个坑把时间真正花在写代码本身。
