` | 각 도구 실행마다 | `gen_ai.tool.name`, `gen_ai.tool.call.id` |
## 설정 레퍼런스
이 섹션은 `openclaw.json`의 `weave` 플러그인 항목에 대한 전체 설정 레퍼런스입니다.
`apiKey` 필드는 4가지 인증 소스를 지원하며, 다음 순서로 확인됩니다.
1. `source: "env"` 또는 `source: "file"`이 지정된 `SecretRef` 객체(아래 예시의 10번째 줄 참조)
2. 리터럴 `apiKey` string(지원되지만 권장되지는 않음)
3. `WANDB_API_KEY` 환경 변수
4. `wandb login`으로 채워진 Weave 호스트용 `~/.netrc` 항목
```json lines theme={null}
{
plugins: {
entries: {
weave: {
enabled: true,
config: {
entity: "YOUR-TEAM",
project: "YOUR-PROJECT",
// Reads WANDB_API_KEY from env if apiKey is omitted.
// SecretRef supports source: "env" or "file":
// { source: "env", provider: "default", id: "WANDB_API_KEY" }
// { source: "file", provider: "default", id: "/run/secrets/wandb" }
// Plain string is supported but discouraged.
apiKey: { source: "env", provider: "default", id: "WANDB_API_KEY" },
serviceName: "openclaw-agent",
// Optional, improves Agents tab grouping.
agentName: "my-agent",
agentVersion: "v1.0",
agentDescription: "What my agent does.",
// ON by default. Set to false for a hard off (compliance or
// retention policy). The plugin does not redact captured
// strings; scrub upstream if needed.
captureContent: true,
flushIntervalMs: 1000,
},
hooks: { allowConversationAccess: true },
},
},
},
}
```
`captureContent`의 기본값은 `true`입니다. `captureContent`가 `true`이면 플러그인은 입력 및 출력 메시지, 도구 인수, 그리고 도구 결과도 `gen_ai.input.messages` 및 `gen_ai.output.messages` payload 형식에 따라 함께 전송합니다. 플러그인은 서브에이전트, compaction 이벤트, 루프 감지, 재시도 시도, 그리고 컨텍스트 사이징을 추가 속성과 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 base URL. 기본값: `https://api.wandb.ai`. Dedicated Cloud 또는 자체 호스팅 설치의 경우 이 값을 설정하세요. |
| `WF_TRACE_SERVER_URL` | 전체 trace-server URL 재정의값입니다. Self-Managed 또는 프록시를 사용하는 설정에 사용하세요. |
## 문제 해결
트레이스가 Weave에 도달하지 않거나 content 필드가 비어 있으면, 가장 일반적인 원인을 진단하려면 아래 섹션을 참조하세요.
게이트웨이 로그는 `openclaw`를 실행하는 process의 터미널 출력이거나, 데몬으로 실행한 경우 프로세스 관리자의 로그 스트림입니다.
### 플러그인이 로드되었지만 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. 확인 중인 Weave 프로젝트의 URL 슬러그와 엔터티 및 프로젝트가 일치하는지 확인하세요. `/weave status`는 `project=[YOUR-TEAM]/[YOUR-PROJECT]`를 출력해야 합니다.
4. 인증 소스를 확인하세요. `/weave status`는 `auth=...`를 출력해야 합니다. `WANDB_API_KEY env`라고 표시되는데 키를 다른 환경 변수에 설정했다면, 플러그인이 잘못된 키를 읽고 있는 것입니다.
### span은 수신되지만 입력/출력 텍스트가 비어 있습니다
게이트웨이 로그에서 다음 내용을 확인하세요:
```text theme={null}
[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에서는 콘텐츠가 포함된 훅을 operator가 opt-in한 경우에만 사용할 수 있습니다. 설정에서 `plugins.entries.weave.hooks.allowConversationAccess: true`를 지정한 다음 게이트웨이를 다시 시작하세요. `span` 구조와 비용/사용 데이터는 훅이 아니라 진단 이벤트를 통해 전달되므로, `allowConversationAccess`가 `false`인 경우에도 계속 작동합니다.
### Weave로 트레이스를 전송할 때 발생하는 오류
플러그인이 활성화되어 span을 생성하고 있는데도 Weave에 표시되지 않으면, 게이트웨이 로그에서 내보내기 오류를 확인한 뒤 아래 표와 대조하세요.
| Symptom | Most likely cause | Fix |
| ------------------------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `trace.wandb.ai`에서 `401` 또는 `403` 반환 | 유효하지 않거나 범위가 제한된 API 키 | 키가 현재 사용 중인 키인지, 그리고 팀이 해당 entity와 프로젝트를 소유하고 있는지 확인하세요. `wandb login`을 실행하면 `~/.netrc`가 갱신됩니다. |
| agents endpoint에서 `404` 반환 | 잘못된 base URL 또는 trace-server URL | Dedicated 설치의 경우 `WANDB_BASE_URL`을 설치 호스트로 설정하세요. self-managed 또는 프록시 환경의 경우 `WF_TRACE_SERVER_URL`을 trace-server URL로 설정하세요. |
| 연결 거부 또는 DNS 오류 | DNS, 프록시 또는 방화벽 문제 | 게이트웨이 호스트가 `443` 포트에서 `trace.wandb.ai`(cloud) 또는 설치 호스트(Dedicated)에 연결할 수 있는지 확인하세요. |