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

RAOY的AI笔记

180人浏览 · 2026-07-17 14:01:36

RAOY的AI笔记 · 2026-07-17 14:01:36 发布

一、Codex CLI适合处理什么任务？

普通对话更适合解释概念、讨论方案和生成较短的代码片段；Codex CLI更偏向项目执行。登录并获得相应权限后，它可以围绕本地仓库检查文件、提出修改、运行测试，并把过程交给开发者审核。

阅读陌生项目的目录、入口、依赖和测试方式；
根据明确需求修改多个相关文件；
复现Bug并分析失败测试；
运行格式检查、静态检查和单元测试；
通过Git差异核对修改范围；
使用codex exec处理可重复的开发任务。

涉及生产数据库、支付、权限配置和敏感代码时，不应直接放开全部权限，也不能省略人工Review。

二、安装Codex CLI

本文以npm安装为例：

npm install -g @openai/codex
codex --version
codex 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.0

pytest -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