Codex 进阶实战：AGENTS.md、授权模式、MCP 与 Skills（企业级用法）

适合人群：已经能跑通 codex，想提升效率与可控性的开发者
覆盖内容：会话恢复、快捷命令、授权模式、网络搜索、图片输入、AGENTS.md、MCP、Skills
预计阅读：12 分钟

---

一、先把“会话”管起来

Codex 支持恢复历史会话，断点续聊非常方便。

# 打开历史会话选择菜单
codex resume

# 直接恢复最近一次会话
codex resume --last

# 按 session id 恢复
codex resume 719f9a2e-1b3c-4c7a-9b6e-123456789abc

如何查 session id：

• 会话内输入 /status
• 或查看本地目录：~/.codex/sessions/

建议：一个大任务尽量在同一会话里做完；任务方向变了，再用 /new 开新对话，避免上下文污染。

---

二、快捷命令：输入 / 就是效率入口

在 Codex 交互界面输入 /，会弹出快捷命令列表。常用命令如下：

命令	作用
/model	切换模型与推理强度
/approvals	设置授权模式
/new	开启新对话
/init	初始化 AGENTS.md
/compact	压缩上下文，避免触顶
/diff	查看 git diff（含未跟踪文件）
/mention	引用某个文件
/status	查看当前会话配置和 Token 用量
/skills	打开 Skills 菜单
/quit	退出会话

几个高频操作

1）多行输入提示词

长提示不要挤一行，换行更清晰：

• macOS：Option + Enter
• 通用：Control + J

2）中断当前任务

• 生成过程中按 Esc 或 Ctrl + C
• 再按一次 Ctrl + C，或输入 /quit 退出会话

3）上下文快满了

直接：

/compact

把历史对话压缩成摘要，继续干活。

---

三、授权模式：安全与效率怎么平衡

输入：

/approvals

一般有三档：

1）Read Only（只读）

• 能读文件、回答问题
• 改文件、跑命令、访问网络都要你批准
• 适合：先聊方案、做 Code Review、梳理架构

2）Auto / Default（默认）

• 可在当前工作区读文件、改文件、跑命令
• 访问网络或改工作区外文件时需要确认
• 适合：日常开发主模式

3）Full Access（完全访问）

• 可越出工作区改文件、访问网络，且不反复确认
• 效率最高，风险也最高
• 适合：隔离环境、明确可信任务；不要在生产仓库随便开

一句话建议：

先 Read Only 想清楚 → Auto 动手改 → 特殊自动化再考虑 Full Access。

---

四、精准喂上下文：@ 引用文件 + --search 联网

1）用 @ 指定文件

输入 @ 后开始打文件名，会出现候选列表，例如：

@style.css
@src/utils/date.ts

比“你自己去找某某文件”更稳，也更省 Token。

2）开启可控联网搜索

codex --search

适合需要查最新文档、发行说明、报错资料的场景。
相比直接 Full Access 放开网络，--search 更可控。

3）图片也能丢给 Codex

交互里可直接粘贴图片；CLI 可用：

codex -i screenshot.png "解释一下这个界面报错"
codex --image img1.png,img2.jpg "总结一下这些图表"

排查 UI 问题、看报错截图时特别好用。

---

五、AGENTS.md：给 Agent 写的项目说明书

如果你用过 Claude Code 的 CLAUDE.md，那 AGENTS.md 就是同一思路：

它不是给人看的 README，而是给 AI Agent 看的“项目操作手册”。

存放层级（可叠加）

~/.codex/AGENTS.md          # 全局习惯
./AGENTS.md                 # 当前项目
./components/AGENTS.md      # 子目录局部规则

快速生成

在项目根目录启动 Codex 后：

/init

它会帮你生成初始 AGENTS.md。

更多规范见：

https://agents.md/

一个可直接改的 Vue3 示例

# Repository Guidelines

## Project Structure & Module Organization
- 技术栈：Vue 3 + Vite
- 代码在 `src/`，静态资源在 `public/`
- 入口：`src/main.js`
- 根组件：`src/App.vue`
- 组件目录：`src/components/`（PascalCase）
- 路径别名：`@` 指向 `src`

## Build, Test, and Development Commands
- `npm install`
- `npm run dev`
- `npm run build`
- `npm run preview`
- Node 版本：`^20.19.0 || >=22.12.0`

## Code Style & Naming Conventions
- 缩进：2 spaces
- 使用 Vue3 Composition API + `<script setup>`
- 组件文件：PascalCase（如 `UserCard.vue`）
- 变量/函数：camelCase
- CSS class：kebab-case
- 组件保持单一职责，优先沿用现有写法

## Testing Standards
- 当前无强制测试框架时，新增单测可用 `*.spec.js`
- 或放在 `src/__tests__/`

写好 AGENTS.md 后，Codex 的改动会更“像你们团队的代码”，而不是每次都重新猜规范。

---

六、配置调优：网络不稳也能稳住

配置文件：

~/.codex/config.toml

可直接改，也可在 VS Code Codex 插件设置里点“打开 config.toml”。

示例：

model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
trust_level = "trusted"

[model_providers.openai]
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

含义很直观：

• request_max_retries：HTTP 失败重试次数
• stream_max_retries：流式连接断开重试
• stream_idle_timeout_ms：空闲超时（示例为 5 分钟）

官方配置文档可参考 Codex 仓库的 docs/config.md。

---

七、MCP 集成：给 Codex 装“外挂工具”

