追踪 Claude Code 应用

本指南展示如何把对话从 Claude Code CLI 自动发送到 LangSmith。

一旦配置好，每个 Claude Code 项目都可选择将追踪发送到 LangSmith。每条追踪包含用户消息、工具调用、压缩、子 agent 运行和助手响应。系统提示不包含在内，因为 Claude Code 不会在对话转录中返回它们。

前置条件

在设置追踪之前，请确保你具备：

Claude Code CLI 已安装。
一个 LangSmith API 密钥。
Node.js 已安装。

入门

在 Claude Code 内，运行：

bash

/plugin marketplace add langchain-ai/langsmith-claude-code-plugins
/plugin install langsmith-tracing@langsmith-claude-code-plugins
/reload-plugins

要更新该插件，从 Claude Code 内刷新市场：

bash

/plugin marketplace update langsmith-claude-code-plugins

然后从你的 shell 把安装移到新版本，并重启 Claude Code：

bash

claude plugin update langsmith-tracing@langsmith-claude-code-plugins

NOTE

市场更新本身只刷新目录克隆。你的安装仍固定到它被安装自的版本目录，因此钩子会一直运行旧的 bundle，直到 claude plugin update 把它移动。要下次跳过这两步，运行 /plugin，打开 Marketplaces → langsmith-claude-code-plugins 并选择 Enable auto-update：第三方市场默认关闭它，启用后会一起更新市场及其已安装的插件。

NOTE

如果你从之前推荐的手动创建 stop 钩子追踪 Claude Code 的版本迁移，参阅从手动 stop 钩子迁移。

设置环境变量

选项 1：项目级配置（推荐）

该插件需要以下环境变量：

TRACE_TO_LANGSMITH: "true"：为此项目启用追踪。移除或设为 false 以禁用追踪。
CC_LANGSMITH_API_KEY：你的 LangSmith API 密钥。
CC_LANGSMITH_PROJECT：你的追踪将发送到的 LangSmith 项目名。
（可选）CC_LANGSMITH_METADATA：一个 JSON 对象，含要附加到所有运行的自定义元数据（例如 PR URL、作者）。
（可选）CC_LANGSMITH_DEBUG: "true"：启用详细调试日志。移除或设为 false 以禁用调试日志。

要完成设置，创建或编辑 Claude Code 的项目设置文件。在你的项目目录创建一个 .claude/settings.local.json 并按如下填充：

json

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_API_KEY": "<LangSmith API key>",
    "CC_LANGSMITH_PROJECT": "my-project"
  }
}

NOTE

或者，要为所有 Claude Code 会话启用向 LangSmith 的追踪，你可以把上一个 JSON 添加到你的全局 Claude Code settings.json 文件。

选项 2：Shell 环境变量

在你的 shell 中运行以下命令，或把它们添加到你的 shell 配置文件（~/.zshrc、~/.bashrc 或 ~/.bash_profile）：

bash

export TRACE_TO_LANGSMITH="true"
export CC_LANGSMITH_API_KEY="<LangSmith API key>"
export CC_LANGSMITH_PROJECT="my-project"

验证设置

在 Claude Code 响应后，追踪会在你的 LangSmith 项目中完整出现。如果你在一次运行进行中打断它，插件只会在你发送下一条消息或结束会话时才刷新那次运行。

在 LangSmith 中，你会找到：

每条向 Claude Code 的消息都显示为一条追踪。
来自同一 Claude Code 会话的所有轮次用一个共享的 thread_id 分组，你可以在一个项目的 Threads 标签中查看。

自定义元数据

把 CC_LANGSMITH_METADATA 环境变量设为一个 JSON 对象，以把自定义元数据附加到所有被追踪的运行。这有助于用上下文信息（如 PR URL、作者或环境名）为追踪打标签。

