1. 为什么要在 Codex 里养一只阿梓 Azi
Codex 的宠物系统本质上是一个状态可视化层：它把模型当前处于 idle、running、waiting、failed 还是 review 这些内部状态，映射成一张 spritesheet 上的不同动作帧。默认宠物能用，但看久了确实没什么辨识度。阿梓 Azi 这个像素宠物包的价值在于，它把「我现在到底在忙什么」这件事变成了一个能一眼看懂的小动画——跑动代表正在请求，挥手代表等待输入，沮丧代表请求失败。
这套东西适合谁？适合每天在终端里跟 Codex 打交道、希望本地开发环境多一点反馈感的开发者。它不改变 Codex 的核心能力，但能让你在长任务里少盯几眼日志。整个接入过程只涉及两个文件（pet.json 和 spritesheet.webp）加一段 config.toml 配置，不需要改 Codex 源码，也不需要额外的运行时依赖。
我试过在 Windows 和 macOS 上各装一遍，踩过的坑主要集中在路径写错和 config.toml 里宠物名对不上这两处。下面把可复制的配置骨架、TaoToken 统一 Key 的接入片段，以及启动后的验证动作一次讲清楚，目标是照着做一次就能跑起来。
2. 前置准备：宠物包结构与 TaoToken 通道
2.1 阿梓 Azi 宠物包长什么样
从仓库拿到手之后，真正需要装进 Codex 的只有azi这一个文件夹，结构如下：
codex-pet-azi/ ├── README.md ├── assets/ │ └── contact-sheet.png └── azi/ ├── pet.json └── spritesheet.webppet.json描述宠物的元信息与动作映射，spritesheet.webp是横向排列的动作图集。Codex 读取的是pet.json里的name字段和帧坐标，所以这两个文件必须放在同一个目录下，缺一不可。
2.2 为什么这里要提 TaoToken
Codex 本身要调用模型才能工作，宠物状态是跟着模型请求走的。如果你希望宠物动作能真实反映请求过程，就需要一个稳定的 API 通道。TaoToken 提供统一的 Key 和兼容 OpenAI 风格的接口，把 base_url 指向https://taotoken.net/api即可，不用在多个供应商之间来回切换配置。宠物包负责「显示」，TaoToken 负责「驱动」，两者配合起来，Azi 的跑动和等待才有实际意义。
先把 Key 准备好：登录后在控制台创建 API Key，复制出来备用。这个 Key 后面会写进 config.toml 的 provider 段。
3. 可复制的 config.toml 配置骨架
3.1 宠物目录的放置位置
Codex 默认从用户目录下的.codex/pets/读取宠物。各平台路径如下：
| 平台 | 宠物根目录 |
|---|---|
| Windows | C:\Users\<你的用户名>\.codex\pets\ |
| macOS | ~/.codex/pets/ |
| Linux | ~/.codex/pets/ |
把azi整个文件夹复制进去，最终应该是：
C:\Users\<你的用户名>\.codex\pets\azi\pet.json C:\Users\<你的用户名>\.codex\pets\azi\spritesheet.webpmacOS / Linux 对应~/.codex/pets/azi/pet.json和~/.codex/pets/azi/spritesheet.webp。注意是复制azi文件夹本身，不是把里面的两个文件直接倒进pets/根目录，否则 Codex 找不到宠物名。
3.2 config.toml 完整骨架
Codex 的配置文件一般位于~/.codex/config.toml（Windows 为C:\Users\<你的用户名>\.codex\config.toml）。下面是一份可直接改用的骨架，把<你的TaoToken Key>替换成上一步复制的 Key：
# ~/.codex/config.toml # 宠物配置：name 必须与 pet.json 中的 name 字段一致 [pet] name = "azi" enabled = true scale = 2 # 模型通道：统一走 TaoToken [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" [profiles.default] model_provider = "taotoken" model = "gpt-4o-mini"这里有几个关键点。[pet]段的name必须和azi/pet.json里的name完全一致，大小写敏感；scale控制像素宠物的显示倍率，2 倍在多数终端下比较清晰。[model_providers.taotoken]段把 base_url 指向 TaoToken 的 API 地址，env_key表示 Key 从环境变量读取，而不是硬编码在文件里——这样更安全，也方便多机同步配置。
3.3 设置环境变量
把 Key 写进环境变量，避免明文躺在 config.toml 里。
Windows PowerShell（当前会话）：
$env:TAOTOKEN_API_KEY = "<你的TaoToken Key>"想永久生效可以写进用户环境变量：
[Environment]::SetEnvironmentVariable("TAOTOKEN_API_KEY", "<你的TaoToken Key>", "User")macOS / Linux（写入 shell 配置）：
echo 'export TAOTOKEN_API_KEY="<你的TaoToken Key>"' >> ~/.zshrc source ~/.zshrc如果你用的是 bash，把~/.zshrc换成~/.bashrc即可。设置完可以用echo $TAOTOKEN_API_KEY（Windows 用echo $env:TAOTOKEN_API_KEY）确认变量已生效。
4. 验证请求与宠物状态显示
4.1 先验证 API 通道是否通
在启动 Codex 之前，先用一条 curl 确认 TaoToken 通道能正常返回，排除 Key 或网络问题：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}] }'如果返回里带有choices字段，说明 Key 和通道都没问题。如果返回 401，检查环境变量是否在当前终端生效；返回 404 则确认 base_url 没有多写或少写/v1。
4.2 启动 Codex 观察宠物状态
通道验证通过后，重启 Codex 或刷新宠物列表。正常情况下你应该能看到 Azi 出现在界面上，并且动作会随状态变化：
| 宠物动作 | 对应状态 | 触发场景 |
|---|---|---|
| idle | 待机 | 无请求，空闲中 |
| running | 忙碌中 | 正在发起模型请求 |
| waiting | 等待 | 等待用户输入或确认 |
| review | 检查/审阅 | 模型输出审查阶段 |
| failed | 失败/沮丧 | 请求报错或超时 |
| waving | 挥手 | 会话开始或唤醒 |
| jumping | 跳跃 | 任务完成 |
如果 Azi 一直停在 idle 不动，先确认 config.toml 里[pet]段的enabled是true，再检查name是否和 pet.json 一致。宠物动作是跟着请求走的，所以你也可以主动发一条消息，观察它是否切到 running。
4.3 用模型对话快速验证
想单独验证模型通道和宠物联动，可以直接在模型对话里发一条测试消息。如果 Azi 在请求期间切到 running、返回后回到 idle，说明宠物状态映射和 API 通道都工作正常。这一步能同时验证两件事：TaoToken 通道可用，宠物状态机在响应。
5. 本篇常见报错排查
5.1 宠物不显示或显示为默认宠物
最常见的原因是路径放错。Codex 只认pets/<宠物名>/pet.json这一层结构，如果你把pet.json直接放在pets/下，它读不到。另一个原因是pet.json里的name和 config.toml 里的name不一致，比如一个是azi、一个是Azi，大小写不同就会匹配失败。用ls ~/.codex/pets/azi/确认两个文件都在。
5.2 报 401 Unauthorized
说明 Key 没被正确读取。先确认环境变量名和 config.toml 里的env_key完全一致，都是TAOTOKEN_API_KEY。然后确认你是在同一个终端会话里启动的 Codex——如果你在 A 终端设了变量、在 B 终端启动 Codex，变量不会传递。Windows 下用[Environment]::SetEnvironmentVariable写入用户变量后，需要新开一个终端才生效。
5.3 报 404 或连接超时
检查 base_url 是否写成了https://taotoken.net/api，不要多加/v1也不要少写。如果公司网络有出口限制，确认能访问该域名。超时通常是网络层问题，可以先用 4.1 的 curl 单独测一次，把 Codex 和网络问题隔离开。
5.4 宠物动作卡住不动
如果 API 请求正常但宠物不动，多半是 spritesheet 没加载成功。确认spritesheet.webp和pet.json在同一目录，且文件没有在复制过程中损坏。可以重新从仓库复制一次azi文件夹覆盖。另外scale设得过大在某些终端下会导致渲染异常，先调回 2 试试。
5.5 config.toml 解析报错
TOML 对格式敏感。常见问题是段名写错，比如把[model_providers.taotoken]写成[model_provider.taotoken]，或者字符串没加引号。改完配置后可以用codex --version之类的命令触发一次解析，看是否报语法错误。缩进不影响 TOML，但键值对必须成对出现。
6. 把通道和宠物一起用起来
配置到这一步，Azi 已经能跟着 Codex 的请求状态动了。如果你打算长期在本地用 Codex 做编码或跑 Agent 任务，建议把 Key 管理固定下来：在控制台里为不同项目建不同的 Key，配合环境变量切换，避免一个 Key 到处用。宠物包本身不消耗额度，真正走量的是模型请求，所以通道的稳定性比宠物本身更值得关注。
需要创建或轮换 Key 的时候，直接进 API Keys 页面操作；接入细节和参数说明可以对照接入文档；想先单独验证模型是否正常，用模型对话发一条消息最快；如果你要把 Codex 用在长期编码或 Agent 工作流里，Coding Plan 会更合适，额度和调用方式都按持续使用来设计。把这几步串起来，Azi 就不只是个装饰，而是你本地开发状态的一个实时指示器。
