1. 命令行看长对话太累我给 Claude Code 套了个 Web GUIClaude Code 是 Anthropic 官方的命令行 AI 编程工具能直接读代码、改文件、跑命令能力确实强。但它只有 CLI 界面这件事用久了痛点很集中长对话要不停翻屏工具调用和正文混在一起分不清截图没法直接贴进去多会话切换得靠记 session id改错一行想回滚还得自己 git stash。我平时一边写代码一边和它聊终端窗口切来切去体验确实欠一点。所以我花了两天写了个开源的 Web GUI把 Claude Code 包了一层浏览器外壳。它支持多会话、图片上传、Token 级流式输出、Git Checkpoint 回滚、暗黑模式等 20 多个特性最关键的是零密钥配置——复用你本机 CLI 的登录态不碰任何 API Key。这篇文章会给出完整的本地启动步骤、环境变量与 endpoint 配置片段并演示把请求地址改到 TaoToken 后怎么验证会话连通和界面回显。适合已经在用 Claude Code、但想要一个顺眼可视化入口的开发者也适合想接第三方兼容 endpoint 做统一管理的团队。架构其实很简单浏览器 ←→ FastAPI 后端 ←→ subprocess 调用本地 claude CLI ←→ 上游 API。前端是原生 JS 零构建后端 Python 3.9 加 FastAPI数据全存本机 SQLite 和 jsonl不上传第三方。下面按“先跑通本地 GUI再改 endpoint 到 TaoToken最后排障”的顺序来。2. 前置准备Claude Code CLI 与 TaoToken 接入配置在装 Web GUI 之前先把底层 CLI 跑通否则 GUI 只是个空壳。前置条件两条本机已装 Claude Code CLI 并登录过Python 3.9 或更高版本。先装 CLInpm install -g anthropic-ai/claude-code claude首次运行claude会走一遍授权流程按提示完成即可。登录态默认存在~/.claude/目录下Web GUI 就是复用这里的凭证所以只要终端里claude能正常对话GUI 就能用。接下来是重点把 Claude Code 的请求地址改到 TaoToken。TaoToken 是一个兼容 Anthropic 接口协议的 API 网关官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的作用是让你用一个 Key 统一管理多家模型Claude Code 这类工具只要改 Base URL 就能接上。Claude Code 读取环境变量的方式有两种一是 shell 里 export二是写进 settings 文件。推荐后者持久且不污染全局。配置文件路径是~/.claude/settings.json内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } }三个字段缺一不可Base URL 指向 TaoToken 的 API 入口AUTH TOKEN 填你在控制台生成的 KeyModel ID 填你要用的模型标识。Key 的获取路径是登录 TaoToken 后进控制台在 API Keys 页面新建一个复制出来即可控制台地址 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。如果你更习惯用 shell 变量也可以这样临时覆盖export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4-5-20250929改完配置后先在终端验证 CLI 是否走通再装 GUI。这一步很关键因为 GUI 只是 subprocess 包装底层不通的话界面里只会一直转圈。验证命令claude -p 回复一句连通成功 --output-format stream-json --include-partial-messages如果看到 JSON 行里带content_block_delta事件和文本内容说明 endpoint 已经切到 TaoToken 并且鉴权通过。这一步过了再往下装 Web GUI 才有意义。3. 可复制配置启动 Web GUI 并指向 TaoToken endpoint底层通了现在装 GUI。方式有两种我推荐第一种——让 Claude Code 自己装最有意思。打开终端进claude交互模式把下面这段话丢给它帮我安装 https://github.com/heng1234/claude-web 到 ~/claude-web 目录 启动成功后告诉我访问地址它会自己 clone、装依赖、起服务。完成后浏览器打开http://127.0.0.1:8765即可。方式二是手动一条命令pip install claude-web-ui claude-web默认监听 8765 端口。常用启动参数claude-web --port 9000 # 自定义端口 claude-web --open # 启动后自动开浏览器 claude-web --host 0.0.0.0 # 局域网共享 claude-web --version # 查看版本注意--host 0.0.0.0会让同网段的人通过http://你的内网IP:8765访问当前版本没有鉴权别直接暴露到公网。关键点来了Web GUI 本身不直连 API它通过 subprocess 调用本地claude命令所以 endpoint 配置完全继承 CLI 的环境。也就是说你在第 2 步写进~/.claude/settings.json的 TaoToken 配置GUI 会自动复用不需要在界面里再填一遍 Key。这也是它“零密钥配置”的原因——GUI 不接触任何 API Key只负责把 CLI 的 stdin/stdout 包装成 SSE 流。如果你想让 GUI 用一套和 CLI 不同的 endpoint可以在启动前覆盖环境变量ANTHROPIC_BASE_URLhttps://taotoken.net/api \ ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 \ ANTHROPIC_MODELclaude-sonnet-4-5-20250929 \ claude-web --port 8765这样启动的进程会带着这组变量去调claude优先级高于 settings 文件。实测下来这种写法适合多项目并行、每个项目接不同 Key 的场景。启动后界面顶部有个“工作目录”输入框这是告诉 Claude 在哪个文件夹里干活。填上你的项目路径它就能直接读写该目录下的文件不填默认是用户主目录。建议第一次先填一个测试目录避免误操作。4. 验证请求会话连通与界面回显怎么确认服务起来后别急着上生产项目先做三步验证。第一步看后端日志。claude-web启动时终端会打印监听地址和 subprocess 调用日志。发一条消息后日志里应该出现类似claude -p --output-format stream-json --include-partial-messages的调用记录。如果这行没出现说明前端请求没到后端检查端口和防火墙。第二步看界面回显。在输入框敲一句“你好报一下当前工作目录”发送。正常情况下你会看到文字一个字一个字打出来这是 Token 级流式靠解析content_block_delta事件实现。如果整段一次性蹦出来说明流式没生效多半是--include-partial-messages没传进去。第三步验证 endpoint 真的走了 TaoToken。最直接的办法是看用量。登录 TaoToken 控制台在用量或日志页面刷新应该能看到刚才那次请求的记录包含模型 ID 和 token 消耗。如果控制台没记录但界面有回复说明请求走了别的 endpoint回去检查ANTHROPIC_BASE_URL有没有被其他配置覆盖。再补一个工具调用的验证在输入框敲会弹出当前工作目录的文件选择器选一个文件插入路径然后让它“读一下这个文件并总结”。如果界面里出现工具调用图标、并且能展开看到 Read 工具的参数和返回说明 subprocess 的 stdin/stdout 通道完全打通。这一步过了图片上传、Git Checkpoint 这些功能基本都不会有问题。图片上传有三种方式点输入框左边回形针按钮选文件、直接 CtrlV 粘贴截图、拖拽图片到输入框。发送后 Claude 会用 Read 工具读取图片内容。验证时贴一张带文字的截图问它“图里写了什么”能答对就说明多模态链路正常。5. 常见报错排查401、local proxy failed 与 reading choices接入过程里最容易撞的几个错我按真实报错整理一下。401 Unauthorized。界面里回复变成一段错误提示后端日志显示 401。原因通常是ANTHROPIC_AUTH_TOKEN没填、填错或者 Key 被禁用。排查顺序先在终端跑echo $ANTHROPIC_AUTH_TOKEN确认变量存在再确认~/.claude/settings.json里的 Key 没有多余空格或换行最后去 TaoToken 控制台看这个 Key 是否还在启用状态。注意 Base URL 结尾不要多加/v1TaoToken 的入口就是https://taotoken.net/api多写路径会导致 404 而不是 401别混淆。local proxy failed / connection refused。这个错一般出现在 GUI 启动后第一次发消息。原因是 subprocess 调claude时CLI 自己也在读环境变量如果 shell 里 export 的变量和 settings 文件冲突CLI 可能连到一个不存在的本地地址。解决办法是统一配置来源要么全用 settings 文件要么全用启动时注入的环境变量别两边都写。排查命令env | grep ANTHROPIC cat ~/.claude/settings.json两处对比确保ANTHROPIC_BASE_URL只有一个值。Error reading choices / unexpected token。这个错通常出现在流式解析阶段界面卡住或报 JSON 解析失败。原因是上游返回的不是标准 SSE 格式可能是网关返回了 HTML 错误页也可能是模型 ID 写错导致返回了非预期结构。先确认ANTHROPIC_MODEL是 TaoToken 支持的模型标识去模型列表页核对再用 curl 直接打一次接口看原始返回curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-5-20250929,max_tokens:64,messages:[{role:user,content:hi}]}如果 curl 返回正常 JSON但 GUI 报 reading choices那就是 GUI 版本和 CLI 输出格式不匹配升级claude-web-ui和anthropic-ai/claude-code到最新版即可。OAuth 相关报错。如果你之前用账号登录过 CLI~/.claude/里会存 OAuth 凭证。切到 TaoToken 的 Key 模式后两者可能打架。干净的做法是先把 OAuth 登录态清掉或换一个配置目录再写 settings 文件。启动时可以用CLAUDE_CONFIG_DIR指定独立目录避免污染原有登录CLAUDE_CONFIG_DIR~/.claude-taotoken claude首次会重新走一遍配置读取把 TaoToken 的 settings 放进这个目录即可。界面一直转圈没有输出。先看后端日志有没有 subprocess 调用记录。有记录但无输出多半是 CLI 卡在权限确认把界面顶部权限策略切到“计划”或“只读”试试。无记录则是前端没连上后端检查claude-web是否真的在监听你访问的端口。6. 把 endpoint 固定下来长期用 TaoToken 跑 Claude Code 的建议跑通之后建议把配置固化别每次靠 export。~/.claude/settings.json是 Claude Code 官方支持的持久配置写进去之后 CLI 和 Web GUI 都会读。如果你有多个项目要用不同模型可以用CLAUDE_CONFIG_DIR给每个项目一套独立配置启动 GUI 时带上对应目录即可。模型切换在界面顶部下拉菜单里Opus、Sonnet、Haiku 都能选底层就是改ANTHROPIC_MODEL。如果你在 TaoToken 上开了多个模型权限这里切换会直接反映到用量统计里。长期编码或跑 Agent 任务的话可以了解下 Coding Plan地址 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合高频调用场景做成本控制。Git Checkpoint 是个容易被忽略但很救命的功能。只要工作目录是 git 仓库每轮对话前会自动基于git stash create建检查点。Claude 把代码改坏了点那一轮用户消息左边的回滚按钮文件恢复到对话前状态对话历史不受影响可以继续聊。我试过在重构时让它连续改十几个文件中途发现方向不对一键回滚比手动 git 快得多。最后提醒两点一是--host 0.0.0.0共享给同事时当前版本没有鉴权只在内网用二是所有会话数据存在本机claude-web.db和history/目录换机器不会同步重要会话记得导出 Markdown。配置片段和启动命令都在上面复制改一下 Key 就能跑。
