Jia-Ethan/codex-keysmith · 上手攻略

  • 仓库：Jia-Ethan/codex-keysmith
  • 链接：https://github.com/Jia-Ethan/codex-keysmith
  • 分类：工具 · Codex 配置管理
  • 作者：Tom
  • 更新：2026-08-09

这是什么

codex-keysmith 是一个零依赖的单文件 Python 脚本，把一份指令 Markdown 部署到 Codex CLI 的配置目录（~/.codex），让 Codex 的每个新会话自动加载这份指令。内置 dry-run 预览、SHA256 校验、manifest 追踪和逐层卸载，同时默认将已有的 hooks.json 隔离为 hooks.json.disabled，防止全局行为被意外覆盖。

解决什么问题：当你需要让 Codex 每次启动都默认加载自定义指令（比如"不要拒绝请求""用中文回答"），但又担心误改全局配置或无法还原。Keysmith 通过事务化的部署流程（预览 → 确认 → 写入 → manifest 记录）让这个过程完全可逆。

快速安装

环境要求：Python 3.10–3.14，macOS / Linux（Windows 支持尚在 beta）。

第一步：下载并校验（将 vX.Y.Z 替换为 Releases 页面 最新 tag）：

base='https://github.com/Jia-Ethan/codex-keysmith/releases/download/vX.Y.Z'
curl --fail --location --remote-name "$base/codex-instruct-vX.Y.Z.py"
curl --fail --location --remote-name "$base/SHA256SUMS"
shasum -a 256 -c SHA256SUMS

⚠️ 不要用 curl | python 直接管道执行，也不要从浮动的 main 分支安装。务必先落盘再校验。

第二步：预览部署效果（不写入任何文件）：

python3 codex-instruct-vX.Y.Z.py --version
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --status --lang zh-CN
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --dry-run --lang zh-CN

第三步：确认无误后写入：

python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --yes --lang zh-CN

部署完成后关闭当前 Codex 会话、新开一个，Codex 仅在会话启动时加载配置。

核心用法

部署自定义指令文件

# 用内置的 gpt-unrestricted.md（默认）
python3 codex-instruct.py --codex-dir ~/.codex --yes --lang zh-CN

# 用自己的指令文件
python3 codex-instruct.py --file ./my-prompt.md --name my-rules \
  --codex-dir ~/.codex --dry-run --lang zh-CN
# 确认后把 --dry-run 换成 --yes

--name 仅接受 ASCII 字母、数字、点、下划线和连字符，不能是路径或空名。

查看部署状态

python3 codex-instruct.py --codex-dir ~/.codex --status --lang zh-CN

输出包括：config.toml 路径、受管 MD 文件路径、hooks 隔离状态、manifest 健康度、卸载就绪度。

卸载（逐层撤销）

# 预览
python3 codex-instruct.py --codex-dir ~/.codex --uninstall --lang zh-CN
# 确认
python3 codex-instruct.py --codex-dir ~/.codex --uninstall --yes --lang zh-CN

卸载只撤销最新一层部署；部署多次则重复运行逐层撤销。

单独恢复 hooks（不碰指令和配置）

python3 codex-instruct.py --codex-dir ~/.codex --restore-hooks --lang zh-CN

中断恢复

如果部署/卸载被 SIGKILL 或断电中断，--status 会报告 blocked，用 --recover 恢复：

python3 codex-instruct.py --codex-dir ~/.codex --recover --lang zh-CN  # 预览
python3 codex-instruct.py --codex-dir ~/.codex --recover --yes --lang zh-CN  # 确认

与 CCSwitch 配合（Provider 级别 On/Off）

如果使用 CCSwitch（多 Provider 管理器），可以让两个副本分别保存 Keysmith 的 On / Off 配置：

# 1. 确保 CCSwitch 的通用配置片段不包含 model_instructions_file
# 2. 选择准备作为 On 的副本，部署 Keysmith（可用 --skip-hooks-isolation 只切换指令）
# 3. 切到 Off 副本，--status 验证：On → active，Off → inactive-by-config
# 4. 卸载后切换回 On 副本确认字段消失

典型适用场景

  • 深度定制 Codex 行为：希望所有新会话默认使用特定角色提示词、禁用拒绝话术、或覆盖敏感内容处理逻辑。
  • 团队共享指令规范：用 --file 指向一份团队共创的指令文件，一键部署到所有成员的 Codex。
  • 安全地试验 prompt：先用 --dry-run 看清写入内容，确认无误才真正部署，随时 --uninstall 撤销。
  • 与 CCSwitch 多 Provider 工作流结合：用 On/Off 两个副本控制指令加载，切换 Provider 时同步切换行为。

坑与注意

  1. 这不是安全边界：内置的 gpt-unrestricted.md 覆盖了 reverse shell / keygen / 武器化内容等的拒绝逻辑，是一次影响很广的行为切换——用前务必先读 examples/gpt-unrestricted.md。

  2. Windows 支持仍在 beta：已发布的 v0.1.0 有已知清理缺陷；v0.1.1 及后续版本重写了 Windows 文件系统后端，但还不是正式支持。

  3. 无自动更新：需要手动从 Release 下载新版本并重新部署，旧脚本和资产不会被覆盖式替换。

  4. 单文件 CLI，没有 pip install：不通过包管理器管理，备份和卸载归档不会自动清理。

  5. 仅影响新会话：部署后需关闭旧会话、新开一个才能生效；运行中的会话不会热更新。

  6. hooks 隔离是全局的：默认 hooks.json 隔离不跟随 Provider 配置切换，需要纯指令 On/Off 时在部署时加 --skip-hooks-isolation。

  7. 事务残留不要手工删除：如果遇到 .codex-keysmith-transaction-* 残留，用 --status 检出后按 --recover 流程处理，不要手动删文件。

与同类对比

工具 类型 核心功能 优势 局限
codex-keysmith 单文件脚本 全局指令部署 + hooks 隔离 + 逐层卸载 零依赖、事务化、dry-run、manifest 可审计 仅支持 Codex CLI，Windows 仍在 beta
OpenClaw Skills 配置系统 指令 + 工具 + 记忆 多实例管理、权限隔离、群组共享 复杂度更高，学习曲线陡
Claude Code --resume 启动参数 加载 CLAUDE.md 无需额外工具 仅在启动时生效，无法管理全局行为
手动编辑 config.toml 手工操作 直接改配置 无额外依赖 无 dry-run、无备份、无卸载机制

一句话推荐结论

如果你重度使用 Codex CLI、需要全局指令管理、且希望有可审计的部署/卸载记录，codex-keysmith 是目前最轻量且最安全的方案——零依赖、单文件、事务化，动手前先 --dry-run 永远是对的。