Codex保姆级教程（下载+安装+登录+使用，含所有版本，2026最新）

Codex作为面向开发者的AI编码助手，支持桌面客户端、CLI命令行工具、IDE插件三大版本，能够读懂项目代码结构、自动生成业务代码、重构存量脚本、排查程序BUG、生成单元测试与接口文档，适配前端、后端、脚本、容器编排等各类开发场景。借助阿里云百炼服务，Codex可以直接对接Token Plan、Coding Plan，在阿里云ECS服务器上搭建稳定的云上编码环境，非常适合团队远程开发、服务端自动化编码、批量工程改造场景。本文为2026最新保姆级教程，覆盖全部版本的下载、安装、登录认证、配置对接、日常使用、常见故障排查，配套可直接复制的命令，新手也可以一步一步完成部署上手。

一、版本区分与选型建议

Codex一共分为三大客户端版本，功能侧重点不同，大家可以根据自己的开发场景按需选择。桌面客户端Codex App，图形化界面友好，支持项目文件夹绑定、对话历史管理、可视化代码差异对比，适合新手、架构设计、需求梳理、跨文件重构；Codex CLI是命令行版本，轻量无图形依赖，可接入服务器终端、CI流水线，适合自动化脚本、批量代码处理、服务器运维编码；IDE插件版本支持VSCode、JetBrains全系列编辑器，深度嵌入开发流，在写代码时随时唤起AI补全、函数解释、漏洞修复，是日常开发最常用的版本。

三个版本底层能力一致，共享同一套密钥与模型配置文件，配置文件统一存放路径：Linux与macOS环境为~/.codex/config.toml，Windows系统在C:\Users\用户名\.codex\config.toml。在阿里云ECS服务器上部署，优先选择CLI版本，资源占用更低，不需要图形环境；本地开发电脑可以搭配IDE插件+桌面客户端组合使用。

二、阿里云ECS环境前置准备

2026年阿里云双十一活动入口：

在阿里云ECS上部署Codex CLI，推荐选用主流Linux发行版，系统需要预装Node.js 18及以上稳定版本、npm包管理器、git工具。登录服务器SSH终端，先执行环境校验命令，确认基础环境就绪：

# 校验Node与npm版本
node -v && npm -v
# 安装git（如未预装）
yum install git -y
# 创建codex配置目录
mkdir -p ~/.codex

如果Node版本偏低，可以使用nvm工具切换版本，避免安装Codex时出现依赖报错。同时需要提前在阿里云百炼控制台开通服务，创建Token Plan或者Coding Plan的API密钥，密钥只展示一次，复制保存到本地，不要直接提交到代码仓库，防止密钥泄露。

三、各版本下载与安装步骤

1. Codex CLI版本（阿里云ECS服务器首选）

CLI版本通过npm全局安装，是云上服务器最稳定的部署方式，执行安装命令：

# 全局安装Codex CLI
npm install -g @openai/codex
# 校验安装是否成功，查看版本号
codex --version
# 查看全部可用指令说明
codex --help

安装完成后，终端输入codex即可进入交互式会话。如果安装出现权限报错，Linux环境可以增加--unsafe-perm参数，或者使用nvm管理node，避免root权限冲突。

2. Codex桌面客户端

Windows系统可以前往官方页面下载安装包，或者在应用商店搜索Codex；macOS下载dmg镜像，拖拽到应用程序文件夹即可完成安装。桌面客户端安装完成打开后，会提供两种登录方式，ChatGPT账号一键登录，或者手动填写API Key对接百炼模型。

3. IDE插件版本

打开VSCode或者JetBrains编辑器，在扩展市场搜索Codex，找到官方插件点击安装。安装完成后，侧边栏会出现Codex入口，首次打开会引导登录或者导入配置文件，自动读取本机.codex/config.toml配置，无需重复填写密钥。

四、登录认证与阿里云百炼对接配置

登录分为两种模式，账号一键登录模式适合使用原生服务；开发者更多使用API Key对接阿里云百炼，将Codex底层模型切换为百炼大模型，走Token Plan、Coding Plan计费。
第一种方式，临时环境变量设置，适合临时测试，终端关闭之后失效：

# Linux/macOS终端临时设置密钥
export OPENAI_API_KEY="你的百炼APIKEY"
# 验证环境变量是否生效
echo $OPENAI_API_KEY

第二种方式，修改config.toml配置文件，永久生效，推荐所有线上服务器使用这个方案。

# 编辑配置文件
nano ~/.codex/config.toml

写入对接阿里云百炼Token Plan的配置内容：

model_provider = "Token_Plan"
model = "auto"
[model_providers.Token_Plan]
name = "Token_Plan"
base_url = "[https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1](https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1)"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

