Codex APP 国内使用教程：安装、配置

qq_35624199

168人浏览 · 2026-05-07 22:43:03

qq_35624199 · 2026-05-07 22:43:03 发布

本文适合想在国内环境中使用 OpenAI Codex APP 的开发者。相比命令行版本，Codex APP 更像一个桌面端“AI 开发工作台”：可以管理多个项目、并行跑多个任务、查看 Git diff、开启 Worktree、预览网页、使用插件和自动化。
下文会用一个兼容 OpenAI API 的通用服务商配置作为示例。实际使用时，请以你自己的账号、控制台说明和服务条款为准。

在这里插入图片描述

1. Codex APP 是什么

Codex 是 OpenAI 面向软件开发场景推出的 AI 编程智能体。它不是传统意义上的“代码补全插件”，而是可以进入项目目录，读取文件、理解上下文、修改代码、运行命令、执行测试，并根据终端结果继续迭代。

如果你之前用过 Codex CLI，应该会发现命令行版本已经很强：打开终端、进入项目目录、输入任务，它就能开始干活。但命令行有一个天然问题：很多状态都藏在文本里，任务多了以后不容易管理，diff、权限、项目、线程、浏览器预览这些东西也需要你在不同工具之间来回切。

Codex APP 的优势就在这里。它把 Codex 从“终端里的一个命令”变成了一个桌面端 AI 开发工作台，更适合日常高频使用：

对比点	Codex CLI	Codex APP
项目管理	需要自己 `cd` 到不同目录	左侧直接管理多个项目
多任务	多开终端或多开会话	一个界面里管理多个对话线程
Git diff	依赖命令行或编辑器查看	APP 内直接查看改动和提交
权限确认	主要看终端提示	图形界面里确认读写、命令和联网权限
Worktree	需要自己理解并操作 Git worktree	更直观地创建隔离环境做功能开发
前端预览	终端启动服务，再切浏览器	可以在 APP 里配合浏览器检查页面
插件和自动化	需要额外配置和记命令	左侧入口更清晰，适合新手探索

所以我更建议新手从 Codex APP 入门：它保留了命令行版本能读项目、改代码、跑测试的能力，同时把项目切换、任务管理、权限控制和结果检查做得更可视化。尤其是在国内环境里，配置 API 中转、排查模型请求、查看错误信息时，有一个稳定的桌面入口会省心很多。

你可以让它做这些事：

先不要修改任何文件。请阅读当前项目结构，说明技术栈、启动方式、测试方式和核心模块。

也可以让它直接修复问题：

运行测试并定位失败原因。请先说明问题，再修改代码，最后重新运行相关测试。

或者让它开发一个完整功能：

为用户模块增加邮箱验证码登录。保持现有代码风格，补充必要测试，并总结修改了哪些文件。

如果你平时经常做重构、修 Bug、补测试、写文档、迁移旧项目，Codex APP 会比单纯聊天工具更顺手，因为它能直接进入代码仓库工作。

2. 安装前准备

建议先准备下面这些东西：

环境	说明
Codex APP	桌面端主程序，Windows / macOS 可用性以官网页面为准
Git	用于查看 diff、创建分支、提交代码
API token	国内环境建议使用中转站 token
一个测试项目	建议先用非生产项目熟悉权限和工作流

Windows 用户可以打开 PowerShell 检查：

git --version

macOS 用户可以打开终端检查：

git --version

其他运行时按项目实际技术栈准备即可。Codex APP 本身不要求你提前安装某一种特定语言环境。

3. 下载和安装 Codex APP

打开 OpenAI Codex 官方页面：

https://openai.com/codex/

根据自己的系统下载 Codex APP。不同系统的下载入口、灰度范围和版本更新可能会变化，以官网页面实际展示为准。下载时建议只从 OpenAI 官方页面进入，避免使用来路不明的安装包。

3.1 Windows 安装

Windows 用户最简单的方式是直接打开 Microsoft Store 安装。OpenAI 官方文档目前给出的 Windows 安装方式是：

Microsoft Store 下载：https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi
或者使用 winget：

winget install Codex -s msstore

