Appearance
最后更新时间：2026 年 10 月 24 日
Codex CLI 终端教程 2026：安装、登录与本地代码任务实战
Codex CLI 是 OpenAI 的本地命令行编程智能体。它在终端中运行，围绕当前项目读取和修改代码，也能按所选权限运行命令。它适合已经用终端和 Git 管理项目的人；不熟悉 shell 的用户可以考虑桌面应用或 IDE 扩展。本文按官方仓库和文档整理安装、登录与第一次任务流程。系统支持和命令可能随版本变化，安装前请再次查看官方说明。
国内中文入口：AIMI 和 AIBox
安装 CLI 前，如果只是想问代码概念、解释报错或准备任务描述，可以使用 AIMI 或 AIBox 进行中文问答。两者均为第三方 AI 服务，并非 OpenAI Codex CLI 官方入口，也不能据此假定它们拥有本地文件权限、终端执行能力或同一套账号与额度。是否可用某个模型和功能，以平台当前页面为准。不要把密钥、私有仓库或生产日志直接贴入外部服务。
系统要求与安装前确认
OpenAI Codex 仓库当前列出的 CLI 支持平台包括 macOS 12 及以上、Ubuntu 20.04+/Debian 10+ 等 Linux，以及通过 WSL2 使用的 Windows 11。仓库列出最低 4 GB 内存、推荐 8 GB；Git 不是基本启动所必需，但仓库工作和 PR 辅助功能中很有用。产品版本可能扩展支持范围，请以安装时官方文档为准。
安装之前先确认终端可运行 git --version，知道项目目录，且系统架构和包管理工具与安装方式匹配。若用 Windows，先安装并打开 WSL2。官方仓库对 CLI 的 Windows 支持说明是通过 WSL2；如果在 PowerShell、WSL 和 VS Code Remote 中混合操作，应核实实际工作目录和文件系统位置。
官方安装方式
官方仓库提供独立安装脚本，也支持 npm 和 Homebrew。macOS/Linux 可用命令：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
若本机已安装 Node.js/npm，官方仓库的另一种方式是：
npm install -g @openai/codex
使用 Homebrew 的 macOS 用户也可以运行：
brew install --cask codex
Windows 11 通过 WSL2 使用时，按官方页面的当前指引在 WSL 环境安装。官方仓库也列有 PowerShell 安装命令；安装前要核对支持说明和命令来源，不要复制论坛里来历不明的镜像脚本。
安装完成后运行 codex 检查是否启动。若提示找不到命令，先检查安装器输出和 PATH，再重开终端；不要立刻重复安装多个版本。可通过包管理器查询已安装版本，并按同一安装来源更新，以免系统里出现多个同名可执行文件。
脚本安装方便，但它会下载并执行安装内容。对企业设备或受管环境，优先使用组织批准的安装流程；需要检查脚本时可以先下载查看，再按官方文档执行。不要通过聊天群、网盘或短链接获取所谓“国内加速版”二进制。
首次启动与登录
在可信终端里输入 codex，根据界面选择登录方式。官方仓库建议个人用户通过 ChatGPT 账号登录，将 Codex 纳入符合条件的 ChatGPT 计划；也可以使用 API Key，但需要额外配置，并按 API 方式计费。账号可用性、计划内容和使用限额会变化，应查看官方计划说明，不要用旧教程推断当前权益。
Codex 登录成功只表示身份认证通过，不代表当前项目的每个操作都会自动执行。命令审批、沙箱和网络规则受配置与产品版本影响。遇到审批提示时先读完整命令及工作目录，判断它会读取、覆盖、删除或上传什么，再决定是否放行。不要把登录令牌复制到项目文件、命令行参数、截图或公开日志中；共享电脑上使用完成后退出账号，也要确认 shell history 没保存 API Key。
在正确的项目目录中启动
使用 CLI 的关键是让它从正确目录理解上下文。先进入仓库，确认状态和文件，再运行 codex：
cd path/to/project
git status
codex
路径请换成你自己的项目目录。启动后可以先要求它总结项目结构和测试入口，不要马上修改：
请先阅读项目说明与目录结构，概括主要模块、开发启动方式和测试命令。暂时不要修改文件；如果说明文件里没有相关信息，请标出来。
如果总结中的文件路径不存在，就修正上下文，确认它确实读到了目标仓库。CLI 不会自动知道你的意图；工作目录、分支、项目说明和任务条件共同决定它看到什么。
第一个任务：小范围修复并验证
挑一个可复现、影响范围小的问题。任务描述可以按下面格式写：
现象：用户在资料页保存昵称后，刷新页面会看到旧值。
目标：修复昵称保存或加载逻辑。
范围：先检查资料页、相关 API 调用和已有测试；不要变更后端接口。
验收：新增覆盖刷新场景的测试，运行相关测试并报告命令与结果。先说明计划，若确认需要改接口请暂停。
第一轮最好让 Codex 先解释计划和相关文件。计划合理后再让它实现；完成后读 diff、确认修改范围、运行测试并手工复现。测试不通过时把完整错误给它，让它解释现象，不要只说“继续修到绿”。这样能减少为了通过测试而删除断言或放宽校验的情况。
CLI 特别适合接收终端命令输出。遇到失败时提供命令、错误全文、运行目录和版本信息。删除环境变量、数据库内容或重置 Git 状态都可能造成损失，不要让模型在未确认的情况下执行破坏性命令。涉及部署、推送或生产数据的任务，应单独确认目标和影响。
Shell、安全与配置
Codex CLI 可以执行命令，因此任务前要了解当前安全模式、审批要求和允许访问范围。不要因为命令看上去简短就跳过检查，例如删除目录、安装系统包、写入全局配置、访问生产服务或上传文件的命令都需要知道副作用。
对代码仓库任务，保留 Git 工作区和分支作为恢复手段。让模型先读再改；在共享环境里，不要让它执行未经审阅的 sudo、数据库清空、密钥轮换或发布命令。即使有沙箱和审批机制，也要把它们当作降低风险的控制措施，而不是不检查输出的理由。
OpenAI 的配置和安全说明会更新。不要直接复制过时的配置字段或网络模式参数。要改变审批等级、沙箱范围、联网访问或项目级设置时，先查官方配置文档，理解每项设置影响哪些目录与命令。多人项目可以把共同约束写进开发说明，但不要把个人令牌放入仓库。
常见故障排查
命令找不到： 检查安装是否成功、当前 shell 的 PATH 和是否打开了新终端；用包管理器确认是否装了多个版本。
登录打不开或认证失败： 检查官方登录状态、默认浏览器和组织账号策略。不要把 OAuth URL、回调内容或令牌发给陌生人排查。
在错误目录运行： 先终止当前任务，检查当前路径、Git 根目录和分支，再到正确项目重新启动。不要假设 CLI 自动知道哪个窗口是目标项目。
命令需要审批： 查看命令完整文本、路径和影响，特别关注删除、覆盖、网络上传和系统级操作。确认不了就拒绝并要求模型解释替代方案。
测试命令无法运行： 让它先阅读 README、package.json、pyproject.toml 或项目实际配置，不要根据常见框架猜命令。
CLI 实战：从 issue 到可审查补丁
一个适合练习的流程是先把 issue 原文保存下来，再在仓库根目录启动 Codex。第一轮只要求它确认复现条件、相关文件和已有测试；第二轮让它提出最小修改方案，并指出哪些假设尚未验证；第三轮才允许编辑。每轮都保持目标单一，例如先修复状态保存，再考虑日志和重构。这样即使中途停止，也能留下清晰的可恢复状态。
执行命令时，要特别关注当前工作目录和环境变量。npm test、pytest 或 go test 可能读取本地配置，命令相同并不代表结果相同。可以让 Codex 在报告中写出运行目录、版本、命令和退出码；若测试被跳过、需要网络或依赖外部服务，应明确标注。遇到长时间运行的进程，先确认是否可以安全终止，避免留下占用端口或写入临时数据的后台任务。
提交前建议做三次检查。第一次用 git diff --stat 看范围，第二次用 git diff 看逻辑，第三次查看未跟踪文件和忽略规则。重点关注自动生成文件、锁文件、配置文件和删除操作。若任务涉及数据库或用户数据，要求 Codex 给出回滚方案和演练方式；如果没有可靠回滚，就把它拆成只读诊断或离线迁移。只有在负责人确认目标分支、提交内容和发布窗口后，才执行 commit、push 或部署。
终端输出怎样写成高质量反馈
给 Codex 的反馈越接近原始证据，越容易复现问题。错误信息不要只截取最后一行，至少包含命令、工作目录、关键堆栈和首次出现异常的位置。可以同时说明你期望的行为和实际行为，但把“我猜是缓存问题”标为猜测。模型需要知道哪些步骤已经做过，避免重复清理依赖或反复修改同一处代码。对于包含路径、域名和账号信息的日志，先脱敏再粘贴。
适合 CLI 的日常工作习惯
每天开始工作时先查看分支和工作区状态，把当天目标写成一条可验证的任务；结束时保存 diff、测试结果和未完成事项。若要连续处理多个 issue，为每个 issue 建立独立分支或至少分开提交，避免一个任务的失败影响另一个任务。对脚本自动生成的文件设置明确输出目录，定期清理临时文件前先确认其中没有未提交成果。长期坚持这种习惯，CLI 才能真正融入开发流程，而不是变成一个难以追踪的黑盒命令。
常见问题
Codex CLI 免费吗？
使用 ChatGPT 账号还是 API Key，适用的计划、额度和计费方式不同。OpenAI 会调整计划权益，本文不把历史限额当作当前承诺。登录前查看 Codex 计划说明；API 用户还应检查项目和组织账单设置。
CLI 和桌面版应该选哪个？
喜欢终端、需要和 Git 或脚本衔接的开发者可试 CLI；偏好图形界面、任务并行管理的用户可试桌面 App。功能和系统支持以当前官方文档为准。你也可以先安装一种，避免同时维护多套配置。
能在 Windows 命令提示符里直接使用吗？
OpenAI Codex 开源仓库当前列出的 Windows CLI 使用方式是 Windows 11 上通过 WSL2。未来版本可能变化，请根据官方安装页确认，不要把 PowerShell 安装脚本与原生 Windows 支持混为一谈。
AIMI、AIBox 能运行本地 Codex CLI 吗？
网页聊天本身不会因此获得你电脑的文件和终端权限。若某个平台另有代码执行或本地连接能力，应单独核对产品说明、权限范围、隐私和计费规则。
官方资料
命令行能让 Codex 靠近本地开发流程，也让工作目录和命令执行变得更重要。先从小任务开始，核对每次变更，再逐步增加任务复杂度，通常比一上来开放广泛权限更稳妥。