自学教程

Codex 规则与钩子

Codex 教程

Codex 的规则（Rules） 是静态约束声明，定义智能体的行为边界、编码规范与权限限制；钩子（Hooks） 是生命周期事件触发器，在任务运行的关键节点自动执行外部脚本，实现动态校验、自动检查与流程拦截。规则用于“告诉Codex不能做什么、该遵循什么规范”，钩子用于“在特定时机自动执行程序做校验、拦截、后置处理”，二者配合完成项目治理与安全管控。

一、Codex 规则（Rules）

1.1 规则文件位置与优先级

规则分为项目级与用户全局两级：

  1. 项目级规则：.codex/rules.toml 或 AGENTS.md，提交Git仓库，团队共享，优先级更高，仅作用于当前仓库。
  2. 用户全局规则：~/.codex/rules.toml，仅本机生效，适用于所有项目，作为基础兜底约束。

优先级：项目规则 > 用户全局规则。同名约束，项目配置会覆盖全局配置。

1.2 规则的两类形式

  1. 自然语言规则（AGENTS.md）
    采用Markdown文本，描述项目编码规范、架构约束、修改限制、输出格式。属于软性规则，Codex在思考过程中读取并尽量遵守，适合业务规范、项目背景、代码风格要求。
    示例片段：
# AGENTS.md 项目规则
- 新增接口必须编写单元测试
- 禁止修改 config/prod.env 生产配置文件
- 所有SQL必须使用参数化查询，禁止直接字符串拼接
  1. 声明式硬规则（rules.toml）
    采用TOML配置，定义命令黑名单、文件保护、审批策略，属于强制约束，Codex会主动拦截违规操作。
# .codex/rules.toml
[file_protection]
protected = ["config/prod.env", ".env"]
message = "禁止修改生产环境配置文件"

[bash_blacklist]
block_commands = ["rm -rf", "curl | bash"]
require_approval = ["npm run deploy"]

1.3 规则核心能力

  • 文件保护：锁定敏感配置文件，阻止修改或删除。
  • 命令管控：黑名单直接拦截高危命令；部分高风险命令配置人工审批。
  • 输出约束：限定文件输出路径、代码风格、注释规范。
  • 子代理继承：默认规则会传递给子代理，也可单独为子代理重写规则。

二、Codex 钩子（Hooks）

钩子是绑定在任务生命周期事件上的脚本触发器，当Codex运行到指定阶段，自动执行shell、python等外部脚本，实现动态校验。和静态规则不同，钩子可以读取工具执行结果、检查文件变更，甚至拦截任务继续执行。

2.1 支持的钩子事件

钩子事件触发时机典型用途
pre-task任务开始执行前加载项目上下文、环境预检
post-task任务全部完成后自动执行测试、代码格式化、输出报告
pre-commit代码提交前Lint检查、安全扫描、敏感信息检测
pre-tool-use调用工具之前（bash、文件修改、MCP调用）拦截高危命令、校验参数
post-tool-use工具执行完成之后检查文件修改结果、校验代码变更
on-error任务发生异常时错误告警、自动回滚、日志记录
subagent-start子代理启动时给子代理注入独立约束、上下文

2.2 钩子配置方式

钩子可以直接写在 config.toml 的 [hooks] 节点，也可以使用独立 hooks.json 存放复杂多事件配置。

示例 .codex/config.toml 钩子配置：

[hooks]
# 任务完成后自动执行单元测试
post-task = "npm test"
# 提交前执行代码检查与格式化
pre-commit = "npm run lint && npm run format"
# 发生错误时发送告警通知
on-error = "curl -X POST [https://webhook.example/codex-error](https://webhook.example/codex-error) -d '任务执行失败'"
[hooks.settings]
timeout_ms = 30000 # 钩子超时时间，单位毫秒

复杂多事件、多匹配规则，推荐使用独立文件 .codex/hooks.json：

