Skip to main content
Claude Code용 CoreWeave Forge 플러그인은 모든 Claude Code 세션을 자동으로 트레이스하고 구조화된 데이터를 Agent Lens로 전송합니다. 코드를 변경하지 않아도 모든 턴, 도구 Call, 서브에이전트가 로깅됩니다. 이 트레이스를 활용해 세션을 디버깅하고, 도구 사용 내역을 감사하고, 여러 run에 걸친 비용과 지연 시간을 모니터링하세요. 이 가이드에서는 플러그인을 설치하고, Agent Lens에서 Claude Code 트레이스를 확인하고, 플러그인을 설정하고, 플러그인 라이프사이클을 관리하는 방법을 안내합니다.
이 플러그인은 Claude Code 세션 데이터를 Agent Lens로 전송합니다. 이 데이터에는 사용자 프롬프트, Claude 응답, 도구 입력 및 출력, Claude Code 도구가 읽은 파일 내용, 셸 명령어 및 출력, 가져온 URL 및 페이지 콘텐츠가 포함될 수 있습니다.PII 제거 및 민감한 데이터 마스킹 기능은 제공되지 않습니다. 보안 또는 규정 준수 요구 사항상 이 데이터를 Agent Lens로 전송할 수 없다면 이 플러그인을 설치하지 마세요.

​
사전 요구 사항

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

​
플러그인 설치

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

CLI 설치

이 플러그인은 Weave 가이드에서 설명하는 weave-claude-code 플러그인과는 별개입니다. 이 플러그인의 CLI는 forge-agent-lens-for-claude-code이며, 스킬은 forge라는 이름을 사용합니다. weave-claude-code 또는 이전 @coreweave/forge-claude-code 패키지를 설치했다면 두 플러그인이 트레이스를 중복으로 전송하지 않도록 이 플러그인을 설치하기 전에 기존 패키지를 제거하세요.
어느 패키지의 설정도 이전되지 않습니다. 설치 프로그램에서 요청하면 프로젝트와 API 키를 다시 설정하세요. 플러그인의 환경 변수를 설정해 두었다면 WEAVE_PROJECT는 FORGE_TRACE_PROJECT로, WEAVE_AGENT_NAME은 FORGE_CLAUDE_CODE_AGENT_NAME으로 이름을 변경하세요.
2

설치 프로그램 실행

설치 프로그램은 다음 작업을 수행합니다.
  • ~/.forge-agent-lens-for-claude-code/settings.json을 생성합니다.
  • Claude Code에 플러그인을 등록합니다.
  • Agent Lens 프로젝트([YOUR-TEAM]/[YOUR-PROJECT])와 Forge API 키가 아직 설정되어 있지 않으면 입력을 요청합니다.
CI, 부트스트랩 스크립트 등 자동화된 시스템에서 입력 요청을 건너뛰려면 실행하기 전에 환경 변수를 설정하세요.
비대화형 모드에서도 설치 프로그램은 설정 파일을 생성하고 플러그인을 등록합니다. 이때 환경의 FORGE_TRACE_PROJECT와 WANDB_API_KEY를 사용하며, 둘 중 하나라도 없으면 경고를 표시합니다. 이 값들은 settings.json에 저장되지 않습니다.기본적으로 설치 프로그램은 GitHub에서 플러그인을 등록합니다. CI 시스템이나 컨테이너에서 GitHub에 접근할 수 없다면 --source=local을 지정해 이전 단계에서 설치한 npm 패키지로 플러그인을 등록하세요.
3

Claude Code 시작

Claude Code가 이미 실행 중이라면 해당 세션에서 /reload-plugins를 실행하세요.이제부터 플러그인이 세션을 자동으로 트레이싱합니다. 특정 프로젝트의 세션만이 아니라 이 머신에서 실행되는 모든 Claude Code 세션이 트레이싱됩니다.

​
Agent Lens에서 Claude Code 트레이스 보기

