Cara Menggunakan Apidog CLI di OpenClaw

OpenClaw bekerja dalam sebuah siklus: membaca ruang kerja, menjalankan perintah shell melalui alat eksekusi, membaca output, lalu menentukan langkah berikutnya. Agar pengujian API masuk ke siklus yang sama, jalankan skenario Apidog melalui CLI—bukan hanya dari GUI saat seseorang ingat untuk mengkliknya.

Coba Apidog hari ini

Solusinya adalah menambahkan konfigurasi yang tepat. Apidog CLI, paket npm bernama apidog-cli, dapat menjalankan skenario tes Apidog langsung dari terminal. Setelah CLI tersedia dan OpenClaw mengetahui instruksinya, agen dapat menjalankan tes API seperti tes unit: jalankan perintah, baca kode keluar, lalu perbaiki kode jika hasilnya gagal.

Panduan ini berfokus pada implementasi OpenClaw: menempatkan aturan Apidog di AGENTS.md, mengizinkan alat eksekusi menjalankan apidog run, dan memvalidasi hasil eksekusinya.

Jika CLI belum terinstal, selesaikan langkah tersebut terlebih dahulu. Cara menginstal Apidog CLI dengan agen pengkodean AI mencakup instalasi npm, autentikasi, dan eksekusi pertama. Artikel ini mengasumsikan perintah berikut sudah berhasil:

apidog --version

Akun Apidog Anda juga harus sudah masuk.

OpenClaw yang digunakan dalam panduan ini

OpenClaw adalah agen AI sumber terbuka dan lokal-pertama yang berjalan di mesin Anda sendiri. Ia memiliki ruang kerja, keterampilan, dan alat eksekusi untuk menjalankan perintah shell nyata.

Panduan ini relevan jika Anda sudah menjalankan openclaw secara lokal dan melihatnya mengedit file atau menjalankan perintah. Untuk pengaturan yang lebih luas, baca otomatisasi alur kerja pengembangan OpenClaw dan instalasi OpenClaw yang aman.

Kuncinya adalah file instruksi ruang kerja. OpenClaw membaca aturan proyek dari file tersebut, sehingga instruksi “jalankan tes API” tidak hanya berlaku untuk satu sesi obrolan. File yang digunakan adalah AGENTS.md.

Langkah 1: Tambahkan aturan Apidog ke AGENTS.md

OpenClaw memuat file ruang kerja sebagai instruksi tetap ke konteks agen. Gunakan AGENTS.md untuk mendefinisikan prosedur yang harus diikuti agen.

Secara konsep, file ini mirip CLAUDE.md pada Claude Code. OpenClaw juga memperlakukan tautan simbolis CLAUDE.md sebagai file yang sama. Ruang kerja default berada di:

~/.openclaw/workspace

Anda dapat mengarahkan agen ke direktori proyek melalui agents.list[].workspace. OpenClaw juga mendukung AGENTS.md per subdirektori. Lihat referensi AGENTS.md OpenClaw.

Tambahkan blok berikut ke AGENTS.md proyek Anda:

## Pengujian API dengan Apidog

- Untuk menjalankan tes API, gunakan Apidog CLI: `apidog run -t <scenario_id> -e <env_id> -r cli`.
- Kode keluar 0 berarti setiap pernyataan berhasil. Non-nol berarti ada yang gagal. Perlakukan ini sebagai gerbang lulus/gagal.
- Mesin sudah diautentikasi dengan `apidog login`. Jangan pernah menambahkan flag `--access-token` dan jangan pernah menempatkan token di file ini.
- Jika sebuah flag terlihat asing, jalankan `apidog run --help` alih-alih menebak.

Simpan ID skenario dan lingkungan di file ini, bukan hanya di percakapan. Instruksi dalam sesi dapat hilang saat sesi berakhir, tetapi instruksi di AGENTS.md dapat dipakai oleh setiap rekan tim dan setiap sesi OpenClaw berikutnya.

Langkah 2: Salin perintah dari Apidog

Jangan menulis ID skenario secara manual jika Anda dapat mengambilnya langsung dari Apidog.

1. Buka skenario tes di Apidog.
2. Buka tab CI/CD.
3. Salin perintah CLI yang dihasilkan.

Contohnya:

apidog run -t 1234567 -e 890123 -r cli

Arti flag:

• -t: ID skenario tes.
• -e: ID lingkungan.
• -r cli: reporter yang mencetak hasil langsung ke terminal.

Tempelkan ID nyata ke blok AGENTS.md agar OpenClaw selalu menjalankan skenario yang benar terhadap lingkungan yang benar.

Untuk konfigurasi flag lainnya, lihat panduan lengkap Apidog CLI dan referensi perintah apidog run.

Langkah 3: Minta agen menjalankan tes

