Codex CLI 实战：从安装到玩转命令行 AI 编程智能体

1. 背景与核心概念

1.1 什么是 Codex

很多同学第一次听到“Codex”，可能还停留在 2021 年那个训练出 GitHub Copilot 的旧模型上。但 2025 年的语境里，Codex 已经完全是另一回事了：它是 OpenAI 推出的新一代编程智能体（Coding Agent），而不再只是一个“补全代码的模型”。

你可以把它理解成一个住在终端里的 AI 程序员。普通 AI 编程工具是“你问一句，它补一段”；Codex 则是“你交代一个任务，它自己规划步骤、写代码、跑命令、看报错、再改代码”。整个过程不是单次问答，而是一个持续循环：理解需求 → 制定计划 → 执行命令 → 检查结果 → 调整代码 → 再次验证。

一套完整的 Codex 使用链路通常包括三个入口：命令行工具 Codex CLI、VS Code 里的 Codex 扩展，以及 ChatGPT 网页中的 Codex 云端环境。其中 Codex CLI 是最核心、最灵活的部分，本文会重点讲解。

1.2 Codex 能解决什么问题

如果只用一句大白话概括：Codex 解决的是“写代码动手成本高”的问题。

过去我们写一个功能，需要自己建工程、写业务逻辑、补测试、运行调试，哪一步报错都要手动排查。而 Codex 可以把这些步骤压缩为一句自然语言指令。比如你对它说：“帮我写一个 Python 脚本，读取 CSV 文件，按日期分组统计销售额，并输出图表。”它会自己创建脚本、处理依赖、运行并调试，直到任务基本完成。

常见的应用场景包括：

• 搭建新项目骨架，自动生成目录结构、配置文件和基础代码。
• 跨文件重构，比如把某个模块拆成多个文件，或统一替换旧接口。
• 补单测，让 Codex 针对已有函数生成覆盖主要分支的测试用例。
• 修 bug，把报错栈贴给它，由它定位并修改。
• 写自动化脚本，比如批量重命名文件、定时清理临时目录。
• 辅助学习，让它解释一段复杂代码或生成注释文档。

1.3 Codex 与 Claude Code 的关系

标题里同时提到了 Claude Code，这其实点出了当前 AI 编程工具的一个新方向：各家大模型厂商都在做“终端型编程智能体”。Anthropic 有 Claude Code，OpenAI 有 Codex，本质上是同一个产品形态，只是底层模型和生态不同。

Codex 的优势在于它和 OpenAI 的模型体系、ChatGPT 账号体系深度打通。你用 ChatGPT Plus / Pro / Team 账号就能直接登录使用，也可以为 API 用户单独配置权限。和 Claude Code 相比，Codex 的服务端任务调度、沙箱执行机制、IDE 扩展等细节各有差异，但核心思路是一致的。学会了 Codex，你再去上手 Claude Code 或其他 Agent 工具，会感觉很熟悉。

2. 环境准备与版本说明

在开始安装 Codex 之前，先确认本机环境。下面这些准备工作虽然看着多，实际操作也就几分钟。

2.1 操作系统要求

Codex CLI 官方支持 macOS 和 Linux，Windows 用户建议使用 WSL2（Windows Subsystem for Linux）。如果你平时在 Windows 上只做简单试用，WSL2 是最省事的方案，因为沙箱机制和命令执行环境都更接近 Linux 原生。

版本需要根据你的项目实际情况调整，本文示例以常见环境为例，重点演示配置思路。准备清单如下：

2.2 安装 Node.js 与 npm

Codex CLI 通过 npm 分发，所以 Node.js 是第一前置条件。你可以去 Node.js 官网下载 LTS 版本，也可以用包管理器安装。

macOS 安装示例：

bash复制brew install node
node -v
npm -v

Ubuntu / Debian 安装示例：

bash复制sudo apt update
sudo apt install -y nodejs npm
node -v
npm -v

WSL2 环境下同样使用上面的 Ubuntu 命令。安装完成后，能看到 node 和 npm 的版本号即可。

这里补充一点：Codex CLI 本身是 Rust 编写的，但对外通过 npm 包发布，所以需要 Node 运行时来安装和启动。如果你发现 npm 安装很慢，可以先配置国内 npm 镜像，例如：