保存退出之后，执行测试命令验证连通性：

codex exec "写一段简单的Python冒泡排序代码"

如果正常返回代码，说明密钥、接口地址、网络全部连通，对接成功。如果返回认证失败，核对API Key是否正确、工作空间权限是否开通、ECS服务器出口网络是否可以访问该接口地址。

除了密钥配置，Codex支持项目级上下文绑定，进入项目根目录执行初始化：

cd /home/work/demo-project
codex init

初始化会扫描项目目录，生成项目描述文件，后续Codex可以读取项目内所有代码文件，理解整体架构，跨文件修改代码，不会只针对单段代码生成内容。

五、Codex常用实操命令与使用方法

Codex CLI内置大量实用指令，覆盖代码生成、文件读写、单元测试、代码审查、批量重构等场景。

# 进入交互式对话模式
codex
# 直接单行指令，一次性执行任务
codex exec "给这个项目增加接口参数校验，输出修改后的代码"
# 扫描当前目录代码，找出安全漏洞并给出修复方案
codex exec "扫描当前目录所有go代码，找出注入风险，输出修复方案"
# 生成单元测试，针对main.go文件
codex exec "为main.go里面所有函数编写完整单元测试"
# 查看当前会话历史
codex history
# 清空会话上下文，开启全新对话
codex reset

在交互式会话内，支持内置斜杠指令，/compact精简对话内容、/fork复制当前会话分支、/new新建任务，适合复杂项目分步迭代开发。

桌面端和IDE插件使用逻辑更加直观，绑定项目文件夹之后，可以直接框选代码片段，发送指令：优化性能、修复报错、翻译成其他语言、补充注释、生成文档。IDE插件支持悬浮提问，鼠标停留在函数上，直接询问函数作用、入参说明、潜在缺陷，开发过程不用切换窗口。

六、版本升级、回滚与版本管理

Codex迭代速度较快，新版本会修复BUG、新增Agent多任务能力、优化长上下文处理。CLI版本升级命令：

npm install -g @openai/codex@latest

如果新版本出现兼容问题，可以指定旧版本号回滚：

npm install -g @openai/codex@0.152.1

桌面客户端打开软件之后，会自动检测更新，也可以手动下载历史安装包替换；IDE插件在扩展页面直接更新。不建议频繁追最新版本，生产服务器上的CLI版本，优先选择经过验证稳定版本，避免新版本接口变更导致调用失败。

七、云上部署安全规范与避坑要点

在阿里云ECS部署Codex，安全是重点。第一，API密钥禁止硬编码写在代码、脚本、提交到代码仓库，优先使用环境变量或者独立配置文件，配置文件设置权限，仅当前用户可读：

chmod 600 ~/.codex/config.toml

第二，Codex具备读取本地文件、执行命令的能力，不要给高权限账号运行Codex，尽量使用普通业务账号，限制访问目录，防止AI指令误操作删除业务文件。第三，ECS服务器做好出口访问管控，仅开放百炼接口域名访问，缩小网络暴露面。第四，关注Token消耗，Coding Plan适合高频编码场景，Token Plan适合按需调用，在百炼控制台配置用量告警，防止超额扣费。

高频踩坑点汇总：Node版本过低，直接安装失败；配置文件路径写错，Codex读取不到密钥；服务器缺少出口网络，接口请求超时；项目目录过大，首次init扫描耗时很久，可以在配置里设置忽略目录，类似gitignore；部分Windows环境，终端编码异常，中文提示乱码，修改终端编码为UTF-8即可解决。

八、高阶玩法：搭配流水线、自动化代码检查

Codex CLI可以嵌入CI/CD流水线，在代码提交阶段自动做代码评审、漏洞检测、注释补齐，下面是简单流水线调用示例：

# CI脚本内调用Codex做代码评审
codex exec "评审本次提交变更代码，列出风险点，给出优化建议" >> code-review-report.txt

适合团队规范落地，每次提交自动生成评审报告，降低人工CR工作量。同时支持Skill脚本扩展，自定义能力集，接入内部业务SDK说明，让Codex贴合团队技术栈，生成符合内部规范的代码。

整体来看，Codex三种版本覆盖本地开发、服务器远程编码、自动化流水线场景，搭配阿里云百炼的Coding Plan和Token Plan，能够稳定、低成本地获得AI编码能力。新手建议先从IDE插件入手，熟悉交互逻辑，再尝试CLI版本部署在阿里云ECS，实现云上项目远程编码、批量脚本处理。只要按照步骤完成环境准备、密钥对接、项目初始化，就能把Codex融入日常开发流程，大幅提升写代码、查BUG、重构项目的效率。