> ## 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 플러그인
> 관측성과 디버깅을 위해 W&B Weave에서 OpenClaw 에이전트 세션을 추적하세요.
export const AgentLensBanner = ({href}) =>
This workflow is also available in CoreWeave Agent Lens. Agent Lens is the Forge experience built for tracing, monitoring, and analyzing AI agents, with automated insights into agent failures and user intents. It uses the same trace data as Weights & Biases Weave, so the traces you already send appear there with nothing to migrate.{' '}
{href ? 'See how to do this in Agent Lens' : 'Learn about Agent Lens'}.
;
Weave OpenClaw 플러그인은 OpenClaw 게이트웨이를 통해 실행되는 모든 에이전트 세션을 자동으로 트레이싱하고 구조화된 데이터를 W\&B Weave로 전송합니다. 이 플러그인은 애플리케이션 코드를 변경하지 않고도 모든 턴, 모델 Call, 도구 실행을 로깅합니다. 이러한 트레이스를 사용하여 세션을 디버깅하고, 도구 사용을 감사하고, run 전반의 비용과 지연 시간을 모니터링하세요.
이 가이드는 게이트웨이 뒤에서 실행되는 에이전트에 Weave 트레이싱을 활성화하려는 OpenClaw 게이트웨이 운영자를 위한 문서입니다. 플러그인 설치, 설정, 생성된 트레이스 확인, 일반적인 문제 해결 방법을 안내합니다.
이 플러그인은 OpenClaw 세션 데이터를 Weave로 전송합니다. 이 데이터에는 사용자 프롬프트, 모델 응답, 도구 입력 및 출력, 도구 결과, 대화 이력이 포함될 수 있습니다.
이 플러그인은 개인 식별 정보(PII) 제거 또는 민감한 데이터 마스킹을 구현하지 않습니다. 콘텐츠 캡처를 방지해야 한다면 플러그인 설정에서 `captureContent: false`를 설정하세요. 보안 또는 규정 준수 요구사항에 따라 이 데이터를 Weave로 전송할 수 없다면 이 플러그인을 설치하지 마세요.
사전 요구 사항
* [Node.js](https://nodejs.org/) v22.14 이상.
* 플러그인 API를 지원하는 [OpenClaw](https://openclaw.ai) `2026.4.25` 이상.
* CoreWeave Forge 계정 및 [API 키](https://forge.coreweave.com/settings#apikeys).
* 트레이스를 수신할 Weave 프로젝트 (`[YOUR-TEAM]/[YOUR-PROJECT]`).
플러그인 설치
다음 단계에 따라 플러그인을 설치하고 OpenClaw 게이트웨이에 등록한 후 트레이스가 Weave 프로젝트에 도달하는지 확인하세요.
```bash lines theme={"system"}
openclaw plugins install weave-openclaw
```
전체 이름인 `weave-openclaw`를 사용하세요 (`weave`만 사용하면 이 플러그인이 아닌 W\&B 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/wandb/[YOUR-TEAM]/[YOUR-PROJECT]/weave/`에 트레이스가 표시됩니다.
Weave에서 OpenClaw 트레이스 보기
플러그인이 활성화되면 각 에이전트 세션에서 Weights & Biases UI로 확인할 수 있는 트레이스가 생성됩니다. 에이전트 세션을 하나 이상 실행한 후 Weights & Biases UI에서 프로젝트를 여세요:
1. [Forge](https://forge.coreweave.com/wandb)로 이동하여 프로젝트를 선택하세요.
2. 사이드바 메뉴에서 **Agents**를 선택하세요.
3. **Conversations** 탭을 선택하여 프로젝트에 저장된 모든 에이전트 대화를 확인하세요.
4. 대화를 선택하여 전체 대화 트리를 확인하세요.
Agents 뷰에 대한 자세한 내용은 [에이전트 활동 보기](/ko/products/wandb/weave/guides/tracking/view-agent-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` string(지원되지만 권장하지 않음).
3. `WANDB_API_KEY` 환경 변수.
4. `wandb login`으로 생성된 Weave 호스트의 `~/.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",
// 선택 사항이며, 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](https://github.com/wandb/weave/tree/master/sdks/node)에 위임합니다. 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이 표시되지 않음
1. `/weave status`를 실행하세요. 라이프사이클이 `disabled`, `config-error` 또는 `not-started`이면 플러그인이 활성화되지 않은 것입니다. 게이트웨이 로그에서 `weave: config.entity is required`, `weave: configuration error` 또는 `[weave] incompatible plugin SDK`를 확인하세요.
2. 게이트웨이 설정에서 `diagnostics.enabled: false`를 설정하지 않았는지 확인하세요. 이 필드는 `true`여야 합니다.
3. entity와 프로젝트가 확인 중인 Weave 프로젝트의 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`인 경우에도 계속 작동합니다.
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`로 도달할 수 있는지 확인하세요. |
## Related topics
- [Codex 플러그인](/ko/products/wandb/weave/guides/integrations/agents/codex-harness.md)