bash复制npm config set registry https://registry.npmmirror.com

这个步骤是可选的，不是 Codex 必须的配置，只是提升安装体验。

2.3 账号与权限准备

Codex 需要一个 OpenAI 账号。简单说有以下几种情况：

• ChatGPT Plus / Pro / Team 用户：可以直接登录网页版 Codex，也可以在本地 CLI 中使用账号登录。
• OpenAI API 用户：可以设置 OPENAI_API_KEY 环境变量来使用 Codex。
• 免费用户：能否使用取决于当时官方开放策略，建议以官方页面为准。

注意，Codex 会代表你在本机执行命令，涉及文件读写、软件安装等操作。因此强烈建议在测试环境或自己本机的隔离目录中使用，不要在未授权的情况下连接生产环境，更不要把生产数据库的连接凭据随意放在项目文件里，尤其当它们可能被 AI 工具读取时。

3. 安装与首次启动

环境准备好后，下面开始正式安装 Codex CLI，并完成登录。

3.1 使用 npm 安装 Codex CLI

打开终端，执行全局安装命令：

bash复制npm install -g @openai/codex

安装完成后，验证版本：

bash复制codex --version

如果提示 command not found，通常是 npm 的全局目录没有加入 PATH。可以查看 npm 全局目录：

bash复制npm prefix -g

然后把对应的 bin 目录加入 shell 配置。比如：

bash复制export PATH="$(npm prefix -g)/bin:$PATH"

记得把这一行写入 ~/.zshrc 或 ~/.bashrc，新开终端才会生效。

如果你所在网络环境无法直接访问 npm 官方源，也可以先配置镜像源再安装。本文不展开网络层面的访问问题，按你自己的实际情况处理即可。

3.2 登录与认证

安装成功后的第一步是登录。执行：

bash复制codex login

该命令会自动打开浏览器，引导你完成 OpenAI 账号授权。授权完成后，终端会显示类似“Login successful”的信息。

如果无法使用浏览器登录，也可以使用 API Key 方式。先设置环境变量：

bash复制export OPENAI_API_KEY="你的 API Key"

然后执行 codex 即可绕过登录流程。API Key 的权限管理要格外小心，不要把 Key 提交到 Git 仓库或公开的配置文件中。

退出登录时使用：

bash复制codex logout

3.3 首次运行：进入交互式模式

登录成功后，直接在终端输入：

bash复制codex

你会进入一个类似 >>> 的交互式 REPL 环境。在这里可以输入自然语言指令，Codex 会先展示执行计划，然后逐条执行命令或修改文件。

先试一个最简单的问题：

code复制你好，请介绍一下你自己，并列出你可以帮我完成的编程任务。

Codex 会基于当前环境和模型能力返回一段说明。到这里，Codex CLI 的安装和启动链路已经全部打通。

如果希望直接在交互式环境中退出，可以输入 exit，或者按 Ctrl + D。在任务执行过程中按 Ctrl + C 可以中断当前操作。

4. 核心功能与完整实战案例

安装登录只是热身，下面用一个真实的命令行小项目走一遍 Codex 的完整工作流程。

4.1 核心运行机制：计划、审批、执行、验证

在开始实战之前，需要先理解 Codex CLI 的工作机制。它并不是一次性把代码全部“吐”出来就完事了，而是进入一个循环：

1. 接收任务描述，理解需求和约束。
2. 制定执行计划，比如“先创建项目目录，再安装依赖，然后编写代码”。
3. 在沙箱或本地环境中执行命令。默认情况下，每执行一个关键步骤前会请求你批准（Approval）。
4. 根据命令输出判断结果，如果出错就读取报错信息并修复。
5. 反复执行，直到任务完成或你把任务中断。

这种“Agent 循环”非常像真人程序员的工作方式。好处是它能自己发现编译错误、测试失败等问题并修复，坏处则是它会实际改动文件、执行命令，所以权限审批环节不能省略。

4.2 实战：用 Codex 写一个命令行 Todo 工具

下面我们让 Codex 从零生成一个 Python 版命令行 Todo 工具。

