Codex CLI 实操全指南零基础入门到高阶精通

Codex CLI 是 OpenAI 推出的终端代码智能代理工具，支持本地读取文件、自动修改代码、执行 Shell 命令，还能对接多厂商大模型，打通终端开发全流程，熟练掌握这套工具可以把代码编写、项目重构、BUG 排查效率提升一倍以上。当下后端开发、脚本开发、项目运维都离不开终端环境，传统代码助手只能在编辑器内运行，无法直接操作本地目录与系统命令；Codex CLI 原生运行在终端，具备文件读写、命令执行、多轮代码迭代三大核心能力，还支持权限分级、模型切换、会话持久化，适配单机开发、CI 自动化流水线等多种场景；先完成环境部署与账号登录，再掌握基础交互命令，接着配置权限与模型参数，最后学习多智能体、批量任务、Git 联动等高阶用法，循序渐进完成从入门到精通的全部学习流程，把 AI 编码能力完整嵌入终端开发工作流。

一、基础环境部署（入门阶段）

1. 系统硬件与软件要求

表格

2. 三种主流安装方式

1）npm 全局安装（跨平台首选）

npm install -g @openai/codex

codex --version

2）Homebrew 安装（macOS 专用）

brew install --cask codex

codex --version

3）二进制包手动部署（内网离线环境）

前往 GitHub Release 下载对应系统架构压缩包，解压后将二进制文件放入系统环境变量目录openaicli....。

3. 账号登录与身份认证

1）交互式一键登录，执行命令唤起网页授权：

codex login

2）选择【Sign in with ChatGPT】，绑定 ChatGPT 账号自动生成 API 密钥，无需手动复制密钥；

3）API 密钥自动保存在本地配置文件，路径为~/.codex/config.toml；

4）支持切换为 Azure OpenAI 密钥，手动填入 endpoint 与 api-key 即可切换服务商。

二、基础交互命令（熟练使用阶段）

1. 启动与退出会话

• 直接启动：进入项目目录，直接输入codex进入交互式对话窗口；
• 单次执行指令：无需进入会话，直接在终端执行单行任务：codex 帮我优化这段Python脚本的运行效率；
• 退出会话：输入/exit即可结束当前对话，自动保存会话记录。

2. 内置斜杠指令清单

1）会话管理：/clear清空当前对话上下文；/fork克隆当前会话分支，用来并行测试不同代码方案；

2）权限控制：/approvals切换运行权限模式；

3）模型切换：/model切换当前调用的大模型；

4）系统诊断：codex doctor一键检测网络、权限、依赖、配置全部问题，自动给出修复方案OpenAI。

3. 三种权限运行模式（核心安全配置）

1）Auto 自动模式（默认）：仅允许读取、修改当前工作目录内文件，执行本地命令；访问外网、操作上级目录必须手动确认；

2）Read Only 只读模式：仅能读取代码文件、分析代码逻辑，禁止修改文件、运行任何系统命令，适合纯代码评审场景；

3）Full Access 完全权限：无人工确认，可读写全目录文件、联网调用接口、执行系统命令，仅在隔离测试环境开启，保障本地设备安全。

三、核心配置深度优化（进阶阶段）

1. 配置文件详解

配置文件路径：~/.codex/config.toml，可自定义修改以下参数：

1）model：指定默认调用模型，支持 gpt-6-astra、o4-mini 等多款编码专用模型；

2）reasoning：推理等级，分为 low/medium/high，复杂架构重构开启 high 高推理档位；

3）token_limit：单次上下文 token 上限，防止超长代码库触发超限；

4）workspace：锁定默认工作目录，限制智能体仅在指定项目文件夹内操作。

2. 多模型切换配置

1）OpenAI 官方模型：直接使用账号授权，无需额外配置；

2）Azure OpenAI 模型：在配置文件填入 azure_endpoint、azure_api_key、azure_deployment 三项参数；

3）本地离线模型：对接 Ollama 本地大模型，修改接口地址为本地localhost服务地址，实现离线 AI 编码。

3. 会话持久化管理

• 自动保存每一轮对话，所有历史会话存放在~/.codex/sessions文件夹；
• 使用/load 会话ID可以随时调取历史对话，继续完成未做完的开发任务；
• 支持将会话导出为 JSON 文件，实现多设备之间迁移对话记录。

