opencode 实战指南：从安装到 LSP 与 Playwright 的 AI 编程代理全解析

最近AI编程助手这个赛道肉眼可见地拥挤起来。GitHub Copilot 改了名，Claude Code 火得不行，OpenAI Codex 也从实验品磨成了默认功能。我这两月在两个真实业务项目里来回试，最后常驻终端的反倒是一个起初最不起眼的名字：opencode。它不吵不闹，开源，跨平台，装个命令行就能聊，接模型也自由，内核跟 Claude Code、Codex 走的是同一条 Agent 技术路线，但在“到底用谁的模型”这件事上给了你最大的选择权。

如果你正纠结“要不要从 Claude Code 或 Codex 迁到 opencode”，或者已经照着热搜里的教程装完了却报了一堆错，这篇可以当一份避坑向的 opencode 使用教程。我会把安装、模型接入、skills、memory、LSP、Playwright 测前端这套东西串起来讲，全程只讲我在真实项目里踩过、验证过的东西，不整虚的。

1. 为什么我突然盯上一个叫 opencode 的 AI 编程代理

1.1 它到底是什么，和 Claude Code、Codex 放一桌比

opencode 是一个运行在终端里的 AI 编程代理，核心逻辑和 Claude Code、Codex CLI 很像：你先给它一个任务，它在终端里读文件、搜代码、执行命令、看报错，再决定下一步怎么改。你只需要在边上看着它的思考过程，遇到不合理的地方随时打断纠正。

但它和那几个“官方绑定自家模型”的工具有一个关键区别：opencode 不锁死模型。Anthropic 的模型能用，OpenAI 的模型能用，本地 Ollama 起的开源模型也能用，第三方兼容网关同样能用。我在项目里甚至同时挂了两个模型通道，日常琐碎任务走便宜快速的，复杂重构才切到旗舰模型。这种自由度是很多官方 CLI 给不了的。

第一次搜 opencode 的人还会顺手问一句“opencode 是哪家公司的”。按公开信息看，它是开源项目，代码仓库挂在 GitHub 上，有清晰的 License 和活跃的社区讨论，不是封闭小黑盒。对我来说，它是大厂还是独立团队出品其实不重要，我更看重它迭代速度快不快、社区反馈能不能及时汇入主干。实测下来，它在这方面是合格的。

1.2 我试用时的真实场景

我判断一个 AI 编程工具合不合格，从来不看 Demo 演示，只看两件事：第一，扔进一个我没那么熟的老项目里，它能不能自己摸清楚模块关系；第二，让它做一个跨文件修改时，它会不会把无关代码顺手改坏。

我这次拿它接手的项目是一个有六年历史的后端服务，Java 和 TypeScript 混着，Maven 模块拆了七八个，代码里还全是上个团队留下的历史包袱。我给了 opencode 一个非常模糊的任务：“帮我理一下订单模块和库存模块之间通过什么接口调用”。它没有上来就改代码，而是先做了三件事：找到入口类，追踪 Maven 依赖关系里的相关模块，再把涉及的核心 service 方法列出来。这个“先读懂再动手”的习惯，比它实际改了多少行代码更打动我。

所以这篇文章不是写给“我就想让它自动生成个登录页”的人看的，而是给那些真的想用 opencode 接手任务、改造老项目、把它融进日常开发流程里的人。下文所有配置和命令，均以我当时使用的版本为参考，不同小版本之间某些具体命令名可能略有差异，但整体思路一致。

2. opencode 安装与启动，排掉最常见的三个坑

2.1 官方安装方式：脚本和包管理器两条路怎么选

opencode 的安装方式其实不算复杂，基本可以分两条路：官方提供的一键脚本，以及 npm 全局安装。网上搜“opencode 安装”能搜出一堆教程，但很多都没说清楚这两条路的适用场景。

• 一键脚本：适合大多数用户，尤其是机器上没有 Node.js 环境的人。脚本会把 opencode 的二进制装到用户目录下的隐藏文件夹里，并且自动往 PATH 里写路径。
• npm 全局安装：适合前端/Node 技术栈的人，方便用npm update -g opencode-ai之类的方式统一升级。注意包名在不同版本里不一样，装之前先去 npm 页面确认当前包名，别装错。

