企业官网建设流程全解析

先交代一个背景：我最近在一台Windows笔记本和一台Linux台式机之间轮着写代码，主力编辑器从纯终端慢慢变成了“终端+AI”。试过不少AI编程工具，Claude Code用过，Codex CLI也装过，最后长期留在工作流里的却是opencode。这个工具在开发者社区里讨论度很高，但很多人的第一印象是“又一个终端AI壳子”，实际上它解决的问题、能折腾出来的玩法，比表面看到的要深不少。

这篇文章我会把opencode从安装、模型接入、配置文件、Skills机制，到IDE插件、Playwright前端Bug排查、以及和Codex、Claude Code、Pi这类同类工具的选型差异，完整过一遍。内容包括我在实际环境里踩过的坑、现在稳定使用的配置方案，以及不适合它的场景。如果你是第一次听说opencode，或者装了之后一直停在“能跑但不会用”的状态，这篇应该能帮你把工具真正串起来。

1. opencode不是又一个ChatGPT壳子：它到底在解决什么问题

先说清楚它是什么。opencode是一个开源的、跑在终端里的AI编程Agent，核心是“帮你在真实项目里干活”，不是“陪你在对话框里聊代码”。它由SST团队维护，代码全开源，底层支持对接Anthropic、OpenAI、Google Gemini、OpenRouter、本地Ollama，以及官方的Go订阅服务。

为什么要关注它，而不是继续用各大厂商的官方CLI？我自己的体会是：官方CLI通常和自家模型深度绑定，换来的是开箱即用和稳定；但代价是你在工具链层面几乎没有选择权。opencode把“模型”和“工具”拆开了——Agent框架归Agent框架，模型通道归模型通道，你可以今天用Claude，明天切GPT，后天换本地模型，命令和会话习惯完全不变。

1.1 终端里的Agent和聊天机器人的差别

很多人第一次跑opencode会有点懵：界面是一个TUI终端程序，底部一个输入框，看起来像聊天，但它的工作方式完全不是问答。

它具备真正的Agent能力：读文件、搜索代码、执行bash命令、编辑多个文件、运行测试，然后根据结果调整下一步动作。比如你可以直接说“帮我把这个模块的重试逻辑抽出来，加上指数退避，并补单元测试”，它会自己读代码、找相关函数、改文件、跑测试，最后把diff展示给你确认。

它的关键能力包括：

• 多文件读写和跨文件重构。
• 执行shell命令并读取结果，比如跑测试、格式化代码、查看git状态。
• 持久的会话管理，不同项目可以并行开多个session，互不干扰。
• 支持配置多种模型通道，随时切换。
• 支持Skills机制，把团队规范、项目特定流程固化成可复用的指令套餐。
• 支持LSP，代码跳转、查找引用这类IDE能力也会被Agent使用。
• 能用Playwright自动跑前端测试来复现Bug。

这些能力组合起来，它更像一个“坐在你旁边的结对工程师”，而不是一个问答机器人。

1.2 为什么我把它放在Claude Code和Codex旁边一起比较

我最早的主力是Claude Code，说实话在Claude模型上的表现确实强，尤其是长上下文理解和代码生成。但我在实际项目中遇到几个很难受的点：

• 模型通道固定，想在Claude和GPT之间切换要换工具。
• 配置和Skills的生态偏封闭，团队想统一规范比较费劲。
• 一旦某个模型版本或API出问题，只能等官方修复。

opencode解决的是“工具链自主性”的问题。它把你和模型厂商解耦：Agent框架本身是开源的，模型可以自由选择，配置可以进版本库，Skills可以随项目走。对需要长期维护多个项目、多个技术栈、多套模型渠道的人来说，这种自由度是实打实的工作效率，不是折腾。

当然，自由也有代价：一切都要自己配置，初期学习成本比开箱即用的官方CLI高。这个扯平之后，我现在的结论是：如果你希望工具跟着项目走而不是跟着某个厂商走，opencode值得成为主力。

2. 安装与Windows “cmdlet无法识别” 的问题全解析

安装本来是最简单的一步，但很多人恰恰就卡在这里。热词里那条opencode: 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名，我猜是搜索量最高的报错之一。这个我太熟了，因为我在Windows上第一次装的时候就踩过。

2.1 最省事的安装方式与版本管理

opencode的安装方式有几种，我整理一下现状：

• macOS/Linux推荐：直接执行官方安装脚本：