四、高阶实战能力（精通阶段）

1. 多智能体协同开发

1）开启多 Agent 模式，自动拆分任务：架构设计、代码编写、单元测试、BUG 检测由不同子智能体分工完成；

2）使用/spawn命令创建子任务分支，主任务负责整体方案，子任务并行开发多个功能模块；

3）支持多任务并行执行，互不干扰，适合大型项目模块化开发OpenAI。

2. 与 Git 工作流深度联动

1）自动读取当前 Git 分支、代码变更记录，基于 diff 内容做增量代码修改；

2）一键生成规范 Commit 注释，自动格式化提交信息；

3）自动创建临时分支做代码实验，验证通过后再合并到主分支，避免污染主干代码。

3. CI 流水线自动化集成

1）在 GitHub Actions、Jenkins 中部署 Codex CLI，自动完成代码静态检查、自动修复语法问题；

2）批量扫描项目代码，自动补全单元测试用例；

3）设置只读权限运行，只做代码评审，不修改线上生产代码，保障流水线安全稳定。

4. 终端批量脚本处理

1）批量遍历项目下所有源码文件，批量优化代码格式、统一编码规范；

2）自动生成 Shell、Python、Bash 运维脚本，直接在终端一键执行；

3）批量生成接口文档，读取项目代码自动输出 Markdown 格式接口说明。

五、日常使用最佳实践

1）项目启动前先锁定工作目录，开启 Auto 权限，避免智能体越权修改系统文件；

2）小型代码调试使用 medium 推理等级，节省 token 开销；大型架构重构切换到 high 高推理模式；

3）每次重构代码前先执行/fork新建会话分支，测试方案失败随时丢弃分支，不破坏原有对话上下文；

4）定期执行codex doctor检查网络连通性、模型调用配额、目录权限，提前规避运行异常。

【相关 FAQ】

问题 1：Codex CLI 从入门到精通，在 Windows 系统下要如何正常运行？

回答 1：Codex CLI 从入门到精通，Windows 原生终端不支持运行，必须先开启 WSL2 Linux 子系统，在子系统终端内完成安装与启动，同时可以通过 codex doctor 命令自动排查 WSL 环境配置问题OpenAI。

问题 2：Codex CLI 从入门到精通，一共有哪三种权限运行模式，默认模式是什么？

回答 2：Codex CLI 从入门到精通，一共包含 Auto 自动模式、Read Only 只读模式、Full Access 完全权限模式；软件默认启用 Auto 自动模式，仅可操作当前项目目录，跨目录与联网操作需要人工确认，兼顾实用性与安全性。

问题 3：Codex CLI 从入门到精通，如何在工具内切换 Azure OpenAI 私有模型？

回答 3：Codex CLI 从入门到精通，打开本地~/.codex/config.toml配置文件，填入 azure_endpoint、azure_api_key、azure_deployment 三项参数，保存配置后执行/model指令，即可切换调用 Azure 部署的大模型，实现私有化接入Microsoft ...。

问题 4：Codex CLI 从入门到精通，如何把 AI 编码任务接入 CI 自动化流水线？

回答 4：Codex CLI 从入门到精通，在 CI 配置文件中全局安装 Codex CLI，会话开启 Read Only 只读模式，仅用来自动检查代码、生成测试用例，不开启文件写入权限，保证流水线运行安全，实现自动化代码质检。

【数据来源】

[2026-10-19]（Customer guide: Using Daybreak in Codex CLI）OpenAI 帮助中心

[2026-10-08]（在你的 ChatGPT 套餐中使用 Codex）OpenAI 官方文档

[2026-09-24]（Codex CLI with Azure OpenAI）Microsoft Learn

[2026-09-05]（Codex CLI 安装与版本兼容说明）Microsoft Azure 文档

[2026-05-16]（Codex CLI 账号登录授权流程）OpenAI 产品手册

免责声明：本文仅为 Codex CLI 工具技术实操文档整理，不构成商业开发、线上生产环境部署的最终方案；模型调用额度、接口稳定性、功能更新均以 OpenAI 官方最新公告为准；在生产服务器启用 Full Access 权限前，请做好环境隔离与安全审计，规避文件越权修改风险。