我的建议是：如果你只是想在 Windows 或 macOS 上快速跑起来，用官方脚本最省心；如果你本来就在前端项目里天天折腾 Node 版本，那 npm 全局安装跟你的心智模型更契合。

另外官方也提供了桌面版产物，部分版本里还区分了“desktop”和“cli”两种形态。桌面版本质上还是包了一层图形界面，底层调用同一个引擎。我个人的感受是，日常写代码用终端或 IDE 插件更顺手，桌面版更适合那种“我想单独开一个窗口盯着 agent 干活”的场景，比如让它跑一个很长的测试修 bug 流程。

2.2 “无法将 opencode 项识别为 cmdlet”的根因与解决

Windows 用户高频踩的第一个坑，就是标题里那句经典报错：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

这句话翻译成大白话就是：系统在当前 PATH 路径里找不到 opencode 这个可执行文件。很多人第一反应是“安装失败了”，于是重装一遍，结果还是报错。这不是安装的问题，是环境变量没生效。

排查步骤很简单：

1. 先确认可执行文件到底装到哪了。如果你用的是一键脚本，默认会装到用户目录下的某个隐藏路径，比如C:\Users\你的用户名\.opencode\bin；如果是 npm 全局安装，则通常在你 Node.js 对应的 npm 全局目录下。
2. 用where.exe opencode看系统能不能搜到。如果什么结果都没有，说明 PATH 里确实没有对应目录。
3. 打开“编辑系统环境变量”，把 opencode 可执行文件所在目录追加到用户变量的 PATH 里。
4. 关键一步：保存后务必重新打开一个终端窗口，别在旧窗口里直接敲。PowerShell 只有在启动时才会重新读取 PATH，旧窗口还保留着启动时的快照。
5. 再执行opencode --version验证，能输出版本号就说明通了。

顺序不要搞反。我有一次就是先改 PATH 又在同一个窗口里测试，试了三次以为自己配置错了，浪费了二十分钟。

2.3 旧版残留与全局配置目录

另一个隐蔽坑是旧版本残留。opencode 迭代快，你之前可能装过 preview 或测试版，卸载不干净就会造成新版装好了，但实际起的是老二进制。命令行版本号明明是最新的，行为却跟旧版一样。

遇到这种情况，我的处理习惯是先彻底清理再重装。在 Linux 上，配置文件默认在~/.config/opencode/，临时文件和认证信息也可能放在同目录下；Windows 上对应的是%APPDATA%\opencode或用户目录下的.opencode。舍不得配置的话，可以先备份opencode.json和存放 skills 的目录，然后把旧配置目录整体移走，再启动新版本，让它重新初始化一份干净配置。

关于“opencode linux 修改 json”这类搜索最近特别多，说的就是opencode.json这个配置文件。它长得很像 VSCode 的 settings.json，全局配置和项目配置可以分层覆盖。项目根目录放一份，会优先于全局配置生效；你把团队约定写在项目配置里提交到 Git，其他人拉下来就自动沿用，这种协作方式比人人各自调参要稳得多。

3. 模型接入、免费模型与订阅服务选择

3.1 模型从哪里来：官方 API、第三方聚合和本地模型

opencode 本身不生产模型，它只是把各种模型接到同一条 Agent 流程里。所以安装只是第一步，接模型才是真正决定你用起来爽不爽的地方。

当前主流接入方式大概三种：

• 官方 API：如 Anthropic、OpenAI 官方通道，稳定性好，延迟可控，但成本高。
• 第三方聚合/订阅服务：也就是像“opencode go”这类按套餐或按量收费的中转服务，一次订阅可以在多个模型间切换，适合需要频繁换模型对比效果的人。
• 本地模型：Ollama 之类拉起来的开源模型，私密性最好，零接口费用，但代码能力天花板明显，更适合做简单任务或离线环境。

