敢直接在终端里敲opencode的人多半已经在 Claude Code、Codex CLI 里面折腾过一圈。我第一次在 Windows PowerShell 里敲完这个命令屏幕直接甩回来一句“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名”那一刻我就知道这又是一款需要从头驯服的 AI 编程 agent。严格来说opencode 是一个开源、跑在终端里的 AI 编程 agent重点落在“开源”和“终端”这两个词上。它不像 Cursor 那样是一个完整 IDE也不像 Copilot 那样嵌在编辑器侧边栏它和 Claude Code 更接近——你在命令行里描述需求它自己读代码、改文件、跑测试、提交 Git。区别是 opencode 本身不绑定任何一家模型厂商Claude、GPT、Gemini、本地模型都能接进来。如果你已经受够了单个厂商的额度限制想找一套配置可控、模型自选、数据落在本地的方案这篇文章基本就是为你准备的。我会按实际使用顺序来写先讲清楚它解决了什么问题再把安装和初始化完整走一遍接着聊模型接入、日常操作、skills 与 Playwright、编辑器插件最后把我踩过的高频报错和排错思路整理出来。内容偏实操命令和配置可以直接抄。1. opencode 是什么它凭什么从 Claude Code 手里抢用户1.1 定位对比opencode、codex、claude code 到底哪不一样很多人在搜 opencode 的时候会同时看到 Codex CLI、Claude Code、Gemini CLI 这些名字因为大家解决的是同一类问题让 AI agent 在终端里直接操作代码库。但它们的定位差别其实挺大维度opencodeClaude CodeCodex CLI开源情况开源社区版本免费闭源开源模型绑定不绑定可配置多家模型主要绑定 Anthropic主要面向 OpenAI可扩展交互界面TUI终端图形界面TUITUISkills 技能支持基于 SKILL.md支持插件体系偏实验LSP 支持内置 LSP 客户端支持有限配置方式opencode.json 环境变量配置文件 命令config.toml插件/编辑器集成VSCode、JetBrains官方生态较全较新我自己从 Claude Code 切到 opencode 的核心原因就一个模型自由。Claude Code 体验再好底层默认绑定 Anthropic 的模型有时候你想在同样的流程里试一下其他模型就要绕很多弯。而 opencode 的配置思路是“工具和模型解耦”——agent 框架是固定的模型随便换。这种设计对于经常在不同项目里用不同模型的人来说非常舒服。另外opencode 的社区迭代速度非常快。原来用 TypeScript 写后来团队直接重写成了 Go启动速度和内存占用都提升明显。后面细说。1.2 opencode go用 Go 重写之后到底强在哪“opencode go”这个说法在社区里出现频率很高但很多人会误解成某个叫“go”的订阅套餐。其实它指的是 opencode 的 Go 语言版本。早期版本基于 Node.js/TypeScript安装以后依赖一堆 npm 包跑起来还要等 Node 进程预热。后来团队决定重写目标很明确——做成一个交付即用的原生可执行文件。重写完成之后的 opencode 直接给你编译好的二进制单文件分发没有 node_modules启动速度基本是秒开。实际体验下来体感差异最明显的是两个场景在 CI/SSH 远程机器上使用。以前还要确保目标机器有 Node 环境现在直接丢一个 binary 进去就能跑省了很多环境问题。长时间会话下的内存占用。Node 版跑大项目agent 上下文一多内存动不动几百 MBGo 版本明显更稳日常会话基本在一百多 MB 以内。另外新版安装脚本也更简单了。只要执行官方的一行命令它会自动判断系统和架构下载对应的二进制到你本机目录。这一点对新手很友好。1.3 TUI 界面第一次打开别慌opencode 的界面是典型的 TUITerminal User Interface终端图形界面。我第一次打开的时候面对满屏的分栏有点懵但用熟之后觉得它比纯 CLI 强太多——因为它始终在告诉你“当前 agent 正在做什么”。大致布局可以这样理解左侧是会话历史列表方便在不同任务之间切换。中间是对话区模型输出、工具调用、命令执行结果都会流式显示出来。底部是输入框支持普通文字输入也支持以/开头的斜杠命令。常用命令我建议先记这几个/help查看内置命令列表包括 /models、/sessions、/init 等相当于所有文档的入口。/models查看当前配置了哪些模型可以直接切换。/sessions查看历史会话列表回过去找之前某个任务。/undo撤销 agent 最近一步操作这个比 CtrlZ 更精确它撤销的是 agent 层面的文件变更。Esc或CtrlC中断当前输出注意不会马上终止整个进程通常会进入“是否确认停止”的状态。TUI 存在的意义不是花哨而是让你在 agent 自动操作文件、跑命令的时候有足够的可控感。你永远看得到它下一步要干什么再决定是放行还是打断。这也是我后来更愿意在终端里用 agent 而不是在网页编辑器里拖拽的原因。2. 安装与初始化把 opencode 跑起来的第一步2.1 三条安装路线curl、npm、brew 怎么选opencode 官方提供了几种安装方式选择主要看你平时习惯用哪个包管理器。安装方式命令/做法适合场景官方脚本curl -fsSL https://opencode.ai/install | bash通用各平台都行装到~/.opencode/binnpmnpm install -g opencode-ai已有 Node 环境Windows 上比较方便Homebrewbrew install sst/tap/opencodemacOS 用户升级方便手动下载GitHub Releases 里拿二进制离线环境、CI 镜像我个人的建议是macOS 用 brewLinux 和 Windows 优先用官方脚本Windows 上如果不想折腾 bash直接 npm 也可以。这里要说一个从热搜词里就能看出的高频问题很多人执行完官方安装脚本后在 PowerShell 里运行opencode报“无法识别”。这是 Windows 下 PATH 环境变量的经典坑我下面展开讲。2.2 报错“无法将 opencode 项识别为 cmdlet”的完整排查链路这个报错的完整文本是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写如果存在路径请确保路径正确然后再试一次。出现这个错误本质是 PowerShell 在环境变量 PATH 所列目录里找不到opencode.exe这个可执行文件。但为什么明明“装好了”却找不到我踩过之后梳理了几个常见原因原因 1安装脚本只写入了当前 shell 的 PATH没有写进系统环境变量。官方脚本或 npm 在安装结束后通常会提示“please restart your terminal”或者直接修改当前 shell 的配置文件。如果你用的终端会话是在安装之前就打开的PATH 不会自动刷新。第一步永远是重开一个终端窗口再试。原因 2npm 全局目录不在 PATH 里。在 Windows 上npm 全局安装的包通常放在%APPDATA%\npm目录。这个目录默认是在 PATH 里的但如果你装过多个 Node 版本nvm-windows、fnm 等PATH 被改来改去可能就丢了。可以用下面命令确认npm prefix -g它会输出 npm 全局目录的真实位置。然后你手动把这个目录加进 PATH 即可。原因 3安装工具并不是装到了 Windows 本机而是装进了 WSL。如果你是在 WSL 的 bash 里执行的安装命令那opencode只存在于 WSL 内部。外面 Windows 的 PowerShell 是完全独立的另一个系统当然找不到。这种情况你需要在 WSL 终端里使用或者在 Windows 侧重新装一份。排查路径我整理成一套可复现步骤先确认安装产物是否真的存在。官方脚本默认装到~/.opencode/bin在 PowerShell 里检查Test-Path $env:USERPROFILE\.opencode\bin\opencode.exe如果文件存在手动将这个目录加入用户 PATHsetx PATH $env:USERPROFILE\.opencode\bin;$env:PATH提示setx有 PATH 长度上限通常是 1024 字符如果 PATH 已经很长可能会截断。更稳妥的做法是通过“系统属性 - 环境变量”图形界面编辑避免破坏已有路径。重开终端验证opencode --version这套排查流程不仅适用于 opencode你以后装任何命令行工具遇到“cmdlet 无法识别”都可以套用先确认文件在不在再确认目录在不在 PATH最后刷新终端三步定位。2.3 首次启动登录选模型还是直接填 API Key安装好之后直接在终端输入opencode首次启动会进入模型接入引导。新版后台会让你选择 Provider然后跳转浏览器完成登录或者让你粘贴 API Key。如果你不想每次都被引导打断更推荐直接用环境变量配置export ANTHROPIC_API_KEYsk-ant-... export OPENAI_API_KEYsk-... export GEMINI_API_KEY...Windows PowerShell 里对应写法$env:ANTHROPIC_API_KEYsk-ant-...配置完成后opencode 会把凭据保存在本机配置目录macOS/Linux 是~/.config/opencode/Windows 是%USERPROFILE%\.config\opencode\不需要每次都输入。如果你同时配置了多家模型的 Key启动后用/models命令就能看到所有可用模型直接用方向键切换。2.4 验证环境几行命令快速自检我的习惯是装完任何工具都先跑一遍自检流程能省掉后面排查的一堆时间。opencode 的自检包括opencode --version # 版本是否正常 opencode run Reply with OK # 非交互式跑一个最简单的任务第二条命令很有意思它不启动 TUI而是直接以单次任务模式运行。如果它能输出OK说明安装、PATH、API Key、模型服务整条链路都是通的。我强烈建议你在完全打开 TUI 之前先跑这一条因为一旦进 TUI如果模型服务有问题界面卡在那里报错信息反而不如命令行直观。3. 模型接入与选择同一个任务不同模型差距有多大3.1 官方支持的供应商与接入方式opencode 模型接入的设计思路很开放我总结下来有四类第一类官方直连供应商。Anthropic、OpenAI、Google Gemini 都支持只要设置对应的环境变量 Key 就能用。第二类本地模型。通过 Ollama 等本地推理服务接入。配置好 Ollama 地址默认http://localhost:11434opencode 就能识别本机已经拉取的模型列表。好处是数据完全不出本机而且没有按量计费。第三类OpenAI-compatible 兼容端点。这应该是 opencode 最强大的能力之一。只要某个模型服务提供了兼容 OpenAI 接口格式的 API你就能把它配进 opencode 当模型用。配置方式是在opencode.json里的 provider 字段指定baseURL和模型名。第四类社区维护的 Provider 列表。opencode 社区沉淀了一批现成的 provider 配置模板你在/models里能看到不少选项选中的时候它会自动填入默认配置。3.2 实测建议重活、轻活、免费活别混在一起我自己用下来的一个核心体会是不要指望一个模型解决所有问题。opencode 的价值恰恰在于切换模型足够简单这让我可以按任务类型灵活选择。任务类型我的选择原因跨模块重构、写测试、复杂 bug 排查旗舰模型Claude 系列 / GPT 顶配需要较强的推理和长上下文理解单文件小改动、格式化、解释代码中端模型或开源模型速度更快成本更低简单的问答、日志分析本地模型Qwen、Llama 较小尺寸省成本、数据安全、零延迟等待这里有个很现实的点旗舰模型虽然强但在大规模项目里反复读文件、改几十处代码的时候token 消耗是肉眼可见的。把“重活”和“轻活”分开能明显降低账单。3.3 配合 CCSwitch 管理多套 Key 和端点很多人的 Key 不是只有一家的项目 A 用官方账号项目 B 用公司共享账号还有本地测试用的端点。每次切换都要改环境变量非常烦。社区里有个开源小工具叫 CCSwitch就是专门解决这个问题的。CCSwitch 的使用逻辑很简单打开工具选择你要切换的对象是 Claude Code 还是 opencode。在里面维护多套供应商配置每套包含名称、BaseURL、API Key、默认模型。一键切换到某个配置它会把对应参数写入 opencode 的配置文件或环境变量。重新打开 opencode 就生效了。在我看来opencode 本身就支持 provider 配置所以 CCSwitch 不是必需品但如果你同时维护很多套 Key它确实能把“改配置”这个动作从每分钟变成一秒。特别是调试模型服务出问题的时候快速切换备用端点能节省大量时间。3.4 免费模型和订阅方案怎么选才不坑热搜里“opencode 免费模型”这个词热度很高我的建议是免费的本地模型比如 Ollama 拉下来的开源模型非常适合拿来跑通流程。你第一次用 opencode 不知道命令怎么玩、TUI 怎么操作用本地模型当“陪练”完全够用而且不用花一分钱。我一开始就是用本地模型学会了 skills 的写法。但真正进入生产环境干活免费模型和旗舰模型的差距还是很明显。最典型的区别是长任务稳定性旗舰模型能持续记住你最初定下的目标而免费/小模型经常干到一半“忘记”任务背景开始自作主张改一些不该改的文件。这种返工成本往往比省下的那点 API 费用高得多。如果需要订阅付费方案建议先跑两个星期免费/按量付费看自己的 token 消耗量级再决定。我见过太多人一上来就订阅最高档结果每个月实际用量连十分之一都不到。4. 日常开发工作流从改 bug 到跨文件重构4.1 第一个真实任务修复一个失败的测试前面铺垫了这么多终于到真正干活的部分。我在一个新项目里第一次用 opencode 修 bug 的场景还挺有代表性项目里有个 Python 测试文件test_auth.py其中一个用例test_login_failure跑挂了。报错信息说断言失败但我一时看不出是前端传参问题还是后端逻辑问题。我直接在 opencode 里输入看一下 tests/test_auth.py 里 test_login_failure 为什么失败帮我修复它然后运行 pytest tests/test_auth.py -k test_login_failure 验证。注意最后那句“跑什么命令算验证通过”很重要这是给 agent 一个明确的验收标准。opencode 收到任务后的动作是读取测试文件。追踪被测试的login函数。发现是异常场景下error_code字段拼写错误。修改源码。运行我指定的 pytest 命令。输出测试通过的结果并说明原因。整个过程里它每跑一个命令之前都会在 TUI 里显示出来我可以选择放行或中断。这种“人审阅、agent 执行”的节奏是我认为 AI 编程 agent 最正确的用法——不是全自动放任也不是纯手动而是人在关键节点把关。4.2 多文件改动、批量重构和 Git 提交的节奏当任务从“修一个测试”升级到“重构整个模块”时要格外注意节奏控制。我总结了两个原则原则一用显式边界约束改动范围。比如你要重构src/services下的请求封装prompt 里要写明“只动 src/services 目录下的文件不要改其他目录”。不然 agent 很可能为了“让逻辑更一致”顺手把调用方也改了diff 范围瞬间失控。原则二把改代码和提交 Git 分成两步。我见过一些配置默认让 agent 自己 commit这在简单项目里没问题但复杂项目里它的 commit message 经常写得过于笼统。我的习惯是第一阶段 prompt让 agent 改代码但明确要求“不要提交”。人工执行git diff审查改动。第二阶段 prompt让 agent “根据当前 diff 写一个规范 commit message然后执行 git add git commit”。如果项目有 pre-commit hook让它跑完以后自动修正 lint 问题。这套节奏既保留了 agent 的高效也保住了代码审查的底线。4.3 上下文工程哪些文件该塞给它哪些不要opencode 默认会读取你当前项目结构但它不是每时每刻都在读所有文件。真正决定 agent “懂不懂你的项目”的是你给了它什么上下文。我总结了一个经验公式精确指定 ignore 排除 让它自由探索。具体来讲在 prompt 里用文件路径的方式直接指定关键文件比如src/config.ts 里导出的 CONFIG 对象字段有哪些。在.opencodeignore或者配置里排除node_modules、dist、build、vendor这些非源码目录防止 agent 在无关文件上消耗上下文窗口。开场先给一句话项目背景“这是一个 Next.js 14 项目接口层在 src/api数据库模型在 prisma/schema.prisma。” agent 有了地图探索效率会高很多。为什么这段重要因为 agent 的上下文窗口是有限的。当对话越来越长窗口越满它“忘事”的概率就越高。如果你一上来就丢了几十万 token让它在垃圾信息里找重点任务就已经失败一半了。4.4 LSP让 agent 不只是“读代码”而是真正“理解代码”很多人把 LSP 理解成“编辑器的跳转功能”但在 opencode 里LSP 是让 agent 更聪明地改代码的关键。LSPLanguage Server Protocol语言服务器协议的价值在于它能给 agent 提供语义层面的信息比如某个函数在哪里定义、哪些地方引用了它、当前类型是否匹配。没有 LSPagent 只能靠正则和文本相似度去猜有了 LSP它改完函数签名之后能自动感知哪些调用点需要一起修。我遇到过最典型的一个场景重构一个 TypeScript 接口字段名。如果没有 LSPagent 可能只改了接口定义本身把所有调用点漏掉配置了 LSP 之后它在命令行里输出“检测到 12 处引用需要同步更新”然后逐一处理。在opencode.json里可以自定义 LSP 服务器地址。常用的有TypeScript / JavaScripttypescript-language-serverPythonpyright-langserverGogopls配置方法是在配置文件的lsp字段里指定命令。需要注意首次启动 LSP 会扫描项目建立索引大规模项目会有点吃内存不用的时候可以关掉对应语言的 server用到再开。5. skills 和 Playwright给 opencode 加“技能”和前端调试能力5.1 skills 机制一个 SKILL.md 到底长什么样skills 是 opencode 的一个核心扩展机制。你可以把它理解成“给 agent 预装的一套操作手册”当它遇到某种类型的任务时会自动加载对应手册按里面的步骤执行。一个 skill 本质上就是一个带特定结构的 Markdown 文件放在规定目录下.opencode/skills/skill-name/SKILL.md内容结构长这样--- name: code-review description: 在提交代码前对当前改动进行审查检查潜在 bug、安全隐患和性能问题。 --- # Code Review 当用户说“review”“审查代码”“提交前检查”时执行以下步骤 1. 运行 git diff查看当前工作区改动。 2. 逐文件检查 - 是否存在未处理的异常 - 是否引入安全风险如 SQL 注入、XSS - 是否有明显性能问题 3. 输出审查结论给出修改建议但不要直接改代码。这里的核心是description字段。agent 会基于它对用户输入进行意图匹配如果 description 写得太模糊比如“处理代码问题”它反而不知道该什么时候触发。写清楚触发场景和触发词skill 才实用。5.2 写一个项目专属 skill从需求到生效举一个实际例子。我有个前端项目经常需要排查页面渲染问题于是我写了一个 skill让 opencode 一遇到“页面怎么坏了”“帮我看看这个前端 bug”就自动走一套固定流程--- name: frontend-debug description: 排查前端页面 bug 时使用。包括启动本地服务、用 Playwright 打开页面、查看浏览器 console 错误、定位问题文件。 --- # Frontend Bug Debug 当用户报告前端 bug 或请求检查页面时 1. 确认本地开发服务是否已启动未启动则先运行 npm run dev。 2. 用 Playwright 打开对应页面 URL。 3. 等待页面加载获取 console 日志和 network 错误。 4. 截图保存到 /tmp/debug-screenshot.png并把截图路径告诉用户。 5. 根据错误堆栈定位源码文件分析原因后给出修复建议。这样写完之后skill 文件放进项目的.opencode/skills/目录并提交到 Git。团队其他人克隆项目之后也自动拥有这个能力。5.3 用 Playwright 复现前端 bug 的完整链路我自己用 opencode 加 Playwright 排查过一个很典型的“按钮点击无反应”问题整个过程让我对前端自动化调试信心大增。当时页面里有个登录按钮点击后完全没反应Console 里也不报错从静态代码上很难一眼看出问题。opencode 配合 Playwright 的处理链路是启动本地开发服务器。用 Playwright 打开页面。自动点击那个登录按钮。打印 console 日志和 network 请求列表。发现点击事件里调用了window.handleLogin()但这个函数在某个脚本加载失败后没有被定义。定位到脚本引入顺序的问题修复后重新跑一遍验证。整个过程里最花时间的反而不是 agent 的操作而是它每执行一步都要和我确认。如果你确认任务风险不高可以在配置里允许它自动执行部分命令效率会高很多。需要注意 Playwright 本身需要安装浏览器运行环境。在服务器或 CI 里跑的时候要设置 headless 模式避免因为没有图形界面而启动失败。5.4 skill 没生效的常见原因我遇到过几次写好了 skill 但 agent 完全无视的情况总结下来主要是这几个原因文件名或目录位置不对。必须是.opencode/skills/名称/SKILL.md直接放SKILL.md在根目录不生效。description 写得太泛。agent 匹配意图的时候需要足够明确的触发条件。改完 skill 没重启会话。对话进行中修改 skill 文件当前会话不会自动加载需要开启新会话。项目里配置了 ignore 规则把 skills 目录排除了。检查一下.opencodeignore内容。6. 编辑器集成VSCode 和 IDEA 里的 opencode6.1 VSCode 插件和终端里的 opencode 是什么关系很多人的第一反应是问VSCode 里的 opencode 插件是不是另一个工具其实不是它本质上是终端版 opencode 的“可视化远程控制台”。安装官方扩展后VSCode 侧边栏会出现 opencode 面板。它会连接到你本机的 opencode 服务复用同一个配置和会话历史。也就是说你在终端里开到一半的会话可以在 VSCode 面板里继续反之亦然。我实际使用中觉得最实用的功能是把选中代码直接带入对话。在编辑器里框选一段代码右键选择“发送到 opencode”它会把代码片段、文件路径、当前光标位置一起传给 agent省去手动引用文件的步骤。这个插件适合“边读代码边对话”的场景左边是编辑器右边是和 agent 的对话面板看到哪问到哪。6.2 JetBrains IDEA 插件老牌 IDE 用户怎么接JetBrains 家族的插件IDEA、PyCharm、GoLand 等也已经有官方实现了。功能逻辑和 VSCode 插件类似都是面板集成。需要注意的一点是版本匹配IDEA 插件版本和 opencode CLI 版本不一致时很可能出现连接失败或功能按钮异常。具体表现是面板一直转圈、提示 session host not found 之类。遇到这种情况把两个端都更新到最新版问题基本能解决。IDEA 插件对 Java/Kotlin 项目的支持体验比较自然因为它能和 IDEA 内置终端联动。我个人的建议是如果你主力 IDE 是 JetBrains 系先直接用内置终端跑 opencode插件作为辅助参考不必依赖。6.3 我的混合工作流建议用了一段时间之后我形成了固定的工作方式深度任务在终端 TUI 里跑。涉及多文件重构、自动跑测试、连续执行命令的任务TUI 的可控性和信息密度更高。读代码和提问在 VSCode 面板里做。比如看一个不熟悉的模块选中代码问 agent“这段逻辑有没有问题”比来回切窗口舒服。同一个项目不要同时开两个会话。我在终端开了一个会话又用 VSCode 面板开另一个两边同时操作同一个文件结果出现了互相覆盖的情况。后来就默认“一个项目同时只保留一个 opencode 会话”要么终端要么编辑器不并行。7. 高频报错现场这些坑我替你踩过了7.1 error: unexpected server error. check server logs这是 opencode 用户最常遇到的报错之一原文是error: unexpected server error. check server logs大多数人看到这个第一反应是重试但实际上这个报错的本意是opencode 向模型服务端发起了请求但服务端返回了一个它无法解析的异常。要解决它关键是先搞清楚是哪一端出了问题。我的排查顺序是确认 API Key 有效且没有过期。这是最高频的原因。很多 Key 在后台面板看着是“活跃”的实际上因为欠费或权限变更已经没法用了。确认网络连通性。用 curl 直接访问一下对应模型服务的 API 域名看能否正常响应。这一步能快速排除“本地网络到服务端不通”的问题。查看服务商状态页。如果服务商正在出事故或维护那就不是你能控制的了等恢复即可。检查本地模型服务如果用的是 Ollama。执行ollama list和ollama ps看模型是否加载成功连接是否正常。Ollama 更新版本后 API 有变化也可能导致 opencode 连不上。重置 opencode 进程。某些异常会导致本地状态卡住杀掉进程重开通常能恢复。整套流程下来基本能定位百分之九十的问题。7.2 提示模型不可用this model is not available...怎么办有时候你会看到类似这样的报错This model is not available in your country.这个提示本身说明模型服务商对指定模型设置了开放范围限制你当前的 API 账号所在区域不在支持列表内。遇到这种情况我的处理顺序是确认当前 prompt 用的是哪个供应商的哪个模型登录服务商后台看该模型的支持范围。切换到服务商明确开放的其他模型。比如某些旗舰模型不可用但同系列的中端或旧版本模型仍然可用。如果团队确实需要某个受限模型可以在 opencode 里配置另一家合规供应商的等价模型不影响 workflow。不要轻易相信网上那些“非官方渠道接入”的方案。这类方式既不稳定还容易触发 API Key 风控导致更严重的封禁问题。从工程角度讲模型不可用只是“供应商选择”层面的问题换一个供应商或者换一个等价模型就够了。opencode 的价值恰恰在于切换模型成本极低所以不用非得死磕某一个模型。7.3 手动编辑 opencode.json 的注意点opencode 的配置文件opencode.json放在项目根目录或全局~/.config/opencode/下。手动编辑的时候有几个坑JSON 不允许注释。很多习惯了 JSONC带注释的 JSON的人会顺手写//注释结果 opencode 直接拒绝加载配置。我建议只在外部记录文件里写说明配置本身保持纯净。路径写绝对路径。配置里涉及目录的字段尽量写绝对路径或者先确认相对路径是相对于项目根还是配置文件所在目录避免跨机器同步时路径失效。改完要验证。改完配置后先跑opencode --version或随便跑一条opencode run确认没有语法错误。我自己踩过的最大坑是手滑在某个字段后面多加了一个逗号导致配置完全没加载但命令本身不报错只是行为始终不对排查了很久。7.4 升级与回退版本太快也有烦恼opencode 的迭代速度非常快我用的时候还是早期版本写这篇时已经有人提到 2.0 了。快速迭代带来的最直接问题是配置文件格式、命令行为可能在不同版本之间发生变化。我建议在生产环境里锁定版本。如果你用 brew 安装可以在升级前看当前版本的配置快照如果是二进制方式安装升级之前备份opencode.json和 skills 目录。遇到新版本配置不兼容的问题不要硬着头皮适配直接回退到上一个稳定版本等社区的迁移文档出来再升。最后我当前的配置组合和一个实用习惯写到这里分享一个我现在固定的配置组合供你参考主力模型用旗舰款处理复杂任务日常小改动切到中端或开源模型。Ollama 本地跑一个小尺寸模型负责零散的问答和日志解释不消耗外部 API 额度。用 CCSwitch 维护多套 Key切换的时候不用碰配置文件。opencode.json 和 skills 目录全部放进 dotfiles 仓库新机器一条脚本就能恢复完整环境。还有一个我特别推荐的习惯把 opencode.json 放进项目的版本控制里。这样同一个项目无论谁接手打开 opencode 就能得到一样的模型配置、LSP 设置和 skills。你不需要写长篇 README 告诉新人“要用哪个模型、别动哪些文件”配置文件本身就是最好的文档。opencode 这个工具给我最大的感受是AI 编程 agent 不该被某一家模型厂商绑架。工具负责流程模型负责智能两者自由组合才是这套玩法真正的潜力。如果你也在选终端 agent希望这篇内容能帮你少走一些弯路。