메인 콘텐츠로 건너뛰기
Weave for Agents는 공개 프리뷰 상태입니다. 정식 출시 전에 특성, API 및 Agents 뷰 UI가 변경될 수 있습니다.
Weave Codex 플러그인은 모든 Codex 턴을 자동으로 트레이스하고 구조화된 데이터를 W&B Weave로 전송합니다. Codex 워크플로를 전혀 변경하지 않아도 모든 모델 Call, 도구 실행, 추론 step이 로깅됩니다. 이 트레이스를 사용해 Session을 디버깅하고, 도구 사용을 감사하고, Runs 전반의 비용과 지연 시간을 모니터링하세요. 이 플러그인은 Codex 자체의 rollout Session 파일(~/.codex/sessions/**/rollout-*.jsonl)을 읽어 span을 재구성합니다. fire-and-forget Stop 훅을 통해 Codex의 핵심 경로와 분리되어 완전히 실행되므로, Codex가 네트워크 응답을 기다리는 일은 없습니다.
기본적으로 이 플러그인은 span 콘텐츠를 캡처합니다. 여기에는 프롬프트, 모델의 응답과 추론, 도구 Call 인수, 그리고 도구 결과가 포함됩니다. 도구 결과에는 셸 command, command 출력, 파일 내용이 포함됩니다. 이 데이터는 사용자의 Weave 인스턴스로 전송됩니다.PII 스크러빙과 민감한 데이터 마스킹은 구현되어 있지 않습니다. 구조, token 사용량, 모델, 타이밍만 전송하고 프롬프트, 코드, 출력은 전송하지 않으려면 WEAVE_CODEX_CAPTURE_CONTENT=0으로 설정하세요. 보안 또는 규정 준수 요구 사항 때문에 이 데이터를 Weave로 전송할 수 없다면, 이 플러그인을 설치하지 마세요.

​
사전 요구 사항

  • Node.js v20 이상
  • 훅 시스템을 지원하는 OpenAI Codex CLI
  • W&B 계정과 WANDB_API_KEY 환경 변수로 설정한 API 키
  • 트레이스를 수신할 Weave 프로젝트([YOUR-TEAM]/[YOUR-PROJECT])

​
플러그인 설치

1

패키지 설치

npm install -g weave-codex
2

자격 증명 및 프로젝트 설정

wandb login
export WEAVE_PROJECT="YOUR-TEAM/YOUR-PROJECT"
wandb login 대신 WANDB_API_KEY를 환경 변수로 직접 설정할 수도 있습니다. 전체 우선순위 규칙은 자격 증명 결정 순서를 참조하세요.
3

Stop 훅 설치

weave-codex install
그러면 ~/.codex/hooks.json에 Stop 훅이 병합됩니다. 각 Codex 턴이 완료되면 이 훅은 분리된 워커를 생성하여 세션별 커서 이후의 새 rollout 라인을 읽고, span을 재구성한 다음 Weave로 내보냅니다.
4

Codex에서 훅 승인

Codex는 새로 추가된 훅을 신뢰되지 않는 것으로 표시하며, 승인하기 전까지는 실행하지 않습니다. 다음에 codex를 실행할 때 프롬프트가 표시되면 weave-codex 훅을 승인하세요.또는 프롬프트를 건너뛰려면 ~/.codex/config.toml에서 bypass_hook_trust = true를 설정하세요.모든 항목이 올바르게 설정되었는지 확인하려면 weave-codex status를 실행하세요.
이제 Codex를 평소처럼 실행하면 완료된 각 턴이 약 1초 이내에 Weave에 표시됩니다.

​
Weave에서 Codex 트레이스 보기

Codex 세션을 하나 이상 실행한 후 Weave UI에서 프로젝트를 여세요:
  1. https://wandb.ai로 이동하여 프로젝트를 선택합니다.
  2. 사이드바에서 멀티턴 채팅 뷰와 에이전트별 버전 그룹화를 보려면 Agents를 선택하고, 원시 span 트리를 보려면 Traces를 선택합니다.
  3. 전체 턴 계층 구조를 확인할 대화를 선택합니다.