opencode 的认证逻辑也做得比较清晰，通过类似opencode auth login的交互命令选择模型服务商并填入 API Key，配置会写进opencode.json的 provider 字段里。不同版本的交互入口可能有细微差别，但思路一致：先把认证信息给到 opencode，它才知道去找谁要模型。

3.2 opencode go 订阅到底怎么选套餐

搜“opencode go 订阅模型选择”的人多半是被套餐选择难住了。这类聚合服务一般会分两种计费逻辑：按量付费和包月套餐。按量付费适合使用频率不稳定的人，包月套餐则适合每天都深度使用的人。

我的选型原则其实很简单：

• 日常小需求，比如改个配置、解释一段代码、写个正则，用速度最快的“轻量模型”就够，没必要消耗旗舰模型的额度。
• 批量重构、多文件理解、框架迁移这类复杂任务，再切到旗舰模型。
• 建议选支持“模型自动路由”的服务，也就是它会根据你问题的复杂程度自动分配模型，省去手动切的麻烦。

另外，很多人在搜“opencode go 需要配合 cc switch 等工具吗”这个问题。ccswitch 这样的社区工具，作用是快速切换不同服务商或不同模型通道的配置，让 opencode 在多个 provider 之间跳转时不至于每次手动改 JSON。它不是 opencode 本体的一部分，而是配置管理的外挂。你如果只固定用一个服务商，完全不用装；如果你同时有官方 API 和多家中转订阅，那装一个确实省事。

这类聚合订阅服务有个共性风险：稳定性取决于服务商上游。遇到高峰期，延迟可能突然飙高，甚至返回空响应。我的建议是别把鸡蛋放一个篮子里，至少保留一个官方 API 通道作为兜底，临时出问题时切过去，不至于耽误手上活。

3.3 “this model is not available in your country”怎么排查

这个报错近期的搜索量涨得很快，实际含义是：你当前选择的模型在你的账号或网络环境下不可用。注意，这个判断通常由模型服务商完成，不是 opencode 在乱拦截。

我遇到过一次类似情况，opencode 里其他模型都正常，单独某个模型一调用就返回“This model is not available in your country”。我当时的排查顺序是这样的：

1. 先确认是不是配置问题。打开opencode.json，看当前 model 字段到底指向哪个模型，有没有拼写错误。
2. 直接去模型服务商控制台确认这个模型的可用区域列表。如果模型本身在你的区域没开放，那错误提示就是准确且合法的，属于账号授权范围问题。
3. 检查 API Key 的订阅类型。有些 Key 只允许访问部分模型，不是所有模型都能调用。
4. 换一个相同能力的替代模型。同一个服务商往往有多个能力接近但不完全相同的模型，换掉后效果差异通常不大。

这里我想额外说一句：网上有些教程会尝试引导你改系统的网络出口来绕过区域限制，我个人的态度是不建议这么做。一方面这违反服务提供方的使用条款，另一方面风险很高，账号被风控反而是小事，企业项目里的敏感代码被牵连才是大问题。更稳妥的做法就是前面说的：确认模型可用范围，能用一个合规的替代模型就换，不能就换服务商。

3.4 免费模型与渠道下线风险

“opencode 免费模型”是另一个高流量搜索词，说明很多人就是想零成本试水。社区里也确实出现过一些免费的模型中转渠道，比如之前讨论度很高的 hy3-free 之类。这类免费渠道通常由个人或小团队维护，稳定性没有保障。

网上现在搜“hy3-free 下线了吗”，说明它已经出现服务不稳定甚至停止服务的情况。免费渠道的生命周期本来就短，可能今天能用，明天就限流，后天直接挂。我的建议是，免费模型可以拿来体验 opencode 的工作流，感受 agent 和普通 AI 聊天有什么不同，但千万别在正式项目里依赖它。

如果你所在区域对某类 API 的访问本身有限制，那更不要在免费渠道上抱侥幸心理。合规地选择正式开放的模型通道，虽然可能要花点钱，但至少不会在你改到一半的时候被突如其来的报错打断节奏。我现在的做法是免费模型只给“学习用”，生产环境一律走稳定订阅或官方按量。

