codex-keysmith README

The project's README from github.com/Jia-Ethan/codex-keysmith. As one markdown file: README.md.

Illustrative codex-keysmith dry-run terminal preview; actual paths and output vary

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

codex-keysmith

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

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

Blocking CI tests Source version v0.5.1 Python 3.10 to 3.14 recommended License MIT

简体中文

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

项目 目标工具 部署面 稳妥安装 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 仅源码 无

安装方式

  1. 稳妥：稳定 CLI。 打开 最新稳定 Release，下载单文件 codex-instruct-v*.py 与 SHA256SUMS，校验后再运行；当前稳定资产名为 codex-instruct-v0.5.1.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.5.0，以 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。

如何撤销

以下以 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 限制

两条通道

指令通道把 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。

进阶文档

贡献、安全与系列

提交前阅读 CONTRIBUTING.md。漏洞走 SECURITY.md 的 GitHub 私密渠道。官方反馈：GitHub Discussions；社区交流：LINUX DO。

codex-keysmith (Jia-Ethan/codex-keysmith)

Searching Database…

4.7K ·GitHub
Codex-keysmith
这是什么？一个 CLI 工具，把带版本号的 Markdown 指令文件部署到 Codex 的全局配置目录（通常是 ~/.codex），总是先预览，并支持你之后撤销部署。
这是 GUI 应用，还是命令行工具？它主要是一个单文件 Python CLI 脚本；另有一个未签名的桌面 beta 应用（macOS Apple Silicon DMG、Windows x64 NSIS），它把同一个 CLI 作为 sidecar 打包。
怎么安装并运行它？从最新的稳定 Release 下载经过校验的单文件脚本（当前为 codex-instruct-v0.5.1.py）和 SHA256SUMS，核对哈希，然后用 python3 运行；也可以克隆仓库后直接运行 python3 codex-instruct.py。
使用它需要 pip 或其他包管理器吗？不需要，它是一个零依赖的单文件脚本；你只需要 Python 3.10-3.14，没有 pip install，也没有自动更新机制。
Windows 版现在用起来安全吗？Windows 被标记为 EXPLICITBETA（针对全新部署），旧的 v0.1.0 版本不应使用；桌面 beta 应用未签名、未经公证，可能触发 Gatekeeper 或 SmartScreen 警告。
哪些平台是真正得到完整支持的？CLI 主要支持 macOS 和 Linux，Windows 处于 beta；单独的桌面 beta 应用只为 macOS Apple Silicon 和 Windows x64 构建，没有 Linux GUI。
它会收集或上传我的任何数据吗？不会，正常的 CLI 和桌面运行不会主动收集或上传用户数据。
指令通道和脚手架通道有什么区别？指令通道把一个 Markdown 文件部署到 ~/.codex，默认预设为 unrestricted；单独的 --scaffold 环境通道会把一个 fixture 工作区写入 ~/.codex-fixture-workspace/，不碰 ~/.codex。两者可以同时使用，因为它们从不写入对方的目录。
如果出了问题，怎么撤销一次部署？卸载会逐层回滚；--reactivate（自 v0.3.9 起）只恢复顶层的 modelinstructionsfile 引用而无需完整重新部署；--recover 则处理被打断的部署/卸载事务，无需手动碰 journal 或 manifest。
它和 claude-keysmith、grok-keysmith 是什么关系？它属于“Keysmith”工具家族，这些工具用于安全地部署和移除面向不同 AI 助手的自定义指令：codex-keysmith 针对 Codex 的全局 ~/.codex 指令，而兄弟项目分别针对 Claude Code、Grok Build 和 ZCode App。
它会动我的 hooks.json 吗？会，默认情况下它会通过把 Codex 的 hooks.json 重命名为 hooks.json.disabled 来隔离它；--restore-hooks 标志会立即将其恢复，而且与其他操作不同，它不接受 --yes。
What are similar projects?nuwa-skill, headroom, casbin-gateway, agent-router, SwiftUI-Agent-Skill, jev-code-reviewer, codex-provider-sync, greenbubbles
Which topics is it in?configuration-management, codex-cli, backup, installer, cli-tool, prompt-engineering, local-first, coding-agent, openai, codex, command-line-tool, security
Creator
Jia-Ethan
Size
24.3 MB
Stars
4.7K
Updated
CommitSep 27Releasev0.6.0Sep 10
Age
3mo
Commits · 90 Days