opencode实战指南：从安装配置到编辑器集成的AI编程助手全攻略

AI编程助手这两年火得不行，从Codex到Claude Code，再来一个opencode，命令行里写代码的玩法已经彻底变天了。opencode一出来我就装了，用到现在差不多成了我日常主力工具之一，平时修bug、补单测、接手老项目、翻前端问题，基本都是它在干活。这篇文章就把我从安装到配置、从模型选择到Skills扩展、再到VSCode和IDEA里集成的完整折腾过程写出来，包括那些特别常见又特别容易卡的报错，比如Windows下“无法将opencode识别为cmdlet”、this model is not available in your country、opencode-go订阅怎么选模型，都会一个个拆开讲。想从零上手opencode，或者已经在用但总被配置和报错卡住的同学，这篇应该能省你不少时间。

1. 项目定位与核心设计思路

1.1 opencode是什么，能解决什么问题

opencode是一个开源的、跑在终端里的AI编程Agent。说得直白一点，它是一个命令行程序，你在项目目录里启动它，它就能读懂你的代码、帮你改文件、执行命令、运行测试，甚至自己打开浏览器去复现前端bug。跟Copilot那种“在你写代码时补全”的助手不一样，opencode更像一个“你给它下需求、它自己动手干活的实习生”。

我最早注意到它，是因为实在受够了“绑死一家模型”的玩法。很多同类工具默认只支持某一家模型服务，一旦你想换个模型，要么折腾配置文件，要么根本换不了。opencode的定位就是模型中立，OpenAI系的、Anthropic系的、Google系的、本地跑的模型，都可以通过配置接进来，你甚至可以同时接好几家，按任务类型切换。对有多个API渠道、或者想用中转订阅来控制成本的人来说，这个灵活度太重要了。

它能解决的典型问题包括：报错信息看不懂让AI去排查、跨文件改代码不知道怎么下手、写单元测试没耐心、接手一个没有文档的老项目不知从哪看起、前端bug复现步骤太长懒得录。这些事情你只要能用自然语言描述清楚，opencode就能在终端里帮你跑起来，省掉大量机械劳动。

1.2 和Codex、Claude Code等同类工具的核心差异

很多人纠结opencode、Codex、Claude Code、pi这类Agent到底哪个好用，我自己都试过，简单说下感受。Codex胜在跟OpenAI生态绑定深，开箱即用，但你基本只能在它给的模型集合里选。Claude Code的优势是代码理解和长上下文确实强，如果你主力就是Claude模型，体验很顺，但它同样有很强的模型绑定属性。pi这个工具我也试过，它是另一个风格的CLI Agent，特色是轻量直接，但生态和扩展能力相对少一些。

opencode在这些工具里走的是“开放框架”路线。它不只对接一家模型，而是把模型层抽象出来，让你自己决定底层用谁。它还做了一套很实用的扩展机制，Skills（技能包）、LSP接入、MCP工具都能用。也就是说，你需要的不仅仅是“能改代码”，而是“能按你的工程规范、你的工作流来执行任务”，这时候opencode的架构优势就很明显了。

我专门做过一个对比，从日常使用角度列几个关键维度：

一句话总结：如果只用一个模型且不想折腾，Codex或Claude Code也许更省心；如果想把主动权握在自己手里，想在模型、工具、流程上自由组合，opencode是更合适的选择。

1.3 我为什么把它当成主力工具

刚开始我只是拿opencode尝鲜，后来真正把它转成主力，是因为它解决了我两个很实际的痛点。第一个痛点是“切换模型的成本”。我手里有多个模型渠道，有的擅长写代码，有的擅长长文本分析，以前每换一次都要改一堆环境变量和配置，现在直接在opencode的对话里切换模型就行，省事得多。

