Codex는 루프입니다. 파일을 편집하고, 명령을 실행하고, 출력을 읽고, 다음에 무엇을 할지 결정합니다. 그렇다면 왜 API 테스트는 이 루프에 포함되지 않습니까? API 테스트는 GUI 뒤의 Apidog에 놓여 있으며, 누군가 클릭할 때만 실행됩니다. 에이전트는 이를 전혀 건드리지 않습니다.
해결책은 하나의 구성 블록입니다. Apidog CLI는 Apidog에서 구축한 테스트 시나리오를 터미널에서 직접 실행하는 npm 패키지인 apidog-cli입니다. CLI가 설치되고 Codex가 존재를 알게 되면, 에이전트는 단위 테스트를 실행하는 것과 동일한 방식으로 Apidog 시나리오를 실행합니다. 즉, 명령을 실행하고, 종료 코드를 읽고, 빨간색이면 코드를 수정합니다.
이 가이드는 일반 설치 가이드에서 생략된 Codex 관련 부분, 즉 AGENTS.md에 대한 정확한 라인, Codex에 전달할 프롬프트, Codex가 자체 루프 내에서 apidog run을 실행하는 방법, 그리고 결과를 읽는 방법을 다룹니다.
아직 CLI를 설치하지 않았다면, 먼저 설치하십시오. AI 코딩 에이전트를 사용하여 Apidog CLI를 설치하는 방법은 npm 설치, 액세스 토큰, 그리고 Codex가 입력하는 첫 실행 과정을 설명합니다. 이 문서에서는 apidog --version이 숫자를 출력하고 Apidog 계정이 인증되었다고 가정합니다.
이 글이 다루는 Codex
OpenAI Codex CLI와 Codex 앱 모두입니다. 로컬에서 실행되며, 리포지토리를 읽고, 파일을 편집하고, 샌드박스 내에서 셸 명령을 실행하며, 권한 모드에 따라 승인을 요청합니다. 이것은 구형 Codex 코드 완성 API가 아닙니다. codex를 실행했을 때 차이점과 명령 출력을 보여주는 전체 화면 인터페이스가 나타난다면, 제대로 찾아오신 것입니다. OpenAI Codex CLI 가이드는 기본 사항을 다룹니다.
Codex가 프로젝트 규칙을 학습하는 자체 방식이 있기 때문에 이 구별은 중요합니다. 이 메커니즘은 일회성 "내 테스트 실행"을 Codex가 스스로 찾아내는 것으로 바꿉니다. 그 메커니즘이 바로 AGENTS.md입니다.
메커니즘: AGENTS.md, 채팅 알림이 아님
Codex는 작업을 시작하기 전에 AGENTS.md 파일을 읽습니다. Claude Code의 CLAUDE.md와 비슷하다고 생각하십시오. Codex가 모든 세션 시작 시 컨텍스트로 로드하는 일반 마크다운 파일 형식의 프로젝트 지침입니다. Git 루트에서 현재 디렉토리까지 이동하면서 각 AGENTS.md를 루트 우선으로 연결하여 충돌 시 더 가까운 파일이 우선하도록 지침 세트를 구축합니다. 또한 전역 ~/.codex/AGENTS.md도 있습니다. 우리의 목적을 위해서는 리포지토리 루트에 하나의 파일만 있어도 충분합니다.
이것이 채팅에서 언급하는 대신 AGENTS.md에 CLI를 작성하는 이유입니다. 채팅에 입력된 시나리오 ID는 세션이 끝나면 사라집니다. AGENTS.md에 있는 것은 지금부터 모든 팀원과 모든 Codex 실행을 위해 항상 존재합니다.
1단계: Codex에 프롬프트를 주고 실행을 지켜봅니다
블록이 제자리에 있으면, 리포지토리에서 Codex를 시작합니다.
Codex는 시작할 때 AGENTS.md를 로드하므로, CLI가 거기에 있다는 것을 이미 알고 있습니다. API에 영향을 주는 변경 사항을 만들거나, 검사를 실행하도록 요청합니다.
Codex는 AGENTS.md에서 apidog run 명령을 실행합니다. 기본 Auto 모드에서는 파일을 읽고, 편집하고, 작업 디렉토리 내에서 자체적으로 명령을 실행할 수 있으므로, 일반 apidog run은 일반적으로 프롬프트 없이 실행됩니다. -r cli 리포터는 각 요청과 어설션이 발생하는 것을 터미널에서 단계별 결과와 요약을 바로 출력합니다.
실행이 진행되고 Codex가 요약과 종료 코드 모두를 보고하는 것을 보고 싶을 것입니다. 권한 모드가 읽기 전용인 경우, Codex는 실행 전에 일시 중지하고 묻습니다. 승인하거나, 세션 내에서 /permissions로 모드를 변경하십시오. Auto는 합리적인 기본값입니다. 스테이징에 대한 읽기 전용 테스트 시나리오는 해당 모드가 위해 만들어진 안전한 작업 공간 내 명령이기 때문입니다.
2단계: Codex의 자체 루프 내 테스트
핵심은 당신이 요청을 멈추고 Codex가 AGENTS.md의 지시에 따라 시나리오를 스스로 실행할 때 일어나는 일입니다.
Codex가 결제 응답을 구축하는 핸들러를 편집하는 상황을 상상해 보십시오. 루프가 변경됩니다. 코드를 편집한 다음, 성공을 선언하는 대신 스테이징에 대해 Apidog 시나리오를 실행하고, 종료 코드를 읽고, 이에 따라 행동합니다. 녹색이면 다음으로 넘어갑니다. 빨간색이면 보고서를 열고, 어떤 어설션이 실패했는지(상태 코드, 누락된 필드, 잘못된 값) 읽고, 수정 사항을 시도하고, 다시 실행합니다. API 테스트는 Codex가 이미 단위 테스트를 실행하는 것과 동일한 편집-테스트-수정 루프의 일부가 됩니다. 당신은 하나의 지침을 작성했고 Codex는 명령을 이미 작동하는 방식에 통합했습니다.
이것이 모든 에이전트 워크플로우를 안전하게 만드는 위임-검증 모델입니다. Codex는 명령을 실행하고 결과를 읽습니다. 당신은 Apidog에서 시각적으로 시나리오를 계속 작성하고 에이전트가 종료 코드를 정직하게 읽는지 스팟-체크합니다. 더 넓은 패턴에 대해서는 API 테스트에 AI 에이전트를 사용하는 방법과 Apidog AI 테스트 하네스를 참조하십시오.
Codex가 실제로 CLI를 실행하고 있는지 확인
에이전트는 얻지 못한 성공을 보고하며, Codex도 예외는 아닙니다. 문제가 발생하는 빈도에 따른 세 가지 확인 사항입니다.
첫째, 명령이 전혀 실행되었는지 확인합니다. Codex 인터페이스는 실행된 명령과 해당 출력을 인라인으로 보여줍니다. 리터럴 apidog run ... 줄과 그 아래의 결과를 찾으십시오. Codex가 테스트를 실행했다고 말했지만 명령이 보이지 않는다면, 실제로 수행하지 않은 것을 요약한 것입니다. 다시 실행하도록 요청하고 원시 출력을 보여달라고 하십시오.
둘째, 중요한 종료 코드를 확인합니다.
저 apidog run 명령의 종료 코드는 무엇이었나요?
apidog run은 모든 어설션이 통과하면 0으로 종료하고, 실패하면 0이 아닌 값으로 종료합니다. 이 하나의 동작으로 Codex나 파이프라인은 실행을 깨끗한 게이트로 취급할 수 있습니다. Codex의 설명이 "테스트 통과"라고 말했지만 종료 코드가 0이 아니면, 종료 코드가 올바른 것입니다.
셋째, 실제 시나리오를 사용했는지 확인합니다. 실행이 "시나리오를 찾을 수 없음"으로 실패하면, Codex가 ID를 만들었거나 잘못 기억했을 수 있습니다. AGENTS.md와 Apidog가 CI/CD 탭에서 생성한 명령에 대해 -t 및 -e 값을 다시 확인하십시오. AGENTS.md의 ID가 진실입니다.
테스트 보고서 읽기
실행이 빨간색으로 바뀌면 보고서에 답이 있습니다. -r cli를 사용하면 Codex는 터미널에서 읽기 쉬운 분석을 얻습니다. 각 요청, 각 어설션, 그리고 예상 값과 실제 값 중 어떤 것이 실패했는지 명시합니다. 실패한 어설션은 정확한 필드 또는 상태 코드를 명시하며, 이는 Codex가 수정 사항을 찾는 데 일반적으로 충분합니다.
브라우저에서 열거나 팀원에게 전달할 수 있는 보고서를 원한다면, HTML 리포터를 추가하십시오.
html 리포터는 ./apidog-reports에 자체 포함된 파일을 작성합니다. Codex가 다음 단계를 결정하기 위해 읽는 인라인 출력을 여전히 얻을 수 있도록 cli를 목록에 유지하십시오. JUnit 형식 CI 대시보드 구문 분석을 포함한 모든 플래그 및 리포터에 대한 자세한 내용은 완전한 Apidog CLI 가이드 및 apidog run 명령 참조를 참조하십시오.
셸 명령보다 더 깊이 들어가는 두 가지 방법
AGENTS.md에서 apidog run을 실행하는 것으로 대부분의 필요한 사항이 충족됩니다. 두 가지 경로가 더 깊이 들어갑니다.
첫 번째는 MCP입니다. Codex는 모델 컨텍스트 프로토콜(MCP)을 지원하며, codex mcp add를 사용하거나 ~/.codex/config.toml에 [mcp_servers.NAME] 블록을 편집하여 서버를 추가할 수 있습니다. Apidog MCP 서버는 MCP를 통해 API 사양을 노출하여 Codex가 코드를 작성하는 동안 스키마를 읽을 수 있도록 합니다. 즉, 사후가 아니라 실시간으로 말입니다. CLI는 테스트를 실행하고, MCP는 에이전트에 사양을 제공합니다.
두 번째는 codex exec입니다. 일반 codex가 대화형 인터페이스를 여는 반면, codex exec "..."는 Codex를 비대화형으로 실행하고 결과를 stdout으로 파이프합니다. 이는 스크립트 및 CI에서 필요한 것입니다. Codex 없이 파이프라인에서 apidog run을 실행하려면, GitHub Actions의 Apidog CLI에서 비밀, 리포터 및 종료 코드 게이팅을 다룹니다.
Codex가 잘못할 때
설정 중 몇 가지 실패가 자주 나타납니다.
AGENTS.md 블록을 무시합니다. Codex가 일반 명령을 실행하거나 전혀 실행하지 않는 경우, 블록이 로드되지 않을 수 있습니다. 파일 이름이 정확히 AGENTS.md이고 Git 루트 또는 현재 디렉토리의 상위 디렉토리에 있는지 확인하십시오. 파일 이름에 오타가 있으면 Codex는 파일을 읽지 않습니다. 세션을 다시 시작하면 새로 읽기가 강제됩니다.
어쨌든 액세스 토큰을 전달합니다. Codex가 --access-token을 추가하려고 시도하면, 공개 예제에서 추측하는 것입니다. 머신이 apidog login을 통해 인증되었기 때문에 블록은 이미 그렇게 하지 말라고 지시합니다. 해당 줄을 강화하고, AGENTS.md에 실제 토큰을 넣지 마십시오.
플래그를 발명합니다. "알 수 없는 옵션" 오류는 Codex가 당신의 버전에는 없는 플래그를 추측했음을 의미합니다. apidog run --help를 실행하도록 지시하고, 거기서 정확한 플래그를 복사하게 하십시오. 이는 설치된 버전에 대해 항상 올바른 것입니다.
실패한 실행을 통과로 보고합니다. 가장 비싼 오류이며, 종료 코드 규칙이 AGENTS.md와 검증 단계에 있는 이유입니다. 요약과 종료 코드가 일치하지 않으면 종료 코드가 우선합니다.
일일 에이전트에서 테스트된 루프로
이것이 설정입니다. 설치 가이드에 따라 apidog-cli를 한 번 설치하고, 리포지토리의 AGENTS.md에 짧은 Apidog 블록을 추가하면, Codex는 코드를 편집하는 데 이미 사용하는 동일한 루프 내에서 API 테스트를 실행하고 결과를 읽는 방법을 알게 됩니다. 손상된 엔드포인트는 Codex가 변경 작업을 하는 동안 발견되며, 배포 후에 발견되지 않습니다.
GUI 뒤의 테스트는 사람이 클릭할 때 실행되지만, 한 줄짜리 명령은 Codex가 결정할 때마다 실행됩니다. 당신은 Apidog에서 시각적으로 시나리오를 계속 구축하고, 에이전트는 당신이 보지 않는 곳에서 시나리오를 실행합니다. Apidog를 다운로드하고, 하나의 시나리오를 구축하고, 해당 apidog run 명령을 AGENTS.md에 추가하고, Codex가 다음 변경 시 이를 수행하는 것을 지켜보십시오.