Codex CLI 新手实战：从登录到跑通第一个任务，附高频报错排查

装完 Codex 之后的第一个小时，往往比安装过程更让人迷茫。我见过太多人卡在同一个地方：命令敲下去了，终端也出现了对话界面，但接下来不知道该对这个工具说什么、能从它手里安全地接过什么样的任务。这篇文章就是写给这批人的——从登录、建目录、跑通第一个任务开始，把 Codex 当成一个真实的结对程序员来用，而不是当成一个高级聊天框。

1. 装完 Codex 之后的第一件事：登录与 CLI 快速自检

安装本身没什么可讲的，一条 npm 命令或者官方脚本装完， codex --version 能输出版本号就算过关。真正的分水岭在登录环节，这一步决定了你后面的所有操作是顺畅还是反复报错。

1.1 登录逻辑：为什么绑定 ChatGPT 账号还不够

Codex 的登录方式和你想的不太一样。它不是简单地"登录 ChatGPT"，而是要通过 CLI 触发一个设备授权流程。你在终端输入 codex login ，会看到一个 URL 和一个一次性代码，打开浏览器完成授权后，CLI 会自动拉取一份 API 凭证存到本地。

这里有个新手很容易误解的点：Codex 默认使用的是你 ChatGPT 订阅里包含的额度，它在后端走的是 ChatGPT 的账号体系，而不是单独的 API key。所以如果你的 ChatGPT 账号本身没有可用的订阅，或者网络环境连不上授权页面，登录就会卡在"正在重新连接"这种状态。我见过很多人以为是自己命令敲错了，其实只是账号侧没有准备好。

登录成功的标志有两个：一是终端出现类似 "You are logged in" 的明确提示；二是执行 codex 进入交互模式后，界面上不再弹出登录引导。如果出现反复的登录循环，先检查账号订阅状态，再检查终端是否需要科学的上网环境。这两种情况我都遇到过，前者换个账号就解决，后者属于本地网络链路问题，不是工具本身的问题。

1.2 登录后必做的环境自检清单

登录只是第一步，我建议你不要急着敲任务，先花两分钟做一个环境自检。你可以把下面这段内容直接复制进终端执行：

codex --version
codex login status
codex exec "ping"

第一条命令确认版本号，第二条确认登录状态，第三条是测试 Codex 能不能正常发起一次最小的模型调用。注意第三条里的 exec 子命令，它和交互模式不同，是让 Codex 直接执行一句话任务然后退出，非常适合做连通性测试。如果这三条都通过，说明 CLI 安装、账号授权、网络链路全都没有问题，可以放心进入下一个阶段。

还有一个新手容易忽略的点：Codex 支持在项目目录下存放一个 AGENTS.md 文件，这个文件相当于给 Codex 的项目级"工作手册"。如果你刚登录完就急着干活，可以先不创建它，但我在后面的章节会详细讲它的价值——尤其是当你的项目开始变得复杂时，有没有这个文件，效果差距非常明显。

2. 创建项目：从空目录到让 Codex 理解上下文

新手最常见的用法是：打开终端，随便进一个目录，然后输入 codex ，开始对话。这种方式在小 Demo 里没问题，但一旦任务稍微复杂一点，Codex 就会频繁给出无关建议，甚至反复修改错误文件。原因很简单——你没有给它一个明确的"项目上下文"。

2.1 项目目录的两种起手式

我推荐两种起手式，你根据自己的情况选一种。

第一种是 从空目录开始 ，适合做一个全新项目。命令是这样：

mkdir my-first-codex-project
cd my-first-codex-project
codex

进入交互模式后，第一句话建议是"初始化一个 Python 项目，包含 README、src 目录和 pytest 测试框架"，而不是直接说"帮我写个计算器"。原因在于，Codex 在空目录里会主动创建合理的目录结构，这是它的强项，你得先给它一个"框架级"的指令，它才有机会展示这个强项。

第二种是 在已有代码仓库里工作 ，适合接手一个你不熟悉的项目。进到仓库目录后，直接 codex 就行。它默认会把当前目录作为工作区，能读取项目里的文件结构、依赖清单、配置文件，甚至 git 历史。但这里有一个非常关键的细节：Codex 的上下文窗口是有限的，项目越庞大，它"遗忘"前面信息的概率就越高。

