AI Coding开发学习记录(3)：Codex 常用功能指南

2026-07-13 / 约 6204 字 / 预计阅读 13 分钟 { 教程, 笔记 } • [ AI Coding, Codex ]

前言

之前的Agentic Engineering博客提到了 Subagent 等技术。

这篇博客主要讲这些 AI Agent 的一些常用功能该怎么用。因为我主要用 Codex，而且主要用的是 IDE 插件和 CLI，所以这篇文章的实际操作内容也会以 Codex CLI 和 Codex IDE 插件为主。

不过我不会全讲。有些功能比较鸡肋，我就略过，只说一些我自己经常用的。

我现在学 AI Coding 比学 Coding 还认真🙃

Steer

Steer 一般翻译为“引导”，对 Codex 而言，就是在任务执行的中途给它补充信息加以引导，但是不中断当前任务的运行。

在 Codex IDE 插件等图形化工具中，如果当前对话里的任务正在执行，你后续发的消息到底是直接引导当前任务，还是先进入排队状态，取决于当前界面和设置。如果不想按默认行为走，一般也可以在界面里手动切换。

而在 Codex CLI 中，如果当前对话下任务正在执行，按 Enter 发送就是引导，按 Tab 发送就是排队。

Plan Mode

Plan Mode 一般翻译为“计划模式”，顾名思义，让 Agent 进入计划模式，本质上就是先帮我们把某个任务的计划列出来。

在之前我写的 提问到协作 中我曾经提到过这个功能。

如果你对 Agent 的执行流程不放心，可以先开启计划模式，让 Agent 先列出一个计划。你可以不断修改这个计划，或者回答 Agent 对细节的追问，直到自己满意为止。确定计划没问题后，再让 Agent 按这个计划继续执行。

我认为计划模式本质上就是一种补充上下文信息的方式，也是上下文工程的一部分，目的就是让 AI 能够更加明确你的意图。

在 Codex IDE 插件等图形化工具中，一般是点击对话框左下方的 “+” 按钮，然后选择“计划模式”；有些界面也支持直接输入 /plan，或者用 Shift+Tab 切进去。

在 Codex CLI 中，则是在对话框输入 /plan 并按回车。

AGENTS.md

这个我在提问到协作中也提到过。

AGENTS.md 也是 Codex 上下文工程里很重要的一部分。你可以把它理解成给 AI 准备的一份项目说明书。

不过这里有个边界要注意：它不是你一改完，当前正在跑的会话就一定会立刻全量重读。

更稳妥的理解是：Codex 一般会在新一轮任务，或者新会话开始时，重新整理这一轮要遵守的说明。所以如果你刚改了 AGENTS.md，最好重新开一轮。另外，Codex 启动时所在的工作目录也会影响它实际读到哪些 AGENTS.md。如果 Codex 是在 ~/project/mp/ 下打开的，你不能默认期待它在修改 ~/project/real/ 时自动遵守 ~/project/real/AGENTS.md，除非它显式读取了那个文件，或者当前工作区/上下文机制已经把它纳入了。

MCP

MCP 一般翻译为“模型上下文协议”，是一种工具调用机制。

MCP 可以理解为 Agent 和工具服务之间的一套调用约定。这个工具服务可以是本地的（很多页面里会写成大写的 STDIO，本质上就是 stdio，也就是标准输入输出），也可以是远程的（通过流式 HTTP）。

MCP 作为标准协议，把各家 Agent 接工具的方式稍微统一了一些。现在一个写好的 MCP 工具，市面上很多 Agent 都能比较轻松地接进去。

与此同时，MCP 也让功能可以从 Agent 里解耦出来，不必完全内置在 Agent 本体里，便于单独维护。

管理 MCP

在 Codex IDE 插件等图形化工具中，打开“设置”菜单，选中“MCP 服务器”选项卡，点击“添加服务器”就可以创建新的 MCP 服务。

这里再稍微重复一下。新建页面里那个经常写成全大写的 STDIO，很多人一开始其实没看出来，它说的就是 stdio。如果你学过 C 语言，也可以直接把它联想到“标准输入输出”那套东西：说白了就是通过标准输入输出和本地程序交互。至于流式 HTTP，说白了就是和远程服务器通信。很多厂家提供的 MCP 服务都是远程的，好处是省事，不用自己额外安装工具；坏处就是服务商说关就关，而且你的数据也可能被它收集。

