> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 追踪 Claude Code 应用

本指南向您展示如何将 [Claude Code CLI](https://code.claude.com/docs/en/overview) 的对话自动发送到 LangSmith。

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

## 前提条件

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

* 安装 [**Claude Code CLI**](https://code.claude.com/docs/en/overview)。
* 拥有 [**LangSmith API 密钥**](https://smith.langchain.com/settings/apikeys)。
* 安装 [**Node.js**](https://nodejs.org/)。

## 入门指南

在 Claude Code 中，运行：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
/plugin marketplace add langchain-ai/langsmith-claude-code-plugins
/plugin install langsmith-tracing@langsmith-claude-code-plugins
/reload-plugins
```

要更新插件，请运行：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
/plugin marketplace update langsmith-claude-code-plugins
/reload-plugins
```

<Note> 如果您正在从之前推荐的使用手动创建停止钩子来追踪 Claude Code 的版本迁移，请参阅[从手动停止钩子迁移](#从手动停止钩子迁移)。 </Note>

### 设置环境变量

**选项 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 的项目设置文件](https://code.claude.com/docs/en/settings#:~:text=Project%20settings%20are%20saved%20in%20your%20project%20directory%3A)。在您的项目目录中创建一个 `.claude/settings.local.json` 文件，并按如下方式填充：

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "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](https://code.claude.com/docs/en/settings#:~:text=User%20settings%20are%20defined%20in%20~/.claude/settings.json%20and%20apply%20to%20all%20projects.) 文件中。 </Note>

**选项 2：Shell 环境变量**

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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、作者或环境名称）标记追踪非常有用。

<Tabs>
  <Tab title="设置文件（推荐）">
    ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "env": {
        "TRACE_TO_LANGSMITH": "true",
        "CC_LANGSMITH_API_KEY": "<LangSmith API key>",
        "CC_LANGSMITH_PROJECT": "my-project",
        "CC_LANGSMITH_METADATA": "{\"author\":\"jane\",\"environment\":\"development\"}"
      }
    }
    ```
  </Tab>

  <Tab title="Shell 环境变量">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    export CC_LANGSMITH_METADATA='{"author":"jane","environment":"development"}'
    ```
  </Tab>
</Tabs>

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

## 与 GitHub Actions 一起使用

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

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
- 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` 添加为[仓库密钥](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions)。

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

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

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

**Python**

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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**

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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 数组。这将覆盖其他客户端设置。

追踪到多个[副本](/langsmith/log-traces-to-project)对于以下情况很有用：

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

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

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

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

<Tabs>
  <Tab title="设置文件（推荐）">
    在您的本地 `.claude/settings.local.json` 或全局 `~/.claude/settings.json` 中：

    ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "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 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      echo '[{"apiUrl":"...","apiKey":"...","projectName":"..."}]' | jq -cR .
      ```
    </Tip>
  </Tab>

  <Tab title="Shell 环境变量">
    **选项 2：Shell 环境变量**

    添加到您的 `~/.zshrc`、`~/.bashrc` 或 `~/.bash_profile`：

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"}}}]'
    ```
  </Tab>
</Tabs>

## 故障排除

### LangSmith 中没有出现追踪

1. **检查钩子是否正在运行**：
   ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
   tail -f ~/.claude/state/hook.log
   ```
   您应该在每次 Claude 响应后看到日志条目。

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

3. **启用调试模式**以查看详细的 API 活动：
   ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
   {
     "env": {
       "CC_LANGSMITH_DEBUG": "true"
     }
   }
   ```
   然后检查日志中的 API 调用和 HTTP 状态码。

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

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

### 管理日志文件大小

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 查看日志文件大小
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 仓库](https://github.com/langchain-ai/langsmith-claude-code-plugins) 中找到。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档](/use-these-docs)通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/trace-claude-code.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>