Codex CLI 使用教程：2026年从安装到上手的5步流程与6个实用技巧

摘要：Codex CLI 使用的核心链路是「安装 → 登录 → 配置 → 对话 → 自动化」五步：通过npm、Homebrew或Windows一键脚本安装，用ChatGPT账号完成授权登录，按需调整config.toml，即可在终端里让编码智能体读写本地代码。

• 安装三途径：npm全局安装、macOS Homebrew、Windows PowerShell一键脚本，前提是有Node.js 22及以上；
• 登录两方式：ChatGPT账号浏览器授权（本地回传127.0.0.1:1455）或API Key，企业环境推荐后者；
• 进阶靠config.toml：沙箱模式、审批策略、默认模型都在这里调，报错九成都出在登录回调与沙箱配置。

适用于想在终端里用自然语言驱动代码修改、重构与脚本编写的开发者与小团队。

在终端里输入一句「帮我把这个模块的报错日志改成结构化输出」，几秒钟后diff已经躺在你的工作区——这是Codex CLI 使用者的日常。作为OpenAI官方的终端编码智能体，Codex CLI把ChatGPT的代码能力直接嵌进命令行：读项目、改文件、跑命令、交diff，全程留在开发者的掌控边界内。2026年它的配置体系已经成熟，但新手最常卡住的仍是安装环境、账号授权回调和沙箱配置三个环节。

本文按教程操作型的思路，给出一份完整的 Codex CLI 使用教程：从安装到上手的流程、6个提升效率的使用技巧，以及常见报错的排查清单；团队批量部署时的网络环境问题，可参考IPdodo官网的海外AI网络方案。

一、Codex CLI 是什么：终端里的编码智能体

Codex CLI是OpenAI官方开源的终端工具，底层调用GPT系列编码模型，把「理解需求 → 浏览代码 → 修改文件 → 执行验证」整条链路封装在命令行里。

OpenAI 在 Codex CLI Getting Started 里把它定义成一个本地终端里的轻量级 coding agent。对开发者来说，它最适合的不是“替代你写所有代码”，而是接住这些高频任务：

• 快速解释一个陌生代码库。
• 批量修改重复代码或样板配置。
• 让它先给出 patch、命令或排查思路。
• 在终端里连续做问答、编辑和检查。

它和网页版ChatGPT的差异在于上下文：网页版需要你反复粘贴代码，而Codex CLI直接工作在你的项目目录，能看到完整的文件结构与报错输出，改完以diff形式提交确认。它与IDE插件的关系是互补而非替代——大规模多文件改造适合终端，单文件补全留在编辑器里更顺手。

二、安装 Codex CLI：三种途径与环境准备

三种安装方式按系统选一种即可，共同前提是Node.js 22及以上版本（Windows安装包已内置运行环境，可跳过Node），这也是各类 Codex CLI 使用方式 的共同起点：

装完在终端执行 codex --version 有版本号返回即成功。npm方式最常见的坑是装完提示 command not found：通常是npm全局目录不在PATH里，执行 npm config get prefix 拿到路径，把它加进系统环境变量即可；macOS上若权限不足，换nvm管理Node版本是最省心的解法。

三、Codex CLI 登录与配置：账号授权、API Key 与 config.toml

登录与配置是Codex CLI 使用指南里最常被跳过的部分。登录方式二选一。

个人用户执行 codex login，浏览器会弹出ChatGPT账号授权页，授权成功后回调到本机 http://127.0.0.1:1455 完成握手，Plus与Pro账号的额度直接沿用订阅额度。Windows上若回调报 os error 10013（端口被保留），以管理员身份执行 net stop winnat 再 net start winnat 释放端口即可。

团队或CI环境不方便弹浏览器，改用 codex login --api-key 粘贴API Key，密钥写进环境变量而不是脚本里。

配置文件位于用户目录下的 ~/.codex/config.toml，几个高频项：

建议从 read-only 加 on-failure 的组合起步：Codex可以读全部代码、跑只读命令，写文件和执行命令前必须经你确认，误操作的风险被锁在最小范围。等流程跑顺了，再对可信项目放开到 workspace-write。

