codex-config-optimizer

Codex CLI 优化技能

Codex CLI 配置优化规则与跟踪。

1. 配置文件位置

配置通过 Nix（programs.codex home-manager 模块）以声明式方式管理。

事实来源：

• @~/ghq/github.com/i9wa4/dotfiles/nix/home-manager/agents/codex-cli.nix
• @~/ghq/github.com/i9wa4/dotfiles/nix/home-manager/agents/

目标	来源	管理方式
~/.codex/config.toml	由激活脚本生成	codex-cli.nix
~/.codex/AGENTS.md	由 AGENTS.md 和内联的 rules/*.md 生成	instruction-artifacts.nix
~/.codex/rules/	根据被拒绝的 Bash 策略生成 default.rules	codex-cli.nix
~/.codex/hooks.json	生成的钩子配置	codex-cli.nix
~/.codex/scripts/	软链接的 codex-* 脚本和共享的拒绝模式	codex-cli.nix
~/.codex/skills/	多个 flake 输入和本地内容	agent-skills.nix
MCP 服务	nix/home-manager/agents/mcp-servers.nix	codex-cli.nix

2. 配置管理

静态设置（模型、分析、功能、MCP 服务）以 Nix 属性的形式定义在 codex-cli.nix 中。受信任的项目会在执行 home-manager switch 时通过 fd 动态发现，并追加到 config.toml 中。

钩子也在 codex-cli.nix 中声明；其运行时脚本位于 nix/home-manager/agents/scripts/codex-* 下，并在切换时写入 ~/.codex/scripts/。

要更新设置，请编辑 nix/home-manager/agents/codex-cli.nix 并重新构建。

3. 获取发布版本

3.1. 检测本地版本

始终先检测已安装的版本：

codex --version

此命令会返回本地安装的版本（例如 codex-cli 0.113.0）。 所有发布分析都必须限定在此版本及更早的版本。 不要报告比本地安装版本更新的版本所包含的功能或变更。

3.2. 从 GitHub 获取

FILE=$(mkmd --dir tmp --label output)
gh api repos/openai/codex/releases --jq '.[0:10]' > "$FILE"

然后使用以下命令提取截至本地版本（含本地版本）的条目：

jq '.[] | select(.tag_name == "rust-v<LOCAL_VERSION>") | {tag_name, body}' "$FILE"

4. CHANGELOG 操作

重要：以下所有操作均限定在本地安装的版本范围内。 忽略所有比 codex --version 更新的版本发布条目。

4.1. 最新发布摘要

1. 使用 codex --version 检测本地版本
2. 使用上述命令获取发布记录
3. 提取 rust-v<local-version> 发布条目（不是第一条）
4. 将变更分类为：
   • 新功能（Added）
   • 错误修复（Fixed）
   • 改进（Improved/Changed）
   • 破坏性变更
5. 用中文呈现并简要说明

4.2. 版本差异

1. 使用 codex --version 检测本地版本
2. 询问用户起始版本（结束版本默认为本地版本）
3. 提取起始版本至本地版本（含两端）的所有发布记录
4. 总结累积变更
5. 突出显示破坏性变更和弃用项

4.3. 检测破坏性变更

1. 使用 codex --version 检测本地版本
2. 搜索截至本地版本的发布记录，查找：breaking、removed、 deprecated、changed（行为变更）
3. 列出受影响的命令和选项
4. 提供迁移指南

5. 设置类别

类别	示例
模型	model、model_reasoning、model_reasoning_effort
行为	approval_mode、sandbox、network_access
显示	notify、tui.notifications_method
Shell	shell_environment_commands
钩子	features.codex_hooks、hooks.json、scripts/codex-*
历史记录	history、project_doc_max_bytes
功能	features.skills、features.web_search_request
禁用	disable_response_storage、hide_agent_*
分析	analytics.enabled、feedback.enabled

6. 钩子指南

• 你必须：先启用 features.codex_hooks = true，再依赖任何 hooks.json 行为
• 你必须：将 Codex 主目录级钩子保留在 nix/home-manager/agents/codex-cli.nix 中，除非确实需要在仓库本地覆盖
• 你必须：将 Codex 钩子脚本保留在 nix/home-manager/agents/scripts/codex-* 下
• 你必须：将 denied-bash-commands.nix 作为 Bash 拒绝策略的唯一事实来源（SSOT），不要单独维护仅供 Codex 使用的命令列表
• 你必须：让共享 Bash 拒绝说明以修复为导向，使拒绝信息告诉 Agent 接下来该怎么做，而不只是说明拦截了什么
• 你必须：目前将 Codex 的 PreToolUse 和 PostToolUse 视为仅适用于 Bash
• 你必须：让 PostToolUse Bash 钩子仅提供反馈；命令已经运行，因此应使用它们提供简洁的补救建议，而不是假装实施拦截
• 绝不要：声称 Codex 目前会拦截 Write|Edit|NotebookEdit；这些匹配器示例是有效的正则表达式，但与当前 Codex 运行时不匹配
• 绝不要：依赖 PreToolUse 不支持的 permissionDecision: "ask" / "allow"、updatedInput 或 additionalContext 字段；当前运行时会解析这些字段，但会默认放行
• 注意：官方文档称当前支持的事件包括 SessionStart、PreToolUse、PostToolUse、UserPromptSubmit 和 Stop
• 注意：官方文档称，多个 hooks.json 文件中匹配的钩子都会运行；同一事件中匹配的命令钩子会并发启动
• 注意：Stop 是目前与 Claude PreCompact 最接近的 Codex 等效事件；可用它进行轻量级交接持久化，但不要将其视为完全兼容的证明

7. AGENTS.md 设计指南

• 你必须：只关注角色设定和核心指南
• 你必须：确保说明同时兼容 Claude Code 和 Codex CLI
• 绝不要：包含特定工具的语法（例如 Claude Code 的 TodoWrite）

8. 优化检查清单

编辑 AGENTS.md 或 config.toml 时，请检查以下内容：

• 角色设定是否简洁？
• 基本规则是否真的需要始终生效？
• 详细说明是否可以移至 skills/？
• config.toml 是否使用了合适的 approval_mode？
• 共享 Bash 拒绝消息是否描述了安全的后续操作，而不只是拒绝？
• 是否如实记录了 Codex 钩子的限制（工具调用前后都仅适用于 Bash）？
• PostToolUse 是否仅用于提供确定性的 Bash 反馈，而非实施拦截？
• 钩子状态是否正确地分配在 hooks.json 和 scripts/codex-* 中？

9. 优化跟踪

上次审核的 Codex CLI 版本：v0.117.0 (2026-03-30)

9.1. 已应用的优化

• 根据共享的 AGENTS.md 和内联规则 Markdown 生成 AGENTS.md
• 将 skills/ 符号链接到 Claude Code skills
• 根据拒绝 Bash 的策略生成 default.rules
• 启用用户级 Codex 钩子：UserPromptSubmit、SessionStart、PreToolUse（仅 Bash）、PostToolUse（仅 Bash）和 Stop
• Claude Code 和 Codex CLI 钩子共同使用拒绝 Bash 的模式
• 将共享的拒绝 Bash 说明从单纯拒绝升级为修复指导，供 Claude Code 和 Codex CLI 使用
• Codex 的 UserPromptSubmit 现在包含时间、角色、cwd 和 git 上下文
• 通过 Stop 和 SessionStart 实现轻量级 Codex 交接持久化
• model_auto_compact_token_limit = builtins.floor (codexContextWindow * 0.7)：在 70% 时自动压缩（对于 gpt-5.x 的 272k 窗口为 190,400 个 token）
• tui.terminal_title = []：禁用 Codex 对终端标题的写入，将 tmux pane_title 保留用于角色标识（v0.117.0）

9.2. 待考虑事项

• 如有需要，创建 prompts/ 符号链接，指向 ../claude/commands/
• 创建 generate-config.sh，以自动生成 config.toml
• 评估 MCP 服务集成（例如 AWS 文档 MCP）
• 计划模式（/plan）——现已稳定并默认启用（v0.94.0）
• command_attribution = "disable"——已禁用共同作者归属标记 （v0.103.0）
• PostToolUse Bash 反馈启发式——随着新的仓库故障模式不断重复，保持范围狭窄且确定
• code_mode 实验性功能——隔离的编码工作流；关注其稳定情况（v0.114.0）
• 禁用内置系统技能的配置开关——如果自定义技能足以支持更精简的会话，此开关会很有用 （v0.114.0）
• 权限配置文件配置语言——在 config.toml 中拆分文件系统/网络沙箱策略，以实现更精细的控制（v0.113.0）
• 子 Agent 支持——多 Agent 功能已稳定（v0.115.0）；在 Nix 构建时从 subagents/*.md 自动生成 .toml Agent（codex-cli.nix）
• openai_base_url 配置覆盖项——自定义 API 端点（v0.115.0）
• 智能审批守护 Agent——通过守护子 Agent 路由审查请求，以减少审批阻碍（v0.115.0）

9.3. 不采用的选项

• personality 设置——保留默认值（“friendly”）；更改没有好处
• log_dir 配置——默认日志位置已足够
• tui.notifications_method——保留默认值
• CLAUDE_CODE_DISABLE_CRON 环境变量——不适用于 Codex CLI
• approval_policy: on-failure——已弃用（v0.102.0）；配置中未使用
• PreToolUse / PostToolUse 匹配器模式，例如 Write|Edit——当前 Codex 运行时只会触发 Bash，因此这些配置目前会造成误导
• PreToolUse 中的 permissionDecision: "ask" / "allow" 和 updatedInput——当前运行时能够解析这些设置，但不会强制执行
• Bash 修复钩子的 PostToolUse 决策/阻止语义——将这些钩子仅用于反馈，让 Codex 仍能看到原始命令结果
• AfterToolUse 钩子——已被文档化的钩子引擎取代
• smart_approvals——保留默认行为（v0.93.0）

9.4. 版本说明

• v0.117.0：/title 终端标题选择器现在同时支持经典 TUI 和 app-server TUI，插件成为一等工作流，app-server TUI 现在默认启用，并移除了旧版 artifact、read_file 和 grep_files 处理程序
• v0.116.0：审查时的本地已安装版本；官方 hooks 文档仍将 hooks 标记为实验性，并在 https://developers.openai.com/codex/hooks 中说明当前支持的事件和限制
• v0.115.0：通过 view_image 检查全分辨率图像，js_repl 新增 codex.cwd/codex.homeDir 并支持跨单元格持久化，实时 WebSocket 转录模式 + v2 交接，支持 Python SDK 的 v2 app-server 文件系统 RPC，Smart Approvals guardian 子 Agent 用于审核路由，通过 Responses API 搜索工具并支持回退，多 Agent 功能趋于稳定，wait_agent 工具重命名，Linux 沙盒默认使用 bubblewrap，openai_base_url 配置覆盖
• v0.114.0：实验性代码模式（隔离编码），hooks 引擎（SessionStart/Stop），app-server WebSocket 健康端点（/readyz//healthz），可禁用捆绑系统技能的配置，用于保持轮次连续性的交接转录上下文，带类别标签的 $ 提及选择器，修复 Linux tmux 段错误，跨轮次保留审批状态，Python SDK v2 模式基础
• v0.113.0：request_permissions 工具（运行时权限请求），插件市场 + 精选发现 + 卸载，支持 TTY/PTY 的 app-server 流式执行，完整的 Web 搜索工具配置，权限配置文件配置语言，图像生成保存到当前工作目录，用于日志的 SQLite 数据库，winget 自动更新
• v0.112.0：支持通过 @plugin 提及直接引用插件，权限配置文件合并到每轮沙盒中，修复 JS REPL 绑定持久化问题，SIGTERM 优雅关闭，强化 bubblewrap userns，改进 macOS Seatbelt
• v0.111.0：默认启用快速模式，TUI 显示快速/标准模式，js_repl 可导入本地 .js/.mjs 文件，会话开始时向模型报告插件，app-server v2 MCP elicitation 支持结构化请求/响应
• v0.110.0：插件系统（来自配置或市场的技能/MCP/应用连接器），持久化的 /fast 开关，带审批提示的多 Agent TUI 流程，工作区范围的记忆写入，Windows 安装程序
• v0.107.0：将线程分叉到子 Agent，实时语音设备选择，多模态自定义工具输出，可配置记忆（codex debug clear-memories）
• v0.104.0：用于 WebSocket 代理的 WS_PROXY/WSS_PROXY 环境变量，来自 app-server 的 ConfigChange hook，命令审批 ID 传递
• v0.103.0：通过 command_attribution 配置标注提交共同作者，列表中展示更丰富的应用详情
• v0.102.0：整合权限流程与 TUI 历史记录，授予沙盒读取权限的斜杠命令，可自定义的多 Agent 角色，model/rerouted 通知，已弃用 approval_policy: on-failure
• v0.101.0：修复记忆和模型解析问题
• v0.100.0：实验性 JS REPL 运行时，记忆斜杠命令（/m_update、/m_drop），ReadOnlyAccess 沙盒策略，AfterToolUse hook
• v0.99.0：用于配置 TUI 页脚的 /statusline 命令，Shell 命令不再中断进行中的轮次，支持 GIF/WebP 图像，新增 AfterToolUse hook，安全修复（RUSTSEC-2026-0009）
• v0.98.0：引入 GPT-5.3-Codex 模型，默认稳定启用 steer 模式（Enter 发送，Tab 排队）
• v0.97.0：MCP/应用工具支持“允许并记住”，实时技能更新，/debug-config 斜杠命令，可配置的 log_dir
• v0.96.0：在所有非 Windows 平台上启用 unified_exec
• v0.95.0：加载 ~/.agents/skills 中的个人技能，/plan 接受参数和图像，并行 Shell 工具，注入 CODEX_THREAD_ID 环境变量
• v0.94.0：默认启用计划模式，personality 配置稳定（默认值：友好），支持来自 .agents/skills 的技能

10. 响应格式（CHANGELOG）

# Codex CLI vX.X.X 更新内容

## 新機能
- [機能名]: [説明]

## バグ修正
- [修正内容]

## 改善
- [改善内容]

## 破壊的変更
- [影響を受ける機能と移行方法]

---
Source: https://github.com/openai/codex/releases

11. 重要说明

• Codex CLI 的变更日志位于发布页面，而非 CHANGELOG.md
• 使用 GitHub releases API 获取发布说明
• 始终注明所引用的版本
• 如有官方发布页面，请链接到该页面

12. 参考链接

• Codex CLI：https://github.com/openai/codex
• Codex hooks 文档：https://developers.openai.com/codex/hooks