json

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_API_KEY": "<LangSmith API key>",
    "CC_LANGSMITH_PROJECT": "my-project",
    "CC_LANGSMITH_METADATA": "{\"author\":\"jane\",\"environment\":\"development\"}"
  }
}

元数据的键和值会出现在 LangSmith 的所有运行上，你可用来过滤和搜索追踪。

静默一个线程

静默会在追踪中抑制一个线程的输入和输出内容，而不禁用追踪。除非你设置一个默认，否则静默默认关闭。

在启用追踪的情况下，在 Claude Code 内运行这些插件命令。两个命令都不取参数：

/langsmith-tracing:mute：从后续追踪中省略此线程的输入和输出内容。
/langsmith-tracing:unmute：恢复此线程后续轮次的完整追踪。

两个命令都从下一轮开始生效，因此当前轮不变。一轮的模式在轮开始时固定，其子 agent 继承该模式。

被静默的运行保留其正常的嵌套、名字、计时、状态、模型和工具身份，以及 token 用量。输入和输出被替换为一条系统提示。静默模式也省略原始错误、身份和仓库归属、自定义元数据、SDK 运行时元数据和副本元数据覆盖。静默与机密脱敏相互独立。

设置一个默认静默配置

要在不逐个线程运行命令的情况下以仅元数据模式开始线程，把 CC_LANGSMITH_DEFAULT_MUTED 设为 "true"：

json

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_API_KEY": "<LangSmith API key>",
    "CC_LANGSMITH_PROJECT": "my-project",
    "CC_LANGSMITH_DEFAULT_MUTED": "true"
  }
}

把该变量设为 "false" 以回到未静默默认。比较不区分大小写，任何其他值都会静默，包括空字符串。

该插件还从其自有配置文件读取一个 defaultMuted 布尔，按此顺序：项目目录中的 .claude/langsmith.json 和 langsmith-plugins.json，然后是 ~/.claude/langsmith.json 和 ~/.langsmith-plugins.json。环境变量优先于全部四个。

线程偏好是粘性的。该插件把每次显式静默或取消静默保存到一个隐私文件，默认为 ~/.claude/state/langsmith_state.privacy.json，一个已保存的线程偏好在两个方向上都胜过所配置的默认。删除该隐私文件会移除每个线程覆盖，并把每个线程返回到所配置的默认。

密钥脱敏

插件会在将检测到的密钥从运行输入、输出、错误和元数据上传到 LangSmith 之前对其进行脱敏。脱敏默认开启。

脱敏在上传前于你的机器上运行，因此未脱敏的内容永远不会到达 LangSmith。副本目标接收相同的脱敏负载。

检测涵盖提供程序 API 密钥前缀、JSON Web Token 和 PEM 私钥块。它还涵盖上下文形态，例如 API_KEY=<value>、Authorization header 以及嵌入 URL 的密码。每个匹配项都会替换为 [SECRET_DETECTED]。有关规则列表，请参阅从追踪中脱敏密钥。

脱敏匹配已知的凭据形态，因此请将其视为安全网而非保证。格式无法识别的凭据仍会到达 LangSmith，附件、运行名称和标签不会经过匿名器。已脱敏的追踪仍保留构建它时使用的提示、文件内容和工具结果，因此请限制谁可以读取追踪项目。

脱敏针对凭据值，而非身份。插件附加的 anthropic_user_id 和 local_username 元数据不受影响。要省略内容和归属而非从中清除凭据，静默该线程。

关闭脱敏

把 CC_LANGSMITH_REDACT 设为 false、0、no 或 off。比较不区分大小写，任何其他值都让脱敏保持开启。

bash

export CC_LANGSMITH_REDACT="false"

脱敏额外模式

把 CC_LANGSMITH_REDACT_EXTRA 设为一个 { "pattern": ..., "replace": ... } 规则的 JSON 数组。每个 pattern 是一个正则表达式字符串，全局且区分大小写地应用。replace 可选，回退到 [redacted]。

json

