LazyCodex 与 Codex 如何协作

01 · Executive summary

先说结论：它是 Codex 的扩展层，执行内核仍由 Codex 提供

OpenAI Codex 继续提供模型、会话、审批、沙箱和工具执行内核；LazyCodex / OMO 把可安装的工作流、生命周期脚本、MCP server、角色配置和本地状态挂到 Codex 的插件与 Hook 扩展点上。

02 · Freshness model

“在哪里”与“还能信多久”必须一起读

同一个路径事实可能很稳定，也可能下一次启动就变化。本文把时效拆成六级，避免把安装配置、会话暴露和网络连通性混成一个“可用/不可用”。

03 · Ownership boundary

四个名字，四种所有权

“LazyCodex”“OMO”“oh-my-openagent”“Codex”分属发行、插件、核心上游与宿主层。区分这些所有权，才能判断一个问题该改配置、重装插件、向 LazyCodex 报告，还是追到 OpenAI Codex。

04 · Runtime lifecycle

从一条 Prompt 到 Stop：真正的协作时序

OMO 仅在明确事件点注入上下文、执行检查或提示续跑；其余推理和工具调用由 Codex 完成。

05 · Disk layout

安装后到底写了什么

本机插件根目录包含 2,180 个普通文件和 16 个 symlink，约 466 MiB；大部分体积来自 node_modules/。顶层语义远比体积更重要。

/home/jingyijun/.codex/
├── config.toml                              # plugin、MCP、trust、agents 注册
├── hooks.json                               # 用户自定义 Hook，不属于 OMO
├── hooks/
│   ├── memory_stop.py
│   ├── memory_worker.py
│   └── memory_schema.json
├── agents/*.toml                            # 10 个物化 role
├── backups/pre-lazycodex-20260710-170805/   # 安装前备份
└── plugins/
    ├── cache/sisyphuslabs/omo/4.16.2/       # 插件 payload 根
    │   ├── .codex-plugin/plugin.json        # 必需入口
    │   ├── .mcp.json                        # 5 个 MCP server
    │   ├── hooks/*.json                     # 21 个 Hook 文件
    │   ├── skills/*/SKILL.md                 # 25 个顶层 Skill
    │   ├── components/                       # 15 个安装组件
    │   ├── dist/                             # 聚合 CLI runtime
    │   ├── scripts/                          # 安装、同步、自动更新
    │   └── node_modules/                     # bundled runtime dependencies
    └── data/omo-sisyphuslabs/                # 可变插件数据
        ├── auto-update.json / .log
        ├── bootstrap/
        ├── daemon/v0.1.0/
        └── sessions/

/home/jingyijun/.local/bin/                  # 12 个插件 CLI symlink
/home/jingyijun/.omo/                        # CodeGraph 与 OMO 用户状态
└── codegraph/projects/workspace-63f57d842c75bdea/codegraph.db

06 · Plugin entry

plugin.json 是所有协作面的路由表

Codex 不会递归猜测 OMO 的所有目录。它从 manifest 读取 Skills、Hooks 和 MCP 的声明，再由 loader 解析相对路径、创建插件数据根并交给对应子系统。官方插件文档也规定 .codex-plugin/plugin.json 是必需入口。[S2][S10]

{
  "name": "omo",
  "version": "4.16.2",
  "skills": "./skills/",
  "hooks": [
    "./hooks/session-start-loading-project-rules.json",
    "... 18 more registered files ..."
  ],
  "mcpServers": "./.mcp.json"
}

07 · Codex internals

一次 Hook 执行包含发现、信任、并发与输出解析

Codex 先发现并规范化 Hook，再判断 matcher、enable 和 trust，之后并发启动同步 command，最后按事件解析输出。下面每一步都有具体源码位置。

08 · OMO lifecycle hooks

21 个文件，4.16.2 实际注册 19 个

Codex 只发现 manifest 已注册的文件。4.16.2 manifest 漏掉了 Git Bash reminder 的 PreToolUse 和 PostCompact reset；4.16.3 已把二者补入 manifest。

09 · Reusable workflows

25 个 Skill 编排“如何做”，动作交给工具执行

Skill 的 description 决定何时被选择，完整 SKILL.md 决定步骤、引用、脚本和验收。Skill 可以要求调用 MCP、CLI 或 Agent，但它本身只是 Codex 读取的工作流包。[S3]