curl -fsSL https://opencode.ai/install | bash

• Homebrew用户：

brew install sst/tap/opencode

• npm安装：

npm install -g opencode-ai

• Windows下也可以直接用npm方式或下载官方release的exe文件。

安装完成验证一下：

opencode --version

这里有一个很容易混淆的点：opencode在npm上对应的包名可能是opencode-ai，而不是opencode。如果你执行的是npm install -g opencode，装到的可能是别的东西，最后在终端里敲opencode自然各种报错。装之前先查一下包名，这是最容易被忽略的“隐藏坑”。

关于版本管理，opencode更新很勤，官方CLI自带升级方式，具体可以在终端里执行opencode upgrade。我个人的习惯是每周末统一升一次，因为新版本经常带来Skills和模型通道相关的重要修复。

2.2 cmdlet、PATH和环境变量：一次讲透

回到Windows报错本身。这条报错的含义是：PowerShell在PATH环境变量指定的所有目录里都找不到opencode这个可执行文件。原因通常有三个：

第一个是npm全局安装目录不在PATH里。如果你用npm装的，PowerShell执行的不是opencode，而是opencode.cmd或opencode.ps1，这些文件位于npm的全局bin目录下。你可以用下面命令找到npm全局根目录：

npm prefix -g

然后该目录下的路径（Windows上是%APPDATA%\npm）应该添加到系统PATH里。检查方法：

$env:Path -split ';' | Select-String "npm"

如果没看到，手动把%APPDATA%\npm加进用户环境变量，重开终端即可。

第二个是安装方式冲突。比如之前用脚本装过一次，后来在另一台机器上用scoop或choco装，两个版本串了，而当前终端会话缓存了旧PATH。解决办法是重开终端，或者运行：

refreshenv

第三个是安装包本身没下载完整。Windows Defender或杀毒软件偶尔会把终端工具的exe隔离掉。如果你确认PATH没问题，去安装目录看opencode.exe是否还在，不在就重新解压或重装。

如果你只是想快速临时用一下，不想折腾PATH，可以走npx：

npx opencode-ai

不过这只适合临时验证，长期主力使用还是建议把全局命令配好。

安装完成后，最简单的跑通方式：进入一个项目目录，直接执行opencode。第一次启动通常会引导你配置模型通道（比如设置ANTHROPIC_API_KEY或OPENAI_API_KEY）。不用慌，随便选一个能用的模型，先跑通再慢慢调。

2.3 安装完成后第一件事：跑通一个最小Agent任务

很多新手装完后对着TUI不知道干嘛。我的建议是：不要急着问复杂问题，先做两个最小任务。

第一个，让它读项目结构：

先看一下这个项目的README和目录结构，告诉我这个项目是干什么的、主要用了什么技术栈。

第二个，让它跑一个命令：

帮我运行一下项目里的测试，然后把失败的结果摘要给我。

观察它在终端里是如何拆解任务的：先读文件，再跑命令，再总结。等这一步跑通，说明安装、模型接入、权限配置都正常了，后面再进复杂场景就顺理成章。

3. 模型接入是使用体验的分水岭：从go订阅到ccswitch配置

opencode最大的优点，也是最大的坑，都在模型接入这里。它自由度极高，但如果你不知道怎么选，很容易被各种配置、报错、渠道下线搞得头皮发麻。这一节我详细讲讲模型接入这件事。

3.1 opencode支持哪些模型入口

从大方向说，opencode的模型接入分几个流派：

• 直接配置各大厂商API Key，通过环境变量或配置文件传入。例如Anthropic、OpenAI、Gemini、OpenRouter都支持。
• 本地模型通道，比如Ollama，完全不花钱，离线可用。
• 官方Go订阅服务，这是SST自己在推的聚合订阅方案。
• 社区维护的各种第三方模型通道，这类通常变化最快，稳定性也最看运气。

表面上看，反正都是给工具一个baseURL和API Key。但实际使用中的差异非常大：不同通道的上下文长度、限流策略、可用模型列表、甚至请求格式都可能不一样。opencode本身做了不少兼容工作，但如果你用一个很久没更新的第三方通道，遇到奇怪的报错概率很高。

3.2 go订阅服务和普通API Key的区别

go是opencode生态里的订阅制模型访问方案。简单理解就是：你不需要去Anthropic、OpenAI等平台分别充值、分别管理密钥，而是通过一个统一的订阅套餐，在一个后台里选择和使用多种主流模型，然后在opencode里把它作为模型通道连上。

