Codex CLI入门：安装、项目分析与安全修改流程

一、Codex CLI适合处理什么任务普通对话更适合解释概念、讨论方案和生成较短的代码片段Codex CLI更偏向项目执行。登录并获得相应权限后它可以围绕本地仓库检查文件、提出修改、运行测试并把过程交给开发者审核。阅读陌生项目的目录、入口、依赖和测试方式根据明确需求修改多个相关文件复现Bug并分析失败测试运行格式检查、静态检查和单元测试通过Git差异核对修改范围使用codex exec处理可重复的开发任务。涉及生产数据库、支付、权限配置和敏感代码时不应直接放开全部权限也不能省略人工Review。二、安装Codex CLI本文以npm安装为例npm install -g openai/codexcodex --versioncodex login status图1 隔离演示环境中的安装、版本和登录状态检查。截图时CLI版本为0.144.5状态为未登录。首次使用可运行codex再按照界面提示选择ChatGPT登录或其他可用的认证方式。不要把API Key写进截图、脚本或公开仓库。三、先用只读权限了解项目codex -C ./my-project --sandbox read-only任务描述可以写得具体一些先阅读README、依赖配置、src和tests不要修改任何文件。请输出1. 项目用途与目录结构2. 主要入口和核心调用关系3. 启动命令与测试命令4. 当前信息还缺少什么5. 后续修改可能涉及的风险。这样的提示明确了读取范围、禁止写入并规定了输出结构比“帮我看看项目”更容易检查。四、本地复现一个最小Bug示例函数把百分比数值直接参与了计算def final_price(price: float, discount_percent: float) - float:if price 0:raise ValueError(price must be non-negative)if not 0 discount_percent 100:raise ValueError(discount_percent must be between 0 and 100)return round(price * (1 - discount_percent), 2)测试用例期望100元打八折后得到80元def test_twenty_percent_discount() - None:assert final_price(100.0, 20.0) 80.0pytest -q图2 示例项目的本地pytest失败结果。函数返回-1900.0说明百分比换算存在错误。这一步的目的是先得到稳定、可重复的失败结果。没有复现问题就直接修改代码后续很难判断修复是否有效。五、登录后可以采用的安全修改流程codex -C ./codex-cli-demo --sandbox workspace-write --ask-for-approval on-request任务描述示例运行pytest -q复现当前失败测试。先解释根因不要立即大范围重构。只修改与根因直接相关的文件。修复后重新运行pytest -q并执行git diff。最后按“根因、修改、验证、剩余风险”四部分总结。不要修改无关格式不要删除现有边界检查。需要接入脚本时也可以使用非交互方式codex exec -C ./codex-cli-demo --sandbox workspace-write --ask-for-approval on-request 复现失败测试定位根因完成最小修改重新测试并总结git diff。这里的重点不是让工具自由修改而是控制目录、写入范围和审批条件并要求它先复现、后修改、再验证。六、人工最小修改与回归验证本例的根因是折扣百分比没有除以100。人工完成的最小修改为- return round(price * (1 - discount_percent), 2) return round(price * (1 - discount_percent / 100), 2)图3 人工完成一行最小修改后的Git差异和回归测试3项测试全部通过。该结果不是Codex自动生成。是否只修改了与根因有关的文件原有输入校验和异常行为是否保留是否需要补充0%、100%和小数折扣测试格式化、静态检查和完整测试集是否通过是否出现与当前任务无关的自动重构。七、常用命令# 启动交互模式codex# 查看登录状态codex login status# 指定项目目录codex -C ./my-project# 只读分析codex -C ./my-project --sandbox read-only# 允许修改工作区并在需要时请求人工审批codex -C ./my-project --sandbox workspace-write --ask-for-approval on-request八、常见问题1. 终端提示找不到codex命令npm prefix -gnpm list -g --depth0macOS和Linux通常检查全局目录下的bin是否在PATH中Windows通常检查npm全局目录本身是否已加入PATH。也可以重新打开终端后再测试codex --version。2. 登录后仍显示未登录codex login status必要时先运行codex logout再重新登录。还应确认不同终端没有使用不同的CODEX_HOME或安装路径。3. 工具无法正确理解项目先补充README、启动方式、测试命令和验收标准把任务拆成“项目理解”和“代码修改”两个阶段。不要一开始就要求大范围重构。4. 修改范围过大在任务中明确写出“最小修改、不得改无关格式、先说明计划”并通过Git检查点和git diff审核。发现方向不对时先回退再以只读方式重新分析。5. 测试通过就说明可以上线吗不一定。现有测试只能覆盖已经编写的用例还需要检查安全、权限、异常处理、性能和业务边界。AI生成或人工完成的修改都不能绕过代码审查。九、本文能够说明什么本文展示了CLI安装和状态检查、本地Python Bug复现、人工最小修改后的Git差异与回归测试以及登录Codex后可以采用的权限和任务组织方式。