4. 从能用到好用：skills、memory 与 LSP 的实战

4.1 memory：让 opencode 记住项目偏好

很多人使用 AI 编程代理时最大的挫败感是“每次都得教它重新认识项目”。今天告诉它项目用 pnpm，明天它又用 npm；今天让它别改测试文件，过两天又忘了。memory 功能就是为解决这件事出现的。

在 opencode 里，memory 的作用是让模型跨会话保留特定信息。项目级别的文件类似AGENTS.md，你可以在里面写清楚项目命令、目录约定、代码风格、禁止事项。opencode 每次启动代理时都会读取这份文件，把它当作“项目入职手册”。

我自己的写法是：

# 项目约定 - 包管理器使用 npm，不要使用 pnpm 或 yarn - 构建命令: npm run build - 测试目录在 tests/ 下，修改源码时必须同步更新相关测试 - 数据库迁移脚本放在 db/migrations/，不要手工改数据库

有了这份文件之后，模型在新会话里就基本不会再犯低级的方向性错误。这比每次对话开头都复制一大段上下文要靠谱得多。

如果你用的是支持显式 memory 命令的版本，也可以把一些跨项目通用的经验写进去，比如“所有 HTTP 请求超时时间不能超过 15 秒”。这类信息进入记忆后，后续任务就会被自动遵守。

4.2 skills：把高频操作固化成可复用能力

skills 的概念不是 opencode 首创，但它在 opencode 里的实现很轻量：在配置目录下建一个skills文件夹，每个技能是一个带说明文档的目录。模型在需要时，会读取技能说明里的触发条件和执行步骤。

举一个我实际固化的技能例子。这个项目里每次改完后端接口，都需要手动验证接口响应，而且验证命令里有很长的参数。我把这套流程写成 skill：

# 验证用户订单接口 ## 触发条件 - 当任务涉及修改订单相关接口时 ## 执行步骤 1. 启动本地后端服务: npm run start:api 2. 构造请求参数: 创建测试订单，使用默认用户 token 3. 调用接口: GET /v1/orders/:id 4. 检查返回状态码是否为 200 5. 如果出现新增字段，检查数据库表结构是否同步

接着写一个简单的SKILL.md，描述这个技能的触发关键词。之后再让 opencode 改订单接口，它就会自动调用这套流程做验证，而不是改完就拍屁股走人。

网上常提到的“opencode 接入 superpowers”，本质就是一个预置技能集。它把常见的代码审查、调试、重构流程做成了一套标准可复用的 skill，装好后 agent 的行为会更像一位有经验的老工程师。类似“oh-my-claudecode”这种网红项目也是同一个路子，只不过它把配置管理、提示词风格和辅助脚本打包得更完整。

我的建议是，不要贪多。先把两三个自己最高频的操作固化成 skills，比如“跑前端单测”“定位接口报错”“生成迁移脚本”，用爽了再慢慢加。技能太多反而会让模型在决策时犹豫，影响响应速度。

4.3 LSP：让 opencode 真正“读得懂”项目

模型再聪明，如果只能在文本层面瞎猜代码结构，改起大项目依然容易翻车。LSP（Language Server Protocol）接入是解决这个问题的关键，它让 opencode 能像 IDE 一样拿到代码的语义信息。

“opencode 如何使用 lsp”的热搜说明已经有不少人注意到了这个高级用法。基本原理是在opencode.json里配置 LSP 服务器，让模型能查询符号定义、跳转、自动补全相关的语义信息。对 TypeScript 项目来说，你会配置 typescript-language-server；对 Java 项目，则可以配置 jdtls 或基于 Maven 构建的语言服务。

这里重点说一下“opencode mvn 配置”。Java 项目最麻烦的地方是依赖解析，模型如果读不懂pom.xml里的依赖关系，就很容易把 import 写错或者改到根本不相关的模块。配置好 Java LSP 之后，模型可以直接通过语言服务器获取类路径信息，改代码时的准确率会明显提升。

