Config & Session
“Configure Once, Run Everywhere”
A single config file controls the entire agent harness behavior.
OpenCode 使用单个配置文件声明模型、插件、技能路径和所有其他设置。默认配置文件位于 ~/.config/opencode/opencode.jsonc。项目可以通过在根目录放置自己的 opencode.jsonc 来覆盖设置；配置会合并而非替换。
架构流程图
问题：每个项目都不同，每个开发者都有偏好
开发者可能在大多数任务中偏好 Claude Sonnet，但特定项目需要 GPT-4。他们可能有个人技能集合，而团队维护共享项目技能。配置系统必须协调全局默认值与项目级覆盖，同时保留覆盖任何内容而不复制所有内容的能力。深度合并解决了这个问题：全局配置提供默认值；项目配置覆盖特定字段；其余内容保持不变。
可发现性与 $schema
opencode.jsonc 文件通过 $schema URL 引用 JSON Schema。这并非装饰性的：它在编辑配置文件时启用 IDE 自动完成、验证和内联文档。该 schema 还充当所有可用配置选项的规范参考。新选项首先添加到 schema，然后在代码中实现。这种文档驱动的方法确保配置面始终有文档和验证。
真实实现：带 SQLite 的事件溯源会话
OpenCode 的会话系统超越了配置管理。会话是事件溯源的，通过 Drizzle ORM 存储在 SQLite 中。每个会话维护一个持久事件的 Timeline。这意味着会话在重启后仍然存在，支持通过事件回放进行回滚，并且可以通过同一 SQLite 存储在进程之间共享。SessionRunCoordinator 按会话序列化执行，带有唤醒合并：如果两个提示同时到达，它们被排队并顺序处理，而不是并行处理。
设计决策
配置发现从项目根目录向上遍历目录树，而非从当前工作目录开始。这意味着项目中的任何子目录都能正确解析到项目的 opencode.jsonc。
使用 JSONC 格式（带注释的 JSON）而非纯 JSON。注释使配置自文档化：开发者可以在行内注解自己的选择，无需维护单独的文档文件。
对比 Claude Code
两者都使用配置文件，但 OpenCode 的多源 deepMerge 模式更精细。全局配置 (~/.config/opencode/) 提供默认值，项目配置覆盖特定内容，两者被递归合并。Claude Code 使用更简单的单一配置方式。OpenCode 的会话系统还增加了压缩和消息版本管理，这对于长时间运行的会话至关重要，否则会超出上下文窗口。
深入设计决策
一个配置文件统治一切
opencode.jsonc 是唯一的配置文件。它声明了模型、插件、技能路径和其他设置。agent 启动所需的一切都在一个地方。
全局配置与项目级覆盖
默认配置位于 ~/.config/opencode/opencode.jsonc。项目可以通过在项目根目录放置自己的 opencode.jsonc 来覆盖。设置会合并而非替换。