OpenClaw에서 Apidog CLI 사용법

OpenClaw는 작업 공간을 읽고, exec 도구로 셸 명령을 실행하고, 출력을 확인한 뒤 다음 작업을 결정하는 루프 기반 에이전트입니다. API 테스트도 이 루프에 넣을 수 있습니다. Apidog에서 만든 테스트 시나리오를 apidog-cli로 실행하면, OpenClaw는 단위 테스트처럼 API 테스트의 종료 코드와 출력을 읽고 실패한 변경을 수정할 수 있습니다.

오늘 Apidog 사용해 보기

이 글에서는 OpenClaw가 Apidog CLI를 지속적으로 사용하도록 설정하는 방법을 다룹니다. 핵심은 작업 공간의 AGENTS.md에 테스트 실행 규칙을 추가하고, exec 권한을 설정하며, 실행 결과와 종료 코드를 검증하는 것입니다.

아직 CLI를 설치하지 않았다면 먼저 설치하세요. AI 코딩 에이전트로 Apidog CLI를 설치하는 방법에서 npm 설치, 인증, 첫 실행 과정을 확인할 수 있습니다. 이 글은 다음이 이미 완료된 상태를 가정합니다.

apidog --version

위 명령이 버전을 출력하고, Apidog 계정 로그인도 완료되어 있어야 합니다.

이 글에서 다루는 OpenClaw

OpenClaw는 로컬 컴퓨터에서 실행되는 오픈소스, 로컬 우선 AI 에이전트입니다. 작업 공간 파일, 스킬, 그리고 실제 셸 명령을 실행하는 exec 도구를 사용합니다.

이 글은 다음과 같은 환경을 기준으로 합니다.

• 로컬에서 openclaw를 실행한다.
• 에이전트가 프로젝트 파일을 편집할 수 있다.
• 에이전트가 exec를 통해 명령을 실행할 수 있다.
• Apidog CLI가 설치 및 인증되어 있다.

더 넓은 설정은 OpenClaw 개발 워크플로우 자동화와 안전한 OpenClaw 설치를 참고하세요.

OpenClaw는 작업 공간 파일을 상시 지침으로 읽습니다. 따라서 채팅에서 한 번 “테스트를 실행해”라고 말하는 대신, AGENTS.md에 실행 규칙을 기록해야 합니다.

1단계: Apidog 규칙을 AGENTS.md에 추가

OpenClaw는 작업 공간의 AGENTS.md를 에이전트 컨텍스트로 읽습니다. 이 파일에 API 테스트 절차를 명시하면, 이후 OpenClaw 실행에서도 동일한 규칙을 적용할 수 있습니다.

기본 작업 공간은 일반적으로 다음 경로입니다.

~/.openclaw/workspace

필요하면 agents.list[].workspace로 특정 에이전트의 작업 공간을 프로젝트 디렉터리로 지정할 수 있습니다. OpenClaw는 하위 디렉터리별 AGENTS.md 범위도 지원합니다. 자세한 규칙은 OpenClaw의 AGENTS.md 참조를 확인하세요.

프로젝트 작업 공간의 AGENTS.md에 다음 블록을 추가합니다.

## Apidog를 사용한 API 테스트

- API 테스트는 Apidog CLI로 실행한다: `apidog run -t <scenario_id> -e <env_id> -r cli`.
- 종료 코드가 0이면 모든 어설션이 통과한 것이다. 0이 아니면 실패로 처리하고, 이를 통과/실패 게이트로 사용한다.
- 이 머신은 이미 `apidog login`으로 인증되어 있다. `--access-token` 플래그를 추가하지 말고 이 파일에 토큰을 저장하지 않는다.
- 익숙하지 않은 플래그가 있으면 추측하지 말고 `apidog run --help`를 실행한다.

이 규칙을 채팅이 아닌 AGENTS.md에 넣어야 하는 이유는 간단합니다.

• 채팅에 입력한 시나리오 ID는 세션이 끝나면 사라질 수 있습니다.
• AGENTS.md의 규칙은 팀원과 이후 OpenClaw 실행에 계속 적용됩니다.
• 에이전트가 코드 변경 후 API 테스트를 자동으로 수행할 근거가 됩니다.

2단계: Apidog에서 실행 명령 가져오기

시나리오 ID와 환경 ID를 직접 추측하지 마세요. Apidog에서 테스트 시나리오를 열고 CI/CD 탭으로 이동한 뒤 생성된 명령을 복사합니다.

예시는 다음과 같습니다.

apidog run -t 1234567 -e 890123 -r cli

각 옵션의 의미는 다음과 같습니다.

옵션	설명
-t	테스트 시나리오 ID
-e	실행 환경 ID
-r cli	터미널 출력 리포터

복사한 실제 명령을 AGENTS.md 규칙에 반영하세요. 그러면 OpenClaw가 올바른 시나리오와 환경을 사용합니다.

추가 플래그는 완전한 Apidog CLI 가이드와 apidog run 명령 참조에서 확인할 수 있습니다.

3단계: OpenClaw가 테스트를 실행하도록 설정

