Claude Code Viewer 会话列表空白？让走 TaoToken 的 Claude Code 查 Base URL-育师

会话列表空白，先别怀疑 Viewer

Claude 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_source=taotoken_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 通道和 Key，Claude Code 通过它来发请求。你需要准备两样东西：一个可用的 Key，以及正确的 Base URL。

Key 在控制台的 API Keys 页面创建，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude-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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude-code-viewer。这一步能把「Key 无效」和「Claude Code 配置错」两类问题分开。

三、可复制配置：Claude Code 的 settings.json

Claude 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_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="YOUR_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。它的启动方式还是老样子：

PORT=3400 npx @kimuson/claude-code-viewer@latest

访问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 负责发请求和写 JSONL，TaoToken 负责供给 Key 和 API 通道，Viewer 负责读 JSONL 并可视化。三者职责清晰，排障时也应按这个边界去定位，而不是混在一起猜。

如果你还在接入阶段，需要 Key 和接入文档，可以从 API Keys 页面创建 Key，再对照接入文档确认ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY的写法：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude-code-viewer 和 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude-code-viewer。

如果你只是想把通道本身验证一遍，用模型对话页面发一条消息最快：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude-code-viewer。

如果你打算长期用 Claude Code 做编码和 Agent 任务，频繁跑会话、需要稳定的通道供给，可以看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude-code-viewer。

会话列表空白这件事，多数时候不是 Viewer 的问题，而是上游没落盘。把 Claude Code 的 Base URL 和 Key 配对，让 JSONL 正常生成，Viewer 刷新后自然就有内容了。