Illustrative preview / 示意预览；实际路径与输出以本机 dry-run 为准。

codex-keysmith

先预览、再写入、可撤销的 Codex 全局指令部署工具。

简体中文 · English · Reference · 智能体安装 · Security · License

简体中文

Keysmith 系列为本地 AI 工具安全部署、验证和撤销自定义指令。codex-keysmith 把一份 Markdown 部署到 Codex 配置目录（通常是 ~/.codex），让之后的新会话加载它。

[!WARNING] 这会改变该 Codex 配置下的全局行为，不是项目级开关：写入 config.toml 的 model_instructions_file，并默认把整份 hooks.json 隔离为 hooks.json.disabled。部署、卸载和中断恢复先预览，确认后加 --yes；--restore-hooks 会立即执行且不接受 --yes。先阅读 examples/gpt-unrestricted.md 和 SECURITY.md。

选择哪个 Keysmith

安装方式

1. 稳妥：稳定 CLI。 打开 最新稳定 Release，下载单文件 codex-instruct-v*.py 与 SHA256SUMS，校验后再运行；当前稳定资产名为 codex-instruct-v0.3.9.py。不要 curl | python。
2. 更易用：未签名 Desktop Beta。 见 Desktop 预发布：macOS Apple Silicon DMG 与 Windows x64 NSIS，内嵌 CLI sidecar、双 preset、四个 fixture 包与“恢复配置引用”入口。无签名、无自动更新、无 Linux GUI。安装步骤见 CODE_SIGNING_POLICY.md。
3. 源码。 clone 后直接 python3 codex-instruct.py。此源码树与最新稳定 Release 均为 0.3.9，以 Releases 页为准。

快速开始

# 把 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"
awk '$2 == "codex-instruct-vX.Y.Z.py"' SHA256SUMS | shasum -a 256 -c -

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

源码路径：git clone https://github.com/Jia-Ethan/codex-keysmith.git && cd codex-keysmith，再把上述脚本名换成 codex-instruct.py。部署后关闭旧任务、开一个新 Codex 会话。省略 --codex-dir 会处理全部自动发现的配置目录。Windows 命令把 python3 换成 python。

会修改什么

场景部署另写 <target>/.codex-keysmith/，不改上述指令层文件。完整边界见 docs/reference.md。

如何撤销

以下以 Release 单文件为例；源码 checkout 请把文件名换成 codex-instruct.py。

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

卸载每次只撤销最新一层。--reactivate 从 v0.3.9 开始提供：

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

若 --status 显示 inactive-by-config，--reactivate 只补回缺失的顶层 model_instructions_file，不要手工改 config.toml，也不要为补字段再走一遍完整部署。它会回滚可捕获的批量失败，但不创建 durable journal；硬中断后先运行 --status，无冲突时重跑 --reactivate --yes 完成其余目录。--recover 只处理 deploy/uninstall 中断事务。不要手工删除 journal、备份或 manifest。

平台与 Beta 限制

• CLI：macOS / Linux 为主要支持；Windows 新鲜部署为 EXPLICIT_BETA。不要使用已发布的 v0.1.0。
• Desktop Beta：仅 macOS Apple Silicon 与 Windows x64，未签名、未经公证，可能触发 Gatekeeper / SmartScreen。
• CLI 与 Desktop 正常操作不主动收集或上传用户数据；当前资产尚未完成实体设备验收，也未获 SignPath 签名。
• 推荐 Python 3.10–3.14。没有 pip install，没有自动更新。
• 版本、资产名和签名状态以 Releases 与 CODE_SIGNING_POLICY.md 为准，不要以本页为版本源。

两条通道

指令通道把 Markdown 部署到 ~/.codex（默认 --preset unrestricted）。环境通道 --scaffold 把残缺 fixture 工作区写到 ~/.codex-fixture-workspace/<pack>，不修改 ~/.codex。两通道可叠用，互不写对方目录。默认安装步骤不变；scaffold 不是必做步骤。

python3 codex-instruct.py --scaffold-list
python3 codex-instruct.py --scaffold pytest_complete --dry-run
python3 codex-instruct.py --scaffold pytest_complete --yes

独立单文件脚本旁边没有 fixture_packs/ 时，--scaffold 会提示下载 Release bundle 或指定 --pack-dir。

进阶文档

• 场景部署 / 评估（M1 / M2 / M3）：docs/reference.md · docs/v0.3-scenario-deployment-design.md
• 环境通道 / fixture packs：docs/fixture-channel.md
• CCSwitch：docs/ccswitch.md
• 事务、journal、恢复：docs/hooks-transactions.md
• Desktop / 智能体安装：gui/README.md · docs/agent-install.md

贡献、安全与系列

提交前阅读 CONTRIBUTING.md。漏洞走 SECURITY.md 的 GitHub 私密渠道。社区讨论：LINUX DO。

• codex-keysmith — Codex 全局指令
• claude-keysmith — Claude Code 可卸载 import block
• grok-keysmith — Grok Build home rules（~/.grok/rules/99-keysmith.md，不改 AGENTS.md）
• zcode-keysmith — ZCode App system-role 入口（仅源码，无 Desktop）