1. 为什么需要 Web 端 Claude Code 会话管理面板Claude Code 用久了会话文件会堆成一座小山。每个项目目录下~/.claude/projects/project/session-id.jsonl一个文件几十上百个会话散落在不同项目里想回头找「上周那次重构为什么改了鉴权逻辑」基本靠记忆翻终端历史。终端里claude --resume只能按时间倒序列出当前项目的会话跨项目检索、全文搜索、看某次会话里到底调了哪些工具、改了哪些文件原生能力都比较基础。Claude Code Viewer 就是冲着这个场景来的它是一个开源的 Web 端 Claude Code 客户端直接读取 Claude Code 的标准日志格式把会话列表、详情、工具调用、Git diff、待办项都搬到浏览器里。你可以在一个页面里切换多个项目的会话用CtrlK做跨会话全文检索在移动端也能看开发进度。它不替代 Claude Code 本身而是给会话数据加了一层可视化管理面板。不过这里有个现实问题Claude Code Viewer 启动新会话、继续会话时底层还是要调用 Claude Code 的模型接口。如果你本地有多个项目、多个 Key 散落在不同环境变量里管理起来很乱。我实测下来比较顺的做法是用 TaoToken 统一一个 Key通过环境变量注入给 Claude Code这样 Viewer 里发起的每个会话都走同一个入口不用在每个项目里重复配 Key。这篇就按「先搭 Viewer再接 TaoToken 统一 Key最后验证会话列表和详情」的顺序走一遍命令和配置都能直接复制。适合谁看已经在用 Claude Code、本地会话文件攒了一堆、想有个 Web 面板统一看会话的开发者或者团队里想共享会话内容、做代码审查的人。前置要求是 Node.js 20.19.0、macOS 或 LinuxWindows 原生不支持可以用 WSLClaude Code v1.0.50。2. TaoToken 统一 Key 的前置准备与 Claude Code 接入在搭 Viewer 之前先把 Key 这条链路理顺。Claude Code 读取模型配置主要靠环境变量常见的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY。TaoToken 提供兼容的 API 入口你只需要一个 Key就能在多个项目、多个工具之间复用。第一步去 TaoToken 控制台创建一个 API Key。打开 https://taotoken.net/api 对应的控制台入口在 API Keys 页面新建一个 Key复制出来。这个 Key 后面会同时给 Claude Code 和 Viewer 用所以别弄丢。第二步确认你要用的模型 ID。TaoToken 的模型对话页面能看到当前可用的模型列表选一个你常用的编码模型把 Model ID 记下来。Claude Code 里通常通过ANTHROPIC_MODEL指定或者用默认模型。第三步把环境变量写进 shell 配置。我习惯放在~/.zshrc或~/.bashrc里这样每个终端会话都能读到# TaoToken 统一 Key 接入 Claude Code export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 export ANTHROPIC_MODEL你的模型ID改完执行source ~/.zshrc让配置生效。这里有个坑要注意ANTHROPIC_BASE_URL不要带末尾斜杠也不要带/v1之类的路径Claude Code 会自己拼接。如果你之前配过别的中转地址先把旧的ANTHROPIC_BASE_URL清掉避免两个变量打架。第四步验证 Claude Code 本身能通。在终端里跑一个最简单的请求claude -p 回复 ok 两个字如果返回ok说明 Key 和 Base URL 都对了。如果报 401多半是 Key 复制错了或者环境变量没生效用echo $ANTHROPIC_AUTH_TOKEN确认一下。这一步很关键因为 Viewer 只是壳底层还是 Claude Code 在发请求Claude Code 不通Viewer 里发起的新会话也会失败。对于用 Claude Code 的 coding-plan 场景TaoToken 的 Coding Plan 入口可以看套餐和额度长期编码的话比按量更划算。但不管用哪种Key 都是同一个配一次就行。这里再强调一下三件套的对应关系后面配 Viewer 时会反复用到Base URL 是https://taotoken.net/apiKey 是你在控制台创建的那串sk-开头的字符串Model ID 是模型列表里选的那个。三者缺一不可尤其是 Model ID写错了会报模型不存在。3. 可复制的 Claude Code Viewer 本地启动配置Key 通了之后开始搭 Viewer。最省事的方式是npx直接跑不用装npx kimuson/claude-code-viewerlatest --port 3400启动后访问http://localhost:3400就能看到界面。但这样每次都要敲一长串而且密码、端口这些参数不好管理。我更推荐写一个本地配置文件把启动参数固化下来。Viewer 支持命令行参数也支持环境变量。常用的几个--port端口--hostname主机名--password认证密码--claude-dir指定 Claude 目录。如果你想让 Viewer 读取的 Claude 配置和终端里一致--claude-dir指向你的~/.claude就行。下面是一个可以直接复制的启动脚本保存为start-viewer.sh#!/usr/bin/env bash # Claude Code Viewer 本地启动脚本 export CCV_PASSWORDyour-viewer-password export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 export ANTHROPIC_MODEL你的模型ID npx kimuson/claude-code-viewerlatest \ --port 3400 \ --hostname 127.0.0.1 \ --claude-dir $HOME/.claude给它执行权限chmod x start-viewer.sh然后./start-viewer.sh启动。注意CCV_PASSWORD是 Viewer 自己的登录密码和 TaoToken 的 Key 是两回事别混。Viewer 的密码是保护你这个 Web 面板不被别人访问TaoToken 的 Key 是给底层模型调用用的。如果你偏好 Docker也可以写一个docker-compose.yml。关键是把本地的~/.claude挂进去否则容器里看不到你的会话文件services: viewer: image: node:20 working_dir: /app command: npx kimuson/claude-code-viewerlatest --port 3400 --hostname 0.0.0.0 ports: - 3400:3400 environment: - CCV_PASSWORDyour-viewer-password - ANTHROPIC_BASE_URLhttps://taotoken.net/api - ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 - ANTHROPIC_MODEL你的模型ID volumes: - /path/to/your/claude_home:/root/.claude把/path/to/your/claude_home换成你本机~/.claude的真实路径然后docker compose up。这里有个容易踩的坑默认的 compose 文件如果不挂载claude_homeViewer 启动后会话列表是空的因为它读不到宿主机的会话文件。挂载之后容器里的/root/.claude就对应你本地的会话目录。启动成功后终端会打印监听地址。打开浏览器访问http://localhost:3400输入你设的CCV_PASSWORD登录。如果页面打不开先检查端口有没有被占用lsof -i :3400看一下。4. 验证会话列表加载与详情查看登录进去后第一件事是确认会话列表能正常加载。左侧边栏会按项目分组列出所有会话每个会话显示 session-id、最后活动时间、消息数量。如果你之前用 Claude Code 跑过不少会话这里应该能看到一长串。如果列表是空的先别急着怀疑 Viewer 坏了。按这个顺序排查第一确认--claude-dir指向的目录下有projects子目录ls ~/.claude/projects看看有没有内容第二确认会话文件是.jsonl格式Viewer 只认这个格式第三如果是 Docker 部署确认 volume 挂载路径没写错进容器docker exec -it container ls /root/.claude/projects看一眼。列表加载出来后点任意一个会话进入详情页。详情页会展示完整的对话流用户消息、助手回复、工具调用、文件编辑。这里能看到每次Edit、Write、Bash调用的具体参数和结果比终端里翻历史清楚得多。右侧还有文件与工具检查器汇总这次会话里改过的文件按项目分组。验证详情查看是否正常重点看两个地方一是工具调用卡片能不能展开展开后参数和返回值是否完整二是 Git diff 能不能渲染。如果某个会话里 Claude Code 执行过git commit详情页的 Git 面板应该能看到对应的 diff。如果 diff 是空的可能是会话文件里没有记录 Git 操作或者 Viewer 版本较旧升级到最新版试试。跨会话搜索是 Viewer 的亮点。按CtrlKmacOS 是⌘K唤起搜索框输入关键词比如某个函数名或报错信息它会跨所有会话做全文检索。搜索结果会高亮匹配片段回车跳转到对应会话。这个功能在排查「这个改动是哪次会话做的」时特别有用。再验证一下发起新会话。在 Viewer 里点「新建会话」选一个项目目录它会调用底层 Claude Code 启动会话。这时候如果 TaoToken 的 Key 配对了新会话能正常收发消息如果 Key 有问题这里会报错。你可以发一句「列出当前目录的文件」看它能不能正常调用工具并返回结果。这一步通了说明 Viewer TaoToken 整条链路都打通了。5. 本篇常见报错排查实际搭的过程中报错基本集中在几个地方。下面按真实遇到的错误对照排查。401 Unauthorized / authentication_error这是最常见的。原因通常是ANTHROPIC_AUTH_TOKEN没生效或 Key 错了。先在终端echo $ANTHROPIC_AUTH_TOKEN确认变量有值再确认 Key 没有多余空格。如果是在 Viewer 里发起新会话报 401检查启动脚本里有没有 export 这个变量——npx启动的进程要能继承到环境变量如果你是在另一个终端窗口启动的 Viewer那个窗口也得 source 过配置。local proxy failed / connection refused这个报错说明 Claude Code 连不上ANTHROPIC_BASE_URL。检查地址是不是写成了https://taotoken.net/api/多了斜杠或者https://taotoken.net/api/v1多了路径。正确写法就是https://taotoken.net/api。另外确认本机网络能访问这个域名curl -I https://taotoken.net/api看返回。reading choices of undefined这个错误通常出现在响应格式不符合预期时。如果你用的 Model ID 写错了或者 Base URL 指向了一个不兼容的端点返回的 JSON 结构里没有choices字段解析就会崩。回到 TaoToken 的模型对话页面确认 Model ID 拼写正确然后重新 export 再启动。OAuth / login requiredClaude Code 某些版本会尝试走 OAuth 登录流程。如果你已经用ANTHROPIC_AUTH_TOKEN配了 Key还弹 OAuth说明环境变量没被识别。检查是不是同时存在ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN两个都设可能冲突留一个就行。另外确认 Claude Code 版本在 v1.0.50 以上。会话列表为空前面提过重点查--claude-dir和 Docker volume。还有一个隐蔽原因Viewer 进程的用户权限和~/.claude目录的属主不一致导致读不了文件。用ls -la ~/.claude/projects看权限必要时chmod -R 755 ~/.claude。端口被占用Error: listen EADDRINUSE :::3400。换个端口--port 3401或者lsof -i :3400找到占用进程 kill 掉。排查时有个通用思路先在终端直接跑claude -p test确认 Claude Code 本身通再启动 Viewer确认 Web 界面能开最后在 Viewer 里发新会话。分层定位哪一层报错就查哪一层比一上来就怀疑 Viewer 代码有效得多。6. 把会话面板用起来统一 Key 后的日常姿势链路打通之后日常用起来其实很顺。我现在的习惯是所有项目的 Claude Code 都走同一个 TaoToken KeyViewer 常驻在localhost:3400需要回看某次会话就CtrlK搜关键词需要审查代码就打开 Git 面板看 diff。移动端也能访问出门在外用手机看开发进度没问题。如果你要长期跑编码任务TaoToken 的 Coding Plan 可以看下额度方案配合 Viewer 的定时发送功能能让 Claude Code 在指定时间自动继续任务。定时发送支持 cron 表达式也支持一次性任务检测到限流还会自动安排 continue 消息这个在跑长任务时挺省心。最后留一个实用技巧Viewer 的会话文件是只读展示不会修改你的.jsonl所以放心用。但如果你手动删过~/.claude/projects下的文件Viewer 刷新后列表会同步变化。想备份会话的话直接打包~/.claude/projects目录就行换机器时解压回去Viewer 立刻能读到全部历史。