VSCode中使用Codex命令、Agent与Skills的完整指南

先说几个核心判断。

最近身边不少开发者开始从Claude Code、Cursor、Copilot等工具转向或尝试OpenAI Codex。相比单纯在网页端提问，Codex更适合直接进入项目工程——读代码、分析结构、改文件、生成文档、排查报错，一步到位。

这篇文章主要围绕VSCode展开，咱们不玩纯命令行那套，而是直接上手

Codex官方支持通过IDE扩展在VSCode、Cursor、Windsurf等编辑器中使用，并可以读取编辑器中的文件、选区以及项目上下文。官方也提供了VSCode命令面板、Slash commands、AGENTS.md、Skills、Subagents、自定义Agents等能力。

一、本文适合谁阅读

你可能想知道这玩意儿到底适合谁，简单说，以下人群最合适：

1. 想在

   VSCode
   中使用Codex的开发者
2. 想把Codex用在真实项目中的初学者
3. 想搞清楚AGENTS.md、Skills、Subagents到底怎么用的用户
4. 打算从Claude Code迁移到Codex的用户
5. 希望用Codex辅助后端、前端、数据库、文档生成、代码审查的开发者

本文以Windows + VSCode为主要使用环境，示例项目目录使用D:aitest，你可以根据自己的项目路径替换。

二、Codex在VSCode中的推荐使用方式

如果你主要用VSCode，那么Codex的最佳使用方式绝不是一直在终端里敲命令，而是这样：

VSCode Codex扩展：日常对话、读取文件、修改代码
VSCode命令面板：添加选中代码、添加当前文件、实现TODO
VSCode终端：安装、检查版本、执行一次性命令
AGENTS.md：项目长期规则
.agents/skills：专项能力包
.codex/agents：自定义Agent
.codex/config.toml：Codex配置

理想的使用习惯应该长这样：

打开VSCode项目
→ 打开Codex侧边栏
→ 让Codex读取AGENTS.md
→ 选中文件或代码加入上下文
→ 使用Skill或Agent完成专项任务
→ 查看diff
→ 测试项目

Codex IDE扩展支持在编辑器中使用打开的文件、选中的代码片段和@file引用来提供上下文，也可以在IDE内切换模型、调整审批模式、委派云端任务、使用Slash commands。

三、安装Codex VSCode扩展

1. 在VSCode中安装

打开VSCode，进入扩展市场：

Extensions
→ 搜索Codex
→ 安装OpenAI Codex扩展

也可以通过命令面板打开扩展安装页面：

Ctrl + Shift + P
→ 输入Extensions: Install Extensions
→ 搜索Codex

安装完成后，Codex会出现在VSCode左侧边栏。如果没有看到，可以在命令面板中搜索Codex相关命令。官方Quickstart说明，安装IDE扩展后Codex会显示在编辑器侧边栏，需要登录后开始使用。

四、VSCode中Codex的常用命令

在VSCode里按下Ctrl + Shift + P，然后搜索Codex，你会看到一堆命令。挑几个最常用的说：

Codex官方IDE命令文档列出了这些命令，例如chatgpt.addToThread用于添加选中代码，chatgpt.addFileToThread用于添加整个文件，chatgpt.implementTodo用于实现TODO，chatgpt.openSidebar用于打开侧边栏。

五、VSCode中最推荐的新手使用流程

第一次打开项目，别急着让Codex动手改代码。先让它只读分析项目结构，摸清底细再说。

第一步：打开整个项目目录

不要只打开单个文件，应该打开整个项目文件夹：

File
→ Open Folder
→ 选择项目根目录

例如：D:aitest

这样Codex才能读取到完整的项目结构。

第二步：让Codex只读分析项目

在Codex侧边栏输入：

请只读分析当前项目，不要修改任何文件。
请说明：
1. 后端入口在哪里
2. 前端入口在哪里
3. 数据库相关代码在哪里
4. 启动命令是什么
5. 当前项目可能有哪些风险点

第三步：让Codex给修改方案

请根据当前项目结构，告诉我如果要修改"任务恢复"和"分页显示"，会涉及哪些文件。
暂时不要修改。

第四步：确认方案后再修改

可以按方案修改。
要求：
1. 只修改必要文件
2. 不要动无关代码
3. 不要删除数据
4. 涉及数据库只给SQL，不要直接执行
5. 修改完成后给出测试步骤

第五步：查看修改结果

修改完成后，在VSCode左侧的Source Control中可以查看变更，也可以让Codex总结：

