本指南介绍如何自动将对话从 Claude Code CLI 发送到 LangSmith。

配置完成后，每个 Claude Code 项目都可以选择向 LangSmith 发送追踪。每个追踪包含用户消息、工具调用、压缩、子代理运行和助手回复。系统提示词不包含在内，因为 Claude Code 不会在对话记录中返回它们。

前提条件

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

• - **Claude Code CLI** installed.
• - A **LangSmith API 密钥**.
• - **Node.js** installed.

入门指南

在 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

设置环境变量

选项 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": "",
    "CC_LANGSMITH_PROJECT": "my-project"
  }
}

选项 2：Shell 环境变量

在 shell 中运行以下命令或将它们添加到您的 shell 配置文件（~/.zshrc, ~/.bashrc, or ~/.bash_profile):

验证设置

追踪将在 Claude Code 响应后完整显示在您的 LangSmith 项目中。如果您在使用过程中中断运行，插件只会在您发送下一条消息或结束会话时刷新该运行。

在 LangSmith 中，您会看到：

• - 每次向 Claude Code 发送的消息都会显示为一个追踪。
• - 同一 Claude Code 会话的所有轮次都使用共享的 thread_id进行分组，您可以在项目的 **线程** 标签页中查看。

自定义元数据

设置 CC_LANGSMITH_METADATA 环境变量设置为JSON对象，用于向所有追踪的运行附加自定义元数据。这对于使用上下文信息（如PR URL、作者或环境名称）标记追踪非常有用。

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_API_KEY": "",
    "CC_LANGSMITH_PROJECT": "my-project",
    "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 as 仓库密钥.

这让您可以在LangSmith中将追踪与特定的PR、提交和作者关联起来。

将追踪嵌套在现有运行下

您也可以设置一个名为 CC_LANGSMITH_PARENT_DOTTED_ORDER 的环境变量，将所有Claude Code追踪作为现有LangSmith运行的子级嵌套。这在Claude Code作为更大追踪工作流的一部分以编程方式调用时非常有用。

Python

from langsmith import traceable, get_current_run_tree


os.environ["LANGSMITH_TRACING"] = "true"
os.environ["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": "",
            "CC_LANGSMITH_PROJECT": "claude-code",
            "CC_LANGSMITH_PARENT_DOTTED_ORDER": run_tree.dotted_order,
        },
    )

TypeScript

process.env.LANGSMITH_TRACING = "true";
process.env.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: "",
        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密钥追踪到多个工作区。
• - 为特定副本目标添加额外的元数据。

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

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

{
  "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\"}}}]"
  }
}

故障排除

LangSmith中没有追踪出现

1. **检查hook是否正在运行**:

   tail -f ~/.claude/state/hook.log
   

您应该在每次Claude响应后看到日志条目。

2. **验证环境变量**: - 检查 TRACE_TO_LANGSMITH="true" 在您项目的 .claude/settings.local.json. - 验证您的个人访问令牌(PAT)是否正确（以 lsv2_pt_). - 确保项目名称在LangSmith中存在。

3. **启用调试模式** 查看详细的API活动：

   {
     "env": {
       "CC_LANGSMITH_DEBUG": "true"
     }
   }
   

然后检查日志中的 API 调用和 HTTP 状态码。

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

管理日志文件大小

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

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

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

从手动停止钩子迁移

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

源代码

该插件基于 MIT 许可证开源，可在 此 GitHub 仓库中找到.