> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 플러그인

> 관측성과 디버깅을 위해 W&B Weave에서 Claude Code 세션을 추적하세요.

export const AgentLensBanner = ({href}) => <Tip>
    <strong>This workflow is also available in CoreWeave Agent Lens.</strong> Agent Lens is the Forge experience built for tracing, monitoring, and analyzing AI agents, with automated insights into agent failures and user intents. It uses the same trace data as Weights & Biases Weave, so the traces you already send appear there with nothing to migrate.{' '}
    <a href={href || '/products/agent-lens'}>{href ? 'See how to do this in Agent Lens' : 'Learn about Agent Lens'}</a>.
  </Tip>;

<AgentLensBanner href="/ko/products/agent-lens/integrations/claude-code" />

Weave Claude Code 플러그인은 모든 Claude Code 세션을 자동으로 추적하고 구조화된 데이터를 W\&B Weave로 전송합니다. 이 플러그인은 코드를 변경할 필요 없이 모든 턴, 도구 Call, 서브에이전트를 로깅합니다. 이러한 트레이스를 사용하여 세션을 디버깅하고, 도구 사용을 감사하고, run 전반의 비용과 지연 시간을 모니터링하세요.

이 가이드에서는 플러그인 설치, Weave에서 Claude Code 트레이스 확인, 플러그인 설정, 라이프사이클 관리를 안내합니다.

<Warning>
  이 플러그인은 Claude Code 세션 데이터를 Weave로 전송합니다. 이 데이터에는 사용자 프롬프트, Claude 응답, 도구 입력 및 출력, Claude Code 도구가 읽은 파일 내용, 셸 명령어 및 출력, 가져온 URL 및 페이지 콘텐츠가 포함될 수 있습니다.

  PII 제거 및 민감한 데이터 마스킹은 구현되어 있지 않습니다. 보안 또는 규정 준수 요구사항에 따라 이 데이터를 Weave로 전송할 수 없다면 이 플러그인을 설치하지 마세요.
</Warning>

<h2 id="prerequisites">
  사전 요구 사항
</h2>

