Codex 使用教程：CLI/IDE/桌面端实战

Codex 使用教程：CLI/IDE/桌面端实战

OpenAI 在 2025 年把 Codex 从「藏在 ChatGPT 里的一个功能」做成了三个独立形态：终端里的 CLI、VS Code 里的扩展、还有独立的桌面端 App。我陆陆续续用了一年多，最深的感受是：它跟过去"把代码粘进网页对话框、再把答案粘回来"的工作方式，根本不是一回事。命令能直接改你的文件，能看 diff，能自己跑测试，更像一个真正坐在你旁边动手干活的实习生，而不是一个只会说教的老师。

这篇文章打算把三个形态一次讲清楚：各自怎么启动、适合干什么、命令和交互长什么样。收尾用一个完整任务串一遍「从描述到提交」的全流程，再聊聊我用下来的技巧和限制。默认你已经装好了 Node.js 和 npm，我在 Windows + WSL 环境验证过，macOS 的命令完全一致。版本号拿不准的地方我都标了 （以官方文档为准），截图用占位符标注，你照着跑一遍就能看到预期输出。

三种形态怎么选：先看一张对比

Codex 的三种形态共用同一套账号体系，登录一次，模型权限和会话数据是打通的。差异主要在交互方式和擅长的场景上。

形态	启动方式	适合场景	交互方式	主要局限
CLI（命令行）	终端输入 codex	完整任务、批量操作、脚本化、CI 环境	文本对话 + 自动编辑文件	没有图形界面，上手有门槛
IDE 扩展	VS Code 侧边栏/命令面板	单文件小改、重构、选中代码提问	选中代码后对话框	功能比 CLI 精简，复杂任务仍要回终端
桌面端 App	独立应用	多任务并排、聊天式规划	图形窗口 + 对话	对本地项目文件的操作能力弱

我自己的用法是这样划分的：需要它「动手改代码、跑命令、反复迭代」的任务走 CLI；只是在编辑器里顺手改个函数、问一段代码什么意思，用 IDE 扩展；要做需求拆解、写方案这类「先聊天后动手」的，交给桌面端。

CLI：从安装到跑通第一个任务

CLI 是三种形态里功能最全的，官方更新也最勤。先装。

# 全局安装 Codex CLI
npm install -g @openai/codex

# 验证安装成功
codex --version
# 预期输出：codex/0.x.x（具体版本号以官方文档为准）

装完要登录。这一步会拉起浏览器，你需要在 OpenAI 账号里授权 Codex 访问你的项目。

codex login
# 浏览器弹窗出现后登录 OpenAI 账号，授权完成后回到终端按回车确认
# 预期输出：Login successful

登录后直接输入 codex 就进入交互模式，提示符是 >>>。它默认只读代码，要改文件会先给你看 diff，等你确认。

codex
# 进入交互模式，出现类似这样的提示符：
# >>>

【此处需补真实截图：codex 登录成功 + 进入交互模式的终端截图】

我实测跑的第一个任务很简单——让它在当前项目里给一个函数补 docstring：

>>> 给 src/main.py 里的 process_data 函数补一份中英文 docstring，改动尽量小

它会先读文件、分析结构，然后给出修改计划，再展示 diff。在 diff 界面里操作键是：Tab 循环切换方案，y 接受当前方案，n 拒绝跳到下一个，q 直接退出不改。确认后文件就真的被改了。

【此处需补真实截图：Codex 展示 diff、等待确认的终端截图】

除了交互模式，CLI 还支持一条命令跑完的 exec 模式，适合脚本化和 CI：

# 非交互执行，一步到位
codex exec "给 README.md 补一节「安装」说明"

# 限制它只能读文件、不能写，用于先出方案
codex exec --sandbox read-only "列出这个项目里所有未处理的 TODO"

# 全自动模式：所有修改都直接应用，不逐条确认
codex exec --full-auto "跑一下测试，把失败的用例修好"

--sandbox read-only 这个选项我日常用得多。先让它出一版方案，看完确认没问题，再放开写权限，能省不少来回。

IDE 扩展：在编辑器里小步快改

在 VS Code 扩展市场搜 “Codex”，装官方扩展，然后 Ctrl+Shift+P 打开命令面板，输入 “Codex: Sign in” 登录。

扩展的核心交互是「选中代码 → 对话」。选中一段代码后点侧边栏的 Codex 图标，或右键选择 “Ask Codex”，它只以上下文里的选中内容为准，不会像 CLI 那样读整个仓库。这既是优点也是缺点：不容易误伤别的文件，但它对项目全局的理解也弱。

【此处需补真实截图：VS Code 里选中代码调起 Codex 扩展对话的截图】

IDE 扩展适合的粒度再强调一次：改一个函数的返回值、加一段注释、把某段逻辑抽成函数，这类"改动落点清晰"的任务它非常顺手。但牵扯多个文件联动、要跑测试、要查全局依赖的活儿，扩展版容易顾头不顾尾，这时候切回 CLI 更稳。

桌面端：多任务并排的工作台

桌面端更像 ChatGPT 的界面：左侧是历史任务列表，中间是对话区，可以同时开多个任务窗口，切换互不干扰。适合做需求梳理、代码方案评审这类"写代码前"的工作，也适合聊完一个方案再导出给 CLI 落地。

【此处需补真实截图：Codex 桌面端任务列表与对话区截图】

桌面端还有个用处被很多人忽略：它可以当作"任务看板"用。一个复杂需求拆成几个子任务，分别开成独立会话，左侧列表一眼看到每个子任务的进行状态。做完一个勾一个，比在终端里来回翻记录直观。它的输出格式也更适合贴到文档或评审里。

