跳到主內容
TechSpecs搜尋

Theme / v0.21.46

Oh My Codex (OMX)

Codex CLI 工作流增強層

主題首頁GitHub ↗
基礎觀念

v0.21.19～v0.21.38：模型設定、Team Readiness 與復原安全

🔴 進階｜掌握 OMX v0.21.19～v0.21.38 patch：third-party provider 模型解析、team readiness deadline、plugin cache 與 mailbox 安全、dispatch 隔離、setup symlink 寫入防護、canonicalization regression 修復、torn journal 復原、v0.21.34 shutdown 無法保存工作時保留 worker worktrees、v0.21.35 修復舊版復原日誌 (legacy recovery journal) 的工作樹 (worktree) 歸屬與平台感知重播 (platform-aware replay)，以及 v0.21.36 讓 native-hook CLI 錯誤日誌改走 omxLogsDir、v0.21.37 npm custom prefix ownership 與 completion-marker diagnostics、v0.21.38 OMX-owned canonical plugin hook trust refresh。含互動測驗與檢查清單。

概述

OMX 在四天內連發十二個 patch release：v0.21.19 與 v0.21.20、v0.21.21、v0.21.22、v0.21.23（2026-10-19），v0.21.24、v0.21.25、v0.21.26、v0.21.27（2026-10-20），v0.21.28（2026-10-21），v0.21.29 與 v0.21.30（2026-10-22）。官方對各版定位皆為 patch release，主軸：agent model configuration 與 third-party provider 修正、team readiness deadline 紀律、plugin cache 修復安全強化、團隊 mailbox 與 dispatch 狀態隔離、其他平台修復。

模型設定與 provider（v0.21.19～v0.21.20，2026-10-19）

v0.21.19（#3824/#3825/#3827/#3829/#3831/#3832）是 agent model configuration 與 third-party provider 修正的 patch release：

  • Third-party provider model pins（#3824，修 #3823）：不再為使用 third-party providers 的 agent 烘焙 exactModel pins，讓 provider 能輪換預設 model 同時保持 agent 可解析。
  • Runtime-inherited model detection（#3825，修 #3822）：omx doctor 的 spark-lane model 檢查對齊 runtime-inherited agent model 行為，消除 omx setup --force 也清不掉的誤報。
  • Profile-scoped model overrides（#3827）：採用 profile-scoped agent model 設定與 override 指引到生成的 agent runtime config。
  • Effective profile model resolution（#3831）：在內建 fallback 之前解析 active profile models；內建 provider 未列 model 時保留 exact pins；provider-only configs 不再宣稱使用 fallback models。
  • Provider classification normalization（#3832）：provider ID 一致正規化——保留大小寫、確保 config 生成、exact pins 與 metadata 之間的匹配行為一致。
  • Final readiness poll（#3829/#3832）：timeout deadline 之前必做最後一次 team readiness poll，timeout 預算用罄時不阻塞啟動。

v0.21.20（#3835）把 readiness 紀律收尾：在最後一次 team worker readiness poll 上強制執行設定的 OMX_TEAM_READY_TIMEOUT_MS timeout——team worker 不得在 deadline 之後回報 ready；Incompatibility markers 維持 fail-closed。

Plugin cache 修復安全（v0.21.22～v0.21.24，2026-10-19～2026-10-20）

這組 release 圍繞 omx setup --plugin --repair-plugin-cache 的建議安全性：

  • v0.21.22（2026-10-19，#3842）：fail-closed cache recovery guidance——修復指令不再建議使用者刪除被 live Codex sessions 釘住的 plugin snapshots 或非目錄條目，改發 fail-closed 指引、導向安全恢復選項。
  • v0.21.23（2026-10-19，#3840/#3846）：generated team tasks 預設要求 evidence 證明 code changes 符合 intent（除非明確標記 analysis、reporting 或 read-only），task decomposition 在 CLI 與 DAG planning 間共享 intent 分類（#3840）；cache recovery guidance 擴及非目錄條目（symlinks 等），無法判定安全時續發 fail-closed 指引（#3846）。
  • v0.21.24（2026-10-20，#3851～#3854）：setup repair 硬化——dry-run 強制驗證 removalSafe 欄位、無法驗證時 fail-closed（#3851）；removalSafe 只從已驗證的 managed+unpinned cache eligibility 推導（#3853）；dry-run 對相同 cache 回傳 unchanged、與實際 repair 行為一致（#3854）；.gitignore 排除 gjc runtime session state（#3852）。

