⚙️ 准备工作：请确保基础环境达标

 

安装Codex CLI前，请检查系统环境并确保以下要求：

 

· Node.js版本：最低要求为18.0+，但强烈推荐使用最新的v22.x LTS版本。

· 包管理工具：确保npm也已安装（版本建议9.x以上）。

· 操作系统：支持macOS、Linux和Windows（推荐使用WSL2环境，原生支持为实验性）。

· Git（可选但推荐）：以便Codex更好地与版本控制系统协作。

 

📦 安装方式：三选一

 

CLI

 

· 适用平台：macOS / Linux / Windows (WSL2)

· 安装命令/步骤：npm install -g @openai/codex (首选)，国内用户可使用淘宝镜像加速安装；或通过 Homebrew 安装：brew install --cask codex。

· 启动方式/验证命令：codex --version

 

IDE 插件

 

· 适用平台：VS Code / JetBrains 等

· 安装命令/步骤：在IDE插件市场搜索"OpenAI Codex"或"AI Code Assistant"，找到官方或高评分插件安装即可。

· 启动方式/验证命令：安装完成后，IDE中会出现AI助手图标或侧边栏。

 

桌面应用

 

· 适用平台：Windows / macOS

· 安装命令/步骤：通过Microsoft Store或从OpenAI官网下载安装包，按向导完成安装即可。

· 启动方式/验证命令：在系统应用列表中找到Codex图标启动。

 

📝 核心配置（必做）

 

1. 账号与认证：如果你拥有有效的ChatGPT Plus/Pro订阅，大多数情况下codex login命令会引导你通过浏览器完成授权。

2. 配置文件：Codex的核心配置文件是~/.codex/config.toml（Windows通常在C:\Users\<你的用户名>\.codex\）。

3. 基础配置示例：

   ```toml

   # 定义默认使用的模型

   model = "gpt-5-codex" # 或其他模型，如 "o3"[reference:16]

   

   # 定义沙盒模式，控制Codex对文件系统的访问权限

   sandbox_mode = "workspace-write" # 允许读写当前项目目录[reference:17]

   

   # 定义审批策略，控制命令执行的自动程度

   approval_policy = "on-request" # 对于不确定的操作会请求用户确认[reference:18]

   ```

 

🇨🇳 国内用户的专属配置

 

Codex CLI默认调用OpenAI官方API (api.openai.com)，国内用户可通过修改配置将API指向国内中转服务，即可直接使用。国内用户核心操作只需三步：

 

1️⃣ 获取国内中转API Key

注册并登录一个提供OpenAI兼容API的国内中转服务平台（如七牛云AI等），获取一个API Key。

 

2️⃣ 配置API端点

编辑~/.codex/config.toml，将openai_base_url指向国内兼容端点，并指定模型：

 

```toml

openai_base_url = "https://api.qnaigc.com/v1" # 国内兼容端点示例，请替换成你的服务提供商的地址

model = "deepseek-v4-pro" # 模型名称以服务提供商实际支持的为准

web_search = "disabled" # 建议关闭联网搜索，避免不必要的网络问题

```

 

3️⃣ 设置API Key环境变量

将获取的API Key设置为环境变量：

 

```bash

export OPENAI_API_KEY="你的API_Key"

```

 

🚀 使用入门：你的第一个任务

 

配置完成后，就可以在终端使用Codex了。

 

· 启动交互式会话：在项目目录下输入codex，即可进入对话。

· 发送一次性请求：直接向Codex提问，如codex "解释一下这个项目的README"。

 

使用建议：用自然语言清晰地描述你想要完成的任务，Codex会自主完成一系列操作，并在必要时向你请求确认（如删除文件、安装依赖等）。

 

🤔 常见问题

 

如果你在安装或配置过程中遇到问题，可以参考以下几点：

 

· 版本及验证问题：严格遵循node -v、npm -v检查，确保Node.js >= v22，npm >= 10，并用codex --version验证安装是否成功。

· 网络与权限问题：国内环境务必配置国内中转API端点，并通过codex doctor验证；同时确保项目目录有写入权限。

· WSL环境问题：Windows用户若用WSL2，注意避免跨文件系统操作，尽量将代码项目放在Linux文件系统内（如~/目录下），以规避I/O性能差等问题。

· 问题诊断：可用codex doctor或codex --debug命令快速检测配置和网络状况。