2.2 如何把"项目背景"传给 Codex

很多人忽略了一个事实：Codex 默认只"看"你发给它的命令和它自己探索到的文件，但它并不知道这个项目为什么要存在、目标用户是谁、有哪些不能破坏的约定。

举一个真实例子。我让 Codex 给一个旧项目加一个导出功能，它直接改了核心模块的公共接口，导致其他三个模块全部报错。问题不在于它能力不行，而在于它不知道"这个接口被外部依赖，不能动"这条隐含约定。

解决方式分两层。第一层是在对话开始时把关键约束讲清楚，比如"现有接口保持兼容，只新增函数"；第二层就是前面提到的 AGENTS.md 文件。这个文件可以放在项目根目录，Codex 每次进入交互模式时会读取它作为长期上下文。我建议你在这个文件里写清楚以下内容：

• 项目是干什么的，面向哪些用户
• 技术栈、关键依赖、可用的构建命令
• 代码风格约定和禁忌（比如"不要修改 migrations"）
• 常用操作指令（怎么跑测试、怎么起开发服务器）

2.3 我建议的 AGENTS.md 写法

拿一个 Python 服务举例，一个能真正帮到 Codex 的 AGENTS.md 长这样：

# 项目概述
这是一个处理订单导出的后台服务，输入是订单 ID 列表，输出是 Excel 文件。

# 技术栈
- Python 3.11 + FastAPI
- 数据库：PostgreSQL（通过 SQLAlchemy 访问）
- 测试：pytest + httpx

# 常用命令
- 启动开发服务：uvicorn app.main:app --reload
- 运行全部测试：pytest
- 代码格式化：ruff format .

# 关键约束
- 不要修改 app/db.py 里的现有连接逻辑
- 修改数据库 schema 时必须同时提供迁移脚本
- 导出的 Excel 文件必须保留原有列顺序

这份文件写完之后，你再启动 Codex 干活，它给出的方案会明显"更懂你"。很多人把 Codex 当成一个没有记忆的对话窗口用，遇到上下文不够就反复解释，这是对工具的浪费。 AGENTS.md 就是你给 Codex 植入的长期记忆，值得花十分钟写好。

3. 下发第一个真实任务：提问、审查与验收的完整闭环

环境通了，目录建好了，接下来是最核心的部分——怎么让 Codex 从"能聊天"变成"能干活"。这个环节最考验你对任务拆解的能力，而不是 Codex 本身的能力。

3.1 新手最容易犯的提示词错误

我先说三个我见过最多的错误，你看自己有没有踩过。

第一个错误是 任务描述过于宏大 。比如"帮我做一个购物网站"，这种需求对 Codex 来说无从下手，它要么只给你一个空壳，要么生成一堆你根本跑不起来的半成品。正确的做法是把任务拆成可验证的小步骤，比如"先搭建一个 Flask 应用，提供商品列表的 JSON 接口，用内存数据，不需要数据库"。

第二个错误是 不告诉 Codex 输出标准 。你光说"写一个函数"，它可能给你返回一个只有五行的伪代码，也可能写一个一百行还带大量类型注解的完整实现。你会觉得它不稳定，其实是你的指令缺少验收标准。比较稳妥的指令格式是"用 X 语言写一个函数，完成 A 功能，输入是 B，输出是 C，边界情况考虑 D"。

第三个错误是 完全不做审查 。许多新手把 Codex 当成交钥匙的人，让它写什么就直接复制粘贴运行。结果就是一个小小的隐藏 Bug 能让你排查两小时。正确的心态是：Codex 是替你快速生成初稿的工程师，但代码审查人的角色始终是你自己。

3.2 一个从零到可运行的计算器任务

我们用一个真实可复现的例子来走完整个闭环。目标：在空目录里做一个支持加减乘除的命令行计算器，用 Python 实现，包含测试。

你可以在 Codex 交互模式里这样输入：

