> ## 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. # Codex 플러그인 > W&B Weave에서 Codex의 에이전트형 세션, LLM Call, 도구 실행을 트레이스하세요. 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 Codex 플러그인은 모든 Codex 턴을 자동으로 트레이스하고 구조화된 데이터를 W\&B Weave로 전송합니다. Codex 워크플로를 변경하지 않아도 모든 모델 Call, 도구 실행, 추론 단계가 로깅됩니다. 이러한 트레이스를 활용해 세션을 디버깅하고, 도구 사용 내역을 감사하고, 여러 run에 걸친 비용과 지연 시간을 모니터링하세요. 이 플러그인은 Codex가 자체적으로 기록하는 rollout 세션 파일(`~/.codex/sessions/**/rollout-*.jsonl`)을 읽어 span을 재구성합니다. 완료를 기다리지 않는(fire-and-forget) Stop 훅을 통해 Codex의 핵심 경로 밖에서 완전히 독립적으로 실행되므로, Codex가 네트워크 응답을 기다릴 일이 없습니다. 기본적으로 이 플러그인은 span 내용, 즉 프롬프트, 모델의 응답과 추론, 도구 호출 인수, 도구 결과를 캡처합니다. 도구 결과에는 셸 명령어, 명령어 출력, 파일 내용이 포함됩니다. 이 데이터는 사용자의 Weave 인스턴스로 전송됩니다. PII 제거 및 민감 데이터 마스킹 기능은 제공되지 않습니다. 프롬프트, 코드, 출력을 제외하고 구조, 토큰 사용량, 모델, 소요 시간 정보만 전송하려면 `WEAVE_CODEX_CAPTURE_CONTENT=0`을 설정하세요. 보안 또는 규정 준수 요구 사항상 이 데이터를 Weave로 전송할 수 없다면 이 플러그인을 설치하지 마세요.

사전 요구 사항

