Codex 新手入门：从安装到高效使用，把 auth.json 改到 TaoToken

1. 刚装完 Codex CLI 就卡在登录先搞懂 auth.json 到底管什么很多人第一次接触 Codex CLI流程都差不多终端里敲一行npm i -g openai/codexlatest装完输入codex然后就被一个登录界面拦住了。官方默认走的是 ChatGPT 账号授权浏览器弹出来、点确认、回到终端看起来挺顺。但真到团队协作、多环境切换、或者想接自己的模型服务时这套默认登录就开始别扭了——尤其是当你想把请求指向 TaoToken 这类兼容 OpenAI 协议的服务时auth.json就成了绕不开的核心文件。先把概念理清楚。Codex CLI 是 OpenAI 推出的命令行编程助手能读代码库、执行命令、改文件、跑测试适合喜欢在终端里干活的开发者。它有三种形态CLI、IDE 扩展VS Code、Cursor、Windsurf 等、桌面 App。三者共用同一套配置目录默认在~/.codex/Windows 是%USERPROFILE%\.codex\。这个目录里有两个关键文件config.toml管模型、推理强度、审批模式这些行为参数auth.json管身份凭证也就是你以什么身份、往哪个地址发请求。新手最容易混淆的地方在于以为登录一次就万事大吉。实际上 Codex 的凭证来源有好几种——ChatGPT OAuth 登录、API Key、环境变量。当你用codex login走完浏览器授权凭证会写进auth.json当你想换成 API Key 模式同样要落到这个文件里。所以把 auth.json 改到 TaoToken这件事本质是让 Codex 不再往默认端点发请求而是走你指定的 Base URL并用你提供的 Key 做鉴权。这一步为什么值得单独写一篇因为 401 报错几乎全出在这里。Key 写错、字段名写错、Base URL 少了/v1、文件权限不对、环境变量把文件里的值覆盖了——任何一个都能让你对着401 Unauthorized发呆半小时。下面我会把路径、字段模板、验证步骤、排错清单一次讲透你照着做就能跑通。适合谁看刚装完 Codex CLI 还没成功发出第一个请求的新手想把 Codex 接到自建或第三方兼容端点的开发者在 VS Code 里装了 Codex 扩展但一直转圈的人。读完你能独立完成 auth.json 配置并用一次真实调用确认它生效。2. 动手前的前置准备TaoToken 的 Key、Base URL 和 Codex 版本对齐在改auth.json之前有三样东西必须先拿到手否则后面全是空转。第一样是 API Key。去 TaoToken 控制台创建一个格式通常是一串以特定前缀开头的长字符串。创建后立刻复制保存很多平台只显示一次。这个 Key 就是你auth.json里的核心凭证等价于密码别提交到 Git别贴进聊天记录。第二样是 Base URL。Codex 走的是 OpenAI 兼容协议所以端点地址要写成https://taotoken.net/api这种形式。注意这里有个高频坑不同工具对/v1的处理不一样。有的客户端要求你写https://taotoken.net/api它自己补/v1/chat/completions有的要求你直接写到https://taotoken.net/api/v1。Codex 属于前者还是后者取决于你用的版本和配置方式后面配置章节我会给出实测可用的写法并告诉你如果报 404 该怎么调。第三样是确认 Codex 版本。终端里跑codex --version如果版本太旧auth.json的字段结构可能和新版不一致。建议升到较新的稳定版npm i -g openai/codexlatest升级完再跑一次codex --version确认。顺带说一句Node 版本也别太老建议 18 以上否则 npm 全局安装可能报奇怪的错。接下来定位配置目录。macOS / Linuxls -la ~/.codex/Windows PowerShelldir $env:USERPROFILE\.codex\如果目录不存在手动建一个mkdir -p ~/.codex目录里你可能会看到config.toml、auth.json、history.jsonl之类的文件。auth.json如果不存在等会儿我们直接创建。这里有个细节Codex 对文件权限比较敏感尤其在 macOS / Linux 上auth.json最好设成只有当前用户可读chmod 600 ~/.codex/auth.json权限太开放有时会触发安全校验虽然不一定是 401 的直接原因但属于该做的卫生习惯。还有一点要提前想清楚你是打算全局用 TaoToken还是只在某个项目里用Codex 默认读用户级配置也就是~/.codex/。如果你只想在特定项目生效可以在项目根目录放一个.codex/目录做局部覆盖但新手阶段建议先用全局配置跑通减少变量。最后确认网络能通。在终端里直接测一下端点可达性curl -I https://taotoken.net/api能返回 HTTP 状态码就说明网络层没问题。如果这里就卡住那后面所有配置都白搭先解决连通性。把 Key、Base URL、版本、目录、权限、连通性这六项确认完再进入下一步。很多人跳过这步直接改文件结果 401 和 404 混在一起根本分不清是凭证问题还是地址问题。3. 可复制的 auth.json 与 config.toml 配置模板含 VS Code 验证这一节是全文的核心给你能直接抄的配置。先明确一个原则Codex 的凭证和行为是分开管的auth.json放 Key 和端点config.toml放模型和运行参数。两者配合才完整。先看auth.json。用编辑器打开或新建~/.codex/auth.json写入下面这个结构{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api }字段说明OPENAI_API_KEY填你在 TaoToken 控制台创建的 KeyOPENAI_BASE_URL填https://taotoken.net/api。注意 JSON 里不能有注释不能有多余逗号字符串必须用双引号。这是新手最常翻车的地方——从文章里复制时带了个中文引号或者末尾多了个逗号解析直接失败。有些 Codex 版本对字段名更严格可能要求写成嵌套结构或带tokens字段。如果你写完上面这版仍然 401可以试下面这个更完整的形态{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api, tokens: { access_token: sk-你的TaoToken密钥, token_type: Bearer } }这个版本同时提供了扁平字段和 tokens 对象兼容性更好。实测下来多数新版 Codex 认第一种就够第二种是保险写法。接着配config.toml路径~/.codex/config.tomlmodel gpt-5.5 model_reasoning_effort medium approval_mode suggest service_tier fast web_search cached [tui] theme dracula vim_mode_default false这里model填你要用的模型 ID。如果你在 TaoToken 上用的是别的模型名就换成对应的 ID。model_reasoning_effort控制推理强度日常medium够用复杂任务再上high。approval_mode建议先用suggest让 Codex 改文件前问你一声安全。三件套对齐检查Base URL 是https://taotoken.net/apiKey 是 TaoToken 的 KeyModel ID 是你在 TaoToken 上确认可用的模型名。这三个任何一个不对请求都会失败。现在说 VS Code 里的验证。如果你装的是 Codex IDE 扩展它读的也是同一套~/.codex/配置。装完扩展后按CtrlShiftP打开命令面板搜 Codex找到打开 Codex 面板的命令。面板出来后先别急着提问看右下角或设置里有没有显示当前模型和端点。有些版本会在状态栏显示连接状态。在 VS Code 的 Codex 面板里发一条最简单的消息比如回复 ok。如果配置正确你会看到流式返回。如果转圈或报错打开 VS Code 的输出面板CtrlShiftU选 Codex 相关的输出通道里面会有详细错误。这一步很关键因为 IDE 扩展的报错比 CLI 更隐蔽输出面板是唯一能看到真实原因的地方。如果你用的是 Cline 或带 MCP 的插件配置逻辑类似但字段名可能不同。Cline 通常在设置里填 Base URL、API Key、Model ID 三项对应关系是Base URL 填https://taotoken.net/apiAPI Key 填 TaoToken KeyModel ID 填模型名。这三件套和 Codex 的auth.json是一一对应的只是入口不同。配置写完别急着庆祝。下一节我们用一次真实调用确认它真的生效而不是看起来配好了。4. 一次完整调用验证配置生效从 codex exec 到结果确认配置改完最忌讳的就是我觉得应该行了。要用一次可观测的调用把链路走通。第一步先做最小验证不涉及文件读写。终端里跑codex exec 只回复两个字成功codex exec是非交互模式执行完就退出适合脚本化和快速验证。如果配置正确你会看到它返回成功两个字。如果这里就报 401说明auth.json的 Key 或字段有问题回到上一节检查。第二步验证模型和端点确实走了 TaoToken。跑一条稍微复杂点的codex exec 用一句话解释什么是递归观察返回内容是否正常流式输出。如果返回的是模型正常回答说明 Base URL 和 Key 都通了。如果返回 404大概率是 Base URL 的/v1问题试着把auth.json里的地址改成https://taotoken.net/api/v1再试。如果返回 401还是凭证问题。第三步验证文件读写能力。建个临时目录mkdir -p /tmp/codex-test cd /tmp/codex-test echo def add(a, b): return a b calc.py codex exec 读取 calc.py给它加一个 subtract 函数然后告诉我改了什么这一步会触发 Codex 读文件、改文件。因为approval_mode是suggest它可能会先问你确认。确认后看calc.py是否真的多了subtract函数。这一步验证的是完整链路鉴权、模型、工具调用、文件系统权限。第四步回到交互模式体验一次codex进入 TUI 后输入/status查看当前模型、审批模式、端点信息。这个命令能直观确认你的配置被正确加载。如果/status显示的模型和你config.toml里写的不一致说明配置文件没被读到检查路径和文件名。第五步VS Code 侧再验一次。在 Codex 面板里发读取当前打开的文件并总结看它能否正确引用文件。IDE 扩展和 CLI 共用配置CLI 通了 IDE 通常也通但 IDE 有自己的进程和缓存必要时重启 VS Code。整个验证清单可以归纳成一张表步骤命令/操作预期结果失败指向1codex exec 只回复两个字成功返回成功401 → Key/字段2codex exec 解释递归正常流式回答404 → Base URL3临时目录改文件文件被正确修改权限/审批模式4codex后/status显示配置的模型配置未加载5VS Code 面板提问正常返回IDE 缓存/输出面板走完这五步你就能确定配置是真生效而不是碰巧。任何一步失败对照最后一列去排查比盲目改文件高效得多。5. 常见报错排查401、local proxy failed、reading choices、OAuth 逐个击破这一节把新手最常撞的几类错误拆开讲每条都给出真实报错特征和对应动作。401 Unauthorized。这是最高频的。报错通常长这样Error: 401 Unauthorized - invalid_api_key原因无非几种Key 复制时多了空格或换行Key 已过期或在控制台被删除auth.json里字段名写错比如写成api_key而不是OPENAI_API_KEY环境变量OPENAI_API_KEY存在且覆盖了文件里的值。最后这条特别隐蔽先检查echo $OPENAI_API_KEY如果输出非空说明环境变量在起作用它优先级通常高于auth.json。要么清掉它要么让它和文件里的值一致。local proxy failed。报错类似Error: local proxy failed to connect这通常不是鉴权问题而是网络层或本地代理配置问题。检查你的终端有没有设置HTTP_PROXY/HTTPS_PROXY环境变量如果有且指向一个不可用的地址请求就发不出去。临时清掉再试unset HTTP_PROXY HTTPS_PROXY另外确认 Base URL 拼写正确没有多余斜杠或路径。reading choices 相关报错。典型形态Error: reading choices: unexpected end of JSON input这类错误说明请求发出去了、也返回了但返回体不是预期的 JSON 结构。常见原因是 Base URL 指向了一个返回 HTML 的地址比如少了/v1或路径写错命中了网页而非 API。解决方法是核对端点确保https://taotoken.net/api后面接的是正确的 API 路径。如果客户端自动补/v1/chat/completions而你手动又写了/v1就会变成/v1/v1/...同样触发这类错误。OAuth 相关报错。如果你之前用codex login走过浏览器授权auth.json里可能残留 OAuth 的 token 结构和 API Key 模式冲突。报错可能提示 token 无效或刷新失败。处理方式是清掉旧的 OAuth 凭证重新写入纯 API Key 结构。可以先备份再重写cp ~/.codex/auth.json ~/.codex/auth.json.bak然后按第 3 节的模板重写auth.json。模型不存在 / model not found。报错会明确说模型 ID 无效。这说明鉴权和端点都通了只是config.toml里的model值在 TaoToken 上不可用。去控制台确认可用模型列表换成正确的 ID。权限被拒 / permission denied。读写文件时报这个检查~/.codex/和项目目录的权限以及approval_mode是否设成了不允许自动执行的模式。把这几类错误和现象对应起来你就能在报错出现时快速定位而不是把auth.json改来改去碰运气。记住一个判断顺序401 看凭证404 看地址JSON 解析错看端点路径连接失败看网络和代理。6. 配置跑通之后把 Codex 用顺手的几个实操建议配置通了只是起点真正提升效率的是使用习惯。第一把approval_mode按场景切换。探索陌生代码库时用suggest让它先解释再动手做重复性重构时切到auto-edit减少确认次数只有在完全信任的任务上才考虑更自动的模式。这个开关在config.toml里改也可以在 TUI 里用/permissions临时切。第二善用文件名引用上下文。Codex 不会自动读你脑子里想的那个文件你得明确告诉它。提示词里写参考 UserService.java 的风格重写 OrderService.java比泛泛说按现有风格改准确得多。第三长对话记得/compact。对话历史会占用上下文窗口太长时模型容易丢重点。/compact会压缩历史释放空间。任务切换时用/new开新会话别在一个会话里塞完全不相关的事。第四模型选择别一刀切。日常任务用响应快的模型复杂架构设计再上推理强度高的。config.toml里的model和model_reasoning_effort配合调整比一直用最高配置更划算。第五敏感信息别进提示词。Key、密码、内部地址都不要写进对话Codex 会把上下文发给模型服务。auth.json本身也要确保不被提交到版本库检查.gitignore里有没有~/.codex/或相关路径。如果你打算长期在编码和 Agent 场景里用可以了解下 Coding Plan 这类方案适合高频调用只是偶尔验证模型效果用模型对话入口就够需要管理多个 Key 和额度去控制台和 API Keys 页面操作。接入细节和字段说明官方文档里有完整对照遇到本文没覆盖的报错先去文档核对字段名和端点格式比在社区里翻旧帖快。最后一句实在话auth.json这类配置文件改完一定要用一次真实调用验证别靠看起来对就收工。我见过太多人卡在 401 上最后发现只是 Key 末尾多了个换行符。