Codex从入门到精通：AI编程Agent完全指南

AIPROGRAMMINGAGENT·COMPLETEGUIDECodex从入门到精通AI编程Agent完全指南从界面认知到工作流搭建·从CLI命令到扩展生态2026·技术教程系列目录CONTENTS·九大章节01认识CodexAgent的本质与四步工作循环02App界面详解左中右三栏布局与核心面板03工作区与运行模式Local/Worktree/Cloud选择策略04Plan与权限计划先行与安全边界控制05核心工具终端、浏览器、ComputerUse与Memory06CLI深度使用安装配置、常用命令与快捷键07扩展生态Skills/Plugins/MCP三者关系08自动化与长期任务Automations定时任务与/goal目标09实战进阶四阶段学习路径与最佳实践01认识CodexAgent的本质、工作循环与五大入口Codex是一个能实际操作的Agent普通聊天工具主要给出文字回答，Codex除了回答，还能读取文件、修改代码和文档、运行命令、查看Git改动、打开网页、操作应用，并调用已经接入的外部工具。读取与理解读取项目文件、理解代码结构、分析文档内容、查看终端输出和网页信息修改与执行编辑代码和文档、运行Shell命令、执行测试、安装依赖、操作Git验证与交付查看Diff变更、运行检查验证、创建PullRequest、提交代码到仓库核心原则：交给Codex的最好是一件有材料、有边界、有结果的工作Codex说"完成了"，只能说明它结束了当前执行，不能自动证明文件正确、页面能用或者测试已经通过。验证是使用者的责任，Diff、终端、测试和页面才是判断结果的依据。核心工作循环：四步闭环Codex的基本循环可以写成四步，每一步都有明确的角色和产出STEP1Prompt你提出任务，明确目标、边界和期望结果STEP2Plan它准备怎么做，列出步骤和需要查看的文件STEP3Execute实际读写文件、运行命令、调用工具完成任务STEP4Verify检查结果，通过Diff、测试和页面确认正确性最重要的是最后一步Verify。Codex说"完成了"只代表执行结束，不代表结果正确。你需要用Diff、终端、测试和页面来验证，而不是只看一句"已经完成"。五大入口：选择适合你的使用方式小白没有必要同时学习五种入口，先用明白一种，再按需补充入口形态适用场景推荐人群CodexApp桌面应用图形化界面，可视化Diff和项目管理初学者首选CLI命令行终端直接在终端操作，能力暴露最直接习惯终端的开发者Cloud云端沙盒异步执行长任务，自动创建PR委派独立任务IDE插件编辑器集成在VSCode等编辑器内直接调用IDE重度用户Chrome扩展浏览器插件操作已登录的Web应用和内部系统Web自动化场景提示：已经打开桌面App，就先把App用明白；Cloud、IDE和Chrome扩展都是为具体场景服务的，不是"越多越专业"Codex与传统AI聊天工具的区别对比维度传统AI聊天工具CodexAgent输出形式仅文字回答和代码片段实际操作文件、运行命令、提交代码文件操作需要手动复制粘贴代码直接读写工作区文件，支持多文件编辑命令执行给出命令，用户手动执行自主运行Shell命令并查看输出上下文对话历史，需手动粘贴代码整个项目目录、Git状态、终端输出工作模式一问一答，被动响应Plan-Execute-Verify闭环，可异步执行扩展能力有限的插件和函数调用Skills/Plugins/MCP完整扩展生态02App界面详解左中右三栏布局与核心面板功能App整体布局：左中右三栏结构左侧·管理项目（Project）管理任务（Thread）列表运行状态查看任务弹出独立窗口Automations入口中间·对话与执行Codex回复与计划展示命令执行和工具调用审批请求交互底部输入框（任务控制台）模型选择、权限设置工作模式切换（Local/Worktree/Cloud）右侧·审查Diff变更面板新增绿色/删除红色按文件查看改动Inline评论暂存/撤销修改Commit/Push/开PR主逻辑：左侧管理项目和任务，中间处理对话与执行，右侧检查文件改动。不同功能面板会在这三块周围展开，但主逻辑不会变。左侧面板：项目与任务管理项目Project对应一个工作目录，告诉Codex"这一批文件属于同一项长期工作"决定默认读取材料的位置和沙盒允许写入的范围可以长期存在，一个项目下包含多个任务任务Thread/Chat项目下面的一次独立对话，最好只负责一个明确结果例如"检查文章结构""修复登录页报错""整理提交记录"任务应该有结束点，完成后可以归档或继续左侧常用动作添加或切换项目在当前项目下新建任务打开以前的任务继续处理查看运行中/待审批/已结束任务把任务弹出为独立窗口方便和浏览器或编辑器并排查看旧任务混入无关上下文时新需求完全不同时直接新建任务通常更干净中间面板：对话区与输入框中间区域显示Codex的回复、计划、命令、工具调用和审批请求，底部输入框不只是聊天框，也是任务控制台输入框周围的核心功能发送/停止：提交要求或中断正在执行的任务模型/权限：选择处理模型，设置只读或可写权限附件/语音：加入文件图片，Ctrl+M语音输入工作模式：在Local、Worktree、Cloud间切换执行过程中不必等它彻底结束才说话。发现方向不对，可以直接补充："只检查，不要修改""不要安装依赖""先停在计划阶段"。越早纠偏，浪费的时间越少。右侧面板：Diff与变更审查Diff面板的核心价值查看Codex到底改了什么。新增通常以绿色显示，删除通常以红色显示。可以按文件查看，也可以聚焦某一轮或整个分支的变化。承担代码审查工作查看所有未提交修改在具体代码行旁添加inline评论按文件或改动块暂存、撤销在App内完成commit、push或创建PR技巧：如果某一行有问题，直接在那一行留下评论，比在输入框里描述"上面那个函数"准确得多。评论写完后，再发一句"处理刚才的inline评论"。03工作区与运行模式Local/Worktree/Cloud三种模式的选择策略工作区选择：最小目录原则选择标准：完成这件事所需的文件，能否集中放在一个最小目录里。能，就只打开这个目录。常见场景的选择策略场景做法只改一个独立项目打开项目根目录一个仓库有多个互不相关的应用分别添加为多个Codex项目前后端分成相邻目录以主要目录启动，用额外目录权限补充另一个只想分析，不希望修改仍然打开正确目录，但把权限设为只读任务要在远端环境执行选择Cloud，而不是扩大本地权限Local模式：直接改当前目录Local会在你选中的项目目录里直接工作。改动会立刻出现在本地文件中，适合绝大多数日常任务：改文档、修一个Bug、运行测试、整理目录、查看项目结构。优势直接、即时，改动立即可见不需要额外的同步或合并步骤适合快速迭代和小范围修改单任务从Local开始最省事注意事项你和Codex同时改相同文件可能互相干扰改动直接影响当前工作分支不适合需要隔离的实验性改动多任务并行时容易冲突适用场景：改文档、修Bug、运行测试、整理目录、查看项目结构等绝大多数日常任务Worktree模式：给任务一份隔离副本Worktree基于Git的worktree功能，为任务创建一个独立工作目录。Agent在里面修改，你正在使用的本地目录不会跟着变化。两种典型适用场景场景一：多任务并行同时让多个任务改同一个仓库，每个任务有独立的工作目录，互不干扰。完成后分别建分支、提交并开PR。场景二：实验性改动想让Codex试一个改动，又不想马上碰当前分支。任务完成后可通过Handoff把结果移回Local。Worktree不是每个任务都要开。只改一个小文件、只有一个Agent在工作，Local更短。需要隔离和并行时再用Worktree。Cloud模式：把任务交到云端Cloud会在远端隔离环境里克隆仓库并执行。每个任务在独立的云沙盒中运行，预装了仓库环境，可以并行处理多任务。核心价值不需要守着本机，任务完成后看Diff再决定是否合并云沙盒隔离，不怕AI乱改本地文件任务可以后台排队，支持多任务并行适用任务类型代码审查、修复明确Issue批量重构和跑测试边界清楚、可异步等待的任务需要频繁讨论、依赖本机文件或本地应用的工作，Local或Worktree通常更顺。三种运行模式对比对比维度LocalWorktreeCloud工作位置当前项目目录Gitworktree隔离目录远端云沙盒改动可见性立刻出现在本地文件独立目录，不影响当前分支云端完成后看Diff并行能力单任务为主支持多任务并行多任务后台排队交互方式实时对话，随时纠偏实时对话，Handoff移回异步提交，完成后审查最佳场景日常修改、快速迭代并行开发、实验改动代码审查、批量重构推荐优先级默认首选需要隔离时异步长任务时04Plan与权限计划先行与安全边界控制Plan：执行前的路线图Plan是执行前的路线。复杂任务里能提前发现范围过大、顺序不合理等问题；简单任务里也可能只是多一道形式适合开Plan的情况任务跨多个文件修改不可轻易回退需要先调查原因还在比较几种实现方式不需要强行Plan的情况改标题、查一个报错位置执行一条确定命令简单的文件整理没有必要先列五步计划一份有用的Plan至少回答四个问题真正要解决什么明确目标，不被表面需求带偏准备看哪些材料需要读取的文件和参考资料准备改哪些地方涉及的文件和修改范围最后怎么证明完成验收标准和验证方式权限三档：安全边界控制Read-only只读模式只能读取文件和查看信息不能修改任何文件不能执行写入命令适合分析、审查、理解代码CLI:codex--sandboxread-onlyWorkspace-write工作区可写可读写工作区内文件可在工作区内运行命令超出范围需审批覆盖大多数日常工作小白推荐默认使用此档Fullaccess完全访问可读写工作区外文件可执行任意命令--full-auto低摩擦执行--yolo跳过审批和沙盒不适合作为日常默认项Fullaccess不应该为了少点几次确认而打开，更不适合无人值守的定时任务。--full-auto适合在工作区内低摩擦执行，它不等于整机完全开放。审批弹窗：四要素审查法看到审批请求时，先看四件事，再决定是否允许执行1执行什么命令确认命令内容是否符合当前任务目标2在哪个目录执行确认执行路径在预期工作范围内3是否需要网络网络访问可能涉及数据外传或下载4为何有必要这一步对当前目标是否真的必要以下操作值得停下来确认安装依赖、上传文件、删除数据、修改账号设置、对外发布、访问凭据——这些操作都可能产生不可逆的影响，必须人工确认后再执行。05核心工具终端、浏览器、ComputerUse、图片与Memory集成终端与In-AppBrowser集成终端每个App任务都有自己的终端，macOS中Cmd+J显示终端目录跟随任务：Local打开本地项目，Worktree打开隔离目录可运行测试、启动开发服务、查看gitstatusCodex能读取终端当前输出，直接说"检查终端里的错误"In-AppBrowser内置浏览器适合打开本地页面并检查界面可在页面元素上直接留下带位置的评论例如"这里字号小一点""按钮和输入框对齐"不复用已登录的Chrome会话，需登录系统用Chrome扩展技巧：看到终端报错时，不必整段复制，直接说"检查终端里的错误"，Codex能读取当前输出。在浏览器页面元素上留评论，比纯文字描述"上面那个按钮"准确得多。ComputerUse与图片输入ComputerUse让Codex操作桌面应用：点击、输入、拖拽、读屏幕、使用快捷键适用场景没有API的旧工具批量录入数据文件整理和跨应用流程涉及付款、发布、删除、账号权限和对外发送时，最终确认应留给人图片输入与图像生成图片可直接拖进输入框作为上下文，也可在CLI启动时附带CLI用法：codex-iscreenshot.png"检查这个页面为什么错位"图像生成适合制作界面素材、概念图和文档插图是一项可选能力，不是每个任务都需要生成后检查，出现文字必须重做Memory与AGENTS.mdMemory保留你反复表达过的偏好和纠正。例如项目固定使用哪套测试工具、提交信息采用什么格式、某类文件应该放在哪里。特点逐渐积累的隐式偏好适合长期重复协作跨会话自动生效不需要手动维护AGENTS.mdCodex进入项目时会读取的规则文件。记录不会随一次任务结束而消失的信息：构建命令、目录结构、代码规范、验收方式。特点明确可见、可以审查的项目规则可用/init生成初稿再精简规则来自真实问题，短而准团队共享，随仓库版本管理Memory是隐式偏好积累，AGENTS.md是明确规则。重要规则建议写进AGENTS.md，两者互补不替代。06CLI深度使用安装配置、常用命令与快捷键CLI安装与配置前置条件Node.js>=22，最低4GB内存（推荐8GB），Git2.23+（可选）安装方式npminstall-g@openai/codexbrewinstall--caskcodex(macOS)认证方式方式一：codexauthlogin（ChatGPTPlus/Pro/Team）方式二：exportOPENAI_API_KEY="your-key"验证安装：codex--version中国用户可使用淘宝镜像加速：npminstall-g@openai/codex--registry=配置文件位于~/.codex/config.tomlCLI常用命令与快捷键三个核心子命令codex启动交互界面（全屏TUI）codexexec"任务"非交互执行一次任务codexresume--last继续最近的会话TUI内实用操作操作说明输入/查看特殊命令（/plan、/review、/diff、/permissions、/status）输入@搜索并引用工作区文件输入!+命令直接运行Shell命令Enter/Tab运行时Enter补充指令，Tab排队后续要求07扩展生态Skills/Plugins/MCP三者关系与使用Skills：可复用的做事方法一个Skill本质上是一个目录，核心文件叫SKILL.md。里面有名称、触发说明和具体步骤，也可以附带脚本、模板和参考资料。两种调用方式显式调用在提示中写$skill-name，手动点名触发隐式调用Codex根据Skill的description自动判断常见Skill分类文档和内容长文写作、PDF处理开发流程代码审查、发布、PR视觉与媒体生成图片、制作PPT团队规则测试、部署、验收研究分析检索资料、整理数据Plugins与MCPPlugins能力包把一组Skill、MCP和连接器打包分发。安装后能跨工作区使用。代表性插件AtlassianRovo：Jira、Confluence、BitbucketGitLabIssues：处理GitLab事项CircleCI、Render：查看构建和部署CodeRabbit：辅助代码审查MicrosoftSuite：Word、Excel、Outlook、TeamsGitHub、Slack、GoogleDrive连接器MCP外部接口统一接口，让Codex把外部服务的查询和操作当成工具使用。常见MCPOpenAIDocsMCP：查询OpenAI文档Context7：读取常用开发库文档FigmaMCP：读取设计稿PlaywrightMCP：控制和检查网页SentryMCP：读取线上错误GitHubMCP：处理PR和IssueCLI中用codexmcpadd添加，codexmcplist查看，会话内用/mcp检查连接三者关系：操作手册、能力包、外部接口Skill教Codex怎么做一类事情操作手册Plugin打包一整套能力能力包MCP连接外部工具和数据外部接口包含关系：Plugin可以同时包含多个Skills和MCPServers实际工作不必五个一起上，缺哪一层再补哪一层。重复工作固化成Skill，需要外部系统才接MCP，需要一整套现成能力才装Plugin。Skill是操作手册，Plugin是能力包，MCP是外部接口，Automation是闹钟，/goal是长期任务状态。08自动化与长期任务Automations定时任务与/goal长期目标Automations与/goalAutomations定时任务适合固定频率检查、未来某个时间执行、跨天继续推进的长任务运行结果进入Triage收件箱Git仓库使用Worktree更稳，不打扰正在编辑的目录/goal长期目标跨多次会话推进、有明确完成标准的长任务可跨/clear、对话压缩和会话切换保留状态目标要有可验证的结束条件，太空会让Agent不断找新事做设置五步流程1.选择任务对应的项目2.写清楚到点后要执行的Prompt3.选择时间或重复频率4.选择Local或Worktree执行环境5.检查权限，保存并等待运行定时之前，先在普通任务中手动跑一次同样的Prompt，确认范围、工具、输出和Diff都符合预期，再交给无人值守执行09实战进阶学习路径、最佳实践与工具对比四阶段学习路径第一阶段基础过关选对工作区新建一个任务控制Read-only与Workspace-write学会看Diff能判断"改了什么、有没有越界"第二阶段加入审查复杂任务先看Plan使用集成终端完成后自己运行检查让独立审查Agent看一次改动用/review做代码审查第三阶段并行协作学习Worktree隔离多任务并行处理确实有两个互不依赖的任务时再并行不要为了看到多个Agent运行而硬拆第四阶段扩展生态重复工作固化成Skill需要外部系统接MCP需要整套能力装Plugin需要定时运行开Automation最佳实践与常见误区最佳实践给任务正确的材料和清晰边界执行过程中及时纠偏用Diff、终端、测试判断结果复杂任务先开Plan重要规则