我当时的配置思路是：

1. 确认本机已经装好对应语言的 LSP 服务；
2. 在 opencode 的配置 json 里声明 LSP，并把项目根目录指过去；
3. 启动后先给 opencode 发一个指令，让它用 LSP 解析当前模块，比如“用 LSP 查看 OrderService 类引用了哪些外部依赖”。

这种结合了 IDE 语义能力的方式，让我觉得 opencode 不再只是一个“能在终端里跑的大型语言模型”，而更像一个真正接了开发工具链的工程助理。

4.4 用 Playwright 复现并定位前端 bug

前端 bug 一直是 AI 编程代理的弱项，因为模型看不到页面。Playwright 的出现，把“让 AI 自己开浏览器验证”变成了现实。

热搜里“opencode playwright 怎么测试前端 bug”问得非常具体。我的实际使用流程大致是这样的：

1. 让 opencode 写一个 Playwright 脚本，目标是打开本地开发服务器的一个指定页面；
2. 脚本进行点击、输入、截图，并把控制台报错抓下来；
3. 模型根据截图和控制台报错定位问题源头；
4. 修改代码后重新跑一遍 Playwright 脚本，确认页面恢复正常。

下面是我常用的 prompt 模板：

帮我用 playwright 打开 http://localhost:5173/products 页面， 点击"立即购买"按钮，等待 3 秒后截图保存到 /tmp/checkout.png。 如果页面控制台有报错，把报错信息完整记录下来。 最后对比页面是否符合预期，如果不符合，尝试定位是哪个组件的问题。

用这种方式，我遇到过两次典型的定位成功案例：一次是按钮点击后没触发请求，模型通过控制台报错找到了某个事件被stopPropagation拦截；另一次是新功能页面白屏，模型截图看到空白，顺藤摸瓜查到了路由懒加载的 import 路径写错。

当然，Playwright 这层能力不是 opencode 独有，但它在 opencode 里调用起来特别顺畅，原因是 opencode 本身就在终端里执行命令，而 Playwright 天生就是命令行的好搭档，二者结合非常自然。

5. 把它嵌进日常 IDE：VSCode、JetBrains 与桌面版

5.1 三个入口怎么分工

opencode 的形态越来越丰富，除了终端 CLI，还有 VSCode 插件、JetBrains 插件和桌面版。很多新手会疑惑“我到底该用哪个”，我的建议是按场景来：

• 终端：适合你已经在 Vim/Neovim 或者纯终端工作流里的情况，也是体验最完整、功能迭代最先到位的入口。
• VSCode 插件：适合大多数前端/Node 开发者，你人就在编辑器里，直接把选中的代码或报错丢给 opencode，不用来回切窗口。
• JetBrains 插件：适合 Java、Kotlin 等技术栈，IDEA 里看代码上下文更方便。
• 桌面版：适合长时间跑任务时，单独一个窗口监控 agent 的行为。

我日常最常用的是 VSCode 插件，因为它能直接读取当前打开的编辑器内容、选中代码和文件路径，省去了很多解释上下文的成本。但在大型 Java 项目里，我还是会切到 IDEA 插件，因为 Maven 依赖和类跳转在 IDEA 里更成熟。

5.2 VSCode 插件配置与使用心得

VSCode 插件的安装没什么难度，直接在扩展市场搜 opencode 就行。装好后要注意的一件事是确认扩展能定位到 opencode 的可执行文件。如果之前你从终端手动安装过，路径可能没暴露给插件，需要在设置里手动填一下二进制路径。

我的使用习惯是：先把鼠标停在出问题的代码上，同时选中报错堆栈，右键选择“发送给 opencode”，让它结合当前文件内容一起分析。比手动复制粘贴上下文要高效得多。

“vscode opencode 插件”的高频搜索词背后还有一个隐藏需求：如何让它跟项目里的.env、配置文件、测试命令联动。插件本质上只是壳，真正干活还是靠核心 CLI。所以你在opencode.json里配置的 skills、memory、LSP，在插件里同样生效。这也就意味着，调试好一套配置，三个入口可以共用，非常划算。