如果你主要用 Codex CLI，更推荐直接用 codex mcp add、codex mcp list 和 codex mcp login 来管理。/mcp 更适合在当前会话里查看可用的 MCP 服务和工具；当然，你也可以直接去 ~/.codex/config.toml 里手动改。

例子：Github MCP

如果想让 Codex 支持对 GitHub 的操作，比如读写 Issue、查看仓库信息等，就得先接一个 GitHub 相关的 MCP 服务。这个东西并不是只有一种写法，本地 STDIO 方案和远程 MCP 都有人在用。

如果你接的是很多旧资料里常见的本地 STDIO 方案，配置可能会长这样：

[mcp_servers.github]
command = "npx"
args = ["-y", "@anthropic/mcp-server-github"]
enabled = true
startup_timeout_sec = 15
tool_timeout_sec = 60
bearer_token_env_var = "GITHUB_PAT_TOKEN"

如果你接的是远程 MCP 服务，那么也可能会写成：

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT_TOKEN"

这两种都不是错的，主要看你接的是哪一类服务。前者是本地起服务，后者是直接连远程地址。至于认证，如果服务方要求你用 PAT 或 OAuth，就按它的要求去配。更省事一点的话，也可以直接用 codex mcp add 去加。

Skills

Skills 一般翻译为“技能”，是一种渐近式披露提示词的机制。

一个 Skill 大致可以分成三个部分：

用户发任务给 Agent 时，Agent 会先把本地能扫描到的 Skill 元数据提取出来，形成一个技能列表，一并发给大模型。大模型如果觉得某个 Skill 适合当前任务，Agent 才会进一步把这个 Skill 的指令部分发给它。

因为元数据一般占得少，不怎么浪费 Token；而且只有模型判断需要时，详细指令才会继续加载，所以 Skill 才会被说成是按需加载、渐近式披露的提示词机制。

至于资源，它们不会像元数据那样预加载，但在 Skill 真正执行时，可能会按需读进上下文，或者直接被调用。

开启 Skills 功能

如果你看的还是比较老的资料，可能会见到有人在 ~/.codex/config.toml 里这样开 Skills：

[features]
skills = true

不过这更像是旧版本的历史配置。现在的新版本一般默认就支持 Skills，不需要你再额外打开。

管理 Skills

新增一个 Skill 其实很简单。

Skill 一般是以文件夹的形式组织的，不过这个文件夹不能乱放。就我当前这套环境来说，我平时主要用这两个位置：

不过有些手册或资料里，你也可能会看到 .agents/skills 这种写法。所以最稳妥的办法，还是以你自己当前客户端实际能识别到的路径为准。

每个 Skill 文件夹下必须要有一个 SKILL.md 文件用于存放元数据和指令，其余的文件统称资源（比如脚本、文档、图片等），如下：

my-skill/
├── SKILL.md
├── assets/         # 图片等资源
├── references/     # 文档
└── scripts/        # 脚本
    └── helper.py

SKILL.md 的格式如下：

---
name: Skill 的名字
description: Skill 的调用时机(这个比较关键)
---

指令部分

上面模板里用 6 个 - 包起来的部分就是元数据。

写好 Skill 后，重启 Codex，输入 /skills，看看能不能在技能列表里看到它。

不过很多时候我们也不会自己从零写，而是直接去 GitHub 拉别人现成的，比如 mattpocock/skills。

例子：早餐推荐

比如有时候我不知道每天早餐吃什么比较好，就可以写一个全局的 Skill 来辅助我这个选择困难症患者挑选。

创建 ~/.codex/skills/挑选早餐/SKILL.md，并写入：

---
name: 挑选早餐
description: 当用户不知道早上吃什么的时候，为用户提供推荐早餐
---
我是一个湖北武汉人，你是我的早餐推荐助手，以下是一些武汉本地的早点，挑选 3～5 个早点给我。请用中文输出。