如果 Microsoft Store 打不开，可以先从 OpenAI 官方页面进入下载入口，再跳转到商店安装。安装完成后，开始菜单里应该能看到 Codex。

3.2 macOS 安装

macOS 用户需要根据芯片类型选择安装包：

Apple Silicon 芯片，例如 M1 / M2 / M3 / M4：下载 Apple Silicon 版本。
Intel 芯片：下载 Intel 版本。

如果你不确定自己是哪种芯片，可以点击左上角苹果图标，进入“关于本机”查看。下载完成后，打开安装包，把 Codex 拖进“应用程序”目录即可。

第一次打开时，macOS 可能会提示这是从互联网下载的应用，确认来源是 OpenAI 官方下载后再打开。

3.3 是否需要现在打开 APP

如果你可以正常登录 ChatGPT，可以直接打开 Codex APP，然后选择 ChatGPT 登录。登录成功后，就能先用官方账号体验 Codex。

但本文主要针对国内无法稳定登录 ChatGPT、或者希望走 API 中转的环境。对于这种情况，安装完成后不用急着打开 APP，更建议先按下一节准备 API token，并在本机写好 config.toml。配置完成后再打开 Codex APP，可以少走很多登录失败、模型请求失败的弯路。

配置完成后，第一次打开 APP 通常会看到类似下面的界面：

左侧：快速对话、搜索、技能、插件、自动化、项目列表。
中间：当前线程的输入框和任务区域。
右侧或顶部：模型、权限、工具、Git、终端等入口。

先把安装和配置分开理解，会更清楚：这一节只负责把 Codex APP 安装到电脑上，下一节才开始解决国内环境最关键的 API token 和中转配置。

4. 准备 API Token

国内环境使用 Codex APP，API Token 这一节是关键。实际配置时，大家通常会遇到三个问题：

ChatGPT 登录和官方 API 访问可能不稳定。
模型请求需要稳定的 base_url 和 API token。
桌面 APP、CLI、IDE 插件共用一套 Codex 配置，路径和文件名写错就会导致配置不生效。

所以本文按“API Key + 自定义模型提供商”的方式配置，整体流程如下：

安装 Codex APP。
准备 API token。
创建或修改 ~/.codex/config.toml。
在 Codex APP 中添加项目。
选择模型和权限模式。
用 Local / Worktree 模式开始开发。

文中的配置示例使用一个兼容 OpenAI Responses API 的服务控制台：

如果你的控制台显示了不同的接口地址、模型名或 token 格式，以控制台页面为准。

实际配置前，你需要拿到三个信息：

API token。
API 地址，例如 https://codex.tokenshop.pro/v1。
当前账号可用的模型名。

如果你使用第三方兼容服务，建议先确认服务条款、价格、稳定性和数据处理方式。本文只演示配置方法，具体服务请按自己的需求选择。

注意：API token 不要公开，不要提交到 Git 仓库，也不要放到博客截图里。下面示例统一使用 sk-xxx 作为占位符。

下面以这个示例 API 控制台为例：

https://codex.tokenshop.pro/

大致流程是：

打开控制台。
登录或注册账号。
创建一个用于 Codex 的 API token。
复制 token，后面写入环境变量或本机配置。
查看控制台提供的 API 地址，例如 https://codex.tokenshop.pro/v1。

如果你使用的是其他兼容服务，逻辑也类似：拿到 token、确认 base_url、确认模型名，然后写入 Codex 配置。

5. 配置 Codex APP 的 config.toml

Codex APP、Codex CLI 和 Codex IDE 插件会共享本机 Codex 配置。用户级配置文件一般在：

Windows：

C:\Users\你的用户名\.codex\config.toml

macOS / Linux：

~/.codex/config.toml

如果 .codex 目录不存在，就手动创建一个。

5.1 推荐配置：环境变量保存 token

先设置环境变量。Windows PowerShell：

[Environment]::SetEnvironmentVariable("TOKENSHOP_API_KEY", "sk-xxx", "User")

设置后关闭并重新打开 Codex APP。

macOS / Linux 可以写入 shell 配置文件：

export TOKENSHOP_API_KEY="sk-xxx"