请总结本次修改：
1. 修改了哪些文件
2. 每个文件改了什么
3. 是否涉及数据库SQL
4. 是否涉及删除逻辑
5. 后端如何启动
6. 前端如何启动
7. 如何验证功能
8. 如何回滚

六、VSCode终端中的Codex命令

虽然主要讲VSCode使用方式，但终端仍然是绕不开的一环。

1. 安装Codex CLI

如果你希望在VSCode终端里使用Codex CLI，可以执行：

npm install -g @openai/codex

检查版本：

codex --version

Codex CLI是OpenAI的本地编码Agent，可以在终端中读取、修改和运行当前目录中的代码。官方文档说明，Codex CLI可以通过npm或Homebrew安装。

2. 进入项目目录

cd D:aitest

3. 只读分析项目

codex --sandbox read-only --ask-for-approval on-request

适合第一次分析项目、检查代码、看报错。

4. 允许修改当前工作区

codex --sandbox workspace-write --ask-for-approval on-request

适合确认方案之后，让Codex修改当前项目内的代码。

5. 一次性生成项目分析报告

codex exec "分析当前项目结构，输出后端、前端、数据库、任务队列、目录监听相关模块"

6. 检查危险删除逻辑

codex exec --sandbox read-only "检查当前项目中是否存在DELETE、TRUNCATE、DROP、shutil.rmtree、os.remove、rmdir /s /q 等危险操作"

Codex CLI官方参考文档列出了--sandbox、--ask-for-approval、--cd、--model、--image、exec等命令和参数，并说明命令行参数可以覆盖config.toml中的默认配置。

七、VSCode中的Slash Commands

在Codex聊天输入框中输入/，可以打开Slash commands。

常用命令包括：

Codex IDE扩展支持在聊天输入框中使用Slash commands，用于查看状态、切换模式、发送反馈等；Codex CLI中的Slash commands还支持切换模型、调整权限、总结长对话等能力。

八、AGENTS.md：给Codex的项目说明书

1. AGENTS.md是什么？

AGENTS.md可以理解为“写给Codex看的项目说明书”。README.md通常是写给人看的，而AGENTS.md是写给AI Agent看的。它可以告诉Codex：

项目是什么
技术栈是什么
启动命令是什么
哪些文件不能随便改
数据库修改要注意什么
删除操作有哪些限制
代码风格是什么
任务完成后要输出什么

官方文档说明，Codex会在开始工作前读取AGENTS.md，可以通过全局规则和项目级规则叠加，让不同仓库拥有一致的工作要求。

2. AGENTS.md放在哪里？

项目级文件建议放在项目根目录：D:aitestAGENTS.md。如果是全局规则，可以放在：C:Users你的用户名.codexAGENTS.md。项目级规则适合记录当前项目特有的要求，全局规则适合记录你个人长期使用习惯。

3. AGENTS.md示例

# AGENTS.md
## 项目背景
这是一个本地部署的xxxxx管理系统，用于xxxxxxx。
## 技术栈
- 后端：FastAPI + Uvicorn
- 前端：前后端分离
- 数据库：MySQL
- 目录监听：watchdog
## 工作规则
- 修改代码前，必须先阅读项目结构。
- 修改前必须说明会影响哪些文件。
- 修改后必须给出启动命令和测试步骤。
- 不允许把所有功能堆在一个页面或一个文件里。
- 不允许把HTML写死在Python字符串中。
- 不允许默认使用SQLite，数据库优先使用MySQL。
- 涉及数据库结构修改时，必须给出完整SQL。
- 涉及删除文件、删除结果、清空数据库时，必须有二次确认、操作日志和回滚说明。
## 输出规范
- 原图文件名不能被破坏。
- xxxxx
- xxxxx
- xxxxx
- JSON输出需要稳定，可供其他系统对接。
## 完成标准
每次任务完成后必须说明：
1. 修改了哪些文件。
2. 每个文件修改了什么。
3. 如何启动后端。
4. 如何启动前端。
5. 如何验证功能。
6. 是否涉及数据库SQL。
7. 是否存在风险和回滚方式。

九、Skills：给Codex增加专项能力

1. Skills是什么？

Skills可以理解为Codex的“专项工作手册”。比如你经常让Codex检查YOLO项目代码、生成MySQL迁移SQL、检查危险删除逻辑、整理MQTT设备API文档、重构前端页面、生成测试步骤——这些重复性的要求，就可以封装成一个Skill。

官方说明中，Skill是一个目录，里面必须包含SKILL.md，也可以包含脚本、参考文档、资源文件等。Codex可以通过Skills获得特定任务的流程和专业知识。

