oh-my-openagent 配置文档漂移审计全解：以源码为准的统一 omo.json[c] 配置权威指南

oh-my-openagent 配置文档漂移审计全解以源码为准的统一 omo.json[c] 配置权威指南【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent本篇技术指南围绕 oh-my-openagentOmO仓库中的配置文档漂移审计记录展开系统讲解该项目的统一配置体系omo.json[c]如何被加载、合并、校验、迁移以及官方文档docs/reference/configuration.md与docs/reference/omo-json.md在审计中暴露出的全部 OUTDATED过时、CORRECT正确与 UNVERIFIABLE不可证实结论。读完本文你将掌握 OmO 配置文件的发现与分层解析规则、reasoning统一字段的迁移语义、各选项表的真实默认值与取值约束并学会用源码作为唯一事实基准来排查自己的配置问题。审计是什么方法、范围与判定标准审计任务见 .omo/evidence/20260809-docs-drift-audit/config-docs.md将两份核心文档逐条与实现代码比对审计对象docs/reference/configuration.mdOpenCode/插件侧配置说明与docs/reference/omo-json.md统一配置格式说明代码基准ground truth统一配置核心packages/omo-config-core、OpenCode 插件配置 schema 与校验packages/omo-opencode、模型链packages/model-core、迁移代码packages/omo-opencode/src/config-migration以及遥测环境变量packages/telemetry-core判定三档CORRECT文档与源码一致、OUTDATED文档已过时给出具体修改建议、UNVERIFIABLE仓库内被检查的代码无法证实需要补充运行期证据或外部引用。全文约 200 条 claim 中OUTDATED集中在几大主题reasoning字段统一、配置表不完整、默认值变更、新功能未入文档、以及路径/安全边界的措辞偏差。下面按主题展开并附上每条结论对应的源码路径。统一配置体系的五大基础事实审计确认为 CORRECTomo.json[c] 是唯一运行时配置legacy 文件仅供迁移审计确认configuration.md:3、omo-json.md:3每个 OmO harnessOpenCode / Senpi / Codex在运行时都只读取统一的omo.json[c]旧的oh-my-*文件与~/.omo/config.jsonc仅作为一次性迁移输入迁移完成后不再被运行期读取路径解析实现、迁移发现逻辑。用户配置与项目配置的发现规则用户配置~/.omo/omo.jsonc若不存在则回退到~/.omo/omo.jsondetectUserOmoJsonPath项目配置从cwd逐级向上向 HOME 方向遍历距离更远更靠近根的配置层级更低最近目录的配置优先HOME 本身被跳过——因为 HOME 下的.omo属于用户层不能被重复当作项目层findProjectConfigPathsFarthestFirst注意OUTDATED 修正文档 configuration.md:50 曾写当 cwd 位于 HOME 之外时只检查该目录已过时。实际实现中遍历会一直继续到文件系统根受MAX_PROJECT_CONFIG_DIRECTORY_DEPTH 256深度上限约束符号链接防护符号链接形式的项目.omo目录或配置文件会被跳过isSymlinkedProjectPath/isLoadableProjectConfigFile避免软链接绕过路径边界paths.ts。分层解析与 Harness 视图加载完成后配置文件按四层折叠出某个 harness 的视图resolution.ts共享基础层剥离控制键后的根级内容对应 harness 块[opencode]/[senpi]/[codex]激活的 profile 基础层激活的 profile 中的 harness 块。层与层之间后合并者覆盖先合并者last merged wins且profiles与[harness]控制键不会泄漏进最终结果withoutControlKeys、stripResolutionControlKeys见 loader.ts。Profile 激活优先级Profile 激活优先级为resolveOmoProfileName显式传入的profile参数环境变量OMO_PROFILE环境变量OCX_PROFILEOPENCODE_CONFIG_DIR路径末尾形如profiles/name的尾段以上都没有 → 不激活任何 profile。当激活的 profile 不存在时加载器不会报错中断而是产生一条kind: profile的诊断信息并使用基础配置继续resolution.ts。同时确认仓库不内置任何默认 profileprofile 完全由用户显式定义或由迁移产生config.ts。默认值、严格校验与安全默认值只应用一次所有 schema 默认值在分层解析完成、合并出最终配置后才统一填充loader.ts严格校验OmoConfigSchema使用.strict()未知键被拒绝唯一例外是[opencode]被有意设计为自由格式 recordOmoOpenCodeHarnessConfigSchema z.record(z.string(), z.unknown())而[senpi]、[codex]是严格类型块config.tsJSONC 支持行注释、尾随逗号均被接受解析基于jsonc-parser的allowTrailingComma: true, disallowComments: falseloader.ts原型污染防护__proto__、constructor、prototype三类危险键在任何层级被递归清除携带篡改原型tampered prototype的整层配置会被 fail-closed 拒绝merge.ts、loader.ts失败降级某层文件不可读、JSONC 解析失败、校验失败时产生对应诊断read / parse / validation / unknown-keys并继续加载其他层最终合并结果校验失败时返回全默认配置 诊断而不是抛异常loader.ts。合并语义的细节修正omo-json.md:17 曾断言所有数组整体替换下层审计标记为 OUTDATED 并给出唯一例外codegraph.excluded_roots数组在跨层合并时是 union 去重而不是替换。其余数组如models链仍遵循整体替换语义普通对象则递归深合并merge.ts。最重大的漂移reasoning 统一variant / reasoningEffort / thinking → reasoning审计中最成体系的一组 OUTDATED 结论来自 2026-08 的reasoning统一迁移migration ID2026-08-reasoning-unification。旧文档中散落的variant、reasoningEffort、thinking、textVerbosity、maxTokens等各家厂商专属调优字段现在统一收敛为规范字段reasoning其余均降级为已废弃的兼容输入。统一推理等级词汇表规范值域定义于 reasoning-vocabulary.ts类别取值等级ReasoningLeveloff、minimal、low、medium、high、xhigh、max自动auto透传passthrough任意未识别字符串原样透传供新模型/新供应商归一化特例none归一化为off输入做 trim lowercase模型字符串支持内联 reasoning 后缀规范形式为model:level如gpt-5.6-sol:maxmodel (level)与model level等写法会被归一化为冒号形式splitReasoningSuffix还特别处理了:max与真实模型 ID 结尾的歧义——裸 ID 不拆分带 provider 前缀包含/时才拆分reasoning-vocabulary.ts。模型对象规范字段模型对象agent / category / fallback 链中共用的规范字段由 model-ref.ts 定义{ model: gpt-5.6-sol, reasoning: high, // 规范字段 temperature: 1.0, // 0..2 top_p: 0.95, // 0..1 max_tokens: 8192, // 正整数 provider_options: { } // 供应商专属透传 }废弃字段的归一化优先级normalizeLegacyModelFieldsfallback-models.ts把旧字段映射到新结构优先级为reasoningreasoningEffortvariantthinking仅 disabled 时映射为 off。具体映射关系旧字段新位置variantreasoning废弃reasoningEffortreasoning废弃none归一化为offthinking.typedisabledreasoning: offthinking.typeenabledbudgetTokensprovider_options.thinkingtextVerbosityprovider_options.textVerbositymaxTokensmax_tokensproviderOptionsprovider_optionsfallback_modelsmodels有序链审计特别指出configuration.md:862、989模型后缀与reasoning是独立归一化的两条路径——model:level内联后缀规范化由canonicalModelString完成而显式reasoning字段的优先级高于任何 legacy 字段。因此新文档中的推荐写法统一是reasoning: max取代 configuration.md:1168 中建议的variant: max、omo-json.md:67 中的reasoningEffort: high等旧示例。各配置表的对应修正agent 级agent.ts新增规范字段reasoning、models、max_turns、disallowed_toolsvariant/reasoningEffort标记deprecated。审计要求 configuration.md:211 的 Agent 选项表补充models、reasoning、skills、description、displayName、ultrawork、compaction并把兼容字段标注废弃category 级category.ts补充models、规范reasoning、max_tokens、provider_options删除非 schema 的requiresModel该键只是内置 deep 门的元数据并非CategoryConfig键maxTokens→max_tokensmodel catalog 级model-catalog.ts目录条目只接受规范model 可选reasoning加两个废弃输入variant/reasoningEffort不再接受temperature/top_p/max_tokens/provider_options等调优字段fallback 对象级fallback-models.ts保留temperature/top_p/max_tokens/provider_optionsthinking/textVerbosity/maxTokens/providerOptions/variant/reasoningEffort全部标记废弃OpenCode 插件侧agent-overrides.tstools是recordstring, boolean而非数组mode是枚举subagent | primary | allcolor必须是六位十六进制#RRGGBBultrawork.reasoning取代ultrawork.variantagents.oracle.reasoning取代agents.oracle.variant。审计发现的其他 OUTDATED 事实清单行为/默认值类修正文档位置旧表述事实源码configuration.md:340ultrabrain 默认链首档gpt-5.6-sol xhigh应为maxcategory-model-requirements.tsconfiguration.md:344unspecified-low 默认gpt-5.6-luna xhigh应为gpt-5.6-terra high同一文件 L95-L101configuration.md:426/427Librarian / Explore 首档无 reasoning 调优首档gpt-5.6-luna-fast应补lowconfiguration.md:463background_task.defaultConcurrency默认 unspecified运行时默认 5concurrency.tsconfiguration.md:506experimental.task_system默认 true默认falsetask-system-enabled.tsomo-json.md:261task.residency_max_children仅接受正整数额外接受字面量unlimited且有效默认值是Math.min(16, Math.max(8, availableParallelism() * 2))schema 字面默认 8 会被解析器覆盖task.ts配置表不完整类修正background_taskbackground-task.ts补充maxDepth、messageStalenessTimeoutMs、taskTtlMs、sessionGoneTimeoutMs、taskCleanupDelayMs、syncPollTimeoutMs、maxToolCalls、circuitBreakertmuxtmux.ts补充isolation默认inline及其枚举值确认enabled默认 false、layout默认main-vertical、main_pane_size默认 60范围 20..80、main_pane_min_width默认 120、agent_pane_min_width默认 40runtime_fallbackruntime-fallback.ts补充restore_primary_after_cooldown确认retry_on_errors默认[429,500,502,503,504]、max_fallback_attempts默认 3范围 1..20、cooldown_seconds默认 60允许 0、timeout_seconds默认 300 表示禁用超时升级与message.updated重试检测、notify_on_fallback默认 trueexperimentalexperimental.ts补充preemptive_compaction、plugin_load_timeout_ms、safe_hook_creation、model_fallback_title、max_tools、disable_live_parent_wake_routingdynamic_context_pruningdynamic-context-pruning.ts确认enabled默认 falsenotification枚举off/minimal/detailed默认detailedturn protection 默认开启、3 轮、范围 1..10deduplication / supersede_writes / purge_errors 默认开启purge 在 5 轮后生效。新增功能未入文档类修正内置命令除了goal、refactor、start-work、stop-continuation、remove-ai-slops、hyperplan外新增内置handoff命令commands.ts浏览器自动化提供者除playwright、agent-browser外新增dev-browser与playwright-cli默认仍为playwrightbrowser-automation.ts内置 MCP除websearch、context7、grep_app、lsp外新增内置codegraphmcp/index.tsdisabled_mcps示例需包含它mcp/types.tscodegraph 配置面完整的插件级键包括auto_init、auto_provision、daemon、enabled、excluded_roots、install_dir、telemetry、watch_debounce_msdaemon默认 trueschema/codegraph.ts、schema/codegraph.ts共享层LSP 相关LSP_TOOLS_MCP_PROJECT_CONFIG实际是分隔符分隔的搜索列表.opencode/lsp.json、.omo/lsp.json、.omo/lsp-client.jsonmcp/lsp.tsLSP_TOOLS_MCP_INSTALL_DECISIONS按 harness 区分——Codex 用CODEX_HOME/lsp-install-decisions.jsonOpenCode 注入自身 config-dir 路径旧文档一律为~/.codex/lsp-install-decisions.json的说法过时。路径/安全边界类修正file://~主目录相对路径configuration.md:329并非可指向主目录下任意位置而是仅限~/.config/opencode、~/.config/oh-my-openagent、~/.omo、~/.opencode四个目录resolve-file-uri.ts畸形/缺失/不可读/被拒绝的 file URI 产生带警告的占位内容同文件 L27-L62cwd 在 HOME 外配置遍历继续到文件系统根见上文发现规则Codex 专属键归位codegraph.session_start_cooldown_ms不在 OpenCode 插件 schema 中应归属共享顶层codegraph或[codex].codegraphconfig/schema/codegraph.tsSenpi 与 daemonomo-json.md:239codegraph.daemonfalse使 Senpi 使用进程内 CodeGraph 的说法过时——daemon 仅适用于 Codex 与 OpenCodeSenpi 不支持该键。环境变量与遥测类修正OMO_CODEX_DISABLE_POSTHOG除1/true外yes同样禁用Codex 遥测且全局OMO_DISABLE_POSTHOG也会一并禁用 Codex 遥测telemetry-core/env.tsOMO_CODEX_SEND_ANONYMOUS_TELEMETRY0/false/no禁用且yes目前同样被 telemetry-core 视为 opt-out确认项OMO_SEND_ANONYMOUS_TELEMETRY的0/false/no禁用插件遥测OMO_DISABLE_POSTHOG的1/true/yes禁用插件遥测posthog.tsPOSTHOG_API_KEY覆盖内置 API key、POSTHOG_HOST覆盖采集主机默认https://us.i.posthog.comenv.ts。迁移机制legacy 配置如何进入统一体系审计确认的迁移事实均 CORRECT发现范围迁移会扫描四种oh-my-*基础名用户 / profile / 项目三层~/.omo/config.jsoncdiscovery-paths.ts映射规则legacy 用户配置 →[opencode]profile 差异 →profiles.name.[opencode]项目配置 → 项目.omo/omo.jsonctransform-opencode.ts~/.omo/config.jsonc则映射codegraph与 harness 块其中[omo]映射到[senpi]transform-config-jsonc.ts不覆盖原则迁移是 no-clobber 的并会把旧历史保留在legacy_migrations记录中migration-plans.ts备份位置用户备份在~/.omo/migration-backup-timestamp-opencode-config项目备份在project/.omo/migration-backup-timestampmigration-plans.ts迁移标记_migrations数组用于记录已应用的迁移 ID。审计指出 configuration.md:101 与 omo-json.md:378 声称标记集合只有两个 7 月迁移 ID已过时——现在必须补充2026-08-reasoning-unification该迁移会重写持久化的 model/reasoning 字段reasoning-unification.ts、migration-plans.ts旧顶层lsp块已不被读取迁移时被剥离transform-opencode.ts。分类与 Agent 默认模型链model-core 事实packages/model-core中的category-model-requirements.ts与agent-model-requirements.ts是默认模型链的权威定义。审计确认的要点CORRECT 为主分类默认链visual-engineering以claude-fable-5-1/claude-opus-5max 起步deep默认gpt-5.6-sol mediumartistry默认claude-fable-5-1xhighquick以kimi-for-coding-highspeed起步unspecified-high默认kimi-k3 maxwriting默认kimi-k3 lowcategory-model-requirements.ts。unspecified-low的主列按审计修正为gpt-5.6-terraxhigh 档 grok-4.6 之后。Agent 默认链Sisyphus、Hephaestus、Oracle、Multimodal Looker、Prometheus、Metis、Momus、Atlas、Sisyphus Junior 的链与文档一致agent-model-requirements.ts。任务委派task delegation是按分类路由category-routed而非直接按模型路由delegate-task/categories.tstask.warnings.unavailable_categories与categories.name.warn_unavailable共同控制不可用链告警schema/task.ts、config/schema/categories.ts。UNVERIFIABLE需要人工核实的声明审计把下列声明标记为 UNVERIFIABLE提醒维护者要么补运行期证据、要么删掉绝对化表述sisyphus_agent 默认值default_builder_enabled、planner_enabled、replace_plan的默认值声明——schemasisyphus-agent.ts只接受键、不编码默认值需引用运行期调用点或弱化表述内置技能闭集内置技能恰好是 playwright、playwright-cli、agent-browser、dev-browser、git-master、frontend——没有单一注册表行能证明穷尽性skills.sources的recursive默认 false 也属于缺省即 false-like而非 schema 默认fallback provider 前缀推断schema 接受任意字符串但前缀可省略并被推断属于解析器行为需引用 resolver 代码model_capabilities.source_url默认值schema 仅校验 URL默认https://models.dev/api.json需引用抓取调用点外部插件/供应商能力声明opencode-antigravity-auth的多账号双配额与 variant-based thinking、Antigravity Claude 固定 200k vs 直连 Anthropic 1M 车道、Ollama 需关闭流式避免 JSON 解析错误——均属仓库外行为应依据外部插件版本/供应商文档核实或删除omo-json 侧Senpi task 引擎的内置 agent 清单explore、librarian、oracle、metis、momus与其九项工具白名单、受限 bash、执行模式覆盖忽略、只读 agent 不可入队等均需引用 senpi-task 内置注册表与运行时策略team 的tmuxbackendType 与用户级全局 team 存储目前是schema 接受但运行期未使用统一配置文件自 4.20.0 起支持的说法需对照 changelog 核实。结论把源码当作唯一事实基准这次漂移审计的价值不在于文档错了多少而在于确立了一条可复用的维护纪律schema 文件是字段与默认值的最高权威——packages/omo-config-core/src/schema/下每个.ts文件即配置契约新增/废弃字段首先改这里行为声明必须落到运行期代码——凡是默认值闭集推断规则类表述若 schema 无法证明就必须引用 loader、resolver 或功能模块的调用点否则只能写为 UNVERIFIABLEreasoning统一是当前最大的兼容性断层——任何还在写variant/reasoningEffort/thinking的示例都应更新为规范写法同时明白它们作为兼容输入仍会被归一化处理优先级reasoningreasoningEffortvariant新功能与文档必须同批发布——handoff命令、codegraphMCP、dev-browser/playwright-cli、tmuxisolation、restore_primary_after_cooldown等一批已实现未成文的键是文档漂移最常见的来源。对于使用者这意味着排查配置问题时应以源码 schema 与本文列出的审计结论为准而不是以可能滞后的文档为例。配置文件本身支持 JSONC 注释与尾逗号可用$schema指向 assets/omo.schema.json 获得编辑器补全每次迁移含2026-08-reasoning-unification都会在~/.omo/或项目.omo/下留下时间戳备份迁移前后可放心比对。更详细的分层解析、字段默认值与模型链定义可继续深入 packages/omo-config-core/src、packages/omo-opencode/src/config 与 packages/model-core/src 阅读源码或参考 docs/reference/configuration.md 与 docs/reference/omo-json.md 的最新修订版本。【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考