AI 2026年7月7日 2 分钟阅读

AI 编码 Agent 运行时是黑箱？Agent Log Viewer 让你像看聊天记录一样监控每一次工具调用

tinyash 0 条评论

文章信息

发布时间 2026年7月7日
作者 tinyash
阅读时长 2 分钟阅读

问题现象：Agent 在跑，但你不知道它在做什么

如果你经常用 Claude Code 或 Codex CLI 写代码，一定遇到过这样的场景：你启动了某个任务——可能是一个深度重构、跨文件修改、或者多步骤的代码生成——然后 agent 开始工作。终端里一行一行地输出文字，工具调用、代码生成、错误堆栈、重试逻辑……信息流高速滚动，你盯着屏幕，不知道进度如何、走到哪一步了、是否卡住了。

更让人头疼的是，当你同时运行多个 Agent 任务（主 Agent + 若干子 Agent），或者 Agent 自动生成了后台 Shell 任务时，你完全无法追踪这些任务之间的父子关系。哪个子 Agent 负责什么？后台任务完成了没有？以及最关键的问题：Agent 在生产环境中到底做了哪些操作？

这不是单纯的好奇心问题。当 AI Agent 的决策过程不可见时，代码审查、安全审计、问题排查都变得非常困难。你不知道 Agent 调用了哪些工具、写了哪些文件、是否做出了正确判断。

为什么这是问题：时间成本与安全风险

Agent 日志管理不善带来的后果很直接：

时间成本：开发者在切换 Agent 任务时需要逐行阅读终端输出，手动拼接不同会话的信息。如果 Agent 运行了一小时，光是理解它做了什么就要花 15 分钟。

安全风险：你无法确认 Agent 是否调用了未被授权的工具、是否访问了敏感文件、是否执行了破坏性操作。日志文件分散在 ~/.claude、~/.codex、临时目录等多个位置，手动审查几乎不可能。

调试困难：当 Agent 输出不符合预期时，你需要追溯它每一步的决策过程——但默认的日志格式是 JSONL 文件，结构化的数据不直观，可读性极差。

手动方案：JSONL 日志的痛苦阅读

Claude Code 和 Codex CLI 都会将会话日志保存到本地文件系统中：