这种方案熟悉以后你会觉得挺舒服的，因为：

• 计费统一在一个地方，月底看账单不用来回切页面。
• 模型选择比较直观，订阅后可以按需选模型。
• 不需要自己维护多个API Key。

但要注意，go本质上还是一个商业订阅服务，它的可用性、模型列表、配额规则都跟着官方节奏走。热词里像“opencode go订阅模型选择”、“opencode go套餐”、“opencode go需要配合ccswitch等工具”，说明大家实际使用中确实会有切换需求——可能某天某个模型不支持了，或者配额用完了，或者响应速度变化了，这时候你就需要快速切回其他通道。

我的建议是：go可以当默认主力，但不要成为唯一通道。至少留一套备用的API Key或本地模型，关键时刻能救急。

3.3 用ccswitch管理多个供应渠道

ccswitch这个工具在社区里经常和opencode一起出现。它本质上是一个配置切换器，用来管理不同工具、不同模型的配置档案。

实际场景是这样的：我手上有Anthropic的API Key、OpenAI的API Key、go订阅，还有一个Ollama本地模型。如果全靠环境变量，每次切换都要改一堆配置，非常容易出事。用ccswitch可以把每套渠道存成一个profile，比如：

• profileclaude：指向Anthropic，模型用Claude Sonnet。
• profilegpt：指向OpenAI，模型用GPT-4o。
• profilego：指向go订阅，模型用默认推荐。
• profilelocal：指向Ollama。

需要切换时一条命令就搞定。这样即使某个渠道出问题，切到另一个profile就可以继续干活。

有人可能觉得“这不就是改环境变量吗”，但对重度用户来说，频繁切换时的稳定性和可回滚性比手动改配置重要得多。尤其是团队协作时，把profile文件放进dotfiles仓库管理，新机器几分钟就能恢复全套环境。

顺便说一句，社区还有oh-my-claudecode这类Claude Code配置管理框架，也逐步兼容opencode。如果你本来就在用Claude Code，这类框架可以帮你统一管理两个工具的配置，减少重复劳动。

3.4 免费模型与本地模型的实际体验

很多人关心能不能白嫖模型。我的看法很明确：可以玩，但别把核心工作流押在上面。

先说说本地模型。Ollama跑Qwen、Llama这类模型，在代码补全和简单重构上确实能用，完全的离线环境最安全，数据不出机器。但说实话，在复杂项目理解、多文件重构、长上下文保持上，本地模型和主流云模型差距还是很明显的。我一般把Ollama用作：

• 断网环境下的备用通道。
• 不想把代码发给第三方时的保密通道。
• 简单脚本、单文件修改等轻量任务。

社区免费模型通道，比如前面热词里提到的hy3-free这类渠道，属于“短暂热闹”的典型。这类通道通常由个人或小团队提供，免费是因为烧钱换推广或测试，一旦成本扛不住就下线。我的经验是：免费通道适合做模型评测、玩新特性的尝鲜环境，不适合作为日常工作依赖。哪天打开终端发现通道挂了，你手头写到一半的任务就很尴尬。

所以结论很直接：主力用稳定付费通道，备用一套API Key，防守底牌留一个本地模型。这样无论上面哪一层出问题，你都能继续干活。

4. opencode.json配置：Skills、LSP、权限与项目接手的底层逻辑

opencode拥有强大能力的同时也带来一个必然的要求：学会配置它。好在它的配置思路很清晰，核心就一个opencode.json文件，项目根目录放一份，全局也可以放一份做兜底。

4.1 一个能直接上手的opencode.json

拿一个参考配置来说：

{ "$schema": "https://opencode.ai/config.json", "provider": { "default": "anthropic" }, "model": "claude-sonnet-4-5", "permissions": { "edit": "allow", "bash": "ask", "webfetch": "allow" }, "skills": [ "frontend-review", "commit-message" ], "instructions": "这是一个前后端分离项目。前端是React+TypeScript，后端是Go。修改前端代码前先检查是否有对应的组件测试。" }

这里的核心是permissions。opencode的Agent能执行shell命令，但默认不会让它为所欲为。你可以设置：

• edit：是否允许直接改文件。
• bash：是否允许执行命令。
• webfetch：是否允许抓取网页内容。
• 每个都可以是allow（自动允许）、deny（禁止）、ask（每次询问）。

