> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenClaw 플러그인
> 관측성 확보와 디버깅을 위해 Agent Lens에서 OpenClaw 에이전트 세션을 추적하세요.
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](https://nodejs.org/) v22.14 이상
* 플러그인 API를 지원하는 [OpenClaw](https://openclaw.ai) `2026.4.25` 이상
* CoreWeave Forge 계정 및 [API 키](https://forge.coreweave.com/settings#apikeys)
* 트레이스를 수신할 Agent Lens 프로젝트(`[YOUR-TEAM]/[YOUR-PROJECT]`)
플러그인 설치
다음 단계에 따라 플러그인을 설치하고 OpenClaw 게이트웨이에 등록한 다음, 트레이스가 Agent Lens 프로젝트에 전달되는지 확인하세요.
```bash lines theme={"system"}
openclaw plugins install weave-openclaw
```
전체 이름인 `weave-openclaw`를 사용하세요(`weave`만 입력하면 이 플러그인이 아니라 Weave SDK를 가리킵니다). OpenClaw 게이트웨이는 설정을 통해 플러그인을 로드하므로 애플리케이션 코드에서 임포트할 필요가 없습니다.
기본 설정 파일 위치는 `~/.openclaw/openclaw.json`입니다(주석과 후행 쉼표를 허용하는 JSON5 형식). 아직 설정 파일이 없다면 `openclaw onboard`를 실행하여 기본 파일을 생성하세요.
`[YOUR-TEAM]`과 `[YOUR-PROJECT]`를 사용 중인 프로젝트에 맞게 변경하세요.
```json lines theme={"system"}
{
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에서 프로젝트를 여세요.
1. [CoreWeave Forge](https://forge.coreweave.com)로 이동하여 제품 메뉴에서 Agent Lens를 선택한 다음, 사이드 메뉴 상단의 프로젝트 선택기에서 프로젝트를 선택하세요.
2. 사이드 메뉴에서 **Conversations**를 선택하세요.
3. **Conversations** 탭을 선택하면 프로젝트에 저장된 모든 에이전트 대화를 볼 수 있습니다.
4. 대화를 선택하면 전체 대화 트리를 살펴볼 수 있습니다.
Conversations 탭에 대한 자세한 내용은 [에이전트 활동 보기](/ko/products/agent-lens/conversations/view-activity)를 참조하세요.
플러그인은 [OpenTelemetry (OTel) GenAI 시맨틱 규칙](https://opentelemetry.io/docs/specs/semconv/gen-ai/)에 따라 span을 내보냅니다.
| Span | 내보내는 시점 | 주요 속성 |
| - | - | - |
| `invoke_agent ` | 에이전트 run마다 | `gen_ai.agent.name`, `gen_ai.conversation.id`, 누적 비용, 토큰 사용량 |
| `chat ` | 모델 Call마다 | `gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` |
| `execute_tool ` | 도구 실행마다 | `gen_ai.tool.name`, `gen_ai.tool.call.id` |
설정 레퍼런스
이 섹션에서는 `openclaw.json`에 있는 `weave` 플러그인 항목의 전체 설정 레퍼런스를 설명합니다.
`apiKey` 필드는 네 가지 인증 소스를 지원하며, 다음 순서대로 확인됩니다.
1. `source: "env"` 또는 `source: "file"`이 지정된 `SecretRef` 객체(아래 예시의 10번째 줄 참조)
2. 리터럴 `apiKey` 문자열(지원되지만 권장하지 않음)
3. `WANDB_API_KEY` 환경 변수
4. `wandb login`으로 생성되는 Agent Lens 호스트의 `~/.netrc` 항목
```json lines theme={"system"}
{
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이 표시되지 않는 경우
1. `/weave status`를 실행하세요. lifecycle이 `disabled`, `config-error` 또는 `not-started`이면 플러그인이 활성화되지 않은 것입니다. 게이트웨이 로그에 `weave: config.entity is required`, `weave: configuration error` 또는 `[weave] incompatible plugin SDK` 메시지가 있는지 확인하세요.
2. 게이트웨이 설정에 `diagnostics.enabled: false`가 설정되어 있지 않은지 확인하세요. 이 필드는 `true`여야 합니다.
3. entity와 프로젝트가 현재 확인 중인 Agent Lens 프로젝트의 URL 슬러그와 일치하는지 확인하세요. `/weave status`를 실행하면 `project=[YOUR-TEAM]/[YOUR-PROJECT]`가 출력되어야 합니다.
4. 인증 소스를 확인하세요. `/weave status`를 실행하면 `auth=...`가 출력되어야 합니다. 출력이 `WANDB_API_KEY env`인데 키를 다른 환경 변수에 설정했다면 플러그인이 잘못된 키를 읽고 있는 것입니다.
span은 수집되지만 입력/출력 텍스트가 비어 있는 경우
게이트웨이 로그에서 다음 내용을 확인하세요.
```text theme={"system"}
[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`에 연결할 수 있는지 확인하세요. |