* [Node.js](https://nodejs.org/) v20 이상 * 훅 시스템을 지원하는 [OpenAI Codex CLI](https://github.com/openai/codex) * CoreWeave Forge 계정과 `WANDB_API_KEY` 환경 변수로 설정된 [API 키](https://forge.coreweave.com/settings#apikeys) * 트레이스를 수신할 Weave 프로젝트(`[YOUR-TEAM]/[YOUR-PROJECT]`)

플러그인 설치

```bash lines theme={"system"} npm install -g weave-codex ``` ```bash lines theme={"system"} wandb login export WEAVE_PROJECT="YOUR-TEAM/YOUR-PROJECT" ``` `wandb login`을 사용하는 대신 `WANDB_API_KEY`를 환경 변수로 직접 설정할 수도 있습니다. 전체 우선순위 규칙은 [자격 증명 확인 순서](#credential-resolution-order)를 참조하세요. ```bash lines theme={"system"} weave-codex install ``` 이 명령은 `~/.codex/hooks.json`에 Stop 훅을 병합합니다. Codex 턴이 완료될 때마다 훅이 분리된(detached) 워커를 생성합니다. 이 워커는 세션별 커서 이후에 추가된 rollout 라인을 읽어 span을 재구성한 뒤 Weave로 내보냅니다. Codex는 새로 추가된 훅을 신뢰할 수 없는 훅으로 표시하며, 사용자가 승인하기 전까지는 실행하지 않습니다. 다음에 `codex`를 실행할 때 승인 메시지가 표시되면 `weave-codex` 훅을 승인하세요. 또는 `~/.codex/config.toml`에 `bypass_hook_trust = true`를 설정하면 승인 메시지를 건너뛸 수 있습니다. `weave-codex status`를 실행하여 모든 항목이 올바르게 설정되었는지 확인하세요. 이제 Codex를 평소처럼 실행하면 완료된 턴이 약 1초 이내에 Weave에 표시됩니다.

Weave에서 Codex 트레이스 보기

Codex 세션을 한 번 이상 실행한 후 Weights & Biases UI에서 프로젝트를 여세요. 1. [Forge](https://forge.coreweave.com/wandb)로 이동하여 프로젝트를 선택하세요. 2. 사이드바에서 멀티턴 채팅 뷰와 에이전트별 버전 그룹화를 보려면 **Agents**를, 원시 span 트리를 보려면 **Traces**를 선택하세요. 3. 대화를 선택하면 전체 턴 계층 구조를 살펴볼 수 있습니다. Agents 뷰에 대한 자세한 내용은 [에이전트 활동 보기](/ko/products/wandb/weave/guides/tracking/view-agent-activity)를 참조하세요. 플러그인은 [GenAI 시맨틱 규칙](https://opentelemetry.io/docs/specs/semconv/gen-ai/)에 따라 Codex 턴마다 OTEL 트레이스를 하나씩 내보냅니다. | Span | 내보내는 시점 | 주요 속성 | | - | - | - | | `invoke_agent codex` | 턴마다(루트 span) | 에이전트 이름 또는 버전, `gen_ai.conversation.id`, 모델, 합산된 토큰 사용량, 사용자 프롬프트 및 최종 응답(콘텐츠 캡처가 켜져 있는 경우) | | `chat ` | 모델 Call마다 | `gen_ai.usage.*`(입력, 출력, 캐시된 토큰, 추론 토큰), 종료 사유, `server.address`, assistant 출력(콘텐츠 캡처가 켜져 있는 경우) | | `execute_tool ` | 도구 실행마다 | `gen_ai.tool.name`, `gen_ai.tool.call.id`, 인수 및 결과(콘텐츠 캡처가 켜져 있는 경우). MCP Call에는 `mcp.server.name`도 포함됨 | Weave는 모든 span에 Codex 세션 ID로 설정되는 `gen_ai.conversation.id`를 기준으로 Agents 뷰에서 턴을 하나의 대화로 묶습니다. Span 타임스탬프는 rollout 파일의 타임스탬프를 기준으로 소급 설정되므로, 소요 시간에 실제 실행 시간이 그대로 반영됩니다. 모든 속성이 GenAI 시맨틱 규칙을 따르므로, 트레이스는 OTEL과 호환되는 백엔드라면 어디서든 렌더링할 수 있습니다.

알려진 제한 사항

* `codex`(대화형 TUI) 및 `codex exec` 명령어를 지원합니다. `codex mcp` 및 `app-server` 명령어는 훅을 트리거하지 않으므로 지원 대상에 포함되지 않습니다. * 생성된 서브에이전트는 `spawn_agent` 도구 Call로만 표시됩니다. 서브에이전트 자체의 모델 Call과 도구 실행은 캡처되지 않습니다. * Stop 훅은 중단되거나 오류가 발생한 턴에서는 실행되지 않으므로 이러한 턴은 캡처되지 않습니다.

설정 레퍼런스

이 섹션에서는 플러그인 동작을 사용자 지정하는 데 사용할 수 있는 설정을 나열합니다. 설정 파일과 런타임 파일은 `~/.weave-codex/`에 저장되며, 여기에는 `settings.json`, 훅 shim, 세션별 커서, 로그 파일(`logs/collector.log`)이 포함됩니다. | 설정 | 환경 변수 | `settings.json` 키 | 기본값 | | - | - | - | - | | W\&B API 키 | `WANDB_API_KEY` | `wandb_api_key` | `~/.netrc` (`wandb login`으로 설정) | | Weave 프로젝트 | `WEAVE_PROJECT` | `weave_project` | 없음 (필수, `entity/project`) | | Base URL | `WANDB_BASE_URL` | `wandb_base_url` | `https://trace.wandb.ai` | | 콘텐츠 캡처 | `WEAVE_CODEX_CAPTURE_CONTENT` | `capture_content` | `true` | | 디버그 로깅 | `WEAVE_CODEX_DEBUG` | `debug` | 꺼짐 (오류는 항상 로깅됨) |

자격 증명 확인 순서

플러그인은 다음 순서로 자격 증명을 확인합니다. 1. 환경 변수(`WANDB_API_KEY`, `WEAVE_PROJECT`) 2. `~/.weave-codex/settings.json` 3. `~/.netrc`의 Weave 호스트 항목

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

Codex를 실행하기 전에 `WANDB_BASE_URL`을 사용 중인 설치 호스트로 설정하세요. ```bash lines theme={"system"} export WANDB_BASE_URL=https://YOUR-INSTANCE.wandb.io ```

플러그인 상태 확인

다음 CLI 명령어로 플러그인 상태를 확인하거나 문제를 해결할 수 있습니다. ```bash lines theme={"system"} weave-codex status ``` 각 줄에는 `✓`(정상), `✗`(조치 필요) 또는 `-`(아직 활성화되지 않았지만 오류는 아님)가 표시됩니다. Weave에 턴이 표시되지 않으면 collector 로그를 확인하세요. ```bash lines theme={"system"} cat ~/.weave-codex/logs/collector.log ```

문제 해결

다음 섹션에서는 자주 발생하는 문제와 해결 방법을 설명합니다. 문제를 진단할 때는 주로 `~/.weave-codex/logs/collector.log`에 있는 collector 로그를 확인하세요. 플러그인은 `debug` 설정과 관계없이 항상 오류를 로깅합니다.

Codex 실행 후 트레이스가 표시되지 않음

1. `weave-codex status`를 실행하고 모든 검사를 통과하는지 확인하세요. 2. 훅이 신뢰됨으로 설정되어 있는지 확인하세요. 처음 실행할 때 승인 프롬프트를 건너뛰었다면 `codex`를 다시 실행한 후 메시지가 표시될 때 승인하거나, `~/.codex/config.toml`에 `bypass_hook_trust = true`를 설정하세요. 3. `WEAVE_PROJECT`가 유효한 `entity/project` 슬러그로 설정되어 있는지 확인하세요. `weave-codex status`를 실행하면 최종 적용된 프로젝트가 출력됩니다. 4. 인증 소스를 확인하세요. `weave-codex status`를 실행하면 최종 적용된 자격 증명 소스가 출력됩니다. `WANDB_API_KEY env`로 표시되는데 키를 다른 곳에 설정했다면 플러그인이 잘못된 값을 읽고 있는 것입니다.

턴은 표시되지만 입력/출력 텍스트가 비어 있는 경우

콘텐츠 캡처가 비활성화되어 있을 수 있습니다. `WEAVE_CODEX_CAPTURE_CONTENT`가 `0`으로 설정되어 있지 않은지, `~/.weave-codex/settings.json`의 `capture_content`가 `false`로 설정되어 있지 않은지 확인하세요.

Weave로 트레이스를 전송할 때 발생하는 오류

플러그인이 활성 상태이고 span도 생성되는데 Weave에 표시되지 않는다면, collector 로그에서 내보내기 오류를 찾아 아래 표와 대조하세요. | 증상 | 가장 유력한 원인 | 해결 방법 | | - | - | - | | `trace.wandb.ai`에서 401 또는 403 반환 | API 키가 유효하지 않거나 범위가 제한됨 | 키가 현재 유효한지, 그리고 팀이 해당 entity와 프로젝트를 소유하고 있는지 확인하세요. `weave-codex status`를 실행해 실제로 적용된 자격 증명 소스를 확인하세요. | | 에이전트 엔드포인트에서 404 반환 | 잘못된 base URL | Dedicated Cloud 설치 환경에서는 `WANDB_BASE_URL`을 해당 설치 호스트로 설정하세요. | | 연결 거부 또는 DNS 오류 | DNS, 프록시 또는 방화벽 문제 | 호스트가 443 포트를 통해 `trace.wandb.ai`(클라우드) 또는 설치 호스트(Dedicated Cloud)에 연결할 수 있는지 확인하세요. |

훅이 잠긴 환경

Codex 설정에 `allow_managed_hooks_only`가 설정되어 있으면 맞춤형 훅을 직접 추가할 수 없습니다. 이 경우 Codex의 `notify` 프로그램을 대체 트리거로 사용하세요. ```toml lines theme={"system"} # ~/.codex/config.toml notify = ["sh", "/Users/you/.weave-codex/stop-hook.sh"] ```

제거

```bash lines theme={"system"} weave-codex uninstall ``` 이 명령은 `~/.codex/hooks.json`에서 `weave-codex` 항목만 제거합니다. ## Related topics - [Claude Code 플러그인](/ko/products/wandb/weave/guides/integrations/agents/claude-code-harness.md)