codex-keysmith：先预覽再改寫 Codex 全局指令

一個文件、一個指令文件、每個新會话 · jia-ethan-codex-keysmith-deep-analysis

codex-keysmith 是一個零依赖的單文件 Python 脚本，將指令 Markdown 文件部署到 Codex 配置目錄中，使每個新的 Codex 會话都會加载它。它默認以预覽模式运行，只有在明確確認後才寫入磁盘；每次部署都可以撤销。該工具编辑 ~/.codex/config.toml 中的顶層 model_instructions_file，這會改变 Codex 的全局行為，而非項目级設置。README 警告這是一個广泛的行為改变，而非安全邊界，並建议在使用前阅讀附带的示例提示 examples/gpt-unrestricted.md，或使用 --file 提供你自己的文件。快速入門說明要求你下载發布文件、驗證 SHA256SUMS，並永远不要從漂浮的 main 分支安装或把 curl 輸出直接管道給 Python。

README 也把版本來源、發行資產和安全文件分開處理。下載 v0.3.9 的單檔案 CLI 時，應同時取得 SHA256SUMS，使用 shasum -a 256 -c - 驗證後再執行 --version。這個檢查能確認檔案沒有在傳輸途中被改動，但不會替你判斷提示詞內容是否適合全域使用。部署完成後必須開啟新的 Codex 工作階段，因為舊工作階段不會重新讀取 config.toml。

部署涉及哪些文件 · jia-ethan-codex-keysmith-deep-analysis

部署會寫入四個位置：指令 Markdown 文件（默認是 gpt-unrestricted.md，或自定義 --name）、config.toml（僅顶層 model_instructions_file）、hooks.json（默認重命名為 hooks.json.disabled，先备份），以及清單文件 .codex-keysmith-manifest.json，它记錄部署所做的更改，以便日後卸载。README 的文件表列出了每個路径發生的具體操作。該工具只拥有 model_instructions_file 键；其他配置字段的外部改寫不會阻止状態检查或卸载，並在卸载後保留。如果省略 --codex-dir，工具會處理所有自動發現的目錄，README 表示這僅應在有意的多目錄部署時進行。部署後，必須關闭旧的 Codex 任務並启動新會话，因為配置只在會话启動時讀取。

若使用 --name 指定指令檔名稱，應把它與 config.toml 的 model_instructions_file 一起記錄，避免解除安裝時誤認其他檔案屬於工具。--skip-hooks-isolation 只改變 hooks.json 的隔離策略，並不會縮小全域提示詞的作用範圍；這兩個選項要分開評估。

將 CCSwitch 配置文件用作激活開關 · jia-ethan-codex-keysmith-deep-analysis

README 描述了一個使用 CCSwitch 配置文件作為激活開關的工作流程。由於 CCSwitch 會為每個提供商替换完整的 config.toml，你可以保留一個開启 Keysmith 的副本，和一個没有 model_instructions_file 的副本。步骤包括检查該字段的 Common Config Snippet，如果钩子不應成為全局副作用则使用 --skip-hooks-isolation 部署，並用 --status 驗證。關闭副本應报告 inactive-by-config。README 還指出，卸载後需要在 CCSwitch 正常模式下切换离開已清理的開启副本，检查是否有"outgoing provider backfill failed"警告，並检查該副本存储的配置。該工作流程已针對 CCSwitch v3.18.0 驗證，但代理接管熱切换可能會從提供商的有效配置重建實時配置，因此 Keysmith 不將其视為穩定的兼容性契约。配置切换只影响新會话，绝不會随之切换 hooks.json。

CCSwitch 的案例也提醒一個實務邊界：切換設定檔只影響新啟動的 Codex 工作階段，hooks.json 不會隨提供者設定自動切換。若看到 outgoing provider backfill failed，應回到 CCSwitch 儲存的副本確認，而不是直接手改即時 config.toml。完成檢查。

撤销，以及运行中斷時會發生什么 · jia-ethan-codex-keysmith-deep-analysis

