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 本身没跑出规范的 SessionCodex Viz 打开也是空的。2. 用 TaoToken 统一 Codex 请求通道Base URL 与 Key 怎么配在装 Codex Viz 之前先把 Codex 的请求出口理顺。很多人 Codex Session 日志混乱根源不在 Codex Viz而在于请求通道换过好几次、Key 散落在不同地方导致 Session 里记录的模型行为不一致复盘时对不上号。我的做法是用 TaoToken 做统一通道Base URL 固定指向https://taotoken.net/apiKey 和 Model ID 集中管理。TaoToken 在这里扮演的角色是统一的 API 接入层你拿到一个 Key就能通过同一个 Base URL 访问不同模型Codex 的请求配置里只需要维护一份地址和一份 Key。官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end注册和拿 Key 的入口都在上面。API 地址是https://taotoken.net/api注意这个地址后面不加任何多余路径Codex 的 OpenAI 兼容配置会自己拼接/v1/...之类的后缀。先说清楚三件套这是后面所有配置的基础缺一不可配置项值说明Base URLhttps://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_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite。生成后立刻复制保存页面刷新后就看不到了。接下来是 Codex 的配置。Codex CLI 支持通过auth.json和配置文件指定自定义 Base URL。我实测下来最稳的方式是同时配好环境变量和auth.json避免某一边没生效导致请求打到默认地址。先看auth.json它一般位于~/.codex/auth.jsonWindows 是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/v1Codex 内部会自己补/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/apienv_key告诉 Codex 从环境变量OPENAI_API_KEY读 Keywire_api chat表示走 Chat Completions 协议这是目前兼容性最好的选项。如果你用的是支持 Responses API 的模型也可以改成responses但先用chat跑通更稳妥。环境变量这边Linux/macOS 在~/.zshrc或~/.bashrc里加export OPENAI_API_KEYsk-你的TaoToken密钥 export OPENAI_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:OPENAI_API_KEYsk-你的TaoToken密钥 $env:OPENAI_BASE_URLhttps://taotoken.net/api配完之后先别急着装 Codex Viz先验证 Codex 本身能正常跑通。随便让它执行一个小任务比如列出当前目录文件并写入 list.txt。跑完后去~/.codex/sessions看有没有新的 JSONL 文件生成。有说明通道通了Session 数据也在正常落盘这时候再上 Codex Viz 才有意义。如果这一步就报 401先回去检查 Key 有没有复制完整、auth.json的字段名有没有写错。3. 启动 Codex VizNext.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: sharp0.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_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。想先验证模型对话是否正常可以用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite试一轮。长期跑编码和 Agent 任务的话Coding Plan 入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite适合把通道固定下来再慢慢复盘。