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——本文所有引用均基于新站当日抓取。目录Skills 技能系统渐进式加载与 Record ReplayMemories 本地记忆机制、边界与配置AGENTS.md 分层指令优先级链与 overrideMCP 集成从 codex mcp add 到工具级审批Automations 定时任务RRULE 与无人值守权限Codex SDKTypeScript 与 Python 编程接入进阶排障速查表FAQ一、Skills 技能系统 {#skills}定义Skills 用任务专属能力扩展 Codex把指令instructions、资源resources和可选脚本scripts打包成可复用单元基于开放的 agent skills 标准agentskills.io。一句话分工Skills 是编写格式Plugins 是面向工作区的分发机制——个人自用写 Skill团队分发用 Plugin。1.1 渐进式加载机制Progressive DisclosureCodex 不会把所有技能全文塞进上下文初始只加载每个技能的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、自动化场景SYSTEMOpenAI 内置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_contexttrue时排除用了 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 neverList 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}定义MCPModel Context Protocol让 Codex 访问第三方工具与上下文文档检索、浏览器控制、Figma、Sentry 等。桌面版、CLI、IDE 扩展共享同一份 Codex host 配置——配一次三端生效。4.1 快速添加CLI# 通用格式codex mcpaddserver-name--envVAR1VALUE1 --stdio server-command# 实例添加 Context7 文档检索codex mcpaddcontext7 -- npx-yupstash/context7-mcp# 管理命令codex mcp list codex mcp loginserver-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_VALUEStreamable 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:FREQMONTHLY;BYMONTHDAY1;BYHOUR9;BYMINUTE0每月 1 日上午 9 点执行。5.3 两类任务 技能触发独立任务每次从保存的 prompt 全新启动推荐——上下文干净、结果可预期基于已有会话复用该会话上下文适合长期跟踪型任务prompt 中可用$skill-name显式调用技能。官方示例$recent-code-bugfix内部用git log --since1.week --authorauthor拉取本周提交再分析——“技能定义方法自动化定义时刻表”的标准组合。5.4 无人值守的权限模型遵守 sandbox 默认设置组织策略允许时可用approval_policy never否则任务会卡在审批上管理员可用requirements.toml强制约束用户配置无法突破运维提醒worktree 模式会累积临时目录需定期归档清理。六、Codex SDK 编程接入 {#sdk}定义Codex SDK 让你把 Codex 作为可编程组件嵌入自己的工具链CI 机器人、自动 Review 服务、批处理管道。6.1 TypeScriptNode.js 18npminstallopenai/codex-sdkconstcodexnewCodex();constthreadcodex.startThread();constresultawaitthread.run(Make a plan to diagnose and fix the CI failures);console.log(result.finalResponse);// 恢复历史线程继续跑constthread2codex.resumeThread(thread-id);6.2 Python3.10betapipinstallopenai-codexfromopenai_codeximportCodex,SandboxwithCodex()ascodex:threadcodex.thread_start(modelgpt-5.4,sandboxSandbox.workspace_write)resultthread.run(Make a plan to diagnose and fix the CI failures)print(result.final_response)异步场景用AsyncCodexSandbox 预设Sandbox.read_only/workspace_write/full_access传给run()的 sandbox 对该轮及后续轮次生效Python 包内置固定版本的 Codex CLI 运行时无需单独安装 CLI6.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.tomlMCP OAuth 认证失败只注册了基础回调 URL在 OAuth 提供方注册完整派生 redirect_uriProfile 环境混乱CODEX_HOME 指向错误echo $CODEX_HOME检查审计加载了哪些指令文件—codex -c log_dir./.codex-log后查codex-tui.log八、FAQ {#faq}QSkills、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]自定义 providerbase_urlenv_key但注意 Codex 的 wire 协议要求——若服务商提供 OpenAI 兼容端点如七牛云 AI 大模型广场等聚合平台配置成本最低保留 IDopenai、ollama、lmstudio不可用作自定义 provider 名。Q定时任务会不会在我睡觉时乱改代码AAutomations 遵守你的 sandbox 设置——默认workspace-write下只能改工作区文件网络访问默认受限再配合/review或 auto_review 兜底早上起来审查 diff 再合并即可。Q文档链接为什么都失效了A2026 年年中 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 迭代较快请以最新文档为准。