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

OpenAI Codex 官方欢迎页截图，包含 Continue with ChatGPT 与 Enter API key 两种入口

这是一份独立的 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

选择建议

如果你只是想最快开始，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 安装包。

关于 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 状态或依赖缓存问题。

官方资料来源

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

Codex 是什么

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

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

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

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

安装前准备

开始前先准备：

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

第一部分：Codex App

OpenAI Codex 官方 App 截图，展示项目侧边栏、线程和 Review 面板

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 官方提供可用通知登记

App 安装入口怎么选

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

macOS 安装 App

打开 OpenAI Codex App 文档。
根据机器选择 macOS Apple Silicon 或 macOS Intel 版本。
下载后按 macOS 常规方式安装。
第一次打开时，如果系统提示安全确认，按系统提示允许打开。
打开后进入欢迎页，选择 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 截图，展示项目侧边栏和线程界面

Windows 用户有两种安装方式。

方式一：Microsoft Store

打开 Codex App Windows 文档。
点击 Microsoft Store 的 Codex App 入口。
安装完成后从开始菜单打开 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 流程

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

text

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

流程：

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

示例第一句话：

text

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

App 方式二：API 使用

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

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 视系统能力而定

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 登录后：

浏览器会打开登录页。
完成 ChatGPT 登录和授权。
浏览器把 token 返回给 CLI。
终端进入 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 只放在系统环境变量、凭据管理器或本机安全位置。

不要把 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 输入框

进入项目根目录：

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？

优先检查：

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

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

通常是路径拼错：

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

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

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

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

先看结论 ​

Windows 快速路线 ​

官方资料来源 ​

Codex 是什么 ​

安装前准备 ​

第一部分：Codex App ​

App 平台支持 ​

macOS 安装 App ​

Windows 安装 App ​

Linux 使用 App 的现实选择 ​

App 方式一：ChatGPT 登录 ​

App 方式二：API 使用 ​

第二部分：Codex CLI ​

CLI 支持矩阵 ​

macOS 安装 CLI ​

Linux 安装 CLI ​

Windows 安装 CLI：PowerShell 原生 ​

Windows 安装 CLI：WSL2 ​

CLI 方式一：ChatGPT 登录 ​

CLI 方式二：API 使用 ​

API 请求示例 ​

第一次进入项目 ​

常用工作流 ​

读代码 ​

改小需求 ​

排障 ​

测试 ​

Review ​

写文档 ​

安全边界 ​

常见问题 ​

1. 购买入口在哪里？ ​

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

3. App 和 CLI 该选哪个？ ​

4. Linux 能不能装 Codex？ ​

5. Windows 用 PowerShell 还是 WSL2？ ​

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

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

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

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

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

先看结论

Windows 快速路线

官方资料来源

Codex 是什么

安装前准备

第一部分：Codex App

App 平台支持

macOS 安装 App

Windows 安装 App

Linux 使用 App 的现实选择

App 方式一：ChatGPT 登录

App 方式二：API 使用

第二部分：Codex CLI

CLI 支持矩阵

macOS 安装 CLI

Linux 安装 CLI

Windows 安装 CLI：PowerShell 原生

Windows 安装 CLI：WSL2

CLI 方式一：ChatGPT 登录

CLI 方式二：API 使用

API 请求示例

第一次进入项目

常用工作流

读代码

改小需求

排障

测试

Review

写文档

安全边界

常见问题

1. 购买入口在哪里？

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

3. App 和 CLI 该选哪个？

4. Linux 能不能装 Codex？

5. Windows 用 PowerShell 还是 WSL2？

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

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

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

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