AGENTS.md를 추가한 뒤 프로젝트에서 OpenClaw를 실행합니다. API에 영향을 주는 변경을 요청하거나, 명시적으로 검사를 요청하면 됩니다.

예를 들면 다음과 같이 요청할 수 있습니다.

결제 응답 핸들러를 수정하고, 변경 후 Apidog API 테스트를 실행해.

AGENTS.md가 컨텍스트에 로드되어 있다면 OpenClaw는 exec 도구를 통해 다음과 같은 명령을 실행합니다.

apidog run -t 1234567 -e 890123 -r cli

exec 권한 모드 설정

OpenClaw의 exec 도구는 권한 모드에 따라 셸 명령 실행을 제어합니다.

• deny
• allowlist
• ask
• auto
• full

자세한 내용은 OpenClaw 권한 모드 문서를 참고하세요.

코딩 에이전트에는 일반적으로 auto가 실용적입니다.

• 허용 목록의 명령은 자동 실행됩니다.
• 목록 밖의 명령은 사용자 승인 전에 검토됩니다.
• ask 모드에서는 apidog run 실행 전에 OpenClaw가 승인을 요청합니다.

openclaw.json의 tools.exec 아래에서 모드를 설정하세요. 스테이징 환경에 대한 읽기 전용 API 테스트를 자동 실행하려면 apidog 또는 필요한 실행 명령을 허용 목록에 추가할 수 있습니다.

4단계: OpenClaw에서 테스트 결과 읽기

-r cli 리포터는 터미널에 요청, 어설션, 실패 항목, 예상 값과 실제 값을 출력합니다. OpenClaw가 다음 작업을 결정하려면 이 인라인 출력이 필요하므로 cli 리포터를 유지하세요.

브라우저에서 확인하거나 팀에 공유할 HTML 보고서도 필요하다면 다음처럼 실행합니다.

apidog run -t 1234567 -e 890123 -r cli,html

html 리포터는 독립 실행형 보고서를 ./apidog-reports에 작성합니다. 에이전트가 터미널 출력을 계속 읽을 수 있도록 cli도 함께 지정하세요.

JUnit 등 다른 리포터 형식은 Apidog CLI 테스트 보고서 가이드에서 확인할 수 있습니다.

자체 루프에서 OpenClaw 테스트하기

설정의 목적은 OpenClaw가 코드 편집과 API 테스트를 하나의 루프로 처리하게 만드는 것입니다.

예를 들어 OpenClaw가 결제 응답을 생성하는 핸들러를 수정한다고 가정해 보겠습니다.

1. OpenClaw가 핸들러 코드를 수정합니다.
2. AGENTS.md 규칙에 따라 Apidog 시나리오를 실행합니다.
3. 종료 코드와 CLI 출력을 읽습니다.
4. 종료 코드가 0이면 다음 작업으로 진행합니다.
5. 종료 코드가 0이 아니면 실패한 어설션을 확인합니다.
6. 상태 코드, 누락 필드, 잘못된 값 등을 수정합니다.
7. 테스트를 다시 실행합니다.

즉, API 테스트가 기존의 편집-테스트-수정 루프에 포함됩니다.

이 방식은 위임-검증 모델입니다.

• OpenClaw는 명령을 실행하고 결과를 읽습니다.
• 개발자는 Apidog에서 시나리오를 시각적으로 관리합니다.
• 종료 코드와 원시 출력으로 에이전트의 판단을 검증합니다.

더 넓은 활용 패턴은 AI 에이전트를 API 테스트에 사용하는 방법과 Apidog AI 테스트 하니스를 참고하세요.

OpenClaw가 실제로 CLI를 실행했는지 확인

에이전트의 “테스트 성공” 요약만 믿지 말고, 다음 세 가지를 확인하세요.

1. 실제 명령 실행 여부 확인

OpenClaw 트랜스크립트에서 실행된 exec 명령과 출력을 찾습니다.

다음과 같은 실제 명령이 있어야 합니다.

apidog run -t 1234567 -e 890123 -r cli

OpenClaw가 테스트를 실행했다고 말하지만 명령 기록이 없다면, 실제 실행이 아닌 요약일 수 있습니다. 원시 출력을 보여 달라고 요청하고 다시 실행하세요.

2. 종료 코드 확인

에이전트에게 직접 종료 코드를 물어볼 수 있습니다.

방금 실행한 apidog run 명령의 종료 코드는 무엇이었어?

apidog run의 동작은 다음과 같습니다.

• 0: 모든 어설션 통과
• 0 이외의 값: 하나 이상의 실패 발생

설명에 “테스트 통과”라고 표시되어도 종료 코드가 0이 아니라면 실패로 처리해야 합니다.

3. 올바른 시나리오와 환경 사용 여부 확인

실행 결과에 “시나리오를 찾을 수 없음”이 표시되면 시나리오 ID 또는 환경 ID가 잘못되었을 수 있습니다.

다음을 다시 확인하세요.

• AGENTS.md의 -t 값
• AGENTS.md의 -e 값
• Apidog CI/CD 탭에서 복사한 원본 명령

