1. 为什么 Claude Code 需要一根“探针”Claude Code 在终端里跑起来很爽但它的执行过程基本是个黑盒。你敲一句“帮我把这个模块重构一下”它可能连续调用十几次工具、读写七八个文件、跑几轮 LLM 推理最后给你一个结果。中间发生了什么、哪一步慢、Token 花在哪、有没有执行危险命令你几乎看不到。这就是 cc-langfuse 要解决的问题。它是一个轻量级探针Probe挂在 Claude Code 的 Stop 事件钩子上每次会话结束时自动把会话数据推送到 Langfuse 可观测平台。你能在 Langfuse 里看到完整的调用链每次 LLM 调用的输入输出、Thinking 过程、工具调用参数与结果、Token 用量、真实起止时间、Git 分支、用户标识等。适合谁用三类人最需要一是本地开发调试时想搞清楚 Agent 到底走了哪条路径的开发者二是团队里要监控 Token 成本和工具调用异常的技术负责人三是需要做操作审计、追溯“谁在哪台机器上执行了什么命令”的合规场景。这篇不讲空泛概念直接给你可复制的settings.json和config.toml骨架演示通过 TaoToken 统一 Key/API 通道完成探针初始化并跑一次链路验证帮你定位调用延迟和异常。2. 前置准备TaoToken 通道与 Langfuse 凭据cc-langfuse 本身只负责采集和上送它不关心你的 Claude Code 走哪个 API 通道。但为了让探针采集到的数据能对应上真实的模型调用建议先把 Claude Code 的 API 通道统一到 TaoToken这样 Key 管理、用量统计、模型切换都在一个地方排查问题时不会因为多套凭据互相干扰。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM 参数直接用于配置。你需要先在控制台创建一个 API Key然后把它写进 Claude Code 的环境变量或配置文件。Langfuse 这边你需要两样东西LANGFUSE_PUBLIC_KEY和LANGFUSE_SECRET_KEY以及你的 Langfuse 服务地址自托管或云版都行。cc-langfuse 通过 REST API 直接推送 Ingestion 事件不依赖 Langfuse SDK所以只要这三个值对探针就能工作。注意cc-langfuse 采集的数据是原样上送的工具输入输出截断到 20000 字符超长部分保留 SHA256 摘要。如果你处理的是敏感代码库建议先确认 Langfuse 的部署位置和数据保留策略。安装探针本身只有两条命令npm i -g cc-langfuse cc-langfuse install安装器会自动往 Claude Code 的settings.json里写入 Stop 钩子不需要你手动改 Hook。装完后用cc-langfuse status可以查看安装状态。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层一层是settings.json管 Hook 和权限另一层是config.toml管模型通道和 API 凭据。cc-langfuse 安装时会自动改settings.json但如果你要手动核对或迁移环境下面这份骨架可以直接抄。先看settings.json里探针相关的部分。关键是在hooks.Stop里注册 cc-langfuse 的命令让每次会话结束时触发采集{ hooks: { Stop: [ { matcher: , hooks: [ { type: command, command: cc-langfuse probe } ] } ] } }如果你之前已经有其他 Stop 钩子不要覆盖把 cc-langfuse 这条追加到数组里就行。matcher留空表示匹配所有会话。再看config.toml这里配置 Claude Code 走 TaoToken 通道同时把 Langfuse 的凭据通过环境变量传给探针# Claude Code 模型通道配置 [api] base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 [model] default claude-sonnet-4-20250514 # 探针环境变量供 cc-langfuse 读取 [env] LANGFUSE_HOST https://你的langfuse地址 LANGFUSE_PUBLIC_KEY pk-lf-你的公钥 LANGFUSE_SECRET_KEY sk-lf-你的私钥 CC_LANGFUSE_USER 你的用户标识CC_LANGFUSE_USER是可选的不填的话探针默认用系统账号名做 userId。如果你在团队里想按真实姓名或工号聚合就显式设置这个变量。探针还会自动采集git_branch、cwd、computer机器名等字段写入每条 Trace 的 metadata。配置改完后重启一次 Claude Code 让 Hook 生效。你可以用cc-langfuse status确认探针已注册输出里应该能看到 Stop 钩子的路径和当前版本号。4. 验证请求跑一次链路看数据是否上送配置写完不算完得实际跑一次会话确认数据真的进了 Langfuse。验证步骤分三步触发会话、检查本地日志、在 Langfuse 里查 Trace。第一步在终端里启动 Claude Code随便让它做一件小事比如“读一下当前目录的 package.json 并告诉我 name 字段”。等它执行完退出Stop 钩子会被触发探针开始增量读取当前会话的 Transcript JSONL 文件。第二步检查探针日志。cc-langfuse 是 Fail-Open 设计上送失败不报错只记日志。日志通常在~/.cc-langfuse/logs/下你可以 tail 一下看有没有ingestion success或错误堆栈tail -f ~/.cc-langfuse/logs/probe.log如果看到offset updated和events pushed之类的字样说明采集和上送都正常。如果看到http 401或http 403多半是 Langfuse 的 Key 配错了如果看到ECONNREFUSED检查LANGFUSE_HOST地址是否可达。第三步打开 Langfuse 的 Tracing 视图。你应该能看到一条新的 Trace名称类似UserTask 1。点进去看调用链树顶层是 Trace下面挂着 GenerationLLM 调用、Thinking思考过程、Tool工具调用等子节点。右侧面板会显示 Token 用量、延迟、Session ID、User ID。重点核对几个字段usageDetails里的 input/output/cache_read 是否符合预期tool_duration_ms是否记录了工具纯执行耗时git_branch是否是你当前分支。如果这些都对说明探针链路完全打通。提示探针按message.id归并同一次 LLM 调用的多条 Assistant 消息thinking / text / tool_use所以 Token 不会重复计算。如果你在 Langfuse 里看到 Token 数偏高先检查是不是同一 message.id 被拆成了多条 Generation。5. 本篇常见错排查实际配下来最容易踩的坑集中在四个地方。Hook 没触发。症状是 Claude Code 正常用但 Langfuse 里一条数据都没有。先确认settings.json里hooks.Stop的路径对不对cc-langfuse 安装器写入的 command 通常是绝对路径。如果你手动改过配置可能把这条覆盖掉了。用cc-langfuse status看探针是否认为自己已安装。Langfuse 返回 401/403。这是 Key 或 Host 配错。注意LANGFUSE_HOST不要带尾部斜杠LANGFUSE_PUBLIC_KEY和LANGFUSE_SECRET_KEY不要搞反。如果你用的是自托管 Langfuse确认 Ingestion API 的路径是/api/public/ingestion探针会自己拼这个路径。Token 数对不上。前面说过探针按message.id归并。如果 Claude Code 版本更新后 Transcript 格式变了归并逻辑可能失效导致同一次调用被拆成多条。这时候升级 cc-langfuse 到最新版通常能解决。另外缓存读取量cache_read和缓存写入量cache_write是分开统计的别把它们加进 input 里算。延迟数据看起来不对。探针从 Transcript 里读每条消息的真实时间戳还原 LLM 调用的起止时间而不是用请求发起时间。如果你发现某个 Generation 的延迟特别长先看它下面挂的 Tool 节点tool_duration_ms能告诉你是不是某个工具执行慢。Dashboards 视图里的 p50/p90/p95/p99 分位数就是基于这些时间戳算的。还有一个隐蔽的坑如果你在config.toml的[env]里配了 Langfuse 凭据但 Claude Code 启动时没有把这些环境变量传给子进程探针就读不到。确认你的 Claude Code 版本支持从 config.toml 注入 env或者干脆在 shell 的.zshrc/.bashrc里 export 这些变量。6. 把探针接进你的日常调试流配好之后cc-langfuse 的价值在日常调试里才真正体现。我自己的习惯是每次让 Claude Code 做一个稍复杂的重构或排查任务后顺手打开 Langfuse 看一眼那条 Trace。重点看三样东西——工具调用链有没有异常步骤、Token 消耗有没有突然飙升、哪一步的延迟是瓶颈。如果你要长期跑编码任务或 Agent 工作流建议把 TaoToken 的 Coding Plan 用起来配合探针的用量看板能按天、按分支、按用户维度看 Token 趋势。接入文档和 API Keys 都在控制台里模型对话入口可以用来快速验证通道是否正常。探针的配置骨架你已经有了剩下的就是跑起来、看数据、调参数。真正定位到一次异常调用链的时候你会觉得这根“可观测之翼”插得值。