OpenClaw 플러그인

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

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

사전 요구 사항

Node.js v24.16 이상 또는 v26.1 이상. Node.js v25는 지원되지 않습니다.
OpenClaw 2026.9.8 이상
CoreWeave Forge 계정 및 API 키
트레이스를 수신할 Agent Lens 프로젝트([YOUR-TEAM]/[YOUR-PROJECT])

플러그인 설치

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

패키지 설치

이 플러그인은 Weave 가이드에서 설명하는 weave-openclaw 플러그인과는 별개입니다. 이 플러그인의 ID는 forge이며, 설정 항목과 상태 명령어에도 이 이름을 사용합니다. weave-openclaw를 이미 설치했다면 두 플러그인이 트레이스를 중복으로 보내지 않도록, 이 플러그인을 설치하기 전에 먼저 비활성화하고 제거하세요. 설정은 plugins.entries.weave에서 plugins.entries.forge로 옮기고, plugins.allow의 weave를 forge로 바꾸세요. 설정 필드와 사용자 인증 정보는 그대로 사용할 수 있습니다.

openclaw plugins install clawhub:@coreweave/forge-agent-lens-for-openclaw

OpenClaw 게이트웨이는 설정을 통해 플러그인을 로드하므로 애플리케이션 코드에서 임포트할 필요가 없습니다.

API 키 설정

[YOUR-API-KEY]를 API 키로 바꾼 다음 export하세요.

export WANDB_API_KEY="[YOUR-API-KEY]"

OpenClaw는 ~/.openclaw/.env에서도 WANDB_API_KEY를 로드합니다. 키를 지정하는 다른 방법은 구성 참조를 확인하세요.

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

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

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

hooks.allowConversationAccess를 true로 설정하면 OpenClaw가 대화 내용을 다루는 플러그인 훅인 llm_input과 agent_end를 실행합니다. 이 설정이 없으면 모델 Call 스팬에 프롬프트 텍스트나 시스템 지침이 포함되지 않습니다. 다만 트레이스 구조, 도구 호출, 토큰 및 비용 합계는 진단 이벤트를 통해 계속 수집됩니다.OpenClaw의 최상위 diagnostics.enabled 설정은 기본값이 true입니다. 이 값을 false로 설정하면 플러그인이 사용하는 진단 이벤트가 꺼져 트레이스가 전송되지 않습니다.

게이트웨이 재시작 및 확인

OpenClaw 게이트웨이를 재시작하세요.

openclaw gateway restart

그런 다음 아무 OpenClaw 채팅 화면에서 /forge status를 실행하세요. 플러그인 상태가 running으로 표시되면 정상적으로 실행 중입니다. 첫 에이전트 run을 실행하고 몇 초 이내에 https://forge.coreweave.com/agent-lens/[YOUR-TEAM]/[YOUR-PROJECT] 의 Agent Lens 프로젝트에 트레이스가 표시됩니다. 상태 출력의 dashboard 줄에는 동일한 트레이스 데이터를 공유하는 Weave 프로젝트 링크가 표시됩니다.

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에 있는 forge 플러그인 항목의 전체 구성 참조를 설명합니다. entity와 project만 필수입니다. 플러그인은 다음 순서대로 API 키를 찾습니다.

플러그인 설정의 apiKey 필드(SecretRef 객체 또는 리터럴 문자열). 보안상 리터럴 문자열은 사용하지 않는 것이 좋습니다.
WANDB_API_KEY 환경 변수. OpenClaw는 이 변수를 ~/.openclaw/.env에서도 불러옵니다.
wandb login으로 생성되는 api.wandb.ai의 ~/.netrc 항목

env SecretRef는 별도의 설정 없이 바로 사용할 수 있습니다. file 또는 exec SecretRef를 사용하려면 게이트웨이 설정에 해당하는 secrets.providers 항목이 있어야 합니다. 자세한 내용은 OpenClaw 시크릿 관리를 참조하세요.

{
  plugins: {
    entries: {
      forge: {
        enabled: true,
        config: {
          entity: "YOUR-TEAM",
          project: "YOUR-PROJECT",
          // apiKey를 생략하면 환경 변수에서 WANDB_API_KEY를 읽습니다.
          // SecretRef는 source: "env", "file", "exec"를 지원합니다. "env"
          // 소스는 provider: "default"와 함께 동작합니다. "file" 및 "exec"
          // 소스에는 일치하는 secrets.providers 항목이 필요합니다.
          // 일반 문자열도 사용할 수 있지만 권장하지 않습니다.
          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,
          // 플러그인이 트레이스를 전송하는 주기(밀리초)입니다. 최솟값은 1000입니다.
          flushIntervalMs: 1000,
        },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}

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

문제 해결

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

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

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

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

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

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

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

Agent Lens로 스팬 전송 시 발생하는 오류

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

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

플러그인 관리

다음 명령어를 사용하여 플러그인을 업데이트, 비활성화, 활성화 또는 제거할 수 있습니다.

openclaw plugins update forge
openclaw plugins disable forge
openclaw plugins enable forge
openclaw plugins uninstall forge

Agent Lens

가이드

인테그레이션

레퍼런스

사전 요구 사항

플러그인 설치

Agent Lens에서 OpenClaw 트레이스 보기

구성 참조

문제 해결

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

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

Agent Lens로 스팬 전송 시 발생하는 오류

플러그인 관리

​사전 요구 사항

​플러그인 설치

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

​구성 참조

​문제 해결

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

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

​Agent Lens로 스팬 전송 시 발생하는 오류

​플러그인 관리

사전 요구 사항

플러그인 설치

Agent Lens에서 OpenClaw 트레이스 보기

구성 참조

문제 해결

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

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

Agent Lens로 스팬 전송 시 발생하는 오류

플러그인 관리