第二个痛点是“工具链碎片化”。以前查代码要开IDE，跑测试要开终端，找报错要开浏览器，几个窗口来回切。opencode把读代码、改代码、跑命令、看结果都放在了同一个对话流程里，AI干完活会告诉你它改了哪些文件、跑了什么命令、结果是什么，整个工作过程是完整的、可追溯的。这种“AI替你操作，你在旁边复核”的流程，比传统“人肉复制粘贴代码到对话框”效率高太多了。

另外它的社区活跃度也值得提一句。opencode迭代非常快，我遇到过好几次版本升级后配置字段变化，虽然有点折腾，但至少说明项目在快速进化。配合VSCode插件、IDEA插件、桌面端规划，它的生态比很多人想象中要完整。

2. 从零安装与命令行排错

2.1 安装前的环境检查

安装opencode之前，先花两分钟确认环境，避免后面各种莫名其妙的问题。opencode本质上是Node.js写的CLI工具，所以Node.js是必须的。建议Node.js版本至少20以上，版本太老会出现各种底层兼容问题，比如运行时报语法错误、模块找不到，这种问题排查起来特别没头绪。

Windows上建议先把Node.js和Git装好，macOS上如果还没装Homebrew，也建议装一个，后面操作会方便很多。Linux环境相对简单，但也要确保npm可用的用户目录有写权限。检查环境的命令很简单：

node -v npm -v git --version

如果在Windows上执行node -v提示“无法识别”，说明Node.js没装好或者PATH没生效，先解决这个再继续。这是很多人装opencode失败的第一层原因。

提示：装Node.js的时候尽量装LTS（长期支持）版本，不要追最新版。我以前在某个非LTS版本上跑opencode，遇到了跟OpenSSL相关的加密库报错，降回LTS立刻就好了。

2.2 三种安装方式怎么选

opencode的安装方式有好几种，最常用的是npm全局安装。我自己在Windows和macOS上都是用npm装的，一条命令搞定：

npm install -g opencode-ai

注意包名，我在不同版本里见过官方调整发布包名的情况，所以最稳妥的做法是打开官方文档/README，用里面给出的安装命令。直接靠记忆输命令，很容易装错包。

第二种方式是用一键脚本安装，适合不想走npm、想直接拿二进制文件的用户。官方脚本一般会帮你下载对应平台的二进制，解压到指定目录，并提示你把它加进PATH。这种方式的优点是安装快、不依赖Node运行时，缺点是升级不太方便，每次都要重新跑脚本。

第三种方式是从GitHub Releases页面手动下载对应平台的压缩包，解压后自己放在某个目录，再把目录加进PATH。适合网络环境特殊、或者公司内网无法直接访问npm仓库的场景。

我个人建议：日常开发机直接用npm全局安装，方便升级，一条npm update -g就完事；CI环境或者临时容器里用二进制方式更干净。三种方式选一种即可，不要重复安装不同来源的版本，否则会出现“明明装了两个版本，但命令执行的还是旧版”这种诡异问题。

2.3 Windows下“无法将opencode识别为cmdlet”的完整排查

这个报错可以说是Windows用户安装opencode遇到最多的问题，热词里都排在前几位。完整的报错长这样：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。

这句话翻译过来就是：系统在PATH环境变量里找不到opencode这个命令。原因基本集中在以下几类。

第一类，npm全局安装目录不在PATH里。这是最常见的情况。npm默认把全局包安装到一个目录，这个目录不一定在Windows的PATH环境变量中。先看npm的全局目录：

npm config get prefix

比如输出是C:\Users\你的用户名\AppData\Roaming\npm，那就要确认这个目录是否在PATH里。在PowerShell里临时加一下：

$env:Path += ";C:\Users\你的用户名\AppData\Roaming\npm"

能跑了，就说明是PATH问题，把它加进系统环境变量即可永久解决。

第二类，Node.js安装有问题，npm命令虽然能执行，但实际安装是失败的。这种时候执行安装命令会看到一堆warning，甚至error，但很多人只注意到了最后没报错就直接开新窗口跑opencode，结果找不到命令。我建议安装后先验证一下：

