Codex 客户端配置

Codex 客户端是 OpenAI 的桌面应用。它可以直接登录 ChatGPT，也可以用 API Key 走本地 Codex 工作流。新手最容易混淆的是：官方账号登录、OpenAI API Key、中转站 Key 不是一回事。

官方信息 下载和文档以官方站点为准

官方文档 Codex 官方入口 认证与 Key ChatGPT 登录和 API Key 登录 配置基础 config.toml、模型和 Provider Windows 客户端 Windows 下载和安装说明

先分清两种登录方式

这个页面只讲桌面客户端里和 Key、模型、Provider 有关的配置。命令行安装、终端命令和更完整的 CLI 用法放在 CLI 工具页面。

ChatGPT 登录API Key 登录config.toml模型选择自定义 Provider中转站 Key

方式	适合谁	Key 怎么处理
ChatGPT 登录	已经有 ChatGPT Plus / Pro / Business / Enterprise 等账号，希望直接使用官方 Codex。	按客户端登录引导登录账号，一般不需要手动填写 API Key。
OpenAI API Key 登录	想用 OpenAI Platform 账号按量计费，或本地工作流需要 API Key。	使用 OpenAI 控制台生成的 Key，不是中转站 Key。
中转站 / 代理服务	服务商给了自己的 API 地址、Key、模型名。	不要在官方 API Key 登录框里乱填；通常要通过 config.toml 配自定义 Provider。

Windows 文件管理器中的 Codex 配置目录截图：C:\Users\guoguo\.codex 和 config.toml

示例路径：C:\Users\你的用户名\.codex

Key 怎么配置

Codex 的本地配置目录叫 .codex。Windows 客户端使用 %USERPROFILE%\.codex，macOS / Linux 通常使用 ~/.codex。如果你只用 ChatGPT 登录，先不要手动写 Key；如果你用中转站或第三方服务商 Key，建议把 Key 放进系统环境变量，再让 config.toml 读取这个变量。

系统	配置文件	Key 建议放哪里
Windows	`%USERPROFILE%\.codex\config.toml`	用户环境变量，例如 `MZ_PROXY_API_KEY`。
macOS / Linux	`~/.codex/config.toml`	当前终端环境变量，确认成功后再按自己的系统习惯长期保存。
WSL	`~/.codex/config.toml`	WSL 有自己的 home，不会自动读取 Windows 的 `%USERPROFILE%\.codex`。

先临时测试 Key 下面只保留当前窗口临时生效的命令。确认能跑通后，再到系统环境变量或你熟悉的终端配置里长期保存。

PowerShell 临时测试

$env:MZ_PROXY_API_KEY = "你的_Key"

Terminal 临时测试

MZ_PROXY_API_KEY="你的_Key" codex "请只回复：配置成功"

不要把真实 Key 写进网页、截图、聊天记录或项目仓库。能用环境变量就不要直接把 Key 写进 config.toml。Windows 长期保存时，可以在系统“环境变量”里新增用户变量；macOS / Linux 长期保存方式取决于你实际使用的终端。

模型怎么配置

默认模型写在 config.toml 顶部。官方文档当前推荐从 gpt-5.5 开始；如果你使用中转站，就填服务商后台模型列表里用于 API 调用的那串名称。它可能被后台叫作“模型 ID”“模型名”或“模型名称”，都要原样复制，不要自己改大小写、横线或点号。

模型配置示例

model = "gpt-5.5"

模型配置示例

model = "服务商后台显示的模型 ID 或模型名" model_provider = "mz_proxy"

字段	怎么填	容易错的地方
model	模型 ID / 模型名，也就是后台模型列表里用于 API 调用的原始标识。	把自己起的中文显示名当成模型标识，或自己改了大小写、横线和点号。
model_provider	选择下面定义的 Provider ID。	写了 Provider 表，但这里没有切过去。
openai_base_url	只在你要改内置 OpenAI Provider 的请求地址时使用。	把它和自定义 Provider 混用，导致请求走错。
wire_api	一般使用 `responses`。	服务商不支持 Responses API 时可能无法正常使用。

中转站 Provider 怎么配置

中转站配置的核心是三件事：模型名、Base URL、Key 环境变量。如果你的服务商提供 OpenAI 兼容接口，优先让它支持 Responses API；只支持旧 Chat Completions 的服务商，后续兼容性会更差。

Provider 配置示例

model = "服务商后台显示的模型 ID 或模型名" model_provider = "mz_proxy" [model_providers.mz_proxy] name = "某某中转站" base_url = "https://你的服务商API地址" env_key = "MZ_PROXY_API_KEY" wire_api = "responses"

Provider 配置示例

model = "gpt-5.5" model_provider = "openai" openai_base_url = "https://你的OpenAI代理API地址"

如果你用的是中转站自己的 Key，更推荐“自定义 Provider 示例”这一种；如果只是企业代理、数据驻留或 OpenAI 官方项目的转发地址，才考虑 openai_base_url。

