企业官网建设流程全解析

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-openagent（OmO）仓库中的配置文档漂移审计记录展开，系统讲解该项目的统一配置体系（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.md（OpenCode/插件侧配置说明）与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字段统一、配置表不完整、默认值变更、新功能未入文档、以及路径/安全边界的措辞偏差。下面按主题展开，并附上每条结论对应的源码路径。

统一配置体系的五大基础事实（审计确认为 CORRECT）

omo.json[c] 是唯一运行时配置，legacy 文件仅供迁移

审计确认（configuration.md:3、omo-json.md:3）：每个 OmO harness（OpenCode / Senpi / Codex）在运行时都只读取统一的omo.json[c]，旧的oh-my-*文件与~/.omo/config.jsonc仅作为一次性迁移输入，迁移完成后不再被运行期读取（路径解析实现、迁移发现逻辑）。

用户配置与项目配置的发现规则

• 用户配置：~/.omo/omo.jsonc，若不存在则回退到~/.omo/omo.json（detectUserOmoJsonPath）；
• 项目配置：从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）：

1. 共享基础层（剥离控制键后的根级内容）；
2. 对应 harness 块（[opencode]/[senpi]/[codex]）；
3. 激活的 profile 基础层；
4. 激活的 profile 中的 harness 块。

层与层之间后合并者覆盖先合并者（last merged wins），且profiles与[harness]控制键不会泄漏进最终结果（withoutControlKeys、stripResolutionControlKeys，见 loader.ts）。

Profile 激活优先级

Profile 激活优先级为（resolveOmoProfileName）：

1. 显式传入的profile参数；
2. 环境变量OMO_PROFILE；
3. 环境变量OCX_PROFILE；
4. OPENCODE_CONFIG_DIR路径末尾形如profiles/<name>的尾段；
5. 以上都没有 → 不激活任何 profile。

当激活的 profile 不存在时，加载器不会报错中断，而是产生一条kind: "profile"的诊断信息并使用基础配置继续（resolution.ts）。同时确认：仓库不内置任何默认 profile，profile 完全由用户显式定义或由迁移产生（config.ts）。

默认值、严格校验与安全

• 默认值只应用一次：所有 schema 默认值在分层解析完成、合并出最终配置后才统一填充（loader.ts）；
• 严格校验：OmoConfigSchema使用.strict()，未知键被拒绝；唯一例外是[opencode]被有意设计为自由格式 record（OmoOpenCodeHarnessConfigSchema = z.record(z.string(), z.unknown())），而[senpi]、[codex]是严格类型块（config.ts）；
• JSONC 支持：行注释、尾随逗号均被接受，解析基于jsonc-parser的allowTrailingComma: true, disallowComments: false（loader.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：