在交互式环境中输入：

code复制请创建一个 Python 命令行 Todo 工具，要求：
1. 使用命令行参数添加、删除、列出任务。
2. 使用 JSON 文件保存数据，路径为 data/todo.json。
3. 支持 mark 命令将任务标记为完成。
4. 用 argparse 解析参数，不要使用第三方库。

Codex 会先输出计划，类似这样：

• 创建 todo.py 文件
• 创建 data/ 目录
• 编写基于 argparse 的入口逻辑
• 运行 python todo.py add "写博客" 验证功能

在请求批准时，你看到计划合理后选择批准。我在这里给出一个可运行的参考结果，Codex 每次生成的代码会有差异，但核心功能应该类似：

文件路径：todo.py

python复制import argparse
import json
from pathlib import Path

DATA_DIR = Path("data")
DATA_FILE = DATA_DIR / "todo.json"


def load_tasks():
    if not DATA_FILE.exists():
        return []
    with open(DATA_FILE, "r", encoding="utf-8") as f:
        return json.load(f)


def save_tasks(tasks):
    DATA_DIR.mkdir(exist_ok=True)
    with open(DATA_FILE, "w", encoding="utf-8") as f:
        json.dump(tasks, f, ensure_ascii=False, indent=2)


def add_task(content):
    tasks = load_tasks()
    new_id = max([t["id"] for t in tasks], default=0) + 1
    tasks.append({"id": new_id, "content": content, "done": False})
    save_tasks(tasks)
    print(f"已添加任务：{content}")


def list_tasks():
    tasks = load_tasks()
    if not tasks:
        print("当前没有任务。")
        return
    for task in tasks:
        status = "[x]" if task["done"] else "[ ]"
        print(f"{status} {task['id']}. {task['content']}")


def mark_done(task_id):
    tasks = load_tasks()
    for task in tasks:
        if task["id"] == task_id:
            task["done"] = True
            save_tasks(tasks)
            print(f"任务 {task_id} 已标记为完成。")
            return
    print(f"未找到任务 ID：{task_id}")


def delete_task(task_id):
    tasks = load_tasks()
    new_tasks = [t for t in tasks if t["id"] != task_id]
    if len(new_tasks) == len(tasks):
        print(f"未找到任务 ID：{task_id}")
        return
    save_tasks(new_tasks)
    print(f"任务 {task_id} 已删除。")


def main():
    parser = argparse.ArgumentParser(description="简单命令行 Todo 工具")
    subparsers = parser.add_subparsers(dest="command")

    add_parser = subparsers.add_parser("add", help="添加任务")
    add_parser.add_argument("content", help="任务内容")

    subparsers.add_parser("list", help="列出任务")

    mark_parser = subparsers.add_parser("mark", help="标记完成任务")
    mark_parser.add_argument("id", type=int, help="任务 ID")

    delete_parser = subparsers.add_parser("delete", help="删除任务")
    delete_parser.add_argument("id", type=int, help="任务 ID")

    args = parser.parse_args()

    if args.command == "add":
        add_task(args.content)
    elif args.command == "list":
        list_tasks()
    elif args.command == "mark":
        mark_done(args.id)
    elif args.command == "delete":
        delete_task(args.id)
    else:
        parser.print_help()


if __name__ == "__main__":
    main()

4.3 验证运行结果

Codex 生成代码后，通常会继续在终端中运行验证命令。你也可以手动执行：

bash复制python todo.py add "学习 Codex"
python todo.py add "写一篇技术博客"
python todo.py list

预期输出：

code复制已添加任务：学习 Codex
已添加任务：写一篇技术博客
[ ] 1. 学习 Codex
[ ] 2. 写一篇技术博客

再测试标记完成和删除：

bash复制python todo.py mark 1
python todo.py delete 2
python todo.py list

预期输出：

code复制任务 1 已标记为完成。
任务 2 已删除。
[x] 1. 学习 Codex

这个例子虽然简单，但已经涵盖了 Codex 的核心链路：理解需求、创建文件、编写代码、运行验证。你也可以继续对它提要求，比如“把任务数据改成 SQLite 存储”或“增加导出功能”，观察 Codex 如何跨文件修改代码。