- 热干面
- 三鲜豆皮
- 面窝
- 鲜鱼糊汤粉
- 烧梅
- 油饼包烧梅
- 牛肉粉
- 牛肉面
- 汤包
- 生煎包
- 鸡冠饺
- 汽水包
- 糯米包油条
- 糯米鸡
- 欢喜坨
- 米粑
- 锅贴
- 水饺
- 抄手
- 包子
- 油条
- 糊米酒
- 蛋酒
- 清酒
- 豆浆
- 绿豆汤
- 稀饭

然后重启 Codex，输入“我不知道早上吃什么比较好”，Codex 就会给你输出推荐，如下：

今天早上可以这样吃，比较稳妥：

1. 热干面 + 豆浆
    经典搭配，顶饱，咸香配清爽，早上很合适。

2. 三鲜豆皮 + 糊米酒
    豆皮更有层次，糊米酒暖胃，适合想吃得丰富一点。

3. 牛肉粉
    如果你今天想吃热乎、扎实一点，这个最稳。

4. 汤包 + 稀饭
    想吃得清淡些就选这个，舒服，不容易腻。

5. 糯米包油条
    非常顶饿，适合上午事情多、怕饿得快。

如果你懒得选，我直接替你定一个：热干面 + 豆浆。

Skills VS MCP

它们两个看起来很像，实际上是两个不同的概念，侧重点不太一样，见下表：

类型 侧重点 类比 Token 消耗 核心主体 编写难度
Skill 提示词 带目录的说明书 低 Markdown 文件 低
MCP 工具调用 标准化工具箱 高 MCP server / 工具服务 高

Skills 主要负责按需、渐近地披露提示词，而 MCP 主要负责把工具接进来。

不知道什么时候用哪个，可以参考下面这张快速判断表：

问题 更适合
Agent 缺少访问某个系统的能力 MCP
需要获取实时或私有数据 MCP
涉及认证和授权 MCP
需要执行外部写操作 MCP
已有工具，但执行流程不稳定 Skill
需要遵循固定步骤 Skill
需要固定输出格式 Skill
需要复用模板、规范和示例 Skill
需要“访问系统并按固定流程处理” MCP + Skill

Subagent

之前在 Agentic Engineering 博客中其实已经有个详细的描述了，如果你没有看过，可以去那篇文章参考一下。

我认为使用 Subagent 本质上就是为了做上下文隔离，防止复杂任务撑爆 Main Agent。

关于 Subagent 的优势与劣势，我的总结如下：

项目 单 Agent Main Agent + 多个 Subagent
执行方式 以串行为主 独立任务可以并行
上下文 所有资料和过程集中在一个上下文中 每个 Subagent 只关注自己的任务，Main Agent 主要保留计划和结果
专业分工 一个 Agent 同时承担多个角色 可以为不同角色配置不同规则和工具
审核方式 容易变成“自己写、自己审” 可以由独立的审核 Agent 重新检查
Token 消耗 通常更少 通常更多
协调成本 较低 需要处理任务交接、依赖关系和结果汇总
适用任务 简单修改、单一领域、小规模任务 多模块、可并行、上下文较大或需要独立审核的任务
角色与会话 Main Agent 持续负责整个任务 Subagent 的角色配置可以长期保留，但每次被调用的任务会话通常是临时的

Codex App、Codex CLI 和 IDE 插件现在都支持 Subagent。

不过最稳的触发方式，还是你明确告诉 Codex 要几个、每个干什么。除此以外，如果 AGENTS.md 或 Skill 里已经把委派规则写得很清楚，Codex 也可能自己触发 Subagent。

每个 Subagent 一般都是临时的，什么时候创建、什么时候结束，通常由 Main Agent 和 Codex 自己管理。当然用户也可以通过提示词等方式主动控制。

比如我要分析一个博客开发目录，可以输入如下的提示词：

不做任何修改。

使用三个 Subagent 并行分析

第一个 Subagent 负责分析博客架构。

第二个 Subagent 负责分析文章风格。

第三个 Subagent 负责分析国际化部分如何。

三个 Subagent 都完成任务后，Main Agent 汇总一份博客报告，简单介绍当前博客，并列出它当前的问题。

这里 Main Agent 会创建三个 Subagent 并行完成任务。