{
  "env": {
    "CC_LANGSMITH_REDACT_EXTRA": "[{\"pattern\":\"ACME-[A-Z0-9]{16}\",\"replace\":\"[REDACTED_ACME_KEY]\"}]"
  }
}

额外规则在内置规则之后运行。该插件会跳过一个带无效正则的规则、记录一个错误，并在应用其余规则后上传该轮。

两个设置也从设置一个默认静默配置中描述的插件配置文件读取，作为 redact 和 redact_extra_rules 键：

json

{
  "redact": true,
  "redact_extra_rules": [{ "pattern": "ACME-[A-Z0-9]{16}", "replace": "[REDACTED_ACME_KEY]" }]
}

环境变量优先于全部四个文件。一个文件的行为比环境变量更严格。一个带无效正则的规则会丢弃该文件中的每个设置，而不只是那条规则。

因为项目级的 .claude/langsmith.json 能把 redact 设为 false，在你不控制的仓库中启用追踪之前请审阅那个文件。

与 GitHub Actions 一起使用

你可以把这个插件与 anthropics/claude-code-action 一起在 CI 中追踪 Claude Code 运行。在你的 workflow 添加以下内容：

yaml

- uses: anthropics/claude-code-action@v1
  env:
    TRACE_TO_LANGSMITH: "true"
    CC_LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
    CC_LANGSMITH_PROJECT: "my-project"
    CC_LANGSMITH_METADATA: |
      {
        "pr_url": "${{ github.event.pull_request.html_url || '' }}",
        "pr_number": "${{ github.event.pull_request.number || '' }}",
        "pr_author": "${{ github.event.pull_request.user.login || '' }}",
        "repository": "${{ github.repository }}",
        "commit_sha": "${{ github.sha }}",
        "trigger": "${{ github.event_name }}"
      }
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    github_token: ${{ secrets.GITHUB_TOKEN }}
    plugin_marketplaces: |
      https://github.com/langchain-ai/langsmith-claude-code-plugins.git
    plugins: |
      langsmith-tracing@langsmith-claude-code-plugins
    prompt: |
      Your prompt here

务必把 LANGSMITH_API_KEY 和 ANTHROPIC_API_KEY 添加为仓库机密。

这让你在 LangSmith 中把追踪关联回特定的 PR、commit 和作者。

把一个追踪嵌套到现有运行下

你也可以设置一个名为 CC_LANGSMITH_PARENT_DOTTED_ORDER 的环境变量，把所有 Claude Code 追踪嵌套为一个现有 LangSmith 运行的子项。当 Claude Code 作为一个更大被追踪工作流的一部分被以编程方式调用时，这很有用。

Python

python

import subprocess
from langsmith import traceable, get_current_run_tree

os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "<LangSmith API key>"
os.environ["LANGSMITH_PROJECT"] = "claude-code"

@traceable
def run_claude(prompt: str):
    run_tree = get_current_run_tree()
    subprocess.run(
        ["claude", "-p", prompt],
        env={
            **os.environ,
            "TRACE_TO_LANGSMITH": "true",
            "CC_LANGSMITH_API_KEY": "<LangSmith API key>",
            "CC_LANGSMITH_PROJECT": "claude-code",
            "CC_LANGSMITH_PARENT_DOTTED_ORDER": run_tree.dotted_order,
        },
    )

TypeScript

import { traceable, getCurrentRunTree } from "langsmith/traceable";
import { execSync } from "node:child_process";

process.env.LANGSMITH_TRACING = "true";
process.env.LANGSMITH_API_KEY = "<LangSmith API key>";
process.env.LANGSMITH_PROJECT = "claude-code";

