1. Codex Session 日志太乱，Codex Viz 到底能帮你看清什么
如果你用 Codex 跑过稍微复杂一点的任务，大概率会遇到同一个问题：任务跑完了，但你想复盘它到底干了什么，只能去翻~/.codex/sessions目录下那一堆 JSONL 文件。每一行都是一条事件记录，有 user 消息、assistant 回复、tool call、tool output、token 统计，混在一起密密麻麻。想搞清楚"这次任务为什么多花了 3 万 token""它中间到底调了几次 shell""哪一步开始跑偏的"，靠肉眼读 JSONL 基本等于自虐。
Codex Session 可视化就是来解决这个问题的。Codex Viz 是一个基于 Next.js 构建的本地可视化面板，它直接读取你本机的 Codex Session 日志，把原本散落在 JSONL 里的会话流程、工具调用链路、Token 消耗、错误中断这些信息，还原成 Dashboard 和单会话时间线。一句话说清楚：Codex Viz 是给 Codex Session 日志套上的一层可视化分析界面，让"模型到底做了什么"从不可读变成可读、可复盘。
它适合谁？三类人最对口。第一类是天天用 Codex 写代码、想让每次任务的执行链路可追溯的开发者；第二类是想统计自己 Codex 使用强度、Token 花在哪的重度用户；第三类是做 Agent 调试、需要看清 tool call 与 tool output 对应关系的人。整个分析过程以本地数据为主，Session 不需要先上传到远程服务，这点对在意代码隐私的人比较友好。
不过这里有个容易被忽略的前提：Codex Viz 只负责"看"，它不负责"跑"。你真正跑 Codex 任务时，模型请求走的是哪条 API 通道、用的哪个 Key、哪个 Model ID，这些决定了 Session 日志里记录的内容长什么样。所以这篇教程我会分两条线走：一条是把 Codex 的请求通道用 TaoToken 统一配好，保证 Session 数据来源稳定；另一条是把 Codex Viz 跑起来，导入 Session 数据，验证可视化面板能正常渲染。两条线都跑通，你才算真正拥有一个可复盘的 Codex 工作流。
下面先讲通道配置，再讲 Codex Viz 的安装与验证。顺序别颠倒，因为如果 Codex 本身没跑出规范的 Session，Codex Viz 打开也是空的。
2. 用 TaoToken 统一 Codex 请求通道：Base URL 与 Key 怎么配
在装 Codex Viz 之前，先把 Codex 的请求出口理顺。很多人 Codex Session 日志混乱，根源不在 Codex Viz，而在于请求通道换过好几次、Key 散落在不同地方，导致 Session 里记录的模型行为不一致，复盘时对不上号。我的做法是用 TaoToken 做统一通道，Base URL 固定指向https://taotoken.net/api，Key 和 Model ID 集中管理。
TaoToken 在这里扮演的角色是统一的 API 接入层：你拿到一个 Key，就能通过同一个 Base URL 访问不同模型，Codex 的请求配置里只需要维护一份地址和一份 Key。官网在https://taotoken.net/?utm_source=taotoken_aicg_blog_end，注册和拿 Key 的入口都在上面。API 地址是https://taotoken.net/api，注意这个地址后面不加任何多余路径，Codex 的 OpenAI 兼容配置会自己拼接/v1/...之类的后缀。
先说清楚三件套，这是后面所有配置的基础，缺一不可：
| 配置项 | 值 | 说明 |
|---|---|---|
| Base URL | https://taotoken.net/api | 统一请求入口，Codex 走 OpenAI 兼容协议 |
| API Key | 在 TaoToken 控制台生成 | 形如sk-...，只显示一次，务必存好 |
| Model ID | 例如gpt-5-codex或你实际使用的模型 | 必须和通道支持的模型名一致 |
拿 Key 的路径是：登录官网后进入控制台，找到 API Keys 页面新建一个 Key。这个 Key 就是 Codex 请求时携带的凭证。如果你还没建过，可以直接走这个入口：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite。生成后立刻复制保存，页面刷新后就看不到了。
接下来是 Codex 的配置。Codex CLI 支持通过auth.json和配置文件指定自定义 Base URL。我实测下来，最稳的方式是同时配好环境变量和auth.json，避免某一边没生效导致请求打到默认地址。先看auth.json，它一般位于~/.codex/auth.json（Windows 是C:\Users\你的用户名\.codex\auth.json）：
{ "OPENAI_API_KEY": "sk-你的TaoToken密钥", "OPENAI_BASE_URL": "https://taotoken.net/api" }注意OPENAI_BASE_URL这里填的就是https://taotoken.net/api，不要写成https://taotoken.net/api/v1，Codex 内部会自己补/v1。写多了反而会拼成/v1/v1/...导致 404。
然后是 Codex 的主配置文件~/.codex/config.toml，把模型和通道参数写进去：
model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "OPENAI_API_KEY" wire_api = "chat"这里几个字段值得解释。model_provider指向下面定义的taotoken段；base_url同样是https://taotoken.net/api；env_key告诉 Codex 从环境变量OPENAI_API_KEY读 Key；wire_api = "chat"表示走 Chat Completions 协议，这是目前兼容性最好的选项。如果你用的是支持 Responses API 的模型，也可以改成responses，但先用chat跑通更稳妥。
环境变量这边，Linux/macOS 在~/.zshrc或~/.bashrc里加：
export OPENAI_API_KEY="sk-你的TaoToken密钥" export OPENAI_BASE_URL="https://taotoken.net/api"Windows PowerShell 用：
$env:OPENAI_API_KEY="sk-你的TaoToken密钥" $env:OPENAI_BASE_URL="https://taotoken.net/api"配完之后，先别急着装 Codex Viz，先验证 Codex 本身能正常跑通。随便让它执行一个小任务，比如"列出当前目录文件并写入 list.txt"。跑完后去~/.codex/sessions看有没有新的 JSONL 文件生成。有，说明通道通了，Session 数据也在正常落盘，这时候再上 Codex Viz 才有意义。如果这一步就报 401，先回去检查 Key 有没有复制完整、auth.json的字段名有没有写错。
3. 启动 Codex Viz：Next.js 项目安装与 pnpm 构建脚本处理
通道配好、Session 有数据之后，进入 Codex Viz 的安装环节。Codex Viz 是一个 Next.js 项目，官方仓库在 GitHub 上，安装流程本身不复杂，但 pnpm 的构建脚本拦截是新手最容易卡住的地方，我会重点讲。
第一步，克隆仓库并进入目录：
git clone https://github.com/onewesong/codex-viz.git cd codex-viz第二步，确认包管理器。项目用的是 pnpm，如果你本机没装，先全局装一个：
npm install -g pnpm装完用pnpm -v确认版本，能打印出版本号就行。
第三步，安装依赖：
pnpm i这一步大概率会蹦出这么一段提示：
[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: sharp@0.34.5 Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.这不是报错，是 pnpm 的安全机制。pnpm 默认不执行依赖包的 postinstall 构建脚本，而sharp这个图像处理库需要编译原生模块，被拦下来后 Codex Viz 里涉及图片或图表渲染的部分可能出问题。解决办法就是按提示执行：
pnpm approve-builds执行后会进入一个交互式列表，用方向键找到sharp，按空格勾选，再按回车确认。勾选完成后，重新跑一次：
pnpm install这次应该显示Already up to date或者正常完成，不再有 ignored builds 的警告。到这里依赖就装干净了。
第四步，启动开发服务器：
pnpm dev启动成功后终端会打印本地地址，默认是http://localhost:3000。在浏览器打开这个地址，就能进入 Codex Viz 的 Dashboard。项目本身也提供pnpm build和pnpm start用于生产模式，但复盘场景下pnpm dev足够，热更新还方便你改配置。
这里有个细节要提醒：Codex Viz 读取的是本机~/.codex/sessions目录。如果你是在容器或远程机器上跑 Codex Viz，而 Session 数据在另一台机器上，需要把 sessions 目录挂载或拷贝过来，否则 Dashboard 会是空的。我建议直接在跑 Codex 的同一台机器上启动 Codex Viz，省去数据搬运的麻烦。
启动后如果页面白屏或者报模块找不到，先看终端有没有编译错误。Next.js 首次启动会做一次完整编译，稍等十几秒再刷新。如果终端报Module not found，多半是pnpm i没跑完或者approve-builds没处理，回去重跑一遍依赖安装。
4. 导入 Session 数据并验证可视化面板渲染成功
Codex Viz 启动后，打开http://localhost:3000，它会自动索引本地 Codex Session 并进入 Dashboard。这一步的验证目标是：确认 Session 数据被正确读取、Dashboard 指标有数字、单个 Session 时间线能展开。
先看 Dashboard 顶部，应该有四项核心指标：会话数、消息量、Token 消耗、错误/中断次数。如果这四项全是 0，说明 Codex Viz 没找到 Session 数据，检查~/.codex/sessions目录是否存在、里面有没有.jsonl文件。如果目录存在但页面还是空，可能是 Codex Viz 的读取路径配置问题，看项目 README 里有没有环境变量可以指定 sessions 路径。
指标有数字之后，往下看使用趋势区域。这里会展示会话、消息、工具调用的时间分布，以及 Token 的构成（输入、输出、缓存输入、推理输出）。拖动底部时间轴，各项统计会同步刷新。你可以借此确认：最近哪段时间 Codex 用得最密集、Token 主要消耗在输入还是输出。这一步能正常交互，说明前端渲染和数据绑定都没问题。
再往下是 Top 工具和词云。Top 工具展示 Codex 最常调用的工具，词云提取你输入里的高频词。这两块能正常显示，说明 Codex Viz 对 tool call 和 user 消息的解析是通的。
Dashboard 验证完，进入单个 Session 的验证。点击会话列表，可以按关键词、工具调用、错误/中断筛选。列表会展示每个 Session 的开始时间、时长、消息数、工具调用数、错误数、工作目录。选一个目标 Session，点"查看"，进入完整时间线。
详情页顶部会显示 Session ID、cwd、Token、user、assistant、tool call、tool output、error 这些汇总。往下是时间线，核心阅读顺序是：
user → assistant → tool call → tool output → assistant分别对应：Codex 收到了什么、准备怎么做、实际执行了什么、执行结果是什么、根据结果怎么继续。验证时重点看 tool call 这一环，因为 assistant 说的是"准备做什么"，tool call 才是"真正做了什么"。比如时间线里出现：
*** Add File: attention_demo.py说明 Codex 真的创建了文件；出现：
python ./attention_demo.py说明它不只是写了代码，还实际运行验证了。这些事件能在时间线里正确渲染、顺序正确、tool output 能对应到前面的 tool call，就说明 Codex Viz 的会话还原是成功的。
有一个验证技巧：找一个你印象里报过错的 Session，看时间线里 error 事件有没有被标出来、位置对不对。如果错误事件能准确定位到具体步骤，那这个可视化面板的可用性就达标了。
5. 常见报错排查：401、local proxy failed、reading choices 与 OAuth
配置和启动过程中，有几类报错出现频率特别高，我按实际遇到的顺序整理一下排查思路。
401 Unauthorized。这个基本都出在 Key 或 Base URL 上。先确认auth.json里的OPENAI_API_KEY和 TaoToken 控制台生成的 Key 完全一致，注意有没有多复制空格或换行。再确认OPENAI_BASE_URL是https://taotoken.net/api，没有多写/v1。如果 Key 是对的还报 401，去控制台看这个 Key 是不是被禁用或额度用尽。还有一种情况是环境变量和auth.json同时存在但值不一样，Codex 优先读了环境变量，导致用了旧 Key，把两边统一即可。
local proxy failed。这个报错通常出现在 Codex 尝试走本地代理但代理没起来的时候。检查你的环境变量里有没有残留的HTTP_PROXY、HTTPS_PROXY指向一个已经关掉的本地端口。如果有，清掉这些变量再试。另外确认config.toml里没有配置多余的代理字段。Codex 直连https://taotoken.net/api即可，不需要额外代理层。
reading choices 相关报错。这类错误一般出现在响应解析阶段，提示读取choices字段失败。原因通常是通道返回的响应结构和 Codex 期望的不一致。先确认config.toml里wire_api = "chat"，因为choices是 Chat Completions 协议的字段。如果你误设成了responses，而当前模型或通道返回的是 chat 格式，就会解析失败。改回chat再试。如果还报，检查 Model ID 是否拼写正确，模型名不对时有些通道会返回错误结构而非标准响应。
OAuth 相关报错。如果你之前用 OAuth 方式登录过 Codex，本地可能残留了 OAuth 凭证，Codex 会优先尝试 OAuth 而不是 API Key。表现是明明配了 Key 却提示认证失败或跳转登录。解决办法是清理 Codex 的 OAuth 缓存，通常在~/.codex/下找和 auth 相关的缓存文件，或者重新执行一次登录流程切换到 API Key 模式。确保auth.json里的 API Key 配置生效，OAuth 残留清掉。
排查时有个通用原则：先隔离变量。把 Codex 单独跑通（不涉及 Codex Viz），确认 Session 能正常生成；再单独跑 Codex Viz，确认能读到已有 Session。两边都独立正常，再合起来用。这样出问题时能快速定位是通道问题还是可视化问题。
另外，如果你在配置里用到了 CC Switch、Cline MCP 或 Codex 的auth.json，记住三件套必须写全：Base URL、Key、Model ID。少任何一个都会导致请求失败，而失败信息往往不会直接告诉你缺了哪个，所以配置时逐项核对最省时间。
6. 把 Codex 使用过程变成可复盘的账本
Codex Viz 跑通之后，你手里其实多了一份 Codex 使用账本。Dashboard 回答"用了多少"——会话数、消息量、Token 消耗、错误次数；单个 Session 回答"怎么完成的"——调了哪些工具、执行了哪些命令、哪一步出错、上一步结果如何影响下一步。这两层结合起来，Codex 的每次任务从黑盒变成了可追溯的执行记录。
我自己的用法是：每周看一次 Dashboard 的趋势，确认 Token 消耗有没有异常飙升；遇到任务跑偏时，回到对应 Session 的时间线，顺着user → assistant → tool call → tool output找断点。多数时候问题出在某个 tool call 的输入不对，或者 tool output 没被正确理解，这些在时间线里一眼就能看出来。
需要说清楚边界：Codex Viz 能看到 Codex 做了什么，但不能解释模型内部为什么这么判断。它是执行记录，不是推理透视。想深入调模型行为，还是得回到 prompt 和上下文设计上。
如果你还没配好通道，建议先把 TaoToken 的 Base URLhttps://taotoken.net/api和 Key 落到auth.json与config.toml里，跑一个任务确认 Session 正常生成，再启动 Codex Viz。通道稳了，可视化才有稳定的数据源。需要生成 Key 走https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite，接入细节看文档https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite。想先验证模型对话是否正常，可以用https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite试一轮。长期跑编码和 Agent 任务的话，Coding Plan 入口在https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite，适合把通道固定下来再慢慢复盘。