Agents 뷰에 대한 자세한 내용은 에이전트 활동 보기를 참조하세요. 플러그인은 GenAI semantic conventions를 따라 Codex 턴마다 OTEL 트레이스를 하나씩 내보냅니다:
Span생성 시점주요 속성
invoke_agent codex턴별(루트 span)에이전트 이름 또는 버전, gen_ai.conversation.id, 모델, 총 token 사용량, 사용자 프롬프트와 최종 응답(콘텐츠 캡처가 켜져 있는 경우)
chat <model>모델 Call별gen_ai.usage.* (입력, 출력, 캐시된, 추론 token), 종료 이유, server.address, 어시스턴트 출력(콘텐츠 캡처가 켜져 있는 경우)
execute_tool <name>도구 실행별gen_ai.tool.name, gen_ai.tool.call.id, 인수와 결과(콘텐츠 캡처가 켜져 있는 경우), 그리고 MCP Call에는 mcp.server.name도 포함됩니다.
Weave는 gen_ai.conversation.id를 사용해 Agents 뷰에서 여러 턴을 하나의 대화로 그룹화하며, 이 값은 모든 span에서 Codex 세션 ID로 설정됩니다. span Timestamp는 rollout 파일 Timestamp를 기준으로 소급 적용되므로, 기간은 실제 실행 시간을 반영합니다. 모든 속성이 GenAI semantic conventions를 따르므로, 트레이스는 모든 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_KEYwandb_api_key~/.netrc (wandb login을 통해)
Weave 프로젝트WEAVE_PROJECTweave_project없음 (필수, entity/project)
base URLWANDB_BASE_URLwandb_base_urlhttps://trace.wandb.ai
콘텐츠 캡처WEAVE_CODEX_CAPTURE_CONTENTcapture_contenttrue
디버그 로깅WEAVE_CODEX_DEBUGdebug꺼짐 (오류는 항상 기록됨)

​
자격 증명 결정 순서

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

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

Codex를 실행하기 전에 WANDB_BASE_URL 값을 설치한 호스트로 설정하세요: 
export WANDB_BASE_URL=https://YOUR-INSTANCE.wandb.io

​
플러그인 상태 확인

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

​
문제 해결

다음 섹션에서는 일반적인 문제와 이를 해결하는 방법을 설명합니다. ~/.weave-codex/logs/collector.log의 collector 로그는 가장 중요한 진단 정보 소스입니다. debug 설정과 관계없이 오류는 항상 로깅됩니다.

​
Codex를 실행한 후에도 트레이스가 표시되지 않는 경우

  1. weave-codex status를 실행하세요. 모든 검사가 통과하는지 확인하세요.
  2. 훅이 신뢰된 상태인지 확인하세요. 처음 실행할 때 승인 prompt를 건너뛰었다면 codex를 다시 실행한 뒤 prompt가 표시되면 승인하세요. 또는 ~/.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 로그에서 export 오류를 확인한 뒤 이 표와 대조하세요.
증상가장 가능성 높은 원인해결 방법
trace.wandb.ai에서 401 또는 403 응답 반환유효하지 않거나 범위가 제한된 API 키키가 현재 유효한지, 그리고 팀이 해당 entity와 프로젝트를 소유하고 있는지 확인하세요. weave-codex status로 확인된 credential source도 점검하세요.
agents 엔드포인트에서 404 응답 반환잘못된 base URLDedicated Cloud 설치에서는 WANDB_BASE_URL을 설치 호스트로 설정하세요.
연결 거부 또는 DNS 오류DNS, 프록시 또는 방화벽 문제호스트가 포트 443을 통해 trace.wandb.ai(cloud) 또는 설치 호스트(Dedicated Cloud)에 연결할 수 있는지 확인하세요.

​
훅 제한 환경

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

​
제거

weave-codex uninstall
이 작업은 ~/.codex/hooks.json에서 weave-codex 항목만 제거합니다.