Codex详细入门指南

Codex 详细使用指南本文是关于codex的一些基本用法的入门文档。本文会覆盖Codex 的基本用法AGENTS.md也就是常说的 agent 指令文件Skill 技能自动化 AutomationsMCP、插件、子代理与 Claude / Claude Code 的联动方式用 CC Switch 管理多个工具的配置推荐工作流和安全注意事项1. Codex 是什么Codex 是 OpenAI 面向软件开发的编码代理。它可以在你的项目上下文中读文件、修改文件、运行命令、解释代码、修 bug、写测试、做代码审查也可以通过 MCP、插件、技能和自动化连接更多工具。你可以把它理解成一个会进仓库干活的工程助手而不是只会回答问题的聊天窗口。这个区别其实挺大的普通聊天模型会告诉你“你可以这样改”而 Codex 更常见的做法是“我已经改了这几个文件跑了这些检查还有两个风险想请你确认一下”。Codex 常见使用界面包括使用界面适合场景Codex 桌面应用项目开发、长线程协作、可视化 diff、自动化、浏览器测试、管理线程Codex CLI终端优先的本地仓库开发、脚本化任务、快速修复IDE 扩展与编辑器联动读取打开文件、选中代码、局部重构Codex Cloud / Web并行托管任务、GitHub PR、远程环境中的长期工作In-app Browser / Browser Use前端页面测试、浏览器交互、截图验证Chrome 扩展 / Computer Use需要用户浏览器资料或桌面应用上下文的任务2. 第一次打开 Codex2.1 登录或输入 API key第一次打开 Codex 时你会看到登录入口。通常有两种方式用 ChatGPT 账号继续适合大多数桌面应用和日常开发场景输入 API key适合你想用 API credits 或某些更偏工程化的环境个人日常用可以先拿 ChatGPT 登录。等需要团队环境、自动化、CI 或者隔离配置的时候再回头认真整理 API key、CODEX_HOME、项目配置和权限策略。2.2 选择项目文件夹Codex的使用一定要选对项目目录。你应该尽量从仓库根目录打开项目因为那里通常有package.json、pyproject.toml、Cargo.toml等项目入口.gitREADME测试配置AGENTS.md.codex/config.toml如果你从很深的子目录打开Codex 可能看不到项目全貌如果你从太大的父目录打开它又可能读到一堆无关文件。仓库根目录通常是最舒服的位置。2.3 直接给它一个具体任务选好项目后就可以直接说要它干什么。prompt不要只丢一句“帮我优化一下”或者“修个 bug”。倒不是不能这么说但 Codex 只能靠猜猜歪了返工更费劲。更好的写法是帮我修复设置页保存失败的问题。 复现步骤 1. npm run dev 2. 打开 /settings 3. 修改 Enable alerts 4. 点击 Save 5. 刷新后状态丢失 约束 - 不要改 API 结构 - 尽量小改 - 如果可行补一个回归测试 完成前请运行相关测试并说明你验证了什么。不需要把提示词写得像合同那么严谨但得给它足够的提示。目标、上下文、限制、验收标准这四样都交代清楚Codex 的发挥就会稳定很多。3. 基本工作方式Codex 的一次工作通常是一个 thread也就是线程或会话。你给出目标Codex 读取上下文、制定方案、调用工具、编辑文件、运行命令直到任务完成或你中断它。如上文所说一个好的 Codex 提示词通常包含四个部分目标你希望 Codex 改什么、做什么、查什么。 上下文相关文件、目录、错误日志、截图、复现步骤、设计稿。 约束不要改哪些接口、遵守哪些风格、是否需要兼容旧逻辑。 完成标准测试通过、页面可用、bug 不再复现、输出某个文件。4. 常用任务模式4.1 解释代码适合新接手项目、看不懂模块关系、需要梳理请求链路时使用。阅读 src/api/user.ts 和 src/db/schema.ts解释用户创建请求的完整流程。 请说明 - 每个模块的职责 - 数据在哪里校验 - 哪些地方有兼容性风险 - 如果我要新增字段应该改哪些文件4.2 修 bug给 Codex 复现路径比只给一句“这里这里有问题”有效很多。如可以这样说这个 bug 可以这样复现 1. ... 2. ... 请先复现再定位原因最后给出最小修复。 修完后运行最小相关测试并说明验证结果。4.3 写测试如为 src/utils/parseDate.ts 的 parseDate 函数添加测试。 覆盖 - 正常 ISO 日期 - 空字符串 - 非法日期 - 时区边界 请参考现有测试风格不要引入新测试框架。4.4 做代码审查如请 review 当前未提交改动。 重点关注 - 是否有行为回归 - 是否缺少测试 - 是否有安全风险 - 是否破坏公共 API 请按严重程度排序并给出文件和行号。4.5 前端验证对于前端项目应让 Codex 启动开发服务器用浏览器或截图验证页面。实现这个交互后启动本地 dev server。 用浏览器打开页面检查桌面和移动端布局确认没有文字重叠或空白画布。 最后告诉我可访问的本地 URL。5. Plan mode 和 Goal mode5.1 Plan mode复杂、模糊、风险高的任务可以先让 Codex 计划再动手避免造成不可挽回的错误。适合大规模重构架构调整数据迁移性能优化多模块 bug需求还不清楚的功能开发可以这样说先不要改代码。请先阅读相关文件列出实现计划、风险和需要确认的问题。在支持的界面中也可以用/plan或快捷键进入计划模式。5.2 Goal modeGoal mode 适合长任务。你给 Codex 一个持续目标它会围绕“完成标准”推进并在多步任务中持续检查是否达成。示例/goal 将这个项目从 JavaScript 迁移到 TypeScript。 完成标准 - 所有源码文件迁移完成 - strict 模式下通过类型检查 - 不允许显式 any - 测试仍然通过6.AGENTS.md让 Codex 记住项目规则codex不会同时记住不同对话的内容但你需要它遵守一定的规则。这时你可以写一个AGENTS.md相当于是给编码代理看的项目说明文件。它类似 README但读者是 Codex 这类 agent。它适合放长期稳定的规则而不是一次性任务要求。6.1 应该写什么一个好的AGENTS.md通常包括项目结构如何安装依赖如何启动项目如何运行测试、lint、typecheck代码风格和架构约定PR 或 commit 规范禁止事项完成任务前必须验证什么示例# AGENTS.md ## Project Overview This is a Next.js application using TypeScript, Tailwind CSS, and Vitest. ## Commands - Install: pnpm install - Dev server: pnpm dev - Test: pnpm test - Lint: pnpm lint - Type check: pnpm typecheck ## Engineering Rules - Prefer existing components in src/components. - Do not introduce new dependencies without asking. - Keep API response shapes backward compatible. - Add or update tests for behavior changes. ## Done Criteria Before finishing: - Run the smallest relevant test suite. - Run lint if frontend files changed. - Summarize changed files and verification results.6.2 放在哪里Codex 会按层级加载指令。越靠近当前工作目录的文件优先级越高。常见位置位置作用~/.codex/AGENTS.md个人全局偏好仓库根目录AGENTS.md团队或项目通用规则子目录AGENTS.md某个模块的特殊规则AGENTS.override.md临时覆盖规则示例结构repo/ AGENTS.md packages/ web/ AGENTS.md api/ AGENTS.md如果 Codex 在packages/api/下工作它会读取根目录规则再读取packages/api/AGENTS.md后者更具体。6.3 什么时候更新AGENTS.md当你发现 Codex 老是在同一个地方栽跟头可以把对应规则放进AGENTS.md进行处理。下面是一些适合更新的情况总是跑错测试命令总是误改某个目录总是忽略某类安全要求总是没有遵守 commit 规范review 中反复出现相同反馈你可以直接对 Codex 说请把这次纠正总结成一条简洁规则更新到 AGENTS.md。7. Skills把重复工作做成技能Skill 是 Codex 的可复用工作流。一个 skill 通常是一个目录里面至少有SKILL.md还可以包含脚本、参考文档、模板和资源文件。Skill 适合比AGENTS.md更流程化、更任务化的内容。7.1AGENTS.md和 Skill 的区别类型适合内容AGENTS.md项目长期规则、编码规范、测试命令、约束Skill可复用流程比如发版、审查、安全扫描、生成报告Plugin可安装分发的技能包可能包含 skills、MCP、hooks、资源MCP连接外部工具和实时数据Automation定时或后台执行任务7.2 Skill 的基本结构.agents/ skills/ release-check/ SKILL.md scripts/ check-release.ps1 references/ release-template.mdSKILL.md示例--- name: release-check description: Run the projects release readiness checklist. Use when preparing a release or checking whether a branch is ready to ship. --- 1. Read references/release-template.md. 2. Check package version, changelog, tests, and migration notes. 3. Run the release validation script if available. 4. Return a concise release readiness report with blockers first.7.3 如何调用 Skill显式调用$release-check 检查当前分支是否可以发版。隐式调用帮我检查这个分支是否具备发版条件。如果 skill 的description写得足够清楚Codex 可以自动判断该用它。7.4 Skill 放在哪里作用域位置仓库级.agents/skills个人级$HOME/.agents/skills系统级Codex 内置或管理员提供建议项目专属流程放.agents/skills个人常用流程放$HOME/.agents/skills要分发给团队时打包成 plugin7.5 写 Skill 的建议一个 skill 只做一类事description要写清楚什么时候触发、什么时候不触发优先写步骤说明只有需要确定性工具时才加脚本引用资料放references/自动化或外部工具依赖写清楚如果依赖 MCP在agents/openai.yaml中声明8. Automations让 Codex 定时或后台工作Automations 是 Codex 应用中的自动化能力可以让 Codex 在后台按计划运行任务并把结果放到 Triage / inbox 中。适合每天检查 CI 或 PR 状态定时扫描项目中的 TODO 或 flaky test轮询部署是否完成定期检查依赖升级定期生成代码健康报告每隔几分钟回来继续某个长任务8.1 两类常见自动化类型适合场景Thread automation绑定当前线程保留上下文适合持续跟进Standalone automation每次独立运行适合周期性检查多个项目8.2 Thread automation 示例创建一个线程自动化每 10 分钟检查一次这个部署是否完成。 如果部署成功总结结果并停止提醒。 如果失败说明失败原因。 如果还在进行中只保留简短状态。适合等待 CI等待部署追踪 PR review跟进一个正在进行的排查8.3 Standalone automation 示例创建一个独立自动化每个工作日上午 9 点检查这个项目的测试健康状况。 任务 - 查看最近一次测试结果 - 找出新出现的失败 - 如果没有问题自动归档 - 如果有问题放入 Triage 并给出修复建议8.4 自动化和 Skill 组合自动化适合“什么时候运行”Skill 适合“怎么运行”。示例每天早上 9 点运行 $release-check。 如果发现 blocker把结果放到 Triage。 如果没有发现问题自动归档。8.5 自动化的安全边界自动化是无人值守执行所以权限要保守。注意read-only沙箱下自动化不能改文件、访问网络或操作应用workspace-write可以改工作区文件但不能随意访问工作区外部full access风险最高不建议长期默认使用Git 仓库中优先使用 worktree 隔离自动化改动高频自动化可能产生很多 worktree要定期归档无用 run9. MCP连接外部工具MCP即 Model Context Protocol是 Codex 连接外部工具和上下文的标准方式。可以连接的对象包括GitHubLinearSlackNotionFigmaSentry浏览器内部文档系统数据库或日志系统OpenAI DocsContext7 等开发文档服务9.1 MCP 能提供什么MCP server 通常可以提供Tools让 Codex 执行动作Resources让 Codex 读取资源Prompts提供可复用提示模板9.2 配置方式一般通过~/.codex/config.toml或项目级.codex/config.toml配置。示例[mcp_servers.context7] command npx args [-y, upstash/context7-mcp]HTTP MCP 示例[mcp_servers.figma] url https://mcp.figma.com/mcp bearer_token_env_var FIGMA_OAUTH_TOKENCLI 中也可以使用codex mcpaddcontext7 -- npx-yupstash/context7-mcp codex mcp--help9.3 MCP 和 Skill 的关系推荐组合方式是Skill 定义流程MCP 提供外部能力Automation 定时触发例如Skillreview-pr MCPGitHub MCP Automation每 30 分钟检查 PR 是否有新 review10. Plugins打包和分发能力Plugin 是可安装的扩展包通常可以包含一个或多个 skillsMCP server 配置hooks应用映射图标、资源、展示信息marketplace 元数据如果你只是给当前项目写一个流程用 skill 就够了。如果你想分发给团队、跨项目安装、绑定 MCP 或 UI 元数据就适合做 plugin。一个最简单的plugin 结构如下my-plugin/ .codex-plugin/ plugin.json skills/ hello/ SKILL.mdplugin.json示例{name:my-plugin,version:1.0.0,description:Reusable workflows for this team,skills:./skills/}11. Subagents并行代理Subagents 是让 Codex 同时启动多个专门代理去处理不同子任务可以提高任务效率。适合大型代码审查多方向排查安全、测试、性能分别分析大文档分块总结并行探索多个模块示例请使用 3 个 subagents 并行 review 当前分支 1. 一个关注安全风险 2. 一个关注测试缺口 3. 一个关注可维护性 等待三个代理全部完成后按严重程度汇总结果附文件引用。注意读多写少的任务更适合 subagents多个代理同时改代码容易冲突subagents 会消耗更多 token 和时间主线程应负责整合决策不要让中间日志淹没上下文12. Rules、Sandbox 和权限Codex 可以运行命令也可能修改文件。权限模型决定它能做什么。常见沙箱模式模式行为read-only只能读不能写文件或执行需要写入的操作workspace-write可以写当前工作区不能随意写外部目录full access权限最大风险也最大常见审批策略策略行为prompt / require approval高风险或越权命令需要你批准on-failure先在沙箱跑失败后请求提升权限never自动化常用但要非常谨慎Rules 可以控制哪些命令允许、提示或禁止。示例思路允许 gh pr view 提示 npm install 禁止 rm -rf建议默认使用workspace-write对网络、安装依赖、写工作区外文件保持审批不要让无人值守自动化长期使用 full access对删除、reset、清理类命令保持人工确认13. 与 Claude / Claude Code 联动官方 Codex 手册没有把 Claude 作为 Codex 内置的一键集成来描述。因此实际联动通常走工程协作模式而不是期待两个产品天然共享上下文。常见可落地方式如下。13.1 通过 Git 分工这是最稳的方式。推荐流程Claude 负责方案设计、需求澄清、文案或大方向分析Codex 负责在仓库中落地修改、跑测试、修复失败双方通过 Git diff、commit、PR 描述交接示例Claude 产出设计方案 DESIGN.md Codex 根据 DESIGN.md 实现代码并运行测试 Claude 再阅读 diff 给出 review Codex 修复 review 反馈13.2 通过 Markdown 交接上下文创建一个共享交接文件例如docs/agent-handoff.md内容可以包括# Agent Handoff ## Goal ## Current State ## Decisions Made ## Files Touched ## Open Questions ## Verification ## Next Agent Should Do用法请阅读 docs/agent-handoff.md接着完成 Next Agent Should Do 中的任务。 完成后更新这个文件。这种方式适合 Codex、Claude Code、Cursor、人工开发者之间协作。13.3 通过 MCP 或外部系统共享如果 Claude 和 Codex 都能访问同一个外部系统可以把协作状态放在那里GitHub issue / PRLinear ticketNotion 文档Slack threadGoogle Docs内部任务系统Codex 侧通常通过 MCP、插件或连接器读取这些系统。Claude 侧如果也有对应连接能力就可以围绕同一个任务源协作。推荐结构Linear issue需求和验收标准 GitHub PR代码 diff 和 review Notion/Docs设计说明 Codex实现、测试、修复 Claude需求推敲、方案比较、二次审查13.4 Claude Code 与 Codex CLI 分工如果本机同时使用 Claude Code 和 Codex CLI建议避免两个 agent 同时改同一批文件。推荐模式Claude Code: - 生成设计方案 - 找风险点 - 做第二视角 review Codex: - 实际编辑文件 - 运行命令 - 启动浏览器验证 - 整理最终 diff如果确实要同时工作使用不同 Git 分支或使用不同 worktree或明确文件边界每次交接前先提交或保存 diff13.5 通过命令行桥接如果某个 Claude 工具提供 CLI你可以让 Codex 在受控情况下调用它。但要注意这可能涉及外部网络和 API keyCodex 不应读取或暴露密钥输出应保存为文件或摘要需要人工批准安装、登录和高权限命令建议把桥接做成脚本或 skill而不是每次临时拼命令。示例 skill 思路--- name: claude-review-handoff description: Prepare a review handoff package for Claude or consume Claude review notes and apply fixes. --- 1. Generate a concise diff summary. 2. Write docs/claude-review-request.md. 3. If docs/claude-review-notes.md exists, read it and classify feedback. 4. Apply only concrete, testable fixes. 5. Run relevant verification commands.13.6 不建议的联动方式两个 agent 同时在同一目录随意改代码把 API key、cookie、token 写入交接文件让一个 agent 无限制执行另一个 agent 生成的 shell 命令没有 diff / commit / handoff 文档就来回切换让双方都“自动修复全部问题”最后难以追踪责任边界14. 用 CC Switch 管理多个工具的配置如果你只用 Codex这一节可以跳过。但只要你同时装了 Codex、Claude Code、Gemini CLI 里的两个以上迟早会碰到一件烦人的事想换个 API 供应商比如从官方 API 换成中转、DeepSeek、阿里百炼得挨个去改配置文件。而且每个工具的格式还不一样——Claude 用 JSONCodex 用 TOML 加 auth.jsonGemini 又是另一套。改错一个字符整个工具就起不来了。CC Switch 就是专门解决这个的。它是个跨平台桌面小工具把各个 CLI 的供应商配置集中管起来切换的时候一键写入对应的配置文件不用你手动碰那些 JSON 和 TOML。仓库在github.com/farion1231/cc-switch官网是 ccswitch.io。14.1 它到底帮你做了什么说白了就三件事把配置存在一个地方、切换时帮你写对文件、写的时候不会写坏。第三点比听起来重要。CC Switch 用 SQLite 存所有供应商信息每次写配置文件都走先写临时文件再改名的原子操作所以哪怕切换到一半出问题你原来的配置也不会被写成半截的坏文件。这对经常手滑改坏config.toml的人来说是真的省心。现在它支持的工具比一开始多了不少除了 Claude Code、Codex、Gemini CLI还覆盖了 Claude Desktop、OpenCode 等好几个每个都带自己的一套供应商预设。14.2 装起来macOS 用 Homebrew 最省事brew tap farion1231/ccswitch brewinstall--caskcc-switchWindows 下载.msi装就行Linux 有.deb/.rpm/.AppImageArch 用户可以paru -S cc-switch-bin。第一次打开时它会自己扫一遍你机器上装了哪些 CLI把现有配置尽量导入进来然后在系统托盘挂一个图标。14.3 日常用法主界面顶上是一排工具图标点哪个就是在管哪个工具的配置。加供应商点右上角的可以从内置预设里选官方 Anthropic、DeepSeek、阿里百炼这些都有也可以自己手填。填好之后在列表里点一下想用的那个再点「启用」它就把配置写进对应工具的实际配置文件了。具体写到哪Claude 是settings.jsonCodex 是auth.json加config.toml。如果你切换很频繁不用每次都开主界面——直接从系统托盘的菜单里点就能换。14.4 生效时间这个不同工具不一样得记一下工具切换后Claude Code支持热切换即时生效不用重启Codex需要重启终端才生效Gemini CLI每次请求自动重读配置不用管所以你在 CC Switch 里点了「启用」Codex 却还在用旧供应商多半不是没切成功而是终端没重开。14.5 几个顺手的功能真正装了之后你可能会用到这几个MCP 统一管理在 CC Switch 里加一个 MCP Server能一键同步到 Claude Code、Codex、Gemini CLI 等不用在每个工具里各配一遍。自动故障转移内置一个本地代理配了多个供应商的话一个挂了会自动切到下一个带断路器逻辑。跑长任务不容易被单个供应商拖死。自动备份数据库在~/.cc-switch/cc-switch.db会自动留最近 10 个版本配置切乱了还能回退。14.6 和前面那套联动怎么搭CC Switch 管的是配置层前面第 13 章讲的 Git 分支、handoff 文档管的是协作层两者不冲突配一块用挺舒服Codex 和 Claude Code 各自的供应商、API key 交给 CC Switch 统一切换具体谁改哪些文件、怎么交接还是走分支和 handoff。这样你既不用记一堆配置文件路径也不会让两个 agent 在同一批文件上打架。一个小提醒官方 README 里说过这工具还要大改一轮所以你装的版本界面可能和网上的截图对不上以自己装的实际版本为准就行。15. 推荐个人工作流15.1 新项目初始化让 Codex 阅读项目结构生成或更新AGENTS.md明确测试、lint、构建命令配置常用 MCP把重复流程做成 skill对稳定流程设置 automation提示词请阅读当前项目生成一个简洁实用的 AGENTS.md。 重点包括 - 项目结构 - 安装、启动、测试、lint、构建命令 - 代码风格 - 完成任务前的验证要求 不要写空泛规则。15.2 日常开发实现 X 功能。 参考 docs/spec.md。 约束 - 不要改数据库 schema - 保持现有 API 兼容 - 修改后运行相关测试15.3 提交前请 review 当前 diff。 如果发现问题先列出来不要直接改。 重点看 bug、测试缺口、边界条件和不必要的复杂度。15.4 PR 后读取 PR review 反馈按优先级分类。 先处理 P0/P1 问题。 每修一类问题后运行相关测试。15.5 长期维护可以设置自动化每天检查失败测试每周检查依赖更新每周总结技术债每次 PR 自动做 focused review定期检查AGENTS.md是否需要更新16. 常见问题16.1 Codex 没有按项目规则做检查AGENTS.md是否在正确目录当前工作目录是否正确是否有更近的AGENTS.override.md文件是否过长导致部分指令未加载规则是否过于抽象建议让 Codex 自查请列出你当前加载到了哪些项目指令文件并总结其中和本任务相关的规则。16.2 Skill 没触发检查skill 是否在.agents/skills或$HOME/.agents/skillsSKILL.md是否有 frontmattername是否唯一且好记description是否写清楚触发条件是否需要重启 Codex可以显式调用$skill-name 执行这个任务16.3 自动化没跑检查Codex app 是否在运行项目路径是否还存在沙箱权限是否允许该任务是否被组织策略限制是否使用了 worktree结果是否在 automation run 中prompt 是否能在普通线程中先跑通16.4 Codex 和 Claude 如何避免互相覆盖最佳实践使用 Git 分支或 worktree 隔离明确每个 agent 负责的文件范围用 handoff 文档交接每轮交接前查看 diff一个 agent 实现另一个 agent review19. 总结给 Codex 明确目标、上下文、约束和完成标准对复杂任务先 plan再 implement把长期规则写进AGENTS.md把重复流程做成 skill用 MCP 连接外部系统用 automation 处理稳定的周期性任务用 worktree 隔离后台任务或并行任务用 subagents 做并行分析谨慎并行写代码与 Claude 联动时通过 Git、handoff 文档、PR 和外部任务系统交接不要让多个 agent 无边界地同时修改同一批文件始终要求验证测试、lint、typecheck、浏览器检查或人工可审查 diff20. 资料来源本文参考了当前 Codex 本地手册缓存中的官方内容主要对应以下主题Codex QuickstartExecution Model and WorkflowsPromptingGoal modeAutomationsAgent SkillsCustom instructions withAGENTS.mdModel Context ProtocolPluginsSubagentsRules, sandboxing, permissions本地手册缓存路径C:\Users\Hilbe\AppData\Local\Temp\openai-docs-cache\codex-manual.md文中的三张界面截图来自 OpenAI 官方 Codex 入门页面并已保存到当前文件夹的assets/目录方便离线查看 Markdown。第 14 章关于 CC Switch 的内容主要参考了以下来源CC Switch 官方仓库CC Switch 中文说明CC Switch 官网