检查项	正确做法	不正确做法
Base URL	复制服务商后台给出的 API 地址，是否带 `/v1` 看服务商说明。	把网站首页、控制台首页当 API 地址。
Key	使用环境变量名，例如 `MZ_PROXY_API_KEY`。	把 Key 直接写进项目文件或截图发出去。
Provider ID	自己起一个英文 ID，例如 `mz_proxy`。	使用 `openai`、`ollama`、`lmstudio` 这类保留 ID。
模型 ID / 模型名	复制后台模型列表里用于 API 调用的原始标识。	用自己起的显示名、套餐名或凭印象猜的名字。

客户端设置里先看这些

打开 Codex 客户端设置后，左侧会按“个人、集成、编码、已归档”分组。新手先从常规开始，主要确认工作模式、权限范围、默认打开位置、终端和语言；模型、Key、Provider 仍然回到前面的 config.toml 配置部分处理。

设置项	图里是什么意思	新手建议
工作模式	选择 Codex 回复时显示多少技术细节。适用于编程会更偏代码和控制，适用于日常工作会减少技术细节。	做代码配置、排查报错时选“适用于编程”；只是写文案或整理内容时选“适用于日常工作”。
默认权限	允许 Codex 读取并编辑当前工作区里的文件；需要访问工作区外的内容时再请求额外权限。	保持默认即可。每次授权前看清楚它要访问哪里。
自动审核	Codex 可以自动判断一部分额外访问权限请求，但页面里也提醒自动审核可能会出错。	新手不确定时先关闭，改为自己逐次确认；熟悉后再按需要开启。
完全访问权限	让 Codex 无需审批就能编辑电脑上的任何文件并运行联网命令，风险明显更高。	不要默认开启。只有在你明确知道后果，并且当前任务确实需要时再临时打开。
默认打开目标	决定客户端默认打开文件或文件夹时使用哪个应用。截图里显示的是 Antigravity。	选你平时实际用的编辑器或工作区，不确定就先保持当前值。
集成终端 Shell	决定 Codex 在集成终端里使用 PowerShell、CMD、Git Bash 等哪一种 Shell。	Windows 新手优先用 PowerShell，除非教程明确要求其他终端。
语言	控制客户端界面语言。截图里是自动检测。	想保持中文说明，就选择中文或自动检测。
底部面板 / 默认终端位置	控制底部面板是否显示，以及终端标签页默认出现在底部还是右侧。	按屏幕大小选择：笔记本一般放底部，宽屏可以放右侧。
代码审查	决定启动 `/review` 时是在当前对话中审查，还是拆成单独的审查对话。	新手先用“行内视图”，上下文更集中。
建议提示	根据项目文件和已连接应用，提示下一步可以做什么。	可以打开；如果觉得打扰，再关闭。

验证和排查

改完 Key、模型或 Provider 后，重启客户端，新建一个测试线程。先不要让它改文件，只让它确认当前项目和模型能正常工作。

首次验证提问模板

请先说明你能看到哪些文件。 不要修改任何文件，也不要运行命令。 请只回复当前项目是否可读，以及你正在使用的模型 ID / 模型名。

现象	通常原因	怎么处理
提示没有 Key 或认证失败	环境变量没生效，或客户端还没重启。	重新打开终端/客户端；Windows 用新窗口检查环境变量。
模型不可用	模型 ID / 模型名写错，或服务商没有开通该模型。	回到服务商后台复制模型列表里的原始标识。
404 / endpoint not found	Base URL 路径不对，常见是 `/v1` 多了或少了。	按服务商文档确认 API 地址，不要猜。
请求走到官方 OpenAI	Provider 没切到自定义 ID，或用了 `openai_base_url` 但不是这个场景。	检查 `model_provider` 是否等于你的 Provider ID。
WSL 里生效，Windows 客户端不生效	Windows 和 WSL 使用不同的 `.codex` 目录。	确认你改的是客户端实际读取的那个配置文件。

如果你只是用官方 ChatGPT 登录，不需要先配置中转站 Key。只有当你明确要走 API Key、企业代理或第三方服务商时，才需要改 config.toml。

权限与安全

Codex 客户端可以读取项目文件，也可能根据你的确认修改文件、执行检查或打开页面查看。新手最重要的是先看清楚它要做什么，再允许它继续。

位置	要重点看什么	新手建议
审批提示	是否要修改文件、运行检查或访问外部服务。	看不懂就先拒绝，让 Codex 用中文解释原因。
文件改动	新增、删除、修改了哪些文件。	提交前逐个看 diff，不要只看总结。
项目范围	当前线程绑定的是哪个本地项目。	确认不是旧项目或测试项目。
Worktree	是否在隔离副本里改动。	不确定风险时优先用隔离副本。
浏览器页面查看	打开的是不是本地开发页面。	涉及账号、付款、后台权限时自己手动确认。