如果从图形界面启动的 APP 读取不到 shell 环境变量，可以临时从终端启动 APP 测试，或者改用系统级环境变量管理方式。

然后编辑 config.toml：

model = "gpt-5.5"
model_provider = "tokenshop"
model_reasoning_effort = "high"
forced_login_method = "api"
[model_providers.tokenshop]
name = "TokenShop"
base_url = "https://codex.tokenshop.pro/v1"
wire_api = "responses"
env_key = "TOKENSHOP_API_KEY"

说明：

model：模型名，按你的控制台可用模型填写。
model_provider：当前使用哪个模型提供商。
model_reasoning_effort：推理强度，常用 medium / high / xhigh。
forced_login_method = "api"：让 Codex 优先走 API Key 方式。
base_url：API 接口地址，注意通常要带 /v1。
wire_api = "responses"：Codex 当前配置里常用 Responses API 协议。
env_key：从哪个环境变量读取 token。

5.2 临时排错配置：直接写 token

如果你只是本机测试，环境变量一直读取不到，可以临时用下面方式排查：

model = "gpt-5.5"
model_provider = "tokenshop"
model_reasoning_effort = "high"
forced_login_method = "api"
[model_providers.tokenshop]
name = "TokenShop"
base_url = "https://codex.tokenshop.pro/v1"
wire_api = "responses"
experimental_bearer_token = "sk-xxx"

这种方式不适合团队环境，也不要把带 token 的配置截图发到博客、群聊或仓库里。确认能跑通后，建议改回环境变量方式。

6. 打开使用 Codex APP

前面的 API token 和 config.toml 配好以后，就可以打开 Codex APP 了。第一次进入时，建议先熟悉一下界面，不要急着把生产项目丢进去让它改代码。

6.1 主界面布局

Codex APP 的主界面大致分成三块：

左侧栏：快速对话、搜索、技能、插件、自动化、项目列表和对话列表。
中间区域：当前对话的输入框、任务过程、终端输出、修改说明等。
顶部或输入框附近：模型选择、权限模式、当前项目、发送按钮和工具入口。

左侧的“项目”是 Codex APP 很核心的概念。你可以把不同代码仓库添加成不同项目，以后切换项目时不需要在终端里反复 cd，也不需要记每个仓库的位置。

6.2 设置界面

在这里插入图片描述

Codex APP 的设置入口通常在左下角。第一次打开后建议先进去看一遍，先把“它用什么方式发请求”和“它能对本机做什么”这两件事确认清楚。

从截图里可以看到，左侧主要是功能导航，常用的有：

常规：最基础的应用设置。
配置：模型、供应商、登录方式等核心内容。
Git：和提交、分支、变更查看相关。
环境：运行环境和命令执行相关。
工作树：和 Git worktree 相关。
浏览器使用：前端预览和页面检查相关。
电脑操控：需要自动化操作桌面时再看。
MCP 服务器：接外部工具和服务时再看。

右侧顶部这两个开关最值得先认识：

自动审核：让 Codex 在工作区里更顺畅地读写和处理任务，但遇到高风险操作时仍会拦一下。
完全访问权限：权限最高，Codex 能更自由地改文件和跑命令，适合你非常清楚任务边界时使用。

如果你是第一次用，通常先别急着开最大权限。先用默认或自动审查，等你确认流程顺手了，再考虑完全访问权限。

在“常规”里，截图中能看到几个很实用的选项：

默认打开目标：默认用什么方式打开文件或文件夹，比如 PyCharm。
智能体环境：Codex 在 Windows 上的运行方式，截图里是 Windows 原生。
集成终端 Shell：默认终端壳层，截图里是 PowerShell。
语言：界面语言，截图里是中文（中国）。
弹出窗口快捷键：给弹窗设置全局快捷键，没必要可以先保持默认。
需要 ^ + 回车 发送长文本：长提示词时是否用快捷键发送。
跟进行为：Codex 运行时是排队、引导还是继续当前任务，这个更偏工作流习惯。

这些选项里，最建议先检查的是语言、终端 Shell 和默认打开目标。前两个决定你日常操作顺不顺，默认打开目标决定 Codex 跳转到哪个编辑器或工具。

