1. 为什么 Prompt 写得好auth.json 却先报错很多人在 Codex 里研究 Prompt Design Patterns把目标、上下文、边界、完成标准写得清清楚楚结果第一次跑codex exec就卡在鉴权上。我见过太多这种情况Prompt 结构没问题模型能力也没问题问题出在~/.codex/auth.json这个文件根本没配对。Codex 的鉴权链路其实不复杂。CLI 启动时会读取auth.json从中拿到 API Key 和 Base URL然后向对应的服务端发起请求。如果这个文件里的字段名写错、路径放错、或者 Key 和 Base URL 不匹配你后面 Prompt 设计得再漂亮也没用——请求根本发不出去。这一篇的核心思路是先把鉴权通道打通再谈 Prompt 设计模式。我会用 TaoToken 作为统一的 API 通道把 Codex 的auth.json配置完整走一遍包括可复制的 JSON 片段、逐步验证动作、以及常见的报错排查。你跟着做能在本地复现整条请求链路。适合谁看已经在用 Codex CLI 或准备接入 Codex 的开发者尤其是想把 Prompt 工程落到真实项目里的人。如果你还没配过auth.json或者配了但一直报 401这篇就是给你写的。TaoToken 在这里的角色是统一 Key 和 API 通道。你不需要在多个服务商之间来回切换配置一个 Base URL 加一个 Key 就能把 Codex 的请求链路固定下来。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。先说清楚一个概念Codex 的 Prompt 设计模式Task Prompt、Skill、Scheduled Task、Playbook是使用方式的选择不是四个互斥的产品功能。同样auth.json的配置也是基础设施层面的选择——它决定了你的 Prompt 能不能稳定地跑起来。两者是分层的关系鉴权层管通道Prompt 层管内容。我试过在同一个项目里同时维护三套鉴权配置切换的时候经常搞混 Key 和 Base URL 的对应关系。后来统一到 TaoToken 之后auth.json只需要维护一份Prompt 里的模型调用也稳定了很多。下面从配置开始。2. TaoToken 前置准备Key、Base URL 与 auth.json 路径在改auth.json之前你需要先拿到两样东西API Key 和 Base URL。TaoToken 的 API Key 在控制台里生成地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。生成之后先复制到安全的地方后面配置要用。Base URL 固定为https://taotoken.net/api注意这个地址不加 UTM 参数直接写进配置文件就行。接下来是auth.json的路径。Codex CLI 默认读取用户目录下的.codex文件夹macOS / Linux~/.codex/auth.jsonWindowsC:\Users\你的用户名\.codex\auth.json如果你不确定路径可以在终端里跑codex --version确认 CLI 已安装然后手动创建.codex目录。有些版本在首次运行时会自动生成这个目录但auth.json通常需要你自己写。这里有个容易踩的坑不同版本的 Codex 对auth.json的字段要求不完全一样。有的版本用OPENAI_API_KEY有的用api_key还有的用嵌套结构。我建议你先看一眼当前版本的文档或者直接跑一次codex exec看它报什么错根据报错反推字段名。为了统一下面给的配置片段用的是当前主流版本兼容的写法。如果你跑的时候报字段缺失对照第 5 节的排查表改。在配置之前建议先确认你的 Key 是有效的。可以打开模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 做一次简单对话确认 Key 能正常调用。这一步能帮你排除掉「Key 本身有问题」这个变量后面排查就只剩配置文件的事了。另外如果你用的是 Coding Plan 或者需要长期跑 Agent 任务建议在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 看一下套餐说明避免跑到一半额度不够。准备工作做完接下来进入实际配置。记住三个要素Base URL、Key、Model ID。这三个在后面的 JSON 片段里都会出现缺一不可。3. 可复制配置auth.json 完整片段与字段说明这一节给的是可以直接复制粘贴的配置。先备份你现有的auth.json然后按下面的结构改。{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api, model: gpt-4o, provider: openai }这是最简版本。字段说明OPENAI_API_KEY填你在 TaoToken 控制台生成的 Key注意不要带多余空格。OPENAI_BASE_URL固定为https://taotoken.net/api末尾不要加斜杠。model填你要用的模型 ID比如gpt-4o或gpt-4o-mini具体可用模型在模型对话页面能查到。provider一般填openai因为 Codex 走的是 OpenAI 兼容协议。如果你的 Codex 版本要求嵌套结构用这个版本{ openai: { api_key: sk-你的TaoToken密钥, base_url: https://taotoken.net/api, model: gpt-4o } }两种写法的区别在于字段层级。判断方法很简单跑一次codex exec echo test如果报missing api_key就换成嵌套版如果报unexpected field就换回扁平版。还有一个变体是带auth_mode的{ auth_mode: apikey, OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api, model: gpt-4o }auth_mode设为apikey表示用 API Key 鉴权而不是 OAuth 登录。如果你之前用 ChatGPT 账号登录过 Codex这个字段可能是oauth需要改成apikey否则它会走 OAuth 流程忽略你的 Key。配置文件的权限也要注意。在 macOS / Linux 上auth.json建议设为600chmod 600 ~/.codex/auth.jsonWindows 上不用特别设置但确保文件不在同步盘里避免被其他程序改掉。如果你同时用 Cline MCP 或 Claude Code注意它们的配置文件和 Codex 是分开的。Cline 的 MCP 配置在cline_mcp_settings.jsonClaude Code 在~/.claude/settings.json。不要混在一起改每个工具读自己的配置。配置写完后先别急着跑复杂 Prompt。用最简单的命令验证通道是否打通下一节讲具体步骤。4. 验证请求从 codex exec 到成功返回配置写完第一步是验证鉴权通道。用最简单的非交互命令codex exec 回复 ok如果配置正确你会看到模型返回ok或者类似的简短回复。这一步只验证通道不验证 Prompt 质量。如果这一步就报错先看错误类型。401 通常是 Key 无效或字段名不对local proxy failed通常是 Base URL 写错或网络不通reading choices通常是返回结构不符合预期可能是 Base URL 指向了非兼容接口。通道通了之后再验证一个带文件读取的 Prompt确认 Codex 能正常调用工具codex exec --sandbox workspace-write 读取当前目录的 README.md用一句话总结内容这里--sandbox workspace-write表示允许在工作区内写文件。如果你只是读文件可以用默认的只读沙箱。这一步能验证 Codex 的工具调用链路是否正常。接下来验证 Prompt 设计模式里的「一次性任务」结构。写一个带目标、上下文、边界、完成标准的 Promptcodex exec 目标检查当前目录下所有 .py 文件的语法错误。上下文只检查 .py 文件忽略 venv 和 node_modules。边界只报告不修改任何文件。完成标准列出每个有语法错误的文件路径和错误行号。如果返回了结构化的报告说明 Prompt 结构和鉴权通道都正常。这一步同时验证了两件事模型能理解结构化 Prompt请求链路能稳定返回。对于需要机器可读输出的场景可以用--jsoncodex exec --json 列出当前目录的文件数量返回的 JSON 里会包含事件流方便下游脚本解析。如果你需要固定字段可以配合--output-schema。验证成功后建议把这条命令记下来作为以后排查的基准。每次改完配置先跑这条命令确认通道没坏再去调 Prompt。如果你在验证时遇到OAuth相关的报错说明auth_mode没设对。回到第 3 节把auth_mode改成apikey然后重新跑验证命令。通道验证通过后你就可以放心地去设计复杂的 Prompt 了。下一节讲常见报错和排查方法。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按报错类型逐个排查。每个报错都给出原因和修复动作。401 Unauthorized最常见。原因通常是 Key 无效、字段名不对、或者 Key 和 Base URL 不匹配。排查步骤先确认OPENAI_API_KEY的值没有多余空格和换行再确认OPENAI_BASE_URL是https://taotoken.net/api末尾没有斜杠然后确认auth_mode是apikey。如果都对了还报 401去控制台重新生成一个 Key 试试。local proxy failed这个报错通常和网络链路有关。先确认 Base URL 能通curl -I https://taotoken.net/api如果 curl 也失败说明网络层有问题检查你的网络环境。如果 curl 成功但 Codex 报错检查auth.json里的 Base URL 是不是写成了https://taotoken.net/api/多了斜杠或者https://taotoken.net少了/api。reading choices 相关报错这个报错说明 Codex 收到了返回但结构不符合预期。常见原因是 Base URL 指向了非 OpenAI 兼容的接口。确认你用的是https://taotoken.net/api而不是其他路径。另外检查model字段填的模型 ID 是否在可用列表里填错模型 ID 有时也会导致返回结构异常。OAuth 相关报错如果你之前用 ChatGPT 账号登录过 Codexauth.json里可能有 OAuth 相关的 token。这时候即使你填了 API KeyCodex 也可能优先走 OAuth 流程。修复方法把auth_mode显式设为apikey或者删掉 OAuth 相关的字段只保留 API Key 配置。字段缺失报错如果报missing api_key或missing base_url说明你的 Codex 版本要求的字段名和配置里的不一致。对照第 3 节的两种写法切换。扁平版用OPENAI_API_KEY嵌套版用openai.api_key。权限报错如果报文件权限相关错误检查auth.json的权限。macOS / Linux 上跑chmod 600 ~/.codex/auth.json。Windows 上确认文件没有被其他程序占用。排查完记得每次只改一个变量改完跑一次验证命令。这样能快速定位是哪个字段的问题。6. 把 Prompt 设计模式接到稳定通道上鉴权通道打通之后Prompt 设计模式才有意义。回到本章的主题Task Prompt、Skill、Scheduled Task、Playbook 这四类模式本质上是在稳定的请求链路上做内容组织。一次性任务用清晰的目标、上下文、边界、完成标准就够了。可复用技能把稳定方法固化成 Skill调用时只提供本次输入。定时任务先手动验证 Prompt再交给调度器。长任务用阶段门槛和人工决策点推进。这些模式的共同前提是请求能稳定发出去返回能稳定解析。auth.json配置就是这个前提。你不需要每次调 Prompt 都重新配鉴权但第一次一定要配对。如果你需要长期跑编码任务或 Agent建议在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 看一下套餐避免额度中断影响任务连续性。API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后给一个实用建议把验证命令写成一个脚本每次改完配置跑一遍。这样你调 Prompt 的时候不会因为鉴权问题浪费时间。通道稳定了Prompt 设计模式才能真正落地。