---
description: Codex 中文教程，完整讲解 Codex App 与 Codex CLI 在 Windows、macOS、Linux 上的安装选择、ChatGPT 登录、API 使用方式、gptapi.asia 端点配置、项目工作流和安全边界。
---

# Codex 中文教程：App、CLI、Windows、macOS、Linux 与 API 配置

![OpenAI Codex 官方欢迎页截图，包含 Continue with ChatGPT 与 Enter API key 两种入口](https://images.ctfassets.net/kftzwdyauwt9/6JttRtGUPpCuYGQvs0PCjP/9c54a8e25f76148598e903bed1bddac0/Installer2.png?fm=webp&q=90&w=3840)

这是一份独立的 Codex 中文教程，面向国内用户讲清楚三件事：

- Codex App 和 Codex CLI 分别适合什么场景。
- Windows、macOS、Linux 分别怎么安装和启动。
- ChatGPT 登录方式和 API 使用方式分别怎么配置。

ChatGPT 登录方式的购买入口：

```text
https://dev.hkgpt.top/shop/40
```

API 使用方式的 Base URL：

```text
https://gptapi.asia/v1
```

::: tip 选择建议
如果你只是想最快开始，Windows / macOS 用户先用 Codex App，Linux 用户先用 Codex CLI。
如果你需要自定义 Base URL、团队 API key、服务器环境或脚本化工作流，优先用 Codex CLI。
:::

## 先看结论

| 使用方式 | Windows | macOS | Linux | 适合人群 |
| --- | --- | --- | --- | --- |
| Codex App | 支持，Microsoft Store 或 `winget` | 支持，Apple Silicon / Intel 分版本 | 官方当前是可登记通知，日常建议先用 CLI | 想用桌面界面、多线程、工作树、Review 面板、自动化的人 |
| Codex CLI | 支持，PowerShell 原生或 WSL2 | 支持 | 支持 | 想在终端里读代码、改代码、跑命令、接入自定义 API 的人 |

需要注意：OpenAI 官方当前文档写明 Codex App 可用于 macOS 和 Windows；Linux 用户可以登记 Codex App 可用通知，但实际本地三平台稳定覆盖应优先走 Codex CLI。也就是说，Windows / macOS / Linux 都能使用 Codex 工作流，但不是每个平台都有同等的 App 安装包。

::: warning 关于 Linux App
这里保持中立客观：Linux 可以使用 Codex CLI；Codex App 的 Linux 版本以 OpenAI 官方后续发布为准。本文不会把尚未稳定提供的 Linux App 写成已可下载。
:::

## Windows 快速路线

Windows 用户不要只看 CLI。Codex 在 Windows 上有两条完整路线：

| 目标 | 推荐方式 | 说明 |
| --- | --- | --- |
| 想用桌面界面 | Codex App | 从 Microsoft Store 安装，或用 `winget install Codex -s msstore` |
| 项目在 Windows 文件系统 | App 或 CLI + PowerShell | 适合 `C:\Users\you\Projects\...` 这类路径 |
| 项目依赖 Linux 工具链 | App 配置 WSL2，或 CLI 装在 WSL2 | 适合 Bash、Docker、Linux 原生依赖较多的项目 |
| 需要自定义 API Base URL | 优先 CLI | 用 `OPENAI_BASE_URL` 或 `~/.codex/config.toml` 指向 `https://gptapi.asia/v1` |

Windows App 支持 PowerShell 原生代理，也可以切到 WSL2。官方文档还提醒：Git 功能需要 Windows 本机安装 Git；WSL2 和 Windows 原生路径不要混用同一个仓库，否则容易出现权限、换行、Git 状态或依赖缓存问题。

## 官方资料来源

本页按这些官方资料核对：

- [OpenAI Codex App 文档](https://developers.openai.com/codex/app)
- [OpenAI Codex CLI 文档](https://developers.openai.com/codex/cli)
- [OpenAI Codex Windows 文档](https://developers.openai.com/codex/windows)
- [OpenAI Codex App Windows 文档](https://developers.openai.com/codex/app/windows)
- [OpenAI Codex 认证文档](https://developers.openai.com/codex/auth)
- [OpenAI Codex 高级配置文档](https://developers.openai.com/codex/config-advanced)
- [OpenAI Codex App Linux 通知页](https://openai.com/form/codex-app/)

## Codex 是什么

Codex 是面向工程任务的 AI 编程智能体。它不是只回答问题的聊天框，而是可以在项目上下文里持续执行：

- 阅读仓库结构，解释入口文件、依赖关系和关键模块。
- 修改代码、生成补丁、运行测试或构建命令。
- 做代码 Review，指出风险、漏测、误改和敏感信息。
- 处理重复任务，例如问题 triage、CI 失败分析、文档生成和发布检查。
- 在 App、CLI、IDE、云端任务之间复用部分会话、配置和工作流。

对国内用户来说，更实用的理解是：Codex 是一个能进入项目目录工作的工程助手。你要重点掌握两条路径：

- `Codex App`：桌面工作台，适合多任务、Review、工作树、自动化和图形界面协作。
- `Codex CLI`：终端工具，适合本地仓库、脚本化、服务器环境、Linux 和自定义 provider。

## 安装前准备

开始前先准备：

1. 一个可测试的小项目目录，最好已经用 Git 管理。
2. Windows、macOS 或 Linux 中任意一个开发环境。
3. ChatGPT 登录方式，或 API 使用方式所需的 API key。
4. 如果走 CLI，准备 Node.js / npm；如果走 Windows 原生，建议准备 PowerShell、Git 和 `winget`。
5. 不要把真实 API key 写进源码、截图、Issue、公开聊天或文档。

## 第一部分：Codex App

![OpenAI Codex 官方 App 截图，展示项目侧边栏、线程和 Review 面板](https://developers.openai.com/images/codex/app/app-screenshot-light.webp)

Codex App 适合希望用桌面界面管理多个任务的人。它的优势是项目列表、线程、Review 面板、工作树、自动化、插件和技能更直观。官方文档说明 App 当前覆盖 macOS 和 Windows。

### App 平台支持

| 系统 | 当前建议 |
| --- | --- |
| macOS Apple Silicon | 使用官方 Apple Silicon 版本 |
| macOS Intel | 使用官方 Intel 版本 |
| Windows 11 | 推荐，使用 Microsoft Store 或 `winget` |
| Windows 10 新版本 | 尽量保持系统更新；部分沙箱和终端能力可能不如 Windows 11 |
| Linux | 当前使用 CLI；Codex App 官方提供可用通知登记 |

::: details App 安装入口怎么选
- macOS Apple Silicon：选 Apple Silicon 安装包。
- macOS Intel：选 Intel 安装包。
- Windows：优先 Microsoft Store；命令行用户可用 `winget install Codex -s msstore`。
- Linux：当前先用 CLI；需要 App 时可登记官方通知。
:::

### macOS 安装 App

1. 打开 [OpenAI Codex App 文档](https://developers.openai.com/codex/app)。
2. 根据机器选择 macOS Apple Silicon 或 macOS Intel 版本。
3. 下载后按 macOS 常规方式安装。
4. 第一次打开时，如果系统提示安全确认，按系统提示允许打开。
5. 打开后进入欢迎页，选择 `Continue with ChatGPT` 或 `Enter API key`。

判断 Apple Silicon / Intel 的方式：

- Apple 菜单 -> About This Mac。
- 芯片显示 `Apple M1 / M2 / M3 / M4...` 选 Apple Silicon。
- 处理器显示 Intel 选 Intel。

### Windows 安装 App

![OpenAI Codex 官方 Windows App 截图，展示项目侧边栏和线程界面](https://developers.openai.com/images/codex/windows/codex-windows-light.webp)

Windows 用户有两种安装方式。

方式一：Microsoft Store

1. 打开 [Codex App Windows 文档](https://developers.openai.com/codex/app/windows)。
2. 点击 Microsoft Store 的 Codex App 入口。
3. 安装完成后从开始菜单打开 Codex。

方式二：PowerShell / 命令行

```powershell
winget install Codex -s msstore
```

如果 PowerShell 执行 npm、脚本或工具时报错，例如提示脚本被禁用，通常是执行策略限制。可先只读确认当前策略：

```powershell
Get-ExecutionPolicy
```

确实需要放宽时，再按企业或个人安全要求决定是否设置：

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
```

Windows 上还要注意：

- 推荐 Windows 11。
- Git 功能需要本机安装 Git，可用 `winget install Git.Git`。
- App 可使用 PowerShell 原生沙箱，也可配置 WSL2。
- 如果项目本身在 WSL2 里，可以在 App 设置里把 agent 从 Windows native 切到 WSL2，并重启 App；也可以直接在 WSL2 里使用 CLI。
- 如果 App 和 WSL2 都要共用 Codex 配置，注意 Windows App 默认目录是 `%USERPROFILE%\.codex`，WSL2 CLI 默认目录是 Linux 用户的 `~/.codex`，两边不会天然共享。
- 不建议把同一个仓库同时作为 Windows 原生路径和 `\\wsl$` 路径反复打开。

### Linux 使用 App 的现实选择

OpenAI 当前提供的是 Codex App Linux 可用通知登记页，而不是稳定 Linux App 安装包。Linux 用户要马上使用 Codex，建议走 Codex CLI。

你可以这样安排：

- 需要图形桌面体验：在 Windows 或 macOS 使用 App。
- 需要 Linux 原生开发环境：在 Linux 上使用 CLI。
- 使用 Windows 但项目在 Linux 工具链中：用 WSL2 + CLI。

### App 方式一：ChatGPT 登录

![OpenAI Codex 官方选择项目截图，展示 Select your project 流程](https://images.ctfassets.net/kftzwdyauwt9/ke4GwvCgjA68qQlcrZYiH/85d0fdb04d3d0bdd1cf99f16fd82c263/Installer3.png?fm=webp&q=90&w=3840)

ChatGPT 登录适合希望用 ChatGPT 账号、工作区权限和订阅额度的人。Codex 充值入口使用：

```text
https://dev.hkgpt.top/shop/40
```

流程：

1. 打开 Codex App。
2. 点击 `Continue with ChatGPT`。
3. 浏览器打开后完成 ChatGPT 登录和授权。
4. 回到 App，选择一个本地文件夹或 Git 仓库作为项目。
5. 确认底部或项目设置里使用的是本地工作目录。
6. 第一次任务先让 Codex 只读分析项目，不要直接让它大范围修改。

示例第一句话：

```text
请只读分析这个项目。先说明目录结构、启动方式、主要风险和你建议我下一步验证的命令。不要修改文件。
```

### App 方式二：API 使用

官方 App 欢迎页提供 `Enter API key` 入口。OpenAI 官方 API key 用于 OpenAI Platform 计费；如果你使用自己的兼容服务或代理，需要确认当前 App 版本是否支持自定义 provider / Base URL。

::: tip API 方式的判断
能填 `Base URL` 的客户端，才适合直接接入 `https://gptapi.asia/v1`。
如果某个 App 只能填 OpenAI 官方 API key，不能改 Base URL，就不要硬写代理端点，改用 CLI 的 `config.toml` 自定义 provider。
:::

API 使用方式的 Base URL：

```text
https://gptapi.asia/v1
```

如果 App 或兼容客户端只要求 API key：

```text
YOUR_API_KEY
```

如果 App 或兼容客户端允许填写 Base URL：

```text
https://gptapi.asia/v1
```

如果它要求完整接口地址：

```text
https://gptapi.asia/v1/chat/completions
https://gptapi.asia/v1/responses
https://gptapi.asia/v1/messages
```

判断方式：

- ChatGPT 账号体验、云端线程、部分订阅能力：优先 ChatGPT 登录，并使用 `https://dev.hkgpt.top/shop/40`。
- 团队 key、兼容 API、脚本化调用：优先 API 使用方式。
- App 不支持自定义 Base URL：改用 CLI 的自定义 provider 配置。

## 第二部分：Codex CLI

Codex CLI 是三平台都应该掌握的方式。官方文档说明 CLI 可用于 macOS、Windows 和 Linux。Windows 可以原生 PowerShell 运行，也可以在 WSL2 里运行。

### CLI 支持矩阵

| 系统 | 安装方式 | 推荐运行环境 |
| --- | --- | --- |
| macOS | npm 全局安装 | Terminal、iTerm2、VS Code Terminal |
| Linux | npm 全局安装 | Bash、Zsh、服务器终端、容器环境 |
| Windows 11 | npm 全局安装 | PowerShell 原生，或 WSL2 |
| Windows 10 新版本 | npm 全局安装 | 优先 WSL2；原生 PowerShell 视系统能力而定 |

::: tip CLI 是三平台通用主线
只要能正常安装 Node.js / npm，Windows、macOS、Linux 都可以安装 Codex CLI。Windows 用户如果遇到原生沙箱、PowerShell 或路径问题，优先切到 WSL2。
:::

### macOS 安装 CLI

先确认 Node.js 和 npm：

```bash
node -v
npm -v
```

安装：

```bash
npm i -g @openai/codex
```

启动：

```bash
codex
```

升级：

```bash
npm i -g @openai/codex@latest
```

### Linux 安装 CLI

Linux 上推荐用系统包管理器或版本管理工具安装 Node.js，再安装 Codex CLI。

Ubuntu / Debian 常见流程：

```bash
node -v
npm -v
npm i -g @openai/codex
codex
```

如果 `codex` 命令找不到，检查 npm 全局 bin 路径：

```bash
npm bin -g
```

然后把对应路径加入 shell 的 `PATH`。

在服务器上使用 CLI 时，建议第一轮只让它只读分析，不要直接给写权限或部署权限：

```bash
codex
```

输入：

```text
请只读分析当前目录，不要修改文件，不要执行写操作，不要连接外部服务。
```

### Windows 安装 CLI：PowerShell 原生

先确认 Node.js / npm：

```powershell
node -v
npm -v
```

安装：

```powershell
npm i -g @openai/codex
```

启动：

```powershell
codex
```

升级：

```powershell
npm i -g @openai/codex@latest
```

如果 PowerShell 报 `npm.ps1 cannot be loaded`，先确认执行策略，再决定是否调整：

```powershell
Get-ExecutionPolicy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
```

Windows 原生模式适合项目就在 Windows 文件系统里，例如：

```text
C:\Users\you\Projects\my-app
```

### Windows 安装 CLI：WSL2

如果你的项目依赖 Linux 工具链，或本来就在 WSL2 中开发，建议直接在 WSL2 里安装 CLI：

```bash
node -v
npm -v
npm i -g @openai/codex
codex
```

项目路径建议放在 Linux 文件系统里，例如：

```text
/home/you/projects/my-app
```

不要频繁在 Windows 原生路径和 WSL2 路径之间来回切同一个仓库，否则容易遇到权限、换行、Git 状态和依赖缓存问题。

### CLI 方式一：ChatGPT 登录

第一次运行 `codex` 时，CLI 会提示登录。官方认证文档说明 Codex 支持两种 OpenAI 登录方式：

- ChatGPT 登录：使用 ChatGPT 订阅、工作区权限和相关策略。
- API key 登录：使用 API Platform 计费和组织策略。

ChatGPT 登录方式的 Codex 充值入口：

```text
https://dev.hkgpt.top/shop/40
```

常规流程：

```bash
codex
```

按提示选择 ChatGPT 登录后：

1. 浏览器会打开登录页。
2. 完成 ChatGPT 登录和授权。
3. 浏览器把 token 返回给 CLI。
4. 终端进入 Codex 交互界面。

如果你在无浏览器环境、远程服务器或 localhost 回调被拦截的环境中登录，可以使用设备码方式：

```bash
codex login --device-auth
```

然后按终端提示在浏览器打开链接并输入一次性代码。

### CLI 方式二：API 使用

API 使用方式的 Base URL：

```text
https://gptapi.asia/v1
```

最简单的环境变量方式：

```bash
export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://gptapi.asia/v1"
codex
```

Windows PowerShell：

```powershell
$env:OPENAI_API_KEY="YOUR_API_KEY"
$env:OPENAI_BASE_URL="https://gptapi.asia/v1"
codex
```

如果你的 Codex CLI 版本使用配置文件管理 provider，可编辑：

```text
~/.codex/config.toml
```

示例：

```toml
model = "YOUR_MODEL_NAME"
model_provider = "gptapi"

[model_providers.gptapi]
name = "gptapi.asia"
base_url = "https://gptapi.asia/v1"
env_key = "OPENAI_API_KEY"
```

然后设置 key：

```bash
export OPENAI_API_KEY="YOUR_API_KEY"
codex
```

Windows PowerShell 对应：

```powershell
$env:OPENAI_API_KEY="YOUR_API_KEY"
codex
```

配置原则：

- `base_url` 固定写 `https://gptapi.asia/v1`。
- `env_key` 指向保存 key 的环境变量名，不要把真实 key 明文写进项目配置。
- 项目级 `.codex/config.toml` 只放非敏感默认值。
- 真实 key 只放在系统环境变量、凭据管理器或本机安全位置。

::: warning 不要把 key 写进文档或仓库
示例中的 `YOUR_API_KEY` 只是占位符。真实 key 不要写入 Markdown、截图、Git 提交、Issue、工单或聊天记录。
:::

## API 请求示例

OpenAI Chat Completions 兼容格式：

```bash
curl https://gptapi.asia/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "messages": [
      {
        "role": "user",
        "content": "用三句话解释这个项目的主要功能。"
      }
    ]
  }'
```

OpenAI Responses 风格端点：

```bash
curl https://gptapi.asia/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "input": "请阅读当前需求，并给出最小可回滚实现方案。"
  }'
```

Claude Messages 官方格式：

```bash
curl https://gptapi.asia/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "max_tokens": 800,
    "messages": [
      {
        "role": "user",
        "content": "请先阅读需求，再给出最小修改方案。"
      }
    ]
  }'
```

## 第一次进入项目

![OpenAI Codex 官方首次任务截图，展示 Tell codex what to do 输入框](https://images.ctfassets.net/kftzwdyauwt9/IWLhh4SZnwPrLYHfYbZYS/99c1f79ceece96c9fa9650bdcb0d2023/Installer4.png?fm=webp&q=90&w=3840)

进入项目根目录：

```bash
cd /path/to/your-project
codex
```

第一次建议使用只读提示：

```text
请只读分析当前项目，不要修改文件。

请输出：
1. 项目类型和主要技术栈。
2. 启动、构建、测试命令。
3. 关键目录和入口文件。
4. 当前最可能的风险点。
5. 如果我要让你改一个小需求，应该先提供哪些信息。
```

确认它理解项目后，再给小范围任务：

```text
目标：修复登录页在移动端按钮溢出的问题。
范围：只允许改登录页组件和相关样式。
禁止：不要改鉴权逻辑，不要重构全局布局，不要新增 UI 库。
验证：修改后运行类型检查，并说明 375px 宽度下如何验证。
```

## 常用工作流

### 读代码

```text
请只读分析这个仓库。先给我目录结构，再解释核心业务流程。不要修改文件。
```

### 改小需求

```text
请先定位相关文件，再给出修改计划。确认影响范围后，只改必要文件。
```

### 排障

```text
这是报错日志。请先判断最可能的 3 个原因，再设计最小复现和验证步骤。不要直接改代码。
```

### 测试

```text
请运行项目已有测试。如果失败，先总结失败点和相关文件，不要立刻重写测试。
```

### Review

```text
请以代码 Review 方式检查当前 diff。优先找 bug、回归风险、漏测和敏感信息。
```

### 写文档

```text
请根据当前实现补充用户文档。要求步骤可执行，示例使用占位符，不暴露真实 key。
```

## 安全边界

必须遵守：

- 不把真实 API key、token、证书、数据库连接串粘进公开对话。
- 不把 `~/.codex/auth.json`、环境变量、私钥或内部配置提交到仓库。
- 不让 Codex 在没有影响范围和回滚方案时部署、删库、重启服务或改服务器配置。
- 不把客户数据、用户隐私、内部文档上传到未经批准的平台。
- 不让它为了省事整包重构、批量替换或删除未知文件。
- 涉及支付、订单、购买、权限、后台、数据库、网关、Nginx、Cloudflare 时，先只读分析，再决定是否执行。

如果你不确定某个操作是否安全，就直接这样写：

```text
请只读分析，不要修改文件，不要执行写操作，不要连接外部服务。
```

## 常见问题

### 1. 购买入口在哪里？

ChatGPT 登录方式使用：

```text
https://dev.hkgpt.top/shop/40
```

### 2. API 使用方式的 Base URL 填什么？

统一使用：

```text
https://gptapi.asia/v1
```

### 3. App 和 CLI 该选哪个？

- 想用桌面界面、多任务、Review 面板：选 App。
- 想在 Linux、服务器、终端、脚本或 WSL2 里工作：选 CLI。
- 想接自定义 provider / Base URL：优先选 CLI。
- 想用 OpenAI 官方 ChatGPT 订阅和云端能力：优先 ChatGPT 登录。

### 4. Linux 能不能装 Codex？

能使用 Codex CLI。官方 App 当前是 macOS 和 Windows；Linux App 官方提供可用通知登记。Linux 用户现在最稳定的路径是 CLI。

### 5. Windows 用 PowerShell 还是 WSL2？

项目在 Windows 文件系统、工具链也在 Windows：用 PowerShell 原生。

项目依赖 Linux 工具链、Docker、Bash 脚本或本来就在 WSL2：用 WSL2。

### 6. 为什么登录后终端没有继续？

可能是浏览器回调被拦截，或远程环境无法访问本地回调端口。可以改用：

```bash
codex login --device-auth
```

### 7. 为什么 API 请求返回 401？

优先检查：

1. API key 是否完整。
2. Header 是否正确。
3. Base URL 是否写成 `https://gptapi.asia/v1`。
4. 当前客户端是否真的支持自定义 Base URL。

### 8. 为什么 API 请求返回 404？

通常是路径拼错：

- Chat Completions：`/v1/chat/completions`
- Responses：`/v1/responses`
- Claude Messages：`/v1/messages`

### 9. 能不能让 Codex 直接改线上服务器？

不要默认这么做。先让 Codex 只读分析问题，列出影响范围、回滚方式和最小修改路径。只有确认风险后，再授权具体命令和具体路径。