如果你已经在 config.toml 中写了 forced_login_method = "api"，但 APP 里仍然提示登录账号，可以先完全退出 Codex APP，再重新打开。环境变量方式配置 token 时，也要注意修改环境变量后重启 APP。

不同版本的 Codex APP 设置项名称可能会变化，但核心思路不变：先确认“它用哪里发请求”，再确认“它能对本机项目做什么”。

6.3 无项目的纯对话功能

左侧的“快速对话”适合不绑定项目的普通问答。比如：

帮我解释一下 Git rebase 和 merge 的区别。

帮我写一段适合放在 README 里的项目介绍。

我遇到这个报错，请帮我分析可能原因：xxx

这种模式更像普通 ChatGPT 对话。它不会自动进入某个代码仓库，也不会天然知道你的项目文件内容。适合问概念、写文案、生成命令、分析报错、整理思路。

如果你希望 Codex 读取项目文件、修改代码、运行测试，就应该使用下面的“项目”功能。

6.4 添加项目

进入左侧“项目”区域，添加你的代码目录。建议第一次不要直接选择生产仓库，可以先准备一个小项目测试：

codex-demo
├─ README.md
├─ src
└─ tests

添加项目后，Codex 会以这个目录作为工作空间。它可以读取文件，也可以在你授权后修改文件、运行命令。

第一次使用建议发送：

先阅读当前项目，不要修改文件。请说明项目结构、技术栈、启动命令、测试命令和你建议的开发流程。

这一步很重要。先让 Codex 熟悉项目，再让它动手，效果会明显稳定很多。

7. Local、Worktree、Cloud 怎么选

Codex APP 新建线程时会有不同工作模式。常见选择如下：

模式	适合场景	说明
Local	小改动、读项目、修单个 Bug	直接在当前项目目录工作
Worktree	新功能、重构、并行尝试	创建独立 Git worktree，避免污染当前目录
Cloud	远程环境、长任务	依赖你的云环境配置

国内用户刚开始建议这样选：

读项目、问问题：Local。
真正改代码：优先 Worktree。
没有配置远程环境时，先不用 Cloud。

Worktree 的好处是可以把 Codex 的修改隔离开。比如你当前正在开发 A 功能，又想让 Codex 尝试 B 功能，用 Worktree 会更安全。

8. 权限怎么设置

Codex APP 在输入框附近可以选择权限模式。它决定 Codex 在本机项目里能自动做到什么程度。常见可以理解为三档：

权限模式	适合场景	特点
默认权限	新手入门、读项目、小改动	比较保守，关键操作会让你确认
自动审查	日常开发、修 Bug、补测试	Codex 可以更顺畅地修改和执行常规命令，但高风险操作仍会停下来让你审
完全访问权限	可信项目、临时快速迭代、你明确知道它要做什么	权限最大，效率最高，但也最需要你确认项目和任务边界

刚开始使用建议选择“默认权限”。这个模式最适合熟悉 Codex APP 的行为：让它先读项目、解释结构、给修改建议，小范围试一试它如何运行命令和修改文件。

如果你已经熟悉项目，也信任当前任务范围，可以用“自动审查”。这是我更推荐的日常模式，适合修 Bug、补测试、写文档、做小功能。它不会像默认权限一样频繁打断你，但关键地方仍然保留确认感。

“完全访问权限”只建议在你非常确定任务范围时使用，比如一个临时 demo、一个独立 Worktree、或者你已经准备好随时看 Git diff。不要在生产仓库、包含密钥的目录、数据库迁移任务里随手开完全访问权限。

简单选择方式：

第一次使用：默认权限。
日常写代码：自动审查。
独立 Worktree 里快速试验：可以考虑完全访问权限。
涉及删除、迁移、密钥、生产数据：不要用完全访问权限。

9. Codex APP 常用功能

9.1 Git diff 和提交

Codex APP 内置 Git 功能，可以查看改了哪些文件、哪些行发生变化，也可以 stage、commit、push，甚至创建 PR。

我的习惯是让 Codex 修改后先总结：

请总结本次修改涉及哪些文件、每个文件改了什么、为什么这样改，并提醒我需要重点 review 的地方。