Setelah aturan tersedia di AGENTS.md, jalankan OpenClaw pada proyek Anda. Anda dapat meminta agen menjalankan pemeriksaan secara langsung atau membuat perubahan pada kode yang memengaruhi API.

Contoh permintaan:

Jalankan tes API Apidog setelah memperbarui handler checkout. Jika gagal, baca output dan perbaiki penyebabnya.

Karena AGENTS.md sudah masuk ke konteks agen, OpenClaw dapat menjalankan apidog run melalui alat eksekusinya.

Atur izin eksekusi OpenClaw

Alat eksekusi menjalankan perintah shell di ruang kerja. OpenClaw menyediakan mode izin berikut:

• deny
• allowlist
• ask
• auto
• full

Mode tersebut dijelaskan di halaman mode izin OpenClaw.

Untuk agen pengkodean, auto adalah pilihan yang praktis:

• Perintah yang diizinkan dapat berjalan tanpa prompt.
• Perintah lain tetap melalui peninjauan sebelum meminta persetujuan.

Jika Anda menggunakan mode ask, OpenClaw akan meminta persetujuan sebelum menjalankan apidog run. Anda dapat menyetujui perintah tersebut saat diminta atau menambahkan apidog ke allowlist agar tes baca-saja terhadap staging dapat berjalan otomatis.

Atur mode ini di bawah tools.exec dalam openclaw.json.

Langkah 4: Baca laporan di dalam OpenClaw

Reporter -r cli mencetak hasil langkah demi langkah ke terminal, termasuk:

• setiap request;
• setiap assertion;
• assertion yang gagal;
• nilai yang diharapkan dan nilai aktual.

Output inline ini penting karena OpenClaw membacanya untuk menentukan tindakan berikutnya. Karena itu, pertahankan reporter cli dalam perintah Anda.

Jika Anda juga membutuhkan laporan yang dapat dibuka di browser atau dibagikan ke rekan tim, tambahkan reporter HTML:

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

Reporter html menulis laporan mandiri ke:

./apidog-reports

Tetap gunakan cli bersama html, agar OpenClaw masih menerima output inline yang dapat dianalisis.

Untuk JUnit dan reporter lainnya yang dapat diproses dashboard CI, baca panduan laporan tes Apidog CLI.

Masukkan tes API ke siklus edit-tes-perbaiki

Tujuan akhirnya adalah membuat OpenClaw menjalankan skenario tanpa Anda harus mengingatkannya setiap kali.

Misalnya, OpenClaw mengedit handler yang membangun respons checkout. Dengan aturan di AGENTS.md, siklusnya menjadi:

1. Agen mengedit kode.
2. Agen menjalankan skenario Apidog terhadap staging.
3. Agen membaca kode keluar dan output assertion.
4. Jika hasilnya hijau, agen melanjutkan.
5. Jika hasilnya merah, agen membaca kegagalan—misalnya kode status, field yang hilang, atau nilai yang tidak sesuai.
6. Agen mencoba perbaikan dan menjalankan tes kembali.

Tes API kemudian menjadi bagian dari siklus edit-tes-perbaiki yang sama dengan tes unit.

Model ini adalah delegasikan-lalu-verifikasi: OpenClaw menjalankan perintah dan membaca hasilnya, sementara Anda tetap membangun skenario secara visual di Apidog serta memeriksa bahwa agen menafsirkan kode keluar dengan benar.

Untuk pola yang lebih luas, lihat cara menggunakan agen AI untuk pengujian API dan perangkat pengujian AI Apidog.

Verifikasi bahwa OpenClaw benar-benar menjalankan CLI

Jangan hanya menerima ringkasan agen. Verifikasi tiga hal berikut.

1. Pastikan perintah benar-benar dijalankan

Transkrip OpenClaw harus menampilkan perintah eksekusi dan output-nya. Cari baris seperti:

apidog run ...

Lalu pastikan output hasil tes muncul setelahnya.

Jika OpenClaw mengatakan bahwa tes sudah dijalankan tetapi tidak ada perintah atau output mentah di transkrip, minta agen menjalankannya kembali dan tampilkan output mentahnya.

2. Periksa kode keluar

Tanyakan secara langsung:

What was the exit code of that apidog run command?

apidog run mengembalikan:

• 0 jika seluruh assertion berhasil;
• nilai non-nol jika ada assertion yang gagal.

Kode keluar adalah gerbang lulus/gagal yang dapat digunakan OpenClaw maupun pipeline CI. Jika ringkasan agen mengatakan “tes berhasil” tetapi kode keluarnya non-nol, gunakan kode keluar sebagai sumber kebenaran.

3. Pastikan ID skenario dan lingkungan benar

Jika eksekusi gagal dengan pesan seperti scenario not found, OpenClaw mungkin menggunakan ID yang salah.

Bandingkan nilai berikut:

