메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt

Use this file to discover all available pages before exploring further.

weave-claude-plugin은 Claude Code 명령줄 인터페이스(CLI)용 플러그인으로, Claude Code 세션의 트레이스를 자동으로 캡처해 W&B Weave로 전송합니다. 코드나 워크플로를 변경하지 않아도 모든 대화 턴, 도구 Call, 하위 에이전트 상호작용이 기록됩니다. 이는 에이전트 동작을 디버깅하고, 세션 이력을 감사하고, 팀 전체의 Claude Code 사용을 모니터링하는 데 유용합니다.

​
사전 요구 사항

플러그인을 설치하기 전에 다음이 준비되어 있는지 확인하세요:
  • Claude Code가 설치되어 있어야 합니다.
  • Node.js와 npm이 설치되어 있어야 합니다.
  • 유효한 API 키가 있는 W&B 계정이 있어야 합니다. API 키를 조회하려면 API keys를 참조하세요.

​
W&B Dedicated Cloud 및 Self-Managed 인스턴스

조직에서 W&B Dedicated Cloud 또는 W&B Self-Managed를 사용하는 경우, Claude Code를 실행하기 전에 다음 방법 중 하나로 배포 기본 URL을 설정해야 합니다:
  • WANDB_BASE_URL 환경 변수를 배포 기본 URL로 설정합니다:
export WANDB_BASE_URL=https://your-instance.wandb.io
  • 세션 간에 기본 URL이 유지되도록 하려면 host 플래그와 함께 wandb login 명령어를 실행하세요. 그러면 host URL이 $HOME/.config/wandb/settings에 저장되며, Weave 클라이언트는 환경 변수를 설정하지 않아도 이를 자동으로 읽습니다.
wandb login --host https://your-instance.wandb.io
플러그인 데몬이 이미 실행 중인 상태에서 WANDB_BASE_URL 또는 host 플래그를 변경해야 하는 경우, 변경 사항을 적용하려면 데몬을 다시 시작하세요: 
printf '{"command":"shutdown"}' | nc -U -w1 ~/.weave_claude_plugin/daemon.sock
그런 다음 Claude Code를 다시 시작하세요. 데몬이 업데이트된 기본 URL을 사용해 시작됩니다.

​
플러그인 설치

CLI를 전역으로 설치한 다음, 설치 프로그램을 한 번 실행하세요: 
npm install -g weave-claude-plugin
weave-claude-plugin install
설치 프로그램은 ~/.weave_claude_plugin/settings.json을 생성하고 Claude Code에 플러그인을 등록한 다음, Weave 프로젝트 이름과 W&B API 키 입력을 요청합니다. install를 실행하기 전에 환경에서 WEAVE_PROJECT 및 WANDB_API_KEY가 이미 설정되어 있으면 설치 프로그램이 해당 값을 사용하므로 프롬프트에서 직접 입력하는 단계를 건너뛸 수 있습니다. 완료되면 Claude Code를 실행하거나 다시 시작하세요. Claude Code CLI가 시작되면 플러그인이 백그라운드 데몬을 시작하고 트레이스를 Weave로 전송합니다. 프롬프트가 표시되면 안 되는 CI, 부트스트랩 스크립트 또는 기타 자동화 환경에서는 --non-interactive 플래그를 지정하세요. 먼저 환경 변수를 설정해 설치 프로그램이 W&B에 인증하고 Weave 프로젝트를 구성할 수 있도록 한 다음, 설치 프로그램을 실행하세요. 설치 프로그램은 플러그인을 구성하고 Claude Code에 등록하는 작업도 동일한 방식으로 수행합니다. 환경 변수가 설정되어 있으면 해당 값을 사용하고, 둘 중 하나라도 없으면 경고를 표시합니다: 
export WEAVE_PROJECT=<your-team-name/your-project-name>
export WANDB_API_KEY=<your-api-key>
weave-claude-plugin install --non-interactive
<your-team-name/your-project-name> 및 <your-api-key>를 본인의 값으로 바꾸세요.

​
데이터 공개

이 플러그인은 Claude Code 세션 데이터를 Weave로 전송합니다. 이 데이터에는 다음과 같은 민감한 정보가 포함될 수 있습니다.
  • 사용자 프롬프트 및 모델 응답
  • 도구 입력 및 도구 출력
  • Claude Code 도구가 읽은 파일 경로 및 파일 내용
  • 셸 명령 및 셸 출력
  • 가져온 URL 및 해당 페이지의 콘텐츠