2. Skills放在哪里？

项目级Skills建议放在D:aitest.agentsskills。目录示例：

D:aitest
├─ AGENTS.md
├─ .agents
│ └─ skills
│ ├─ code-review
│ │ └─ SKILL.md
│ ├─ mysql-safe-migration
│ │ └─ SKILL.md
│ └─ dangerous-delete-guard
│ └─ SKILL.md

3. 在VSCode中如何调用Skill？

在Codex聊天框中直接输入：

请使用 $code-review 检查当前项目的任务队列和断点续扫逻辑。

或者：

请使用 $mysql-safe-migration 生成本次数据库修改SQL、备份SQL、回滚SQL。

或者：

请使用 $dangerous-delete-guard 检查当前项目是否存在高风险删除逻辑。

十、Skill示例一：代码审查

文件路径：D:aihelmet.agentsskillsyolo-code-reviewSKILL.md

内容：

---
name: code-review
description: 当任务涉及xxxxx管理系统、FastAPI后端、MySQL、watchdog监听、任务队列、断点续扫、分页、识别结果JSON输出时使用。
---
#代码审查 Skill
## 使用场景
当用户要求检查或修改以下内容时使用：
- xxxxx管理系统
- FastAPI后端
- MySQL数据库
- watchdog目录监听
- 任务队列
- 断点续扫
- 分页
- 输出结果
- 识别结果JSON
## 工作流程
1. 先阅读项目结构，不要直接修改。
2. 找到后端入口、数据库模型、任务服务、监听服务、前端页面。
3. 修改前说明会影响哪些文件。
4. 涉及数据库变更时给出完整SQL。
5. 涉及删除功能时必须要求二次确认、操作日志和回滚方式。
6. 修改完成后给出启动命令、测试步骤和风险点。
## 禁止事项
- 不允许默认清空数据库。
- 不允许删除模型权重文件。
- 不允许把HTML写死在Python字符串里。
- 不允许只改前端不改后端接口。
- 不允许破坏原始图片文件名。

十一、Skill示例二：MySQL安全迁移

文件路径：D:aitest.agentsskillsmysql-safe-migrationSKILL.md

内容：

---
name: mysql-safe-migration
description: 当任务涉及MySQL表结构修改、数据迁移、清库、删除识别结果、DELETE、TRUNCATE、DROP、备份和回滚时使用。
---
# MySQL安全迁移 Skill
## 触发场景
- 修改MySQL表结构
- 新增字段
- 删除字段
- 清理识别结果
- 删除任务数据
- 批量删除JSON或图片
- 使用DELETE / TRUNCATE / DROP
- 生成数据库升级SQL
## 工作步骤
1. 先识别涉及哪些表。
2. 判断是否会影响历史数据。
3. 给出备份SQL。
4. 给出迁移SQL。
5. 给出回滚SQL。
6. 给出验证SQL。
7. 对DELETE / TRUNCATE / DROP做高风险提示。
## 输出格式
必须输出：
- 涉及表
- 风险等级
- 执行前备份SQL
- 正式执行SQL
- 回滚SQL
- 验证SQL
- 注意事项
## 禁止事项
- 不允许直接清空数据库。
- 不允许没有WHERE的DELETE。
- 不允许没有备份方案的DROP / TRUNCATE。
- 不允许忽略外键、索引、历史数据兼容问题。

十二、Skill示例三：危险删除保护

文件路径：D:aitest.agentsskillsdangerous-delete-guardSKILL.md

内容：

---
name: dangerous-delete-guard
description: 当任务涉及删除文件、删除目录、删除数据库记录、清空识别结果、shutil.rmtree、os.remove、rm、rmdir、DELETE、TRUNCATE、DROP时使用。
---
# 危险删除保护 Skill
## 检查范围
需要重点检查：
- Python: os.remove
- Python: os.unlink
- Python: shutil.rmtree
- Shell: rm -rf
- Windows: rmdir /s /q
- SQL: DELETE
- SQL: TRUNCATE
- SQL: DROP
- 前端批量删除按钮
- 后端批量删除接口
## 强制要求
任何删除功能必须包含：
1. 二次确认。
2. 删除范围预览。
3. 操作日志。
4. 操作人或来源记录。
5. 删除数量统计。
6. 异常回滚或失败记录。
7. 不允许删除模型权重文件。
8. 不允许误删raw原始图片。
## 输出格式
请输出：
- 高风险代码位置
- 风险说明
- 可能后果
- 推荐修复方式
- 是否必须立即修改

十三、自定义Agent：让Codex拥有不同角色

1. Agent和Skill的区别

