OpenClaw 플러그인 - CoreWeave Docs

OpenClaw용 Weave 플러그인은 OpenClaw 게이트웨이를 거쳐 실행되는 모든 에이전트 세션을 자동으로 트레이싱하고, 구조화된 데이터를 Agent Lens로 전송합니다. 애플리케이션 코드를 수정하지 않아도 모든 turn, 모델 Call, 도구 실행이 로깅됩니다. 이렇게 수집한 트레이스로 세션을 디버깅하고, 도구 사용 내역을 감사하고, 여러 run에 걸친 비용과 지연 시간을 모니터링하세요. 이 가이드는 게이트웨이 뒤에서 실행되는 에이전트에 Agent Lens 트레이싱을 활성화하려는 OpenClaw 게이트웨이 운영자를 대상으로 합니다. 플러그인 설치 및 설정 방법, 생성된 트레이스 확인 방법, 일반적인 문제 해결 방법을 안내합니다.

이 플러그인은 Weights & Biases Weave 플러그인입니다. CoreWeave Forge 버전은 아직 제공되지 않습니다. Agent Lens와 Weave는 동일한 트레이스 데이터를 공유하므로, 플러그인이 전송한 트레이스는 Agent Lens에 표시됩니다.

이 플러그인은 OpenClaw 세션 데이터를 Agent Lens로 전송합니다. 이 데이터에는 사용자 프롬프트, 모델 응답, 도구 입력 및 출력, 도구 결과, 대화 이력이 포함될 수 있습니다.이 플러그인은 개인 식별 정보(PII) 제거나 민감한 데이터 마스킹 기능을 제공하지 않습니다. 콘텐츠 캡처를 막으려면 플러그인 설정에서 captureContent: false를 지정하세요. 보안 또는 규정 준수 요구 사항 때문에 이 데이터를 Agent Lens로 전송할 수 없다면 이 플러그인을 설치하지 마세요.

사전 요구 사항

Node.js v22.14 이상
플러그인 API를 지원하는 OpenClaw 2026.4.25 이상
CoreWeave Forge 계정 및 API 키
트레이스를 수신할 Agent Lens 프로젝트([YOUR-TEAM]/[YOUR-PROJECT])

플러그인 설치

다음 단계에 따라 플러그인을 설치하고 OpenClaw 게이트웨이에 등록한 다음, 트레이스가 Agent Lens 프로젝트에 전달되는지 확인하세요.

패키지 설치

openclaw plugins install weave-openclaw

전체 이름인 weave-openclaw를 사용하세요(weave만 입력하면 이 플러그인이 아니라 Weave SDK를 가리킵니다). OpenClaw 게이트웨이는 설정을 통해 플러그인을 로드하므로 애플리케이션 코드에서 임포트할 필요가 없습니다.

게이트웨이 설정에 플러그인 추가

기본 설정 파일 위치는 ~/.openclaw/openclaw.json입니다(주석과 후행 쉼표를 허용하는 JSON5 형식). 아직 설정 파일이 없다면 openclaw onboard를 실행하여 기본 파일을 생성하세요. [YOUR-TEAM]과 [YOUR-PROJECT]를 사용 중인 프로젝트에 맞게 변경하세요.