个人建议：全局配置里把bash设为ask，防止Agent顺手执行高风险命令；在明确可信的项目里再放宽容限。因为Agent的执行逻辑再强，也保不齐某个命令的副作用超出预期。

4.2 Skills机制：让AI学会你项目里的特定工作流

Skills是opencode里我认为最值得投入的功能，也是很多人在热词里反复搜opencode skills的原因。它的思路其实特别朴素：把某类任务的做法写成一份Markdown文档，告诉Agent“遇到这类情况时，按这个流程来做”。

Skill的组织方式是一个目录，里面放一个SKILL.md文件，带元信息和正文。例如我在一个前端项目里建了一个frontend-review技能：

--- name: frontend-review description: 对前端组件进行代码审查，重点检查状态管理和副作用。 when_to_use: 当用户要求审查前端组件或定位前端Bug时 --- 1. 先找到目标组件所在文件。 2. 找出它的props、state、effect依赖。 3. 检查是否有内存泄漏风险。 4. 给出简洁的结论，按严重程度排序。

有了这个Skill之后，Agent碰到前端审查任务就会自动加载这个流程。它不会问你要不要用，而是根据描述里的触发条件自动匹配。

这带来的价值是：团队经验可以被固化。新成员接手项目，只要仓库里有这些Skills文档，AI的默认行为就会符合团队规范。这比写几千字的开发文档更有实操意义，因为AI是真正会去执行这些步骤的。

我强烈建议每个项目都花半小时沉淀几个核心Skills：代码审查、提交信息规范、测试执行顺序、部署检查清单。这半小时的投入回报率极高。

4.3 LSP接入：跳转定义与引用查找让AI更像“读懂了代码”

LSP是另一个容易被忽略的功能。简单说，LSP就是让编辑器拥有语言智能的协议。opencode接入LSP之后，Agent在执行跳到定义、查找引用这类操作时，不是靠字符串搜索，而是靠语言的语法分析结果。

这意味着什么？比如你说“把loadUser的所有调用处都检查一遍”，Agent会通过LSP精确找到所有引用位置，而不是靠正则去匹配可能漏掉的地方。对于TypeScript、Python、Go这类强类型语言，LSP能大幅提升改代码时的安全性。

配置上，opencode会尝试启动项目对应语言的LSP Server。例如TypeScript项目需要安装typescript-language-server，Go项目需要gopls。我的做法是：在开发环境里统一把这些常用LSP装好，这样无论哪个项目用opencode都能自动享受语言智能。如果你发现Agent在分析代码时总说“找不到某个符号的定义”，优先检查对应LSP Server是否安装成功。

4.4 接手陌生开发项目时的实际工作流

热词里有“opencode接手开发项目”，这个场景我实测过很多次，效果确实不错。之前接手一个遗留项目，代码量中等偏大，文档匮乏，按传统方式光读代码可能就要一两天。用opencode之后流程变成这样：

第一步，让它读仓库：

先读完README和项目配置文件，告诉我这个项目的架构、核心业务流程、入口文件在哪里。

第二步，用LSP和代码检索梳理调用链：

找到用户鉴权模块的入口，然后追踪一次登录请求从HTTP路由到数据库的完整调用链。

第三步，针对具体任务修改代码。因为前面已经建立了上下文，Agent能比较准确地知道改哪里、怎么改。

这套流程下来，我在半天内就摸清了项目的主干结构，并且产出了可执行的修改方案。对需要快速进入陌生项目的开发者来说，这个场景是实打实的高价值用法。

5. 离开终端之后：VS Code、JetBrains与Desktop版的真实覆盖度

opencode是终端工具，但终端的边界感对部分人来说太强了。热词里大量出现opencode vscode、opencode jetbrains idea 插件和opencode desktop，说明很多人需要更图形化的交互方式。这块目前的生态怎么样？我说下实际体验。

5.1 VS Code插件：把terminal会话搬进编辑器

官方VS Code插件解决的核心痛点是“上下文割裂”。在纯终端里，Agent看到的是文件内容，但你编辑器里打开的标签页、当前选中的代码、光标位置它不一定清楚。装了插件后，可以直接把VS Code里的选中代码、当前文件路径、甚至错误面板内容发送给opencode会话。

我常用的一个流程是：

• 在代码里选中一段有问题的代码。
• 右键选择发送到opencode。
• Agent自动读取相关文件，给出修改建议或直接生成diff。