團隊隔離與 dispatch（v0.21.25～v0.21.30，2026-10-20～2026-10-22）

  • v0.21.25（2026-10-20，#3857）：team mailbox isolation hardening——mailbox 建立未獲確認時 fail-closed：runtime 拒絕、持久化失敗、timeout 與無效 acknowledgement 都不再產生 JSON-only mailbox 紀錄；部分持久化的建立事件在配置新 ID 前先 reconciliation，防止團隊範圍內重複 mailbox ID；跨 refresh races 使用同一已驗證 projection 去重。
  • v0.21.26（2026-10-20，#3859/#3862/#3863）：dispatch state isolation 與效能——fallback requests、retries 與 delivery observations 改存各 Team 的 dispatch 目錄，避免 TypeScript writers 覆寫共享的 runtime projections；merged dispatch reader 只補充已證實的 local fallback requests 或 durable finalization receipts，確保 recovery 不重新注入 stale 請求（#3862）；dispatch identity ledger（dispatch-seen.json）改為每次 merge 載入一次，file I/O 從 O(fallbacks) 次讀取降為單次讀取（#3863）；含 zod 4.6.5 → 4.6.7（#3859）。
  • v0.21.29（2026-10-22，#3876）：修復 dispatch retry 與多訊息場景的三個相關回歸——dispatch retry 改用一致且持久的 projections（runtime dispatch event 可能在 JSON projection 發布前 commit，對空的、缺失或 stale projection 重試可能重複、合併或遺留請求）；mailbox wake 的 acknowledge 延後到該 wake 所有訊息都完成，避免 wake 卡住阻斷後續訊息處理；受損或不可讀的 per-worker mailbox 改視為 undeliverable，而非當成空的（過去可能靜默丟訊息、造成 worker 增殖）。另防止 notification payload 在 Codex startup 與 folder-trust UI 階段被渲染，且這兩個畫面不再被誤判為 ready prompt。
  • v0.21.30（2026-10-22，#3879/#3880/#3882）：把 v0.21.29 對主 dispatch path 的修復延伸到次要 monitor path（monitorTeam → deliverPendingMailboxMessages → dispatchPendingMailboxMessage）——monitor 建立的 wake 條件納入與 acknowledgement 相同的 serialization barrier（#3879）；修復 monitor path 上 acknowledgement 與 dispatch 的 race，dispatch requests 在 serialization barrier 內排隊並做最後再驗證（#3880）；實作 stale monitor notification 的偵測與略過，附完整測試證明 race 在主與 monitor 兩條路徑皆已修復（#3882）。

其他修復（v0.21.21、v0.21.27、v0.21.28）

  • v0.21.21（2026-10-19，#3833/#3835/#3837）：POSIX 系統上生成 Windows shim 路徑改用 host paths——setup/uninstall/codex-hooks 的檔案寫入不再產生 \tmp\… 意外條目（#3833）；同版把 readiness deadline 帶入（#3835），並恢復 stale-launcher warning 測試覆蓋、依 provenance 拆分訊息（missing-launcher vs. incompatible provenance，#3837）。
  • v0.21.27（2026-10-20，#3867/#3868）：subagents contract 對 resume_agent 工具改為三態（available / absent / unknown）——不支援該工具的 host 在 SessionStart reopen guidance 得到準確的 fallback 指引，而非被當成 unknown；unknown 時採保守 recovery 行為。tri-state 接入 native hook contract 與 subagents tracker，回應 issue #3866。
  • v0.21.28（2026-10-21，#3873）：JetBrains 終端機 trackpad scrolling 診斷——macOS WebStorm 等 JetBrains IDE 終端機會把 trackpad 捲動轉成上下方向鍵，alternate screen mode 開啟時會把先前的 prompt 填入輸入框而非捲動輸出。新增 startup 診斷，偵測 JetBrains 環境（檢查 TERM_PROGRAM 與 TERMINAL_EMULATOR），對直接（非 tmux）與 hotswap 啟動建議 omx --no-alt-screen workaround；已指定 --no-alt-screen 時不發出。修 #3872。