Claude Code 日志：~/.claude/projects/**/*.jsonl
Codex CLI 日志：~/.codex/sessions/**/rollout-*.jsonl
后台 Shell 任务：claude-/**/tasks/*.output（通常在 /tmp 或 $TMPDIR）

手动查看这些文件的方式是直接用 cat 或 tail -f 读取 JSONL 文件：

tail -f ~/.claude/projects/$(ls -t ~/.claude/projects/ | head -1)/*.jsonl

cat ~/.codex/sessions/$(ls -t ~/.codex/sessions/ | head -1)/rollout-*.jsonl

但这只是原始的 JSON 行——{ "type": "tool_use", "tool": "Edit", "args": { "file_path": "..." } }——每一行都密密麻麻，人工阅读效率极低。你无法快速定位到关键操作，也无法看到 Agent 之间的调用关系。

工具方案：Agent Log Viewer 让日志变成聊天记录

Agent Log Viewer（npm 包名 agent-log-viewer，MIT 许可）是一个本地 Web UI 工具，它把 Claude Code 和 Codex CLI 的日志文件渲染成可读的聊天式信息流，让你像翻看聊天记录一样追溯 Agent 的每一次操作。

安装和使用只需一行命令：

bunx agent-log-viewer
npx agent-log-viewer

启动后浏览器自动打开 http://127.0.0.1:8898，你会看到一个聊天风格的界面：左侧是项目列表，右侧是会话详情，用户消息和 Agent 回复以聊天气泡展示，工具调用显示为可展开的卡片。

核心功能一：智能会话发现与父子关系树

Agent Log Viewer 会自动扫描本地所有 Agent 日志目录，发现每个会话、子 Agent、Codex 后台任务和 Shell 任务，并构建出一棵会话父子关系树：

主会话（Root Conversation）→ 子 Agent（Sub-agents）→ Codex 后台任务（Companion Jobs）→ Rollout 会话 → 后台 Shell 任务

项目层面，每个项目显示为一个可缩放、可拖拽的拓扑图——根会话在顶部，衍生出的 Agent 任务在下一层，不同的 AI 引擎用不同颜色区分。这解决了多 Agent 协作时「谁是谁的下级、谁干了什么」的追踪难题。

核心功能二：实时活动监控与工具调用可视化

Agent 正在运行时会通过内容检测自动显示「Working」状态，一旦消息完成就变为「Done」。每个工具调用以独立卡片展示，包含调用状态（✓ 成功 / ✗ 失败）和可展开的输出详情。整个界面就像聊天软件一样——左边是工具调用卡片，右边是执行状态，一眼就能看出 Agent 正在做什么、做完了什么。

这个界面的核心价值在于：你不需要在终端里逐行读 JSON 了。一眼扫过去就知道 Agent 调用了哪些工具、每个工具是否执行成功、输出是什么。

核心功能三：深度链接与跨会话跳转

每个会话都有唯一的深链接（http://127.0.0.1:8898#f=），任何时候打开该链接都能精确定位到那段日志。当你在 Codex 后台任务中发现了一个问题，点击就能跳转到该后台任务对应的完整 Rollout 会话中查看详细上下文。

核心功能四：Tailscale 远程访问与安全模型

Agent Log Viewer 内置 Tailscale 支持，可以安全地将日志查看器暴露到你的 Tailnet（虚拟专用网络）中：

bunx agent-log-viewer --tailscale

启动时会生成一个 32 字符的访问密钥，追加到 Tailnet URL 的 ?k=... 参数中。之后每次访问自动设置 30 天有效的 Cookie。--new-token 可以生成新密钥并立即作废所有旧 Cookie。

安全设计上，日志 API 拒绝任何未在白名单目录中的路径。默认绑定到 127.0.0.1，非回环地址强制开启 Token 认证。

核心功能五：可选的口述输入与语音控制

Composer 界面内置语音输入按钮，默认使用本地 faster-whisper 引擎进行离线转录——音频数据不会离开你的机器。也可以选择 ChatGPT 或 ElevenLabs Scribe 作为后端。

echo "elevenlabs" > ~/.config/agent-log-viewer/transcribe-backend
export ELEVENLABS_API_KEY=your_key_here
bunx agent-log-viewer

核心功能六：Review 循环——Implement → Review 自动化

Agent Log Viewer 还内置了一个「实施→审查」循环功能：一个长生命周期的实现 Agent 在 tmux 中运行，每轮使用新的只读审查 Agent 检查完整 diff，自动传递审查结论。从 Flow 按钮启动，支持预设引擎配对（如 “Codex high → Fable”）。

安装与环境配置

前置要求：Node.js ≥ 20.9，以及 bun 或 npm/pnpm。

Linux（原生支持）：进程发现直接读取 /proc，性能最佳。

macOS：通过 ps 和 lsof 的便携后端实现同样的功能——进程检测、tmux 合成器、Agent 生成/终止、后台任务发现全部可用，只是每次扫描有少量子进程开销。

Windows：目前不支持（npm 包的 os 字段会阻止 Windows 安装）。

可选依赖：tmux。没有 tmux 的情况下，日志查看、父子树、实时活动和深链接都正常；合成器、Agent 生成/终止、继续到面板等功能需要 tmux。

brew install tmux
sudo apt install tmux

实用技巧

保持日志持久化：不要手动删除 ~/.claude 和 ~/.codex 中的日志文件——Agent Log Viewer 的增量扫描是只读的，保留历史日志有助于后期审计。

自定义端口：如果需要同时运行多个日志查看器或端口冲突，使用 -p 指定端口：

“`bash

npx agent-log-viewer -p 9900

“`

与 Tailscale 配合使用：在团队环境中，--tailscale 模式比端口转发更安全——Tailnet 本身就是零信任网络，加上 ?k= Token 认证实现双重保护。

语音转录后端的切换：如果你不需要离线隐私，ChatGPT 后端的转录质量通常更好；如果追求低延迟，ElevenLabs Scribe 的流式转录是最佳选择。

预防策略：建立 Agent 日志审查习惯

使用 Agent Log Viewer 不仅仅是「看日志更方便」——它应该成为你的 AI 编码工作流的标配环节：

每次 Agent 完成复杂任务后：打开日志查看器，快速过一遍工具调用卡片，确认 Agent 没有执行意外操作
每次代码审查前：对照 Agent 日志中的文件修改记录和审查目标的代码变更，确保 Agent 的修改在预期范围内
安全审计时：利用父子关系树，追溯每个子 Agent 的文件访问行为

总结

Agent Log Viewer 解决了一个看似简单但实际非常痛苦的问题：AI 编码 Agent 运行的可见性。当 Agent 从单次对话扩展为多任务、多子 Agent、后台任务并行的复杂工作流时，没有可视化工具几乎不可能追踪发生了什么。

它把零散的 JSONL 日志变成了可读的聊天记录，把混乱的派生关系变成了清晰的父子树，把「终端里快速滚动的文字」变成了「可追溯、可搜索、可分享的操作记录」。如果你正在认真使用 Claude Code 或 Codex CLI，这可能是你工具箱里最被低估的实用工具之一。

项目地址：github.com/Latand/live-log-viewer-next
安装命令：npx agent-log-viewer 或 bunx agent-log-viewer
许可协议：MIT
前置要求：Node.js ≥ 20.9

AI AI 工具 AI 编程 Claude Code 开发工具开源教程