~/.codex/sessions/**/rollout-*.jsonl)을 읽어 span을 재구성합니다. 완료를 기다리지 않는(fire-and-forget) Stop 훅을 통해 Codex의 핵심 실행 경로와 완전히 분리되어 동작하므로, Codex가 네트워크 응답을 기다리는 일은 없습니다.
이 플러그인은 Weights & Biases Weave 플러그인입니다. CoreWeave Forge 버전은 아직 제공되지 않습니다. Agent Lens와 Weave는 동일한 트레이스 데이터를 공유하므로, 플러그인이 전송한 트레이스는 Agent Lens에 표시됩니다.
사전 요구 사항
- Node.js v20 이상
- 훅 시스템을 지원하는 OpenAI Codex CLI
- CoreWeave Forge 계정 및
WANDB_API_KEY환경 변수로 설정한 API 키 - 트레이스를 수신할 Agent Lens 프로젝트(
[YOUR-TEAM]/[YOUR-PROJECT])
플러그인 설치
1
패키지 설치
2
자격 증명 및 프로젝트 설정
wandb login을 사용하는 대신 WANDB_API_KEY를 환경 변수로 직접 설정할 수도 있습니다. 전체 우선순위 규칙은 자격 증명 확인 순서를 참조하세요.3
Stop 훅 설치
~/.codex/hooks.json에 Stop 훅을 병합합니다. Codex 턴이 완료될 때마다 훅이 백그라운드에서 독립적으로 실행되는(detached) 워커를 생성합니다. 이 워커는 세션별 커서 이후에 추가된 rollout 줄을 읽어 span을 재구성한 뒤 Agent Lens로 내보냅니다.4
Codex에서 훅 승인
Codex는 새로 추가된 훅을 신뢰할 수 없는 훅으로 표시하며, 승인하기 전까지는 실행하지 않습니다. 다음에
codex를 실행할 때 승인 메시지가 표시되면 weave-codex 훅을 승인하세요.또는 ~/.codex/config.toml에 bypass_hook_trust = true를 설정하면 승인 메시지를 건너뛸 수 있습니다.weave-codex status를 실행하여 모든 항목이 올바르게 설정되었는지 확인하세요.Agent Lens에서 Codex 트레이스 보기
Codex 세션을 한 번 이상 실행한 후 Agent Lens UI에서 프로젝트를 여세요.- CoreWeave Forge로 이동하여 제품 메뉴에서 Agent Lens를 선택한 다음, 사이드 메뉴 상단의 프로젝트 선택기에서 프로젝트를 선택하세요.
- 사이드 메뉴에서 Conversations를 선택하세요.
- 대화를 선택하면 전체 턴 계층 구조를 확인할 수 있습니다.
Agent Lens는
gen_ai.conversation.id를 사용해 Conversations 탭에서 턴을 하나의 대화로 묶습니다. 이 값은 모든 span에서 Codex 세션 ID로 설정됩니다. 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의 Agent Lens 호스트 항목
플러그인 상태 확인
다음 CLI 명령어로 플러그인 상태를 확인하거나 문제를 해결할 수 있습니다.✓(정상), ✗(조치 필요) 또는 -(아직 활성화되지 않았으나 오류 아님) 중 하나가 표시됩니다. Agent Lens에 턴이 표시되지 않으면 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로 설정되어 있지 않은지 확인하세요.
Agent Lens로 트레이스 전송 시 발생하는 오류
플러그인이 활성 상태이고 span도 생성되지만 Agent Lens에 표시되지 않는다면, collector 로그에서 내보내기 오류를 찾아 아래 표와 비교해 보세요.훅이 잠긴 환경
Codex 설정에allow_managed_hooks_only가 지정되어 있으면 맞춤형 훅을 직접 추가할 수 없습니다. 이 경우 Codex의 notify 프로그램을 대체 트리거로 사용하세요.
제거
~/.codex/hooks.json에서 weave-codex 항목만 제거합니다.