初始化一个 Python 项目，实现命令行计算器，支持加、减、乘、除四个操作。
要求：
1. 命令行参数格式为：python calculator.py 3 + 5
2. 除法需要处理除数为 0 的情况，给出明确报错
3. 代码放在 calculator.py，测试放在 test_calculator.py
4. 测试使用 pytest

注意我给的不是一句话，而是带着明确边界条件的命令。Codex 会依次完成创建文件、写代码、写测试这几个动作。你不需要打断它，等它结束之后，先看它生成的代码再运行。

这是一个我实际跑过的结果片段， calculator.py 的核心逻辑通常长这样：

import sys

def calculate(a: float, b: float, op: str) -> float:
    if op == "+":
        return a + b
    elif op == "-":
        return a - b
    elif op == "*":
        return a * b
    elif op == "/":
        if b == 0:
            raise ValueError("除数不能为 0")
        return a / b
    else:
        raise ValueError(f"不支持的运算符: {op}")

if __name__ == "__main__":
    if len(sys.argv) != 4:
        print("用法: python calculator.py <数字> <运算符> <数字>")
        sys.exit(1)
    a = float(sys.argv[1])
    op = sys.argv[2]
    b = float(sys.argv[3])
    result = calculate(a, b, op)
    print(result)

然后运行 pytest ，正常情况下测试会全部通过。如果没有通过，你要做的不是自己改代码，而是把错误信息原封不动地复制给 Codex，让它自己修复。这其实是 Codex 最实用的一个工作流——它写的代码，它自己知道上下文，修起 Bug 来比你看半天再手动改要快得多。

3.3 怎么验收一个工具生成的代码

验收环节我给你三条实用经验。

第一， 一定要自己跑一遍关键路径 。Codex 写的代码可能是对的，但你能保证它跑出来的输出真的符合你的预期吗？命令行计算器的例子很简单，但换到真实项目里，你必须自己执行一遍完整流程，而不是看到"文件创建成功"就放心。

第二， 要求 Codex 写测试，不是可选项 。我见过很多人让 Codex 生成一个功能，但没让它写测试，结果后来改功能时根本没有回归保障。你在最初的任务描述里就把"写测试"作为交付标准，后面会省很多事。

第三， 大胆让 Codex 解释自己的代码 。如果某一段逻辑你没看懂，直接问"为什么要这么写？有没有更简单的方案？"它会给出解释，甚至主动重构。工具生成的代码不是黑盒，你越追问，后面接手就越顺畅。

我当时从安装跑到这里，总共花了大概二十分钟。你第一次跑应该也差不多，慢一点也正常。

4. 高频报错的实操排查链路

跑通第一个任务绝对不等于后面一帆风顺。我整理了几个新手最常碰到的报错，把排查思路完整写出来——不是给你一个直接答案，而是让你学会自己判断问题出在哪一层。

4.1 "model is not supported"：模型配置残留问题

报错信息大致长这样：

The 'gpt-5.6-sol' model is not supported when using Codex with a...

翻译成人话就是：当前配置文件里指定了一个 Codex 后端不认得的模型名。

这个报错最常见的来源是配置文件残留。你以前可能手动改过 ~/.codex/config.toml ，或者参考某个教程往里面填过模型参数，这些参数在 Codex 升级之后就可能失效。排查链路如下：

1. 打开配置文件： cat ~/.codex/config.toml
2. 找到 model 或 model_provider 相关字段
3. 把不认识的模型名改回官方默认值，或者直接注释掉
4. 保存后退出 Codex，重新启动

大多数情况下，清理掉自己加的模型参数就能解决。Codex 每隔一段时间会有新模型上线，网上教程里的配置很容易过时，遇到这类问题优先怀疑本地配置，而不是怀疑安装包损坏。

4.2 "Codex ran out of room in the model's context"：上下文塞太满

这个报错的信息量很直白——模型上下文窗口被填满了。

Codex 在干活的时候，会不断把读到的文件内容、命令输出、你的对话历史都塞进上下文中。当项目文件特别大，或者对话延续了很久之后，它就会提示没有空间了。