* [Node.js](https://nodejs.org/) v18 이상(`npm` 포함).
* [Claude Code](https://claude.ai/code) 설치 및 인증 완료.
* CoreWeave Forge 계정 및 `WANDB_API_KEY` 환경 변수로 설정한 [API 키](https://forge.coreweave.com/settings#apikeys).
* 트레이스를 수신할 Weave 프로젝트(`[YOUR-TEAM]/[YOUR-PROJECT]`).

<h2 id="install-the-plugin">
  플러그인 설치
</h2>

CLI를 설치하고 설치 프로그램을 실행해 Claude Code에 플러그인을 등록한 다음, Claude Code 세션을 시작하면 트레이싱이 시작됩니다.

<Steps>
  <Step title="CLI 설치">
    ```bash lines theme={"system"}
    npm install -g weave-claude-code
    ```
  </Step>

  <Step title="설치 프로그램 실행">
    ```bash lines theme={"system"}
    weave-claude-code install
    ```

    설치 프로그램은 다음 작업을 수행합니다.

    * `~/.weave-claude-code/settings.json`을 생성합니다.
    * Claude Code에 플러그인을 등록합니다.
    * Weave 프로젝트(`[YOUR-TEAM]/[YOUR-PROJECT]`)와 W\&B API 키가 아직 설정되어 있지 않으면 입력을 요청합니다.

    CI, 부트스트랩 스크립트 등 자동화된 시스템에서 입력 요청 없이 설치하려면 실행 전에 환경 변수를 설정하세요.

    ```bash lines theme={"system"}
    WEAVE_PROJECT=[YOUR-TEAM]/[YOUR-PROJECT] \
    WANDB_API_KEY=[YOUR-API-KEY] \
    weave-claude-code install --non-interactive
    ```

    비대화형 모드에서도 설치 프로그램은 설정 파일을 생성하고 플러그인을 등록합니다. 이때 환경 변수의 `WEAVE_PROJECT`와 `WANDB_API_KEY` 값을 사용하며, 둘 중 하나라도 없으면 경고를 표시합니다.
  </Step>

  <Step title="Claude Code 시작">
    ```bash lines theme={"system"}
    claude
    ```

    이제부터 플러그인이 세션을 자동으로 트레이싱합니다. 프롬프트를 한두 개 실행한 다음 Weave 프로젝트를 열어 트레이스가 표시되는지 확인하세요.
  </Step>
</Steps>

<h2 id="view-claude-code-traces-in-weave">
  Weave에서 Claude Code 트레이스 보기
</h2>

Claude Code 세션을 한 번 이상 실행한 후 Weights & Biases UI에서 프로젝트를 여세요.

1. [Forge](https://forge.coreweave.com/wandb)로 이동하여 프로젝트를 선택하세요.
2. 사이드바 메뉴에서 **Agents**를 선택하세요.
3. **Conversations** 탭을 선택하면 프로젝트에 저장된 모든 에이전트 대화를 볼 수 있습니다.
4. 대화를 선택하면 전체 대화 트리를 살펴볼 수 있습니다.

Agents 뷰에 대한 자세한 내용은 [에이전트 활동 보기](/ko/products/wandb/weave/guides/tracking/view-agent-activity)를 참조하세요.

사용자 프롬프트 하나마다 [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)를 따르는 OTEL 트레이스가 하나씩 생성됩니다. 트레이스에는 전체 턴 계층 구조가 표시됩니다.

```text theme={"system"}
invoke_agent claude-code               (루트, 사용자 프롬프트당 트레이스 하나.)
├─ chat <model>                        (턴 내의 각 LLM Call.)
├─ execute_tool <tool_name>            (Read, Bash, Grep 등의 각 도구 Call.)
└─ invoke_agent <subagent_type>        (Agent 도구를 통해 실행되는 서브에이전트.)
   ├─ chat <model>
   └─ execute_tool <tool_name>
```

루트 `invoke_agent claude-code` span은 최상위 에이전트 이름을 사용하며, 기본값은 `claude-code`입니다. `agent_name` 설정 또는 `WEAVE_AGENT_NAME` 환경 변수로 변경할 수 있습니다([플러그인 설정](#configure-the-plugin) 참조). 서브에이전트는 고유한 유형 이름을 유지합니다.

여러 턴으로 이루어진 대화는 서버 측에서 대화 ID로 연결되므로, 여러 트레이스에 걸쳐 대화를 추적할 수 있습니다. 각 span에는 토큰 사용량, 모델 이름, 도구 입력 및 출력, 시간 정보, 프롬프트와 응답의 텍스트 내용이 포함됩니다. 추적되는 데이터에 대한 자세한 내용은 GitHub의 [추적되는 항목](https://github.com/wandb/weave-claude-code/blob/main/README.md#what-gets-traced)을 참조하세요.

<h2 id="configure-the-plugin">
  플러그인 설정
</h2>

설치 후 플러그인 설정을 확인하거나 업데이트하려면 `weave-claude-code config` 명령어를 사용하세요:

```bash lines theme={"system"}
# 모든 현재 설정을 표시합니다.
weave-claude-code config show

# Weave 프로젝트를 설정합니다.
weave-claude-code config set weave_project [YOUR-TEAM]/[YOUR-PROJECT]

# W&B API 키를 설정합니다.
weave-claude-code config set wandb_api_key [YOUR-API-KEY]

# (선택) Agents view에 표시되는 에이전트 이름을 사용자 지정합니다.
weave-claude-code config set agent_name [YOUR-AGENT-NAME]
```

기본적으로 대화는 Agents view에서 `claude-code` 에이전트 이름 아래에 표시됩니다. `agent_name`을 설정하여 다른 이름을 사용하세요. 예를 들어 팀이나 프로젝트를 구분하기 위해서입니다. 이름은 비워둘 수 없으며, 앞뒤 공백은 제거됩니다.

환경 변수는 설정 파일보다 우선합니다:

```bash lines theme={"system"}
export WEAVE_PROJECT=[YOUR-TEAM]/[YOUR-PROJECT]
export WANDB_API_KEY=[YOUR-API-KEY]
export WEAVE_AGENT_NAME=[YOUR-AGENT-NAME]
```

<h2 id="weave-skills">
  Weave 스킬
</h2>

설치 후에는 모든 Claude Code 세션 내에서 Weave 전용 스킬 세 가지를 바로 사용할 수 있습니다.

| 스킬 | 명령어 | 설명 |
| - | - | - |
| 설치 | `/weave:weave-install` | 설치 및 설정 과정을 대화형으로 안내합니다. 새로 설정하는 머신에서 사용하거나 잘못된 설정을 진단할 때 사용하세요. |
| 상태 | `/weave:weave-status` | 현재 플러그인 상태를 확인하고 문제를 설명합니다. `weave-claude-code status` 실행과 동일하지만, Claude가 출력을 해석하고 수정할 사항을 알려줍니다. |
| 설정 | `/weave:weave-config` | Claude Code를 벗어나지 않고 플러그인 설정을 조회하거나 업데이트합니다. |

`weave:weave-config` 스킬을 사용하여 Claude Code 내에서 Weave 값을 설정할 수 있습니다:

```text theme={"system"}
/weave:weave-config set weave_project [YOUR-TEAM]/[YOUR-PROJECT]
/weave:weave-config set wandb_api_key [YOUR-API-KEY]
/weave:weave-config set agent_name [YOUR-AGENT-NAME]
```

<h2 id="check-plugin-status">
  플러그인 상태 확인
</h2>

다음 CLI 명령어를 사용하여 플러그인 상태를 확인하거나 문제를 해결할 수 있습니다:

```bash lines theme={"system"}
weave-claude-code status
```

각 줄에는 `✓`(정상), `✗`(액션 필요) 또는 `-`(아직 활성화되지 않았지만 오류는 아님)가 표시됩니다.

Weave에 대화가 표시되지 않으면 데몬 로그를 확인하세요:

```bash lines theme={"system"}
weave-claude-code logs
```

로그를 실시간으로 확인하려면:

```bash lines theme={"system"}
weave-claude-code logs --follow
```

로그 파일은 `~/.weave-claude-code/logs/daemon.log`에도 있습니다.

<h3 id="wb-dedicated-cloud-or-self-hosted-instances">
  W\&B Dedicated Cloud 또는 self-hosted 인스턴스
</h3>

W\&B Dedicated Cloud 또는 self-hosted 인스턴스를 사용하는 경우, Claude Code를 실행하기 전에 `WANDB_BASE_URL`을 설정하세요:

```bash lines theme={"system"}
export WANDB_BASE_URL=https://[YOUR-INSTANCE].wandb.io
```

플러그인이 시작 시 `WANDB_BASE_URL`을 읽는 백그라운드 데몬을 실행합니다. 변수를 설정할 때 데몬이 이미 실행 중이면 변경 사항을 감지하지 못합니다. 데몬을 다시 시작하려면:

1. 데몬을 종료합니다:
   ```bash lines theme={"system"}
   printf '{"command":"shutdown"}' | nc -U -w1 ~/.weave-claude-code/daemon.sock
   ```
2. `WANDB_BASE_URL`을 설정하거나, `wandb login --host https://[YOUR-INSTANCE].wandb.io`를 실행하여 세션 간 설정을 유지합니다.
3. Claude Code를 다시 시작합니다. 데몬이 자동으로 다시 시작되고 올바른 URL을 사용합니다.

<h2 id="uninstall">
  제거
</h2>

Claude Code에서 플러그인을 제거하려면 다음을 실행하세요:

```bash lines theme={"system"}
weave-claude-code uninstall
```

로그 디렉터리를 유지하려면 `--keep-logs`를 전달하세요.


## Related topics

- [Codex 플러그인](/ko/products/wandb/weave/guides/integrations/agents/codex-harness.md)