5.3 JetBrains IDEA 插件与 Maven 项目的联动

IDEA 插件是我在 Java 项目里的主力。安装后，需要在插件设置里指定 opencode 的执行路径，并配置默认模型。如果你是 Maven 多模块项目，强烈建议在配置里加上-pl 指定模块之类的构建约定，否则 opencode 很可能在根目录执行 mvn 命令然后被全量编译拖死。

“opencode jetbrains idea 插件”的搜索热度一直不低，但真正把配置细节讲清楚的资料不多。我的经验是：

1. 打开项目根目录下的opencode.json，添加 Maven 相关的 LSP 配置；
2. 在 memory 文件里写清楚“编译和测试都在模块级执行，命令参考mvn -pl order-service -am test”；
3. 第一次使用时主动问它一句：“这个项目有哪些 Maven 模块？order-service 模块的依赖有哪些？”让它先建立模型认知。

这样配置好之后，IDEA 里的 opencode 才不会像无头苍蝇一样乱跑。

5.4 ccswitch 管理多套配置，减少心智负担

我看到“ccswitch配置opencode”这个词的时候，其实挺能理解大家的需求。一个开发者往往会同时订阅官方 API、某个聚合订阅、甚至本地模型，对应需要维护不同模型的配置文件和 API Key。每次手动切换既容易出错，又容易把生产环境的配置弄丢。

ccswitch 这类小工具的思路是：预置多套完整配置，一键切换当前生效的配置。它本质上只是帮你复制/软链配置文件，核心还是 opencode 自己的配置加载逻辑。

我用它管理了三套配置：

切换命令非常简单，比如ccswitch use pro之后，opencode 下次启动读到的就是 pro 配置。配合 ccswitch 的提示符显示功能，你能时刻知道自己当前在哪个模型通道下，避免拿着旗舰模型干杂活、白白烧额度。

如果你没有这类工具，也可以手动维护两三份 json 然后复制覆盖，但说实话，手工切配置迟早会出错一次。我确实曾经因为忘切换配置，让轻量模型去做大任务，结果生成了大量低质量的“废话代码”，还不如自己写来得快。

6. 实际接盘老项目时，opencode 表现如何

6.1 先让它“读”而不是“改”

在新项目里，AI 编程代理写代码很爽；在老项目里，最容易翻车的反而是“读代码”。老项目往往有历史遗留的命名习惯、循环依赖、隐式约定，这些在代码里不会明说，模型容易误判。

我的策略是：接手任何老项目的第一天，绝不让 opencode 直接改任何业务逻辑。只给它一个任务，把项目结构、模块职责、核心数据流、关键接口列表梳理出来。

针对“opencode 接手开发项目”这个搜索需求，我给出一段我实际用过的 prompt：

请先不要修改任何代码。任务是： 1. 分析当前项目根目录的 pom.xml / package.json，列出所有模块； 2. 找到入口类和核心配置类，说明项目启动流程； 3. 画出订单模块的核心调用链，只用文字描述，不用图表； 4. 标注出代码里 TODO、FIXME 比较集中的文件，这些可能是有历史包袱的地方。

opencode 跑完之后，我会把梳理结果读到 memory 文件里，让它成为后续所有会话的共享背景。这样再做具体需求时，它就不会连项目怎么启动都不知道。

6.2 一个跨文件需求，我让它按这个顺序干活

我实际让它改过一个跨模块需求：订单创建后需要异步通知库存模块扣减，并且要在库存不足时返回特定错误码。这个需求涉及订单 service、库存 service、消息队列 topic、错误码定义文件四个位置。

如果一步到位让它改完，风险很高。我是这样拆解的：

1. 先让它定位现有订单创建方法的位置，以及库存扣减服务的入口；
2. 让它列出现有消息通知的所有 topic 和使用方式，确认有没有可复用的；
3. 让它设计一个最小改动的方案，但不落代码；
4. 确认方案没问题后，才让它按“先定义错误码、再改库存校验、再改订单调用、最后写测试”的顺序执行；
5. 改完后让它跑相关测试，并把测试结果反馈给我。