我自己的排查思路是这样的：先判断是单次任务太大，还是对话历史太长。

如果是单次任务太大，比如你让它"读取整个项目并重构"，它需要在上下文里装太多文件。解决方法是把任务拆小，一次只处理一个模块，或者用 AGENTS.md 把最关键的项目信息提前固话，减少它现场读文件的压力。

如果是对话历史太长，最简单的办法是开启一个新的会话。Codex 不会保留上一个对话的记忆，但重新开始的会话会重新加载 AGENTS.md 的核心信息，所以之前固化好的项目约束不会丢。

4.3 "cc switch local proxy failed while handling codex endpoint /responses"：本地链路问题

这个报错是很多人的噩梦，一串长英文，还有一个 "local proxy" 的关键词。我看到网络上有不少人在搜这个问题，也看到很多没营养的复制粘贴回答。

先说结论：这个报错通常不是你 Codex 本身的问题，而是本地有一个"中间层"在处理 Codex 的请求时出错了。你机器上可能有其他软件改过环境变量，或者存在残留的本地服务配置，Codex 默认试图通过 localhost 某个端口来转发 /responses 这个 API 请求，结果那个端口上的服务不认这个请求。

排查链路我建议按顺序走：

1. 检查环境变量： env | grep -i openai ，看有没有 OPENAI_BASE_URL 或者类似的变量指向本地端口。如果有，先把它清掉，然后新开一个终端窗口再启动 Codex。
2. 检查本地监听端口： lsof -iTCP:5678 -sTCP:LISTEN （或者你环境变量里指向的端口），看是哪个进程占用了这个端口。如果是某个别的软件占用，那你应该动的是那个软件的配置，而不是 Codex 的。
3. 重置 Codex 配置：把 ~/.codex/config.toml 里和 base URL、proxy 相关的自定义字段注释掉，让 Codex 走默认配置。
4. 最后才考虑重装。我见过很多人一遇到问题就卸载重装，其实绝大部分报错都是环境变量和残留配置导致的，重装解决不了根本问题。

要特别注意一点：如果你发现这个报错和当前网络环境有绑定关系，换了一个网络环境就不报错了，那说明 Codex 请求链路上某个环节依赖特定网络条件。这种情况不在本文的讨论范围内，你能做的是保证运行环境干净、配置默认、依赖全装好，这是最稳妥的用法。

4.4 登录卡在"正在重新连接"

这个也是高频问题。有些人是首次登录就卡住，有些人是用到一半突然掉线。

我的排查经验是：先看账户状态，再看本地配置。如果 ChatGPT 账号订阅可用，网络无异常，那问题大概率出在本地凭证文件损坏。你可以退出登录再重新登录一次：

codex logout
codex login

如果你装了多个版本的 Codex 或者用过其他 OpenAI 系工具，凭证文件冲突也可能导致这个问题。Windows 用户还比较容易碰到安装不完整的情况，尤其是杀毒软件拦截了部分文件。遇到这种情况，以官方安装文档为准，先把旧版本清理干净再装。

5. 进阶配置：换模型、接入兼容后端与工作流打磨

基础跑通之后，你会发现 Codex 的默认配置未必是最适合你的。尤其是当你同时使用多个模型服务商的时候，配置层面的灵活性决定了你用得顺不顺手。

5.1 通过 config.toml 切换到 DeepSeek 等兼容后端

Codex 内置的模型是 OpenAI 系的，但它的 CLI 架构设计得很开放，支持通过修改 ~/.codex/config.toml 切换到底层模型服务。

我拿接入 DeepSeek 来举例。DeepSeek 提供和 OpenAI 兼容的 API 格式，所以你不需要改 Codex 的代码，只需要改配置。步骤很简单：

1. 在 DeepSeek 开放平台申请 API key
2. 打开 ~/.codex/config.toml
3. 添加模型提供商配置：

model = "deepseek-chat"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

4. 在环境变量里设置 DEEPSEEK_API_KEY （或者直接在终端 export DEEPSEEK_API_KEY=你的key ）
5. 重启 Codex

