本文面向已完成 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-sdkconstcodex=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-codexfromopenai_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/机器人 |
延伸阅读：
- 七牛云 AI 大模型广场——OpenAI 兼容端点，多模型统一接入
本文全部配置语法与行为描述基于 learn.chatgpt.com 官方文档 2026-07-13 当日抓取，逐字核对。Codex 迭代较快，请以最新文档为准。