这比“复制粘贴到终端”自然多了。而且插件在编辑器里可以直接展示Agent生成的改动，配合diff视图查看，体验上接近Cursor这类内置AI的工具。

但从覆盖度来说，VS Code插件目前更像一个前端入口，真正复杂的会话管理、Skills调试还在终端里。我的建议是：日常小需求用插件，大任务还是在终端里跑，两个配合使用。

5.2 JetBrains IDEA插件与Desktop应用

JetBrains的插件生态没有VS Code那边成熟，但已经有了可用的IDEA插件。它能做的核心事情也类似：把编辑器选中的内容、当前上下文发给opencode，或者在IDE里打开一个opencode面板。对用IDEA为主的人来说，至少不用为了用opencode专门切到终端。

Desktop版是另一个值得关注的方向。它的思路是把TUI终端应用包装成桌面应用，对不习惯终端操作的人来说友好很多。有了Desktop之后可以看到会话列表、文件改动对比、模型切换变得更直观。不过Desktop版的迭代节奏和功能完整性，还需要一段时间才能追上CLI版。我目前的定位是：CLI是主力，Desktop是演示和给新手的友好入口。

6. 用Playwright测前端Bug：让Agent自己动浏览器

前面说了不少“改代码”的场景，但opencode还有一个让我觉得特别值的能力：自动用Playwright复现前端Bug。热词里“opencode playwright怎么测试前端bug”的搜索量很高，我实际跑通过，这里把完整思路分享出来。

6.1 手把手搭一条“复现Bug”流程

我最常用的做法不是在会话里临时敲一堆命令，而是把它做成一个Skill。原因很简单：临时让Agent写Playwright脚本，每次都要重新交代项目路径、启动方式、测试范围；做成Skill之后，一条命令就直接执行标准复现流程。

Skill大致长这样：当用户反馈某个前端Bug时，Agent先看项目里有没有现成的Playwright环境；没有就先安装并初始化一个最小配置。然后根据Bug描述写一个复现测试脚本，操作步骤尽量忠实还原用户路径，打开页面、点击按钮、输入表单、监听console错误。跑完以后把截图和console输出带回来，让用户确认这对不对得上。

我第一次实测的场景是一个数据表格的筛选异常。我告诉它：

筛选条件选择“已完成”时，表格仍然会显示一条“待处理”的数据。请用Playwright复现这个问题。

它的执行路径大概是：

1. 读到项目启动脚本和前端路由。
2. 启动本地开发服务器。
3. 用Playwright打开页面，设置筛选条件。
4. 截取表格数据，发现确实多了一条不该出现的数据。
5. 把console的错误信息一并带回。

整个复现链路跑完大概几分钟，比我手动点要快得多。

6.2 实测效果与边界

这个能力最爽的一点是：Agent能帮你把“模糊的问题描述”变成“可验证的失败步骤”，这本身就是Debug工作的第一步。有了稳定的复现路径，后续让Agent修复时也更容易验证结果：直接再跑一遍测试，看它还挂不挂。

但边界也很清楚。以下几个场景我不建议依赖Agent跑Playwright：

• 视觉类回归问题，比如“这个按钮颜色不对”，这类像素级问题它判断不准。
• 依赖登录态和复杂账号数据的场景，需要你先mock好了再让它跑。
• 页面性能类问题，结果波动大，复现链路也不稳定。

Playwright集成更适合“可描述的交互逻辑Bug”，不适合“纯视觉主观问题”。把它的适用边界想清楚，用起来才不会失望。

7. 选型血泪账：opencode、Codex、Claude Code、Pi的差异化对比

用了这么多Agent工具，经常有人问我到底选哪个。这个问题没有标准答案，但可以分享一套自己的判断框架。热词里“opencode codex claude code哪个agent好用”“opencode codex pi哪个agent好用”其实问的就是这个。

7.1 四款工具脾气对比

直接上结论：

单看“谁能干更多活”是不准确的，因为工具的能力上限受限于模型质量，而模型质量又和你的渠道选择强相关。opencode之所以在我的主力位置上，是因为它能用最好的模型（不管这个模型是哪家的），同时保留我的工具使用习惯。

7.2 我现在的分工策略

说得具体一点，我现在大致的分工是这样的：

