codex-keysmith 是一个面向 Codex CLI 的本地指令文件安装辅助工具。它用 Python 编写，主要功能是把本地 Markdown 指令文件复制到 Codex 的 `.codex` 配置目录，并在 `config.toml` 顶层写入或更新 `model_instructions_file` 配置项，从而让 Codex CLI 加载该指令文件。项目强调安全写入：默认仅预览，必须显式传入 `--yes` 才会修改文件，并会在修改前备份原有配置和同名指令文件。它不是 Codex 的分叉版，也不修改 Codex 二进制、网络流量或运行进程。
适用领域
AI 编程助手配置 / Codex CLI 工具链 / 本地开发环境自动化 / Prompt / Instruction 管理 / 开发者效率工具 / 命令行工具
配置难度
低。对于熟悉命令行和 Codex CLI 的开发者，使用成本很低；主要操作是运行 Python 脚本、指定 `.codex` 目录和确认写入。对新手来说，需要理解 `~/.codex/config.toml`、`model_instructions_file` 和备份回滚的含义。
商业价值
该项目的商业价值主要体现在提升 AI 编程工具配置效率和降低手动修改配置的风险。对于个人开发者，它可以快速安装和切换 Codex CLI 指令文件；对于团队，它可以作为标准化本地 AI 助手行为配置的轻量工具。不过项目本身功能较小，尚未形成完整的企业级配置管理、策略审计、权限控制或多环境管理能力，因此更适合作为开发者工具链中的辅助组件，而不是独立商业产品。
01
技术亮点
- 默认安全：没有 `--yes` 时只预览，不会实际写入文件
- 修改前自动备份 `config.toml`，降低配置损坏风险
- 如果目标 `.md` 文件已存在，也会先备份再覆盖
- 明确限制文件名，防止通过 `--name` 写出 `.codex` 目录之外
- 不修改 Codex 二进制、不拦截网络、不修改运行进程，边界清晰
- 支持使用内置示例，也支持通过 `--file` 指定用户自己的指令文件
- 项目结构简单，单文件 Python CLI，便于审计
- README 同时提供中文和英文说明，对中文开发者友好
- MIT 许可证，商业和个人使用门槛较低
02
目标用户
- 使用 Codex CLI 的开发者
- 希望为 Codex CLI 配置自定义本地指令文件的用户
- 需要频繁切换或部署 Prompt / Instruction 文件的 AI 编程用户
- 不想手动编辑 `.codex/config.toml` 的开发者
- 希望在修改 Codex 配置前自动备份的谨慎型用户
- 使用 Codex、Claude Code、Cursor Agent 等智能体辅助配置本地环境的用户
03
配置要求
- 需要本机已安装 Python 3.8+
- 需要已有或准备使用 Codex CLI 的本地配置目录，通常为 `~/.codex`
- 推荐显式传入 `--codex-dir ~/.codex`，避免脚本推断路径与实际使用路径不一致
- 如使用自定义指令文件，需要提供本地 `.md` 文件路径，例如 `--file ./my_prompt.md`
- `--name` 只能包含字母、数字、点、下划线和连字符，不能包含路径分隔符、绝对路径、`..`、空格或空名称
- 写入时必须传入 `--yes`，否则即使未传 `--dry-run` 也只会预览
- Codex CLI 需要支持 `model_instructions_file` 配置项
- 写入后需要重启 Codex CLI 才能生效
04
适用场景
- 将自定义 Markdown 指令文件安装到 `~/.codex` 目录
- 自动更新 Codex CLI 的 `model_instructions_file` 配置
- 在修改 `config.toml` 前自动生成备份，便于回滚
- 预览即将修改的文件和配置项，避免误操作
- 使用内置示例指令文件快速测试 Codex CLI 指令加载能力
- 用自己的 `.md` 文件替换默认指令文件，实现团队或个人规则注入
- 让 AI Agent 按安全流程帮助安装 Codex 本地配置
05
部署与配置
- 克隆仓库：`git clone https://github.com/Jia-Ethan/codex-keysmith.git`
- 进入目录：`cd codex-keysmith`
- 确认 Python 版本为 3.8 或更高：`python3 --version`
- 先进行语法检查：`python3 -m py_compile codex-instruct.py`
- 可选：运行测试：`python3 -m pytest tests`
- 先预览，不写入任何文件：`python3 codex-instruct.py --dry-run`
- 确认目标目录后写入默认指令文件：`python3 codex-instruct.py --codex-dir ~/.codex --yes`
- 如需使用自己的指令文件：`python3 codex-instruct.py --file ./my_prompt.md --name my-rules --codex-dir ~/.codex --yes`
- 重启 Codex CLI，使新的 `model_instructions_file` 配置生效
06
风险与注意事项
- 仓库内置的 `gpt5.5-unrestricted-mode` 示例指令文件可能不适合所有团队或生产环境，需要用户自行审查内容
- 该工具只是配置 `model_instructions_file`，不能保证自定义指令一定改善模型行为
- 目前没有 `restore`、`uninstall`、`status` 等子命令，回滚需要手动复制备份文件
- TOML 修改采用保守顶层键处理方式，未使用完整 TOML 编辑库；复杂 `config.toml` 场景下需谨慎验证
- 目前未打包为 pip 工具，安装和使用仍依赖直接运行脚本
- 主要面向全局 Codex 配置，尚未提供 profile 隔离或多配置管理能力
- Windows 路径仅做基础兼容，跨平台使用仍需实际验证
- 如果用户误用不可信的 Markdown 指令文件，可能引入不符合预期的模型行为或安全策略偏移
2026-07-05
第11名
新收录 · github_search
2026-07-04
第11名
新收录 · github_search
2026-07-03
第16名
新收录 · github_search
2026-07-02
第17名
新收录 · github_search
2026-07-01
第28名
新收录 · github_search
