OmX 0.17.3 热修复深度解析：恢复 Codex CLI-first/Plugin 配置下的 Team 默认启动与 Worker MCP 隔离

OmX 0.17.3 热修复深度解析：恢复 Codex CLI-first/Plugin 配置下的 Team 默认启动与 Worker MCP 隔离

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex

导读

本文围绕 OmX（Oh My codeX）0.17.3 热修复版本展开，核心主题是恢复 Codex CLI-first/plugin 配置下omx team的默认启动能力，同时完整保留 0.17.1 引入的 worker MCP 隔离机制。读完本文，你将掌握OMX_TEAM_WORKER_MCP_COMPAT逃生舱口的正确用法、Team worker 启动时 MCP 禁用覆盖（override）的底层判定逻辑，以及如何用仓库内置测试与冒烟命令验证这一兼容性修复。

背景：0.17.1 的 worker MCP 隔离与 0.17.3 的回归

0.17.1 引入了一项安全设计：OmX Team 在拉起 Codex worker 时，默认禁用 OMX 第一方 MCP 服务器，避免 worker 与 leader 竞争同一组 MCP 通道。这套"worker MCP 隔离"通过向 Codex worker 的启动参数中追加mcp_servers.<name>.enabled=false覆盖实现。

然而该实现在 0.17.2 之后的 Codex 版本上暴露了一个兼容性问题：当用户使用CLI-first 或 plugin 配置（CODEX_HOME/config.toml中并未声明任何 OMX 第一方 MCP 服务器表）时，Team 启动逻辑仍会为 worker 合成这些 MCP 服务器表，导致当前 Codex 在启动阶段直接报invalid transport错误——worker 尚未就绪，Team 就已失败。这正是 0.17.3 作为0.17.2之后的 hotfix 要解决的核心问题：不凭空捏造 Codex 配置中不存在的 MCP 服务器表，同时保留对"传统配置（legacy config）中已显式声明这些服务器"场景的默认禁用行为。

根因：为不存在的服务器表注入 enabled=false

从源码看，0.17.3 之前的问题出在禁用覆盖的生成条件上。在 src/team/tmux-session.ts 中，Team 维护了一份需要默认禁用的第一方 MCP 服务器清单：

const TEAM_WORKER_DISABLED_OMX_MCP_SERVERS = [ 'omx_state', 'omx_memory', 'omx_code_intel', 'omx_trace', 'omx_wiki', 'omx_hermes', ] as const;

（对应 src/team/tmux-session.ts）

如果这段逻辑无条件遍历清单并为每个服务器追加mcp_servers.<name>.enabled=false，那么当config.toml中压根没有这些表时，Codex 就会看到一张"被引用的服务器表不存在"的配置，从而以invalid transport拒绝启动。0.17.3 的修复要点正是把"是否追加"从"总是追加"改为"仅当用户配置中已声明该服务器时才追加"。

修复实现：声明式探测 + 有条件的覆盖注入

0.17.3 的修复落在 src/team/tmux-session.ts 的四个函数上，形成了完整的判定链路：

1. 兼容开关判定shouldDisableOmxMcpForTeamWorker（src/team/tmux-session.ts）：读取OMX_TEAM_WORKER_MCP_COMPAT环境变量，只有取值为1、true、on、compat时才抑制禁用逻辑，其余任何取值（含未设置）都保持默认禁用行为。

2. 配置路径解析resolveCodexConfigPath（src/team/tmux-session.ts）：优先使用CODEX_HOME环境变量，未设置时回退到~/.codex，最终定位config.toml。

3. 表存在性探测codexConfigDeclaresMcpServer（src/team/tmux-session.ts）：用正则^\s*\[\s*mcp_servers\s*\.\s*(?:"name"|'name'|name)\s*\]\s*$逐行匹配config.toml，同时兼容带引号与不带引号的 TOML 表名写法；文件缺失或读取失败一律视为"未声明"。

4. 覆盖注入appendTeamWorkerMcpDisableOverrides（src/team/tmux-session.ts）：遍历六服务器清单，仅对"已在 config.toml 声明"且"启动参数中尚未存在同名 override"的服务器，在--分隔符之前插入-c mcp_servers.<name>.enabled=false。

值得注意的是，这一覆盖只作用于Codex worker：在buildAttachedTmuxWorkerStartupPlan（src/team/tmux-session.ts）中，仅当processSpec.workerCli === 'codex'时才调用appendTeamWorkerMcpDisableOverrides，Claude/Gemini worker 不参与此逻辑。

六服务器隔离清单与 legacy 配置的默认行为

修复后存在两种明确区分的场景：

• CLI-first/plugin 配置（config.toml不含任何第一方 OMX MCP 表）：Team worker 不再收到任何mcp_servers.<omx>.enabled=false覆盖，worker 可正常就绪，omx team恢复默认启动。
• legacy 配置（config.toml仍显式声明omx_state、omx_memory、omx_code_intel、omx_trace、omx_wiki或omx_hermes）：Team 依旧默认对 Codex worker 禁用这些服务器，0.17.1 的隔离语义保持不变。

