~/.codex/sessions/**/rollout-*.jsonl)을 읽어 스팬을 재구성합니다. 턴이 종료되면 Stop 훅이 분리된 수집기를 시작하므로 Codex가 네트워크 작업을 기다릴 필요가 없습니다. 동일한 Codex 세션에 속한 턴은 대화 ID를 공유하므로 Agent Lens에서 하나의 대화로 표시됩니다.
사전 요구 사항
- macOS 또는 Linux. Windows는 지원되지 않습니다.
- Node.js v20.6 이상.
- 훅과 롤아웃 로깅이 활성화된 OpenAI Codex CLI.
codex --ephemeral은 롤아웃 파일을 기록하지 않으므로 지원되지 않습니다. - CoreWeave Forge 계정 및 Forge API 키.
- 트레이스를 수신할 Agent Lens 프로젝트(
[YOUR-TEAM]/[YOUR-PROJECT]).
플러그인 설치
1
패키지 설치
이 플러그인은 Weave 가이드에서 설명하는
weave-codex 플러그인과는 별개입니다. 이 플러그인의 패키지는 @coreweave/forge-agent-lens-for-codex이며, 명령어, 환경 변수, 설정 디렉터리에는 forge-agent-lens-for-codex 및 FORGE_ 이름을 사용합니다. weave-codex를 이미 설치했다면 두 플러그인이 트레이스를 중복으로 전송하지 않도록, 이 플러그인을 설치하기 전에 weave-codex uninstall과 npm uninstall -g weave-codex를 실행하세요. FORGE_TRACE_PROJECT에는 WEAVE_PROJECT에 사용했던 값을 설정하세요. 이 플러그인은 weave-codex 설정을 읽지 않습니다.2
프로젝트 및 API 키 설정
[YOUR-TEAM]/[YOUR-PROJECT]를 Agent Lens 프로젝트로, [YOUR-API-KEY]를 API 키로 바꾼 다음 export하세요.WANDB_API_KEY를 설정하는 대신 wandb login을 실행해도 됩니다. 플러그인이 각 설정 값을 결정하는 방식은 구성 참조를 참조하세요.3
Stop 훅 설치
~/.codex/hooks.json에 Stop 훅을 병합하고, 원본 파일은 최초 1회에 한해 hooks.json.bak으로 백업합니다. 또한 기존 Codex 세션은 건너뛰므로 설치 이후에 실행한 턴만 Agent Lens로 전송됩니다. 이전 이력을 직접 전송하려면 이전 세션 수집을 참조하세요.4
Codex에서 훅 승인
Codex는 새로 추가된 훅을 승인하기 전까지는 실행하지 않습니다.
-
터미널을 열고 다음을 실행하세요.
-
셸이 아닌 대화형 Codex 화면에서 다음을 입력하세요.
- Stop 이벤트 아래에서 Forge Agent Lens 훅을 선택한 다음 활성화하거나 신뢰하도록 설정하세요.
--dangerously-bypass-hook-trust 플래그를 사용할 수도 있습니다.forge-agent-lens-for-codex status를 실행하여 훅이 설치되었고 플러그인이 ready 상태인지 확인하세요.Agent Lens에서 Codex 트레이스 보기
Codex 세션을 한 번 이상 실행한 후 Agent Lens UI에서 프로젝트를 여세요.- CoreWeave Forge로 이동하여 제품 메뉴에서 Agent Lens를 선택한 다음, 사이드 메뉴 상단의 프로젝트 선택기에서 프로젝트를 선택하세요.
- 사이드 메뉴에서 Conversations를 선택하세요.
- 대화를 선택하면 전체 턴 계층 구조를 확인할 수 있습니다.
Span 타임스탬프는 롤아웃 파일에서 가져오므로, 소요 시간에 실제 실행 시간이 반영됩니다. 각 턴은 한 번만 전송됩니다. 내보내기에 실패하면 플러그인은 다음에 Stop 훅이 실행될 때 해당 턴을 다시 시도합니다.
알려진 제한 사항
codex(대화형 TUI) 및codex exec명령어가 지원됩니다.codex mcp, 앱 서버 또는 API에 직접 연결한 세션, Stop 이벤트 없이 중단된 턴은 지원되지 않습니다.- 생성된 서브에이전트는 도구 span으로만 표시됩니다. 서브에이전트의 별도 롤아웃 파일은 중첩된 트레이스로 재구성되지 않으므로 서브에이전트 자체의 모델 호출과 도구 실행은 캡처되지 않습니다.
- 일부
codex exec환경에서는 Stop 훅이 실행되지 않습니다. 플러그인 README의 Headless runs and explicit collection을 참조하세요.
구성 참조
이 섹션에서는 플러그인 동작을 사용자 지정할 때 사용할 수 있는 설정을 설명합니다. 상태, 설정, 로그 파일은~/.forge-agent-lens-for-codex/에 저장되며, 여기에는 settings.json과 logs/collector.log가 포함됩니다. FORGE_CODEX_HOME은 격리된 개발 환경이나 테스트 환경에서만 설정하세요.
Codex가 프록시나 브리지를 거쳐 다른 모델 공급자에게 요청을 보내는 경우
FORGE_CODEX_PROVIDER_NAME을 설정하세요. 플러그인은 이 값을 모델 스팬에 기록합니다.
사용자 인증 정보 결정 순서
플러그인은 API 키를settings.json에 기록하지 않습니다. 키는 다음 순서로 찾습니다.
WANDB_API_KEY환경 변수api.wandb.ai에 대한~/.netrc항목(WANDB_BASE_URL을 설정한 경우 해당 호스트에 대한 항목)
settings.json, 기본값 순으로 우선 적용됩니다.
트레이스 서버와 전송 방식은 Forge SDK가 결정합니다. 맞춤형 배포를 사용하는 경우 WANDB_BASE_URL을 설정하세요. 트레이스 서버를 명시적으로 재정의하려면 WF_TRACE_SERVER_URL을 설정하면 됩니다.
콘텐츠 캡처 끄기
FORGE_CODEX_INCLUDE_CONTENT=false를 설정하면 프롬프트, assistant 출력, 추론, 도구 인수 및 결과, 작업 디렉터리가 제외됩니다. 스팬에는 모델 이름, 토큰 사용량, 소요 시간, 도구 이름, 호출 ID, MCP 서버 이름이 계속 기록됩니다.
대화형 Stop 훅으로 수집하는 경우에는 환경 변수 대신 ~/.forge-agent-lens-for-codex/settings.json에서 include_content를 false로 설정하세요. codex 명령어에만 지정한 변수는 이미 실행 중인 Codex 앱 서버가 실행하는 훅에 전달되지 않을 수 있으므로, 파일에서 설정하는 편이 더 확실합니다. 훅 프로세스의 환경 변수가 설정 파일보다 우선 적용되므로, 해당 환경에 FORGE_CODEX_INCLUDE_CONTENT=true가 설정되어 있지 않은지 확인하세요. 이 변수가 설정되어 있지 않으면 플러그인은 settings.json의 값을 사용합니다. forge-agent-lens-for-codex collect를 명시적으로 실행할 때는 환경 변수가 확실하게 적용됩니다.
이전 세션 수집
collect --all은 명시적인 백필 작업입니다. 모든 롤아웃 세션에서 아직 내보내지 않은 턴을 전송합니다. 커서가 없는 롤아웃은 처음부터 읽기 때문에, 이 명령어를 실행하면 플러그인을 설치하기 전에 생성된 이력까지 전송될 수 있습니다.
--json을 추가하세요.
플러그인 상태 확인
다음 명령어를 사용하여 플러그인 상태를 확인하거나 문제를 해결할 수 있습니다.--json을 추가하세요.
Agent Lens에 턴이 표시되지 않으면 수집기 로그를 확인하세요.
문제 해결
다음 섹션에서는 자주 발생하는 문제와 해결 방법을 설명합니다. 문제를 진단할 때는 주로~/.forge-agent-lens-for-codex/logs/collector.log에 있는 수집기 로그를 확인하세요. 플러그인은 debug 설정과 관계없이 오류를 항상 로깅합니다.
Codex를 실행한 후 트레이스가 표시되지 않는 경우
forge-agent-lens-for-codex status를 실행하세요. 마지막 줄에not ready가 표시되면 함께 출력된 원인을 해결하세요.- 훅이 설치되어 있고 활성화되어 있는지 확인하세요. 승인 단계를 건너뛰었다면
codex를 실행한 다음/hooks를 실행해 훅을 활성화하세요. FORGE_TRACE_PROJECT가/를 정확히 하나 포함하는 유효한entity/project슬러그로 설정되어 있는지 확인하세요.status를 실행하면 확인된 프로젝트가 출력됩니다.- API 키를 찾았는지 확인하세요.
status는 키를 찾았는지 여부만 알려 줄 뿐, 키를 어디에서 가져왔는지는 알려 주지 않습니다. 플러그인이 잘못된 키를 읽는다면WANDB_API_KEY와~/.netrc를 확인하세요. - Codex를
--ephemeral플래그로 실행하고 있지 않은지 확인하세요. 이 플래그를 사용하면 플러그인이 읽는 롤아웃 파일이 생성되지 않습니다. - 패키지를 업그레이드했거나 Node.js 버전을 변경했다면
forge-agent-lens-for-codex install을 다시 실행하세요. 훅에는 설치 당시의 Node.js 경로와 패키지 경로가 기록되기 때문입니다.
턴은 표시되지만 입력 및 출력 텍스트가 비어 있는 경우
콘텐츠 캡처가 비활성화되어 있을 수 있습니다.FORGE_CODEX_INCLUDE_CONTENT가 false로 설정되어 있지 않은지, ~/.forge-agent-lens-for-codex/settings.json에서 include_content가 false로 설정되어 있지 않은지 확인하세요. status를 실행하면 최종 적용된 include content 값이 출력됩니다.
Agent Lens로 트레이스 전송 시 발생하는 오류
플러그인이 활성 상태이고 스팬도 생성되지만 Agent Lens에 표시되지 않는다면, 수집기 로그에서 내보내기 오류를 찾아 아래 표와 비교해 보세요.플러그인 업그레이드
훅은 설치 당시의 Node.js 경로와 패키지 경로를 기록합니다. 플러그인을 업그레이드하려면, 또는 Node.js 버전을 변경한 경우에는 패키지를 다시 설치한 후install을 다시 실행하세요: