> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnimux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> 将 Codex CLI 连接到 OmniMux

## 概述

<Note>
  OmniMux 网关统一使用 Base URL：`https://api.omnimux.ai`（OpenAI 兼容客户端通常填 `https://api.omnimux.ai/v1`）。控制台为 [omnimux.ai/dashboard](https://omnimux.ai/dashboard)。文中的模型 ID 仅为示例，请以控制台或 `GET /v1/models` 为准。
</Note>

Codex CLI 是 OpenAI 官方推出的命令行工具，专注于在终端环境中完成代码相关任务。相比通用对话工具，Codex CLI 更强调"工程化输出"，能以更清晰的结构给出可直接落地的代码与修改建议。
通过将 Codex CLI 与 **OmniMux API** 进行配置集成，您可以在命令行中以统一的 OpenAI 兼容接口调用 OmniMux 提供的多种模型能力（如 **GPT 系列**），实现统一 Key、统一 Base URL 的多模型接入。

## 使用前准备

在开始配置之前，请确保已完成以下准备工作：

### 1. 安装 Node.js 与 npm

**为什么需要？** Node.js 是运行 CLI 工具的基础环境（类似手机需要安装微信才能聊天，电脑需要安装 Node.js 才能运行 CLI 工具）。

**如果已安装：** 运行 `node -v` 和 `npm -v` 检查版本，如果是 v20+，可跳过此步骤。

**首次安装：**

* 请从 [Node.js 官方网站](https://nodejs.org/) 下载并安装（推荐下载 LTS 长期支持版）
* 如果不熟悉安装流程，可参考 [菜鸟教程 - Node.js 安装配置](https://www.runoob.com/nodejs/nodejs-install-setup.html)
* 建议使用 **Node.js v20 或更高版本**
* 安装完成后，可通过以下命令验证：

```bash theme={null}
node -v
npm -v
```

### 2. 获取 OmniMux API Key

* 登录 [OmniMux 控制台](https://omnimux.ai/dashboard)
* 在控制台中找到 API Keys，点击"创建新Key"按钮，然后复制生成的 Key
* API Key 通常以 `sk-` 开头，请妥善保存

## 第一步：安装 Codex CLI

**提示：** 如果不知道如何打开命令行终端，请查看 [常见问题 - 如何打开命令行终端](#13-如何打开命令行终端？)

### 1. 全局安装

```bash theme={null}
npm install -g @openai/codex
```

**预期结果：** 会看到下载信息滚动，最后显示 `added XX packages` 表示成功（需要 1-3 分钟）。

**如果出错：** 提示 `permission denied` 时，Windows 需右键"以管理员身份运行" PowerShell，macOS/Linux 在命令前加 `sudo`。

### 2. 检验安装

```bash theme={null}
codex --version
```

**成功标志：** 显示版本号（如 `1.x.x`）。

## 第二步：配置 OmniMux API

Codex CLI 支持通过配置文件设置自定义 Provider，无需修改源代码。

### 1. 打开配置目录

键盘按下 `Win + R` 键，输入以下内容后回车，打开你的 Codex 配置目录：

```
%userprofile%\.codex
```

在访达界面按下 `Command + Shift + G`，输入以下路径并回车，打开 Codex 配置目录：

```
~/.codex
```

在文件管理器中访问配置目录：

```
~/.codex
```

### 2. 编辑 config.toml

在配置目录中找到 `config.toml` 文件，编辑以下内容：

```toml theme={null}
model = "gpt-5.2"
model_reasoning_effort = "medium"
model_provider = "omnimux"

[model_providers.omnimux]
name = "OmniMux API"
base_url = "https://api.omnimux.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
```

**⚠️ 重要提示：**

* 请**完整复制**下面内容，不要遗漏任何符号
* 将 `"你的 OmniMux API Key"` 替换为实际的 API Key
* TOML 格式对缩进和符号敏感，请保持原样

```powershell theme={null}
@"
model = "gpt-5.2"
model_reasoning_effort = "medium"
model_provider = "omnimux"

[model_providers.omnimux]
name = "OmniMux API"
base_url = "https://api.omnimux.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
"@ | Out-File -FilePath "$env:USERPROFILE\.codex\config.toml" -Encoding utf8
```

```bash theme={null}
cat > ~/.codex/config.toml << 'EOF'
model = "gpt-5.2"
model_reasoning_effort = "medium"
model_provider = "omnimux"

[model_providers.omnimux]
name = "OmniMux API"
base_url = "https://api.omnimux.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
EOF
```

执行命令后，配置文件将自动创建并写入。

```toml theme={null}
model = "gpt-5.2"
model_reasoning_effort = "medium"
model_provider = "omnimux"

[model_providers.omnimux]
name = "OmniMux API"
base_url = "https://api.omnimux.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
```

配置项说明：

* `model`：默认模型名称
* `model_reasoning_effort`：推理强度（按需调整）
* `model_provider`：绑定下方自定义 Provider 名称
* `base_url`：OmniMux API 接口地址
* `env_key`：读取 API Key 的环境变量名
* `wire_api`：必须为 `responses`

### 2. 配置 API Key

**临时设置（当前会话有效）**

```powershell theme={null}
$env:OPENAI_API_KEY = "你的 OmniMux API Key"
```

**永久设置**

```powershell theme={null}
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的 OmniMux API Key", "User")
```

设置后需要重启终端才能生效。

**检验配置**

```powershell theme={null}
echo $env:OPENAI_API_KEY
```

如果输出你的 API Key，说明配置成功。

**临时设置（当前会话有效）**

```bash theme={null}
export OPENAI_API_KEY="你的 OmniMux API Key"
```

**永久设置**
编辑 `~/.bashrc` 或 `~/.zshrc`，添加：

```bash theme={null}
export OPENAI_API_KEY="你的 OmniMux API Key"
```

然后执行 `source ~/.bashrc` 或 `source ~/.zshrc` 使配置生效，或重启终端。

**检验配置**

```bash theme={null}
echo $OPENAI_API_KEY
```

如果输出你的 API Key，说明配置成功。

## 第三步：开始使用 Codex CLI

### 1. 进入工作目录

```shell theme={null}
cd 你的工作目录
```

**说明：** 将 `你的工作目录` 替换为实际路径

### 2. 启动交互模式

```shell theme={null}
codex
```

### 3. 验证配置

```shell theme={null}
codex "你是谁"
```

**成功标志：**

* 看到 AI 的回复内容（几行文字）
* **没有**出现 `401`、`403`、`API Key invalid` 等错误

**如果看到错误：**

* `401 Unauthorized`：API Key 未设置或无效 → 检查环境变量
* `403 Forbidden`：API Key 权限不足 → 检查 API Key 是否正确
* `Network error`：网络问题 → 检查网络连接

## 常见问题

### 1. Codex CLI 是什么？主要用来做什么？

Codex CLI 是 OpenAI 官方推出的命令行工具，专注于代码相关任务。相比通用对话工具，它更强调工程化输出，能以更清晰的结构给出可直接落地的代码与修改建议。

### 2. 第一次使用时，如何确认是否已经安装并配置成功？

依次执行以下命令验证：

* `node -v` 和 `npm -v`：确认 Node.js 和 npm 已安装
* `codex --version`：确认 Codex CLI 已安装
* `codex "你是谁"`：确认 API 配置正确，能正常返回响应

### 3. 交互模式和单次命令模式有什么区别？

* **交互模式**：执行 `codex` 进入持续对话，可多轮交互，适合复杂任务
* **单次命令模式**：执行 `codex "问题"` 获取单次响应后退出，适合快速查询

### 4. Codex CLI 会不会自动读取或上传我本地的文件和代码？

不会自动读取或上传。Codex CLI 需要用户主动引用或授权才会读取文件内容，且会在执行敏感操作前请求确认。建议在专门的项目文件夹中使用。

### 5. 如何使用 Codex CLI 分析或处理本地文件内容？

在交互模式中，可以通过以下方式引用文件：

* 直接输入文件路径让 Codex 读取
* 拖拽文件到终端窗口
* 复制粘贴文件内容

### 6. Codex CLI 是否支持中文输入和中文输出？

完全支持。Codex CLI 支持中文输入和输出，可以直接用中文提问并获得中文回答。

### 7. 执行后没有任何输出，可能是什么原因？

常见原因包括：

* 网络连接问题，无法访问 API 服务器
* API Key 无效或余额不足
* `base_url` 配置错误
* 防火墙或代理阻止了请求

### 8. 修改了配置文件或环境变量后，为什么没有生效？

* 需要重新启动终端或命令行窗口
* 检查 `config.toml` 文件格式是否正确（TOML 语法）
* 确认配置文件路径正确：
* Windows: `C:\Users\{用户名}\.codex\config.toml`
* macOS / Linux: `~/.codex/config.toml`

### 9. 使用时出现 401/403 错误一般是什么原因？

* **401 错误**：`OPENAI_API_KEY` 未设置或 API Key 无效
* **403 错误**：API Key 权限不足或已过期
* 请检查 `env_key` 是否与环境变量名称一致

### 10. Codex CLI 适合哪些使用场景？又不适合哪些场景？

**适合的场景：**

* 代码编写、调试和重构
* 命令行环境下的快速问答
* 文件内容分析和处理
* 自动化脚本集成

**不适合的场景：**

* 需要图形界面的复杂交互
* 实时协作编辑
* 大规模文件批量处理

### 11. 如何切换模型？

打开配置文件 `config.toml`（位于 `~/.codex/config.toml` 或 `C:\Users\{用户名}\.codex\config.toml`），修改 `model` 字段：

```toml theme={null}
model = "gpt-5.2"  # 将模型名称改为你想使用的模型
```

修改后保存文件，重新启动 Codex CLI 即可生效。

### 12. 怎么上传图片？

* 方法一：直接引用图片路径
* 方法二：拖拽图片进终端
* 方法三：直接粘贴

以上方式均需用户主动操作，Codex CLI 不会自动读取或上传本地图片。

### 13. 如何打开命令行终端？

* 方法一：按 `Win + R` 键，输入 `cmd` 或 `powershell`，按回车

* 方法二：在开始菜单搜索"命令提示符"或"PowerShell"

* 方法三：在文件夹中按住 Shift 键，右键点击空白处，选择"在此处打开 PowerShell 窗口"

* 方法一：按 `Command + 空格` 打开 Spotlight，输入 `Terminal`，按回车

* 方法二：在"应用程序" → "实用工具" → "终端"

* 方法一：按 `Ctrl + Alt + T` 快捷键

* 方法二：在应用程序菜单中搜索"终端"或"Terminal"

## 注意

建议在专门的项目文件夹内启动 Codex CLI，避免在敏感目录（如系统目录、包含密钥的目录）中运行。Codex CLI 会以当前工作目录为起点进行文件操作。

配置文件中的 `wire_api` 必须设置为 `"responses"`，`"chat"` 已被弃用。