~/.codex/sessions/**/rollout-*.jsonl)을 읽어 span을 재구성합니다. 완료를 기다리지 않는(fire-and-forget) Stop 훅을 통해 Codex의 핵심 경로 밖에서 완전히 독립적으로 실행되므로, Codex가 네트워크 응답을 기다릴 일이 없습니다.
사전 요구 사항
- Node.js v20 이상
- 훅 시스템을 지원하는 OpenAI Codex CLI
- CoreWeave Forge 계정과
WANDB_API_KEY환경 변수로 설정된 API 키 - 트레이스를 수신할 Weave 프로젝트(
[YOUR-TEAM]/[YOUR-PROJECT])
플러그인 설치
1
패키지 설치
2
자격 증명 및 프로젝트 설정
wandb login을 사용하는 대신 WANDB_API_KEY를 환경 변수로 직접 설정할 수도 있습니다. 전체 우선순위 규칙은 자격 증명 확인 순서를 참조하세요.3
Stop 훅 설치
~/.codex/hooks.json에 Stop 훅을 병합합니다. Codex 턴이 완료될 때마다 훅이 분리된(detached) 워커를 생성합니다. 이 워커는 세션별 커서 이후에 추가된 rollout 라인을 읽어 span을 재구성한 뒤 Weave로 내보냅니다.4
Codex에서 훅 승인
Codex는 새로 추가된 훅을 신뢰할 수 없는 훅으로 표시하며, 사용자가 승인하기 전까지는 실행하지 않습니다. 다음에
codex를 실행할 때 승인 메시지가 표시되면 weave-codex 훅을 승인하세요.또는 ~/.codex/config.toml에 bypass_hook_trust = true를 설정하면 승인 메시지를 건너뛸 수 있습니다.weave-codex status를 실행하여 모든 항목이 올바르게 설정되었는지 확인하세요.Weave에서 Codex 트레이스 보기
Codex 세션을 한 번 이상 실행한 후 Weights & Biases UI에서 프로젝트를 여세요.- Forge로 이동하여 프로젝트를 선택하세요.
- 사이드바에서 멀티턴 채팅 뷰와 에이전트별 버전 그룹화를 보려면 Agents를, 원시 span 트리를 보려면 Traces를 선택하세요.
- 대화를 선택하면 전체 턴 계층 구조를 살펴볼 수 있습니다.
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)이 포함됩니다.
자격 증명 확인 순서
플러그인은 다음 순서로 자격 증명을 확인합니다.- 환경 변수(
WANDB_API_KEY,WEAVE_PROJECT) ~/.weave-codex/settings.json~/.netrc의 Weave 호스트 항목
W&B Dedicated Cloud 또는 자체 호스팅 인스턴스
Codex를 실행하기 전에WANDB_BASE_URL을 사용 중인 설치 호스트로 설정하세요.
플러그인 상태 확인
다음 CLI 명령어로 플러그인 상태를 확인하거나 문제를 해결할 수 있습니다.✓(정상), ✗(조치 필요) 또는 -(아직 활성화되지 않았지만 오류는 아님)가 표시됩니다. Weave에 턴이 표시되지 않으면 collector 로그를 확인하세요.
문제 해결
다음 섹션에서는 자주 발생하는 문제와 해결 방법을 설명합니다. 문제를 진단할 때는 주로~/.weave-codex/logs/collector.log에 있는 collector 로그를 확인하세요. 플러그인은 debug 설정과 관계없이 항상 오류를 로깅합니다.
Codex 실행 후 트레이스가 표시되지 않음
weave-codex status를 실행하고 모든 검사를 통과하는지 확인하세요.- 훅이 신뢰됨으로 설정되어 있는지 확인하세요. 처음 실행할 때 승인 프롬프트를 건너뛰었다면
codex를 다시 실행한 후 메시지가 표시될 때 승인하거나,~/.codex/config.toml에bypass_hook_trust = true를 설정하세요. WEAVE_PROJECT가 유효한entity/project슬러그로 설정되어 있는지 확인하세요.weave-codex status를 실행하면 최종 적용된 프로젝트가 출력됩니다.- 인증 소스를 확인하세요.
weave-codex status를 실행하면 최종 적용된 자격 증명 소스가 출력됩니다.WANDB_API_KEY env로 표시되는데 키를 다른 곳에 설정했다면 플러그인이 잘못된 값을 읽고 있는 것입니다.
턴은 표시되지만 입력/출력 텍스트가 비어 있는 경우
콘텐츠 캡처가 비활성화되어 있을 수 있습니다.WEAVE_CODEX_CAPTURE_CONTENT가 0으로 설정되어 있지 않은지, ~/.weave-codex/settings.json의 capture_content가 false로 설정되어 있지 않은지 확인하세요.
Weave로 트레이스를 전송할 때 발생하는 오류
플러그인이 활성 상태이고 span도 생성되는데 Weave에 표시되지 않는다면, collector 로그에서 내보내기 오류를 찾아 아래 표와 대조하세요.훅이 잠긴 환경
Codex 설정에allow_managed_hooks_only가 설정되어 있으면 맞춤형 훅을 직접 추가할 수 없습니다. 이 경우 Codex의 notify 프로그램을 대체 트리거로 사용하세요.
제거
~/.codex/hooks.json에서 weave-codex 항목만 제거합니다.