配置 Subagent

这里需要先区分 MultiAgent v1 和 MultiAgent v2。

它们并不是同一套配置换了几个字段名，而是两套不同的多 Agent 实现。Codex 会根据模型目录中的配置和功能开关选择使用哪一套，所以即使 Codex 客户端版本没有变化，只是切换了模型，实际使用的配置也可能不一样。

配置文件根据作用域分为两个位置：

MultiAgent v1

MultiAgent v1 使用 [agents]：

[agents]
max_threads = 6
max_depth = 1

这就是 v1 明确支持的写法，并不是配置错误。

MultiAgent v2

MultiAgent v2 使用 [features.multi_agent_v2]，例如：

[features.multi_agent_v2]
enabled = true
max_concurrent_threads_per_session = 7
hide_spawn_agent_metadata = false
tool_namespace = "agents"

v2 不再使用 max_depth，这个字段只负责限制 v1 的嵌套深度，在 v2 中会被忽略。如果不希望 v2 的 Subagent 继续创建 Subagent，可以在 Subagent 的 developer_instructions 或 AGENTS.md 中写入禁止规则，不过这种方式属于提示词约束，不是 v1 中 max_depth 那样的运行时硬限制。

我现在使用的 Codex CLI 0.145.0 中，模型目录为 GPT-5.6 Sol 和 GPT-5.6 Terra 指定了 v2，而 GPT-5.6 Luna 仍然使用 v1。GPT-5.4 和 GPT-5.5 没有在模型目录中强制指定版本，会继续受到本地功能开关等配置影响。不过这个映射也会随着更新发生变化，例如 Codex CLI 0.142.5 的模型目录就曾经为 GPT-5.5 指定 v2。

所以配置 Subagent 时，不能只看 Codex 的版本，还要确认当前模型实际选择的是 MultiAgent v1 还是 v2。也不要把两套配置混在一起使用，否则很容易出现配置已经写了，但实际没有生效的情况。

自定义 Subagent

很多时候，通用 Subagent 并不完全贴合实际项目，而且每次任务想要的职责划分也可能不一样。

所以实际项目里，一般还是得自己定义一套 Subagent。

管理自定义 Subagent

根据作用域，同样分两种位置存放：

一个最基础的 Subagent 配置大概长这样：

name = "Agent 名称"
description = "什么时候适合调用这个 Agent"
developer_instructions = "Agent 的角色、职责、工作边界和输出要求"

model = "可选，指定使用的模型"
model_reasoning_effort = "可选，指定推理强度"
sandbox_mode = "可选，指定文件和命令权限"

Bug 说明与解决方案

目前 GPT 5.5/5.6 貌似会有 Bug 无法读取自定义配置。

创建 Subagent 会走内部的工具，而非用户的配置。

目前貌似最方便的办法就是给降到 GPT 5.4 启动 Codex ，命令为：

codex -m gpt-5.4

貌似还有其它的办法，见这个视频下的第一个评论回复，如图：

评论区截图

我还没尝试过，我目前的方案是 Main Agent 为 GPT 5.4 ，Subagent 为 GPT 5.6 。

感觉这个方案还行，毕竟干活的主要还是 Subagent ，而 Main Agent 只起到调度的作用。

结语

不得不感叹这群玩 AI 的搞出来的概念真是多。什么“渐近式披露”了之类的，每隔几周或者更快的时间就可能会搞出一个新概念。

感觉现在只要是和写程序相关的工作，已经很难离开 AI 了。无论你是新手还是大佬，是干互联网的，还是干嵌入式之类的，据我所知几乎都在用 AI，每天挂着刷几千行也很常见。

可以说如果你不用，那么你的产出就上不去，然后就被淘汰，被公司扫地出门了。

所以这些新的概念我们要学，虽然不一定用得上，但是要有所了解。

后续应该还会出一篇 MCP 和 Skills 的收集推荐博客吧。最近被好友推荐了一些 Skills，感觉还不错。

参考资料

这里的资料比较乱，可能有重复。可以按需观看，并非需要全部看完。

AI Agent 相关概念：

Codex 的使用：

Skills：

MCP：

Subagent：

文章作者：成元
上次更新：2026-08-03