Codex 官方安装与国内使用教程：Windows/macOS/Linux + codex login 一次跑通（TaoToken 统一 Key 版）

1. 为什么你的 Codex CLI 装完还是跑不起来Codex CLI 是 OpenAI 官方推出的终端编程代理能在项目目录里读代码、改文件、跑测试、排查报错适合习惯命令行、SSH 服务器、VS Code 或 Cursor 工作流的开发者。但很多人第一次装它卡点根本不在安装本身而在装完之后codex login那一步浏览器授权走不通、登录态写不进去、auth.json找不到、Base URL 不知道填哪。这篇就按 Windows、macOS、Linux 三平台从零把安装到登录校验整条链路走一遍最后用一条最小请求确认登录真的成功了。先说清楚一个容易混的点Codex 有 App、CLI、IDE extension 三个入口。App 适合桌面用户打开文件夹直接用CLI 适合终端、服务器、编辑器集成IDE extension 适合想在编辑器里直接调用的人。本文聚焦 CLI因为它是三平台通用、最容易自动化、也最容易踩坑的那条路。如果你只是想在电脑上点开就用装 App 也行但一旦涉及 SSH、CI、脚本化改代码CLI 是绕不开的。另一个高频误区是把 ChatGPT Plus/Pro 订阅和 API Key 计费混为一谈。codex login走的是账号授权流程而 API Key 是另一套计费体系。国内用户经常在这两者之间来回切换结果登录态和额度对不上。本文的做法是安装用官方 standalone installer登录态统一走 TaoToken 的 Key这样三平台配置一致auth.json里填的东西也统一排查问题时不用再猜是账号问题还是网络问题。下面按「先装、再配、后验」的顺序展开。每一步都给可复制的命令和配置片段你照着敲就行。装之前建议先确认一件事你的终端能正常执行curlmacOS/Linux或 PowerShell 能跑irmWindows这是后面所有步骤的前提。2. 三平台安装 Codex CLI 与 TaoToken 前置准备2.1 macOS / Linux 官方安装命令打开终端直接跑官方 standalone installercurl -fsSL https://chatgpt.com/codex/install.sh | sh装完检查版本codex --version能看到版本号就说明 CLI 装好了。如果提示command not found先关掉当前终端再开一个新的多数情况是 PATH 还没刷新。Linux 服务器上如果用的是非 bash shell比如 zsh记得把安装脚本输出的 PATH 行加到对应的 rc 文件里。2.2 Windows 安装方式Windows 优先用 PowerShell管理员或普通权限都行irm https://chatgpt.com/codex/install.ps1 | iex装完同样检查codex --version如果提示「不是内部或外部命令」先关掉当前 PowerShell 窗口重新开一个新的再试。这一步能解决八成 Windows 找不到命令的问题因为环境变量刷新需要新会话。还是不行的话去安装目录确认codex.exe是否存在再手动把目录加进系统 PATH。2.3 WSL2 与备用安装方式如果你在 WSL2 的 Ubuntu 里写代码直接在 WSL2 终端里跑 Linux 那条安装命令即可不要用 Windows 侧的 PowerShell 装否则登录态和项目路径会对不上。本机已经配好 Node.js 或 Homebrew 的话也可以用备用方式npm install -g openai/codexbrew install codex但新手我更建议先用官方 standalone installer它不依赖你本机 npm 或 Homebrew 是否配好少一层变量。2.4 TaoToken 前置拿 Key 与确认 Base URL安装只是第一步真正让 Codex CLI 在国内稳定跑起来的是登录态配置。这里统一用 TaoToken 的 Key三平台配置一致。先去控制台创建 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys创建完把 Key 复制出来形如sk-xxxx。Base URL 统一用https://taotoken.net/api注意这个地址后面不加 UTM 参数配置里就写干净的https://taotoken.net/api。Model ID 按你实际要用的填比如gpt-5-codex这类编码模型。这三件套——Base URL、Key、Model ID——后面在auth.json和config.toml里都要用到先记好。提示Key 只显示一次创建后立刻复制保存。丢了就重新建一个不要到处找。3. 可复制配置auth.json 与 config.toml 片段Codex CLI 的登录态和模型配置分两个文件管auth.json存凭证config.toml存模型和 provider 设置。三平台路径不一样下面分别给。3.1 配置文件路径对照平台auth.json 路径config.toml 路径macOS / Linux~/.codex/auth.json~/.codex/config.tomlWindows%USERPROFILE%\.codex\auth.json%USERPROFILE%\.codex\config.tomlWSL2~/.codex/auth.json~/.codex/config.toml如果.codex目录不存在先手动建mkdir -p ~/.codexWindows PowerShellNew-Item -ItemType Directory -Force -Path $env:USERPROFILE\.codex3.2 auth.json 配置片段把下面内容写进auth.json把sk-xxxx换成你自己的 Key{ OPENAI_API_KEY: sk-xxxx, OPENAI_BASE_URL: https://taotoken.net/api }这个文件是登录态的核心。codex login走官方账号授权时会写这个文件但我们这里直接用 Key 方式省掉浏览器授权那一步国内环境更稳。3.3 config.toml 配置片段config.toml管模型和 provider写进对应路径model gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key OPENAI_API_KEY wire_api responses这里model_provider指向下面定义的taotokenbase_url和auth.json里的保持一致env_key告诉 CLI 从环境变量或auth.json读 Key。wire_api按你用的模型接口类型填编码模型一般用responses。3.4 环境变量方式可选不想写文件的话也可以直接设环境变量。macOS/Linuxexport OPENAI_API_KEYsk-xxxx export OPENAI_BASE_URLhttps://taotoken.net/apiWindows PowerShell$env:OPENAI_API_KEYsk-xxxx $env:OPENAI_BASE_URLhttps://taotoken.net/api但环境变量方式每次开新终端都要重设长期用还是写进auth.json更省事。两种方式不要同时用否则容易互相覆盖排查时说不清哪个生效。注意auth.json和config.toml里的 Base URL 必须一致都写https://taotoken.net/api不要一个带斜杠一个不带也不要一个带 UTM 一个不带。4. 验证请求一条最小命令确认登录成功配置写完先别急着进项目。用一条最小请求确认登录态真的生效了。4.1 先跑 codex login 校验在终端执行codex login如果你已经用 Key 方式配好auth.json这一步会直接读取现有凭证不再弹浏览器授权。看到类似「already logged in」或直接进入交互提示就说明登录态被识别了。如果它仍然弹浏览器说明auth.json没被读到检查路径和 JSON 格式。4.2 最小请求验证进一个空目录跑一条最简单的非交互请求codex exec print hello或者用交互模式codex进入后输入一句简单指令比如让它解释当前目录。如果模型正常返回内容说明 Base URL、Key、Model ID 三件套全部生效。返回内容里如果带模型名确认是你配置的gpt-5-codex而不是默认模型。4.3 成功结果长什么样正常返回大概是这样终端先打印请求信息然后流式输出模型回复最后回到提示符。整个过程没有 401、没有连接超时、没有reading choices之类的报错。这时候你可以进真实项目目录试cd your-project codex让它读一个文件、改一行代码、跑一次测试。能正常读写文件说明登录态和工具调用都通了。4.4 用模型对话页交叉验证如果 CLI 里返回异常想确认是 Key 问题还是 CLI 配置问题可以去 TaoToken 的模型对话页发一条同样的请求模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat对话页能正常返回说明 Key 和 Base URL 没问题问题在 CLI 配置对话页也报错那就是 Key 或额度的问题。这个交叉验证能帮你快速定位故障层。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth下面这几个报错是实测下来最高频的逐个对照。5.1 401 Unauthorized报错长这样401 Unauthorized: Incorrect API key provided原因基本是 Key 写错、Key 失效、或者auth.json没被读到。排查顺序先确认auth.json路径对不对Windows 是%USERPROFILE%\.codex\auth.json不是当前目录再确认 JSON 格式合法可以用cat ~/.codex/auth.json看一眼最后确认 Key 没有多余空格或换行。如果 Key 是从控制台复制的注意别把前后引号也复制进去。5.2 local proxy failed报错类似local proxy failed: connection refused这个通常是 Base URL 写错或网络层不通。先确认config.toml和auth.json里的 Base URL 都是https://taotoken.net/api没有多余路径。然后确认本机网络能正常访问该地址。如果用了环境变量检查是不是环境变量和文件里的值冲突了。5.3 reading choices 相关报错报错类似error reading choices: unexpected end of JSON input这个多半是接口返回了非预期格式常见原因是wire_api配错。编码模型一般用responses如果你填成了chat或其他值返回结构对不上就会报这个。改回wire_api responses再试。另外 Model ID 写错也可能触发类似错误确认model字段是你实际可用的模型名。5.4 OAuth 授权失败如果你走的是codex login浏览器授权流程可能遇到OAuth callback failed / browser not opened国内环境浏览器授权链路容易断。最稳的做法是直接改用 Key 方式把auth.json写好跳过 OAuth。这样不依赖浏览器回调也不受账号风控影响。如果你确实需要账号授权流程确认浏览器能正常打开授权页再重新执行codex login。5.5 Windows 找不到 codex 命令codex is not recognized as an internal or external command先关掉当前 PowerShell 重开一个新的让 PATH 刷新。还不行就去安装目录确认codex.exe存在手动把目录加进系统环境变量 PATH。加完记得重开终端。5.6 三件套自查清单出现任何报错先按这个清单过一遍检查项正确值Base URLhttps://taotoken.net/apiKeysk-开头无空格无引号Model ID如gpt-5-codex与实际可用模型一致auth.json 路径对应平台的~/.codex/auth.jsonconfig.toml 路径对应平台的~/.codex/config.tomlwire_apiresponses这六项对上了九成报错都能解决。剩下的一成去接入文档对照最新配置接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc6. 长期编码与 Agent 工作流把 Codex CLI 用顺安装和登录跑通只是起点。Codex CLI 真正好用的地方是在项目目录里持续做代码修改、测试、排查。这里给几个实测下来比较顺的用法。6.1 在项目里跑交互模式进项目目录直接codex它会读取当前目录上下文你可以让它解释某个文件、改一个函数、跑测试。第一次进大项目建议先让它「列出项目结构并解释主要模块」确认它读到的上下文符合预期再让它动代码。6.2 非交互模式做自动化CI 或脚本里用codex execcodex exec run tests and summarize failures这种模式适合把 Codex 接进自动化流程比如提交前跑一遍检查。注意非交互模式不会等你确认改文件前最好先让它输出计划。6.3 长期编码用 Coding Plan如果你打算把 Codex CLI 当日常编码工具长期高频调用建议走 Coding Plan额度更稳Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan6.4 Claude Code 用户接入参考如果你同时用 Claude Code接入方式类似Base URL 和 Key 三件套一致具体配置看文档Claude Code 接入https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode-anthropic6.5 几个实用技巧第一auth.json和config.toml改完不用重启终端但codex进程要重开才读新配置。第二多项目切换时Codex 读的是当前工作目录cd到哪就读哪别在根目录乱跑。第三Key 泄露了立刻去控制台吊销重建别拖。第四Windows 和 WSL2 的配置是两套别混用否则登录态对不上。装好、配好、验证过后面就是把它接进你自己的工作流。先把这条链路跑通再谈效率提升。