npm list -g --depth=0

能看到opencode-ai的安装记录，再继续。

第三类，PowerShell执行策略限制。Windows默认可能禁止运行本地脚本，导致opencode入口脚本无法执行。解决方法是用管理员身份打开PowerShell，查看当前策略：

Get-ExecutionPolicy

如果显示Restricted，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

改完之后重新打开终端，再执行opencode试试。

第四类，安装时权限不足。如果在公司电脑上装，npm全局目录没有写入权限，安装过程会失败或者装上但缺文件。这种情况可以用管理员权限的PowerShell重新安装，或者把npm全局目录改成用户目录下的某个自定义路径。

2.4 验证安装与第一次启动

安装完成后，先跑个版本号确认：

opencode --version

能输出版本号，说明安装没问题。第一次启动opencode，直接在你想要的项目目录下运行：

opencode

会进入一个交互式的终端界面，首次启动一般会让你选择或者配置模型提供商。如果还没配置任何模型，界面里会有提示引导你进去设置。这一步不用慌，配置模型的事情下一章详细讲。你只要能看到opencode的TUI界面正常渲染，输入文字能发出去，安装就算彻底OK了。

macOS用户如果用的是Homebrew安装的二进制版本，出现“无法打开，因为无法验证开发者”之类的提示，需要去“系统设置-隐私与安全性”里允许该应用运行。Linux用户如果跑不起来，先检查有没有缺少共享库，比如libstdc++相关报错，安装对应的基础依赖即可。

3. 模型配置与订阅选择

3.1 模型配置文件结构

opencode的模型配置集中在两个地方：全局配置和项目配置。全局配置文件一般在~/.config/opencode/opencode.json（Windows上路径可能是C:\Users\你的用户名\.config\opencode\opencode.json），项目配置则在项目根目录下的opencode.json。项目配置会覆盖全局配置里的同名项，这个设计很实用——你可以在全局配好通用的provider，在具体项目里单独指定用哪个模型。

配置文件的核心字段包括provider、model、apiKey、baseURL等。一个最基础的示例长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "anthropic": { "npm": "@ai-sdk/anthropic", "name": "Anthropic", "options": { "apiKey": "你的API Key" }, "models": { "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" } } } }, "model": "anthropic/claude-sonnet-4-20250514" }

这里的model字段就是当前对话默认使用的模型，格式通常是provider名/模型ID。如果你的某个provider支持多模型，就在models里都列出来，后面切换模型就是在provider之间切换。

注意：不同版本的opencode对配置字段的兼容性不太一样，我升级过几次之后遇到过老配置文件里的字段被废弃的情况。配置文件尽量以当前版本的官方文档为准，遇到报错先想想是不是“配置文件里写了旧字段”导致的。

3.2 opencode-go订阅模型怎么选

很多人会看到“opencode go”这个词，其实它指的是一个叫opencode-go的服务/中转渠道，用它可以订阅多个模型，不用自己分别去各大模型服务商开账号、充余额。它的用法跟普通API类似，你把baseURL指向opencode-go提供的地址，再配好它给的API Key，就能在opencode里调用它支持的模型。

选择模型订阅的时候，我建议先问自己一个问题：你主要用opencode来干什么？如果是写业务代码、改脚本、补单测，那选一个“快速且便宜”的模型当默认就够用；如果是跨模块重构、分析老项目架构、让AI做复杂推理，那需要“强推理型”模型。opencode-go的订阅套餐一般会区分模型等级，价格差异也挺大，选错了要么浪费钱，要么跑不动。

我整理了一个选择参考表，直接照着选就行：

另外还要关注模型对“工具调用”（tool calling）的支持。opencode要调用命令行工具、读写文件、操作浏览器，全部依赖模型能正确生成结构化的工具调用指令。如果选的模型工具调用能力弱，你会看到AI答非所问、该执行命令的时候输出一大段解释，体验非常糟糕。