4.4 任务审批与授权模式

默认情况下，Codex 在执行命令前会等待用户批准。你可以在交互界面看到代码执行的命令内容，确认安全后再放行。

如果对某个任务足够放心，也可以在启动时传入参数：

bash复制codex --full-auto "运行项目测试并修复失败用例"

--full-auto 表示全自动模式，Codex 不再逐条请求批准。这个模式方便但风险也更高。生产环境、支付环境、包含真实用户数据的项目里，务必保持默认的审批模式，不要为了省事而一路放行。

5. Codex 进阶用法

基础流程跑通之后，我们再看几个实际项目中更高频的用法。

5.1 非交互式运行与脚本化

除了进入 codex 交互环境，Codex 也支持直接把任务作为参数执行。在较新版本中，相关命令可以这样使用：

bash复制codex exec "检查当前目录下所有 Python 文件的语法错误"

如果你的版本命令不同，可以通过 codex --help 查看当前支持的子命令。脚本化场景下，Codex 可以集成到 CI/CD 流程中，例如自动修复代码格式、自动生成变更说明。但脚本化执行必须严格控制权限范围，并在独立环境中运行。

5.2 配置文件与模型调整

Codex CLI 的配置文件通常存放在用户目录下。早期版本的路径是：

text复制~/.codex/config.toml

常见配置项包括 model、model_provider 等。不同版本配置项差异较大，如果你需要修改，先执行：

bash复制codex --help

查看当前版本的配置说明。这里给出一个配置风格示例，真实字段以你的版本为准：

toml复制model = "gpt-5-codex"
model_provider = "openai"

修改配置文件后，重启 Codex 生效。

5.3 IDE 扩展与云版 Codex

Codex 不只有命令行形态。

• VS Code 扩展：在扩展市场搜索“Codex”，安装 OpenAI 官方扩展后，可以在编辑器侧边栏与 Codex 对话，选中代码让它修改，也可以让它解释报错。IDE 扩展适合日常写代码场景，因为上下文直接关联当前打开的文件。
• 云版 Codex：登录 ChatGPT 网页版后，可以进入 Codex 云端环境。它像一个预置好的远程开发容器，Codex 在里面代替你操作终端、读写文件、跑服务和测试。适合你不想在本地装一堆依赖，或者需要在一个干净的 Ubuntu 环境里做演示的情况。

三种入口底层共享同一套 Agent 能力，区别只是界面和运行环境。

5.4 与 Claude Code 的对比学习思路

如果你之前用过 Claude Code，会发现两者的操作模式高度相似：

• 都是在终端中启动。
• 都通过自然语言描述任务。
• 都能多轮对话并持续修改文件。
• 都支持命令审批和自动模式。

差异主要体现在账号体系、模型选择、沙箱实现和扩展生态上。推荐的学习方式是：先彻底掌握任意一个工具的任务拆分、审批策略和日志排查方法，再迁移到另一个工具时就会很快。编程 Agent 的核心能力是“让 AI 安全地替你操作电脑”，这个方法论是通用的。

6. 常见问题与排查思路

6.1 常见问题速查表

6.2 登录与认证问题

如果 codex login 打开浏览器后一直转圈，或提示授权失败，优先检查账号类型是否支持 Codex。部分免费账号可能无法访问完整功能。

排查步骤：

1. 执行 codex logout，再重新执行 codex login。
2. 确认浏览器没有拦截授权页面弹窗。
3. 使用 API Key 方式登录，先设置环境变量再运行 codex。
4. 查看网络环境是否能正常访问 OpenAI 服务，根据你的实际情况处理。

6.3 沙箱执行失败

Codex 出于安全考虑会在沙箱中执行命令。Linux 环境下，如果系统缺少相应沙箱组件，命令执行很可能直接失败。解决思路是安装对应系统依赖，常见包名类似 bubblewrap。不同发行版包名不同，安装前先用系统包管理器搜索。

如果你不希望因为沙箱问题阻碍开发，可以在配置中调整沙箱模式或关闭沙箱。但关闭沙箱意味着 Codex 可以直接读写更广泛的文件范围，务必只在可控环境中使用。

