Appearance
Codex CLI 安装与首次使用
Codex CLI 是 OpenAI 提供的终端编码代理，可以在本地项目中阅读代码、修改文件、执行命令并协助完成多步骤开发任务。它适合习惯使用 PowerShell、Terminal、Shell 或 WSL 的开发者。
本文介绍 Windows、macOS 和 Linux 上的安装方法，并说明如何验证安装、从项目目录启动，以及通过 CC Switch 接入应天AI。
Codex CLI 能够读取和修改当前项目中的文件，也可能运行终端命令。首次使用时应从测试项目开始，并认真确认它请求执行的操作。
一、开始前准备
安装前请确认：
- 电脑能够正常访问 Codex 官方下载地址或 npm
- 当前用户可以安装命令行程序
- 已准备一个用于测试的本地项目目录
- 如果计划接入应天AI，已经拥有应天AI账号和 API Token
Codex CLI 与 Codex 桌面端用途相近，但操作入口不同：
| 工具 | 使用方式 | 适合场景 |
|---|---|---|
| Codex CLI | 在终端中运行 codex | 命令行工作流、脚本和本地仓库任务 |
| Codex 桌面端 | 图形界面 | 偏好窗口化任务管理的用户 |
| Codex 编辑器扩展 | 安装到 VS Code 等编辑器 | 希望在编辑器中直接使用 Codex |
官方入口：
二、选择安装方式
推荐优先使用 OpenAI 提供的独立安装脚本。也可以根据本机环境选择 npm、Homebrew 或手动下载可执行文件。
同一台电脑只需要选择一种安装方式。混用多个安装来源可能导致终端调用到旧版本。
| 安装方式 | 适用系统 | 是否需要 Node.js |
|---|---|---|
| 官方安装脚本 | Windows、macOS、Linux | 否 |
| npm 全局安装 | Windows、macOS、Linux | 是 |
| Homebrew | macOS | 否 |
| 手动下载二进制文件 | macOS、Linux 等官方发布平台 | 否 |
三、Windows 安装
方法一：使用官方 PowerShell 安装脚本
打开 PowerShell，执行：
powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"安装完成后，关闭当前 PowerShell 窗口并重新打开，使终端重新加载环境变量，然后检查版本：
powershell
codex --version如果输出版本号，说明 Codex CLI 已经可以从终端启动。
执行远程安装脚本前，应确认地址属于 OpenAI 官方域名。不要把第三方来源的一键脚本直接复制到具有管理员权限的终端中运行。
方法二：使用 npm 安装
如果电脑已安装 Node.js 和 npm，可以执行：
powershell
npm install -g @openai/codex安装后验证：
powershell
codex --version如果提示 npm 不存在，请先安装 Node.js，或者改用官方 PowerShell 安装脚本。
Windows 与 WSL 如何选择
Codex CLI 可以在 Windows 终端中安装。对于依赖 Linux 工具链、Shell 脚本或容器环境的项目，也可以在 WSL 中单独安装。
需要注意：Windows 和 WSL 是两套环境。在 PowerShell 中安装的 Codex 不一定能直接在 WSL 中使用；反之亦然。请在实际开发项目所在的环境中完成安装。
四、macOS 安装
方法一：使用官方安装脚本
打开 Terminal，执行：
bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh重新打开终端后验证：
bash
codex --version方法二：使用 Homebrew
已经安装 Homebrew 的用户可以执行：
bash
brew install --cask codex安装完成后运行：
bash
codex --version方法三：使用 npm
如果本机已有 Node.js：
bash
npm install -g @openai/codex不建议在不清楚 npm 全局目录权限的情况下直接添加 sudo。遇到权限错误时，优先检查 Node.js 的安装方式和 npm 全局目录配置。
五、Linux 安装
方法一：使用官方安装脚本
在终端执行：
bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh重新打开终端后验证：
bash
codex --version方法二：使用 npm
已安装 Node.js 和 npm 时，可以执行：
bash
npm install -g @openai/codex方法三：下载官方二进制文件
如果不使用安装脚本或 npm，可以从 Codex Releases 下载与系统架构对应的压缩包。
常见文件包括：
| 系统架构 | 常见文件名 |
|---|---|
| Linux x86_64 | codex-x86_64-unknown-linux-musl.tar.gz |
| Linux ARM64 | codex-aarch64-unknown-linux-musl.tar.gz |
| macOS Apple Silicon | codex-aarch64-apple-darwin.tar.gz |
| macOS Intel | codex-x86_64-apple-darwin.tar.gz |
解压后通常需要将带平台后缀的程序重命名为 codex，再移动到系统的可执行路径中。手动安装适合熟悉 PATH、文件权限和系统架构的用户。
六、确认安装结果
无论使用哪一种方式，安装后都应完成以下检查：
1. 查看版本
bash
codex --version2. 查看帮助
bash
codex --help如果两个命令都能正常返回，说明可执行文件已经安装并被当前终端识别。
3. 确认命令来源
如果电脑曾通过不同方式安装 Codex，可以检查当前终端实际调用的程序位置。
Windows PowerShell：
powershell
Get-Command codexmacOS 或 Linux：
bash
which codex如果升级后仍显示旧版本，通常是系统中存在多个 Codex 可执行文件，或者终端仍缓存旧路径。
七、在项目中首次启动
建议先进入准备好的项目目录，再启动 Codex。这样 Codex 会以该目录作为主要工作区。
Windows PowerShell：
powershell
Set-Location "D:\path\to\your-project"
codexmacOS、Linux 或 WSL：
bash
cd /path/to/your-project
codex首次启动时，Codex 可能要求选择登录或认证方式。使用 OpenAI 官方服务时，可以按界面提示登录 ChatGPT 或配置 OpenAI API Key。
如果计划使用应天AI中转服务，请先完成后文的 CC Switch 配置，再重新启动 Codex CLI。
八、第一次任务建议
首次运行不要直接要求 Codex 大范围修改项目。建议从只读任务开始，例如：
text
请分析当前项目的目录结构，只说明各主要目录的用途，不要修改文件。确认目录识别正常后，再尝试小范围任务：
text
请检查当前项目的启动命令，并告诉我应该如何运行，不要修改文件。当 Codex 请求执行命令或修改文件时，应先阅读操作内容和影响范围，再决定是否批准。对于删除文件、覆盖配置、安装依赖或访问网络等操作尤其需要谨慎。
九、通过 CC Switch 接入应天AI
如果希望 Codex CLI 使用应天AI提供的模型服务，推荐使用 CC Switch 管理 Provider：
- 阅读 CC Switch 安装教程，完成安装和首次启动。
- 在应天AI API 密钥 页面创建 Codex 专用 Token。
- 从 Token 操作菜单选择 CC Switch。
- 在导入窗口中选择 Codex，填写配置名称并选择可用模型。
- 在 CC Switch 中启用刚导入的 Provider。
- 退出当前 Codex CLI 会话，然后重新运行
codex。
完整的图文配置过程请阅读 Codex 配合 CC Switch 接入应天AI。
重新进入 Codex CLI 后，可以发送：
text
请只回复：您好随后打开应天AI使用日志，确认请求时间、模型、状态和消耗信息正确。
十、更新与卸载
更新官方脚本安装版本
可以重新运行对应系统的官方安装脚本，获取当前版本。更新后重新打开终端，并执行：
bash
codex --version更新 npm 安装版本
bash
npm install -g @openai/codex@latest更新 Homebrew 安装版本
bash
brew upgrade --cask codex卸载 npm 安装版本
bash
npm uninstall -g @openai/codex其他安装方式请使用对应包管理器或官方安装说明进行卸载。卸载前如需保留自定义配置，请先确认 Codex 配置目录和 CC Switch Provider 是否需要备份。
常见问题
提示 codex 不是命令
先关闭并重新打开终端。如果仍然失败，检查安装是否成功以及 Codex 所在目录是否已加入 PATH。npm 用户还需要确认 npm 全局可执行目录是否在 PATH 中。
npm 安装时报权限错误
不要反复使用管理员权限覆盖安装。优先确认 Node.js 是否通过合适的版本管理工具安装，并检查 npm 全局目录的写入权限。也可以改用 OpenAI 官方独立安装脚本。
Windows 中安装成功，WSL 内无法运行
Windows 和 WSL 使用不同的文件系统与环境变量。请进入 WSL 后，使用 Linux 安装命令再次安装 Codex CLI。
启动后仍然访问旧 Provider
先退出 Codex CLI 会话，确认 CC Switch 中正确的 Codex Provider 显示为当前使用，再重新打开终端并运行 codex。
Codex 可以启动，但请求没有返回
检查网络连接、认证状态和 Provider 配置。如果使用应天AI，查看控制台是否出现请求日志：没有日志通常表示请求尚未到达平台；有失败日志则根据状态码检查 Token、模型和额度。
返回 401 或 API Key 无效
确认使用的是有效 API Token，Token 前后没有空格或换行，并检查 Token 是否过期或已被停用。
返回模型不存在
从应天AI模型广场复制当前可用模型名称，并确认 Token 对该模型具有权限。
升级后版本没有变化
执行 Get-Command codex 或 which codex 检查当前命令位置。电脑中可能同时存在官方脚本、npm 或 Homebrew 安装的多个版本。
安全建议
- 只从 OpenAI 官方页面、官方 GitHub 仓库或 npm 官方包安装 Codex。
- 不要运行来源不明的 Codex 配置脚本。
- 首次在新项目中使用时，优先选择只读分析任务。
- 批准文件修改和终端命令前，先确认影响范围。
- 不要把 API Token 写入代码、提交记录或公开配置。
- 为 Codex CLI 创建独立 Token，便于限制权限和排查用量。