const runClaude = traceable(
  async (prompt: string) => {
    const runTree = getCurrentRunTree();
    const pluginDir = new URL(".", import.meta.url).pathname;
    const res = execSync(`claude -p "${prompt}" --plugin-dir '${pluginDir}'`, {
      env: {
        ...process.env,
        TRACE_TO_LANGSMITH: "true",
        CC_LANGSMITH_API_KEY: "<LangSmith API key>",
        CC_LANGSMITH_PROJECT: "claude-code",
        CC_LANGSMITH_PARENT_DOTTED_ORDER: runTree.dotted_order,
      },
    });
    return res.toString();
  },
  { name: "run_claude" },
);

产生的追踪层级看起来像：

Your outer run (chain)
└── Claude Code Turn (chain)
    ├── Claude (llm)
    ├── Read (tool)
    └── Claude (llm)

追踪到多个目的地（副本）

你可以使用 CC_LANGSMITH_RUNS_ENDPOINTS 环境变量同时追踪到多个 LangSmith 项目或工作区。把 CC_LANGSMITH_RUNS_ENDPOINTS 设为一个副本配置的 JSON 数组。这会覆盖其他客户端设置。

追踪到多个副本适用于：

将追踪同时发送到生产项目和暂存项目。
使用不同 API 密钥追踪到多个工作区。
向特定副本目标添加额外元数据。

每个副本对象支持以下字段：

字段	必需	描述
`apiUrl`	是	LangSmith API URL（通常是 `https://api.smith.langchain.com`）
`apiKey`	是	目标工作区的 API 密钥
`projectName`	是	目标工作区中的项目名
`updates`	否	要在被复制运行上覆盖的可选元数据/字段

设置 CC_LANGSMITH_RUNS_ENDPOINTS 环境变量有两种方式：

在你本地的 .claude/settings.local.json 或全局 ~/.claude/settings.json 中：

json

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_RUNS_ENDPOINTS": "[{\"apiUrl\":\"https://api.smith.langchain.com\",\"apiKey\":\"ls__key_workspace_a\",\"projectName\":\"project-prod\"},{\"apiUrl\":\"https://api.smith.langchain.com\",\"apiKey\":\"ls__key_workspace_b\",\"projectName\":\"project-staging\",\"updates\":{\"metadata\":{\"environment\":\"staging\"}}}]"
  }
}

TIP

要生成转义的 JSON 字符串，使用：

bash

echo '[{"apiUrl":"...","apiKey":"...","projectName":"..."}]' | jq -cR .

故障排查

LangSmith 中没有出现任何追踪

检查钩子正在运行:
bash
```
tail -f ~/.claude/state/hook.log
```
1
你应该在每条 Claude 响应后看到日志条目。
验证环境变量:
- 检查你项目的 .claude/settings.local.json 中 TRACE_TO_LANGSMITH="true"。
- 验证你的个人访问令牌（PAT）正确（以 lsv2_pt_ 开头）。
- 确保该项目名存在于 LangSmith 中。
启用调试模式以查看详细的 API 活动：
json
```
{
  "env": {
    "CC_LANGSMITH_DEBUG": "true"
  }
}
```
1
2
3
4
5
然后检查日志中的 API 调用和 HTTP 状态码。

用户中断后子 agent 运行不出现

子 agent 只在完成时被追踪。这意味着如果你在一次子 agent 运行进行到一半时打断一个对话轮，子 agent 的子运行将不会被追踪。

管理日志文件大小

该钩子把所有活动记录到 ~/.claude/state/hook.log。启用调试模式时，这个文件可能变得很大：

bash

# View log file size
ls -lh ~/.claude/state/hook.log

# Clear logs if needed
> ~/.claude/state/hook.log

从手动 stop 钩子迁移

如果你之前用旧版追踪 Claude Code 搭配 LangSmith，你需要移除 ~/.claude/hooks/stop_hook.sh，并移除从你之前添加它的任何 settings.local.json 或 settings.json 文件中对该钩子的引用，然后遵循插件安装说明。

源代码

该插件在 MIT 许可下开源，可在这个 GitHub 仓库中获得。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织