Hooks、Rules 与自定义

Codex 的自定义能力可以分成三层:告诉它“怎么做”的说明层,限制它“能做什么”的控制层,以及扩展它“能连什么”的工具层。

#AGENTS.md

AGENTS.md 是 Codex 自动加载的项目说明。适合写:

• 项目结构和重要目录
• 安装、启动、测试、构建命令
• 代码风格和架构约束
• PR / review 标准
• 禁止事项和完成定义

Codex 会从全局、项目根、当前目录逐层加载。越靠近当前目录的文件越晚出现,优先级也更高。

# Project instructions

## Commands

- npm run lint
- npm run typecheck
- npm run build

## Done when

- Relevant checks pass
- Diff is reviewed
- No unrelated refactor

快速生成:

/init

#Custom prompts

Custom prompts 适合把一段常用指令做成可复用入口,例如“发布前检查”“写 PR 描述”“分析失败日志”。如果它只是固定提示词,用 custom prompt;如果还需要资料、脚本、模板或多步骤流程,做成 Skill 更合适。

#Memories

Memories 适合沉淀个人偏好和长期习惯。它和 AGENTS.md 的区别:

不要把密钥、客户隐私、临时 token 写进 memory。

#Hooks

Hooks 在生命周期节点触发,适合把团队规则变成机制。Codex 可以从 hooks.json 或 config.toml inline [hooks] 加载 hooks。

常用位置:

示例:

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = './.codex/hooks/pre_tool_use_policy.sh'
timeout = 30
statusMessage = "Checking Bash command"

如果同一层同时存在 hooks.json 和 inline [hooks],Codex 会同时加载并警告。建议每一层只选一种写法。

#Rules

Rules 控制哪些命令可以在 sandbox 外执行。相比 hooks,Rules 更适合可预测的命令前缀策略。

prefix_rule(
    pattern = ["git", "push"],
    decision = "prompt",
    justification = "Pushing branches requires explicit review",
    match = ["git push origin feature"],
)

决策从宽到严:

如果多个规则匹配,更严格的结果获胜。

#Skills 和 Plugins

本地 Skill 适合固化重复流程:

$skill-creator
/skills
$readme-skill

Plugin 是安装和分发单位。一个插件可以包含 skills、MCP server 配置、assets、app mappings 和 manifest。团队内部共享时,先把 workflow 做成 skill,稳定后再打包成 plugin。

#Import

/import 用于把受支持的 Claude Code 配置、项目文件或最近 chats 迁移到 Codex。它适合从已有 Claude Code 工作流迁移,但不要无脑导入所有历史配置。

建议顺序:

1. 先导入项目说明或命令规则
2. 检查是否和现有 AGENTS.md 冲突
3. 再决定是否迁移 hooks、skills、custom prompts
4. 迁移后用 /debug-config 查看实际加载结果

#Subagents

Codex 支持内置和自定义 subagents。自定义 agent 通常放在:

每个 agent 文件至少要有:

• name
• description
• developer_instructions

Subagent 适合明确分工,例如探索、测试、review、迁移。不要让多个 subagent 同时改同一批文件;需要并行实现时配合 worktree。

#推荐落地顺序

1. 先写短的 AGENTS.md
2. 把重复 prompt 做成 custom prompt 或 skill
3. 用 rules 处理明确命令策略
4. 用 hooks 做审计、通知、自动检查
5. 用 MCP 接外部工具
6. 稳定后把能力打包成 plugin

#官方参考

• Codex manual: Custom instructions with AGENTS.md
• Codex manual: Hooks
• Codex manual: Rules
• Codex manual: Agent Skills
• Codex manual: Plugins