至于“opencode go需要配合ccswitch等工具”这件事，我的理解是：如果你有多个订阅渠道或者多个token要管理，手动改配置文件太麻烦，ccswitch这类工具可以把渠道配置做成可切换的，一条命令就能换。它的本质是帮你管理环境变量或者配置文件里的API Key和baseURL。我这里单独把ccswitch和oh-my-claudecode放在下一节详细说，因为很多人第一次接触都会被这两个名字绕晕。

3.3 ccswitch与oh-my-claudecode怎么配合

ccswitch本来是我在折腾Claude Code时候用到的工具，后来发现它也能配合opencode。它的作用简单说就是：以“配置集”的方式管理不同的API渠道或模型订阅，切换时不用手动改文件。比如你有opencode-go的一个订阅，又有官方API的另一个Key，平时想用哪个就切换哪个。

用ccswitch管理opencode配置的逻辑大概是这样的：先在ccswitch里把每个渠道的baseURL、API Key、模型映射关系配置好，然后通过命令切换到目标渠道，ccswitch会把对应的环境变量或者配置文件内容更新掉，之后启动opencode，它读到的就是你切换后的配置了。

oh-my-claudecode则是另一个方向的工具，最早是用来管理Claude Code的配置模板，后来也支持opencode。它的核心价值是“配置模板化”，比如你想在不同项目里使用不同风格的prompt、不同的技能包，oh-my-claudecode可以帮你把这些配置组织成可复用的模板，避免每个项目从零开始配。

我的建议是：初期不需要上这些工具，先手动把配置文件搞清楚，知道每个字段是干什么的，再考虑用工具简化操作。一上来就依赖工具，出了问题反而不知道是配置文件写错了还是工具切错了，排查难度直接翻倍。

3.4 免费模型与hy3-free下线的影响

有不少人用opencode是为了省API费用，会去折腾各种免费模型渠道。热词里提到的hy3-free就是其中一个常见的免费模型，很多人配置过它，但这类免费模型有个通病：不稳定，今天能用明天可能就404了。我见过不止一次，有人前一天还跑得好好的，第二天所有请求全部报错，原因是免费模型服务下线或者被限流。

如果你依赖免费模型，我的建议只有一条：不要把免费模型当成生产环境主力。你可以用免费模型来做探索性测试、跑简单任务，但日常真正要干活、要接手项目的时候，最好有一个付费模型当兜底。这跟买保险一个道理，你平时可能用不上，但关键时刻没它寸步难行。

还有一点，免费模型的model ID经常变。你在网上看到别人分享的配置，能跑通可能是因为那个model ID刚好还活着，但过一段时间再看，服务商可能已经悄悄改了名字。遇到模型报错，第一步不是怀疑opencode坏了，而是确认这个model ID当前是否还有效。

3.5 “this model is not available in your country”的排查思路

这个报错是很多人在配置新模型时遇到的，看到“country”就以为是网络问题，其实不是。这个错误的核心含义是：模型服务商根据你的API Key所属账户/授权范围，判断当前请求的模型不可用。也就是说，这不是网络通不通的问题，而是“你有没有权限使用这个模型”的问题。

遇到这个报错，按顺序排查四件事。第一，检查model ID是否拼写正确，很多时候是配置文件里多打了空格或者复制的时候丢了字符。第二，检查API Key对应的账户是否真的开通了这个模型的权限，有些服务商把不同模型分开放权，你开了A模型不代表能用B模型。第三，查看服务商的文档，确认这个模型在哪些区域/哪些类型的账户里开放，如果明确不开放，那就换一个可用区域/可用账户下的模型。第四，如果你用的是中转渠道，注意中转渠道的模型列表可能跟官方不完全一致，以渠道商提供的模型ID为准，不要拿官方文档里的ID硬套。