Claude Code 세션을 한 번 이상 실행한 후 Agent Lens UI에서 프로젝트를 여세요.
  1. CoreWeave Forge로 이동하여 제품 메뉴에서 Agent Lens를 선택한 다음, 사이드 메뉴 상단의 프로젝트 선택기에서 프로젝트를 선택하세요.
  2. 사이드 메뉴에서 Conversations를 선택하세요.
  3. Conversations 탭을 선택하면 프로젝트에 저장된 모든 에이전트 대화를 확인할 수 있습니다.
  4. 대화를 선택하면 전체 대화 트리를 자세히 살펴볼 수 있습니다.
Conversation 탭에 대한 자세한 내용은 에이전트 활동 보기를 참조하세요. 사용자 프롬프트마다 GenAI 시맨틱 규칙을 따르는 OTEL 트레이스가 하나씩 생성됩니다. 트레이스에는 다음과 같이 전체 턴 계층 구조가 표시됩니다.
루트 invoke_agent claude-code span은 최상위 에이전트 이름을 사용하며, 기본값은 claude-code입니다. 이 이름은 agent_name 설정이나 FORGE_CLAUDE_CODE_AGENT_NAME 환경 변수로 변경할 수 있습니다(플러그인 설정 참조). 서브에이전트는 자체 유형 이름을 그대로 유지합니다. 멀티턴 대화는 서버 측에서 대화 ID를 기준으로 연결되므로, 여러 트레이스에 걸친 대화의 흐름을 따라갈 수 있습니다. 각 span에는 토큰 사용량, 모델 이름, 도구 입력 및 출력, 소요 시간, 프롬프트와 응답의 텍스트 내용이 포함됩니다. 트레이스되는 데이터에 대한 자세한 내용은 GitHub의 What Gets Traced를 참조하세요.

​
플러그인 설정하기

설치 후에는 forge-agent-lens-for-claude-code config 명령어로 플러그인 설정을 확인하거나 변경할 수 있습니다.
기본적으로 대화는 Conversations 탭에서 claude-code라는 에이전트 이름으로 표시됩니다. 팀이나 프로젝트를 구분하는 등 다른 이름을 사용하려면 agent_name을 설정하세요. 이름은 비워 둘 수 없으며, 앞뒤 공백은 자동으로 제거됩니다. 플러그인의 백그라운드 데몬은 시작될 때 설정을 읽어 들입니다. 실행 중인 데몬에 변경한 설정을 적용하려면 데몬을 다시 시작하세요.
환경 변수는 설정 파일보다 우선 적용됩니다.

​
Agent Lens 스킬

설치를 마치면 모든 Claude Code 세션에서 Agent Lens 전용 스킬 세 가지를 바로 사용할 수 있습니다. forge:forge-config 스킬을 사용하면 Claude Code 안에서 Agent Lens 값을 설정할 수 있습니다.

​
플러그인 상태 확인

다음 CLI 명령어를 사용하여 플러그인 상태를 확인하거나 문제를 해결할 수 있습니다.
각 줄에는 ✓(정상), ✗(조치 필요) 또는 -(아직 활성화되지 않았지만 오류는 아님)가 표시됩니다. Agent Lens에 대화가 표시되지 않으면 다음 명령어를 실행하여 데몬 로그의 마지막 50줄을 출력하세요.
더 많은 줄을 출력하려면 --tail 옵션에 출력할 줄 수를 지정하세요.
로그를 실시간으로 모니터링하려면 다음 명령을 실행하세요.
로그 파일은 ~/.forge-agent-lens-for-claude-code/logs/daemon.log에서도 확인할 수 있습니다. 문제를 진단할 때 더 자세한 데몬 출력을 보려면 디버그 모드를 켜세요.
현재 셸 세션에서만 디버그 모드를 켜려면 대신 FORGE_CLAUDE_CODE_DEBUG=1을 설정하세요.

​
제거

Claude Code에서 플러그인을 제거하고 트레이싱을 중지하려면 다음 명령을 실행하세요.
로그 디렉터리를 유지하려면 --keep-logs 옵션을 지정하세요.
마지막 수정일 2026년 10월 23일