#Codex 安装与使用

本章帮你装好 桌面应用、CLI 与 IDE 扩展 并完成登录。大多数人从桌面应用开始最顺手。

#系统要求

其他要求：

• 网络可访问 OpenAI 服务
• Git（强烈推荐，App 的 Diff、worktree、检查点都基于 Git）
• 一个含 Codex 额度的 ChatGPT 套餐，或 OpenAI API Key

#一、安装桌面应用（推荐起点）

1. 打开 developers.openai.com/codex 或 Quickstart
2. 下载对应平台安装包：
   • macOS：.dmg，拖入「应用程序」
   • Windows：安装程序，按向导完成
3. 启动后用 ChatGPT 账号登录（见下文「登录」）
4. 选择一个项目文件夹，在 Local 模式发送第一条消息

也可以在已安装 CLI 的机器上执行 codex app 直接打开桌面应用。

详细的首次使用见 桌面应用。

#二、安装 Codex CLI

#方式一：官方安装脚本（推荐）

macOS / Linux：

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

Windows（PowerShell）：

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

无人值守安装：

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

#方式二：npm

npm install -g @openai/codex

#方式三：Homebrew（macOS）

brew install --cask codex

#验证与更新

codex --version
codex update        # 检查并应用 CLI 更新
codex doctor        # 生成本地诊断报告，排查环境问题

详见 命令行工具（CLI）。

#三、安装 IDE 扩展（可选）

在 VS Code / Cursor / Windsurf 的扩展市场搜索 Codex 安装，侧边栏会出现 Codex 面板。详见 IDE 扩展。

#登录方式

首次启动 App 或运行 codex 会提示登录：

#1. ChatGPT 账号（推荐个人开发者）

• 使用含 Codex 额度的 Plus / Pro / Business / Edu / Enterprise 套餐
• 自动配置凭据，免去手动管理 Key
• CLI 中对应 codex login（OAuth）

#2. OpenAI API Key / 访问令牌

• 适合 CI、企业按量计费、自动化用户
• 在 platform.openai.com 创建 Key
• 部分 ChatGPT 专属功能可能不可用

codex login          # 交互式登录（OAuth / API Key / 访问令牌）
codex logout         # 移除已存凭据

#目录与环境变量

#常见问题

#codex: command not found

• 确认安装脚本已把二进制加入 PATH
• npm 全局：npm prefix -g 的 bin 目录应在 PATH 中

#Windows 上 Shell 行为异常

• 优先参考官方 Windows setup
• 需要 Linux 原生工具链时用 WSL2

#登录失败或 401

• 检查系统时间、代理、防火墙
• API Key 是否过期、组织是否已启用 Codex

#想体检环境

codex doctor

#下一步

• 桌面应用：添加项目、Local/Cloud、Hand off
• 基础入门：完成第一个可验证的小任务
• 核心概念：理解 Agent 如何工作