切换之后，Codex 的对话界面、文件操作逻辑、命令执行能力都不变，变的只是底层模型。这个设计对国内开发者来说很实用，因为网络链路和计费策略都有明显差异。

我用过一段时间 DeepSeek 后端之后，一个切身体会是：不同模型在 Codex 里的表现差异挺大。有些模型代码生成质量高但执行指令时比较"谨慎"，有些模型速度极快但偶尔会漏掉你要求的一部分约束。所以建议你在项目里固定一个模型，不要频繁切换，否则你很难判断"这次的 Bug 是模型导致的还是我指令写得不清楚"。

5.2 一些值得设置的配置项

除了模型切换之外，下面这几个配置项可以说是我日常使用频率最高的，建议你根据自己的需求加到 config.toml 里：

# 自动同意执行命令，不用每次都手动确认
auto_accept = true

# 保存在对话中的最大消息数
max_conversation_turns = 20

# 启用代码权限校验，防止它改到不能改的文件
sandbox_file_checks = true

auto_accept 这个选项要谨慎开。它确实可以让 Codex 执行命令时不用每次都等你按确认键，效率会高很多，但风险也随之上升——如果它执行的命令里有不可逆的操作（比如删除文件、强制推代码），你来不及拦。我的建议是：本地开发环境可以开，生产环境相关操作一定不要开。

5.3 把 Codex 嵌入日常开发工作流

跑通单个任务不算完，真正提升效率的是把 Codex 嵌入到日常开发流里。我目前比较稳定的一套工作流是这样的：

• 版本管理工具是 Git，分支按功能切，Codex 只放在功能分支里，避免它直接在主干上做大规模改动。
• 每次给 Codex 派活之前，先自己把需求拆成不超过 15 分钟能完成的小块，同一时间只让它做一个任务。
• Codex 完成一个任务之后，必须跑一遍测试，再让我做一轮 code review，通过后才合并。
• 每做完一个功能，把过程中发现的项目约束补充到 AGENTS.md 里，保证长期项目越用越顺。

有一个细节很多人没留意：Codex 执行完测试之后给出的错误信息是非常有效的调试线索。你可以把这些错误信息原样复制给 Codex，它会基于自己写的代码上下文给出修复方案。这种"让 Codex 自己修自己写的 Bug"的闭环，效率惊人，比你自己一头扎进源码里排查要快得多。

6. 用了一段时间 Codex，我的真实体会与避坑建议

最后聊点实践出来的感受。Codex 这半年更新速度很快，模型能力也在持续变化，但有几个底层逻辑一直没变，也是新手最容易忽略的。

第一， Codex 是工具不是人，它对项目的"理解"完全取决于你给它的上下文 。同一个任务，你在空目录里问和在配好 AGENTS.md 的项目里问，得到的结果可能天差地别。很多人觉得 Codex 不行，其实是自己没给它提供足够的项目背景。

第二， 上下文管理是长期使用的核心能力 。代码生成质量再高，上下文塞满了也是白搭。我现在的习惯是：对话超过 15 轮就主动开新会话，必要信息靠 AGENTS.md 传递；一个大任务拆成多个小任务分多次执行，避免一次性把上下文撑爆。

第三， 能问清楚就不要猜 。Codex 所有基于猜测的行动都可能跑偏，而它在你给出清晰约束的时候表现最好。有时候为了让一条指令足够清楚，我会花几分钟写一段包含输入、输出、边界条件、禁止事项的命令。这些前置时间花得很值，因为 Codex 返工一次的成本远高于我多写几行字。

第四， 报错排查遵循"先环境后配置再代码"的顺序 。我在前面写的三个高频报错，每一个都符合这个规律。Codex 本身是个很稳定的工具，大多数问题都出在本地环境和残留配置上。遇到报错先冷静，按链路排查，不要一上来就重装。

如果你现在是第一次用 Codex，照着这篇文章走一遍，从登录到跑通第一个计算器任务再到换个模型体验一下，应该不会超过一个小时。等你把这套流程走熟了，再回头看那些让你头疼的报错，会发现它们其实都是同一类问题：不是环境变量残留，就是配置字段过时。工具本身，远比你想的耐用。