Codex下载、安装、配置基础教程

最后更新：2026-08-12· 14 分钟阅读

🚀 快速通道

ChatGPT 国内版：点击直达↗
稳定镜像站：打开镜像↗
官方 ChatGPT：chatgpt.com ↗

Codex下载、安装、配置基础教程

更新时间：2026-08-12

导读

Codex 是 OpenAI 面向开发者的编码 Agent：在终端 CLI、IDE 插件或桌面应用中读取仓库、编辑文件、运行命令并解释结果。它与 ChatGPT 网页聊天的定位不同——前者是「结对程序员」，后者更适合单次问答与文档草稿。

OpenAI 同时提供 Codex CLI、Codex Web 与 VS Code / Cursor 等 IDE 扩展。本文以 CLI 为主线；IDE 侧共享同一套配置层级。若你已在用 Anthropic 生态，可先对照 Claude Code 编程助手指南理解 Agent 编程共性，再按本文完成 Codex 安装。

Codex 解决什么问题？

网页 ChatGPT	Codex CLI / IDE
粘贴代码片段问答	直接索引项目目录与 Git 状态
人工复制 diff 到编辑器	授权范围内改文件、跑测试
适合解释概念、写草稿	多步修 bug、重构、脚手架

适合： 有 Git 工作流、能在本地执行测试的开发者。
不适合： 无版本控制、无法跑命令的纯文档环境。

安装前：环境与账户

项目	最低建议	说明
系统	macOS 13+、Ubuntu 22.04+、Windows 11	Windows 上 WSL2 沙箱支持更完整
Git	2.30+	在已 `git init` 的项目根目录启动体验最佳
账户	ChatGPT Plus/Pro/Team 或 OpenAI API Key	套餐是否含 Codex 以 Platform 账户页为准
Node.js	18+（仅 npm 路径需要）	官方脚本 / Homebrew 可不依赖 Node
资源	~200 MB 磁盘；建议 8 GB 可用内存	大仓库索引会占用更多

安全提醒： 不要在不可信第三方站下载所谓「Codex 破解版」。CLI 具备读改文件与执行 shell 的能力，来源不明的二进制风险极高。

下载与安装（三条路径）

命令会随版本更新，执行前请对照 Codex CLI 官方文档。

路径 A：官方脚本（macOS / Linux，推荐）

curl -fsSL https://chatgpt.com/codex/install.sh | sh

路径 B：Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

路径 C：npm 或 Homebrew

npm install -g @openai/codex          # 需 Node.js 18+
brew install --cask codex               # 仅 macOS

安装完成后执行 codex --version 确认可用。若提示命令不存在，检查 PATH 并重启终端；也可从 Codex GitHub Releases 下载二进制。

首次登录与授权

cd 到项目根目录（建议已是 Git 仓库）。
运行 codex 进入交互界面。
选择授权方式：
- Sign in with ChatGPT：绑定订阅，额度随套餐变化。
- API Key：走 OpenAI Platform 按量计费，适合 CI 或自动化。
确认沙箱模式与命令审批策略——默认应在改动文件或执行 shell 前询问你。

国内用户若登录页或下载受限，可先阅读 ChatGPT 国内访问完整指南；授权与账单仍以 OpenAI 官方账户为准。

config.toml：从默认到可控

Codex 配置按优先级生效：CLI 参数 > 项目配置 > Profile > 用户配置 > 内置默认值。

层级	路径	典型用途
用户级	`~/.codex/config.toml`（Windows：`%USERPROFILE%\.codex\config.toml`）	默认模型、全局沙箱、自定义 provider
项目级	`.codex/config.toml`	团队共享的非敏感默认值（仅已信任项目加载）
Profile	`~/.codex/.config.toml` 或 config 内 `[profiles.]`	多模型 / 多后端切换

完整键名见 Codex 配置文档。

新手推荐的最小配置

model = "gpt-5.4"                      # 模型 ID 以官方文档为准
approval_policy = "on-request"         # 改文件 / 跑命令前询问
sandbox_mode = "workspace-write"       # 仅允许在工作区内写入

常用键速查

键	典型值	作用
`model`	官方模型 ID	默认推理模型
`approval_policy`	`on-request` / `never`	工具调用是否需人工确认
`sandbox_mode`	`read-only` / `workspace-write`	文件系统写入范围
`model_reasoning_effort`	`low` / `high`	推理深度（若模型支持）

安全建议： 新手保持 on-request + workspace-write；仅在隔离练习仓库中尝试更宽松策略。若希望改用 DeepSeek 作为后端，见 Codex 配置 DeepSeek 模型详细教程。

IDE 扩展与桌面端

除 CLI 外，Codex 还可通过 VS Code、Cursor、Windsurf 等 IDE 扩展使用，或通过 codex app 启动桌面应用。扩展与 CLI 共享同一套 config.toml 层级。

团队若需统一规范，可把 .codex/config.toml 中非敏感默认值提交到仓库；密钥只放环境变量，绝不进 Git。

安装后五步验收

codex --version 有版本号输出。
在小型练习仓库根目录执行 codex，能完成登录。
发起只读任务（例如「列出 src/ 下主要模块职责」），确认能索引文件。
发起一次需写文件的小改动，确认审批弹窗与沙箱行为符合预期。
若走 API Key，在 Platform 确认项目余额、模型权限与限流正常。

权限与安全（必读）

Codex 能读文件、改文件、跑 shell——权限过大等于把笔记本交给第三方。

仓库：只在可信项目启用；贡献开源项目前先 fork 到隔离目录。
密钥：确保 .env、credentials.json 在 .gitignore；启用前确认工具是否会读取 ignored 文件。
命令：对 rm -rf、包安装、外网请求保持确认；公司环境遵循内部 AI 使用政策。
输出：生成代码仍需 code review + CI，禁止未经审查直接合入 main。

常见问题

安装脚本下载失败怎么办？

先检查网络与代理，再尝试 npm 或 Homebrew 路径；也可到 Codex GitHub Releases 下载二进制。Windows 用户优先在 WSL2 内安装 Linux 版以获得完整沙箱。

ChatGPT 订阅和 API Key 有什么区别？

ChatGPT 登录通常绑定套餐内 Codex 额度；API Key 走 Platform 独立计费。两者授权入口不同，不要混用密钥。

`codex` 命令找不到？

重启终端；检查安装程序输出的 PATH 提示；npm 全局安装时确认 npm prefix -g 目录在 PATH 中。

项目级 config.toml 不生效？

.codex/config.toml 仅在被标记为信任的项目中加载；部分键（如 model_provider）只能写在用户级 ~/.codex/config.toml。

Windows 原生与 WSL2 该选哪个？

日常开发若在 WSL2 内进行，在 WSL 内安装 Codex 体验更一致；纯 PowerShell 环境可用 Windows 安装包，但沙箱与路径行为可能与 Linux 文档描述略有差异。

装好后第一条任务该做什么？

建议先做只读问答（读懂一个模块），再做单测修复——详见 Codex 新手快速上手。

官方资源

下一步阅读

行动路径

今天：在练习仓库完成安装、登录与一次只读问答。本周：用真实 failing test 跑通「读日志 → 最小 patch → 本地验证」闭环。长期：把团队默认的 approval_policy、沙箱策略与 .gitignore 检查写进 CONTRIBUTING.md。

导读