Codex Session 可视化：Codex Viz 实测教程

目录

• 1. Codex Viz 是什么
• 2. Codex Viz 怎么安装
• 3. Dashboard：整体使用情况怎么看
• 4. 单个 Session：一次任务具体怎么完成
• 5. Codex Viz 总结

1. Codex Viz 是什么

Codex 每次运行都会产生一段 Session，并以 JSONL 日志保存在本地，记录对话、工具调用和 Token 消耗等信息。

Codex Viz 的作用，就是把这些难以直接阅读的日志，转成可视化 Dashboard。

它读取本地 ~/.codex/sessions 数据，并将 Session、消息、工具调用、Token 消耗和高频关键词等信息集中展示。

一句话概括：

Codex Viz，就是给 Codex Session 加上一层可视化分析界面，让原本藏在日志里的使用过程变得可读、可分析。

整个分析过程以本地数据为主，不需要先把 Session 上传到远程服务，比较适合用来复盘自己使用 Codex 的过程。

2. Codex Viz 怎么安装

Codex Viz 基于 Next.js，官方安装只需两步：安装依赖并启动服务。

首先克隆仓库：

git clone https://github.com/onewesong/codex-viz.git
cd codex-viz

项目使用 pnpm。如果本机没有，先安装：

npm install -g pnpm

然后安装项目依赖：

pnpm i

如果出现：

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: sharp@0.34.5

说明 sharp 的构建脚本被 pnpm 拦截。执行：

pnpm approve-builds

选中 sharp：按 Space 勾选，再按 Enter 确认：

随后重新检查依赖：

pnpm install

出现 Already up to date 或正常完成后，即可启动 Codex Viz：

pnpm dev

启动成功后，在浏览器打开：

http://localhost:3000

即可进入 Codex Viz Dashboard。
项目本身提供 dev、build 和 start 等标准 Next.js 命令。

3. Dashboard：整体使用情况怎么看

启动 Codex Viz 后，打开：

http://localhost:3000

页面会自动索引本地 Codex Session，并进入 Dashboard。整个界面可以分成三部分来看。

3.1 整体使用情况

顶部汇总四项核心指标：

• 会话数：Session 数量
• 消息量：用户与 Codex 的交互次数
• Token：输入、输出及缓存消耗
• 错误/中断：执行异常次数

这里适合先回答一个最简单的问题：

这段时间 Codex 用了多少、聊了多少、消耗了多少 Token。

3.2 使用趋势

趋势雷达用来观察 Codex 的使用强度与 Token 消耗变化。

使用情况：会话、消息、工具调用
Token 构成：Token、Prompt、输入、输出、缓存输入、推理输出

拖动底部时间轴，可以聚焦任意时间段，各项统计会同步刷新。

主要看两件事：

• 什么时候使用最集中
• Token 主要消耗在哪里

3.3 Token、工具和输入内容

Token 可继续拆分为输入、输出、缓存输入和推理输出，用于判断消耗主要来自哪里。

页面底部的 Top 工具展示最常调用的工具，词云则提取用户输入中的高频内容。

这部分主要回答：Token 花在哪，Codex 常用什么工具，最近主要在做什么。

至此，原本分散在 JSONL 中的 Session 日志，就被整理成了可直接观察的使用量、趋势、消耗和行为数据。

4. 单个 Session：一次任务具体怎么完成

单个 Session 怎么看

趋势雷达看整体，单个 Session 看的是：一次任务具体怎么跑完。

进入 会话列表，可按关键词、工具调用、错误/中断筛选。列表会展示：

开始时间 · 时长 · 消息数 · 工具调用 · 错误数 · 工作目录

选择目标 Session，点击 「查看」，即可进入完整时间线。

① 先看顶部：这次任务在哪里跑、规模多大

详情页顶部会显示：

Session ID · cwd · Token · user · assistant · tool call · tool output · error

其中：

• cwd：任务执行目录；
• tool call：实际执行了多少操作；
• error：过程中是否报错；
• Token：这次任务的上下文与输出消耗。

② 找到真正的任务起点

时间线里的 user 不一定都是手动输入，也可能包含 Codex 自动注入的环境信息、插件信息、AGENTS.md等。

因此，先找到真正的 Prompt，再从这里往下看。

例如本次任务的起点是：

阅读《Attention Is All You Need》→ 总结 Transformer → 生成 attention_notes.md

③ 顺着执行链看

单个 Session 最核心的阅读方式是：

user → assistant → tool call → tool output → assistant

分别表示：

• user：Codex 收到了什么；
• assistant：准备怎么做；
• tool call：实际执行了什么；
• tool output：执行结果是什么；
• 后续 assistant：根据结果怎么继续。

例如这次任务的实际过程是：

制定计划 → 搜索本地论文 → 未找到 → 改用公开论文 → 生成笔记 → 检查文件

④ 重点看 tool call

assistant 告诉你 Codex 准备做什么，tool call 才告诉你它 真正做了什么。

重点看三项：

调用什么工具 · 执行什么命令 · 在哪个目录执行

例如：

python .\attention_demo.py

说明 Codex 不只是写了代码，还实际运行并验证了结果。

再如：

*** Add File: attention_demo.py

说明它真正创建了文件。

⑤ 多轮 Session 看“结果如何继续被使用”

多轮对话的价值，在于能看到 Codex 如何基于上一轮结果继续工作。

这次 Session 的四轮任务可以概括为：

读论文并写笔记
→ 重新核对并修改笔记
→ 实现 Attention 示例并运行
→ 检查笔记与代码是否一致

所以，看完一个 Session，最终只需要回答四个问题：

收到了什么任务？
准备怎么做？
实际做了什么？
上一步结果如何影响下一步？

能回答这四个问题，这个 Session 就基本看懂了。

5. Codex Viz 总结

Codex Viz 的价值，不在“可视化”本身，而在于把 Codex 的使用过程变成可复盘、可分析的数据。

它主要回答三类问题：

• 用了多少：Session、消息和 Token 消耗情况；
• 怎么完成：调用了哪些工具、执行了哪些操作、哪里出现异常；
• 平时怎么用：常用哪些工具、主要做什么、使用强度如何变化。

看整体，用 Dashboard；看具体过程，就回到单个 Session。

因此，Codex Viz 更像一份 Codex 使用账本和执行记录：既能看长期使用情况，也能还原一次任务是怎么完成的。

它的边界也很明确：能看到 Codex 做了什么，但不能完全解释模型内部为什么这样判断。