1. Codex 宠物模式开启失败的真实场景：auth.json 配置错误导致桌宠加载不出来
Codex 宠物模式（Pets）是最近 Codex 客户端里一个挺有意思的功能，简单说就是在桌面上养一只赛博桌宠，它会实时显示 AI 当前的工作状态——正在生成代码、等待输入、任务完成需要复核，都能通过桌宠的动作和气泡提示看出来。对于经常让 Codex 在后台跑长任务的人来说，不用反复切回主窗口就能知道进度，实用性比想象中高。开启方式也不复杂，设置里打开 Appearance 下的 Pets 分类，或者在输入框直接敲/pet就能召唤默认桌宠。
但问题来了：很多人照着教程操作，设置里 Pets 开关是灰的，或者输入/pet之后桌面毫无反应，重启客户端也没用。我自己第一次遇到的时候也懵了，以为是版本不对，重装了两遍 Codex 才发现根因根本不在客户端本身，而是auth.json里的 endpoint 和 key 配置有问题。Codex 的宠物模式依赖后端会话通道来同步状态，如果认证配置指向了一个不可用或者不匹配的地址，桌宠进程初始化时会静默失败——它不会弹报错，只是什么都不显示，这就很容易让人误判成功能没上线。
这个场景其实挺典型的：你下载了最新版 Codex，设置里也能看到 Pets 选项，但就是激活不了。排查顺序应该是先确认版本，再检查auth.json，最后才怀疑客户端 bug。本文就聚焦在auth.json这个环节，把 endpoint 和 key 的可复制配置片段给出来，然后演示改完之后重启 Codex 验证桌宠是否正常出现的完整动作。如果你正在搜「Codex 宠物模式怎么开启」「Codex 桌宠加载失败」「Codex Pets 不显示」这类问题，下面的步骤可以一步步跟着做。
需要提前说明的是，Codex 的认证配置文件在不同平台上路径不一样。macOS 通常在~/.codex/auth.json，Windows 在%USERPROFILE%\.codex\auth.json，Linux 在~/.codex/auth.json。如果你用的是通过 TaoToken 接入的方式，这个文件里的OPENAI_BASE_URL和OPENAI_API_KEY两个字段就是关键。宠物模式的会话状态同步走的是同一个通道，所以这两个值配错了，桌宠自然起不来。下面第二节先讲清楚 TaoToken 这边的准备工作，第三节给完整配置，第四节验证，第五节排错，最后给一个接入文档的入口。
2. TaoToken 前置准备：拿到可用的 Base URL 和 API Key
在改auth.json之前，你得先有一个能用的 API 端点和对应的 key。TaoToken 这边提供的是兼容 OpenAI 接口规范的接入方式，Codex 作为客户端可以直接把 Base URL 指过来。整个准备流程分三步：注册账号、创建 API Key、确认 Base URL。这三步做完，你手里会有两个值——一个以https://taotoken.net/api开头的地址，和一个sk-开头的密钥字符串。这两个值就是后面写进auth.json的核心内容。
先说 Base URL。TaoToken 的 API 入口是https://taotoken.net/api，注意这里不要加任何多余的路径后缀，Codex 会自己在后面拼接/v1/chat/completions之类的端点。有些教程会让你写成https://taotoken.net/api/v1，这样反而会导致 404，因为路径重复了。我实测下来，auth.json里的OPENAI_BASE_URL填https://taotoken.net/api是最稳的。如果你后面要换成别的兼容端点，也遵循同样的规则：只写到域名加/api这一层。
再说 API Key。登录 TaoToken 控制台之后，进 API Keys 页面创建一个新的 key。创建的时候建议给它起个能认出来的名字，比如codex-desktop，方便以后区分。创建完立刻复制，因为页面刷新之后完整 key 就不再显示了。这个 key 就是auth.json里OPENAI_API_KEY的值。如果你之前已经创建过 key，也可以直接用旧的，但要注意 key 是否有额度、是否被禁用。宠物模式本身不消耗额外额度，但它依赖的会话通道需要 key 有效，所以一个被限流或者余额为零的 key 同样会导致桌宠加载失败。
这里有个容易踩的坑：有些人把 key 写进了系统环境变量OPENAI_API_KEY，以为 Codex 会自动读取。实际上 Codex 桌面端优先读auth.json里的字段，环境变量只在部分命令行场景生效。所以如果你环境变量里有一个旧的 key，而auth.json里是空的或者写错了，桌宠照样起不来。排查的时候要两个地方都看一眼，以auth.json为准。
另外，如果你用的是 Coding Plan 或者需要长期跑 Agent 任务，建议在 TaoToken 控制台里确认一下当前套餐的并发限制。宠物模式的状态同步是长连接，如果并发被占满，桌宠可能会卡在「等待输入」状态不动。这个不是配置错误，但表现上容易和 auth 问题混淆。准备阶段把 key 和 Base URL 记在一个临时文本里，下一步直接粘贴进配置文件，避免手打出错。
3. 可复制配置：auth.json 中 endpoint 与 key 的完整写法
这一节是核心，直接给可复制的配置片段。Codex 的auth.json是一个 JSON 文件，结构不复杂，但字段名必须完全匹配，多一个空格或者少一个引号都会导致解析失败。下面是最小可用配置，你把自己的 key 替换掉sk-你的TaoToken密钥这一行即可。
{ "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "sk-你的TaoToken密钥", "OPENAI_MODEL": "gpt-4o-codex", "auth_mode": "apikey" }逐字段说明一下。OPENAI_BASE_URL填https://taotoken.net/api，不要带尾部斜杠，也不要带/v1。OPENAI_API_KEY填你在 TaoToken 控制台创建的那个sk-开头的字符串。OPENAI_MODEL这一项是 Codex 用来发起会话的模型 ID，如果你不确定填什么，可以先填gpt-4o-codex，或者去 TaoToken 的模型列表页确认当前可用的编码模型 ID。auth_mode设为apikey表示用密钥认证，而不是 OAuth 流程。如果你之前登录过官方账号，这个字段可能是oauth，改成apikey之后才会走你配置的 Base URL。
文件路径按平台来。macOS 和 Linux 在终端里执行：
mkdir -p ~/.codex nano ~/.codex/auth.json然后把上面的 JSON 粘贴进去，保存退出。Windows 的话，在文件资源管理器地址栏输入%USERPROFILE%\.codex，如果目录不存在就手动建一个，然后用记事本或者 VS Code 打开auth.json编辑。注意 Windows 下不要用系统自带的「写字板」，它可能保存成 RTF 格式导致 JSON 解析失败，用记事本或者 VS Code 都行。
如果你用的是 Codex 的 TOML 配置模式（部分版本支持config.toml和auth.json并存），那config.toml里可以这样写：
[model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "OPENAI_API_KEY" [profiles.default] model_provider = "taotoken" model = "gpt-4o-codex"然后在auth.json里只保留 key：
{ "OPENAI_API_KEY": "sk-你的TaoToken密钥" }这种写法适合你同时想保留多个 provider 配置的情况。不过对于大多数只想开宠物模式的用户，直接用前面那个完整的auth.json就够了，不用折腾 TOML。改完文件之后，先别急着开 Codex，用命令行验证一下 JSON 格式是否合法：
python3 -m json.tool ~/.codex/auth.json如果输出格式化后的 JSON 且没有报错，说明格式没问题。如果报Expecting property name enclosed in double quotes之类的错误，那就是引号或者逗号写错了，回去检查。这一步能省掉很多「改了没反应」的困惑，因为 Codex 遇到格式错误的auth.json会直接忽略整个文件，回退到默认配置，表现就是桌宠不出现。
4. 验证请求：重启 Codex 后桌宠是否正常出现
配置改完，接下来是验证。验证分两层：先确认 API 通道本身是通的，再确认宠物模式能加载。第一层用 curl 就能测，第二层需要重启 Codex 客户端。
先测 API 通道。在终端里执行下面这条命令，把 key 替换成你自己的：
curl -s -o /dev/null -w "%{http_code}" \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-codex","messages":[{"role":"user","content":"ping"}],"max_tokens":5}' \ https://taotoken.net/api/v1/chat/completions如果返回200，说明 Base URL 和 key 都是有效的，通道没问题。如果返回401，说明 key 错了或者被禁用；返回404，大概率是 Base URL 写成了带/v1的版本导致路径重复；返回429，说明触发了限流，等一会儿再试或者去控制台看套餐余量。这一步能快速定位问题出在配置还是客户端。
通道确认没问题之后，完全退出 Codex。注意是「完全退出」，不是关窗口。macOS 上按Cmd+Q，或者在 Dock 图标上右键选退出；Windows 上在任务管理器里确认 Codex 进程已经结束。然后重新启动 Codex。启动之后，先别急着敲/pet，等主界面加载完成，大概三五秒。然后有两种方式召唤桌宠：一是进 Settings → Appearance → Pets，看开关是否可点，选一个内置形象；二是在输入框直接输入/pet回车。
正常情况下，桌面右上角或者右下角会出现一个悬浮窗，里面就是你的赛博桌宠。它会根据 Codex 当前状态变化：你发一个代码生成请求，桌宠会显示「忙碌中」；请求完成等待你确认时，桌宠会显示「待机」或者弹一个气泡提醒。如果你看到桌宠出现了，并且状态能跟着任务变化，说明auth.json配置正确，宠物模式已经正常工作。
如果/pet输入之后没反应，先看 Codex 的日志。macOS 在~/Library/Logs/Codex/，Windows 在%APPDATA%\Codex\logs\。找最新的日志文件，搜pet或者auth关键字。常见的一条是failed to initialize pet session: invalid auth config，这就直接指向auth.json问题。另一条是local proxy failed to start，这个通常和端口占用或者 Base URL 不可达有关。日志里能看到具体原因，比盲目重装有效得多。
验证通过之后，你可以进一步自定义宠物。Codex 支持通过 Skill 创建个性化桌宠，安装命令是：
$skill-installer hatch-pet安装完用自然语言描述你想要的形象，比如「一只会写代码的猫」或者「赛博机械狗」，Codex 会生成对应的桌宠。这一步依赖的仍然是同一个会话通道，所以auth.json配置正确是前提。如果自定义宠物生成失败，先回到第四节开头用 curl 再测一次通道，确认不是 key 过期导致的。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth 报错对照
这一节把宠物模式开启过程中最常见的几类报错列出来，对照着排查。这些错误有的来自 Codex 客户端日志，有的来自 curl 测试，表现不同但根因往往都落在auth.json或者网络通道上。
第一类：401 Unauthorized。这个最直接，key 无效。可能的原因有：key 复制的时候少了字符、key 被控制台禁用、key 对应的套餐余额为零。排查方法是重新去 TaoToken 控制台创建一个新 key，替换auth.json里的OPENAI_API_KEY，然后重启 Codex。注意不要用环境变量里的旧 key 覆盖，以文件里的为准。如果换了新 key 还是 401，检查auth_mode字段是不是写成了oauth，改成apikey。
第二类：local proxy failed to start。这个报错通常出现在 Codex 启动阶段，意思是本地代理进程没起来。原因可能是端口被占用，或者OPENAI_BASE_URL指向了一个不可达的地址。先确认 Base URL 是https://taotoken.net/api，没有多余路径。然后检查本机是否有其他程序占用了 Codex 默认的本地端口，重启一下机器往往能解决。如果重启后仍然报这个错，把auth.json里的OPENAI_BASE_URL临时改成官方地址测试一下，如果官方地址能起来，说明是 TaoToken 这边的网络连通性问题，检查一下本机 DNS 或者防火墙设置。
第三类：reading choices相关报错。这个通常出现在请求返回阶段，日志里会写error reading choices: unexpected end of JSON input或者类似内容。意思是 Codex 收到了响应，但解析失败。原因可能是 Base URL 指向的端点返回了非标准格式，或者模型 ID 填错了导致后端返回了错误结构。排查方法是确认OPENAI_MODEL填的是 TaoToken 支持的模型 ID，不要填一个不存在的名字。另外检查 Base URL 是否误写成了https://taotoken.net/api/v1，路径重复会导致返回 404 的 HTML 页面，Codex 尝试按 JSON 解析自然失败。
第四类：OAuth 相关报错。如果你之前用官方账号登录过 Codex，auth.json里可能残留了oauth模式的 token 字段。这些字段和你新加的OPENAI_API_KEY冲突时，Codex 可能优先走 OAuth 流程，然后因为 token 过期报错。解决办法是把auth.json里除了OPENAI_BASE_URL、OPENAI_API_KEY、OPENAI_MODEL、auth_mode之外的字段全部删掉，保持最小配置。特别是tokens、refresh_token、expires_at这类字段，删干净。改完重启 Codex，让客户端重新按apikey模式初始化。
第五类：桌宠出现但状态不更新。这个不是报错，但体验上等于没用。原因通常是会话通道建立了但长连接被中断，可能是并发限制或者网络抖动。去 TaoToken 控制台看一下当前并发使用情况，如果接近上限，桌宠的状态同步会排队。另外确认 Codex 版本是最新的，旧版本对 Pets 的状态同步支持不完整。更新到最新版之后重新走一遍第四节的重启验证流程。
排查的时候有个通用原则：先看日志，再改配置，改完必须完全重启 Codex。很多人改了auth.json之后只是关窗口再打开，进程没退干净，读的还是旧配置，自然觉得「改了没用」。养成用Cmd+Q或者任务管理器结束进程的习惯，能省掉一半的无效排查。
6. 接入文档与 API Keys 入口：继续配置 Coding Plan 或自定义宠物
走到这里，如果你的桌宠已经正常出现并且状态能跟着任务变化，那auth.json的配置就算完成了。后面如果想继续折腾，比如把 Codex 接到 Coding Plan 上跑长期 Agent 任务，或者用 Skill 生成更多自定义宠物，入口都在下面。
API Keys 管理页面用来创建和轮换密钥，地址是 https://taotoken.net/console/api-keys 。如果你在排查 401 的时候需要新建 key，直接从这里进。接入文档在 https://taotoken.net/doc ，里面有不同客户端（包括 Codex、Cline、Claude Code 等）的配置示例，auth.json的字段说明也在里面，遇到不确定的字段名可以对照查。模型对话入口在 https://taotoken.net/chat ，可以用来快速测试某个模型 ID 是否可用，不用每次都改auth.json重启 Codex。如果你打算长期用 Codex 跑编码任务，Coding Plan 的入口在 https://taotoken.net/coding-plan ，套餐和并发限制的说明都在那个页面。
自定义宠物这块，$skill-installer hatch-pet装完之后，描述词越具体生成效果越好。比如「一只戴着耳机敲键盘的柴犬，背景是终端窗口」就比「一只狗」更容易得到可用的形象。生成失败的话，先确认 API 通道正常，再检查 Skill 是否安装完整。宠物形象文件一般存在~/.codex/pets/目录下，可以手动备份，换机器的时候直接拷过去。
最后提醒一个实操细节：auth.json里如果同时存在OPENAI_API_KEY和OPENAI_BASE_URL，Codex 会优先用文件里的值，环境变量只在文件缺失时兜底。所以换 key 的时候只改文件就行，不用去动系统环境变量。改完记得用python3 -m json.tool验一下格式，然后完全退出重启。这套流程走顺了，以后换模型或者换 key 都是两分钟的事。