MCP（Model Context Protocol）可以理解为大模型的工具插件协议。
Codex 的 MCP 配置写在 config.toml，格式是 TOML（不是 Cursor/Claude 常见的 JSON）。

配置示例

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "test" = "123456" }

[mcp_servers.puppeteer]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-puppeteer"]
env = { "test" = "123456" }

怎么验证 MCP 是否生效？

Codex 目前没有像某些工具那样单独的 mcp list 验命令，主要看启动日志：

• 正常：会出现 mcp: xxx ready
• 异常：会直接报错，例如：

MCP client for context7 failed to start: request timed out

排查思路：

1. 包名是否写错
2. npx 是否可用
3. 网络是否能拉到对应包
4. env 是否缺关键变量

---

八、Skills：把重复工作沉淀成可复用能力

Skills 是 Codex 企业级落地的关键能力：
把“提示词 + 规则 + 脚本 + 参考资料”打包，让 Agent 按固定流程执行。

1）推荐目录结构

.codex/skills/
└── meeting-skill/
    ├── SKILL.md
    ├── prompt.md
    ├── scripts/
    ├── references/
    └── assets/

也可用 $plan Skill 先规划，再用 skill-creator 完善。

2）SKILL.md 最小模板

---
name: your-skill-name
description: 当用户提到 XXX 时使用这个 Skill，帮助完成 YYY。
metadata:
  short-description: 可选的简短用户可见描述
---

# Skill 标题

这里写详细指令：一步步指导 Codex 如何执行任务。
- 使用哪些工具或库
- 处理边缘情况
- 输出格式要求
- 示例等

description 很重要：自动触发是否准，几乎取决于它写得清不清楚。

3）存放位置与优先级（高 → 低）

1. 当前项目：.codex/skills/
2. 仓库根：repo_root/.codex/skills/（团队共享）
3. 个人全局：~/.codex/skills/
4. 系统内置（不可覆盖）

同名 Skill：高优先级覆盖低优先级。
所以个人习惯可以全局放一份，项目特殊规则再在仓库覆盖。

4）怎么调用 Skills

显式调用（更精准，推荐）：

$.meeting-skill

或：

/skills

自动选择（更自然）：

直接描述任务，Codex 根据 description 自动匹配。

创建命令：

codex
# 然后输入 /
# 或 /skills
# 或 $skill-creator firstskill

5）企业案例：会议总结助手

一个典型 Skill 可以规定：

总结维度

• 参会人员
• 议题
• 决定
• 财务提醒（出现“费用/采购/支出”时，对照 公司财务手册.md 校验）

上传规则

当用户说“上传 / 同步 / 推送到云端”时，自动执行：

python scripts/upload.py "会议纪要内容"

输出要求

每个维度尽量一句话，避免碎片化 bullet。

这就是 Skills 的价值：
不是“再聊一次”，而是“按公司流程稳定执行”。

6）脚本型 Skill 小例子（makefolder）

skills/
└── makefolder/
    ├── SKILL.md
    └── scripts/
        └── make_folder.ps1

先单独测脚本：

./skills/makefolder/scripts/make_folder.ps1 test

通过后再让 Codex 按 Skill 流程调用，可重复、可迭代、可沉淀。

---

九、一条推荐工作流（建议收藏）

把上面能力串起来，日常可以这样用：

1. cd 到项目根目录
2. codex 启动
3. /init 生成或完善 AGENTS.md
4. /approvals 先用 Auto
5. 用 @文件 精准喂上下文
6. 复杂任务先让它出方案，再让它改代码
7. Token 快满时 /compact
8. 重复流程沉淀成 Skill
9. 需要外部工具时接 MCP
10. 中途离开用 codex resume --last 接上

---

十、非交互自动化：给 CI / 脚本预留口子

codex exec "修复这个报错的问题"
codex exec "帮我生成变更说明，输出到 CHANGELOG.md"

适合：

• 本地脚本批处理
• 固定检查任务
• 文档生成流水线

注意：自动化场景权限给得越小越好，避免误改。

---

十一、进阶避坑清单

1. AGENTS.md 写太虚
   “代码要优雅”没用；写清目录、命令、命名、禁止事项。

2. Skill description 写太宽
   太宽会导致乱触发；要写清“什么场景用、完成什么目标”。

3. 一上来 Full Access + 关沙箱
   出问题成本很高，企业环境尤其不建议。

4. MCP 配了却不看启动日志
   Codex 很多 MCP 问题都在启动时报出来。

5. 上下文只增不压
   长会话记得 /compact，或 /new 开新任务。

---

十二、速查命令表

# 会话
codex
codex resume
codex resume --last
codex exec "fix this error"
codex --search

# 交互内
/model
/approvals
/init
/compact
/status
/skills
/diff
/quit

# 引用与图片
@src/App.vue
codex -i shot.png "看看这个报错"

# 关键路径
~/.codex/config.toml
~/.codex/AGENTS.md
./AGENTS.md
.codex/skills/

---

写在最后

Codex 真正拉开差距的，不是“会不会问问题”，而是你有没有把它工程化：

• 用 AGENTS.md 固定项目规范
• 用授权模式控制风险
• 用 MCP 扩展工具边界
• 用 Skills 沉淀团队流程

当你把这些配齐后，Codex 就不再是一次性聊天工具，而更像团队里一个可训练、可复用、可审计的“初级工程师助手”。

如果你正在把 Codex 落进真实项目，建议先做一个最小闭环：

一个 AGENTS.md + 一个业务 Skill + 默认 Auto 授权。

跑通这三样，再谈更复杂的企业级集成会轻松很多。