Codex 实用教程：Windows、macOS、Linux 安装配置到首个可验收项目

安装完成后只问一句"你能做什么"，往往很难知道如何开始。更有效的第一步，是给 Codex 一个输入明确、结果可以检查的小项目：读一份 CSV，验证价格数据，输出摘要，再用测试确认错误数据没有被悄悄吞掉。

本文覆盖三种系统的安装与日常操作，并给出可直接复现的练习。核查日期为 2026-09-17；本机实际为 macOS / arm64、Python 3.12.14，已读取到 codex-cli 0.154.0。Windows/Linux 安装步骤来自官方文档，本次没有在这两种系统运行，也没有进行不同模型的速度或质量比较。

Windows、macOS、Linux 分别怎么安装

本文以 Codex CLI 为统一入口。桌面应用、IDE 扩展和 CLI 是不同形态，界面与权限配置不能直接混用。当前官方桌面入口已放在 ChatGPT 桌面应用文档中，也列有 Linux 安装指引；这里不把旧版桌面支持范围当成 CLI 限制。桌面入口

Windows 原生： 打开 PowerShell，使用官方页面列出的 Windows 安装命令：

powershell 复制代码

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex --version

命令中的 ExecutionPolicy 参数作用于启动的 PowerShell 进程，不是让你永久关闭系统策略。若公司设备禁止脚本安装，按管理员允许的渠道安装，不反复扩大权限。已有 Node.js/npm 环境也可选择官方 npm 方式：npm install -g @openai/codex。

Windows 11 是官方推荐的原生基线；较新的 Windows 10 为尽力支持。Windows 原生可以使用自身沙箱，不必为了启动 Codex 就先装 WSL 。Windows 说明

macOS： 打开终端，在 zsh 或 bash 中运行：

bash 复制代码

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

Linux： 同样使用上面的 shell 安装器，安装后在当前 Linux 终端检查版本。安装 Codex 并不会自动替项目安装 Python、Node、编译器等开发依赖。

已经使用 WSL 的 Windows 开发者： 在 WSL2 的 Linux 终端内安装和启动 Codex，项目优先放在 Linux 家目录。Windows 里的安装与 WSL 内的安装、PATH、运行时是两套环境。当前官方文档明确 WSL1 不再适用于新版本，不能沿用"WSL1 也一样"的旧教程。WSL 指引

安装和升级渠道以Codex CLI 官方入口为准，更新后重新运行 codex --version 记录实际版本。

登录后，先进入正确的项目目录

新建一个只放练习文件的目录，例如 ai-price-lab，用终端进入它，再启动：

text 复制代码

codex login
codex

首次登录按页面完成账户认证。ChatGPT 登录与 API key 登录的额度、计费与组织政策不同；使用 API key 不等于自动消费 ChatGPT 订阅额度。密钥不要写进项目说明或截图。认证文档

进入会话后查看 /status，确认当前目录与配置；用 /permissions 查看本轮允许的操作。项目外路径或网络被拒绝时，先检查具体需要，不要把全权限当作通用修复。

用一份具体任务代替"帮我写个工具"

在练习目录保存 prices.csv：

csv 复制代码

sku,price
A,0.10
B,0.20

两行数据的期望是 count 为 2，total 为字符串 0.30。价格用十进制数，是为了让这个示例的结果可以稳定比较。向 Codex 发送：

text 复制代码

请实现 check_prices.py：读取 UTF-8 CSV，表头为 sku,price。
验证 SKU 非空、不重复，价格为有限非负十进制数。
成功输出 JSON，包含 count 和字符串形式的 total；错误输入报错并非零退出。
只使用 Python 标准库，不修改输入文件。
给出 unittest 测试，覆盖正常求和、只有表头、错误表头、重复 SKU、
空 SKU、非法/负数/NaN/Infinity 价格、缺列/多列和中文 SKU。
先说明输入输出与需要创建的文件，再实施。最后实际运行测试并报告结果。

这段提示词约定了输入、异常行为、依赖、修改范围和验收方式。第一次生成不符合要求时，反馈失败输入与实际输出，例如"重复 SKU 未报错"，比"写得不好"更有助于定位。

把稳定约定放进 AGENTS.md