整个过程中最重要的不是它写得快，而是它在每一步都停下来等我确认。这个“分步确认”的习惯，是我在 memory 文件里预先写好的约定。如果你拿到 opencode 的第一时间就开始让它一口气改完，很容易得到一份能编译但行为完全不对的代码。

6.3 Windows 终端里 unexpected server error 怎么定位

我遇到过在C:\Windows\System32>这个默认目录下直接执行opencode，结果报unexpected server error. check server logs的情况。这个问题在 Windows 上特别容易误导人，因为任何人打开终端都默认停在系统目录，而你如果在这个目录下启动 opencode，它会尝试把当前目录当作项目根目录，读取不到任何项目配置，进而触发各种诡异报错。

我当时的排查链路是：

1. 先确认是不是网络问题。执行opencode --version一切正常，但发消息就报错，说明二进制和网络没问题，问题出在上下文。
2. 再看配置目录。检查opencode.json和认证信息是否存在且正确。
3. 最后才意识到，错在把工作目录选在了 System32。我 cd 到项目目录后重新启动 opencode，同一个模型、同一个 API Key，问题直接消失。

如果你在 Windows 下遇到类似报错，第一步永远是看两样东西：当前工作目录是否为项目目录，以及项目目录下有没有被 opencode 识别到的配置文件。不要一上来就怀疑模型或 API Key，很多“server error”其实只是环境问题。

如果确认目录没问题但依然报错，那就去找它提示的日志文件。opencode 通常会把日志写到配置目录下的 log 文件里，打开看最后几十行，基本能定位到是模型服务商的上游超时，还是本地某些命令执行失败。日志信息虽然看着枯燥，但比猜要快得多。

7. Codex、Claude Code、Pi、opencode，到底选哪个

7.1 横向对比的真实差异

网上隔几天就能看到“opencode codex claude code 哪个 agent 好用”或者“opencode codex pi 哪个 agent 好用”的提问。我也装了这几个工具，来回用了差不多一个月，简单说说我的主观感受。

“opencode codex pi 哪个 agent 好用”这类问题的答案，其实取决于你的核心诉求。如果追求配置自由度和可扩展性，opencode 是明显更好的选择；如果只想开箱即用，对模型绑定无所谓，那 Claude Code 或 Codex 的选择题反而更简单：看你更喜欢哪个模型商。

7.2 什么场景我会固定用 opencode

经过这段时间的使用，我给自己定了一个很清晰的选择标准：

• 需要同时操作多个模型时，用 opencode；
• 项目里要定制大量团队规范、skills、memory 时，用 opencode；
• 需要在本地离线环境跑开源模型时，用 opencode；
• 前端 bug 要结合 Playwright 做多轮回归时，用 opencode。

道理很简单，这些场景都涉及“深度定制”，而 opencode 开放的结构给了你最大的操作空间。相比之下，如果你只是想要一个不费脑子的结对编程伙伴，那绑定大模型能力的官方 CLI 反而更合适。工具本身没有绝对的谁碾压谁，只有适不适合你目前的项目形态和性格偏好。

7.3 我踩过一圈之后的心里话

现在 AI 编程代理的选择太多，最大的成本其实不在订阅费，而在你花在“熟悉工具特性”上的时间。我不建议今天看这个推荐就换，明天看那个对比又换。选定一个主力工具，花两三天把配置、skills、memory、LSP 调顺，然后再深度使用两星期，再去评价它好不好，这才是一个负责任的评估流程。

我个人最终选择 opencode 留下，不是因为它哪个单点能力最强的，而是因为它最愿意放手让我改。它不会替我做太多决定，我让它用什么模型、按什么流程、守什么规矩，它都会老老实实去执行。这套“可控感”是我在日常复杂项目里最看重的东西。opencode 的社区还在高速迭代，也许两三个月后它又会变个样，但只要它保持这种开放干净的架构，我就愿意继续往它身上投入配置成本。