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

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

本页介绍官方 ChatGPT 桌面应用的本地工作模式（Codex）如何配置 LYRouter 模型服务，参见[官方网关配置指南](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)。网页版聊天不读取本机的 `config.toml`，以下配置适用于桌面应用的本地工作。

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

## 前提条件

本页使用官方桌面应用的本地工作（Codex）。准备联网环境、可写的用户配置目录，以及与当前操作系统和处理器匹配的官方安装包；桌面应用安装无需先安装 Codex CLI。

**选择操作系统**

Windows:
使用官方 Windows 桌面应用，准备 PowerShell 和安装权限。从[官方 Windows 指南](https://learn.chatgpt.com/docs/windows/windows-app)进入下载入口；采用命令行安装时先确认 `winget` 可用：

```powershell
winget --version
```

本页按原生 Windows 环境配置；WSL 中的 CLI 使用独立的 Linux 用户目录，不自动共享本页配置。

Linux:
官方 Linux 桌面应用目前为预览版。按[官方 Linux 指南](https://learn.chatgpt.com/docs/linux/linux-app)确认发行版和处理器受支持，准备图形桌面、终端及软件包安装权限：

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

根据发行版选择 `.deb`、`.rpm` 或官方 Arch 安装路径；按 x64 / ARM64 选择对应包。

macOS:
从[官方桌面应用入口](https://learn.chatgpt.com/docs/app)选择适合设备的安装包；当前页面提供 Apple Silicon 下载入口。准备终端及应用安装目录写权限，检查系统与架构：

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

下载前以官方页面列出的系统和处理器要求为准。

LYRouter 侧需要一把已启用的 [API Key](https://platform.lyrouter.com/ai_gateway/docs/api-keys)，以及该 Key 所属工作空间中支持 [Responses](https://platform.lyrouter.com/ai_gateway/docs/responses-api) 的可用模型和服务来源。应用账号与 LYRouter 账号分别管理权限。

## 安装应用

**按系统安装**

Windows:
从[官方 Windows 指南](https://learn.chatgpt.com/docs/windows/windows-app)进入 Microsoft Store 下载并安装，也可以在 PowerShell 中执行官方命令：

```powershell
winget install --id 9PLM9XGG6VKS -s msstore
```

安装完成后，从开始菜单打开 ChatGPT。

Linux:
从[官方 Linux 指南](https://learn.chatgpt.com/docs/linux/linux-app)下载对应架构的安装包。Ubuntu / Debian 的 x64 示例：

```bash
cd ~/Downloads
sudo apt install ./chatgpt_amd64.deb
chatgpt
```

ARM64 使用 `chatgpt_arm64.deb`。Fedora 的 x64 示例：

```bash
cd ~/Downloads
sudo dnf install ./chatgpt.x86_64.rpm
chatgpt
```

ARM64 使用 `chatgpt.aarch64.rpm`。Arch 安装按官方指南执行。

macOS:
1. 在[官方桌面应用页面](https://learn.chatgpt.com/docs/app)下载 macOS 安装包。
2. 打开安装包，将应用放入“应用程序”目录。
3. 从“应用程序”打开 ChatGPT，完成首次启动提示。

确认应用能正常打开，在应用中进入本地工作（Codex）并准备本地项目或文件夹；随后按下节配置 LYRouter。

## 配置 LYRouter

### 1. 配置模型服务

打开用户级配置文件，合并以下内容。已有相同配置项时修改原值，不要重复添加。

| 系统 | 配置文件 |
| --- | --- |
| macOS / Linux | `~/.codex/config.toml` |
| Windows | `%USERPROFILE%\.codex\config.toml` |

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

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

- 将 `MODEL_ID` 替换为当前工作空间可用、支持 [Responses](https://platform.lyrouter.com/ai_gateway/docs/responses-api) 的系统模型标识，详见[模型命名与查询](https://platform.lyrouter.com/ai_gateway/docs/model-names)。
- `model`、`model_provider` 和 `web_search` 放在第一个 TOML 表头之前。
- `base_url` 包含 `/v1`，不填写控制台地址或完整的 `/v1/responses` 端点。
- 首次配置关闭网页搜索；需要启用时先确认模型及来源支持对应能力。

### 2. 设置 API Key

将已启用的 LYRouter [API Key](https://platform.lyrouter.com/ai_gateway/docs/api-keys) 设置为 `LYROUTER_API_KEY`。密钥由应用进程的环境变量提供，不写入项目配置或仓库。

**设置密钥**

macOS:
在终端执行以下命令，然后完全退出桌面应用并重新打开：

```bash
launchctl setenv LYROUTER_API_KEY "YOUR_LYROUTER_API_KEY"
```

该设置用于当前登录会话；重新登录后需重新设置。

Windows:
在 PowerShell 中设置用户环境变量：

```powershell
[Environment]::SetEnvironmentVariable("LYROUTER_API_KEY", "YOUR_LYROUTER_API_KEY", "User")
```

重新登录 Windows 后再打开桌面应用，使启动进程读取新的用户环境变量。

Linux:
在启动桌面应用的终端中执行：

```bash
export LYROUTER_API_KEY="YOUR_LYROUTER_API_KEY"
chatgpt
```

通过桌面图标启动时，需要在应用的启动环境中设置该变量；仅在另一个终端执行 `export` 不会传给已经运行的应用。

## 验证首次调用

完全退出并重新打开 ChatGPT 桌面应用，在本地工作中新建任务，确认生效的模型服务为 `LYRouter`、模型为配置的 `MODEL_ID`。发送“请只回复 OK”，再到 LYRouter [请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)按时间和 API Key 确认实际调用。

## 日常使用与故障排查

### 安装后应用无法打开，怎么办？

**答：** 确认使用官方安装包，并检查操作系统与处理器架构。Linux 还需确认发行版受支持、安装的软件包正确且图形桌面可用。按本页“官方资料”中的对应系统指南核对安装结果。

### 修改配置后，为什么没有使用 LYRouter？

**答：** 确认进入桌面应用的本地工作（Codex），配置写入用户级 `config.toml`；检查是否选中了其他配置档，顶层 `model` 和 `model_provider` 是否放在第一个表头之前。完全退出并重新启动应用后再验证。网页版聊天不读取本机配置。

### Base URL 和模型应该怎么填写？

**答：** `base_url` 使用 `https://api.lyrouter.com/v1`，`wire_api` 使用 `responses`。模型填写工作空间可用的系统标识，并确认至少有一个支持 Responses 的有效来源；不填写展示名称，也不重复拼接 `/v1`。详见[模型命名与查询](https://platform.lyrouter.com/ai_gateway/docs/model-names)和 [Responses](https://platform.lyrouter.com/ai_gateway/docs/responses-api)。

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

**答：** 确认 Key 已启用，`LYROUTER_API_KEY` 已传入桌面应用进程。macOS 重新登录后需重新设置本页的会话环境变量；Windows 设置用户变量后需重新登录再打开应用。再检查 Key 的工作空间模型权限，详见[鉴权与权限 FAQ](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)。

### 请求返回 429，怎么办？

**答：** 先确认是限流、预算限制还是上游额度问题，再调整调用频率、并发或资源配置。避免连续密集重试，详见[限流与配额 FAQ](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。

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

**答：** 检查当前任务生效的模型服务、模型标识和网关地址，再按正确工作空间、调用时间和 Key 查询[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)。使用最小文本任务验证实际生成请求，不能只凭应用回复判断接入成功。

## 官方资料

安装方式、支持环境和配置项以后续官方 OpenAI 文档为准。

- [ChatGPT 桌面应用与 macOS 下载入口](https://learn.chatgpt.com/docs/app)
- [Windows 安装指南](https://learn.chatgpt.com/docs/windows/windows-app)
- [Linux 安装指南](https://learn.chatgpt.com/docs/linux/linux-app)
- [模型网关配置](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)
- [配置项参考](https://learn.chatgpt.com/docs/config-file/config-reference)