Claude Code 플러그인 - CoreWeave Docs

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

이 플러그인은 Claude Code 세션 데이터를 Weave로 전송합니다. 이 데이터에는 사용자 프롬프트, Claude 응답, 도구 입력 및 출력, Claude Code 도구가 읽은 파일 내용, 셸 명령어 및 출력, 가져온 URL 및 페이지 콘텐츠가 포함될 수 있습니다.PII 제거 및 민감한 데이터 마스킹은 구현되어 있지 않습니다. 보안 또는 규정 준수 요구사항에 따라 이 데이터를 Weave로 전송할 수 없다면 이 플러그인을 설치하지 마세요.

사전 요구 사항

Node.js v18 이상(npm 포함).
Claude Code 설치 및 인증 완료.
CoreWeave Forge 계정 및 WANDB_API_KEY 환경 변수로 설정한 API 키.
트레이스를 수신할 Weave 프로젝트([YOUR-TEAM]/[YOUR-PROJECT]).

플러그인 설치

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

CLI 설치

npm install -g weave-claude-code

설치 프로그램 실행

weave-claude-code install

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

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

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

WEAVE_PROJECT=[YOUR-TEAM]/[YOUR-PROJECT] \
WANDB_API_KEY=[YOUR-API-KEY] \
weave-claude-code install --non-interactive

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

Claude Code 시작

claude

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

Weave에서 Claude Code 트레이스 보기

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

Forge로 이동하여 프로젝트를 선택하세요.
사이드바 메뉴에서 Agents를 선택하세요.
Conversations 탭을 선택하면 프로젝트에 저장된 모든 에이전트 대화를 볼 수 있습니다.
대화를 선택하면 전체 대화 트리를 살펴볼 수 있습니다.

Agents 뷰에 대한 자세한 내용은 에이전트 활동 보기를 참조하세요. 사용자 프롬프트 하나마다 GenAI semantic conventions를 따르는 OTEL 트레이스가 하나씩 생성됩니다. 트레이스에는 전체 턴 계층 구조가 표시됩니다.

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 환경 변수로 변경할 수 있습니다(플러그인 설정 참조). 서브에이전트는 고유한 유형 이름을 유지합니다. 여러 턴으로 이루어진 대화는 서버 측에서 대화 ID로 연결되므로, 여러 트레이스에 걸쳐 대화를 추적할 수 있습니다. 각 span에는 토큰 사용량, 모델 이름, 도구 입력 및 출력, 시간 정보, 프롬프트와 응답의 텍스트 내용이 포함됩니다. 추적되는 데이터에 대한 자세한 내용은 GitHub의 추적되는 항목을 참조하세요.

플러그인 설정

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

# 모든 현재 설정을 표시합니다.
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을 설정하여 다른 이름을 사용하세요. 예를 들어 팀이나 프로젝트를 구분하기 위해서입니다. 이름은 비워둘 수 없으며, 앞뒤 공백은 제거됩니다. 환경 변수는 설정 파일보다 우선합니다:

export WEAVE_PROJECT=[YOUR-TEAM]/[YOUR-PROJECT]
export WANDB_API_KEY=[YOUR-API-KEY]
export WEAVE_AGENT_NAME=[YOUR-AGENT-NAME]

Weave 스킬

설치 후에는 모든 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 값을 설정할 수 있습니다:

/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]

플러그인 상태 확인

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

weave-claude-code status

각 줄에는 ✓(정상), ✗(액션 필요) 또는 -(아직 활성화되지 않았지만 오류는 아님)가 표시됩니다. Weave에 대화가 표시되지 않으면 데몬 로그를 확인하세요:

weave-claude-code logs

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

weave-claude-code logs --follow

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

W&B Dedicated Cloud 또는 self-hosted 인스턴스

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

export WANDB_BASE_URL=https://[YOUR-INSTANCE].wandb.io

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

데몬을 종료합니다:

printf '{"command":"shutdown"}' | nc -U -w1 ~/.weave-claude-code/daemon.sock

WANDB_BASE_URL을 설정하거나, wandb login --host https://[YOUR-INSTANCE].wandb.io를 실행하여 세션 간 설정을 유지합니다.
Claude Code를 다시 시작합니다. 데몬이 자동으로 다시 시작되고 올바른 URL을 사용합니다.

제거

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

weave-claude-code uninstall

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

​사전 요구 사항

​플러그인 설치

​Weave에서 Claude Code 트레이스 보기

​플러그인 설정

​Weave 스킬

​플러그인 상태 확인

​W&B Dedicated Cloud 또는 self-hosted 인스턴스

​제거