# Codex CLI 接入 LYRouter：安装、配置与故障排查

来源: https://platform.lyrouter.com/ai_gateway/docs/codex
更新日期: 2026-10-14

Codex CLI 可以通过自定义模型服务接入 LYRouter。本文从安装前提开始，说明如何配置并完成第一次调用。

已安装应用？直接查看[配置 LYRouter](#配置-lyrouter)。

## 前提条件

本页针对 Codex CLI 的自定义模型提供商接入，采用 npm 安装方式。选择操作系统，准备 Node.js LTS / npm、联网环境及用户全局安装目录写权限；模型服务需要支持 Responses。

**选择操作系统**

Windows:
#### 1. 选择终端环境

可在 **PowerShell** 中原生运行 Codex CLI；项目和依赖位于 WSL 时，在 WSL 终端运行，并按 Linux 页签准备环境。Windows 的运行与隔离方式参见[官方 OpenAI 文档](https://developers.openai.com/codex/windows/)。

#### 2. 准备 Node.js 与 npm

未安装时，先按[快速开始的环境准备](https://platform.lyrouter.com/ai_gateway/docs/quickstart)安装 Windows Node.js LTS，重新打开 PowerShell 后检查：

```powershell
node --version
npm.cmd --version
npm.cmd config get prefix
```

确认显示了版本号，且全局安装目录可写。Windows 使用 `npm.cmd`，避免 PowerShell 对 `npm.ps1` 的执行策略限制。

Linux:
#### 1. 准备终端与项目目录

在 **Bash** 终端运行，准备可读写的本地项目目录、联网环境及用户级工具安装目录。先检查系统与架构：

```bash
cat /etc/os-release
uname -m
```

#### 2. 准备 Node.js 与 npm

未安装时，按[快速开始的 Linux 环境准备](https://platform.lyrouter.com/ai_gateway/docs/quickstart)安装 Node.js LTS，再检查：

```bash
node --version
npm --version
npm config get prefix
```

使用可写的用户级安装目录；安装权限问题先检查 Node.js / npm 的路径与安装方式。

macOS:
#### 1. 准备终端与项目目录

打开 **终端（Terminal）**，使用 Bash / Zsh，准备可读写的项目目录及联网环境：

```bash
sw_vers -productVersion
uname -m
```

#### 2. 准备 Node.js 与 npm

未安装时，按[快速开始的 macOS 环境准备](https://platform.lyrouter.com/ai_gateway/docs/quickstart)安装 Node.js LTS；确认 PATH 已配置后检查：

```bash
node --version
npm --version
npm config get prefix
```

本页使用 npm 路径；使用官方独立安装器或 Homebrew 的用户以[官方 CLI 指南](https://developers.openai.com/codex/cli/)为准。

接入 LYRouter 还需要一把已启用的 API Key 和当前工作空间可用的模型。示例中的 `MODEL_ID` 必须替换为实际系统模型标识；工具账号与 LYRouter 账号是两个独立身份。

## 安装应用

**按系统安装**

Windows PowerShell:
```powershell
npm.cmd install -g @openai/codex@latest
codex --version
```

Linux / WSL:
```bash
npm install -g @openai/codex@latest
codex --version
```

macOS:
```bash
npm install -g @openai/codex@latest
codex --version
```

安装后重新打开终端并检查版本。采用其他安装方式时，参见下方官方指南。

## 配置 LYRouter

在 `~/.codex/config.toml` 合并自定义提供商配置：

```toml
model = "MODEL_ID"
model_provider = "lyrouter"

[model_providers.lyrouter]
name = "LYRouter"
base_url = "https://api.lyrouter.com/v1"
env_key = "LYROUTER_API_KEY"
wire_api = "responses"
```

当前官方配置中 `wire_api` 只支持 `responses`，不使用旧的 `chat` 值。密钥放入配置指定的环境变量：

**设置密钥**

macOS / Linux / WSL:
```bash
export LYROUTER_API_KEY="YOUR_LYROUTER_API_KEY"
codex
```

Windows PowerShell:
```powershell
$env:LYROUTER_API_KEY="YOUR_LYROUTER_API_KEY"
codex
```

模型和来源必须实际支持[Responses](https://platform.lyrouter.com/ai_gateway/docs/responses-api)，选择 Chat-only 来源会导致调用失败。

## 验证首次调用

启动应用，显式选择刚配置的模型，发送“请回复 OK”这样的最小任务。再到 LYRouter 的[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)检查生成端点、状态和实际模型。连接测试成功不等于完整生成或工具调用已通过。

## 日常使用与故障排查

### 安装后提示找不到命令，怎么办？

**答：** 重新打开终端，执行本页安装步骤中的版本检查命令，并核对安装目录是否在 PATH 中。使用与安装步骤一致的终端和运行环境；仍不可用时，按官方安装指南检查安装结果。

### Base URL 和调用协议应该如何配置？

**答：** 本页的 `base_url` 使用 `https://api.lyrouter.com/v1`，`wire_api` 使用 `responses`。确认选择了 `lyrouter` 提供商，且模型与服务来源支持[Responses](https://platform.lyrouter.com/ai_gateway/docs/responses-api)；不要在地址中重复添加 `/v1`。

### 切换模型前需要检查什么？

**答：** 确认新模型已在当前工作空间启用、至少有一个有效服务来源，并支持应用所需的协议和工具能力。使用系统模型标识，不使用展示名称。

### 应用更新后，原来的配置为什么不生效？

**答：** 先核对当前应用版本和实际读取的配置位置，再对照本页“配置 LYRouter”检查提供商、地址、密钥和模型。不同版本的配置要求以本页链接的官方资料为准。

### 请求返回 401 / 403，应该先检查什么？

**答：** 确认填写的是已启用的 LYRouter API Key，并检查该 Key 所属工作空间的模型来源与访问策略。结合具体错误和日志判断拒绝来源，详见[鉴权与权限 FAQ](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)。

### 请求返回 429，反复重试有用吗？

**答：** 先确认是平台限制还是上游额度耗尽，再调整并发、调用频率或资源配置。使用有上限的退避重试，避免立即密集重试，详见[限流与配额 FAQ](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。

### 应用有回复，但 LYRouter 日志里找不到请求，怎么办？

**答：** 确认当前生效的是本页配置的 LYRouter 提供商和模型，并核对网关地址。用最小生成任务验证后，在正确工作空间按时间和 Key 查询[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)。仅拉取模型列表不会出现在普通调用列表中。

## 官方资料

下列要求和安装方式来自工具官方资料，后续版本以官方说明为准。

- [Codex CLI](https://developers.openai.com/codex/cli/)
- [当前配置参考](https://developers.openai.com/codex/config-reference/)
- [Codex 开源仓库与 npm 安装说明](https://github.com/openai/codex)