{
  plugins: {
    allow: ["weave"],
    entries: {
      weave: {
        enabled: true,
        config: { entity: "YOUR-TEAM", project: "YOUR-PROJECT" },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}

**hooks.allowConversationAccess**를 **true**로 설정하세요. 그러면 OpenClaw가 콘텐츠를 포함하는 훅(llm_input, llm_output, agent_end)을 실행하고, span에 입력 및 출력 텍스트, 도구 인수, 도구 결과가 포함됩니다.diagnostics.enabled는 기본적으로 켜져 있습니다. 비활성화해야 하는 경우에만 명시적으로 설정하세요.

게이트웨이 재시작 및 확인

OpenClaw 게이트웨이를 재시작한 다음, OpenClaw 채팅 화면 중 아무 곳에서나 /weave status를 실행하여 플러그인이 활성 상태인지 확인하세요. 에이전트를 처음 실행하고 몇 초 이내에 https://forge.coreweave.com/agent-lens/[YOUR-TEAM]/[YOUR-PROJECT] 에 트레이스가 표시됩니다.

Agent Lens에서 OpenClaw 트레이스 보기

플러그인이 활성화되면 에이전트 세션마다 트레이스가 생성되며, 이 트레이스는 Agent Lens UI에서 살펴볼 수 있습니다. 에이전트 세션을 한 번 이상 실행한 후 Agent Lens UI에서 프로젝트를 여세요.

CoreWeave Forge로 이동하여 제품 메뉴에서 Agent Lens를 선택한 다음, 사이드 메뉴 상단의 프로젝트 선택기에서 프로젝트를 선택하세요.
사이드 메뉴에서 Conversations를 선택하세요.
Conversations 탭을 선택하면 프로젝트에 저장된 모든 에이전트 대화를 볼 수 있습니다.
대화를 선택하면 전체 대화 트리를 살펴볼 수 있습니다.

Conversations 탭에 대한 자세한 내용은 에이전트 활동 보기를 참조하세요. 플러그인은 OpenTelemetry (OTel) GenAI 시맨틱 규칙에 따라 span을 내보냅니다.

Span	내보내는 시점	주요 속성
`invoke_agent <agent>`	에이전트 run마다	`gen_ai.agent.name`, `gen_ai.conversation.id`, 누적 비용, 토큰 사용량
`chat <model>`	모델 Call마다	`gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`
`execute_tool <tool>`	도구 실행마다	`gen_ai.tool.name`, `gen_ai.tool.call.id`

설정 레퍼런스

이 섹션에서는 openclaw.json에 있는 weave 플러그인 항목의 전체 설정 레퍼런스를 설명합니다. apiKey 필드는 네 가지 인증 소스를 지원하며, 다음 순서대로 확인됩니다.

source: "env" 또는 source: "file"이 지정된 SecretRef 객체(아래 예시의 10번째 줄 참조)
리터럴 apiKey 문자열(지원되지만 권장하지 않음)
WANDB_API_KEY 환경 변수
wandb login으로 생성되는 Agent Lens 호스트의 ~/.netrc 항목

{
  plugins: {
    entries: {
      weave: {
        enabled: true,
        config: {
          entity: "YOUR-TEAM",
          project: "YOUR-PROJECT",
          // apiKey를 생략하면 환경 변수에서 WANDB_API_KEY를 읽습니다.
          // SecretRef는 source: "env" 또는 "file"을 지원합니다.
          //   { source: "env",  provider: "default", id: "WANDB_API_KEY" }
          //   { source: "file", provider: "default", id: "/run/secrets/wandb" }
          // 일반 문자열도 사용할 수 있지만 권장하지 않습니다.
          apiKey: { source: "env", provider: "default", id: "WANDB_API_KEY" },
          serviceName: "openclaw-agent",
          // 선택 사항입니다. 설정하면 Conversations 탭의 그룹화가 개선됩니다.
          agentName: "my-agent",
          agentVersion: "v1.0",
          agentDescription: "What my agent does.",
          // 기본값은 켜짐입니다. 완전히 끄려면(규정 준수 또는 보존 정책)
          // false로 설정하세요. 플러그인은 캡처된 문자열을 마스킹하지
          // 않으므로, 필요하면 업스트림에서 민감한 정보를 제거하세요.
          captureContent: true,
          flushIntervalMs: 1000,
        },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}

captureContent의 기본값은 true입니다. captureContent가 true이면 플러그인은 입력 및 출력 메시지, 도구 인수, 도구 결과도 gen_ai.input.messages 및 gen_ai.output.messages 페이로드 형식에 맞춰 함께 내보냅니다. 또한 서브에이전트, 컴팩션 이벤트, 루프 감지, 재시도, 컨텍스트 사이징 정보를 추가 속성과 span 이벤트로 기록합니다. 규정 준수 또는 데이터 보존 정책상 캡처를 비활성화해야 하는 경우 captureContent를 false로 설정하세요.

문제 해결

트레이스가 Agent Lens에 전달되지 않거나 content 필드가 비어 있으면 다음 섹션을 참고하여 가장 흔한 원인을 진단하세요. 게이트웨이 로그는 openclaw를 실행 중인 프로세스의 터미널 출력입니다. 데몬으로 실행한 경우에는 프로세스 관리자의 로그 스트림을 확인하세요.

플러그인은 로드되었지만 span이 표시되지 않는 경우

/weave status를 실행하세요. lifecycle이 disabled, config-error 또는 not-started이면 플러그인이 활성화되지 않은 것입니다. 게이트웨이 로그에 weave: config.entity is required, weave: configuration error 또는 [weave] incompatible plugin SDK 메시지가 있는지 확인하세요.
게이트웨이 설정에 diagnostics.enabled: false가 설정되어 있지 않은지 확인하세요. 이 필드는 true여야 합니다.
entity와 프로젝트가 현재 확인 중인 Agent Lens 프로젝트의 URL 슬러그와 일치하는지 확인하세요. /weave status를 실행하면 project=[YOUR-TEAM]/[YOUR-PROJECT]가 출력되어야 합니다.
인증 소스를 확인하세요. /weave status를 실행하면 auth=...가 출력되어야 합니다. 출력이 WANDB_API_KEY env인데 키를 다른 환경 변수에 설정했다면 플러그인이 잘못된 키를 읽고 있는 것입니다.

span은 수집되지만 입력/출력 텍스트가 비어 있는 경우

게이트웨이 로그에서 다음 내용을 확인하세요.

[plugins] typed hook "llm_input"  blocked because non-bundled plugins must set
                                  plugins.entries.weave.hooks.allowConversationAccess=true
[plugins] typed hook "llm_output" blocked ...
[plugins] typed hook "agent_end"  blocked ...

OpenClaw는 콘텐츠가 포함된 훅을 운영자가 명시적으로 옵트인한 경우에만 사용할 수 있도록 제한합니다. 설정에서 plugins.entries.weave.hooks.allowConversationAccess: true를 지정하고 게이트웨이를 다시 시작하세요. span 구조와 비용 및 사용량 데이터는 훅이 아닌 진단 이벤트를 통해 전달되므로, allowConversationAccess가 false여도 정상적으로 수집됩니다.

Agent Lens로 트레이스 전송 시 발생하는 오류

플러그인이 활성 상태이고 span도 생성되는데 Agent Lens에 표시되지 않는다면, 게이트웨이 로그에서 내보내기 오류를 찾아 다음 표와 비교하세요.

증상	가장 가능성 높은 원인	해결 방법
`trace.wandb.ai`에서 `401` 또는 `403` 반환	API 키가 유효하지 않거나 범위가 제한됨	키가 유효한지, 그리고 팀이 해당 entity와 프로젝트를 소유하고 있는지 확인하세요. `wandb login`을 실행하면 `~/.netrc`가 갱신됩니다.
연결 거부 또는 DNS 오류	DNS, 프록시 또는 방화벽 문제	게이트웨이 호스트가 `443` 포트를 통해 `trace.wandb.ai`에 연결할 수 있는지 확인하세요.

​사전 요구 사항

​플러그인 설치

​Agent Lens에서 OpenClaw 트레이스 보기

​설정 레퍼런스

​문제 해결

​플러그인은 로드되었지만 span이 표시되지 않는 경우

​span은 수집되지만 입력/출력 텍스트가 비어 있는 경우

​Agent Lens로 트레이스 전송 시 발생하는 오류

사전 요구 사항

플러그인 설치

Agent Lens에서 OpenClaw 트레이스 보기

설정 레퍼런스

문제 해결

플러그인은 로드되었지만 span이 표시되지 않는 경우

span은 수집되지만 입력/출력 텍스트가 비어 있는 경우

Agent Lens로 트레이스 전송 시 발생하는 오류