# Codex 进阶教程：Skills、Memories、AGENTS.md、MCP、Automations 与 SDK 全解（2026 版）

- 原文：[https://news.qiniu.com/archives/1783994696399](https://news.qiniu.com/archives/1783994696399)
- 发布时间：2026-07-14
- 分类：教程与实践
- 标签：MCP、Agent Skills、Codex、上下文管理

> 本文面向已完成 Codex 基础使用的开发者，系统讲解六大进阶能力——技能系统（Skills）、本地记忆（Memories）、分层指令（AGENTS.md）、MCP 工具扩展、定时任务（Automations）和 SDK 编程接入，全部内容基于 2026 年 7 月官方文档（learn.chatgpt.com）逐字核对。

**⚠️ 先说一个重要变化**：OpenAI Codex 官方文档站已从 `developers.openai.com/codex` 整站迁移至 **`learn.chatgpt.com`** ，部分路径也已改变（如 `/review` → `/codex/code-review`）。旧教程里的文档链接大多已 308 重定向或 404——本文所有引用均基于新站当日抓取。

* * *

## 目录

1. [Skills 技能系统：渐进式加载与 Record & Replay](https://news.qiniu.com/archives/1783994696399#skills)
2. [Memories 本地记忆：机制、边界与配置](https://news.qiniu.com/archives/1783994696399#memories)
3. [AGENTS.md 分层指令：优先级链与 override](https://news.qiniu.com/archives/1783994696399#agents-md)
4. [MCP 集成：从 codex mcp add 到工具级审批](https://news.qiniu.com/archives/1783994696399#mcp)
5. [Automations 定时任务：RRULE 与无人值守权限](https://news.qiniu.com/archives/1783994696399#automations)
6. [Codex SDK：TypeScript 与 Python 编程接入](https://news.qiniu.com/archives/1783994696399#sdk)
7. [进阶排障速查表](https://news.qiniu.com/archives/1783994696399#排障)
8. [FAQ](https://news.qiniu.com/archives/1783994696399#faq)

* * *

## 一、Skills 技能系统 {#skills}

**定义**：Skills 用任务专属能力扩展 Codex，把指令（instructions）、资源（resources）和可选脚本（scripts）打包成可复用单元，基于开放的 agent skills 标准（agentskills.io）。

**一句话分工**：**Skills 是编写格式，Plugins 是面向工作区的分发机制**——个人自用写 Skill，团队分发用 Plugin。

### 1.1 渐进式加载机制（Progressive Disclosure）

Codex 不会把所有技能全文塞进上下文：

- 初始只加载每个技能的 `name`、`description` 和文件路径
- 选中技能后才加载完整 `SKILL.md`
- 初始技能列表的预算上限约为**模型上下文窗口的 2%**（窗口未知时为 8,000 字符）
- 技能过多时：先缩短 description → 再省略部分技能并警告

**实操含义**：description 是技能的"广告位"——要简洁、关键信息前置、包含触发词，否则隐式匹配不会命中。

### 1.2 技能的四个作用域

| 作用域 | 路径 | 用途 |
|---|---|---|
| REPO | `$CWD/.agents/skills`、父目录及 `$REPO_ROOT/.agents/skills` | 仓库/目录级团队技能 |
| USER | `$HOME/.agents/skills` | 跨仓库个人技能 |
| ADMIN | `/etc/codex/skills` | 机器/容器级默认（SDK、自动化场景） |
| SYSTEM | OpenAI 内置（skill-creator 等） | — |

**注意**：重名技能**不合并**，二者都会出现在选择器中——团队技能命名要加前缀避免撞名。

### 1.3 三种创建方式

**方式一：Record & Replay（演示比描述容易时用）**

Codex 录制你的工作流、检查步骤，并从这次演示中起草一个可复用的技能。适合"我做一遍你学会"类流程（发布流程、环境体检等）。

**方式二：内置创建器**

```
$skill-creator
```

它会依次询问：技能做什么、何时触发、是纯指令型（默认）还是包含脚本。

**方式三：手动创建**

在对应作用域目录下建目录，写 `SKILL.md`：

```markdown
---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.
```

可选增强：`scripts/`、`references/`、`assets/`、`agents/openai.yaml`（配置图标、品牌色、是否允许隐式调用等）。

### 1.4 激活、禁用与安装

- **显式激活**：prompt 中提及技能名，或 CLI/IDE 中运行 `/skills`、输入 `$`
- **隐式激活**：Codex 将任务与 description 匹配；在 `agents/openai.yaml` 中设 `policy.allow_implicit_invocation: false` 可禁止隐式触发
- **安装精选技能**：`$skill-installer linear`（示例），或让它从其他仓库拉取
- **禁用某技能**（`~/.codex/config.toml`，需重启）：

```toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
```

* * *

## 二、Memories 本地记忆 {#memories}

**定义**：Memories 让 Codex 把过往任务的有用上下文带入未来会话。本地 Codex 客户端（CLI/桌面/IDE）使用**独立的本地记忆存储**，与 ChatGPT 网页版记忆是两套体系。

### 2.1 与 AGENTS.md 的分工（官方边界）

> 官方原文要求：**将 memories 视为"辅助回忆层"（a helpful recall layer）**——团队必须遵守的规则应放在 AGENTS.md 或提交到仓库的文档中，而不是依赖记忆。

| 载体 | 性质 | 适合放什么 |
|---|---|---|
| AGENTS.md | 确定性规则，每次必加载 | 测试命令、代码规范、禁止事项 |
| Memories | 概率性回忆，后台生成 | 项目偏好、历史决策上下文 |

### 2.2 工作机制（四个关键行为）

1. **后台生成**：不是任务结束即时生成——会等任务空闲足够长时间，避免总结进行中的工作
2. **自动跳过**：活跃或短暂的会话不生成记忆
3. **密钥脱敏**：生成字段做 secret redaction（但分享 `~/.codex` 目录前仍应人工检查）
4. **限速保护**：剩余速率限制低于配置阈值时跳过记忆生成，不跟你的正常任务抢额度

### 2.3 启用与配置

本地记忆**默认关闭**。启用方式（`config.toml`）：

```toml
[features]
memories = true
```

进阶配置键：

| 配置键 | 作用 |
|---|---|
| `memories.generate_memories` | 新任务能否作为记忆生成的输入 |
| `memories.use_memories` | 是否将现有记忆注入未来会话 |
| `memories.disable_on_external_context` | `true` 时排除用了 MCP/web search 的任务 |
| `memories.min_rate_limit_remaining_percent` | 低于此剩余额度百分比时不生成 |
| `memories.extract_model` / `consolidation_model` | 覆盖提取/整合模型 |

**存储位置**：`~/.codex/memories/`（摘要、持久条目、近期输入、证据）。官方明确：这是生成态数据，**排障可查看，不要手工编辑**。

**单任务控制**：会话中输入 `/memories` 控制当前任务能否使用/贡献记忆（不改全局设置）。

**Chronicle**（仅桌面端）：帮助 Codex "从你的屏幕恢复最近的工作上下文以建立记忆"——桌面用户的增强记忆来源。

* * *

## 三、AGENTS.md 分层指令 {#agents-md}

**定义**：AGENTS.md 给 Codex 提供项目级指令与上下文，Codex 开始工作前构建一条指令链，将全局默认与项目级覆盖组合。

### 3.1 发现机制（每次运行重建，无缓存）

优先级链（三步）：

1. **全局作用域**：在 Codex home（默认 `~/.codex`）读取 `AGENTS.override.md`（若存在），否则 `AGENTS.md`——只取第一个非空文件
2. **项目作用域**：从项目根（通常 Git 根）向下到当前目录，每目录依次检查 `AGENTS.override.md` → `AGENTS.md` → `project_doc_fallback_filenames` 自定义名——每目录至多用一个
3. **合并顺序**：从根开始拼接（root-first），**离工作目录越近的文件越靠后出现在 prompt 中，因此覆盖前面的**

**两条硬边界**：

- 空文件跳过
- 组合大小达到 `project_doc_max_bytes`（默认 **32 KiB**）即停止加载——超限要么调高上限，要么把内容拆到嵌套目录

### 3.2 Monorepo 三层写法实例

**全局**（`~/.codex/AGENTS.md`）——个人工作约定：

```markdown
## Working agreements
- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.
```

**仓库根**（`AGENTS.md`）——团队共识：

```markdown
## Repository expectations
- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.
```

**子服务覆盖**（`services/payments/AGENTS.override.md`）——专项规则：

```markdown
## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.
```

**验证加载顺序**：

```bash
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
```

预期输出顺序：全局 → 仓库根 → payments 覆盖。

**关键细节**：官方原文 "Codex stops searching once it reaches your current directory"——搜索到当前目录即停止，所以 override 文件要放在专项工作目录附近；同目录下 override 与普通 AGENTS.md 并存时，**普通文件被忽略**。

### 3.3 自定义回退文件名

团队已有 `TEAM_GUIDE.md` 之类的规范文件？不用改名：

```toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
```

重启后查找顺序变为：`AGENTS.override.md` → `AGENTS.md` → `TEAM_GUIDE.md` → `.agents.md`。

* * *

## 四、MCP 集成 {#mcp}

**定义**：MCP（Model Context Protocol）让 Codex 访问第三方工具与上下文（文档检索、浏览器控制、Figma、Sentry 等）。桌面版、CLI、IDE 扩展**共享同一份 Codex host 配置**——配一次，三端生效。

### 4.1 快速添加（CLI）

```bash
# 通用格式
codex mcp add <server-name> --env VAR1=VALUE1 -- <stdio server-command>

# 实例：添加 Context7 文档检索
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 管理命令
codex mcp list
codex mcp login <server-name>   # OAuth 服务器认证
```

会话中输入 `/mcp` 查看已连接服务器。

### 4.2 config.toml 完整配置

**STDIO 服务器**：

```toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"
```

**Streamable HTTP 服务器**（Bearer token）：

```toml
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
```

### 4.3 工具级审批（进阶重点）

`default_tools_approval_mode` 有四档：`auto` / `prompt` / `writes` / `approve`，还可以按单个工具覆盖：

```toml
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]        # 在允许列表之后应用
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20               # 默认 10
tool_timeout_sec = 45                  # 默认 60

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"              # 单工具覆盖
```

**审批模式选型建议**：只读检索类（文档、日志查询）用 `auto`；会改外部状态的（发消息、改工单）用 `prompt` 或 `writes`；高危操作单独 `approve`。

### 4.4 两个容易踩的坑

1. **服务器指令前 512 字符**：Codex 读取 MCP 服务器初始化返回的 `instructions` 字段，**前 512 字符应自成一体**——自建 MCP server 时把最重要的工作流约束放在开头
2. **OAuth 回调注册**：Codex 会在 `mcp_oauth_callback_url` 基础上附加服务器专属回调 ID 生成 `redirect_uri`，需要在 OAuth 提供方**注册完整派生地址**，只注册基础 URL 会认证失败

* * *

## 五、Automations 定时任务 {#automations}

**定义**：Automations 让 Codex 按计划无人值守地执行任务（每日 Issue 分诊、每周依赖体检、定期清理死代码）。

### 5.1 平台边界（先确认你的端支持）

| 端 | 支持情况 |
|---|---|
| 桌面 App | ✅ 可在本地项目目录或隔离 worktree 中运行（**电脑须开机且 App 运行**） |
| Web 端 | ⚠️ 可用但不能访问本地文件夹 |
| CLI / IDE 扩展 | ❌ 无定时任务界面 |

### 5.2 自定义周期：RFC 5545 RRULE

界面预设之外，支持标准 RRULE 表达任意周期：

```
RRULE:FREQ=MONTHLY;BYMONTHDAY=1;BYHOUR=9;BYMINUTE=0
```

（每月 1 日上午 9 点执行。）

### 5.3 两类任务 + 技能触发

- **独立任务**：每次从保存的 prompt 全新启动（推荐——上下文干净、结果可预期）
- **基于已有会话**：复用该会话上下文（适合长期跟踪型任务）

prompt 中可用 `$skill-name` 显式调用技能。官方示例 `$recent-code-bugfix`：内部用 `git log --since=1.week --author=<author>` 拉取本周提交再分析——**"技能定义方法，自动化定义时刻表"** 的标准组合。

### 5.4 无人值守的权限模型

- 遵守 sandbox 默认设置
- 组织策略允许时可用 `approval_policy = "never"`（否则任务会卡在审批上）
- 管理员可用 `requirements.toml` 强制约束（用户配置无法突破）

**运维提醒**：worktree 模式会累积临时目录，需定期归档清理。

* * *

## 六、Codex SDK 编程接入 {#sdk}

**定义**：Codex SDK 让你把 Codex 作为可编程组件嵌入自己的工具链（CI 机器人、自动 Review 服务、批处理管道）。

### 6.1 TypeScript（Node.js 18+）

```bash
npm install @openai/codex-sdk
```

```typescript
const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run("Make a plan to diagnose and fix the CI failures");
console.log(result.finalResponse);

// 恢复历史线程继续跑
const thread2 = codex.resumeThread("<thread-id>");
```

### 6.2 Python（3.10+，beta）

```bash
pip install openai-codex
```

```python
from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(model="gpt-5.4", sandbox=Sandbox.workspace_write)
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)
```

- 异步场景用 `AsyncCodex`
- Sandbox 预设：`Sandbox.read_only` / `workspace_write` / `full_access`，传给 `run()` 的 sandbox 对该轮及后续轮次生效
- Python 包内置固定版本的 Codex CLI 运行时，无需单独安装 CLI

### 6.3 官方选型边界

> SDK 适用于**纯编码场景**；若 Codex 只是更大编排流程中的一环，官方建议改用 **"Codex CLI as MCP server + Agents SDK"** 的组合。

* * *

## 七、进阶排障速查表 {#排障}

| 症状 | 原因 | 修复 |
|---|---|---|
| AGENTS.md 完全没加载 | 不在正确仓库 / 文件为空 | `codex status` 确认仓库；检查文件非空 |
| 加载了错误的指导 | 上层目录或 `~/.codex` 有 override 文件 | 找到并移除/重命名 `AGENTS.override.md` |
| 自定义回退文件名被忽略 | 拼写错误或未重启 | 核对 `project_doc_fallback_filenames`，重启 Codex |
| 指令被截断 | 超过 32 KiB 默认上限 | 调大 `project_doc_max_bytes` 或拆分到子目录 |
| 新技能不出现 | 变更未被检测到 | 重启 Codex |
| `--profile` 不生效 | Codex 0.134.0 起不再读 config.toml 内联 `[profiles.name]` | 迁移为独立文件 `~/.codex/<name>.config.toml` |
| MCP OAuth 认证失败 | 只注册了基础回调 URL | 在 OAuth 提供方注册完整派生 redirect\_uri |
| Profile 环境混乱 | CODEX\_HOME 指向错误 | `echo $CODEX_HOME` 检查 |
| 审计加载了哪些指令文件 | — | `codex -c log_dir=./.codex-log` 后查 `codex-tui.log` |

* * *

## 八、FAQ {#faq}

**Q：Skills、AGENTS.md、Memories 三者怎么分工？**

A：一句口诀——**反复照做的流程做 Skill，必须遵守的规则写 AGENTS.md，希望它记得的上下文交给 Memories**。Skill 是按需加载的能力包，AGENTS.md 是每次必读的规则，Memories 是概率性的辅助回忆层（官方明确不要把必守规则只放记忆里）。

**Q：项目级 `.codex/config.toml` 什么都能配吗？**

A：不能。项目级配置**禁止覆盖**安全敏感键，包括 `model_provider`、`model_providers`、`notify`、`profile`、`openai_base_url` 等——这些只能在用户级 `~/.codex/config.toml` 配置，防止恶意仓库劫持你的模型端点。

**Q：能在 Codex 里接国产模型吗？**

A：可以通过 `[model_providers.<id>]` 自定义 provider（`base_url` + `env_key`），但注意 Codex 的 wire 协议要求——若服务商提供 OpenAI 兼容端点（如七牛云 AI 大模型广场等聚合平台），配置成本最低；保留 ID `openai`、`ollama`、`lmstudio` 不可用作自定义 provider 名。

**Q：定时任务会不会在我睡觉时乱改代码？**

A：Automations 遵守你的 sandbox 设置——默认 `workspace-write` 下只能改工作区文件，网络访问默认受限；再配合 `/review` 或 auto\_review 兜底，早上起来审查 diff 再合并即可。

**Q：文档链接为什么都失效了？**

A：2026 年年中 OpenAI 将 Codex 文档整站迁移至 `learn.chatgpt.com`，旧域名 308 重定向、部分路径变更。收藏夹里的旧链接建议全部更新。

* * *

## 小结：进阶 Codex 的一张路线图

| 阶段 | 该配什么 |
|---|---|
| 个人提效 | AGENTS.md（全局 + 仓库）→ 2\~3 个高频 Skill → 按需开 Memories |
| 团队协作 | 仓库级 `.agents/skills` → Plugin 分发 → requirements.toml 管控 |
| 自动化 | Automations 定时任务 + `$skill` 组合 → SDK 接入 CI/机器人 |

**延伸阅读：**

- [七牛云 AI 大模型广场](https://www.qiniu.com/ai/models)——OpenAI 兼容端点，多模型统一接入
- [AI Coding](https://www.qiniu.com/ai/plan)

* * *

*本文全部配置语法与行为描述基于 learn.chatgpt.com 官方文档 2026-07-13 当日抓取，逐字核对。Codex 迭代较快，请以最新文档为准。*
