想要高效使用OpenCode，掌握其配置系统是关键。本文深入解析其核心配置文件的格式、加载逻辑与优先级顺序，帮助用户理清不同配置间的关系，构建清晰、个性化的开发环境，解决配置混乱与冲突的常见痛点。
智能速览
OpenCode配置支持带注释的JSONC格式，推荐使用。
配置文件遵循“合并覆盖”原则，而非完全替换。
配置加载存在明确的优先级顺序，内联参数优先级最高。
全局配置用于设置用户通用偏好，项目配置则针对特定项目。
通过JSON Schema可以获得配置文件的语法提示，降低出错率。
精华内容
理解OpenCode的配置机制，关键在于掌握其文件格式与加载优先级。下面将深入剖析配置的合并规则、不同优先级的存放位置以及各自的适用场景，助你从零构建高效的配置体系。
文件格式选择
OpenCode的配置文件支持JSON与JSONC两种格式。JSONC（JSON with Comments）允许在文件中添加注释，这对于长期维护或团队协作至关重要。当你或他人回顾配置时，注释能清晰说明每项设置的用途和意图。
例如，在JSONC文件中可以用`//`或`/* */`添加备注，而标准JSON则不支持此功能，容易导致配置遗忘或理解困难。因此，在创建和编辑配置时，强烈推荐使用JSONC格式，以提升代码的可读性和可维护性。
合并覆盖原则
配置的加载遵循“合并覆盖”原则，而非简单的替换。当多个配置源存在时，系统会按优先级顺序依次加载。后面的配置会覆盖前面配置中同名的属性，而不同名的属性则会保留并合并在一起。
例如，远程配置默认关闭了某个服务，而全局配置中将其开启，那么最终生效的是开启状态。同时，如果远程配置设置了主题A，全局配置设置了默认模型B，最终配置将同时包含主题A和模型B。这一机制保证了配置的灵活性和层次性。
加载优先级详解
配置文件的加载优先级从低到高依次是：
远程配置：由服务提供商提供的默认配置，作为基础配置层。
全局配置：作用于当前用户的所有项目，存放在 `~/.config/opencode/opencode.jsonc` (macOS) 或 `C:Users<用户名>.configopencodeopencode.jsonc` (Windows)。
自定义配置：通过环境变量指定的配置文件。
项目配置：位于项目根目录的 `.opencode.jsonc` 文件，优先级较高，适合存放项目专属设置，并可安全提交至代码仓库。
内联配置：通过命令行（CLI）直接指定的参数，具有最高优先级，用于临时覆盖。
配置场景应用
理解了优先级后，可以灵活应用。全局配置适合放置个人偏好，如界面主题、默认使用的AI模型、快捷键定义以及通用的回复规则（例如，要求回复语言与提问语言一致）。这些设置在所有项目中都会生效。
而项目配置则用于特定项目的需求，例如，在一个数据分析项目中，可以专门配置用于数据处理的Agent或插件，而不影响其他项目的配置。这种分层管理方式，让配置既统一又灵活，极大提升了工作效率。
熟练掌握OpenCode的配置系统，是从新手到高手的必经之路。通过合理利用JSONC格式、理解合并覆盖原则并遵循加载优先级，可以构建起一套稳定、高效且易于维护的开发环境。你的OpenCode配置有哪些独到之处？欢迎分享你的实践与思考。