6.4 生成结果不符合预期

这是使用 Agent 工具最常见的问题。AI 生成的代码不一定完全满足需求，原因通常是需求描述精度不够。改进方法：

• 明确语言和框架，例如“用 Python 3.10，不使用第三方库”。
• 明确文件路径，例如“把脚本放在 scripts/ 目录下”。
• 明确验收标准，例如“运行后打印任务总数和完成率”。
• 明确边界，例如“不要修改 tests 目录以外的文件”。

更具体的描述能显著提升 Codex 的完成质量。

7. 工程实践与安全建议

工具越强大，责任边界越重要。Codex 是一个能执行命令、改写文件的智能体，使用不当会造成真实影响，下面几条建议来自工程落地经验。

7.1 始终使用版本控制

在让 Codex 动手之前，先初始化 Git 仓库并提交一个干净的基线。例如：

bash复制git init
git add .
git commit -m "before codex changes"

这样 Codex 每次修改后，你都能通过 git diff 查看改动内容，不满意时还能轻松回滚。不要让 Codex 在没有版本控制保护的目录里大改文件。

7.2 严格控制命令执行权限

默认审批模式不要关闭，尤其是下面几类高危操作：

• 删除文件或目录，特别是 rm -rf。
• 操作数据库，尤其是 DROP TABLE、DELETE FROM 等 SQL。
• 修改系统级配置文件。
• 在非测试环境执行涉及生产业务的命令。
• 安装不明来源的依赖。

当你看到 Codex 准备执行这些操作时，宁可中断任务，手动检查后再决定是否继续。

7.3 借助日志与审计

Codex 提供了日志查看能力：

bash复制codex log

当任务执行结果异常，或者你想复盘 Codex 到底执行过哪些命令时，先查日志。团队使用场景下，可以约定所有人必须在本地目录运行 Codex，并把日志按日期归档，方便问题追溯。

7.4 需求拆分优于一次性大任务

一次给 Codex 塞十个小需求很容易让它“忘前顾后”。推荐把大任务拆成多个小任务，逐个推进：

• 第一轮：生成项目骨架。
• 第二轮：实现核心逻辑。
• 第三轮：编写单元测试。
• 第四轮：补充 README 和示例。

每一轮都验证结果后再进入下一轮。这种工作方式和人类开发者的迭代节奏一致，排查问题时也更清晰。

7.5 不要把密钥放进项目代码

Codex 在读取文件和上下文时会看到项目里的内容。如果你在代码中硬编码 API Key、数据库密码、Token 等敏感信息，等于把这些信息暴露给了 AI 工具，也容易随 Git 仓库泄露。正确做法是使用环境变量或本地密钥管理工具，并且把密钥文件加入 .gitignore。

涉及数据库、生产环境、真实用户数据时，先在测试环境验证，获得合法授权后再执行变更，并始终保留备份和回滚方案。

8. 总结与学习路线

到这里，你其实已经掌握了一整套 Codex 的使用方法：从环境准备、npm 安装、账号登录，到交互式任务、文件生成、命令审批、日志查看，再到安全边界与团队落地建议。

接下来建议按这个顺序继续深入：

1. 在上手的第一周，只在自己的本地测试项目里使用 Codex，体验它修改文件、执行命令、失败修复的完整循环。
2. 第二周尝试用 Codex 重构一个已有项目的小模块，观察代码风格是否符合你的预期。
3. 第三周尝试脚本化运行，结合 codex exec 或 CI 流程，让 Agent 帮你做自动化格式修复或测试补充。
4. 如果对 Agent 的原理感兴趣，可以研究一下 Codex CLI 的开源实现，了解它如何组织上下文、安排计划、控制沙箱。

Codex 这类工具的价值不仅仅是“写代码更快”，更重要的是它改变了开发者与代码之间的交互方式。你可以用自然语言指挥一个 AI 程序员干活，但判断力、安全边界和工程质量意识，仍然要留在自己手里。

如果收藏了本文，建议把文中的命令和排查思路整理成自己的速查笔记。下次遇到“Codex 登录失败”“沙箱启动失败”“生成结果不符合预期”这些问题时，能少走很多弯路。