Illustrative preview / 示意预览；实际路径与输出以本机 dry-run 为准。
先预览、再写入、可撤销的 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。
| 项目 | 目标工具 | 部署面 | 稳妥安装 | Desktop |
|---|---|---|---|---|
| codex-keysmith | Codex | 全局 ~/.codex 指令 |
稳定 CLI Release | 未签名 Beta |
| claude-keysmith | Claude Code | 项目 / 用户 CLAUDE.md import |
源码 CLI | 未签名 Beta |
| grok-keysmith | Grok Build | 全局 ~/.grok/rules（不改 AGENTS.md） |
稳定 CLI Release | 未签名 Beta |
| zcode-keysmith | ZCode App | 用户目录 system-role + wrapper | 仅源码 | 无 |
- 稳妥：稳定 CLI。 打开 最新稳定 Release，下载单文件
codex-instruct-v*.py与SHA256SUMS，校验后再运行；当前稳定资产名为codex-instruct-v0.3.7.py。不要curl | python。 - 更易用：未签名 Desktop Beta。 见 Desktop 预发布：macOS Apple Silicon DMG 与 Windows x64 NSIS，内嵌 CLI sidecar。无签名、无自动更新、无 Linux GUI。安装步骤见
CODE_SIGNING_POLICY.md。 - 源码。 clone 后直接
python3 codex-instruct.py。当前默认分支源码版本为0.3.7；最新稳定 Release 仍以 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。
| 路径 | 会发生什么 |
|---|---|
<codex-dir>/gpt-unrestricted.md（或 --name） |
新建，或先备份再替换 |
<codex-dir>/config.toml |
只改顶层 model_instructions_file |
<codex-dir>/hooks.json |
默认整体隔离为 hooks.json.disabled |
<codex-dir>/.codex-keysmith-manifest.json |
记录本层所有权，供卸载使用 |
场景部署另写 <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卸载每次只撤销最新一层。中断事务先 --status，再 --recover 预览，确认后加 --yes。不要手工删除 journal、备份或 manifest。
- 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）