本文按“入门基础 - 基础使用 - 深度技巧 - 邪修提效 - 推荐配置”的顺序整理一套适合国内开发者上手的 Codex 使用方法。一、Codex 到底是什么Codex 不是传统意义上的代码补全插件。更准确地说它是一个面向软件开发的 AI 编码代理可以读项目、理解上下文、修改文件、运行命令、查看报错、修复问题并把结果交给你审查。可以把它理解成三层能力理解代码库不只看当前文件而是围绕任务去检索目录、阅读关键文件、分析依赖关系。执行开发动作能写代码、改配置、运行测试、生成文档、做代码审查。沉淀工作流通过AGENTS.md、config.toml、MCP、hooks、skills、自动化任务把你的个人习惯和团队规范变成可复用能力。从入口看Codex 主要有几种使用方式Codex CLI适合终端党、脚本化任务、CI、批量处理和本地仓库工作。IDE 扩展适合边看编辑器边让 Codex 读当前文件、改代码、解释报错。ChatGPT 桌面端 / Codex App适合长任务、跨文件协作、可视化审查、工作树、多代理并行。Codex Cloud适合把任务丢到隔离云环境中并行处理再把结果应用回本地。新手先从 CLI 或 IDE 扩展开始最直接如果你经常做复杂重构、文章生成、资料整理、自动化发布桌面端和任务自动化会更顺手。二、入门基础先跑通第一条任务官方当前推荐的 macOS / Linux 安装方式是独立安装脚本curl-fsSLhttps://chatgpt.com/codex/install.sh|sh安装后进入一个项目目录cdpath/to/your-project codex第一次运行会让你登录。一般可以选择 ChatGPT 登录如果是自动化或 CI 场景也可以按官方说明使用 API key但不要把 key 写死在仓库、脚本日志或公开配置里。入门阶段建议先让 Codex 做低风险任务阅读这个项目告诉我主要目录结构、启动方式、测试方式以及你建议我先看的 5 个文件。然后再做一个小修改修复 README 里的过期启动命令并说明你改了哪里。最后让它跑验证运行最相关的检查确认 README 中的命令和 package.json 里的脚本一致。这三个任务能帮助你快速理解 Codex 的基本循环读上下文、改文件、运行命令、汇报结果。三、基础使用提示词要说清四件事很多人用 Codex 的第一个误区是把它当聊天机器人只说“帮我优化一下”。更稳定的写法是一次讲清楚四件事目标你到底要它完成什么。上下文哪些文件、目录、报错、接口文档、截图或日志重要。约束不要动哪些文件、保持哪些兼容性、遵循哪些代码风格。验收标准什么结果算完成例如测试通过、页面无报错、接口返回结构不变。一个更可执行的例子目标修复登录页手机号校验错误的问题。 上下文先看 src/pages/login、src/utils/validators.ts 和最近一次失败日志。 约束不要重构登录流程不要引入新依赖保持现有 UI 文案。 完成标准新增或更新一个单元测试运行相关测试并说明根因。CLI 里常用的命令和快捷入口codex codex解释这个项目如何启动codex--cd./apps/web检查这个页面的构建错误codexexec总结最近 10 次提交生成 release notescodex review codex mcp list codex resume--last常用斜杠命令/init生成AGENTS.md初稿。/status查看当前模型、权限、工作目录和上下文状态。/permissions切换读写和审批权限。/model切换模型和推理强度。/plan进入先规划再执行的模式。/diff看本轮改动。/review让 Codex 审查当前工作树。/compact长对话后压缩上下文。/mcp查看已连接的 MCP 工具。四、深度使用技巧把 Codex 从“能用”调到“好用”1. 用 AGENTS.md 固化你的开发习惯AGENTS.md是 Codex 的长期说明书。你可以在全局、仓库、子目录放不同层级的规则Codex 启动时会自动读取并且越靠近当前目录的规则优先级越高。适合写进AGENTS.md的内容项目结构和关键目录。本地启动、测试、构建命令。代码风格、提交规范、PR 要求。哪些文件不能随便改。修改完成后必须跑哪些验证。示例# AGENTS.md ## 项目约定 - 修改前先阅读相关测试和调用方。 - 前端改动后运行 pnpm lint 和相关页面测试。 - 后端接口返回字段必须保持兼容新增字段需要写明默认值。 - 不要改动 .env*、生产部署脚本和数据库迁移文件除非任务明确要求。 - 完成后给出修改摘要、验证命令、剩余风险。当 Codex 连续两次犯同类错误不要每次在提示词里纠正直接更新AGENTS.md。2. 用 config.toml 管住模型、权限和网络Codex 的用户级配置通常放在~/.codex/config.toml项目级配置可以放在.codex/config.toml建议新手先保持相对安全的权限model gpt-5.6 model_reasoning_effort medium approval_policy on-request sandbox_mode workspace-write web_search cached [features] hooks true multi_agent true这套配置的含义很简单允许 Codex 在工作区内读写和运行必要命令但涉及越界写入、网络访问等高风险动作时要停下来确认。3. 用 MCP 接外部上下文MCP 可以让 Codex 接入外部工具和资料源比如最新开发文档、浏览器、Figma、GitHub、Sentry、内部系统等。例如接入 Context7 文档服务codex mcpaddcontext7 -- npx-yupstash/context7-mcp适合接 MCP 的场景文档经常变不想手动复制。需要读 issue、PR、监控、日志、设计稿。希望 Codex 调工具而不是只靠你粘贴上下文。原则是少而准。不要一上来把所有系统都接给 Codex先接一两个能明显减少复制粘贴的工具。4. 用 hooks 做防呆hooks 是 Codex 的生命周期钩子可以在工具调用前后、权限申请时、会话开始或结束时运行脚本。它适合做工程团队里的防呆和审计。常见用法PreToolUse阻止危险命令比如误删目录、读取敏感文件。UserPromptSubmit检查用户是否粘贴了 API key、token、生产密码。PostToolUse命令跑完后自动扫描输出中的错误或敏感信息。Stop任务结束前自动要求补充验证摘要。示例思路{hooks:{PreToolUse:[{matcher:Bash,hooks:[{type:command,command:python3 .codex/hooks/block_dangerous_commands.py,statusMessage:Checking command safety}]}]}}真正进入团队使用后hooks 往往比“口头提醒 Codex 小心点”更可靠。5. 用 codex exec 批量处理重复任务codex exec适合不需要打开交互界面的场景比如生成 changelog、总结日志、批量审查、CI 失败分析。codexexec总结这个仓库最近 20 次提交按功能、修复、风险分类配合管道使用npmtest21|codexexec总结失败原因并给出最小修复建议需要机器可读输出时codexexec--json审查当前工作树输出主要风险自动化场景一定要记住权限越自动环境越要隔离。不要在本机主力目录里随手开danger-full-access。五、邪修使用方法能提效但不要越界这里的“邪修”不是绕过限制而是一些实战里很省时间的非传统用法。1. 先让 Codex 写验收清单不要一上来让它改代码先让它定义完成标准先不要改代码。请阅读相关文件列出你认为这个任务的验收清单、风险点和需要确认的假设。这一步能显著减少“它改了很多但不是你想要的”。2. 让它先写最小复现调 bug 时先问先写一个最小复现或失败测试证明问题存在。测试失败后再开始修复。这样可以避免 Codex 直接凭感觉改。3. 双模型接力简单批处理、格式转换、摘要抽取可以用更快、更便宜的模型复杂重构、架构判断、深度排错再切到更强的模型和更高推理强度。官方当前把 GPT-5.6 系列分成 Sol、Terra、LunaSol 更适合复杂高价值任务Terra 适合日常全能任务Luna 适合清晰可重复任务。4. 一人多工位worktree / fork / side chat复杂任务不要让一个长对话无限膨胀。可以把“调研”“实现”“测试”“审查”拆开分别放到不同任务、side chat、worktree 或 subagent 里再由主线汇总。5. 把日志直接喂给 Codex不要复制一整屏报错到聊天框可以直接走管道tail-n200app.log|codexexec找出最可能的根因列出 3 个验证步骤这类玩法非常适合线上问题复盘、CI 失败摘要、接口压测报告整理。6. 让 Codex 审自己的改动改完后追加一句现在站在代码审查者角度审查你刚才的改动只列风险和可能的回归不要夸自己。再配合/diff和/review能把很多低级问题挡在提交前。7. 建一个“任务模板库”把常用提示词沉淀成文件例如.codex/prompts/fix-bug.md .codex/prompts/review-pr.md .codex/prompts/write-doc.md .codex/prompts/refactor-plan.md每次任务只改目标和上下文不重新发明提示词。8. 明确禁止的“邪修”下面这些不要做不要导出、分享、保存 Cookie、验证码、auth.json、API key。不要把私有代码交给来路不明的中转服务或不可信 MCP。不要在主力电脑、生产目录、真实密钥环境里开--yolo。不要让 Codex 自动改数据库、删文件、发版除非有隔离环境和明确审批。不要盲信国内镜像脚本至少先看脚本内容和来源。真正高效的 Codex 用法核心是“可回滚、可验证、可审查”不是“完全放飞”。六、推荐配置按场景准备三套1. 日常开发配置model gpt-5.6 model_reasoning_effort medium approval_policy on-request sandbox_mode workspace-write web_search cached [features] hooks true multi_agent true适合日常改 bug、写功能、补测试、改文档。2. 只读审查配置保存为~/.codex/readonly.config.tomlapproval_policy never sandbox_mode read-only model_reasoning_effort medium使用codex--profilereadonly审查这个项目的风险点不要修改文件适合看陌生项目、读私有仓库、做安全初筛。3. 深度重构配置保存为~/.codex/deep.config.tomlmodel gpt-5.6-sol model_reasoning_effort high approval_policy on-request sandbox_mode workspace-write web_search cached使用codex--profiledeep适合复杂排错、跨模块重构、架构分析、发布前审查。4. 批处理配置保存为~/.codex/batch.config.tomlmodel gpt-5.6-luna model_reasoning_effort low approval_policy never sandbox_mode read-only使用codexexec--profilebatch把最近提交总结成 10 条变更日志适合摘要、分类、格式转换、日志解读这类清晰任务。七、一套实际工作流如果你刚开始用 Codex可以按这个流程来进仓库前先确保 Git 状态干净。运行codex先让它解释项目结构和测试方式。用/init生成AGENTS.md补上真实项目规则。做复杂任务前先/plan让它列执行计划。让 Codex 实现最小改动不要顺手大重构。要求它运行相关测试、lint、类型检查。用/diff看改动再用/review找风险。人工确认后再提交。这个流程慢一点但更稳。等你熟悉项目和 Codex 行为后再逐步把重复步骤变成脚本、hooks、skills 或定时任务。结语Codex 最近在国内开发者圈火起来不只是因为它“能写代码”而是因为它更接近一个能在真实工程环境里干活的代理。入门看 CLI进阶看AGENTS.md和config.toml深度使用看 MCP、hooks、codex exec、review 和多代理协作。一句话总结把 Codex 当新人同事用给上下文、给边界、给验收把 Codex 当自动化系统用给配置、给工具、给审计。这样它才会从“偶尔惊艳”变成“稳定提效”。参考来源OpenAI / ChatGPT LearnCodex CLI 文档https://learn.chatgpt.com/docs/codex/cliOpenAI / ChatGPT Learn配置基础https://learn.chatgpt.com/docs/config-file/config-basicOpenAI / ChatGPT LearnAGENTS.md 自定义说明https://learn.chatgpt.com/docs/agent-configuration/agents-mdOpenAI / ChatGPT LearnMCP 文档https://learn.chatgpt.com/docs/extend/mcpOpenAI / ChatGPT LearnHooks 文档https://learn.chatgpt.com/docs/hooksOpenAI / ChatGPT Learn非交互模式https://learn.chatgpt.com/docs/non-interactive-modeCSDNOpenAI Codex CLI 完全指南https://blog.csdn.net/weixin_43571227/article/details/161613409CSDNCodex CLI 教程安装指南https://blog.csdn.net/qq_20236937/article/details/159642302CSDN快速上手 Codex CLIhttps://blog.csdn.net/tenifs/article/details/161629436掘金Codex CLI 和 Codex 桌面端完整教程https://juejin.cn/post/7648903840466780170掘金Codex CLI 深度指南https://juejin.cn/post/7634760691857539082博客园OpenAI Codex CLI 完全指南https://www.cnblogs.com/ljbguanli/p/19439518博客园CodeX CLI 实用小技巧https://www.cnblogs.com/javastack/p/19113665
本文按“入门基础 - 基础使用 - 深度技巧 - 邪修提效 - 推荐配置”的顺序整理一套适合国内开发者上手的 Codex 使用方法。一、Codex 到底是什么Codex 不是传统意义上的代码补全插件。更准确地说它是一个面向软件开发的 AI 编码代理可以读项目、理解上下文、修改文件、运行命令、查看报错、修复问题并把结果交给你审查。可以把它理解成三层能力理解代码库不只看当前文件而是围绕任务去检索目录、阅读关键文件、分析依赖关系。执行开发动作能写代码、改配置、运行测试、生成文档、做代码审查。沉淀工作流通过AGENTS.md、config.toml、MCP、hooks、skills、自动化任务把你的个人习惯和团队规范变成可复用能力。从入口看Codex 主要有几种使用方式Codex CLI适合终端党、脚本化任务、CI、批量处理和本地仓库工作。IDE 扩展适合边看编辑器边让 Codex 读当前文件、改代码、解释报错。ChatGPT 桌面端 / Codex App适合长任务、跨文件协作、可视化审查、工作树、多代理并行。Codex Cloud适合把任务丢到隔离云环境中并行处理再把结果应用回本地。新手先从 CLI 或 IDE 扩展开始最直接如果你经常做复杂重构、文章生成、资料整理、自动化发布桌面端和任务自动化会更顺手。二、入门基础先跑通第一条任务官方当前推荐的 macOS / Linux 安装方式是独立安装脚本curl-fsSLhttps://chatgpt.com/codex/install.sh|sh安装后进入一个项目目录cdpath/to/your-project codex第一次运行会让你登录。一般可以选择 ChatGPT 登录如果是自动化或 CI 场景也可以按官方说明使用 API key但不要把 key 写死在仓库、脚本日志或公开配置里。入门阶段建议先让 Codex 做低风险任务阅读这个项目告诉我主要目录结构、启动方式、测试方式以及你建议我先看的 5 个文件。然后再做一个小修改修复 README 里的过期启动命令并说明你改了哪里。最后让它跑验证运行最相关的检查确认 README 中的命令和 package.json 里的脚本一致。这三个任务能帮助你快速理解 Codex 的基本循环读上下文、改文件、运行命令、汇报结果。三、基础使用提示词要说清四件事很多人用 Codex 的第一个误区是把它当聊天机器人只说“帮我优化一下”。更稳定的写法是一次讲清楚四件事目标你到底要它完成什么。上下文哪些文件、目录、报错、接口文档、截图或日志重要。约束不要动哪些文件、保持哪些兼容性、遵循哪些代码风格。验收标准什么结果算完成例如测试通过、页面无报错、接口返回结构不变。一个更可执行的例子目标修复登录页手机号校验错误的问题。 上下文先看 src/pages/login、src/utils/validators.ts 和最近一次失败日志。 约束不要重构登录流程不要引入新依赖保持现有 UI 文案。 完成标准新增或更新一个单元测试运行相关测试并说明根因。CLI 里常用的命令和快捷入口codex codex解释这个项目如何启动codex--cd./apps/web检查这个页面的构建错误codexexec总结最近 10 次提交生成 release notescodex review codex mcp list codex resume--last常用斜杠命令/init生成AGENTS.md初稿。/status查看当前模型、权限、工作目录和上下文状态。/permissions切换读写和审批权限。/model切换模型和推理强度。/plan进入先规划再执行的模式。/diff看本轮改动。/review让 Codex 审查当前工作树。/compact长对话后压缩上下文。/mcp查看已连接的 MCP 工具。四、深度使用技巧把 Codex 从“能用”调到“好用”1. 用 AGENTS.md 固化你的开发习惯AGENTS.md是 Codex 的长期说明书。你可以在全局、仓库、子目录放不同层级的规则Codex 启动时会自动读取并且越靠近当前目录的规则优先级越高。适合写进AGENTS.md的内容项目结构和关键目录。本地启动、测试、构建命令。代码风格、提交规范、PR 要求。哪些文件不能随便改。修改完成后必须跑哪些验证。示例# AGENTS.md ## 项目约定 - 修改前先阅读相关测试和调用方。 - 前端改动后运行 pnpm lint 和相关页面测试。 - 后端接口返回字段必须保持兼容新增字段需要写明默认值。 - 不要改动 .env*、生产部署脚本和数据库迁移文件除非任务明确要求。 - 完成后给出修改摘要、验证命令、剩余风险。当 Codex 连续两次犯同类错误不要每次在提示词里纠正直接更新AGENTS.md。2. 用 config.toml 管住模型、权限和网络Codex 的用户级配置通常放在~/.codex/config.toml项目级配置可以放在.codex/config.toml建议新手先保持相对安全的权限model gpt-5.6 model_reasoning_effort medium approval_policy on-request sandbox_mode workspace-write web_search cached [features] hooks true multi_agent true这套配置的含义很简单允许 Codex 在工作区内读写和运行必要命令但涉及越界写入、网络访问等高风险动作时要停下来确认。3. 用 MCP 接外部上下文MCP 可以让 Codex 接入外部工具和资料源比如最新开发文档、浏览器、Figma、GitHub、Sentry、内部系统等。例如接入 Context7 文档服务codex mcpaddcontext7 -- npx-yupstash/context7-mcp适合接 MCP 的场景文档经常变不想手动复制。需要读 issue、PR、监控、日志、设计稿。希望 Codex 调工具而不是只靠你粘贴上下文。原则是少而准。不要一上来把所有系统都接给 Codex先接一两个能明显减少复制粘贴的工具。4. 用 hooks 做防呆hooks 是 Codex 的生命周期钩子可以在工具调用前后、权限申请时、会话开始或结束时运行脚本。它适合做工程团队里的防呆和审计。常见用法PreToolUse阻止危险命令比如误删目录、读取敏感文件。UserPromptSubmit检查用户是否粘贴了 API key、token、生产密码。PostToolUse命令跑完后自动扫描输出中的错误或敏感信息。Stop任务结束前自动要求补充验证摘要。示例思路{hooks:{PreToolUse:[{matcher:Bash,hooks:[{type:command,command:python3 .codex/hooks/block_dangerous_commands.py,statusMessage:Checking command safety}]}]}}真正进入团队使用后hooks 往往比“口头提醒 Codex 小心点”更可靠。5. 用 codex exec 批量处理重复任务codex exec适合不需要打开交互界面的场景比如生成 changelog、总结日志、批量审查、CI 失败分析。codexexec总结这个仓库最近 20 次提交按功能、修复、风险分类配合管道使用npmtest21|codexexec总结失败原因并给出最小修复建议需要机器可读输出时codexexec--json审查当前工作树输出主要风险自动化场景一定要记住权限越自动环境越要隔离。不要在本机主力目录里随手开danger-full-access。五、邪修使用方法能提效但不要越界这里的“邪修”不是绕过限制而是一些实战里很省时间的非传统用法。1. 先让 Codex 写验收清单不要一上来让它改代码先让它定义完成标准先不要改代码。请阅读相关文件列出你认为这个任务的验收清单、风险点和需要确认的假设。这一步能显著减少“它改了很多但不是你想要的”。2. 让它先写最小复现调 bug 时先问先写一个最小复现或失败测试证明问题存在。测试失败后再开始修复。这样可以避免 Codex 直接凭感觉改。3. 双模型接力简单批处理、格式转换、摘要抽取可以用更快、更便宜的模型复杂重构、架构判断、深度排错再切到更强的模型和更高推理强度。官方当前把 GPT-5.6 系列分成 Sol、Terra、LunaSol 更适合复杂高价值任务Terra 适合日常全能任务Luna 适合清晰可重复任务。4. 一人多工位worktree / fork / side chat复杂任务不要让一个长对话无限膨胀。可以把“调研”“实现”“测试”“审查”拆开分别放到不同任务、side chat、worktree 或 subagent 里再由主线汇总。5. 把日志直接喂给 Codex不要复制一整屏报错到聊天框可以直接走管道tail-n200app.log|codexexec找出最可能的根因列出 3 个验证步骤这类玩法非常适合线上问题复盘、CI 失败摘要、接口压测报告整理。6. 让 Codex 审自己的改动改完后追加一句现在站在代码审查者角度审查你刚才的改动只列风险和可能的回归不要夸自己。再配合/diff和/review能把很多低级问题挡在提交前。7. 建一个“任务模板库”把常用提示词沉淀成文件例如.codex/prompts/fix-bug.md .codex/prompts/review-pr.md .codex/prompts/write-doc.md .codex/prompts/refactor-plan.md每次任务只改目标和上下文不重新发明提示词。8. 明确禁止的“邪修”下面这些不要做不要导出、分享、保存 Cookie、验证码、auth.json、API key。不要把私有代码交给来路不明的中转服务或不可信 MCP。不要在主力电脑、生产目录、真实密钥环境里开--yolo。不要让 Codex 自动改数据库、删文件、发版除非有隔离环境和明确审批。不要盲信国内镜像脚本至少先看脚本内容和来源。真正高效的 Codex 用法核心是“可回滚、可验证、可审查”不是“完全放飞”。六、推荐配置按场景准备三套1. 日常开发配置model gpt-5.6 model_reasoning_effort medium approval_policy on-request sandbox_mode workspace-write web_search cached [features] hooks true multi_agent true适合日常改 bug、写功能、补测试、改文档。2. 只读审查配置保存为~/.codex/readonly.config.tomlapproval_policy never sandbox_mode read-only model_reasoning_effort medium使用codex--profilereadonly审查这个项目的风险点不要修改文件适合看陌生项目、读私有仓库、做安全初筛。3. 深度重构配置保存为~/.codex/deep.config.tomlmodel gpt-5.6-sol model_reasoning_effort high approval_policy on-request sandbox_mode workspace-write web_search cached使用codex--profiledeep适合复杂排错、跨模块重构、架构分析、发布前审查。4. 批处理配置保存为~/.codex/batch.config.tomlmodel gpt-5.6-luna model_reasoning_effort low approval_policy never sandbox_mode read-only使用codexexec--profilebatch把最近提交总结成 10 条变更日志适合摘要、分类、格式转换、日志解读这类清晰任务。七、一套实际工作流如果你刚开始用 Codex可以按这个流程来进仓库前先确保 Git 状态干净。运行codex先让它解释项目结构和测试方式。用/init生成AGENTS.md补上真实项目规则。做复杂任务前先/plan让它列执行计划。让 Codex 实现最小改动不要顺手大重构。要求它运行相关测试、lint、类型检查。用/diff看改动再用/review找风险。人工确认后再提交。这个流程慢一点但更稳。等你熟悉项目和 Codex 行为后再逐步把重复步骤变成脚本、hooks、skills 或定时任务。结语Codex 最近在国内开发者圈火起来不只是因为它“能写代码”而是因为它更接近一个能在真实工程环境里干活的代理。入门看 CLI进阶看AGENTS.md和config.toml深度使用看 MCP、hooks、codex exec、review 和多代理协作。一句话总结把 Codex 当新人同事用给上下文、给边界、给验收把 Codex 当自动化系统用给配置、给工具、给审计。这样它才会从“偶尔惊艳”变成“稳定提效”。参考来源OpenAI / ChatGPT LearnCodex CLI 文档https://learn.chatgpt.com/docs/codex/cliOpenAI / ChatGPT Learn配置基础https://learn.chatgpt.com/docs/config-file/config-basicOpenAI / ChatGPT LearnAGENTS.md 自定义说明https://learn.chatgpt.com/docs/agent-configuration/agents-mdOpenAI / ChatGPT LearnMCP 文档https://learn.chatgpt.com/docs/extend/mcpOpenAI / ChatGPT LearnHooks 文档https://learn.chatgpt.com/docs/hooksOpenAI / ChatGPT Learn非交互模式https://learn.chatgpt.com/docs/non-interactive-modeCSDNOpenAI Codex CLI 完全指南https://blog.csdn.net/weixin_43571227/article/details/161613409CSDNCodex CLI 教程安装指南https://blog.csdn.net/qq_20236937/article/details/159642302CSDN快速上手 Codex CLIhttps://blog.csdn.net/tenifs/article/details/161629436掘金Codex CLI 和 Codex 桌面端完整教程https://juejin.cn/post/7648903840466780170掘金Codex CLI 深度指南https://juejin.cn/post/7634760691857539082博客园OpenAI Codex CLI 完全指南https://www.cnblogs.com/ljbguanli/p/19439518博客园CodeX CLI 实用小技巧https://www.cnblogs.com/javastack/p/19113665
