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 인수, 그리고 도구 결과가 포함됩니다. 도구 결과에는 셸 명령어, 명령어 출력, 파일 내용이 포함됩니다. 이 데이터는 사용자의 Weave 인스턴스로 전송됩니다.PII 스크러빙과 민감한 데이터 마스킹은 구현되어 있지 않습니다. 구조, token 사용량, 모델, 타이밍만 전송하고 프롬프트, 코드, 출력은 전송하지 않으려면 WEAVE_CODEX_CAPTURE_CONTENT=0으로 설정하세요. 보안 또는 규정 준수 요구 사항 때문에 이 데이터를 Weave로 전송할 수 없다면, 이 플러그인을 설치하지 마세요.
패키지 설치
npm install -g weave-codex
자격 증명 및 프로젝트 설정
wandb login
export WEAVE_PROJECT="YOUR-TEAM/YOUR-PROJECT"
wandb login 대신 WANDB_API_KEY를 환경 변수로 직접 설정할 수도 있습니다. 전체 우선순위 규칙은 자격 증명 결정 순서를 참조하세요.Stop 훅 설치
그러면 ~/.codex/hooks.json에 Stop 훅이 병합됩니다. 각 Codex 턴이 완료되면 이 훅은 분리된 워커를 생성하여 세션별 커서 이후의 새 rollout 라인을 읽고, span을 재구성한 다음 Weave로 내보냅니다. Codex에서 훅 승인
Codex는 새로 추가된 훅을 신뢰되지 않는 것으로 표시하며, 승인하기 전까지는 실행하지 않습니다. 다음에 codex를 실행할 때 프롬프트가 표시되면 weave-codex 훅을 승인하세요.또는 프롬프트를 건너뛰려면 ~/.codex/config.toml에서 bypass_hook_trust = true를 설정하세요.모든 항목이 올바르게 설정되었는지 확인하려면 weave-codex status를 실행하세요.
- https://wandb.ai로 이동하여 프로젝트를 선택합니다.
- 사이드바에서 멀티턴 채팅 뷰와 에이전트별 버전 그룹화를 보려면 Agents를 선택하고, 원시 span 트리를 보려면 Traces를 선택합니다.
- 전체 턴 계층 구조를 확인할 대화를 선택합니다.
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도 포함됩니다. |
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_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 | 꺼짐 (오류는 항상 기록됨) |
- 환경 변수 (
WANDB_API_KEY, WEAVE_PROJECT)
~/.weave-codex/settings.json- Weave 호스트에 대한
~/.netrc 항목
W&B Dedicated Cloud 또는 자체 호스팅 인스턴스
WANDB_BASE_URL 값을 설치한 호스트로 설정하세요:
export WANDB_BASE_URL=https://YOUR-INSTANCE.wandb.io
✓(정상), ✗(조치 필요), 또는 -(아직 활성화되지 않았지만 오류는 아님)가 표시됩니다. Weave에 턴이 표시되지 않으면 collector 로그를 확인하세요:
cat ~/.weave-codex/logs/collector.log
~/.weave-codex/logs/collector.log의 collector 로그는 가장 중요한 진단 정보 소스입니다. debug 설정과 관계없이 오류는 항상 로깅됩니다.
Codex를 실행한 후에도 트레이스가 표시되지 않는 경우
weave-codex status를 실행하세요. 모든 검사가 통과하는지 확인하세요.- 훅이 신뢰된 상태인지 확인하세요. 처음 실행할 때 승인 prompt를 건너뛰었다면
codex를 다시 실행한 뒤 prompt가 표시되면 승인하세요. 또는 ~/.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로 트레이스를 전송할 때 발생하는 오류
| 증상 | 가장 가능성 높은 원인 | 해결 방법 |
|---|
trace.wandb.ai에서 401 또는 403 응답 반환 | 유효하지 않거나 범위가 제한된 API 키 | 키가 현재 유효한지, 그리고 팀이 해당 entity와 프로젝트를 소유하고 있는지 확인하세요. weave-codex status로 확인된 credential source도 점검하세요. |
| agents 엔드포인트에서 404 응답 반환 | 잘못된 base URL | Dedicated Cloud 설치에서는 WANDB_BASE_URL을 설치 호스트로 설정하세요. |
| 연결 거부 또는 DNS 오류 | DNS, 프록시 또는 방화벽 문제 | 호스트가 포트 443을 통해 trace.wandb.ai(cloud) 또는 설치 호스트(Dedicated Cloud)에 연결할 수 있는지 확인하세요. |
allow_managed_hooks_only가 설정되어 있으면 맞춤형 훅을 직접 추가할 수 없습니다. 이 경우 대체 트리거로 Codex의 notify 프로그램을 사용하세요:
# ~/.codex/config.toml
notify = ["sh", "/Users/you/.weave-codex/stop-hook.sh"]
~/.codex/hooks.json에서 weave-codex 항목만 제거합니다. 