Claude Code가 세션 중에 시크릿, 자격 증명, 독점 소스 코드, 개인 데이터 또는 기타 기밀 자료를 다루는 경우, 해당 정보가 트레이스의 일부로 Weave에 로깅될 수 있습니다.
현재 플러그인에는 PII 스크러빙 및 민감한 데이터 마스킹이 구현되어 있지 않습니다. 보안 또는 규정 준수 요구 사항상 이러한 범주의 데이터를 Weave로 전송할 수 없는 경우에는 플러그인을 설치하거나 활성화하지 마십시오.

​
Weave에서 트레이스 보기

플러그인을 설치하고 Claude Code를 실행한 후 Weave 프로젝트의 Traces 탭을 열어 트레이스를 확인하세요. 각 Claude Code 세션은 개별 턴과 도구 Call을 하위 항목으로 포함하는 최상위 트레이스로 표시됩니다. 각 트레이스에는 token 사용량, 모델 이름, 도구 입력과 출력, 소요 시간, 그리고 프롬프트 및 응답에 연결된 텍스트 콘텐츠가 포함됩니다. 
claude_code.session
  └─ claude_code.turn                          (사용자 메시지당 하나.)
       ├─ claude_code.tool.*                   (Read, Bash, Grep 등 각 도구 호출.)
       │    └─ claude_code.permission_request  (사용자 승인이 필요한 경우.)
       └─ claude_code.subagent                 (Claude가 하위 에이전트를 생성한 경우.)
            └─ claude_code.tool.*

​
status 및 로그 확인

다음 명령을 사용해 플러그인이 실행 중인지 확인하고 문제를 진단하세요. status를 확인해 데몬이 활성 상태인지, Claude Code가 등록되었는지 확인하세요. Weave에 트레이스가 표시되지 않거나 status에서 액션이 필요하다고 보고하면 로그를 확인하세요. 터미널에서 다음을 실행하세요: 
weave-claude-plugin status
출력의 각 줄에는 다음 레이블 중 하나가 표시됩니다:
  • OK: Tracing에 필요한 모든 항목이 설정되어 정상적으로 실행 중입니다.
  • 조치 필요: 일부 항목이 잘못 설정되었거나 누락되었습니다. 자세한 내용은 아래와 같이 데몬 로그를 확인하세요.
  • 아직 활성화되지 않음: 오류는 아닙니다. 플러그인이 아직 활동을 기록하지 않았습니다. Claude Code 세션을 시작하거나 계속한 뒤 잠시 기다렸다가 명령을 다시 실행하세요.
세션이 Weave에 표시되지 않으면, 문제를 디버깅하는 데 도움이 되도록 데몬 로그를 확인할 수 있습니다: 
weave-claude-plugin logs
실시간으로 로그를 확인하려면: 
weave-claude-plugin logs --follow
~/.weave_claude_plugin/logs/daemon.log에서 로그 파일을 직접 열 수도 있습니다.

​
Claude Code의 스킬

플러그인을 설치하면 다음 스킬을 모든 Claude Code 세션에서 슬래시 명령으로 사용할 수 있습니다. Claude Code의 기본 제공 스킬과 충돌하지 않도록, 아래와 같이 weave:weave-* 이름을 사용합니다.

​
/weave:weave-install

설치와 설정을 대화형으로 안내합니다. 새 머신에서 사용하거나 설치나 설정에 문제가 있을 때 진단용으로 사용하세요. Claude가 CLI를 확인하고 설치 프로그램을 실행한 뒤, 누락된 값을 입력하라는 메시지를 표시하고 모든 것이 정상적으로 작동하는지 확인합니다. 
/weave:weave-install

​
/weave:weave-status

현재 플러그인 상태를 보여주고 수정이 필요한 사항을 설명합니다. weave-claude-plugin status를 실행하는 것과 같으며, Claude가 출력 내용을 해석해 줍니다. 
/weave:weave-status

​
/weave:weave-config

Claude Code에서 나가지 않고 플러그인 설정을 조회하거나 업데이트하세요. 
# 현재 설정을 표시합니다.
/weave:weave-config

# 값을 직접 설정합니다.
/weave:weave-config set weave_project <your-team-name/your-project-name>
/weave:weave-config set wandb_api_key <your-api-key>

​
제거

플러그인과 해당 설정을 제거하려면 다음을 수행하세요: 
weave-claude-plugin uninstall
이렇게 하면 설정 디렉터리가 삭제되고 데몬이 중지됩니다.