1. 为什么要在 Codex 里养一只阿梓 AziCodex 的宠物系统本质上是一个状态可视化层它把模型当前处于 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 为什么这里要提 TaoTokenCodex 本身要调用模型才能工作宠物状态是跟着模型请求走的。如果你希望宠物动作能真实反映请求过程就需要一个稳定的 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/读取宠物。各平台路径如下平台宠物根目录WindowsC:\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.tomlWindows 为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_KEYWindows 用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 就不只是个装饰而是你本地开发状态的一个实时指示器。
给 Codex 加一只像素宠物：阿梓 Azi 的 config.toml 配置与验证
1. 为什么要在 Codex 里养一只阿梓 AziCodex 的宠物系统本质上是一个状态可视化层它把模型当前处于 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 为什么这里要提 TaoTokenCodex 本身要调用模型才能工作宠物状态是跟着模型请求走的。如果你希望宠物动作能真实反映请求过程就需要一个稳定的 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/读取宠物。各平台路径如下平台宠物根目录WindowsC:\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.tomlWindows 为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_KEYWindows 用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 就不只是个装饰而是你本地开发状态的一个实时指示器。