# Codex Hooks、Rules 与自定义

> Codex AGENTS.md、自定义 prompts、memories、hooks、rules、import、subagents 和项目级自定义能力的边界与配置方式。

URL: https://docs.passion8.cc/docs/codex/customization-hooks-rules
Language: zh-CN
Publisher: Passion8

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

| 层 | 解决什么 | 典型文件或入口 |
| --- | --- | --- |
| 说明层 | 规则、风格、流程、完成标准 | `AGENTS.md`、custom prompts、memories、skills |
| 控制层 | 命令、审批、生命周期阻断 | rules、hooks、sandbox、approval |
| 工具层 | 外部数据和动作 | MCP、plugins、app connectors |

## AGENTS.md

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

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

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

```md title="AGENTS.md"
# Project instructions

## Commands

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

## Done when

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

快速生成:

```text
/init
```

## Custom prompts

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

## Memories

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

| 机制 | 范围 | 适合 |
| --- | --- | --- |
| `AGENTS.md` | repo / 目录 | 项目事实、命令、团队标准 |
| Memories | 用户 / workspace | 个人偏好、重复习惯 |
| Prompt | 当前线程 | 一次性约束 |

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

## Hooks

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

常用位置:

| 位置 | 作用 |
| --- | --- |
| `~/.codex/hooks.json` | 用户级 hooks |
| `~/.codex/config.toml` | 用户级 inline hooks |
| `.codex/hooks.json` | 项目级 hooks,需信任项目 |
| `.codex/config.toml` | 项目级 inline hooks,需信任项目 |

示例:

```toml title=".codex/config.toml"
[[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 更适合可预测的命令前缀策略。

```python title=".codex/rules/default.rules"
prefix_rule(
    pattern = ["git", "push"],
    decision = "prompt",
    justification = "Pushing branches requires explicit review",
    match = ["git push origin feature"],
)
```

决策从宽到严:

| decision | 行为 |
| --- | --- |
| `allow` | 匹配后允许 |
| `prompt` | 匹配后询问 |
| `forbidden` | 匹配后阻止 |

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

## Skills 和 Plugins

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

```text
$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 通常放在:

| 位置 | 作用 |
| --- | --- |
| `~/.codex/agents/` | 个人 agent |
| `.codex/agents/` | 项目 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](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Hooks](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Rules](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Agent Skills](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Plugins](https://developers.openai.com/codex/codex-manual.md)