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

本文面向已完成 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
  2. Memories 本地记忆：机制、边界与配置
  3. AGENTS.md 分层指令：优先级链与 override
  4. MCP 集成：从 codex mcp add 到工具级审批
  5. Automations 定时任务：RRULE 与无人值守权限
  6. Codex SDK：TypeScript 与 Python 编程接入
  7. 进阶排障速查表
  8. FAQ

一、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：

---
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，需重启）：
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

二、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）：

[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 给 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）——个人工作约定：

## 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）——团队共识：

## 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）——专项规则：

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

验证加载顺序：

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 之类的规范文件？不用改名：

# ~/.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（Model Context Protocol）让 Codex 访问第三方工具与上下文（文档检索、浏览器控制、Figma、Sentry 等）。桌面版、CLI、IDE 扩展共享同一份 Codex host 配置——配一次，三端生效。

4.1 快速添加（CLI）

# 通用格式
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 服务器：

[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）：

[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，还可以按单个工具覆盖：

[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 让 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 编程接入

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

6.1 TypeScript（Node.js 18+）

npm install @openai/codex-sdk

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）

pip install openai-codex

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

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/机器人

延伸阅读：

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

posted @ 2026-07-14 10:10  vibecoding患者  阅读(1078)  评论(0)    收藏  举报