10 · Agent roles

Agent role 的源文件、物化与注册

10 个 role 的源 TOML 位于插件 components/ultrawork/agents/。安装器将它们复制到 ~/.codex/agents/，再在 config.toml [agents.*] 中注册。源文件与 materialized 文件的 SHA256 全部一致。

11 · MCP and CLI

5 个 MCP server、17 个已知 MCP tool、12 个插件 CLI link

“配置里启用”只代表 Codex会尝试启动；“本会话暴露”才代表当前线程已拿到工具 schema；远程 endpoint 的工具集还可能由服务端动态变化。

12 · Components

15 个已安装组件，4.16.3 多出 lsp-tools-mcp

组件是 Hook、MCP、CLI 与 Skill 的实现载体。它们在源码中可独立维护，但最终被聚合成一个 OMO plugin namespace。

13 · State and trust

代码之外，还有一层会变的状态面

诊断 LazyCodex 时，不能只看 cache payload。trust、updater throttle、daemon endpoint、CodeGraph index 和 telemetry 都在插件根之外。

14 · Install, update, rollback

版本检查能发现更新，升级提示仍可能失效

本机上一次成功检查启动了 24 小时节流，4.16.3 恰好在窗口内发布；与此同时，release note 推荐的 marketplace 命令与本机 local source 模式不兼容。

15 · Version delta

4.16.3 共改变 110 个路径，涉及注册、路由与工作流

对 LazyCodex 固定 tag v4.16.2..v4.16.3 的 plugins/omo/ 做源码 diff，共 110 个路径变化。

16 · Doctor verdict

健康度结论：安装完整性 PASS，工作流状态 WARN

插件 payload 与最小运行探针通过；版本落后一版、更新提示不匹配、一次远程 MCP 启动降级及四项公开已知问题，使“所有工作流均可用”这一更强结论无法成立。

17 · Security and privacy

风险集中在新增的可执行边界

Hook command、MCP server、CLI link 和 Agent role 都扩展了 Codex 的行为面，应按代码依赖审查其来源、权限、数据流和更新方式。

18 · Full inventory

完整 2,196 行文件与 symlink 搜索器

清单覆盖插件根下 2,180 个普通文件和 16 个 symlink，每行包含相对路径、绝对路径、对象类型、link target、target 是否存在、大小、mtime、SHA256、顶层类别和时效范围。

滚动到本节或使用搜索器时加载 installed-files.tsv…

cd /home/jingyijun/Projects/workspace/research/lazycodex-codex-integration-study
python3 -m http.server 8766 --bind 127.0.0.1

# 浏览器打开
http://127.0.0.1:8766/reports/2026-07-11-lazycodex-codex-integration.html

19 · Sources and reproduction

来源、固定版本与复验命令

本报告优先使用本机实证、OpenAI 官方文档、固定 release 源码和 LazyCodex / OMO 固定 tag。临时 checkout 路径只用于本次研究，永久引用使用 commit-pinned URL。

1. [S1]OpenAI Codex Advanced Configuration

   Hook 来源、项目层信任、JSON 与 inline TOML。研究快照 SHA256：c9703f7d…518f28。

2. [S2]OpenAI Build plugins

   plugin structure、manifest path rules、Skills/MCP/Hooks、PLUGIN_ROOT/PLUGIN_DATA。SHA256：0716a152…573c6。

3. [S3]OpenAI Customization

   AGENTS、Skills、MCP、Subagents 与组合边界。SHA256：6a855fee…2edd2d70。

4. [S4]OpenAI Configuration Reference

   features.hooks、command-only 支持状态、MCP 字段。SHA256：e3e8c202…2796da5。

5. [S5]Codex 0.144.1 Hook discovery.rs

   来源合并、plugin env、matcher validation、async/prompt/agent skip、timeout、hash 与 trust。

6. [S6]Codex 0.144.1 dispatcher.rs

   FuturesUnordered 并发启动和结果排序。

7. [S7]Codex 0.144.1 command_runner.rs

   cwd、stdin、stdout/stderr、timeout、shell invocation。

8. [S8]Codex 0.144.1 events/common.rs

   哪些事件保留 matcher，以及 exact / pipe / regex 匹配。