提示：遇到这类涉及“地区/区域”的模型限制报错，最稳妥的做法是回到服务商那边确认授权范围，或者直接换用当前账户可用、文档明确支持的模型。不要试图用任何非常规手段绕过，既不稳定，也容易让API Key被风控。

4. 进阶玩法：Skills、LSP、Playwright

4.1 Skills机制：让AI按团队规范干活

安装好opencode、配好模型，基本的“帮我写代码”已经能跑了。但如果只是这样用，你只是把opencode当成一个高级版ChatGPT，没有发挥出它真正的威力。它的核心进阶能力之一是Skills，中文叫技能包。

Skills本质上是把一组指令、规范、约束写成一个结构化的Markdown文件，放在约定好的目录下，opencode在干活的时候会自动加载并使用它。比如你想让AI在每次生成代码时候遵循你团队的命名规范，你不需要在每次对话里重复粘贴规范，只需要写一个skill，然后告诉opencode“按我的代码规范处理”即可。

技能包的目录一般在~/.config/opencode/skills（全局）或者项目根目录的.opencode/skills（项目级）。每个skill是一个文件夹，里面放一个SKILL.md文件。举一个最简单的例子，我写了一个生成commit message的skill：

--- name: commit-message description: 生成符合团队规范的Git提交信息 --- 当我要求你生成commit message时，请遵循以下规范： 1. 格式：<type>(<scope>): <subject> 2. type必须是feat/fix/docs/style/refactor/test/chore之一 3. subject不超过50个字符，用中文描述 4. 如果有破坏性变更，在正文中用BREAKING CHANGE标注

写完之后，在opencode对话里说“帮我把当前改动生成commit message”，它就会按这个规范来执行。这东西的价值在于，你只要配一次，之后所有AI生成的内容都会自动符合你的工程习惯，而不是每次都靠临场口述。

我做了一个经验总结：Skill不要一开始就写很复杂，先把最高频的三个场景做好——代码规范、提交信息、代码审查。这三个用顺手之后，再慢慢加单元测试规范、文档规范、安全规范等。

4.2 接入LSP提升代码理解能力

LSP（Language Server Protocol，语言服务器协议）是编辑器领域的一项技术，简单理解就是：它能够让工具程序获得“像IDE一样理解代码”的能力——知道一个符号在哪定义、哪里引用了这个变量、某个函数调用有哪些参数、当前文件有没有编译错误。

opencode支持接入LSP，这意味着AI不再是把代码当纯文本“硬读”，而是能利用语言服务器提供语义信息，找到更加准确的代码位置和上下文。比如你让AI“找到这个函数的所有调用点并修改”，有了LSP，它定位的准确度会高很多，不容易漏改、误改。

接入方法通常在配置文件里增加lsp相关配置，以TypeScript项目为例，可以用typescript-language-server。配置思路大致是：

npm install -g typescript-language-server typescript

然后在opencode配置中启用对应的LSP服务。不同版本的配置方式和字段不完全一样，我建议直接查当前版本的文档确认。如果你用的语言是Go，可以用gopls；Python的话可以用pyright或者pylsp。

接入LSP之后，最直观的感受是AI在回答“这个问题在哪些地方出现”“这个改动会影响什么”这类问题的时候，给出的答案不再那么“泛泛而谈”，而是真的能指出具体的文件和行号，改代码时也更有底气。

4.3 用Playwright驱动浏览器修前端bug

前端bug的修复流程，以前效率很低：先在浏览器里手动复现，再看控制台报错，再猜是哪段代码的问题，改完再刷新一遍重新点半天。现在opencode可以借助Playwright，让AI自己打开浏览器、操作页面、收集报错信息，相当于把“手工复现”这个环节自动化了。

实现方式是通过MCP（Model Context Protocol，模型上下文协议）接入Playwright。MCP你可以理解成一个标准化的“工具插槽”，模型通过MCP就能调用外部工具，而Playwright MCP Server就是让模型可以直接控制浏览器的桥梁。

在opencode配置里加入Playwright MCP服务之后，你可以直接给AI下指令，比如：“打开本地开发服务器，访问首页，尝试点击右上角的登录按钮，然后把控制台报错截图发给我”。AI会自己去执行这些步骤，然后根据结果分析问题原因。这个过程听起来很酷，但我必须提醒一句：它不是一个100%稳定的功能，浏览器自动化本来就容易受页面元素变化影响，AI点击不到你要的元素时候会来回尝试，需要你有耐心。

另外，如果你要用这个能力，模型选择很关键。浏览器操作涉及到“多步骤工具调用”，模型必须稳定、准确地生成每一步的指令。用弱模型的话，经常会出现AI自己都不知道自己在干什么的情况，建议至少用一个中等偏上的强模型来驱动这类任务。

5. 编辑器集成与项目实战

5.1 VSCode插件：在编辑器里直接用opencode

终端里的opencode已经很好用了，但很多人还是习惯在VSCode里写代码，长时间切到终端总觉得打断思路。好消息是opencode官方有VSCode插件，装上之后可以直接在编辑器侧边栏打开一个opencode面板，相当于把AI助手嵌进了IDE里。

这个插件的好处是它和当前编辑器打开的文件夹是共享上下文的。你不用在终端里重新cd到项目目录，直接在面板里问AI问题、让它改代码，改动会直接反映在编辑器里。我实际用下来，配合VSCode的diff视图，AI改完代码你可以在编辑器里直接看到变更，再决定是保留还是撤销，比终端里盲改要安全和直观得多。

安装方式直接在VSCode扩展市场搜索opencode即可。需要注意：

• 插件版本跟CLI版本最好保持一致，有时候CLI更新了插件还在旧版，会有API对不上的小问题。
• 如果你已经在终端里启动了opencode，插件会尝试连接，可能会有抢占会话的情况，建议养成习惯，同一时间只在一个端使用。
• 首次使用插件还是要先完成CLI的基本配置，插件本身不负责配置模型。

5.2 JetBrains IDEA插件：Java/Kotlin项目的另一个选择

用JetBrains家族IDE（IDEA、PyCharm、GoLand等）的人，也不用非得切到终端去。opencode同样有JetBrains插件，安装后在IDE侧边栏就能打开对话窗口。这个插件在Java、Kotlin这类重型项目里表现不错，因为IDE本身对这类语言的理解要比通用CLI工具强很多，两下配合起来，AI对项目结构的感知会更准。

不过IDEA插件的成熟度目前还赶不上VSCode插件，偶尔会有配置同步不及时、模型切换不同步的小毛病。我的经验是：把IDEA插件当成“轻量对话入口”用，别指望它把终端版的所有功能都复制过来。遇到插件行为怪异，检查一下插件版本和IDE版本是否兼容。

5.3 用opencode接手老项目的实战流程

接手老项目是所有程序员都怕的事情，尤其是那种没有README、没有注释、依赖关系混乱的“屎山”项目。用opencode接手后，这个流程能变得轻松不少。我的标准执行套路是这样的：

第一步，让AI扫描并概括项目结构。直接对它说：“先遍历项目根目录，分析文件组织方式，告诉我这是什么技术栈、有哪些关键模块、入口文件在哪。”它会读配置文件、目录结构，然后给你输出一份项目概览。

第二步，让AI生成项目文档。基于刚才的扫描结果，让它把项目架构、依赖关系、启动方式整理成一份MARKDOWN文档写进项目里。以后再有人问你项目怎么跑、结构什么样，直接把这份文档甩过去。

第三步，定位关键代码路径。接手项目最怕就是找不到入口、找不到核心逻辑。你可以问AI：“这个项目的认证流程是怎么走的？从登录接口到token校验，把相关文件列出来。”AI会沿着调用链查找，甚至能标出关键函数的位置。

