用 Codex CLI 半个月，我用 30 行代码搭了一个跨平台 PDF 工具——完整复盘

大多数人第一次用 AI 写代码，都会在同一个地方翻车：让它"帮我写个 XXX 软件"，然后什么都做不成。

原因很简单——你给的上下文太少，它给的代码太碎，你们之间缺一个协作流程。

OpenAI 的 Codex CLI 正好解决这个问题。它不是 ChatGPT 的网页版，而是直接跑在你终端里、能读你本地代码、能执行命令、能迭代修改的 AI 编程助手。我用它半个月，从零搭出了一个能跨平台运行的 PDF 处理工具，踩了不少坑，这篇文章把完整流程还原给你。

先说结论：Codex CLI 适合做什么

有明确功能边界的小工具：PDF 合并、图片压缩、批量重命名
重复性脚手架代码：读文件、写配置、处理命令行参数
跨平台兼容层：Windows/macOS/Linux 的路径处理、打包脚本

它不擅长的：大型架构设计、需要业务背景的复杂逻辑。

环境准备


npm install -g @openai/codex

codex --version

Codex CLI 默认调用 OpenAI API。如果你没有境外信用卡，或者 API 费用太贵，可以把 base URL 指向国内中转服务，价格直接打六折：


export OPENAI_API_KEY="你的key"

export OPENAI_BASE_URL="https://api2everything.xyz/v1"

设完之后 codex 命令就走国内线路，不需要代理，延迟也更低。

实战：30 行核心代码搭 PDF 工具

我的需求是：命令行合并多个 PDF，输出单个文件，Windows 和 macOS 都能用。

先不急着让 AI 写，把需求拆成三个小任务：

1. 解析命令行参数（输入文件列表 + 输出路径）

2. 合并 PDF（用 pypdf 库）

3. 打包成单文件可执行（用 pyinstaller）

第一步：让 Codex 生成骨架

在项目目录下运行：


codex "写一个 Python CLI 工具，接受多个 PDF 文件路径作为参数，合并成一个文件，输出路径用 --output 指定，用 pypdf 库"

它会生成类似这样的代码，同时在终端里直接执行 pip install pypdf：


#!/usr/bin/env python3

"""PDF 合并工具 - 跨平台命令行版本"""



import argparse

import sys

from pathlib import Path

from pypdf import PdfWriter



def merge_pdfs(input_paths: list[str], output_path: str) -> None:

    writer = PdfWriter()

    

    for path_str in input_paths:

        path = Path(path_str)

        if not path.exists():

            print(f"错误：文件不存在 {path}", file=sys.stderr)

            sys.exit(1)

        if path.suffix.lower() != ".pdf":

            print(f"警告：跳过非 PDF 文件 {path}")

            continue

        writer.append(str(path))

    

    output = Path(output_path)

    output.parent.mkdir(parents=True, exist_ok=True)

    

    with open(output, "wb") as f:

        writer.write(f)

    

    print(f"合并完成，共 {len(writer.pages)} 页 → {output}")



def main():

    parser = argparse.ArgumentParser(description="合并多个 PDF 文件")

    parser.add_argument("inputs", nargs="+", help="输入 PDF 文件路径")

    parser.add_argument("--output", "-o", required=True, help="输出文件路径")

    args = parser.parse_args()

    merge_pdfs(args.inputs, args.output)



if __name__ == "__main__":

    main()

这段代码直接可以跑。测试：


python merge_pdf.py a.pdf b.pdf c.pdf --output result.pdf

第二步：迭代——加进度条

Codex CLI 的核心优势是在同一个上下文里连续对话。直接追加需求：


codex "给合并过程加一个进度条，用 tqdm 库，显示当前处理的文件名"

它会定位到 merge_pdfs 函数，只修改必要的部分，不会重写整个文件。这和网页版 ChatGPT 最大的区别——它知道你的代码现在长什么样。

第三步：跨平台打包

这步最容易翻车，不同系统的 pyinstaller 参数不一样：


codex "写一个 Makefile，分别有 build-mac 和 build-win 两个 target，用 pyinstaller 把 merge_pdf.py 打包成单文件可执行，mac 用 --onefile，windows 额外加 --noconsole"

生成的 Makefile 片段：


build-mac:

	pyinstaller --onefile --name pdf-merge merge_pdf.py



build-win:

	pyinstaller --onefile --noconsole --name pdf-merge.exe merge_pdf.py



clean:

	rm -rf dist build __pycache__ *.spec

踩坑记录

坑 1：让 AI 一次性写完整个项目

结果是一堆看起来完整、实际上互相依赖的文件，运行直接报错。正确方式：拆成最小可测试单元，逐步迭代。

坑 2：上下文丢失

Codex CLI 的会话上下文有限制。做复杂项目时，每次启动前用 --context 参数指定一个 CONTEXT.md，把项目结构和当前进度写进去，相当于给 AI 的"工作记忆"。

坑 3：Windows 路径分隔符

生成的代码经常用 /，在 Windows 上会出问题。让它统一用 pathlib.Path，一次解决。

工具链费用算了一下

用 Codex CLI 开发这个工具，整个过程调用了大概 400 次 API（含大量代码上下文），如果直接走 OpenAI 官方，大约花了 $3 左右。

我用的是无量Api，同样的用量折算下来不到 ¥8，支持国内直连，OpenAI / Claude / Gemini / DeepSeek 300+ 模型都有，改一行 OPENAI_BASE_URL 就能接入，注册还送 ¥1 体验额度。对于这种长期高频的 CLI 开发场景，省下来的钱很可观。

最后

AI 写代码这件事，上限不是 AI 的能力，而是你把需求拆得够不够细。Codex CLI 只是把"拆任务→执行→验证"这个循环的摩擦力降到最低。

你现在用什么工具辅助编程？遇到过哪些奇怪的 bug？评论区聊聊， 也欢迎点赞收藏，下次出 Codex CLI 进阶配置篇。