OpenClaw는 루프입니다. 작업 공간을 읽고, exec 도구를 통해 셸 명령을 실행하고, 출력을 읽고, 다음에 무엇을 할지 결정합니다. 그렇다면 왜 API 테스트는 이 루프에 포함되지 않습니까? API 테스트는 GUI 뒤의 Apidog에 보관되어 있으며, 누군가 클릭하는 것을 기억할 때 실행됩니다. 에이전트는 결코 이들을 건드리지 않습니다.
해결책은 하나의 설정 블록입니다. Apidog CLI는 Apidog에서 구축한 테스트 시나리오를 터미널에서 직접 실행하는 npm 패키지인 apidog-cli입니다. CLI가 설치되고 OpenClaw가 이를 인식하면, 에이전트는 단위 테스트를 실행하는 것과 동일한 방식으로 Apidog 시나리오를 실행합니다. 명령을 실행하고, 종료 코드를 읽고, 빨간색(실패)인 경우 코드를 수정합니다.
이 가이드는 일반 설치 가이드에서 건너뛰는 OpenClaw 관련 부분을 다룹니다. 에이전트가 Apidog 규칙을 유지하도록 어디에 배치해야 하는지, OpenClaw의 exec 도구가 실제로 apidog run을 어떻게 실행하는지, 그리고 결과를 읽는 방법입니다.
아직 CLI를 설치하지 않았다면, 먼저 설치하십시오. AI 코딩 에이전트로 Apidog CLI를 설치하는 방법은 npm 설치, 인증 및 첫 실행 과정을 안내합니다. 이 문서는 apidog --version이 숫자를 출력하고 Apidog 계정이 로그인되어 있다고 가정합니다.
이 글에서 다루는 OpenClaw
OpenClaw는 사용자 자신의 컴퓨터에서 실행되는 오픈소스, 로컬 우선 AI 에이전트입니다. 작업 공간, 일련의 스킬, 그리고 실제 셸 명령을 실행하는 exec 도구를 가지고 있습니다. 이는 코드 자동 완성 플러그인도 아니고 호스팅된 챗봇도 아닙니다. 로컬에서 openclaw를 실행하고 파일 편집 및 명령 실행을 지켜본 적이 있다면 제대로 찾아오셨습니다. 더 넓은 설정에 대해서는 OpenClaw 개발 워크플로우 자동화와 명령을 넘겨주기 전에 안전한 OpenClaw 설치 가이드를 참조하십시오.
이러한 구별이 중요한 이유는 OpenClaw가 작업 공간 파일에서 프로젝트 규칙을 학습하며, 그 메커니즘이 일회성으로 "내 테스트 실행"을 OpenClaw가 스스로 활용하는 것으로 바꾸기 때문입니다. 그 메커니즘이 바로 AGENTS.md입니다.
1단계: Apidog 규칙을 AGENTS.md에 추가
OpenClaw는 작업 공간 파일을 상시 지침으로 읽고 에이전트의 컨텍스트에 주입합니다. 여러분이 원하는 것은 에이전트에게 무엇을 어떻게 해야 할지 알려주는 절차 규칙서인 AGENTS.md입니다. Claude Code의 CLAUDE.md로 생각하십시오. OpenClaw는 심지어 작업 공간으로 복사할 수 있는 기본 템플릿을 제공하며, 동반 CLAUDE.md 심볼릭 링크를 동일한 파일로 처리합니다. 작업 공간은 기본적으로 ~/.openclaw/workspace이지만, agents.list[].workspace를 사용하여 에이전트를 프로젝트 디렉토리에 지정할 수 있으며, OpenClaw는 하위 디렉토리별로 범위가 지정된 AGENTS.md 파일을 지원합니다(OpenClaw의 AGENTS.md 참조 참조).
여러분의 AGENTS.md에 짧은 블록을 추가하세요:
## API testing with Apidog
- To run API tests, use the Apidog CLI: `apidog run -t <scenario_id> -e <env_id> -r cli`.
- Exit code 0 means every assertion passed. Non-zero means something failed. Treat it as the pass/fail gate.
- The machine is already authenticated with `apidog login`. Never add an --access-token flag and never put a token in this file.
- If a flag looks unfamiliar, run `apidog run --help` instead of guessing.
이것이 채팅에서 언급하는 대신 AGENTS.md에 CLI를 작성하는 이유입니다. 세션에 입력된 시나리오 ID는 세션이 끝나면 사라집니다. AGENTS.md에 있는 것은 모든 팀원과 지금부터의 모든 OpenClaw 실행을 위해 존재합니다.
2단계: Apidog에서 명령 가져오기
시나리오 ID를 직접 작성할 필요는 없습니다. Apidog에서 테스트 시나리오를 열고, CI/CD 탭으로 이동하여 생성된 명령을 복사합니다. 다음과 같습니다:
apidog run -t 1234567 -e 890123 -r cli
-t는 테스트 시나리오, -e는 환경, -r cli는 리포터입니다. 실제 ID를 1단계의 AGENTS.md 블록에 붙여넣어 OpenClaw가 항상 올바른 환경에 대해 올바른 시나리오를 호출하도록 하십시오. 세부 조정을 원하시면 완전한 Apidog CLI 가이드와 apidog run 명령 참조에서 모든 플래그를 확인할 수 있습니다.
3단계: 에이전트가 테스트를 실행하도록 하기
블록이 준비되면, 프로젝트에 대해 OpenClaw를 시작하고 API에 영향을 미치는 변경 사항을 만들거나, 단순히 검사를 실행하도록 요청하십시오. AGENTS.md가 이미 컨텍스트에 있으므로, 에이전트는 CLI가 존재한다는 것을 알고 exec 도구를 통해 apidog run 명령을 발행합니다.
exec 도구는 작업 공간에서 셸 명령을 실행하며, OpenClaw는 이를 권한 모드로 제어합니다. 모드에는 deny, allowlist, ask, auto, full이 있습니다(OpenClaw의 권한 모드 페이지에 설명되어 있습니다). 코딩 에이전트의 경우 auto가 합리적인 설정입니다. 허용 목록에 있는 명령은 프롬프트 없이 실행되고, 그 외의 모든 것은 사용자에게 묻기 전에 검토를 거칩니다. 모드가 ask인 경우 OpenClaw는 apidog run을 실행하기 전에 일시 중지하고 승인을 요청합니다. 한 번 승인하거나, 명령을 허용 목록에 추가하여 스테이징에 대한 읽기 전용 테스트가 자동으로 실행되도록 하십시오. openclaw.json의 tools.exec 아래에서 모드를 설정하십시오.
4단계: OpenClaw 내에서 보고서 읽기
-r cli 리포터는 터미널에 각 요청, 각 어설션, 그리고 예상 값과 실제 값 중 어떤 것이 실패했는지 단계별 결과를 출력합니다. 이 인라인 분석은 OpenClaw가 다음 단계를 결정하기 위해 읽는 것이므로, 목록에 cli를 유지하십시오.
브라우저에서 열거나 팀원에게 전달할 수 있는 보고서를 원한다면, HTML 리포터를 추가하십시오:
apidog run -t 1234567 -e 890123 -r cli,html
html 리포터는 독립적인 파일을 ./apidog-reports에 작성합니다. OpenClaw가 여전히 인라인 출력을 얻도록 cli를 함께 유지하십시오. CI 대시보드가 파싱하는 JUnit 형식 및 기타 모든 리포터에 대해서는 Apidog CLI 테스트 보고서 가이드를 참조하십시오.
자체 루프 내에서 OpenClaw 테스트
요점은 여러분이 요청을 멈추고 AGENTS.md가 지시했기 때문에 OpenClaw가 시나리오를 스스로 실행할 때 어떤 일이 발생하는지입니다.
OpenClaw가 결제 응답을 생성하는 핸들러를 편집하는 상황을 상상해 보십시오. 그 루프는 변경됩니다. 코드를 편집한 다음, 성공을 선언하는 대신, 스테이징 환경에 대해 Apidog 시나리오를 실행하고, 종료 코드를 읽고, 이에 따라 행동합니다. 초록색(성공)이면 다음으로 진행합니다. 빨간색(실패)이면 보고서를 열고, 어떤 어설션이 실패했는지(상태 코드, 누락된 필드, 잘못된 값) 읽고, 수정을 시도한 후 다시 실행합니다. API 테스트는 OpenClaw가 이미 단위 테스트를 실행하는 것과 동일한 편집-테스트-수정 루프의 일부가 됩니다. 여러분은 하나의 지침을 작성했고 에이전트는 그 명령을 기존 작동 방식에 통합했습니다.
이것은 모든 에이전트 워크플로우를 안전하게 만드는 위임-검증 모델입니다. OpenClaw는 명령을 실행하고 결과를 읽습니다. 여러분은 Apidog에서 시각적으로 시나리오를 계속 작성하고 에이전트가 종료 코드를 정확하게 읽는지 점검합니다. 더 넓은 패턴에 대해서는 AI 에이전트를 API 테스트에 사용하는 방법과 Apidog AI 테스트 하니스를 참조하십시오.
OpenClaw가 실제로 CLI를 실행하는지 확인
에이전트는 얻지 못한 성공을 보고하고, OpenClaw도 예외는 아닙니다. 문제가 얼마나 자주 발생하는지에 따라 세 가지 확인 사항이 있습니다.
첫째, 명령이 실행되었는지 확인하십시오. OpenClaw의 트랜스크립트는 실행된 exec 명령과 그 출력을 보여줍니다. 문자 그대로의 apidog run ... 라인과 그 아래의 결과를 찾으십시오. OpenClaw가 테스트를 실행했다고 말하지만 명령이 보이지 않는다면, 실제로 하지 않은 일을 요약한 것입니다. 다시 실행하고 원시 출력을 보여달라고 요청하십시오.
둘째, 중요한 종료 코드를 확인하십시오. 직접 물어보세요:
What was the exit code of that apidog run command?
apidog run은 모든 어설션이 통과하면 0으로 종료하고, 무언가 실패하면 0이 아닌 값으로 종료합니다. 이 단일 동작으로 OpenClaw 또는 파이프라인은 실행을 깔끔한 게이트로 처리할 수 있습니다. 설명에서 “테스트 통과”라고 하지만 종료 코드가 0이 아닌 경우, 종료 코드가 맞습니다.
셋째, 실제 시나리오를 사용했는지 확인하십시오. 실행이 "시나리오를 찾을 수 없음"으로 실패하면, OpenClaw가 ID를 만들어내거나 잘못 기억했을 수 있습니다. -t와 -e 값을 AGENTS.md 및 Apidog가 CI/CD 탭에서 생성한 명령과 다시 확인하십시오. AGENTS.md의 ID가 진실입니다.
선택 사항: Apidog MCP 서버 연결
exec 도구를 통해 apidog run을 실행하는 것은 필요한 대부분을 충족합니다. 한 가지 방법은 더 나아갑니다. 바로 모델 컨텍스트 프로토콜(Model Context Protocol)입니다.
OpenClaw는 MCP 서버를 지원합니다. openclaw mcp add <name>을 사용하여 추가할 수 있으며, 이 명령은 서버 정의를 ~/.openclaw/openclaw.json의 mcp.servers 아래에 작성하고 --command 및 --arg와 같은 표준 입출력 플래그를 허용합니다(OpenClaw의 MCP 문서 참조). Apidog MCP 서버는 MCP를 통해 API 사양을 노출하므로, OpenClaw는 코드를 작성하는 동안 스키마를 읽을 수 있으며, 사후에만 읽는 것이 아닙니다. 작업 분할은 명확합니다. CLI는 테스트를 실행하고, MCP는 에이전트에게 사양을 제공합니다.
OpenClaw가 잘못될 때
설정 중에 몇 가지 오류가 자주 발생합니다.
AGENTS.md 블록을 무시합니다. OpenClaw가 일반 명령을 실행하거나 아무것도 실행하지 않는다면, 파일이 컨텍스트로 로드되지 않을 수 있습니다. 블록이 에이전트의 활성 작업 공간에 속하는 AGENTS.md에 있는지 확인하고, OpenClaw가 디렉토리별로 범위가 지정된 AGENTS.md 파일을 탐색하므로 잘못된 하위 트리에 포함된 규칙은 건너뛰어진다는 점을 기억하십시오. 세션을 다시 시작하면 새로 읽기가 강제됩니다.
exec가 차단되어 아무것도 실행하지 않습니다. OpenClaw의 기본 정책이 강화된 이후로, exec는 거부되거나 허용 목록 뒤에 갇힐 수 있습니다. apidog run이 자동으로 건너뛰어지면, tools.exec 아래의 권한 모드를 확인하고 auto로 전환하거나 apidog를 허용 목록에 추가하십시오. 모든 것을 열지 않고 이 명령만 여는 방법은 안전한 OpenClaw 설치 가이드를 참조하십시오.
어쨌든 액세스 토큰을 전달합니다. OpenClaw가 --access-token을 추가하려고 한다면, 공개 예시에서 추측하는 것입니다. 이 블록은 이미 apidog login을 통해 머신이 인증되었으므로 그렇게 하지 말라고 알려줍니다. 해당 줄을 강화하고, AGENTS.md에 실제 토큰을 절대 넣지 마십시오. 올바른 패턴은 Apidog CLI 인증을 참조하십시오.
플래그를 만들어냅니다. "알 수 없는 옵션" 오류는 OpenClaw가 여러분의 버전에는 없는 플래그를 추측했음을 의미합니다. apidog run --help를 실행하고 거기서 정확한 플래그를 복사하도록 지시하십시오. 이것은 항상 설치된 버전에 대해 올바릅니다.
실패한 실행에 대해 성공을 보고합니다. 가장 비용이 많이 드는 문제이며, 종료 코드 규칙이 AGENTS.md 및 검증 단계에 있는 이유입니다. 요약과 종료 코드가 일치하지 않을 때, 종료 코드가 우선합니다. 다른 에이전트를 사용했더라도 동일한 규칙이 적용됩니다. 이 접근 방식은 Codex의 Apidog CLI에서 다루는 내용과 Claude Code vs OpenClaw의 차이점을 반영합니다.
일상적인 에이전트에서 테스트 루프로
이것이 설정입니다. 설치 가이드에 따라 apidog-cli를 한 번 설치하고, 작업 공간 AGENTS.md에 짧은 Apidog 블록을 추가하고, 명령이 실행될 수 있도록 exec 권한 모드를 설정하면, OpenClaw는 코드를 편집하는 데 이미 사용하는 동일한 루프 내에서 API 테스트를 실행하고 결과를 읽는 방법을 알게 됩니다. 손상된 엔드포인트는 OpenClaw가 변경 작업을 진행하는 동안 감지되며, 배포된 후가 아닙니다.
GUI 뒤의 테스트는 사람이 클릭할 때 실행됩니다. 한 줄짜리 명령은 OpenClaw가 결정할 때마다 실행됩니다. 여러분은 Apidog에서 시각적으로 시나리오를 계속 구축하고, 에이전트는 여러분이 지켜보지 않는 곳에서 이를 실행합니다. Apidog를 다운로드하고, 시나리오 하나를 구축한 다음, apidog run 명령을 AGENTS.md에 넣고, OpenClaw가 다음 변경 사항에서 이를 어떻게 활용하는지 지켜보십시오. 에이전트 없이 파이프라인에서 동일한 게이트를 원한다면, GitHub Actions의 Apidog CLI가 비밀, 리포터, 종료 코드 게이팅을 다룹니다.