第四步，让AI跑测试并修复失败用例。老项目的测试可能已经挂了很久，让AI先把测试跑一遍，把结果汇总出来，然后一个一个看失败原因。简单的修复AI能直接改，复杂的它会先给你分析报告和建议，你再决定怎么处理。

这个流程走下来，一个陌生项目的上手速度能快一倍不止。但我也要提醒：AI对老项目的理解不是万无一失的，尤其在那些充满“历史包袱”的代码里，它可能忽略掉某些隐藏的全局状态依赖。AI给的建议一定要自己复核一遍，别无脑照单全收。

5.4 opencode、Codex、Claude Code、pi到底选谁

这个问题没有标准答案，但我可以根据自己的使用场景给点参考。如果你平时主要在写Python/TypeScript，项目不是特别庞大，又希望能自由切换模型，那opencode会非常顺手。如果你深度使用某个云厂商的生态，比如一直在用OpenAI或者一直用Anthropic，那直接用对应的官方Agent，省去配置成本，可能会更稳定。

如果你是一个“轻量党”，每次只想快速问一两个问题，不想看到复杂的终端界面，那pi这种极简工具可能更合适。但要注意，极简工具的功能上限一般也低，遇到复杂的、跨文件的改动，它的能力可能会不够用。

我的建议是：不用纠结“哪个最好”，多花一两个小时把两三个工具都装起来，在同一个项目上试一下，哪个让你觉得“沟通不费劲、结果靠得住”，就留哪个。工具是拿来干活的，不是拿来信仰的，适合你手头的工作类型才是第一原则。

6. 常见问题与避坑手册

6.1 高频报错速查表

从安装到使用，我攒了一堆报错处理经验，整理成一个速查表，遇到问题直接对应着看：

遇到报错，先冷静下来判断问题出在哪一层：是opencode本身的安装问题，还是模型配置问题，还是模型服务端问题。不要一上来就重装，排查的顺序应该是先看配置、再看日志、最后才考虑重装。

6.2 三个我踩过的印象最深的坑

第一个坑，配置了不存在的model ID。有一次我从网上抄了一份配置，model字段写的是某个看起来很新的模型名，结果所有请求都返回404。我检查了很久才发现，那个模型只是某个渠道内测时的名字，现在早就下架了。从那以后，我每次改模型配置，都先到服务商文档或渠道商提供的模型列表里确认ID，再往配置文件里填。

第二个坑，多个provider时API Key串了。我同时配了A和B两个provider，结果A模型的请求一直报鉴权失败，查了半天发现是因为我复制配置的时候，把B的API Key填到了A的options里。这种错误特别隐蔽，因为配置文件格式完全合法，要不是逐项核对，根本发现不了。

第三个坑，升级后老skill失效。有一阵opencode版本更新很快，我升级之后发现之前写的好几个skill不生效了，后来一查是skill的格式规范做了调整，旧版frontmatter的字段名不兼容。从那之后我升级前都会先看一眼release notes，特别是涉及配置、skill格式的变更，提前做好准备再动手。

6.3 最后分享一点个人体会

如果让我给刚接触opencode的人一个建议，我会说：先不要急着配一大推东西。第一天就装好、配一个最常用的模型，在真实项目里写几个小任务——让AI改个变量名、写个函数、生成一段测试，先把对话交互的感觉摸透。等你觉得“这东西确实能帮我干活”了，再逐步加Skills、LSP、MCP工具这些进阶能力，一口吃不成胖子，配置堆得越多，出问题时需要排查的范围就越大。

还有一个小技巧，平时让opencode干活的时候，尽量把需求说得具体一点。不要只说“帮我优化这段代码”，而是说“帮我看这个函数的性能瓶颈，目标是把响应时间降下来，不要改变外部行为”。需求越具体，AI输出的结果越接近你想要的样子，返工次数就越少。这大概是所有AI编程工具通用的使用心法。