追踪 Claude Code 应用 - Docs by LangChain

本指南向您展示如何将 Claude Code CLI 的对话自动发送到 LangSmith。配置完成后，每个 Claude Code 项目都可以选择将追踪发送到 LangSmith。每条追踪包括用户消息、工具调用、压缩、子代理运行和助手响应。系统提示不包含在内，因为 Claude Code 不会在对话记录中返回它们。

前提条件

在设置追踪之前，请确保您已：

入门指南

在 Claude Code 中，运行：

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

要更新插件，请运行：

/plugin marketplace update langsmith-claude-code-plugins
/reload-plugins

如果您正在从之前推荐的使用手动创建停止钩子来追踪 Claude Code 的版本迁移，请参阅从手动停止钩子迁移。

设置环境变量

选项 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 文件，并按如下方式填充：

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

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

选项 2：Shell 环境变量 在您的 shell 中运行以下命令，或将它们添加到您的 shell 配置文件（~/.zshrc、~/.bashrc 或 ~/.bash_profile）中：

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、作者或环境名称）标记追踪非常有用。

设置文件（推荐）
Shell 环境变量

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

export CC_LANGSMITH_METADATA='{"author":"jane","environment":"development"}'

元数据的键和值将出现在 LangSmith 中的所有运行上，您可以使用它们来过滤和搜索追踪。

与 GitHub Actions 一起使用

您可以将此插件与 anthropics/claude-code-action 一起使用，以在 CI 中追踪 Claude Code 运行。将以下内容添加到您的工作流中：

- 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、提交和作者关联起来。

将追踪嵌套在现有运行下

您还可以设置一个名为 CC_LANGSMITH_PARENT_DOTTED_ORDER 的环境变量，将所有 Claude Code 追踪嵌套为现有 LangSmith 运行的子项。当 Claude Code 作为更大追踪工作流的一部分以编程方式调用时，这非常有用。 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 环境变量：

设置文件（推荐）
Shell 环境变量

在您的本地 .claude/settings.local.json 或全局 ~/.claude/settings.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\"}}}]"
  }
}

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

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

选项 2：Shell 环境变量添加到您的 ~/.zshrc、~/.bashrc 或 ~/.bash_profile：

export 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"}}}]'

故障排除

LangSmith 中没有出现追踪

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

用户中断后子代理运行未出现

目前，子代理仅在完成时被追踪。这意味着如果您在子代理运行过程中中断对话轮次，子代理的子运行将不会被追踪。

管理日志文件大小

钩子将所有活动记录到 ~/.claude/state/hook.log。启用调试模式后，此文件可能会变得很大：

# 查看日志文件大小
ls -lh ~/.claude/state/hook.log

# 如果需要，清除日志
> ~/.claude/state/hook.log

从手动停止钩子迁移

如果您之前使用的是使用 LangSmith 追踪 Claude Code 的旧版本，您需要删除 ~/.claude/hooks/stop_hook.sh，并从您之前添加过它的任何 settings.local.json 或 settings.json 文件中移除对该钩子的引用，然后按照上面的插件安装说明操作。

源代码

该插件在 MIT 许可证下开源，可在此 GitHub 仓库中找到。

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

​前提条件

​入门指南

​设置环境变量

​验证设置

​自定义元数据

​与 GitHub Actions 一起使用

​将追踪嵌套在现有运行下

​追踪到多个目标（副本）

​故障排除

​LangSmith 中没有出现追踪

​用户中断后子代理运行未出现

​管理日志文件大小

​从手动停止钩子迁移

​源代码

前提条件

入门指南

设置环境变量

验证设置

自定义元数据

与 GitHub Actions 一起使用

将追踪嵌套在现有运行下

追踪到多个目标（副本）

故障排除

LangSmith 中没有出现追踪

用户中断后子代理运行未出现

管理日志文件大小

从手动停止钩子迁移

源代码