1. 改了 opencode.json 却不生效问题出在哪如果你正在用 opencode 做 AI Agent 开发大概率踩过这个坑明明在opencode.json里改了model字段重启后 Agent 还是用旧模型或者团队下发了disabled_providers本地 tool 注册表却纹丝不动。这不是你配置写错了而是配置系统的加载链路比你想的复杂——它不是一个文件说了算而是 5 层来源按确定优先级合并后的结果。opencode 的配置系统要解决的核心问题是配置是跨模块的状态契约不是某个模块的私有字段。用户用 JSON 配置 provider、Agent、权限规则、MCP 服务这些字段被 server、TUI、tool 注册表、session 管理等多个模块同时消费。如果每个模块自己import自己需要的字段就会出现两个致命问题跨模块联动断裂改了server.portTUI 的 WebSocket URL 不知道和来源优先级混乱全局配置、项目配置、环境变量同时赋值时谁赢没有答案。opencode 的解法是5 层来源合并管道 一个 Config.Service 统一查询入口。所有来源最终合并成一个Config.Info结构63 个顶级字段CLI 的opencode debug config和 SDK 的sdk.config.get()共享同一个 Service。这篇就按源码级拆解这个管道从loadGlobal的三文件级联到loadInstanceState的完整合并链最后给你一份可复制的配置骨架和验证动作。适合谁看正在设计多来源配置系统的后端/Agent 开发者或者想搞清楚 opencode 配置为什么改了不生效的使用者。读完你能自己搭一个 10 行 merge 函数跑通整个管道也能定位 90% 的配置不生效问题。2. 前置准备TaoToken 接入与 opencode 环境在拆源码之前先把运行环境跑通。opencode 的配置系统里 provider 和 model 字段最终要指向一个可用的 LLM 服务这里用 TaoToken 作为 provider 接入点它的 API 兼容 OpenAI 格式配置起来最省事。你需要准备三样东西第一一个 TaoToken 账号和 API Key。访问官网注册后进入控制台创建 API Key这个 Key 会用在provider.apiKey字段里。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite第二opencode CLI 已安装。如果你还没装用 npm 全局安装即可npm install -g opencode-ai opencode --version第三确认你的工作目录结构。opencode 会扫描当前目录和工作树根目录下的.opencode/文件夹所以建议在项目根目录操作mkdir -p my-agent/.opencode cd my-agent关于 API Key 的获取和模型列表查询接入文档里有完整的字段说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意API Key 不要硬编码进提交到 Git 的配置文件。opencode 支持环境变量注入后面第 3 节会讲OPENCODE_CONFIG_CONTENT的用法CI 场景下用它比写死在 JSON 里安全得多。环境就绪后先跑一句opencode debug config看看当前生效的配置长什么样。如果输出是空对象或者报错说明还没有任何配置文件这正好我们从零开始搭。3. 可复制配置5 层来源骨架与 Config.Service 调用这一节给你一份可以直接抄的配置骨架覆盖 5 层来源中的关键层并演示 Config.Service 的两条消费入口。3.1 全局三文件级联config.json → opencode.json → opencode.jsoncopencode 在全局目录下同时支持三个文件名读取顺序决定优先级后读取的覆盖前者。你可以在~/.config/opencode/下建这三个文件来验证// ~/.config/opencode/config.json 旧版格式优先级最低 { model: gpt-4o, server: { port: 3000 } }// ~/.config/opencode/opencode.json 标准配置名 { model: claude-sonnet-4 }// ~/.config/opencode/opencode.jsonc 带注释优先级最高 { // 这里覆盖前两个文件的 model model: claude-opus-4, disabled_providers: [legacy-provider] }合并结果model取opencode.jsonc的值claude-opus-4server.port从config.json继承3000disabled_providers只在opencode.jsonc出现所以直接生效。这就是mergeDeep的语义——按叶子节点逐字段覆盖空值不覆盖。3.2 项目级配置.opencode/opencode.json在项目根目录建.opencode/opencode.json它会覆盖全局层的同名字段// my-agent/.opencode/opencode.json { provider: { taotoken: { apiKey: ${TAOTOKEN_API_KEY}, baseURL: https://taotoken.net/api } }, model: taotoken/claude-sonnet-4, permissions: { bash: ask, edit: allow } }注意apiKey用了${TAOTOKEN_API_KEY}占位符opencode 会在加载时做环境变量替换。这样你的 Key 不用写进文件。3.3 环境变量注入OPENCODE_CONFIG_CONTENT最高优先级的一层适合 CI 和容器场景export OPENCODE_CONFIG_CONTENT{model:taotoken/claude-opus-4,permissions:{bash:deny}} opencode debug config这层会覆盖前面所有来源的同名字段。在 GitHub Actions 里可以这样用- name: Run opencode agent env: TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }} OPENCODE_CONFIG_CONTENT: {model:taotoken/claude-sonnet-4} run: opencode run 分析这个仓库的依赖3.4 Config.Service 的两条消费入口配置合并完成后消费方只调一个get()。CLI 入口在packages/opencode/src/cli/cmd/debug/config.ts核心就三行const Config await Effect.promise(() import(/config/config)) const info await Config.Service.use((cfg) cfg.get()) console.log(JSON.stringify(info, null, 2))SDK 入口走 HTTP服务端暴露GET /config经过实例路由和权限校验后返回同一个 Service 的get()结果。两条入口殊途同归消费方看到的都是一个扁平的Config.Info结构不需要知道背后有几层来源。如果你要长期跑 Agent 任务建议用 Coding Plan 来管理模型配额和调用策略比单次 API 调用更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite4. 验证请求从 debug config 到 resolved JSON配置写完了怎么确认合并结果符合预期opencode 提供了debug config命令它直接调用 Config.Service 的get()输出最终合并后的 JSON。4.1 基础验证opencode debug config预期输出是一个包含 63 个字段的 JSON 对象大部分字段可能为空因为都是 optional。重点检查这几个字段{ model: taotoken/claude-sonnet-4, provider: { taotoken: { baseURL: https://taotoken.net/api } }, permissions: { bash: ask, edit: allow }, disabled_providers: [legacy-provider] }如果model显示的是全局层的值而不是项目层的值说明项目级.opencode/opencode.json没被扫描到——检查你的工作目录是否是项目根目录。4.2 逐层剥离验证想确认某一层的值可以临时清空其他层。比如只验证全局三文件级联# 临时移走项目级配置 mv .opencode/opencode.json /tmp/ opencode debug config | grep model # 应该输出全局 opencode.jsonc 里的值 mv /tmp/opencode.json .opencode/4.3 用 SDK 验证 HTTP 入口如果你在写自己的 Agent 应用通过 SDK 拿配置import { createOpencodeClient } from opencode-ai/sdk const client createOpencodeClient({ baseUrl: http://localhost:3000 }) const config await client.config.get() console.log(config.model)服务端返回的config和 CLI 的debug config是同一个对象这验证了单一查询入口的设计——两条路径共享 Config.Service。4.4 验证远程配置重新加载远程配置层通过invalidate()触发重新加载。你可以模拟这个流程# 启动 opencode server opencode serve --port 3000 # 另一个终端触发配置失效 curl -X POST http://localhost:3000/config/invalidate如果远程 well-known URL 有更新下一次get()会返回新值。这个机制由 Effect 的cachedInvalidateWithTTL驱动TTL 过期后自动重新计算。5. 本篇常见错排查配置不生效的问题90% 出在下面这几个点。按顺序排查。5.1 文件名和目录位置不对opencode 扫描的是当前目录和工作树根目录下的.opencode/文件夹。如果你在子目录里跑opencode而配置在项目根目录的.opencode/下它可能扫不到。确认方式pwd ls -la .opencode/ ls -la $(git rev-parse --show-toplevel)/.opencode/两个位置都要检查。monorepo 场景下子项目的.opencode/opencode.json会覆盖根目录的但前提是你在子项目目录下运行。5.2 JSONC 语法错误导致整层被跳过opencode.jsonc支持注释和尾随逗号但语法错误会导致整个文件解析失败。opencode 的处理是打日志并跳过该层不会中断进程。所以你可能看到配置部分生效——其实是某一层被静默跳过了。排查方式用jsonc-parser校验文件npx jsonc-parser validate .opencode/opencode.jsonc或者临时把.jsonc改成.json去掉注释看是否生效。5.3 环境变量占位符没替换${TAOTOKEN_API_KEY}这种占位符如果对应的环境变量没设置opencode 会保留原字符串或者置空取决于版本。验证echo $TAOTOKEN_API_KEY # 如果为空先 export export TAOTOKEN_API_KEYsk-xxx opencode debug config | grep apiKey5.4 优先级理解反了记住优先级从低到高全局三文件 →$OPENCODE_CONFIG→ 项目扫描 → 远程 well-known →OPENCODE_CONFIG_CONTENT。后合并的覆盖前面的。如果你在全局配了model项目级也配了项目级赢。如果你在OPENCODE_CONFIG_CONTENT里配了它赢所有。常见误解以为config.json优先级最高因为名字最基础。实际上它是最低的因为最先读取。5.5 数组字段的合并行为instructions数组是去重拼接不是覆盖。全局配了 3 条项目配了 2 条最终是 5 条去重后。如果你期望项目级覆盖全局级的 instructions会发现它们被合并了。这是mergeConfigConcatArrays的特化处理其他数组字段默认是替换。5.6 远程配置拉取失败但不报错远程 well-known URL 拉取失败时opencode 只打日志不中断。所以你可能以为远程配置生效了实际上它被跳过了。检查日志opencode debug config 21 | grep -i remote\|fetch\|well-known如果看到 fetch 失败的日志检查网络和 URL 格式必须是https://开头路径是/.well-known/opencode。6. 配置合并管道的落地建议拆完 opencode 的 686 行config.ts核心洞察其实一句话配置的消费者不应该知道配置的来源。CLI handler 只调cfg.get()SDK 只调sdk.config.get()它们都不知道管道里有多少层。如果你要自己实现类似系统不需要 686 行。记住三个设计原则第一查询路径只有一条。所有消费方走同一个get()接口来源管道可以加层、减层、重排序消费方不改代码。第二合并规则是确定的。mergeDeep决定语义——后合并的覆盖前面的同名字段空值不覆盖。数组字段单独处理去重拼接或替换在文档里写清楚。第三失败可恢复。远程拉取超时、文件不存在、JSON 解析失败都只打日志不中断。用 Effect 的Option/Either模式或者简单的 try-catch fallback 都能实现。一个 10 行的 merge 函数就能跑通整个管道function mergeDeep(target: any, source: any): any { if (!isRecord(source)) return source ?? target const result { ...target } for (const [key, value] of Object.entries(source)) { if (isRecord(value) isRecord(result[key])) { result[key] mergeDeep(result[key], value) } else if (value ! undefined value ! null) { result[key] value } } return result }配合一个按优先级顺序调用的加载器你就有了 opencode 配置系统的核心。剩下的 600 行花在patchJsonc原地编辑、TOML 迁移兼容、Effect 异步管道上——这些是工程细节不是架构必需。如果你在验证模型配置时想快速测试不同 provider 的响应用模型对话页面直接试比改配置文件快得多https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite最后提醒一个实操细节patchJsonc原地修改单字段的能力是 opencode 选 JSONC 弃 TOML 的根本原因。如果你的系统需要运行时改配置而不丢注释和格式JSONC jsonc-parser是目前最省事的组合。TOML 生态没有等价工具改一个字段要全量重写用户体验差一截。