一个完整任务：从描述到提交

下面用真实任务串一遍完整流程。场景：我维护的一个 Python 小工具，parse_config 函数读配置文件时对非法格式直接抛异常，我想让它改成"跳过坏行并打印警告"。

第 1 步，进 CLI 交互模式，把需求说清楚：

>>> 项目里 src/config_reader.py 的 parse_config 函数，现在读到非法格式会直接抛异常。
>>> 改成：跳过坏行，打印一条警告到 stderr，函数返回能解析的部分。

第 2 步，它给出计划并开始读文件。中途可以补充约束：

>>> 警告信息要带行号，格式统一成 "config line {n}: {reason}"

这一步 Codex 会先读文件、分析结构，然后给出修改计划。以 parse_config 为例，改动前后的核心逻辑大致是这样：

修改前：读到非法格式直接抛异常，整个解析中断。

def parse_config(path):
    config = {}
    with open(path, encoding="utf-8") as f:
        for line in f:
            key, value = line.strip().split("=", 1)  # 格式不对直接抛 ValueError
            config[key] = value
    return config

修改后：跳过坏行，打印带行号的警告，函数返回能解析的部分。

def parse_config(path):
    config = {}
    with open(path, encoding="utf-8") as f:
        for line_no, line in enumerate(f, start=1):
            line = line.strip()
            if not line or line.startswith("#"):  # 跳过空行和注释
                continue
            try:
                key, value = line.split("=", 1)  # 只按第一个 "=" 切分
            except ValueError:
                # 关键逻辑：坏行不中断，打印警告后继续下一行
                print(f"config line {line_no}: 缺少 '='，已跳过该行", file=sys.stderr)
                continue
            config[key.strip()] = value.strip()
    return config

几个关键点：enumerate(f, start=1) 拿到真实行号，正好对应约束里要求的 config line {n}: {reason} 格式；try/except 把「解析失败」从致命错误降级成「跳过 + 警告」，保证单行坏数据不影响其余配置；continue 让循环继续往下走，而不是整个函数崩掉。

第 3 步，看 diff，逐个确认。y 接受，n 拒绝，不满意的地方直接说"这里改成 xxx"，它会迭代。

第 4 步，让它自测：

>>> 跑一下项目里的测试，然后给我一个包含非法行的临时配置验证一下

第 5 步，验收。这一步别省——自己读一遍改动的 diff，特别是它处理边界条件（空文件、全是坏行）的逻辑。

第 6 步，提交：

>>> 帮我 commit，message 写清楚改动内容

第 7 步，push。到这里整个任务闭环。

整个过程 CLI 会改动文件、跑测试，我在旁边只负责判断"这么改对不对、意图对不对"，重复劳动基本为零。

技巧与限制

几个我在实战里摸索出来的用法：

• 用 --sandbox read-only 先出方案。复杂改动先让它只读分析、给方案，你确认方向后再放开写，避免它大动干戈。
• 任务描述越具体，结果越可控。说"改好"不如说"改成什么行为、异常怎么处理、警告格式是什么"。
• 小步确认优于一次大改。一个请求只让它做一件事，diff 好审，出问题也好回退。
• 保留 git 回退能力。让 Codex 动代码前先确认工作区是干净的，或者提前 commit，这样它改砸了 git checkout 就能回来。

限制也讲清楚。exec 模式跑复杂任务时，上下文很长，token 消耗快，账单要盯一下；CLI 会读写你的真实文件，企业项目、涉密代码慎用；Codex 用的模型版本会随官方迭代变化，行为可能跟网上教程描述的不一致（以官方文档为准）。这些不是劝退理由，但先知道比踩坑后知道好。

常见问题与排查

新手阶段问得最多的几个问题，整理成一张排查表：

现象	常见原因	处理办法
安装后提示 codex 不是内部或外部命令	npm 全局目录没进 PATH	Windows 把 %APPDATA%\npm 加进系统 PATH，重开终端再试
打开就弹登录、反复要求授权	认证状态失效，或环境变量冲突	重新执行 codex login；检查是不是 export 了跟它冲突的 API key
diff 界面不知道按什么键	快捷键没记住	界面底部有按键提示：Tab 切换方案、y/n 接受或拒绝、q 退出
长任务做到一半"失忆"	上下文窗口耗尽	让它把当前进展整理成摘要，新开会话接着干，别硬续
改动了不该动的文件	任务边界没描述清楚	描述里点名"只动哪几个文件"；复杂任务先 --sandbox read-only 出方案
生成的代码风格跟项目不一致	缺项目上下文	描述时让它先读一两个现有文件再动手，风格自然对齐
请求一直超时	代理或网络出口问题	检查 HTTP_PROXY/HTTPS_PROXY 设置，确认外网可达

其中"改动了不该动的文件"最容易让人措手不及。AI 能理解你的意图，但理解不了你没说出口的边界。写任务描述的时候，把"允许动的文件"和"禁止动的目录"都写清楚，比事后回退省太多事。我遇到过两次它顺手改了 package.json 的缩进，虽然不影响运行，但 diff 里混进无关改动，review 起来很烦。

关于费用，交互模式里能查当前会话的开销（命令名以官方文档为准）。我的习惯是复杂任务开新会话跑，别让一个会话无限续——既省 token，也避免上下文残留把后面的任务带偏。

结论

Codex 的价值不在"帮你写代码"，而在"把写代码这件事变成一个可以对话、可以确认、可以回退的过程"。日常小任务交给 IDE 扩展，完整任务走 CLI，规划类工作用桌面端，三者配合基本覆盖了我一天里绝大部分开发场景。