很多人容易把Agent和Skill混在一起，可以这样理解：

例如：project_explorer负责只读分析项目结构，reviewer专门做代码审查，mysql_guardian专门检查数据库风险。

官方Subagents文档说明，Codex可以派生多个子Agent并行工作，等待它们完成后汇总结果；自定义Agent可以放在~/.codex/agents/或项目级.codex/agents/中。

2. 自定义Agent放在哪里？

项目级Agent建议放在D:aitest.codexagents。目录结构：

D:aitest
├─ .codex
│ ├─ config.toml
│ └─ agents
│ ├─ project-explorer.toml
│ ├─ reviewer.toml
│ └─ mysql-guardian.toml

十四、自定义Agent示例

1. 项目探索Agent

文件路径：D:aitest.codexagentsproject-explorer.toml

内容：

name = "project_explorer"
description = "只读项目结构分析Agent，用于在修改代码前梳理目录、模块、调用链和风险点。"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
你是只读项目探索Agent。
你的任务：
1. 阅读项目结构。
2. 定位后端入口。
3. 定位前端入口。
4. 定位数据库模型。
5. 定位任务队列和目录监听逻辑。
6. 输出风险点和下一步建议。
禁止修改任何文件。
"""

2. 代码审查Agent

文件路径：D:aitest.codexagentsreviewer.toml

内容：

name = "reviewer"
description = "代码审查Agent，重点检查正确性、安全风险、测试缺失和可维护性。"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
你是严格的代码审查Agent。
重点检查：
1. 逻辑错误
2. 安全问题
3. 数据库风险
4. 删除操作风险
5. 并发问题
6. 测试缺失
7. 可维护性问题
不要修改代码，只输出审查结果。
每个问题必须包含：
- 问题位置
- 风险说明
- 修改建议
- 是否必须修复
"""

3. 数据库安全Agent

文件路径：D:aitest.codexagentsmysql-guardian.toml

内容：