{
  "hooks": [
    {
      "event": "pre-tool-use",
      "matcher": "bash",
      "hooks": [
        {
          "type": "command",
          "command": "./.codex/hooks/check-danger-cmd.sh",
          "timeout": 5000
        }
      ]
    }
  ]
}

2.3 钩子脚本存放

自定义脚本建议统一放在 .codex/hooks/ 目录，提交到Git仓库，团队共享。脚本支持bash、python、node等可执行程序。

安全说明：项目钩子加载前，需要手动信任当前工作目录；未信任的项目，钩子不会自动运行，防止恶意脚本执行。

三、规则与钩子的区别与协作

项目规则 Rules钩子 Hooks
本质静态约束声明事件驱动的自动脚本
执行时机Codex启动会话时一次性加载任务生命周期的各个节点触发运行
能力限制文件、命令，定义行为规范运行外部程序，读取输出，动态拦截、校验
形式AGENTS.md / rules.tomlTOML配置、hooks.json + 外部脚本
作用层级会话全局生效绑定到事件，单次触发

完整协作流程

  1. Codex启动会话，加载AGENTS.md与rules.toml规则，初始化约束；
  2. 用户提交任务，触发pre-task钩子，做环境预检；
  3. Codex准备调用工具，触发pre-tool-use钩子，检查是否为高危操作；
  4. 工具执行完成，触发post-tool-use钩子，校验文件修改结果；
  5. 任务完成，触发post-task钩子，自动运行测试与格式化；
  6. 任务异常，触发on-error钩子，执行告警与回滚。

搭配关系：规则做基础防护，钩子做动态校验。规则拦截已知高危操作，钩子做自定义业务校验。

四、钩子管理斜杆命令

Codex桌面、IDE、CLI通用钩子管理命令：

# 查看当前项目全部钩子配置
/hooks list查看指定事件钩子详情
/hooks info post-task
重载钩子配置，修改文件后无需重启会话
/hooks reload
手动执行指定钩子进行测试
/hooks run pre-task

五、安全与最佳实践

  1. 最小权限原则：钩子脚本仅授予必要权限，不使用root/管理员权限运行。
  2. 超时控制：为所有钩子配置超时，防止脚本卡死阻塞Codex任务。
  3. 区分软硬约束：简单禁止项写在rules.toml；复杂动态检查交给钩子脚本。
  4. 敏感信息处理：钩子脚本禁止硬编码密钥，使用环境变量读取。
  5. 子代理隔离：子代理可单独配置钩子，防止子代理绕过主项目校验规则。
  6. 不要过度使用钩子：过多钩子会增加任务耗时与Token消耗，仅保留核心校验。
  7. 钩子失败策略：关键校验类钩子失败直接终止任务；日志、通知类钩子失败仅记录日志，不阻断主任务。

六、常见问题

Q：AGENTS.md属于规则还是钩子？
A：AGENTS.md属于静态规则，用来定义智能体的行为规范，不会自动执行脚本，不属于钩子。

Q：钩子脚本执行失败，会中断Codex任务吗？
A：取决于钩子类型，安全校验类钩子失败会阻断任务；日志通知类钩子失败仅记录日志，任务继续执行。

Q：子代理是否会继承主项目的规则与钩子？
A：默认继承主会话规则与钩子；可在子代理.toml配置文件单独重写、禁用钩子。

Q：修改hooks.json之后需要重启Codex吗？
A：不需要，执行 /hooks reload 重载配置即可。

七、总结

Codex规则（Rules）与钩子（Hooks）共同构成项目治理体系。规则通过AGENTS.md、rules.toml声明静态行为约束，定义文件保护、命令黑白名单；钩子在任务生命周期的关键节点自动运行外部脚本，完成动态校验、自动化测试、安全扫描、异常告警。

规则负责“预设边界”，钩子负责“动态检查”，二者可以和Agent Skills、子代理、MCP组合使用，构建完整的企业级AI开发管控流程。

标签：

0 条笔记