OpenClaw 플러그인 - CoreWeave Docs

Weave OpenClaw 플러그인은 OpenClaw 게이트웨이를 통해 실행되는 모든 에이전트 세션을 자동으로 트레이싱하고 구조화된 데이터를 W&B Weave로 전송합니다. 이 플러그인은 애플리케이션 코드를 변경하지 않고도 모든 턴, 모델 Call, 도구 실행을 로깅합니다. 이러한 트레이스를 사용하여 세션을 디버깅하고, 도구 사용을 감사하고, run 전반의 비용과 지연 시간을 모니터링하세요. 이 가이드는 게이트웨이 뒤에서 실행되는 에이전트에 Weave 트레이싱을 활성화하려는 OpenClaw 게이트웨이 운영자를 위한 문서입니다. 플러그인 설치, 설정, 생성된 트레이스 확인, 일반적인 문제 해결 방법을 안내합니다.

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

사전 요구 사항

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

플러그인 설치

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

패키지 설치

openclaw plugins install weave-openclaw

전체 이름인 weave-openclaw를 사용하세요 (weave만 사용하면 이 플러그인이 아닌 W&B 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/wandb/[YOUR-TEAM]/[YOUR-PROJECT]/weave/에 트레이스가 표시됩니다.

Weave에서 OpenClaw 트레이스 보기

플러그인이 활성화되면 각 에이전트 세션에서 Weights & Biases UI로 확인할 수 있는 트레이스가 생성됩니다. 에이전트 세션을 하나 이상 실행한 후 Weights & Biases UI에서 프로젝트를 여세요:

Forge로 이동하여 프로젝트를 선택하세요.
사이드바 메뉴에서 Agents를 선택하세요.
Conversations 탭을 선택하여 프로젝트에 저장된 모든 에이전트 대화를 확인하세요.
대화를 선택하여 전체 대화 트리를 확인하세요.

Agents 뷰에 대한 자세한 내용은 에이전트 활동 보기를 참조하세요. 플러그인은 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 string(지원되지만 권장하지 않음).
WANDB_API_KEY 환경 변수.
wandb login으로 생성된 Weave 호스트의 ~/.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",
          // 선택 사항이며, Agents 탭의 그룹화를 개선합니다.
          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로 설정하세요.

W&B Dedicated Cloud 또는 자체 호스팅 인스턴스

이 플러그인은 엔드포인트와 인증 처리를 Weave Node SDK에 위임합니다. Weave Python 및 Node SDK와 동일한 규칙에 따라 다음 환경 변수를 읽습니다:

변수	설명
`WANDB_BASE_URL`	W&B API 기본 URL. 기본값: `https://api.wandb.ai`. Dedicated Cloud 또는 자체 호스팅 설치 시 설정하세요.
`WF_TRACE_SERVER_URL`	전체 트레이스 서버 URL 재정의. Self-Managed 또는 프록시를 사용하는 설정에 사용하세요.

문제 해결

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

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

/weave status를 실행하세요. 라이프사이클이 disabled, config-error 또는 not-started이면 플러그인이 활성화되지 않은 것입니다. 게이트웨이 로그에서 weave: config.entity is required, weave: configuration error 또는 [weave] incompatible plugin SDK를 확인하세요.
게이트웨이 설정에서 diagnostics.enabled: false를 설정하지 않았는지 확인하세요. 이 필드는 true여야 합니다.
entity와 프로젝트가 확인 중인 Weave 프로젝트의 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인 경우에도 계속 작동합니다.

Weave로 트레이스 전송 오류

플러그인이 active하고 span을 생성 중이지만 Weave에 나타나지 않는 경우, 게이트웨이 로그에서 내보내기 오류를 확인하고 다음 table과 일치하는지 확인하세요.

증상	가장 가능성 있는 원인	해결 방법
`401` 또는 `403` from `trace.wandb.ai`	유효하지 않거나 범위가 제한된 API 키	키가 최신인지 확인하고 팀이 entity와 프로젝트를 소유하고 있는지 확인하세요. `wandb login`은 `~/.netrc`를 갱신합니다.
agents 엔드포인트에서 `404`	잘못된 base 또는 트레이스 서버 URL	Dedicated 설치의 경우 `WANDB_BASE_URL`을 설치 호스트로 설정하세요. Self-Managed 또는 프록시의 경우 `WF_TRACE_SERVER_URL`을 트레이스 서버 URL로 설정하세요.
연결 거부 또는 DNS 오류	DNS, 프록시 또는 방화벽	게이트웨이 호스트가 `trace.wandb.ai` (cloud) 또는 설치 호스트 (Dedicated)에 `443`로 도달할 수 있는지 확인하세요.

​사전 요구 사항

​플러그인 설치

​Weave에서 OpenClaw 트레이스 보기

​설정 레퍼런스

​W&B Dedicated Cloud 또는 자체 호스팅 인스턴스

​문제 해결

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

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

​Weave로 트레이스 전송 오류