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…

Что это такое?CLI-инструмент, который разворачивает версионируемый файл инструкций в Markdown в глобальный каталог конфигурации Codex (обычно ~/.codex), всегда сначала показывая предпросмотр и позволяя потом отменить развёртывание.
Это приложение с GUI или инструмент командной строки?Это прежде всего однофайловый Python CLI-скрипт; есть ещё неподписанное бета-приложение Desktop (macOS Apple Silicon DMG, Windows x64 NSIS), оборачивающее тот же CLI как sidecar.
Как его установить и запустить?Скачайте проверенный однофайловый скрипт (сейчас это codex-instruct-v0.5.1.py) вместе с SHA256SUMS из последнего стабильного Release, проверьте хеш, затем запустите через python3; как вариант — склонируйте репозиторий и сразу запустите python3 codex-instruct.py.
Нужен ли pip или какой-либо пакетный менеджер?Нет, это однофайловый скрипт без зависимостей; нужен лишь Python 3.10-3.14 — ни pip install, ни механизма автообновления нет.
Безопасно ли сейчас пользоваться сборкой для Windows?Windows помечена как EXPLICITBETA для свежих развёртываний, а старый релиз v0.1.0 использовать не следует; бета-приложение Desktop неподписанное и без нотаризации, поэтому может вызывать предупреждения Gatekeeper или SmartScreen.
Какие платформы реально полностью поддерживаются?Основные поддерживаемые платформы CLI — macOS и Linux, Windows в бете; отдельное бета-приложение Desktop собирается только для macOS Apple Silicon и Windows x64, а GUI для Linux нет.
Собирает ли он или куда-то загружает мои данные?Нет, при обычной работе CLI и Desktop данные пользователя активно не собираются и не выгружаются.
В чём разница между каналом instruction и каналом scaffold?Канал instruction разворачивает Markdown-файл в ~/.codex с предустановкой по умолчанию unrestricted; отдельный канал окружения --scaffold записывает фикстурное рабочее пространство в ~/.codex-fixture-workspace/, не трогая ~/.codex. Ими можно пользоваться вместе, поскольку они никогда не пишут в каталоги друг друга.
Как отменить развёртывание, если что-то сломалось?Удаление откатывает по одному слою за раз; --reactivate (начиная с v0.3.9) восстанавливает только верхнеуровневую ссылку modelinstructionsfile без полного переустановления, а --recover обрабатывает прерванные транзакции deploy/uninstall без ручного вмешательства в журнал или манифест.
Как это связано с claude-keysmith или grok-keysmith?Это часть семейства инструментов «Keysmith», которые безопасно разворачивают и удаляют пользовательские инструкции для разных ИИ-ассистентов: codex-keysmith нацелен на глобальные инструкции ~/.codex у Codex, а родственные проекты — на Claude Code, Grok Build и ZCode App соответственно.
Он трогает мой hooks.json?Да, по умолчанию он изолирует hooks.json Codex, переименовывая его в hooks.json.disabled; флаг --restore-hooks возвращает его немедленно и, в отличие от других операций, не принимает --yes.
Creator
Jia-Ethan
Size
24.3 MB
Stars
4.8K
Age
3mo
Commits · 90 Days