在项目根目录创建 AGENTS.md，写入下面的练习约定。Windows 若使用 py -3 运行 Python，应把测试命令同步改成 py -3 -m unittest -v。

text 复制代码

这是离线 CSV 校验练习，只处理本目录的合成数据。
使用 Python 标准库，不引入第三方依赖。
字段必须为 sku,price；SKU 去掉首尾空白后非空且唯一。
价格用 Decimal，必须为有限非负数；表头-only 文件返回零条。
修改后运行 python3 -m unittest -v，并报告实际退出状态。
不改原始 CSV，不访问真实业务服务，不提交或推送代码。

AGENTS.md 用来提供项目说明，不是操作系统的权限开关。可以请 Codex 列出实际读取的指令文件，检查是否被上层或更近目录的约定影响。具体发现顺序见项目指令文档。

一份可对照的实现

下面是本文准备并在本机运行过的参考实现，保存为 check_prices.py。它用来校对练习结果，不代表每次向模型提问都会生成完全相同的代码。

python 复制代码

import csv
import io
import json
import sys
from decimal import Decimal, InvalidOperation
from pathlib import Path


def summarize(text):
    rows = csv.DictReader(io.StringIO(text))
    if rows.fieldnames != ['sku', 'price']:
        raise ValueError('header must be sku,price')
    seen = set()
    total = Decimal('0')
    for line, row in enumerate(rows, 2):
        if None in row or row['price'] is None:
            raise ValueError(f'line {line}: invalid columns')
        sku = row['sku'].strip()
        if not sku or sku in seen:
            raise ValueError(f'line {line}: empty or duplicate sku')
        try:
            price = Decimal(row['price'])
        except InvalidOperation as error:
            raise ValueError(f'line {line}: invalid price') from error
        if not price.is_finite() or price < 0:
            raise ValueError(f'line {line}: price must be finite and nonnegative')
        seen.add(sku)
        total += price
    return {'count': len(seen), 'total': str(total)}


if __name__ == '__main__':
    text = Path(sys.argv[1]).read_text(encoding='utf-8-sig')
    print(json.dumps(summarize(text), ensure_ascii=False))

macOS/Linux 运行 python3 check_prices.py prices.csv；Windows 在已配置 Python 启动器时运行 py -3 check_prices.py prices.csv。实际样本输出为：

text 复制代码

{"count": 2, "total": "0.30"}

本地 unittest 共 8 个测试方法通过，覆盖提示词中的八类验收点，非法价格和列数测试各包含多个子场景。测试只是这份小脚本的证据：没有验证超大文件性能、任意 CSV 方言、超高精度金额或恶意超长输入。生产金额还需要限制小数位数、数值范围及 Decimal 精度；不要直接拿此练习替代财务逻辑。

日常使用可以重复这四步

先让 Codex 解释当前实现与测试入口，再描述一个具体改动；完成后检查实际命令输出，最后查看代码差异。已有 Git 项目先运行 git status --short；保留好原有改动。修改后用 git diff 看已跟踪文件，同时查看 git status 中的新文件，因为普通 git diff 不显示未跟踪文件。

可用 /review 发起检查，重点告诉它检查什么，例如错误输入是否仍非零退出、是否偷偷改了原始 CSV。恢复已有对话可用 codex resume。命令与会话中的斜杠指令分属两层，终端里输入 /review 不会替你启动 Codex。CLI 命令参考

常见卡点

找不到 codex：新开终端，Windows 用 Get-Command codex，macOS/Linux 用 command -v codex，核对安装位置与 PATH。
登录成功却运行失败：先区分账户额度、模型访问和本地命令失败，保存具体错误，不反复安装。
Python 找不到：这是项目运行时缺失，不是模型未理解需求；确认 python3 --version 或 py -3 --version。
WSL 中找不到 Windows 安装：回到实际工作的终端检查，别把两个系统的 PATH 当成同一份。
测试没运行却说完成：要求报告运行命令、退出状态和未完成原因；一段"应该通过"的文字不是执行结果。

下一次可以只加一个需求：增加 --output 参数，把结果写到一个新文件。保持原始输入不变，再补成功和失败两条验收；这样才能逐步形成可复用工具。