9. [S9]Codex hooks feature

   canonical key 为 hooks、Stable、default enabled；legacy alias 在 features/src/legacy.rs。

10. [S10]Codex plugin manifest parser

    插件 manifest 与 loader / manager 的源码边界。

11. [S11]LazyCodex v4.16.3 release

    commit bb8764ca1754148ca56478d433c42b91c550e0f4，发布于 2026-07-10T14:06:12Z。

12. [S12]oh-my-openagent v4.16.3 release

    commit c0af948da3d21ae4e843ec9b555bc883b042342b。

13. [S13]npm registry：lazycodex-ai@4.16.3

    registry 发布时间 2026-07-10T14:03:50.500Z；固定版本 JSON 端点在研究时返回 200。

14. [S14]本报告来源与证据台账

    官方 Markdown SHA、版本 commit、运行时探针、更新链路与不确定性记录。

15. [S15]研究简报

    范围、范围边界、必答问题、来源优先级和时效要求。

16. [S16]最终 HTML 运行时审计

    三项调试假设、浏览器交互、CJK 修复、Lighthouse 因果实验和清理记录。

17. [S17]结构化证据校验结果

    2,196 个插件对象和全部 TSV 路径、类型、大小、SHA256、相对链接的复验结果。

18. [S18]真实 Chrome 浏览器 QA JSON

    320 / 375 / 768 / 1280 四档 overflow、动态加载、搜索、过滤、复制、clipboard、快捷键、目录与 disclosure 证据。

19. [S19]Lighthouse 生产式预览结果

    移动/桌面各 3 次；Performance、Accessibility、Best Practices 中位数均为 100。

20. [S20]Codex Hook trust bypass CLI

    --dangerously-bypass-hook-trust 仅面向已自行审查 Hook 来源的自动化；固定到本机 0.144.1 release commit。

21. [S21]Codex Hook startup review

    TUI 明示 trusted Hooks 可以在沙箱之外运行；固定到本机 0.144.1 release commit。

22. [S22]LazyCodex issue #119

    OMO 4.16.2 teammode 与 Codex CLI 0.144.1 缺失 codex_app.* thread tools 的兼容性问题。

23. [S23]LazyCodex issue #123

    SessionStart 配置迁移可能把 GPT-5.5 profile 写入缺少根模型设置的项目配置。

24. [S24]LazyCodex issue #124

    $omo:ulw-plan 与通用 Ultrawork 关键词 Hook 的确定性触发碰撞。

25. [S25]LazyCodex issue #125

    GPT-5.6 PostCompact 使用 200K fallback；issue 中包含已验证、尚未进入固定 tag 的修补方案。

26. [S26]OMO install permissions.mjs

    固定到 LazyCodex src gitlink commit；autonomous 权限写入的逐行证据。

27. [S27]OMO install cli-args.mjs

    权限参数位于 34-42；uninstall 映射位于 100-102。

28. [S28]OMO install-local.mjs

    默认 autonomous 条件与配置更新入口，固定到 gitlink commit。

29. [S29]OMO codex-cleanup.ts

    卸载时的配置修复、cache 删除与托管 Agent link 清理。

# 版本与入口
codex --version
command -v codex
jq .version /home/jingyijun/.codex/plugins/cache/sisyphuslabs/omo/4.16.2/.codex-plugin/plugin.json

# Hook / Skill / Agent / MCP 数量
find /home/jingyijun/.codex/plugins/cache/sisyphuslabs/omo/4.16.2/hooks -name '*.json' | wc -l
find /home/jingyijun/.codex/plugins/cache/sisyphuslabs/omo/4.16.2/skills -mindepth 1 -maxdepth 1 -name SKILL.md | wc -l
find /home/jingyijun/.codex/agents -name '*.toml' | wc -l
jq '.mcpServers | keys' /home/jingyijun/.codex/plugins/cache/sisyphuslabs/omo/4.16.2/.mcp.json

# 更新 dry-run；不会改安装
npx --yes lazycodex-ai@4.16.2 update --dry-run

# 最小真实运行
codex exec --skip-git-repo-check --json \
  'Reply exactly LAZYCODEX_RUNTIME_OK. Do not use tools.'