然后自己看 diff。确认没问题后，再让它生成 commit message：

请根据当前 diff 生成一个简洁的英文 commit message，格式使用 Conventional Commits。

9.2 内置终端

每个线程都有自己的终端。你可以运行：

git status
pytest
go test ./...
cargo test

Codex 可以读取终端输出，所以当测试失败时，不需要你复制一大段日志给它。你可以直接说：

查看当前终端输出，定位测试失败原因，然后修复。

9.3 内置浏览器

如果你在做前端项目，可以启动本地开发服务器：

# 使用你的项目实际启动命令

然后在 Codex APP 的浏览器里打开本地地址，例如：

http://localhost:3000

你可以让 Codex 检查页面布局、截图验证、修复按钮错位、移动端适配等问题。

9.4 Skills 和插件

Codex APP 支持 Skills。简单理解，Skill 是一组专门任务说明、脚本和资源，比如：

生成图片素材。
处理表格。
制作演示文稿。
自动化浏览器测试。
按团队规范做代码审查。

当任务比较专业时，Skill 会比普通提示词更稳定。比如你要生成一张博客封面图，可以直接说：

$imagegen 生成一张适合 Codex APP 使用教程的博客封面图，风格简洁、科技感、不要出现真实品牌 Logo。

9.5 自动化

自动化适合重复任务，例如：

每天检查依赖更新。
定时查看 CI 失败原因。
每周总结项目变更。
定期扫描 TODO 或报错日志。

刚开始使用时不建议一上来配置太复杂的自动化，先从“让 Codex 在一个线程里定期提醒或检查”开始。

10. 国内环境常见问题

10.1 配置不生效

重点检查：

config.toml 是否在当前用户的 .codex 目录。
Windows 文件名是否变成了 config.toml.txt。
修改配置后是否重启 Codex APP。
model_provider 是否和 [model_providers.tokenshop] 的名字对应。
环境变量设置后是否重新打开 APP。

10.2 请求 401 或 unauthorized

常见原因：

token 写错。
token 已过期。
环境变量没有被 APP 读取到。
使用了错误的 API 控制台 token。

处理方式：

重新复制 token。
检查环境变量名是否和 env_key 一致。
重新打开 APP。
临时使用 experimental_bearer_token 排查是否是环境变量问题。

10.3 `model not found`

常见原因：

当前 token 不支持这个模型。
控制台显示的模型名和本地配置不一致。
Codex APP 或 CLI 版本较旧。

处理方式：

在控制台确认可用模型名。
把 model = "gpt-5.5" 改成控制台实际模型名。
确认 Codex APP 已更新到较新的版本。

10.4 能打开 APP，但一直请求失败

重点检查这段：

[model_providers.tokenshop]
name = "TokenShop"
base_url = "https://codex.tokenshop.pro"
wire_api = "responses"

base_url 要以控制台提供的地址为准。很多请求失败都是因为少了 /v1、多了路径、或者填成了网页控制台地址。

10.5 Windows 权限或命令执行失败

Windows 下建议优先使用 PowerShell。Codex APP 官方文档提到 Windows 可使用原生 PowerShell 和 Windows sandbox。遇到命令执行失败时，检查：

项目路径是否有中文或特殊字符。
PowerShell 执行策略是否限制脚本。
Git、Python、Java、Go 等项目命令是否加入 PATH。
当前线程是否有足够权限运行命令。

可以先让 Codex 执行只读命令：

请运行 git status 和当前项目的依赖检查命令，不要修改文件。

如果这类命令都失败，先处理本机环境。

11. 我自己的使用习惯

11.1 每个新项目先让 Codex 读一遍

先阅读项目，不要修改文件。请说明项目结构、核心模块、启动方式、测试方式、风险点和你建议我如何使用 Codex 开发这个项目。

11.2 大改动一定用 Worktree

请在 Worktree 模式下实现这个功能，完成后总结 diff，并说明如何合并回主分支。

11.3 让 Codex 自己验证

修改完成后，请运行相关测试。如果测试失败，先分析失败原因，再决定是否继续修改。

11.4 让 Codex 写“可 review 的总结”