Apidog가 생성한 CI/CD 명령을 기준으로 유지하는 것이 안전합니다.

선택 사항: Apidog MCP 서버 연결

대부분의 경우 exec로 apidog run을 실행하는 것만으로 충분합니다. 다만 API 사양을 에이전트 컨텍스트에 제공하려면 MCP(Model Context Protocol)를 추가할 수 있습니다.

OpenClaw는 MCP 서버를 지원합니다. 다음 명령으로 서버를 추가할 수 있습니다.

openclaw mcp add <name>

이 명령은 서버 정의를 ~/.openclaw/openclaw.json의 mcp.servers 아래에 작성하며, --command, --arg 같은 표준 입출력 플래그를 지원합니다. 자세한 사용법은 OpenClaw MCP 문서를 참고하세요.

Apidog MCP 서버는 MCP를 통해 API 사양을 노출합니다. 역할은 다음처럼 분리할 수 있습니다.

• Apidog CLI: 테스트 시나리오 실행과 결과 검증
• Apidog MCP 서버: 코드 작성 중 API 스키마와 사양 제공

OpenClaw가 잘못 동작할 때

설정 과정에서 자주 발생하는 문제와 확인 방법입니다.

AGENTS.md 규칙을 무시하는 경우

OpenClaw가 일반 명령만 실행하거나 테스트를 실행하지 않는다면, AGENTS.md가 컨텍스트에 로드되지 않았을 수 있습니다.

다음을 확인하세요.

• 파일이 활성 작업 공간의 AGENTS.md인지 확인합니다.
• 규칙이 잘못된 하위 디렉터리에 있지 않은지 확인합니다.
• OpenClaw의 디렉터리별 범위 규칙 때문에 상위 또는 다른 트리의 파일이 적용되지 않을 수 있습니다.
• 세션을 다시 시작해 파일을 다시 로드합니다.

exec가 차단되어 명령이 실행되지 않는 경우

기본 정책 또는 허용 목록 때문에 exec가 차단될 수 있습니다.

다음을 확인하세요.

• tools.exec의 권한 모드
• apidog 명령이 허용 목록에 포함되어 있는지 여부
• ask 모드에서 승인 요청을 놓치지 않았는지 여부

전체 권한을 열지 않고 필요한 명령만 허용하는 방법은 안전한 OpenClaw 설치 가이드를 참고하세요.

--access-token을 추가하려는 경우

이미 apidog login으로 인증했다면 OpenClaw가 --access-token을 붙일 필요가 없습니다.

AGENTS.md에 다음 규칙이 있는지 확인하세요.

`--access-token`을 추가하지 말고, 이 파일에 토큰을 저장하지 않는다.

실제 토큰을 AGENTS.md에 넣지 마세요. 올바른 인증 방식은 Apidog CLI 인증을 참고하세요.

존재하지 않는 플래그를 사용하는 경우

“알 수 없는 옵션” 오류는 에이전트가 설치된 버전에 없는 플래그를 추측했다는 의미입니다.

추측하지 말고 다음을 실행하도록 지시하세요.

apidog run --help

그 출력에 표시된 플래그만 사용하면 현재 설치된 버전에 맞는 명령을 구성할 수 있습니다.

실패한 실행을 성공으로 보고하는 경우

가장 중요한 기준은 종료 코드입니다.

• 요약이 성공이라고 말해도 종료 코드가 0이 아니면 실패입니다.
• AGENTS.md에 종료 코드 규칙을 명시합니다.
• OpenClaw 트랜스크립트에서 원시 명령과 출력을 확인합니다.

이 검증 방식은 다른 코딩 에이전트에도 동일하게 적용됩니다. 관련 사례는 Codex의 Apidog CLI와 Claude Code vs OpenClaw에서 확인할 수 있습니다.

일상적인 에이전트를 테스트 루프로 바꾸기

설정은 다음 네 단계로 끝납니다.

1. 설치 가이드에 따라 apidog-cli를 설치합니다.
2. 작업 공간의 AGENTS.md에 Apidog 실행 규칙을 추가합니다.
3. tools.exec 권한 모드 또는 허용 목록을 설정합니다.
4. OpenClaw가 명령, 출력, 종료 코드를 확인하도록 합니다.

이제 OpenClaw는 코드 편집에 사용하던 루프 안에서 API 테스트도 실행할 수 있습니다. 손상된 엔드포인트를 배포 후가 아니라 변경 작업 중에 발견할 수 있습니다.

GUI의 테스트는 사람이 클릭할 때만 실행됩니다. 반면 AGENTS.md에 기록된 한 줄의 CLI 명령은 OpenClaw가 코드 변경을 검증할 때마다 실행할 수 있습니다.

Apidog에서 시나리오를 만들고, Apidog를 다운로드한 뒤, 생성된 apidog run 명령을 AGENTS.md에 추가해 보세요. 에이전트 없이 CI 파이프라인에서 같은 게이트를 사용하려면 GitHub Actions의 Apidog CLI를 참고하세요.