会话列表空白先别怀疑 ViewerClaude Code Viewer 的会话列表读的是~/.claude/projects/project/session-id.jsonl。列表空白通常不是 Viewer 的解析逻辑坏了而是这些 JSONL 压根没被写出来或者写到了另一个项目目录下。而 JSONL 没写出来的一个高频原因是 Claude Code 侧的 Base URL 或 Key 没配对——请求根本没成功自然没有会话落盘。这篇从排障视角走一遍先确认 Claude Code 本身能正常跑通再让 Viewer 去读日志。TaoToken 在这里的角色很明确只负责供给 Key 和 API 通道不替代 Viewer 的日志解析也不接管它的会话恢复逻辑。需要先拿 Key 的话从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 进控制台创建即可。一、原问题与场景Viewer 有界面但列表是空的Claude Code Viewer 的定位是本地自托管 Web 客户端直接读 Claude Code 在本地生成的 JSONL 会话文件然后做可视化、会话恢复、Git Diff 查看这些事。它的数据来源是文件系统不是自己的数据库。所以当你在浏览器里打开 Viewer左侧会话列表一片空白时本质上是「它去读了但没读到东西」。常见成因可以归成三类第一类Claude Code 从未成功执行过对话。请求在鉴权或网络层就失败了~/.claude/projects/下没有新的 JSONL 生成Viewer 自然无内容可列。第二类Base URL 或 Key 配错。比如把 Anthropic 官方地址和第三方通道混用、Key 复制时带了空格、环境变量写在了错误的 shell 配置文件里。这类问题的表现很典型Claude Code 命令行里报 401 或连接超时但很多人只盯着 Viewer 界面看忽略了终端里的报错。第三类项目路径不匹配。JSONL 是按项目目录归档的如果你在 A 目录跑 Claude Code却在 Viewer 里期望看到 B 项目的会话那列表当然是空的。Viewer 读的是它启动时对应的工作目录下的项目记录。排障顺序建议是先在终端确认 Claude Code 能正常对话并落盘再回到 Viewer 刷新。顺序反了就会一直在前端找后端的问题。二、TaoToken 前置Key 与 Base URL 怎么准备TaoToken 提供的是 API 通道和 KeyClaude Code 通过它来发请求。你需要准备两样东西一个可用的 Key以及正确的 Base URL。Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude-code-viewer。创建后复制完整字符串注意不要带首尾空格。本文示例统一用YOUR_API_KEY占位实际使用时替换成你自己的。Base URL 填https://taotoken.net/api。这个地址不加任何 UTM 参数直接作为 Anthropic 兼容端点使用。Claude Code 走的是 Anthropic 协议所以配置项是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这一组而不是 OpenAI 那套。如果你还想确认通道本身是否可用可以先用模型对话页面发一条测试消息地址是 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude-code-viewer。这一步能把「Key 无效」和「Claude Code 配置错」两类问题分开。三、可复制配置Claude Code 的 settings.jsonClaude Code 的配置走settings.json环境变量走ANTHROPIC_*系列。下面给出可直接复制的写法。方式一写进 settings.json。文件通常位于~/.claude/settings.json内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: YOUR_API_KEY } }方式二用环境变量。在~/.zshrc或~/.bashrc里追加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYYOUR_API_KEY改完执行source ~/.zshrc让配置生效。两种方式选一种即可不要同时写否则容易出现「以为改了 A实际生效的是 B」的排查干扰。配置完成后重启 Claude Code。注意是重启进程不是只重开一个终端窗口——环境变量在进程启动时读取旧进程不会自动感知新配置。如果你用的是 CLI 形态的接入命令是npm i -g taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m MODEL_ID其中MODEL_ID换成你要用的模型标识。这条命令适合想快速验证通道、不想手动改配置文件的场景。四、验证请求与成功结果配置改完先别急着开 Viewer。在终端里跑一次 Claude Code发一条最简单的消息比如让它读一下当前目录。观察两件事一是终端有没有报错。如果出现 401、403 或连接超时说明 Key 或 Base URL 还有问题回到上一节检查。特别注意 Key 是否复制完整、Base URL 结尾有没有多余的斜杠。二是~/.claude/projects/下有没有新的 JSONL 生成。可以这样看ls -lt ~/.claude/projects/按时间排序最新的目录就是刚才这次会话对应的项目。进去应该能看到session-id.jsonl文件且文件大小不为零。这一步是关键的「落盘确认」——只要 JSONL 写出来了Viewer 就有东西可读。确认落盘后再启动或刷新 Claude Code Viewer。它的启动方式还是老样子PORT3400 npx kimuson/claude-code-viewerlatest访问http://localhost:3400/左侧列表此时应该能看到刚才那次会话。如果终端里 Claude Code 正常、JSONL 也生成了但 Viewer 还是空白那问题就转移到 Viewer 侧了重点查它启动时的工作目录是否和 JSONL 所在项目一致。成功的结果是终端对话正常、JSONL 文件存在且有内容、Viewer 列表出现对应会话、点进去能看到完整历史并能继续交互。四个条件同时满足才算这条链路真正打通。五、本篇常见错排查错误一Key 带了空格或换行。从网页复制时容易带上尾部空白表现为 401。解决方法是重新复制或在配置里确认字符串首尾无空白。错误二Base URL 写成了官网首页。https://taotoken.net和https://taotoken.net/api是两个不同的东西前者是站点首页后者才是 API 端点。填错会直接连不上。错误三改了配置但没重启 Claude Code。环境变量在进程启动时读取改完必须重启进程。只重开终端窗口不够。错误四Viewer 工作目录不对。Viewer 读的是它启动时对应目录下的项目记录。如果你在别的目录启动它列表可能读不到目标项目的 JSONL。解决方法是切到正确目录再启动或确认 Viewer 的项目选择逻辑。错误五把 Viewer 当成 Key 配置工具。Viewer 只负责读日志和展示它不参与 Claude Code 的鉴权配置。Key 和 Base URL 要在 Claude Code 侧配好Viewer 才有数据可读。这个边界要分清。错误六JSONL 存在但 Viewer 版本不兼容。Viewer 对 Claude Code 版本有要求工具权限等功能需要较新版本。如果列表能显示但某些功能异常检查版本兼容性。排查时建议按「终端 → 文件系统 → Viewer」的顺序逐层确认不要跳步。每一层都有明确的成功标志定位起来会快很多。六、把链路固定下来这条链路的本质是Claude Code 负责发请求和写 JSONLTaoToken 负责供给 Key 和 API 通道Viewer 负责读 JSONL 并可视化。三者职责清晰排障时也应按这个边界去定位而不是混在一起猜。如果你还在接入阶段需要 Key 和接入文档可以从 API Keys 页面创建 Key再对照接入文档确认ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY的写法https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude-code-viewer 和 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude-code-viewer。如果你只是想把通道本身验证一遍用模型对话页面发一条消息最快https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude-code-viewer。如果你打算长期用 Claude Code 做编码和 Agent 任务频繁跑会话、需要稳定的通道供给可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude-code-viewer。会话列表空白这件事多数时候不是 Viewer 的问题而是上游没落盘。把 Claude Code 的 Base URL 和 Key 配对让 JSONL 正常生成Viewer 刷新后自然就有内容了。