请按下面格式总结：
1. 修改了哪些文件
2. 每个文件的核心变化
3. 已运行哪些验证命令
4. 还有哪些风险或需要人工确认的地方

11.5 不要把 token、密钥、生产数据交给它乱跑

Codex 是开发助手，不是权限管理工具。涉及 .env、数据库、云服务密钥、生产日志时，一定要注意脱敏和权限边界。

12. 适合放进收藏夹的提示词

读项目：

先不要修改任何文件。请阅读当前项目，说明技术栈、目录结构、启动命令、测试命令、核心业务模块和潜在风险。

修 Bug：

请复现并定位这个问题。先说明原因，不要急着修改。确认后再给出最小修改方案，并运行相关测试。

补测试：

请分析当前模块缺少哪些关键测试，只补最有价值的测试用例，保持现有测试风格，最后运行对应测试命令。

代码审查：

请以代码审查的方式检查当前 diff，优先指出可能导致线上问题的 bug、兼容性风险和缺失测试，不要纠结无关风格问题。

写文档：

请根据当前代码生成一份面向新开发者的 README，包含启动方式、环境变量、常见命令、目录说明和排错建议。

13. 关于中转站

如果你在国内环境里配置 Codex APP，最重要的不是先选某个具体服务，而是确认这个服务是否真的适合 Codex 的工作方式。

可以重点看这些信息：

是否支持 OpenAI Responses API。
是否能在 Codex APP、Codex CLI 或 IDE 插件里统一配置。
控制台是否清楚展示 base_url、模型名、额度和调用记录。
token 是否可以随时创建、禁用或重置。
价格、稳定性、隐私说明和服务条款是否足够清楚。

配置时记住三个值：

API token：在控制台创建
base_url：https://codex.tokenshop.pro
model：以控制台实际支持的模型名为准

如果你使用第三方 API 服务，建议先用非生产项目测试读项目、改文件、跑命令、看 diff 这一整条流程。确认稳定后，再考虑把它放进日常开发工作流。token 只在自己电脑上使用，不要发给别人，也不要放进公开仓库。

14. 总结

国内使用 Codex APP，可以按这个流程走：

安装 Codex APP。
准备 Git 和一个测试项目。
在 API 控制台创建 token。
配置 ~/.codex/config.toml。
设置 model_provider、base_url、wire_api = "responses" 和 token。
在 Codex APP 添加项目。
先让 Codex 读项目，再让它改代码。
真正开发功能时优先使用 Worktree。
修改后看 diff、跑测试、再提交。

Codex APP 最值得用的地方，不是“帮你生成几行代码”，而是让 AI 真正进入工程上下文，完成读代码、改代码、跑测试、看 diff、写总结这一整条链路。只要配置稳定、权限控制得当，它会是一个非常适合日常开发的 AI 工作台。

参考链接

OpenAI Codex：https://openai.com/codex/
Codex APP 官方下载说明：https://developers.openai.com/codex/app
Codex APP Windows 安装说明：https://developers.openai.com/codex/app/windows
Codex APP 官方功能说明：https://developers.openai.com/codex/app/features
Codex APP 设置说明：https://developers.openai.com/codex/app/settings
Codex 配置基础：https://developers.openai.com/codex/config-basic
Codex 配置参考：https://developers.openai.com/codex/config-reference
Codex 示例配置：https://developers.openai.com/codex/config-sample

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

YOLOv8【第十五章：遥感与无人机航拍篇·第15节】遥感领域的域泛化——如何让模型适应不同季节与光照的卫星图！

AtomGit开源社区

风光储与电解制氢系统仿真模型（光伏耦合PEM制氢）（Simulink仿真实现）

电解水制氢作为一种新型储能手段，可作为调整风光能源输出电力的绿色手段。该文以风力发电、光伏发电、电解制氢与燃料电池为研究对象，通过对风光互补发电系统与电解水制氢系统的输出输入功率进行建模仿真，协调优化控制风光电、电解槽、燃料电池以及系统负载的负荷变化要求，改善了风光发电电解水制氢系统与系统负荷之间的负荷不平衡问题，为风光豆补可再生能源系统的稳定运行提供了理论依据。关键词: 风力发电;光伏发电;风光