Codex安装使用指南一、什么是 CodexCodex 是 OpenAI 推出的 AI 代码智能体Code Agent不是简单的代码补全插件它可以直接读取你的项目代码、修改文件、执行命令完成从代码生成、调试到批量运维的复杂任务。它有三种使用形态Web 版ChatGPT 网页中的 Codex无需本地安装IDE 插件支持 VS Code、Cursor、Windsurf 等编辑器嵌入开发流程CLI 命令行工具本地终端运行的完整体能力最强支持复杂长任务二、安装前准备系统要求支持 Windows 10/11、macOS 12、Linux 全发行版Windows 原生支持为实验性推荐使用 WSL 子系统获得更稳定体验最低内存要求 8G推荐 16G 以上处理大项目更流畅依赖准备CLI 版本需要 Node.js 环境Node.js ≥18.0推荐 22 LTS 版本旧版本会出现语法兼容错误npm ≥10.0可选Git用于项目版本控制与集成账号准备官方使用需要 ChatGPT Plus/Team/Enterprise 订阅账号可直接登录使用无订阅账号可通过国内中转平台获取 API Key低成本使用后文有详细配置三、三种安装方式按需选择1. IDE 插件新手首选开箱即用如果你习惯在编辑器里开发IDE 插件是最简单的选择无需配置环境。以 VS Code 为例打开 VS Code 的扩展市场搜索Codex认准OpenAI 官方的插件避免山寨版安装完成后侧边栏会出现 OpenAI 的 Logo点击即可打开 Codex 面板登录你的 ChatGPT 账号即可开始使用注插件会自动读取你本地的/.codex 配置和 CLI 版本配置互通2. CLI 命令行全功能首选终端党必备CLI 版本是 Codex 的完整体支持所有高级功能适合终端用户、服务器运维、批量任务处理。Mac/Linux 安装方式一npm 安装推荐先安装 Node.jsUbuntu/Debiancurl-fsSLhttps://deb.nodesource.com/setup_22.x|sudobash-sudoapt-getinstall-ynodejsmacOS# 先安装Homebrew如果没装的话xcode-select--install/bin/bash-c$(curl-fsSLhttps://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)# 安装Nodebrewinstallnode验证 Node 版本node-v# 应显示v22.x或更高npm-v安装 Codex CLInpminstall-gopenai/codex# 国内网络慢的话用淘宝镜像加速# npm install -g openai/codex --registryhttps://registry.npmmirror.com方式二Homebrew 安装Mac 专属brewinstallcodexWindows 安装推荐 WSLWindows 原生 CLI 支持不完善推荐使用 WSL 子系统开启 Windows 功能打开「启用或关闭 Windows 功能」勾选Virtual Machine Platform和Windows Subsystem for Linux安装 Ubuntuwsl--install-d Ubuntu-24.04重启电脑后进入 WSL 终端按照上面的 Linux 步骤安装 Node 和 Codex 即可。验证安装安装完成后执行codex--version# 输出版本号如0.77.0即表示成功3. 桌面端应用可视化操作新手友好如果你不习惯命令行OpenAI 还提供了桌面端的 Codex 应用可视化界面操作更简单访问官方下载页https://chatgpt.com/zh-Hans-CN/codex/下载对应系统的安装包按照向导完成安装登录 ChatGPT 账号即可使用支持拖拽文件夹、可视化任务进度查看桌面端界面简洁分为左侧项目区、中间对话区、右侧状态区即使是新手也能快速上手支持中途随时打断调整任务不会浪费 Token。四、核心配置从登录到个性化1. 官方账号登录推荐如果你有 ChatGPT Plus 账号直接在终端执行codex系统会自动弹出浏览器登录你的 ChatGPT 账号授权后 Token 会自动保存无需手动配置一键完成。2. API Key 模式无订阅用户如果你没有订阅账号使用中转 API 的话需要手动配置进入 Codex 的配置目录WindowsC:\\Users\lt;你的用户名\gt;\.codex\\Mac/Linux\~/\.codex/创建auth\.json文件填入你的 API Key{OPENAI_API_KEY:sk-你的实际API密钥}创建config\.toml文件配置中转地址和模型model_provider 你的中转标识 model gpt-5-codex model_reasoning_effort high disable_response_storage true preferred_auth_method apikey [model_providers.你的中转标识] name 你的中转标识 base_url https://你的中转地址/v1 wire_api responses⚠️ 注意不同中转平台的base\_url和标识不同请按照平台文档填写配置完成后重启终端生效。3. 全局中文回复强烈推荐默认 Codex 会用英文回复我们可以配置全局默认中文mkdir-p~/.codexprintfAlways respond in Chinese-simplified\n~/.codex/AGENTS.md配置后所有 Codex 会话都会默认用简体中文回复不用每次都手动要求。4. 国内用户网络注意事项官方版本需要开启全局 Tun 模式代理不建议规则模式避免连接失败避免频繁切换 IPOpenAI 对 Codex 的风控比普通 ChatGPT 更严格也可以直接使用国内中转平台无需代理更稳定五、高频使用技巧效率翻倍1. Slash 快捷命令在 Codex 交互界面输入/可以打开快捷命令菜单常用命令命令作用/model切换模型推荐gpt\-5\-codex high推理模式/new开启新会话清空上下文/status查看当前会话的 Token 消耗、配置状态/compact压缩过长的上下文避免 Token 溢出/diff查看当前的文件修改 diff/init初始化当前项目的 [AGENTS.md](AGENTS.md) 记忆文件/approvals切换授权模式2. 授权模式选择Codex 有三种安全授权模式根据场景选择模式说明适合场景Suggest默认只读文件所有修改 / 命令都需要你确认新手试用、敏感项目Auto Edit可自动修改文件执行命令需要确认日常开发Full Access全自动执行无沙箱限制个人开发环境追求效率如果要开启最高效率的 Full Access 模式启动时可以加参数codex --dangerously-bypass-approvals-and-sandbox⚠️ 注意这个模式仅在个人开发环境使用不要用在重要项目避免误操作。3. 别名优化一键启动最优配置我们可以把常用的参数做成别名不用每次都输入# 编辑~/.zshrc或~/.bashrcaliascodexcodex -m gpt-5-codex -c model_reasoning_efforthigh --search --yolo保存后执行source \~/\.zshrc之后输入codex就会自动用高推理模型、开启搜索、全自动模式一步到位。4. 项目记忆不用每次重新解释Codex 支持两层记忆系统全局记忆就是我们之前配置的\~/\.codex/AGENTS\.md对所有项目生效比如你的编码习惯、偏好项目记忆在项目根目录创建AGENTS\.md只对当前项目生效比如项目的背景、技术栈、注意事项比如你接手一个陌生项目第一次让 Codex 理解后让它生成项目的 [AGENTS.md](AGENTS.md)之后不管什么时候打开它都能直接记住项目的所有信息不用重新解释。5. 常用实战场景快速生成脚本直接在命令行输入任务不用进入交互模式codex写一个批量重命名图片的Python脚本按拍摄时间排序3 秒就能输出可运行的代码。批量修改文件比如要把项目里所有的旧 IP 换成新 IP把当前目录下所有.conf文件里的192.168.1.100替换成10.0.0.50Codex 会自动批量修改还会自动验证配置有没有错误。修复 Bug把报错丢给它它会自动定位修复帮我跑一下pytest看看报错然后修一下它会自己跑测试、读报错、改代码全程不用你动手。读懂陌生项目接手别人的项目直接问帮我理一下这个项目的结构解释一下认证模块的实现逻辑它会自动读所有文件给你清晰的说明比你自己 grep 快 10 倍。六、常见问题与排查1.codex: command not found原因npm 的全局安装路径没加入 PATH或者安装失败解决重新安装npm install \-g openai/codex检查 Node 的全局路径把它加入系统 PATH重启终端2. 登录失败 / 401 Unauthorized原因网络问题或者 Token 过期解决检查代理是否正常全局 Tun 模式是否开启执行codex logout然后重新登录如果是 API Key 模式检查 auth.json 里的 Key 是否正确3. 配置文件不生效原因配置写错了或者没重启终端解决检查 config.toml 里的model\_provider名称要和后面的\[model\_providers\.xxx\]完全一致重启终端让配置生效检查文件的权限确保 Codex 有读取权限4. 网络连接超时原因网络不通或者中转地址错了解决检查代理是否正常能不能访问openai.com如果是中转模式检查 base_url 是否正确有没有写错公司网络的话检查是否有防火墙拦截5. 大项目上下文不够用原因项目太大Codex 的上下文窗口装不下解决用/compact压缩上下文清理无用的历史针对性的让它只处理某个子目录不要全项目扫描小步迭代每次只做一个小任务不要一次性让它改整个项目七、总结Codex 作为 OpenAI 推出的 AI 代码智能体已经从早期的玩具工具变成了真正能干活的开发搭档不管是日常写代码、批量运维还是接手陌生项目都能帮你节省大量时间。对于国内用户来说只要配置好网络或者中转就能获得比 Claude Code 更稳定、成本更低的体验而且它的迭代速度非常快新功能不断更新。新手建议先从桌面端或者 IDE 插件入手熟悉之后再尝试 CLI 版本解锁全部功能让你的开发效率直接翻倍。