模型字符串支持内联 reasoning 后缀：规范形式为model:level（如gpt-5.6-sol:max），model (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": { } // 供应商专属透传 }

废弃字段的归一化优先级

normalizeLegacyModelFields（fallback-models.ts）把旧字段映射到新结构，优先级为：reasoning>reasoningEffort>variant>thinking（仅 disabled 时映射为 off）。具体映射关系：

审计特别指出（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_tools；variant/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_tokens；
• model 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_options，thinking/textVerbosity/maxTokens/providerOptions/variant/reasoningEffort全部标记废弃；
• OpenCode 插件侧（agent-overrides.ts）：tools是record<string, boolean>而非数组；mode是枚举subagent | primary | all；color必须是六位十六进制#RRGGBB；ultrawork.reasoning取代ultrawork.variant，agents.oracle.reasoning取代agents.oracle.variant。

审计发现的其他 OUTDATED 事实清单

行为/默认值类修正

配置表不完整类修正

• background_task（background-task.ts）：补充maxDepth、messageStalenessTimeoutMs、taskTtlMs、sessionGoneTimeoutMs、taskCleanupDelayMs、syncPollTimeoutMs、maxToolCalls、circuitBreaker；
• tmux（tmux.ts）：补充isolation（默认inline）及其枚举值；确认enabled默认 false、layout默认main-vertical、main_pane_size默认 60（范围 20..80）、main_pane_min_width默认 120、agent_pane_min_width默认 40；
• runtime_fallback（runtime-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默认 30（0 表示禁用超时升级与message.updated重试检测）、notify_on_fallback默认 true；
• experimental（experimental.ts）：补充preemptive_compaction、plugin_load_timeout_ms、safe_hook_creation、model_fallback_title、max_tools、disable_live_parent_wake_routing；
• dynamic_context_pruning（dynamic-context-pruning.ts）：确认enabled默认 false；notification枚举off/minimal/detailed默认detailed；turn protection 默认开启、3 轮、范围 1..10；deduplication / 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；默认仍为playwright（browser-automation.ts）；
• 内置 MCP：除websearch、context7、grep_app、lsp外，新增内置codegraph（mcp/index.ts），disabled_mcps示例需包含它（mcp/types.ts）；
• codegraph 配置面：完整的插件级键包括auto_init、auto_provision、daemon、enabled、excluded_roots、install_dir、telemetry、watch_debounce_ms；daemon默认 true（schema/codegraph.ts、schema/codegraph.ts（共享层））；
• LSP 相关：LSP_TOOLS_MCP_PROJECT_CONFIG实际是分隔符分隔的搜索列表：.opencode/lsp.json、.omo/lsp.json、.omo/lsp-client.json（mcp/lsp.ts）；LSP_TOOLS_MCP_INSTALL_DECISIONS按 harness 区分——Codex 用CODEX_HOME/lsp-install-decisions.json，OpenCode 注入自身 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-L62）；
• cwd 在 HOME 外：配置遍历继续到文件系统根（见上文"发现规则"）；
• Codex 专属键归位：codegraph.session_start_cooldown_ms不在 OpenCode 插件 schema 中，应归属共享顶层codegraph或[codex].codegraph（config/schema/codegraph.ts）；
• Senpi 与 daemon（omo-json.md:239）：codegraph.daemon=false使 Senpi 使用进程内 CodeGraph 的说法过时——daemon 仅适用于 Codex 与 OpenCode，Senpi 不支持该键。

环境变量与遥测类修正

• OMO_CODEX_DISABLE_POSTHOG：除1/true外，yes同样禁用Codex 遥测；且全局OMO_DISABLE_POSTHOG也会一并禁用 Codex 遥测（telemetry-core/env.ts）；
• OMO_CODEX_SEND_ANONYMOUS_TELEMETRY：0/false/no禁用，且yes目前同样被 telemetry-core 视为 opt-out；
• 确认项：OMO_SEND_ANONYMOUS_TELEMETRY的0/false/no禁用插件遥测；OMO_DISABLE_POSTHOG的1/true/yes禁用插件遥测（posthog.ts）；POSTHOG_API_KEY覆盖内置 API key、POSTHOG_HOST覆盖采集主机（默认https://us.i.posthog.com）（env.ts）。

迁移机制：legacy 配置如何进入统一体系

审计确认的迁移事实（均 CORRECT）：

• 发现范围：迁移会扫描四种oh-my-*基础名（用户 / profile / 项目三层）+~/.omo/config.jsonc（discovery-paths.ts）；
• 映射规则：legacy 用户配置 →[opencode]；profile 差异 →profiles.<name>.[opencode]；项目配置 → 项目.omo/omo.jsonc（transform-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-<timestamp>（migration-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 medium；artistry默认claude-fable-5-1xhigh；quick以kimi-for-coding-highspeed起步；unspecified-high默认kimi-k3 max；writing默认kimi-k3 low（category-model-requirements.ts）。unspecified-low的主列按审计修正为gpt-5.6-terra（xhigh 档 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.ts）；task.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的默认值声明——schema（sisyphus-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 核实。

结论：把源码当作唯一事实基准

这次漂移审计的价值不在于"文档错了多少"，而在于确立了一条可复用的维护纪律：

1. schema 文件是字段与默认值的最高权威——packages/omo-config-core/src/schema/下每个.ts文件即配置契约，新增/废弃字段首先改这里；
2. 行为声明必须落到运行期代码——凡是"默认值""闭集""推断规则"类表述，若 schema 无法证明，就必须引用 loader、resolver 或功能模块的调用点，否则只能写为 UNVERIFIABLE；
3. reasoning统一是当前最大的兼容性断层——任何还在写variant/reasoningEffort/thinking的示例都应更新为规范写法，同时明白它们作为兼容输入仍会被归一化处理（优先级reasoning>reasoningEffort>variant）；
4. 新功能与文档必须同批发布——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