name = "mysql_guardian"
description = "MySQL数据库安全Agent，用于检查表结构修改、DELETE、TRUNCATE、DROP、清库、迁移和回滚风险。"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
你是MySQL数据库安全Agent。
重点检查：
1. 是否存在DROP / TRUNCATE / DELETE无条件执行
2. 是否缺少事务
3. 是否缺少备份方案
4. 是否缺少回滚SQL
5. 是否影响历史识别结果
6. 是否存在连接池耗尽风险
7. 是否存在字段兼容问题
不要直接执行数据库命令。
输出必须包含：
- 风险等级
- 涉及表
- 涉及SQL
- 修复建议
- 备份方案
- 回滚方案
"""

十五、VSCode中如何使用多个Agent

在Codex聊天框中输入：

请启动3个subagents并行分析当前项目：
1. project_explorer：分析项目结构、入口文件和调用链。
2. reviewer：检查代码质量、安全风险和测试缺失。
3. mysql_guardian：检查MySQL表结构、删除逻辑和迁移风险。
要求：
- 不要修改文件。
- 每个Agent单独输出发现。
- 最后由主Agent汇总成一份修改优先级清单。

这种方式适合大项目整体审查、前后端同时修改前的风险分析、数据库迁移前检查、删除功能上线前检查、任务队列和并发问题排查。不过要注意，Subagents会消耗更多上下文和token，不适合简单问题。官方也说明Codex只会在用户明确要求时创建新的Agent。

十六、Codex配置文件config.toml

1. 配置文件位置

用户级配置：C:Users你的用户名.codexconfig.toml。项目级配置：D:aitest.codexconfig.toml。Codex配置文档说明，config.toml用于配置模型、审批策略、沙箱、MCP等内容；Codex CLI会继承~/.codex/config.toml中的大多数默认设置。

2. 推荐配置

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[agents]
max_threads = 4
max_depth = 1

如果你主要使用VSCode，不建议过度依赖profile。官方高级配置文档说明，profiles目前主要用于CLI，暂不支持Codex IDE extension。

如果使用CLI，可以再增加：

[profiles.readonly]
approval_policy = "on-request"
sandbox_mode = "read-only"

[profiles.dev]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.strict]
approval_policy = "untrusted"
sandbox_mode = "read-only"

然后在终端中使用：codex --profile readonly或codex --profile dev。

十七、推荐项目目录结构

如果你想长期稳定使用Codex，建议项目结构整理成这样：

D:aitest
├─ AGENTS.md
├─ .codex
│ ├─ config.toml
│ └─ agents
│ ├─ project-explorer.toml
│ ├─ reviewer.toml
│ └─ mysql-guardian.toml
├─ .agents
│ └─ skills
│ ├─ code-review
│ │ └─ SKILL.md
│ ├─ mysql-safe-migration
│ │ └─ SKILL.md
│ ├─ dangerous-delete-guard
│ │ └─ SKILL.md
│ ├─ mqtt-api-doc-writer
│ │ └─ SKILL.md
│ └─ frontend-page-refactor
│ └─ SKILL.md
├─ backend
├─ frontend
├─ README.md
└─ requirements.txt

十八、VSCode中最常用的提示词模板

1. 只读分析项目

请读取AGENTS.md，并只读分析当前项目结构。
不要修改任何文件。
请告诉我：
1. 项目整体结构
2. 后端入口
3. 前端入口
4. 数据库相关文件
5. 任务队列相关文件
6. 目录监听相关文件
7. 当前项目主要风险点

2. 修改前给方案

请给出修改方案。
要求说明：
1. 要修改哪些文件
2. 每个文件为什么要修改
3. 是否涉及数据库
4. 是否涉及删除操作
5. 风险点是什么
6. 如何验证
暂时不要修改。

3. 使用Skill检查项目

请使用 $code-review 检查当前项目的任务队列、watchdog监听、断点续扫和分页逻辑。
先给出问题清单和修改方案，不要直接修改。

4. 使用Skill检查删除风险

请使用 $dangerous-delete-guard 检查当前项目中所有删除相关逻辑。
重点搜索：
- os.remove
- os.unlink
- shutil.rmtree
- rm -rf
- rmdir /s /q
- DELETE
- TRUNCATE
- DROP
- 批量删除接口
- 前端删除按钮
不要修改文件，只输出风险清单和修复建议。

5. 使用Skill生成数据库迁移SQL

请使用 $mysql-safe-migration 分析这次数据库修改需求。
要求输出：
1. 涉及表
2. 备份SQL
3. 修改SQL
4. 回滚SQL
5. 验证SQL
6. 风险说明
不要直接执行SQL。

6. 多Agent并行审查项目

请启动3个subagents并行审查当前项目：
1. project_explorer：只读分析项目结构和调用链。
2. reviewer：检查代码正确性、安全性和测试缺失。
3. mysql_guardian：检查数据库结构、删除逻辑和迁移风险。
要求：
- 不要直接修改代码。
- 每个Agent单独输出发现。
- 最后由主Agent汇总成一份修改优先级清单。

7. 修改完成后总结

请总结本次修改：
1. 修改了哪些文件
2. 每个文件修改了什么
3. 是否涉及数据库
4. 是否涉及删除操作
5. 如何启动后端
6. 如何启动前端
7. 如何验证功能
8. 如何回滚

十九、初学者使用Codex的注意事项

1. 不要一上来就让Codex改代码

错误示例：帮我把整个项目优化一下。 更好的写法：请先只读分析当前项目结构，不要修改文件。然后告诉我如果要优化任务恢复逻辑，需要改哪些文件。

2. 涉及数据库时，不要让Codex直接执行SQL

建议这样说：涉及数据库的部分只给SQL，不要直接执行。请同时给出备份SQL、修改SQL、回滚SQL和验证SQL。

3. 涉及删除功能时，一定要加限制

建议这样说：涉及删除文件、删除结果、清空数据库的功能，必须有二次确认、删除范围预览、操作日志和回滚说明。

4. 不要只打开单个文件

使用Codex时，建议打开完整项目目录，否则Codex很难理解项目结构，也容易改错地方。

5. 长会话要及时压缩或新开对话

如果在一个任务中连续修改很多轮，可以使用/compact，或者新建一个Codex对话，让上下文更清晰。

二十、最终建议

最后说一句：如果你主要在VSCode中使用Codex，建议优先掌握这6件事——打开完整项目目录、打开Codex侧边栏、使用Add selected text to thread、使用Add file to thread、编写AGENTS.md、使用$skill-name调用Skills。

然后再逐步掌握.codex/config.toml、.codex/agents、.agents/skills、Subagents、Slash commands、Codex CLI。

对真实项目来说，最推荐的组合是：

• AGENTS.md：项目总规则
• Skills：专项操作手册
• Custom Agents：专业角色
• Subagents：多角色并行审查
• config.toml：默认配置
• VSCode Codex扩展：日常主入口

一句话总结：在VSCode中使用Codex，最好的方式不是直接让它乱改代码，而是先用AGENTS.md定规则，再用Skills固化流程，再用Agent分工审查，最后让Codex在明确边界内修改和验证。