当前位置：首页 > news >正文

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

news 2026/7/14 19:50:23

本文面向已完成 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——本文所有引用均基于新站当日抓取。

Skills 技能系统：渐进式加载与 Record & Replay
Memories 本地记忆：机制、边界与配置
AGENTS.md 分层指令：优先级链与 override
MCP 集成：从 codex mcp add 到工具级审批
Automations 定时任务：RRULE 与无人值守权限
Codex SDK：TypeScript 与 Python 编程接入
进阶排障速查表
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：

--- 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}

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

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

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

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

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

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

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}

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

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

优先级链（三步）：

全局作用域：在 Codex home（默认~/.codex）读取AGENTS.override.md（若存在），否则AGENTS.md——只取第一个非空文件
项目作用域：从项目根（通常 Git 根）向下到当前目录，每目录依次检查AGENTS.override.md→AGENTS.md→project_doc_fallback_filenames自定义名——每目录至多用一个
合并顺序：从根开始拼接（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--cdservices/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}

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

4.1 快速添加（CLI）

# 通用格式codex mcpadd<server-name>--envVAR1=VALUE1 --<stdio server-command># 实例：添加 Context7 文档检索codex mcpaddcontext7 -- 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 两个容易踩的坑

服务器指令前 512 字符：Codex 读取 MCP 服务器初始化返回的instructions字段，前 512 字符应自成一体——自建 MCP server 时把最重要的工作流约束放在开头
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+）

npminstall@openai/codex-sdk

constcodex=newCodex();constthread=codex.startThread();constresult=awaitthread.run("Make a plan to diagnose and fix the CI failures");console.log(result.finalResponse);// 恢复历史线程继续跑constthread2=codex.resumeThread("<thread-id>");

6.2 Python（3.10+，beta）

pipinstallopenai-codex

fromopenai_codeximportCodex,SandboxwithCodex()ascodex: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 大模型广场等聚合平台），配置成本最低；保留 IDopenai、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/机器人

延伸阅读：