四、Codex CLI 使用技巧：6个进阶用法

掌握基础对话之后，这6个用法能明显提升效率：

1. 用斜杠命令控场：会话中输入 /status 看额度与配置、/model 切模型、/diff 审改动、/quit 退出，不用记外部命令；
2. 会话续接：中断的任务用 resume 子命令找回历史会话，长任务跨天继续不用从头解释背景；
3. 非交互执行：codex exec “跑一遍测试并修复失败用例” 适合写进CI或定时任务，输出直接落日志；
4. 给任务带上下文：启动时把需求文档、接口约定放进项目里的AGENTS.md，Codex每次会话自动读取，减少重复说明；
5. 分步审批复杂改造：大改动拆成「只读分析 → 出方案 → 再执行」三轮对话，每轮确认后再推进，返工率显著下降；
6. 多项目隔离配置：不同仓库放不同的config.toml覆盖项，测试项目放开沙箱、生产仓库保持只读，互不干扰。

如果你本身也在对比 Codex、Gemini CLI 或其他命令行代理，已发布的 Codex怎么用？从CLI、IDE到云端任务的上手说明 可以一起看，它更适合从整体产品视角理解 Codex 的定位。

五、常见问题解答（FAQ）

Codex CLI 使用需要付费吗？

是否产生费用取决于登录方式。使用 ChatGPT 账号登录时，Codex 的使用量受当前订阅方案及额度限制；使用 API Key 登录时，则按照 OpenAI API 的标准价格计费。可在 Codex CLI 中运行 /status 查看当前会话的使用情况，具体规则以 OpenAI 官方价格页面为准。

Windows 上怎么安装 Codex CLI？

Codex CLI 支持在 Windows 原生环境或 WSL 中运行。由于安装方式可能随版本调整，建议按照 OpenAI 官方 Codex CLI 文档提供的当前步骤安装，不要执行来源不明的一键脚本。安装完成后，可运行 codex --version 检查是否安装成功。

Codex login 后浏览器回调失败怎么办？

Codex 的浏览器登录流程需要通过本机 localhost 完成回调。失败时可先检查防火墙、安全软件、代理设置以及本地端口是否被占用，然后重新运行 codex login。如果浏览器回调仍无法完成，可以尝试 codex login --device-auth，或按照官方文档使用 API Key 登录。运行 codex login status 可以查看当前登录状态。

Codex CLI 的 config.toml 在哪里？

个人配置文件默认位于 ~/.codex/config.toml，Windows 对应路径通常为 %USERPROFILE%\.codex\config.toml。如果文件不存在，可以自行创建。项目目录还可以使用 .codex/config.toml 设置项目级配置，具体生效范围取决于项目的信任状态和配置优先级。

Codex CLI 频繁出现 Reconnecting 是什么原因？

Reconnecting 通常与网络抖动、代理配置、TLS 检查、长连接中断、服务状态、CLI 版本或登录状态有关，并不能仅凭这一提示判断是出口 IP 风控。建议先更新 Codex CLI、检查 OpenAI 服务状态与登录状态，再测试其他稳定网络并查看日志。稳定的网络链路有助于减少重连，但不能解决账号额度或服务端故障。

相关文章推荐

	Codex 一直 Reconnecting 怎么办？2026年Codex Reconnecting连接失败原因与解决方法
	Selected model is at capacity 是什么意思？2026年Codex模型爆满的4类原因与3套恢复方案
	Codex 地区不支持怎么办？2026 年原因排查与跨境访问解决方法

总结

Codex CLI 使用的学习曲线集中在开头一小时：装好Node环境、选对安装方式、完成账号授权、把config.toml的沙箱与审批调到舒服的位置，之后就只剩「怎么把需求描述清楚」这一件事。记住两条主线——权限从紧到松逐步放开，任务从大拆小逐轮确认——再配一条稳定的跨境网络，它就能从尝鲜工具变成日常生产工具。