• 复杂重构、跨文件大改动、新功能开发，用opencode配Claude系列模型，因为它的Agent能力和长上下文在交互式开发中最稳。
• 需要和GitHub联动紧密的PR总结、Issue分析，偶尔用Codex CLI，因为它在OpenAI生态里确实顺手。
• 简单的、模式固定的运维脚本、构建优化，偶尔用Pi这类偏自动化的Agent去跑，懒得开一个超长交互会话。
• 需要绝对保密、不能出内网的任务，opencode配Ollama本地模型兜底。

这套策略的核心逻辑很简单：不要把鸡蛋放在一个篮子里，但也不要同时用五个工具做同一件事。选一个主力，其他做备用场景，这样效率最高。

8. 高频报错排查：从server error、地区限制到免费模型下线

最后这一节，我把搜索热词里出现频率最高的几个opencode报错和问题集中梳理一下。这些基本都是我在真实环境里遇到、或者帮别人排查过的，照着检查通常能解决。

8.1 unexpected server error，先查哪三个地方

opencode error: unexpected server error. check server logs是热词里排名很靠前的报错。这个提示比较笼统，我第一次遇到也很懵。排查思路，我建议按以下顺序：

第一，确定是哪个环节报错。如果使用go订阅或第三方通道，大概率是远端模型服务返回异常，而不是你的本地配置问题。先看看同网络的普通请求能不能正常访问该服务，排除网络连通性。

第二，看本地日志。opencode会把运行日志写到本地，具体位置因版本和系统而异，在终端里执行opencode --print-logs可以拉起调试日志。重点看有没有请求超时、权限拒绝、baseURL拼错这类线索。

第三，检查配置文件里的baseURL和API Key。很多人会在配置里自定义baseURL，指向某个中转或代理服务。如果这个服务本身不稳，或者Key过期了，就会出现“服务端错误”这种看似高深、实则普通的报错。切回官方默认通道再试一次，是最快的判断方法。

8.2 “model is not available in your country”到底是谁的限制

热词里有一条很具体的报错：this model is not available in your country。这个报错经常出现在使用某些跨国模型服务时。

这个限制是模型提供方根据你的访问来源IP做的区域授权控制，不是opencode本身的功能限制，也不是你的电脑有什么问题。它的本意是服务商只在特定地区提供该模型，你的请求来源不在授权范围内，所以被拒绝了。

面对这种问题，最关键的一点是：不要试图去改opencode配置来解决。它根本不在你的客户端控制范围内。现实可行的做法就两条：换一个在当前地区可用的模型通道，或者调整使用策略。比如这个模型不行，切到另一个服务商提供的同级别模型，一样能完成任务。把这当成一种“模型选址”问题来解决，而不是技术问题来硬刚。

8.3 免费模型通道下线，别把核心工作流绑在上面

免费模型通道的存续问题，前面已经提过一嘴。热词里“opencode hy3-free下线了吗”说明很多人一直在用某个免费模型通道，直到它突然某天挂掉才来找答案。

我的经验是：凡是免费的公共模型通道，你都要默认它有随时下线的风险。这种通道通常由个人或社区提供，算力成本持续消耗的情况下，很难长期免费。一旦下线，你的对话记录里全是“连接失败”，这时候才想起来配备用方案，就非常被动。

所以不要问“它下线了吗”，而要问“如果它下线了，我的工作流还有没有Plan B”。这也是为什么我在第三章强调保底方案的原因。

8.4 Linux改JSON配置的一个高发错误

最后提一个Linux下的典型问题：手动修改opencode.json后工具报配置解析错误。大多是因为手写JSON时留下了注释或尾逗号。JSON标准格式不允许注释，但很多人从JSONC的习惯带过来，顺手写了//注释，结果工具直接罢工。

解决方案很简单：

• 用支持JSON Schema的编辑器（VS Code配官方schema）编辑配置文件，让校验器帮你抓错误。
• 改完以后用python -m json.tool opencode.json快速校验。
• 大型项目可以把配置拆成全局和项目两份，全局放公共逻辑，项目里只放覆盖项。

还有一个细节：项目根目录的配置文件默认只对当前项目生效。如果你发现配置改了没生效，先确认文件放的位置对不对，再确认没有拼写错误。这类“配置不生效”问题，九成是路径或字段名的问题。

前面这些都是我实际踩过或者帮别人排查过的坑。工具越灵活，需要自己负责的边界就越大，opencode尤其如此。但换个角度看，正是这种“自己掌控一切”的灵活性，让我愿意长期把它留在工具链的核心位置。希望这篇文章能帮你少走一些弯路，把opencode真正用起来。