卸载每次运行只移除最新一層部署，因此重復运行可以逐層回退。有两個命令：--restore-hooks 只恢復 hooks.json，--uninstall 同時移除配置、指令和钩子。两者都支持预覽和 --yes 確認。如果运行被硬中斷（SIGKILL 或斷电），README 建议先运行 --status；如果报告 blocked，则预覽 --recover 並確認。它明確警告不要手動删除任何 .codex-keysmith-transaction-* 目錄、备份或清單。缺失 model_instructions_file 時，只讀状態會报告為 inactive-by-config，但在活動配置文件恢復托管引用之前，部署和卸载仍會失败關闭。目標不同、目標字段歧義或不支持的語句結構仍属於冲突。

支持的环境和 Windows 缺陷 · jia-ethan-codex-keysmith-deep-analysis

README 推荐 Python 3.10 至 3.14，並表示已针對 codex-cli 0.144.1 驗證。macOS 和 Linux 是主要支持范围。Windows 在發布的 v0.1.0 中有一個已知缺陷：os.utime 失败後接着出現第二次 PermissionError，留下旧脚本無法恢復的日志。v0.1.1 及更高版本在 EXPLICIT_BETA 下包含了重寫的 Windows 文件系统後端，可用但尚未正式支持。如果 v0.1.0 在 Windows 上留下了日志，恢復顺序是 --status、--recover 预覽、--recover --yes，然後 --status；切勿手動删除證據。該工具是單文件 CLI，没有 pip install 或自動更新器，备份和卸载存檔不會自動清理。完整限制、事務保證和维护者驗證在 docs/reference.md 中。

許可證和问題报告渠道 · jia-ethan-codex-keysmith-deep-analysis

該項目以 MIT 許可證發布，允許使用、復制、修改、合並、出版、分發、再許可和出售，前提是包含版权声明和許可声明。許可證文本說明軟件按"原樣"提供，不提供任何担保，作者不對索赔、损害或其他责任负责。README 指示通過 SECURITY.md 中的私有渠道报告漏洞，並要求贡献者在提交前阅讀 CONTRIBUTING.md。該項目還接受 LINUX DO 社区的监控和反馈。README 没有提及這些文檔之外的任何具體安全保證、支持承诺或生產就绪性；許可證的免责声明是唯一關於责任的正式陈述。

狀態輸出如何協助排錯

codex-keysmith 的 --status 是部署後最直接的觀察入口。它會指出 model_instructions_file 是否仍由工具管理，也能辨識 inactive-by-config 這類設定狀態。當部署或解除安裝被 SIGKILL 或斷電打斷，README 要求先查看 status，再以 --recover --dry-run 預覽可處理的交易；確認目標、備份與清單沒有衝突後，才使用 --recover --yes。這些步驟依賴 .codex-keysmith-transaction-*、備份檔和 .codex-keysmith-manifest.json 的證據，不能把它們當成可任意清理的暫存檔。

從 v0.3.9 起，--reactivate 只補回遺失的頂層 model_instructions_file，適用於 status 顯示 inactive-by-config 的情況；它不是完整重新部署，也不應拿來替代 --uninstall。Windows 若曾使用 v0.1.0 並留下 PermissionError，應按 status、recover 預覽、recover 確認、status 的順序處理。README 將 Windows 新鮮部署標成 EXPLICIT_BETA，因此 Windows 團隊應把檔案權限與回復結果納入上線前檢查。

編輯結論

codex-keysmith 适合需要把同一份 Markdown 指令穩定部署到多個 Codex 配置目錄、又希望在寫入前看到计划的人；它不适合未经审查就追求自動修改全局行為的环境。先下载穩定版脚本和 SHA256SUMS，在测試目錄执行 `--status` 與 `--dry-run`，確認 config.toml、hooks.json.disabled 和 manifest 的實際变化後再使用 `--yes`。

官方來源

1. Official README
2. Project repository
3. Release notes