隨堂測驗

v0.21.20 對 team worker readiness poll 加上了什麼紀律？

💡 想先看個提示？

關鍵詞是「the final team worker readiness poll」。

動手升級檢查清單

升級 v0.21.30：動手檢查清單

逐項勾選，確認你已完成升級必要的步驟（進度會保存在此瀏覽器）

0 / 5

Setup 路徑安全、journal 復原與 shutdown 保留（v0.21.31～v0.21.36）

這組 patch releases 延伸前述 setup、dispatch 與 shutdown 安全工作。焦點包括寫入前拒絕 symlink 目的地、修正嚴格路徑檢查誤拒合法 symlink scope、從不完整的 journal append 中保留可復原紀錄、在 shutdown 無法保存工作時保留 worker worktrees、修復 legacy recovery journal 的 worktree 歸屬與平台感知 replay，以及讓 native-hook CLI 錯誤日誌改走設定的 OMX 日誌目錄。

omx setup 會在讀取、備份或寫入 managed destination 前檢查 symlink，包含 dangling links。檢查會逐一驗證路徑元件，避免目的地的父目錄是 symlink 時繞過保護。原文列出的寫入範圍包括 .gitignore、native agent TOMLs 與 manifest、HUD config、skill receipt。若受管理路徑是 symlink，setup 會 fail closed 並回報錯誤。

v0.21.32：canonicalize 後再比較 scope

v0.21.31 的嚴格路徑字串比較會把 HOME 或 CODEX_HOME 經過 symlink 的合法 scope 判成「outside managed scope」。v0.21.32 在比較前 canonicalize scope paths，恢復 symlink ancestor 環境下的合法設定；同時保留拒絕 symlink managed destination 的行為。project-scope .codex 與 OMX_ROOT 也改按各自的 root boundary 驗證。

v0.21.33：從 torn journal line 保留有效紀錄

Team dispatch finalization 的 runtime-finalizations.jsonl 若在 append 中途遇到 crash，尾端可能只剩截斷 JSON。新 parser 會略過格式錯誤的行，繼續取出有效 finalization commands；新紀錄前加換行分隔，避免受損尾端連帶遮蔽之後的紀錄。此修復針對 runtime reconciliation 的 journal 復原，不改 dispatch API contract。

v0.21.34：shutdown 失敗時保留 worker worktrees

Team runtime 的 shutdown 若無法保存工作——checkpointing（檢查點）失敗、merge 失敗，或工作目錄含 ignored files——過去仍會刪除 worker worktrees，recovery state（復原狀態）隨之遺失。v0.21.34（#3896，@shenyankm 貢獻，修 #3897）在這些失敗情況下不再刪除 worktrees，讓下一次 run 可以帶著完整狀態重試。submodules、report provenance 與部分 pane/prompt cleanup 仍獨立進行——單一元件的失敗不再連帶觸發 worktree 刪除。官方相容性說明：無 breaking API changes，shutdown 韌性改善，不改 shutdown API contract；既有 session 不受影響，除非曾遇到帶 ignored files 或 checkpointing 錯誤的 shutdown 失敗。

v0.21.35：legacy recovery journal 的歸屬與平台感知 replay

