说实话Codex 在终端里干活的样子像极了那种把自己关在工位上闷头猛干的同事——你只看见命令一行行往外蹦但到底改了多少个文件、哪个任务卡住了、这轮对话烧了多少 token、中途回滚了几次你一概不知。我拿 Codex 跑了将近两个月的批量改代码任务一边享受它自动修 bug 的爽感一边忍受“全程盲操作”的不安最后实在憋不住了干脆给我的 Codex 单独搭一个可视化办公室把所有运行状态、会话记录和文件变更全部摊到浏览器里看清楚。这个项目做完之后我发现这事比想象中简单也比想象中实用今天把它完整拆开讲。1. 先搞清楚一个问题Codex 到底缺什么1.1 终端里的 Codex 很强但反馈太“原始”Codex 本质上是跑在终端里的 AI 编程代理你给它一个任务它会自己读代码、改文件、跑命令、看报错再继续改。这个循环非常适合自动化执行但它的输出方式是典型的“终端流式文本”一堆颜色各异的字符刷过去任务一多或者会话一长你就分不清哪条消息对应哪个任务、哪个文件被改过、改完以后测试到底过没过。我以前的做法是开了好几个终端窗口每个窗口跑独立的 Codex 会话哪个窗口不动了就切过去看。听着还行实际上一小时下来眼睛就花了。真正让我决定动手的是一件事某次它自动重构了一个模块改完以后测试挂了但我压根不知道它动了哪些文件想回滚都不知道去哪回滚。那一刻我就明白我需要一个能记录、能检索、能统计的“可视化层”而不是继续对着终端猜。1.2 可视化办公室要解决的四个问题状态可见性当前有几个 Codex 会话在跑各自处于什么阶段读代码、改文件、跑命令一眼看清。变更可追溯每个会话改了哪些文件、新增多少行、删除多少行、有没有 apply_patch 失败记录。成本可量化每次会话消耗了多少 token、调了多少次模型接口、整体趋势怎么样。操作可回放会话结束之后还能按时间线翻看当时的完整上下文而不是关掉窗口就没了。听起来很像数据可视化大屏对不对确实我本质上是把 Codex 当成了一个“数据生产者”然后给它的产出做了一套专属的大屏系统。它不需要覆盖全部功能只要解决上面四个痛点就算成功。1.3 为什么不用现成方案而要自己搭Codex 生态里其实已经出现了一些第三方工具、VSCode 插件和桌面客户端人家也做得不错。但我的情况比较特殊我同时要管好几台机器上的 Codex 任务而且希望把历史会话集中归档还想把 token 消耗和项目维度绑定起来做统计。现成工具大多是单机单会话的形态很难满足这种“办公室管理”的需求。自己搭还有一个现实原因Codex 的数据本地化程度很高会话文件、日志文件、配置文件全在自己的目录里并没有一个明确说“你来读我吧”的开放 API。这意味着无论用什么工具都得先解决数据解析的问题而一旦把解析逻辑握在自己手里后续想加什么展示都方便。2. 整体架构设计与技术选型2.1 核心思路监听本地数据Web 端做展示我管这个方案叫“旁路监听”不改 Codex 本身也不做任何注入。Codex 在跑任务的时候会持续把数据写到本地目录我只需要另外起一个服务去读这些数据整理成接口再送到浏览器渲染。这样有几个好处第一Codex 的任何版本更新都不会破坏我的核心链路最多改一下解析逻辑第二即便 Codex 崩了我的历史记录和统计依然还在第三整个过程不需要动 Codex 的配置风险最低。架构上分了三层数据层会话 JSONL 文件、运行日志文件、配置文件以及我自己建的 SQLite 索引库。服务层一个本地 Web 服务负责扫描、解析、缓存数据通过 WebSocket 推送实时更新通过 HTTP 接口提供历史查询。展示层浏览器里的仪表盘页面包含会话列表、任务状态卡片、文件变更时间线、token 消费图表。整个系统跑在 localhost 上不开外网端口纯本地使用。因为我只需要自己在浏览器里看没必要暴露到公网降低安全风险。2.2 技术栈为什么这么选后端我选了 FastAPI Python。原因很直接Codex 的会话文件是 JSONL 格式用 Python 解析几乎不用写多余的胶水代码如果涉及文件差异对比、token 估算Python 生态里现成的库也最多。前端Vue 3 ECharts。其实用不用框架都行但我后面要加图表、时间线、实时列表Vue 的响应式能省不少事。ECharts 则承担了所有的曲线图和饼图包括 token 趋势、任务耗时分布这些。实时推送WebSocket。Codex 执行任务时我希望页面上的状态不要靠手动刷新而是像看直播一样自己滚动。用 WebSocket 把日志解析后的结构化事件推过去比前端轮询优雅得多。有人可能问用 Node.js 是不是更简单也行但我的主力语言是 Python而且后续想把采集到的数据直接用 pandas 做分析所以后端定为 Python 更顺手。做这类工具选自己最熟的技术栈永远比选“最流行”的更重要。2.3 数据源细节Codex 到底把东西写在哪Windows 和 Linux/macOS 的路径有差异但逻辑一致。我以 Linux 为例会话文件~/.codex/sessions/目录下按日期或会话 ID 存成 JSONL每行是一条消息包含 role、内容、时间戳、模型等字段。运行日志~/.codex/log/目录下一般有codex-tui.log之类的文件记录终端交互的底层细节。配置文件~/.codex/config.toml里面写着模型选择、provider 配置、权限控制等。我的服务启动时先全量扫描一遍这些文件建立索引之后进入监听模式发现新文件或文件更新就增量解析。这里有一个非常关键的判断不能直接拿日志文件当唯一数据源。因为日志是给人看的文本格式在不同版本里变化很大而 JSONL 会话文件才是结构化的哪怕以后 Codex 更新只要消息结构还在解析逻辑就还能用。3. 核心模块实操实现3.1 会话解析模块把 JSONL 变成结构化记录每个会话文件本质是一串 JSON 对象关键字段大致包括消息角色、正文内容、创建时间以及一些内部元数据。我的解析器做的事情很简单按行读取 JSONL跳过空行和解析失败的行。提取每条消息的角色和内容按时间戳排序。在内容里通过关键词匹配识别动作类型读文件、写文件、执行命令、收到报错。将会话级信息汇总成一条记录会话 ID、开始时间、结束时间、消息条数、模型名、涉及文件列表。这里有一个容易踩的坑会话文件在 Codex 运行过程中是持续写入的如果解析器每次都从头读整个文件会话一长性能就会越来越差。我的做法是记录每个文件的读取偏移量增量读取新追加的行如果检测到文件被重写比如 Codex 做了归档再重新全量解析。另一个坑是编码。Codex 在 Windows 上写会话文件可能带 BOM直接按 UTF-8 读会在首行多出一个不可见字符。我在读取时统一用utf-8-sig顺手解决。3.2 实时状态推送怎么让页面“自己动起来”我想要的效果是Codex 每新增一条消息浏览器里的对应会话卡片就更新一次不需要任何人去点刷新。实现链路是这样的后端维护一个全局事件队列解析器发现新消息后把事件放进队列。WebSocket 连接建立时先给前端推一份全量快照之后每次有新事件只推送增量。前端收到事件后根据会话 ID 找到对应卡片原地更新内容。这里我用了事件总线的模式而不是每个会话单独开一个 socket。因为浏览器页面通常只需要同时看一个总览把所有事件合成一个流反而简单。前端再做一层节流如果一秒内来了超过 20 条事件就合并成一条批量更新防止渲染卡顿。实测下来一个长会话在跑的时候页面基本能做到半秒以内的延迟体感上就是“跟着它在动”。这种实时反馈带来的安全感是终端刷日志完全比不了的。3.3 文件变更追踪还原每次改动的具体位置这是整个项目里我觉得最有价值的部分。Codex 修改代码的方式是生成 apply_patch 格式的差异内容在会话消息里可以看到哪些文件被改、哪些行被加、哪些行被删。我的模块把这些差异解析成结构化数据文件路径修改类型新增、修改、删除新增行数、删除行数变更前后的代码片段保留关键上下文在页面上我用一条时间线把某个会话的所有文件变更按顺序排列出来点击任意一条就能看到对应的 diff 视图。这个功能解决了我最开始的痛点任务结束后我能立刻知道它到底动了什么。而且我可以把 diff 复制出来直接拿去给同事 review或者自己确认后再决定要不要保留。解析 diff 的时候要特别小心Codex 的 patch 不一定是标准 unified diff有时候会带一些特殊标记。我做的兼容处理是先按常规 diff 解析遇到无法解析的块就整块降级成“未解析变更”只记录文件路径和前后片段长度不强行分解。宁可少展示一点细节也不能解析错。3.4 用量统计token 与耗时可视化Codex 的会话消息里通常带有 usage 信息包含输入、输出的 token 数量。我把这些数据单独抽成一张统计表按天、按项目、按模型三个维度聚合。ECharts 在这块起了大作用我画了三个图一个是折线图展示每日 token 消耗趋势一个是柱状图对比各项目的调用次数和耗时一个是饼图看不同模型的用量占比。虽然这些图在“大数据大屏”面前很朴素但对我准确掌握自己的成本结构很有帮助。看完统计我才发现约六成的 token 消耗来自“让 Codex 反复读日志找报错”从那以后我开始在提示词里直接贴关键报错片段省了不少钱。3.5 快捷操作区把高频动作做成按钮可视化办公室不能光看还得能做事。我加了一个操作区功能不太复杂但对日常使用很关键一键复制 Codex 会话中的最后一条命令。把指定会话导出成 Markdown 或 HTML方便归档和分享。从历史会话里检索包含某段代码的会话直接跳转。运行环境选择可以为不同项目绑定不同的启动命令和工作目录。这块功能做起来不难但要注意安全任何从页面触发的操作都必须做二次确认尤其是“重跑某条命令”因为命令可能包含rm -rf这类危险动作。我可不想因为一个按钮点错把整个项目删了。4. 配置与接入细节4.1 应对 Codex 配置的差异Codex 的配置文件config.toml里可以指定模型、模型提供商、权限模式等。我做的第一版可视化面板绑定死了默认模型名结果同事把模型换成第三方服务之后会话文件里的模型字段跟我预期不一致导致统计出错。后来我改成模型名全部做成动态映射只读接口显示不做硬编码判断。同时解析config.toml时先提取当前生效的模型和 provider再反过来修正统计图表的图例名称。如果解析失败就退回显示原始字段值绝不因为配置格式变化让整个面板崩掉。这里也顺带提一句Codex 本身是可以接入不同模型提供商的配置文件里 provider 字段改一下就行。我的可视化面板对 provider 没有特殊限制因为它只读取会话数据不关心请求具体发给谁。所以无论你用官方模型还是第三方模型这个面板都能正常展示。我自己测试过切换模型之后历史会话依旧可以完整回放只是成本统计里的“模型名”变了而已。4.2 多项目隔离与工作目录映射我经常同时处理三四个项目Codex 启动时的工作目录决定了它改的是哪个仓库。但会话文件里未必会直接写“项目名”只会把文件路径写进去。我做了一层映射在配置中心维护一份项目清单每个项目对应一个根目录路径。解析到会话涉及的文件路径时用最长前缀匹配算出所属项目。页面按项目维度展示时填充自定义的项目显示名和备注。这个映射逻辑不复杂但使用体验提升巨大。以前我只能看到一片文件路径现在页面上清清楚楚写着“项目A-登录模块重构”“项目B-接口文档生成”一眼就能定位到某个任务。4.3 前端页面布局与交互要点页面的信息密度要高但也不能堆成真正的“大屏广告牌”毕竟我是拿来干活的不是拿来看的。我的布局分四块顶部状态栏当前活动会话数、今日 token 消耗、最近一次任务结束时间。左侧会话列表按时间倒序卡片显示项目名、状态、耗时、文件变更数。中间主区域选中的会话详情包含消息时间线和文件 diff。右侧统计面板三张图表和时间筛选器。交互上有一个很实用的细节会话消息按“动作块”聚合而不是一条一条平铺。比如连续三条消息都是在读文件我就折叠成“读取了 3 个文件”一行展开才看到细节。这样页面长度大幅缩短扫一眼就能知道 Codex 在干什么。5. 踩坑记录与问题排查实录5.1 会话文件读不到内容我一开始直接在 Codex 运行的同时去读会话文件偶尔读到一半内容为空。后来才发现这是写入缓冲导致的。Codex 不是每写一行就立刻 flush 到磁盘解析器读到的可能是还没来得及落盘的内容。解决办法解析逻辑检测到文件大小最近几秒没有变化才做全量解析如果文件仍然在增长就只追加解析尾部数据。另外一个更省事的替代方案是直接监听日志目录的文件变化事件但要注意事件触发的频率很高必须做防抖处理否则你会看到 CPU 在跑。5.2 单个会话文件高达几十 MB跑过大型重构任务的人都会遇到这种情况一个会话几千条消息JSONL 文件轻松超过 30MB。如果每次打开详情页面都把整个文件加载进来浏览器必卡。我的方案是分两级会话列表页只读索引库中的摘要字段不碰正文进入详情页后先只加载前 100 条消息用于快速预览用户往下滚动时再按需加载更多。索引库我用的是一个本地 SQLite 文件虽然技术老套但这种负载下反而最稳。5.3 WebSocket 推送风暴导致前端卡死Codex 高峰期每秒钟能产生好几十条日志事件如果全部实时推到前端浏览器事件循环会被塞满。我加了三道闸后端合并同类型事件每 500ms 批量推一次。前端对 dom 更新做 requestAnimationFrame 节流。页面处于后台标签页时暂停详情刷新只更新状态数字。加了闸之后即使 Codex 疯狂刷日志页面帧率也能保持稳定。这里我特别想强调做实时面板核心不是推得快而是合并得聪明。实时是手段可读才是目的。5.4 版本升级后解析崩溃Codex 有一次版本更新之后把会话文件里的消息结构改了导致我的解析器大面积报错统计表里突然多出很多“未知类型”的行。这个问题的根源在于我把内部字段结构当成了稳定契约。修正方案是把解析逻辑从主流程里解耦加了一个“适配器”层。每个适配器对应一种消息结构版本解析时先探测版本再选择适配器没匹配到的单独丢到“待兼容”列表里并在页面上用黄色标签提示。这样即使未来 Codex 再改结构我的旧数据不会丢失新数据也能在修复后自动补上解析。5.5 跨平台路径与编码在 Linux 上跑得好好的放进 Windows 就出了问题。一是磁盘路径分隔符不同二是终端编码导致乱码。我的做法是所有路径统一抽象成“逻辑路径”存储时用标准化的 POSIX 风格展示时再按平台转换。读取文件时优先尝试 UTF-8失败后回退到 GBK 或 Latin-1并在详情页标记“该文件使用了非 UTF-8 编码部分内容可能显示异常”。这类问题平时遇不到一旦遇到就特别隐蔽。我的建议是如果你只在一台机器上用不用折腾兼容但如果要团队共用跨平台问题越早处理越省心。5.6 单机多开 Codex 实例的冲突我有时会同时开两个 Codex 实例处理不同项目它们会各自写会话文件。最开始我的索引逻辑很简单按“文件路径 文件修改时间”排重结果同一个会话被两个实例同时写的话会出现串数据。后来我才意识到会话文件本身带有会话 ID唯一标识应该用会话 ID 而不是文件路径。我重建了索引表结构以会话 ID 为主键文件路径只是辅助定位字段同时记录最近一次读取位置。现在无论开多少个实例数据入索引都不会乱。6. 最后分享一点实用经验这个项目做到中期的时候我一度陷入了“图表越加越多、按钮越加越多”的膨胀状态什么都想可视化每个数据都觉得能做成一张卡。直到有一次我为了看一个简单的问题需要先找到页面、再调整时间范围、再点开三层菜单我才突然意识到——这个可视化办公室已经偏离了最初的目标。我后来做了两件事第一把所有页面上超过 7 天都没点过的功能找出来砍掉或收进“高级设置”第二给页面加了一个“极简模式”只剩会话列表、状态和最新时间线。结果反而极简模式成了我平时默认打开的页面完整模式变成了每周做总结时才用。另外如果你也想做类似的东西我给你三个最朴素的建议第一先解决“看到状态”再解决“看到图表”别一上来就堆数据大屏第二所有解析逻辑禁止直接依赖某个具体软件版本里的字段名多做一层映射第三实时连接必须做断线重连。WebSocket 这东西在本地网络里已经是相对最稳的方案了但电脑休眠、浏览器锁屏、服务重启这些场景都会断断线之后自动恢复的能力比“永不掉线”的承诺更实际。我个人在这套可视化办公室上最大的体会是它并没有让我少盯着 Codex而是让我盯得更准了。以前我要花大量时间在输出流里翻找“这轮到底干了什么”现在打开页面扫一眼状态和文件变更数就心里有数。如果你也被终端里那种盲盒式体验折磨过照着这个思路自己搭一套本地面板你会回来感谢自己的。