• -t di perintah yang dijalankan;
• -e di perintah yang dijalankan;
• nilai di AGENTS.md;
• perintah yang dihasilkan pada tab CI/CD Apidog.

Gunakan ID di AGENTS.md sebagai instruksi tetap yang harus diikuti agen.

Opsional: Hubungkan server Apidog MCP

Menjalankan apidog run melalui alat eksekusi sudah mencakup sebagian besar kebutuhan pengujian. Jika Anda ingin agen juga dapat membaca spesifikasi API saat menulis kode, gunakan Model Context Protocol (MCP).

OpenClaw mendukung server MCP. Tambahkan server dengan:

openclaw mcp add <name>

Perintah tersebut menulis definisi server ke:

~/.openclaw/openclaw.json

Konfigurasinya berada di bawah mcp.servers dan mendukung flag stdio seperti --command serta --arg. Lihat dokumentasi MCP OpenClaw.

Server Apidog MCP mengekspos spesifikasi API melalui MCP. Pembagian tanggung jawabnya sederhana:

• Apidog CLI menjalankan tes.
• Apidog MCP memberi agen akses ke spesifikasi API saat menulis kode.

Troubleshooting

OpenClaw mengabaikan blok AGENTS.md

Jika agen menjalankan perintah generik atau tidak menjalankan perintah sama sekali, pastikan file dimuat dari ruang kerja aktif.

Periksa hal berikut:

1. Blok Apidog berada di AGENTS.md dalam workspace yang digunakan agen.
2. Aturan tidak tersimpan di subtree yang tidak relevan.
3. Konfigurasi agents.list[].workspace mengarah ke proyek yang benar.
4. Mulai ulang sesi OpenClaw untuk memaksa pembacaan ulang.

OpenClaw mendukung AGENTS.md yang berskala per direktori, sehingga lokasi file memengaruhi apakah aturan diterapkan.

Eksekusi diblokir oleh izin

Jika apidog run tidak pernah berjalan, periksa pengaturan tools.exec.

Kebijakan default OpenClaw dapat menolak atau menahan eksekusi di balik allowlist. Gunakan mode auto atau tambahkan apidog ke allowlist untuk mengizinkan perintah ini tanpa membuka semua akses shell.

Untuk pendekatan yang lebih terbatas, baca panduan instalasi OpenClaw yang aman.

Agen mencoba meneruskan access token

Jika OpenClaw menambahkan --access-token, ia mungkin menebak berdasarkan contoh publik.

Pastikan AGENTS.md menyatakan dengan jelas:

Mesin sudah diautentikasi dengan `apidog login`. Jangan gunakan `--access-token`.

Jangan pernah menyimpan token asli di AGENTS.md. Untuk pola autentikasi yang benar, lihat autentikasi Apidog CLI.

Agen menciptakan flag yang tidak ada

Pesan unknown option berarti OpenClaw menggunakan flag yang tidak didukung oleh versi CLI Anda.

Jalankan:

apidog run --help

Gunakan flag yang ditampilkan oleh versi terinstal tersebut, bukan flag yang ditebak agen.

Agen melaporkan lulus, tetapi eksekusi gagal

Jika ringkasan agen tidak sesuai dengan kode keluar, kode keluar selalu menang.

Pastikan aturan berikut tetap ada di AGENTS.md:

Kode keluar 0 berarti lulus. Kode keluar non-nol berarti gagal.

Pola yang sama juga berlaku untuk agen lain. Lihat Apidog CLI di Codex dan perbandingan Claude Code vs OpenClaw.

Dari agen harian ke siklus yang teruji

Ringkasnya:

1. Instal apidog-cli mengikuti panduan instalasi.
2. Tambahkan aturan Apidog ke AGENTS.md.
3. Salin perintah apidog run dari tab CI/CD skenario Apidog.
4. Atur tools.exec agar perintah dapat berjalan.
5. Verifikasi perintah, output, dan kode keluar dari setiap eksekusi.

Dengan pengaturan ini, OpenClaw dapat menjalankan tes API dan membaca hasilnya di dalam siklus yang sama saat ia mengedit kode. Endpoint yang rusak dapat terdeteksi ketika agen masih mengerjakan perubahan, bukan setelah perubahan dikirim.

Tes yang hanya ada di GUI berjalan saat manusia mengklik. Perintah satu baris dapat berjalan kapan pun OpenClaw memutuskan bahwa perubahan perlu diverifikasi. Anda tetap membuat skenario secara visual di Apidog, sementara agen menjalankannya sebagai bagian dari alur kerja pengembangan.

Unduh Apidog, buat satu skenario, masukkan perintah apidog run ke AGENTS.md, lalu gunakan hasilnya sebagai gerbang sebelum perubahan dianggap selesai. Untuk menerapkan gerbang yang sama di pipeline tanpa agen, baca Apidog CLI di GitHub Actions.