v0.21.35 是修補版 (patch release)，修復舊版復原日誌 (legacy recovery journal) 的歸屬與平台感知重播 (platform-aware replay) 邏輯。此版本處理 v0.21.34 關機保留 (shutdown preservation，#3896) 引入的問題：其他 worker 的 legacy recovery journal 可能阻塞健康 worker 的 shutdown。

  • RESILIENCE：worktree 範圍的 journal recovery（#3903，@shenyankm）：其他 worker 擁有的待處理 legacy（陣列格式 (array format)）recovery journal，不再使健康 worker 的 shutdown 因 shutdown_worktree_preservation_failed 而失敗。這修復 v0.21.34 #3896 引入的回歸。
  • SAFETY：平台感知的 legacy journal 歸屬（#3904）：以 .. 開頭的 legacy journal 名稱不再被視為父層路徑穿越 (parent traversal)；平台感知的歸屬檢查阻止跨 worker journal 汙染。
  • MODULE ISOLATION：僅模組重播（#3904）：legacy journal replay 僅對 modules 執行，避免設定錯誤的 legacy journal 造成狀態損壞。

官方相容性說明原文為：「No breaking API changes; recovery robustness improvements only.」曾在 v0.21.34 遇到 recovery journal 阻塞 shutdown 的 team runtime 使用者，本版修復此問題。

v0.21.36：native-hook CLI 錯誤日誌改走 omxLogsDir

v0.21.36（2026-10-25 發布）是 patch release，將 native-hook 的 CLI 錯誤診斷路由到設定的 OMX 日誌目錄。

  • NATIVE HOOK LOGGING（#3909，修 #3908）：CLI 錯誤診斷改用設定的 omxLogsDir——依 OMX_ROOT 與 OMX_STATE_ROOT 解析，不再一律寫到專案工作目錄底下。
  • 優先序：OMX_ROOT 優先於 OMX_STATE_ROOT；兩者皆未設定時，日誌行為不變，續用專案 .omx/logs 目錄。
  • 相容性：官方明言「No breaking API changes」。
  • 已知問題：#3898（live-pin 修復）仍卡在 owner 設計決策；在 Codex 0.164.0 上，plugin cache 中的 .omx-live-pin 檔案可能使 hook approval 失效——#3898 提供的 workaround 是停用 oh-my-codex-local plugin。

全域安裝偵測與 plugin-cache 診斷（v0.21.37，2026-10-27 UTC／2026-10-28 Asia/Taipei）

v0.21.37 是修補版，於 2026-10-27 18:41 UTC 發布，台北時間為 2026-10-28 02:41。

  • npm 自訂全域前綴的安裝歸屬辨識 (custom prefix ownership)（#3922，修 #3920）：當 npm 使用與 Node runtime path 不同的自訂 global prefix 時，正確辨識 npm 管理的全域安裝。ownership validation 仍採 fail-closed。
  • 完成標記診斷 (completion-marker diagnostics)（#3923，修 #3921）：setup／doctor 現在區分格式錯誤的 completion marker、marker 版本不符與 claim digest 不符。這項變更僅改善診斷，不改變 provenance semantics。
  • 相容性：沒有 breaking API changes。MCP SDK runtime dependency 更新至 1.32.2，Biome development dependency 更新至 2.6.2。
  • 已知問題仍存在：#3898 live-pin 修復仍待 owner design decision；在 Codex 0.164.0，plugin cache 的 .omx-live-pin 可能使 hook approval 失效。#3924 尚在 review、未包含於此版，預計稍後發布。

OMX 所屬外掛掛鉤的信任紀錄更新 (plugin hook trust refresh)（v0.21.38，2026-10-27 UTC／2026-10-28 Asia/Taipei）

v0.21.38 是修補版，於 2026-10-27 22:37 UTC 發布，台北時間為 2026-10-28 06:37。

plugin cache rebuild 後，setup refresh 會從 canonical OMX plugin-scoped Codex hook trust records 移除過期的 trusted hashes，避免因舊記錄而以 managed_trust_key_conflict 失敗（#3924，修 #3918）。此自我修復只適用於 OMX 擁有的 canonical plugin hook trust records；第三方或格式錯誤的 trust state 仍 fail-closed。官方相容性說明為沒有 breaking API changes。

v0.21.38 的 known issues 仍列出 #3898 live-pin 修復待 owner design decision；Codex 0.164.0 下 .omx-live-pin 可能使 hook approval 失效，workaround 仍是停用 oh-my-codex-local plugin。這和本版處理的 OMX-owned canonical trust records 是不同問題，不能視為 #3898 已修復。

隨堂測驗

v0.21.32 如何修正 v0.21.31 在 symlink-heavy scope 上誤拒合法 setup 的回歸？

💡 想先看個提示？

修正的是 comparison 前的 path representation。

升級 v0.21.38：動手檢查清單

逐項勾選，確認你已完成升級必要的步驟（進度會保存在此瀏覽器）

0 / 8