🧭 **这是 Codex + VS Code 系列的目录页。**从安装、下任务和配置，到代码验收、长任务与故障排查，下面 6 篇各解决一个具体问题。可以顺着练，也可以按症状跳到对应文章。操作说明更新至 2026 年 10 月 29 日。
全部 Codex 文章：本页是 VS Code 系列目录；系列之外的 Codex 文章，都收录在 省点力 · Codex 小类。
先说结论：最值得学的 5 件事
- 给 Codex 正确的代码上下文，减少反复解释。
- 用
AGENTS.md保存项目规则。 - 让 Codex 先分析、再修改，最后检查 Diff 和测试结果。
- 学会在 VS Code、CLI、云端任务之间切换。
- 处理长会话、卡顿、权限和额度问题。
这些比单纯的安装教程有用得多。对需要用 Codex 持续维护项目的人，最该掌握的是这一套：**读懂原项目 → 控制修改范围 → 执行测试 → 检查 Diff。**只会装插件、输入一句“帮我优化网站”，远远不够。
6 篇文章
- Codex 第一次上手：装对插件、登录成功、选对入口：插件装错、登录失败、不知道该用插件、CLI、App 还是云端；Windows 上第一步就卡住；装好了不知道第一天练什么。
- 让 Codex 听懂你：上下文、提示词和斜杠指令怎么用：Codex 理解错需求、反复解释、改的范围失控；不知道怎么点名文件、贴截图和报错；斜杠指令一大堆不知道先用哪个。
- 一次配好 Codex：AGENTS.md、config.toml、Skills 与 MCP：每次都要重新交代项目规则；
AGENTS.md、config.toml、Skills、MCP 不知道该写什么、放哪里；网上旧配置照搬后不生效。 - Codex 改代码不翻车：权限、分支、Diff、测试和 Code Review：怕它改坏代码、改到不该动的地方；它说“完成了”其实没测过；权限不知道怎么给；不会看 diff、不会让它做 Code Review。
- Codex 长任务和大项目：计划文件、Goals、会话管理、并行、云端与额度：大任务、跨天任务一做就乱；对话太长上下文混乱；想并行、想交给云端；不知道怎么选模型、怎么省额度。
- Codex 出问题怎么办：消息卡住、插件卡顿、历史消失、登录报错：消息卡住、一直转圈或消失；插件面板卡死；历史会话找不到；登录报错、
command not found、MCP 不工作。
建议按 1 → 5 的顺序读，第 6 篇遇到问题时再查。
痛点对照：遇到这个问题看哪篇
按症状找到对应的处理办法：
| 痛点 | 用户实际遇到的问题 | 去看 |
|---|---|---|
| 1. 消息发不出去、卡住 | 输入后一直转圈、进入等待队列，甚至消息消失；2026 年 10 月 1–3 日多名用户报告（#49991、#50118） | Codex 出问题怎么办：消息卡住、插件卡顿、历史消失、登录报错 |
| 2. 插件卡顿，VS Code 本身正常 | Codex 面板停止响应，日志里有扩展进程阻塞、消息积压、服务器过载（#22393） | Codex 出问题怎么办：消息卡住、插件卡顿、历史消失、登录报错 |
| 3. 历史会话突然找不到 | 旧聊天不在历史列表里，但本地数据库和会话文件还在（#21244） | Codex 出问题怎么办：消息卡住、插件卡顿、历史消失、登录报错 |
| 4. 复杂代码修改难以一次做对 | 数据库结构变更、数据迁移、端到端测试；要看测试证据，不能只看它回复“完成” | Codex 改代码不翻车：权限、分支、Diff、测试和 Code Review、Codex 长任务和大项目：计划文件、Goals、会话管理、并行、云端与额度 |
| 5. 上下文和任务要求容易混乱 | 长任务涉及多个文件、约束和历史决策，常常要重复说明 | 让 Codex 听懂你：上下文、提示词和斜杠指令怎么用、一次配好 Codex：AGENTS.md、config.toml、Skills 与 MCP、Codex 长任务和大项目：计划文件、Goals、会话管理、并行、云端与额度 |
遇到问题时，先按这个顺序处理：
- 插件卡顿或消息消失：先查插件版本和 GitHub Issue；重载 VS Code、开新会话、回退版本只是个别版本的临时办法（Codex 出问题怎么办：消息卡住、插件卡顿、历史消失、登录报错）。
- 历史会话找不到：别马上删
.codex文件夹或清缓存，本地记录还在不等于数据丢失（Codex 出问题怎么办：消息卡住、插件卡顿、历史消失、登录报错）。 - 复杂任务质量不稳定：分阶段执行，每一段都要它跑检查、报告具体通过和失败的项目；数据库迁移、生产环境修改必须保留人工审核（Codex 改代码不翻车：权限、分支、Diff、测试和 Code Review、Codex 长任务和大项目：计划文件、Goals、会话管理、并行、云端与额度）。
- 担心浪费额度：把探索、编码和验收拆清楚，先让它找出要改的文件，再执行具体任务，避免对一个模糊问题反复全项目扫描；这是实用习惯，但不能承诺固定的节省比例（Codex 长任务和大项目：计划文件、Goals、会话管理、并行、云端与额度）。
- “修改现有网站又不想改坏其他功能”的任务模板，在 Codex 改代码不翻车：权限、分支、Diff、测试和 Code Review 的“安全修改”模板里。
怎么学最省时间
- 先完成安装篇的只读任务，熟悉界面、文件上下文和代码修改。
- 按提示词篇练习小范围修改，再用配置篇的
AGENTS.md模板记录项目规则。 - 根据实际任务补配置和 Skills，别一上来装一大堆插件。
- 最后读 GitHub 上的几个高频问题，知道哪些故障是工具自身的问题，不必盲目折腾环境。
需要界面演示时再看视频
下面的视频可辅助熟悉界面；安装参数、模型和权限设置仍以当前版本为准。
| 视频 | 作者 · 时长 | 数据 · 发布时间 | 讲什么 | 重点看 |
|---|---|---|---|---|
| Getting Started with Codex（最推荐） | OpenAI 官方 · 约 53 分钟 | 约 29.1 万播放 · 4,900 赞 · 2026-01-12 | 完整教学：VS Code 插件、CLI 安装、AGENTS.md、配置文件、提示词、MCP，以及更高级的自动化用法 | 08:12 AGENTS.md；14:14 环境配置；16:26 提示词；27:02 IDE 技巧；34:59 MCP |
| OpenAI Codex in Your Code Editor | OpenAI 官方 · 约 6 分钟 | 约 29 万播放 · 4,700 赞 · 2025-10-17 | 直接演示真实代码库：理解已有代码、修改悬停效果、云端处理任务、探索设计方案、检查代码改动 | 00:45 读代码；01:20 修改功能；02:40 云端任务；05:30 审查改动 |
| OpenAI Codex Tutorial #7 — IDE Extension | Net Ninja · 约 7 分 36 秒 | 约 6.6 万播放 · 399 赞 · 2025-10-06 | 专讲 VS Code 里的 Codex 扩展，属于完整的 11 集 Codex 课程 | 整条看完，再按需看第 8–11 集（上下文、MCP、云端、并行任务） |
**观看顺序：2 → 3 → 1。**先用 6 分钟理解 VS Code 里怎么工作，再跟着实操，最后补上完整配置和高级能力。不看视频也可以直接按文章中的步骤练习。
操作手册和故障入口
官方操作文档
| 资料 | 主要内容 | 用途 |
|---|---|---|
| Codex IDE 官方使用指南 | VS Code 安装、引用编辑器上下文、查看代码修改、云端任务 | 入门必读 |
| Codex 官方 VS Code 插件 | 插件安装、登录、功能说明 | 避免装错插件 |
| Codex 配置文件说明（中文） | config.toml、权限、模型、MCP、配置优先级 | 进阶配置 |
| Iterating Development Workflows with Codex | AGENTS.md、任务计划、分阶段执行、测试验收 | 项目实操最有用 |
| Rethinking Skills and Prompts for GPT-6 Astra | 怎么精简 Skills、项目规则和提示词 | 纠正过度配置 |
| Using Goals in Codex | 怎么定义完成条件、证据、限制和停止条件 | 复杂任务和长任务 |
特别推荐最后两份。
安装第三方配置前先检查
部分第三方教程涉及改模型供应商、权限设置或自定义 API。别照搬旧配置文件，尤其是权限和第三方模型地址，先看官方当前参数再决定改不改。
故障判断要有现场证据
保留版本号、错误信息和复现步骤，先确认自己的环境能否复现，再判断是否需要重载或回退。
GitHub 上的真实故障报告
排查时到 Codex 官方 GitHub 仓库核对问题描述、复现环境、插件版本和开发者回应。只有症状相似还不够，版本与环境也要对得上。
2026 年 10 月初那批消息队列问题，是具体版本的故障，不能简单归咎于用户不会操作。详见 Codex 出问题怎么办：消息卡住、插件卡顿、历史消失、登录报错。
新旧说法冲突时，以谁为准
旧视频适合学界面和基本操作，当前的配置、模型和工作习惯以新官方文档为准。重点检查以下设置：
AGENTS.md写多少：2025 年的一些教程教人往里塞几十甚至上百条指令；OpenAI 在 2026 年 9 月的文章里专门提醒，要重新检查这些冗长规则，“务必跑测试”这类叮嘱对 GPT-6 Astra 可以删掉。详见 一次配好 Codex：AGENTS.md、config.toml、Skills 与 MCP。- 网页搜索：旧字段
web_search_request已弃用；当前配置使用web_search，默认值是"cached"。详见 一次配好 Codex：AGENTS.md、config.toml、Skills 与 MCP。 - 审批策略：
approval_policy = "untrusted"已退役；approval_policy = "never"在公司管理的电脑上可能被requirements.toml禁止。详见 一次配好 Codex：AGENTS.md、config.toml、Skills 与 MCP、Codex 改代码不翻车：权限、分支、Diff、测试和 Code Review。
使用这些说明时要注意
- 演示视频可能使用旧界面。遇到按钮位置或参数不同，先核对本地版本，再查对应的官方操作文档。