这套行为被 src/team/tests/tmux-session.test.ts 的三组测试完整锁定：

• does not synthesize absent first-party OMX MCP server tables for Codex team workers（src/team/tests/tmux-session.test.ts）：构造只含mcp_servers.gitnexus的config.toml，断言生成的 worker 启动命令中六个服务器均不出现enabled=false。
• disables configured first-party OMX MCP compatibility servers for Codex team workers by default（src/team/tests/tmux-session.test.ts）：在 config.toml 显式声明六个服务器后，断言每个服务器都出现enabled=false。
• recognizes every MCP config spelling before -- and inserts generated overrides before positional suffixes（src/team/tests/tmux-session.test.ts）：验证-c、--config、-c=、--config=四种拼写均被识别，且用户显式传入的enabled=true不会被覆盖。

OMX_TEAM_WORKER_MCP_COMPAT：显式逃生舱口

对于确实需要在 Team worker 中启用第一方 OMX MCP 服务器的高级用户，0.17.3 保留并重申了显式 opt-in 变量：

export OMX_TEAM_WORKER_MCP_COMPAT=1 # 或 true / on / compat

只要该变量取值为上述四种之一，shouldDisableOmxMcpForTeamWorker即返回假，Team 完全不再追加任何 worker MCP 禁用覆盖（参见 src/team/tmux-session.ts 与测试 src/team/tests/tmux-session.test.ts）。注意：这只代表"不强制禁用"，不代表 OmX 会替你声明这些服务器——config.toml 中不存在的表依旧不会被创建。

顺带搭车：AGENTS 契约覆盖保护与元数据对齐

0.17.3 的对比区间还带上了两条dev分支上已就绪的加固提交：

• AGENTS 契约覆盖保护（commit906b37ec）：当工作区缺少完整 OMX 契约标记时，不再静默覆盖已有AGENTS.md内容。相关实现可参见 src/cli/agents-init.ts：OMX 管理的文件带有<!-- OMX:AGENTS-INIT:MANAGED -->标记（src/cli/agents-init.ts），对未管理的AGENTS.md默认跳过，只有显式传入--force才会在备份后接管（src/cli/agents-init.ts）。
• 插件元数据对齐与 question 返回注入测试隔离（commit318bd2e6）：对齐插件元数据，并隔离 question 返回注入相关测试，避免测试间状态串扰。

验证证据与复现步骤

0.17.3 的发布验证覆盖构建、单测、静态检查与两条真实 Team 冒烟启动：

# 1. 构建 npm run build # 2. worker MCP 隔离核心单测 node --test dist/team/__tests__/tmux-session.test.js # 3. 未使用代码检查 npm run check:no-unused # 4. 默认启动冒烟（无 compat 变量，验证修复生效） OMX_TEAM_READY_TIMEOUT_MS=12000 OMX_TEAM_STARTUP_EVIDENCE_TIMEOUT_MS=1500 ./dist/cli/omx.js team 1:explore "default smoke launch fixed" # 5. 兼容模式冒烟（显式 opt-in 仍需正常工作） OMX_TEAM_WORKER_MCP_COMPAT=1 OMX_TEAM_READY_TIMEOUT_MS=12000 OMX_TEAM_STARTUP_EVIDENCE_TIMEOUT_MS=1500 ./dist/cli/omx.js team 1:explore "compat smoke launch still fixed"

其中OMX_TEAM_READY_TIMEOUT_MS与OMX_TEAM_STARTUP_EVIDENCE_TIMEOUT_MS控制 Team 就绪判定与启动证据收集的超时窗口，这两条冒烟命令在 CHANGELOG.md 中有对应记录。

关于就绪语义的重要提示：0.17.3 并未放宽 Team 的就绪语义——若 worker 启动失败，Team 仍会如实报告失败，而不会伪装成"已启动"。修复只消除"因合成 MCP 表导致的启动前失败"，不掩盖任何真实的 worker 故障。

升级与排查建议

• 升级后无需改动配置即可恢复omx team默认启动；若你的config.toml显式声明了六个第一方服务器，worker 默认仍被隔离，这是预期行为。
• 若升级后 worker 依旧报invalid transport，请检查CODEX_HOME指向的config.toml中是否存在残缺的[mcp_servers.*]表（例如只写了表名但没有command），0.17.3 只负责"不为不存在的表注入覆盖"，不负责修复用户配置本身的语法错误。
• 需要 worker 访问第一方 MCP 服务器时，按上文设置OMX_TEAM_WORKER_MCP_COMPAT后重启 Team。

总结

0.17.3 是一次小而精准的兼容性热修复：它把"worker MCP 隔离"从"无条件合成覆盖"收敛为"仅对已声明配置生效的有条件覆盖"，在保住 0.17.1 安全语义的同时，让 CLI-first/plugin 形态的 Codex 配置重新获得默认的omx team启动能力，并以四组测试与两条真实冒烟命令锁定了这一行为边界。

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex