Cách sử dụng Apidog CLI trong OpenClaw

OpenClaw hoạt động theo một vòng lặp: đọc không gian làm việc, chạy lệnh shell qua công cụ exec, đọc đầu ra, rồi quyết định bước tiếp theo. Nếu các bài kiểm thử API chỉ nằm trong giao diện Apidog, agent sẽ không thể tự chạy chúng. Kết nối Apidog CLI vào vòng lặp này để OpenClaw có thể chạy kiểm thử, kiểm tra mã thoát và xử lý lỗi ngay khi chỉnh sửa mã.

Dùng thử Apidog ngay hôm nay

Apidog CLI là gói npm apidog-cli, cho phép chạy các kịch bản kiểm thử đã tạo trong Apidog ngay từ terminal. Sau khi cài CLI và khai báo quy tắc cho OpenClaw, agent có thể thực hiện quy trình tương tự kiểm thử đơn vị:

1. Chạy apidog run.
2. Đọc đầu ra CLI.
3. Kiểm tra mã thoát.
4. Nếu kiểm thử thất bại, đọc xác nhận lỗi, sửa mã và chạy lại.

Bài viết này tập trung vào phần tích hợp với OpenClaw: đặt quy tắc Apidog ở đâu, cách exec chạy apidog run, và cách xác minh kết quả.

Trước hết, hãy bảo đảm CLI đã được cài đặt, xác thực và hoạt động:

apidog --version

Nếu chưa hoàn tất bước này, xem cách cài đặt Apidog CLI với AI coding agent. Bài viết này giả định máy đã đăng nhập Apidog và lệnh trên in ra phiên bản CLI.

OpenClaw được đề cập trong bài viết này

OpenClaw là AI agent mã nguồn mở, ưu tiên chạy cục bộ. Nó có:

• Không gian làm việc (workspace).
• Tệp hướng dẫn cho agent.
• Công cụ exec để thực thi lệnh shell.
• Chế độ quyền kiểm soát các lệnh được phép chạy.

Đây không phải plugin hoàn thành mã hoặc chatbot lưu trữ. Nếu bạn đang chạy openclaw cục bộ và thấy nó chỉnh sửa tệp, gọi shell command, bạn đang dùng đúng loại công cụ.

Trước khi cho agent chạy lệnh trong môi trường phát triển, hãy tham khảo:

• Tự động hóa quy trình làm việc phát triển OpenClaw
• Hướng dẫn cài đặt OpenClaw an toàn

Điểm quan trọng là OpenClaw đọc hướng dẫn dự án từ các tệp trong workspace. Để biến “hãy chạy kiểm thử API” thành hành vi lặp lại được, hãy dùng AGENTS.md.

Bước 1: Thêm quy tắc Apidog vào AGENTS.md

OpenClaw đưa nội dung trong AGENTS.md vào ngữ cảnh agent như các hướng dẫn cố định. Tệp này đóng vai trò như sổ tay thủ tục cho dự án.

Theo tài liệu OpenClaw:

• Workspace mặc định là ~/.openclaw/workspace.
• Bạn có thể cấu hình workspace riêng cho agent qua agents.list[].workspace.
• OpenClaw hỗ trợ AGENTS.md theo phạm vi thư mục con.
• Một symlink CLAUDE.md cùng cấp cũng được xem như cùng loại tệp hướng dẫn.

Xem thêm tài liệu tham khảo AGENTS.md của OpenClaw.

Thêm khối sau vào AGENTS.md của workspace hoặc thư mục dự án đang hoạt động:

## Kiểm thử API với Apidog

- Để chạy kiểm thử API, sử dụng Apidog CLI: `apidog run -t <scenario_id> -e <env_id> -r cli`.
- Mã thoát 0 có nghĩa là mọi xác nhận đều vượt qua. Mã khác 0 có nghĩa là có lỗi. Hãy coi đây là cổng đạt/không đạt.
- Máy đã được xác thực bằng `apidog login`. Không bao giờ thêm cờ --access-token và không bao giờ đặt token vào tệp này.
- Nếu một cờ trông lạ, hãy chạy `apidog run --help` thay vì đoán.

Sau đó, thay <scenario_id> và <env_id> bằng các ID thực của bạn.

Đặt lệnh trong AGENTS.md thay vì chỉ gửi trong chat vì:

• Hướng dẫn trong chat mất khi phiên làm việc kết thúc.
• AGENTS.md được dùng lại trong các phiên OpenClaw tiếp theo.
• Cả nhóm có cùng quy tắc chạy kiểm thử.
• Agent ít có khả năng tự đoán sai lệnh, ID hoặc cờ CLI.

Bước 2: Sao chép lệnh từ Apidog

Không cần tự nhập ID kịch bản bằng tay.

1. Mở kịch bản kiểm thử trong Apidog.
2. Chuyển đến tab CI/CD.
3. Sao chép lệnh được Apidog tạo sẵn.

Lệnh thường có dạng:

apidog run -t 1234567 -e 890123 -r cli

Trong đó:

• -t: ID kịch bản kiểm thử.
• -e: ID môi trường.
• -r cli: bộ báo cáo đầu ra cho terminal.

Dán lệnh thực vào AGENTS.md để OpenClaw luôn chạy đúng kịch bản trên đúng môi trường.

Nếu cần điều chỉnh cờ, xem:

• Hướng dẫn đầy đủ về Apidog CLI
• Tài liệu tham khảo lệnh apidog run

Bước 3: Cho OpenClaw chạy kiểm thử

Sau khi cập nhật AGENTS.md, khởi động OpenClaw trong workspace của dự án. Bạn có thể:

• Yêu cầu agent chạy kiểm thử API.
• Yêu cầu agent sửa một thay đổi liên quan đến API.
• Đưa quy tắc vào AGENTS.md để agent chạy kiểm thử trước khi kết luận thay đổi đã hoàn tất.

OpenClaw sẽ gọi lệnh qua công cụ exec:

apidog run -t 1234567 -e 890123 -r cli

Cấu hình quyền cho exec

OpenClaw kiểm soát lệnh shell bằng chế độ quyền. Các chế độ gồm:

• deny
• allowlist
• ask
• auto
• full

Xem trang chế độ quyền của OpenClaw.

Với coding agent, auto là lựa chọn hợp lý:

• Lệnh trong allowlist được chạy không cần hỏi.
• Lệnh ngoài allowlist cần được xem xét trước khi OpenClaw yêu cầu phê duyệt.
• Bạn vẫn giữ quyền kiểm soát các thao tác không mong muốn.

Cấu hình chế độ này dưới tools.exec trong openclaw.json.

Nếu dùng chế độ ask, OpenClaw sẽ dừng trước khi chạy apidog run. Bạn có thể phê duyệt từng lần hoặc thêm apidog vào allowlist để các kiểm thử chỉ đọc trên môi trường staging có thể chạy tự động.

Bước 4: Đọc báo cáo trong OpenClaw

Bộ báo cáo -r cli in kết quả chi tiết vào terminal, bao gồm:

• Các request đã chạy.
• Từng assertion.
• Assertion thất bại.
• Giá trị mong đợi và giá trị thực tế.

Đây là dữ liệu OpenClaw cần đọc để quyết định có tiếp tục hay sửa lỗi. Vì vậy, hãy giữ cli trong danh sách reporter.

Nếu cần báo cáo mở trong trình duyệt hoặc gửi cho đồng đội, thêm reporter HTML:

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

Reporter html tạo tệp báo cáo độc lập trong:

./apidog-reports

Vẫn nên giữ cli cùng với html, vì agent cần đầu ra trực tiếp trong terminal để xử lý kết quả ngay trong phiên làm việc.

Để dùng JUnit hoặc các định dạng khác cho CI, xem hướng dẫn báo cáo kiểm thử Apidog CLI.

Đưa kiểm thử API vào vòng lặp của OpenClaw

Mục tiêu không chỉ là yêu cầu agent chạy kiểm thử một lần. Mục tiêu là để agent tự chạy kiểm thử khi quy trình sửa mã yêu cầu.

Ví dụ, OpenClaw chỉnh sửa bộ xử lý tạo phản hồi thanh toán:

1. Agent thay đổi mã.
2. Agent chạy kịch bản Apidog trên môi trường staging.
3. Agent kiểm tra mã thoát.
4. Nếu mã thoát là 0, agent tiếp tục.
5. Nếu mã thoát khác 0, agent đọc assertion lỗi.
6. Agent sửa lỗi liên quan đến mã trạng thái, trường bị thiếu hoặc dữ liệu sai.
7. Agent chạy lại kiểm thử.

Khi đó, kiểm thử API trở thành một phần của vòng lặp:

chỉnh sửa → kiểm thử → đọc lỗi → sửa lỗi → kiểm thử lại

Đây là mô hình ủy quyền rồi xác minh: OpenClaw thực thi lệnh và đọc kết quả, còn bạn vẫn xây dựng, duy trì và kiểm tra ngẫu nhiên các kịch bản trực quan trong Apidog.

Để tìm hiểu thêm, xem:

• Cách sử dụng AI agent cho kiểm thử API
• Bộ công cụ kiểm thử AI Apidog

Xác minh OpenClaw thực sự đã chạy CLI

Agent có thể báo cáo kiểm thử thành công dù lệnh chưa thực sự được chạy. Kiểm tra theo ba bước sau.

1. Xác nhận lệnh đã được thực thi

Bản ghi OpenClaw phải hiển thị lệnh exec và đầu ra của nó. Tìm chính xác dòng:

apidog run ...

Sau đó đọc phần kết quả ngay bên dưới.

Nếu OpenClaw nói đã chạy kiểm thử nhưng không có lệnh thực tế trong bản ghi, hãy yêu cầu nó chạy lại và hiển thị đầu ra thô.

2. Kiểm tra mã thoát

Hỏi trực tiếp agent:

Mã thoát của lệnh apidog run đó là gì?

Quy tắc là:

Mã thoát	Ý nghĩa
0	Mọi assertion đều đạt
Khác 0	Có ít nhất một kiểm thử hoặc assertion lỗi

Nếu phần tóm tắt nói “kiểm thử đã đạt” nhưng mã thoát khác 0, hãy tin mã thoát.

3. Xác nhận đúng kịch bản và môi trường

Lỗi như scenario not found thường cho thấy agent đã dùng ID sai hoặc tự tạo ID.

Kiểm tra lại:

• Giá trị sau -t.
• Giá trị sau -e.
• Lệnh trong AGENTS.md.
• Lệnh được Apidog tạo trong tab CI/CD.

Các ID được lưu trong AGENTS.md nên là nguồn thông tin chuẩn cho agent.

Tùy chọn: Kết nối máy chủ Apidog MCP

Chạy apidog run qua exec đáp ứng phần lớn nhu cầu kiểm thử. Nếu muốn agent có thể đọc đặc tả API trong lúc viết mã, bạn có thể dùng Model Context Protocol (MCP).

OpenClaw hỗ trợ máy chủ MCP. Bạn thêm máy chủ bằng:

openclaw mcp add <name>

Lệnh này ghi cấu hình máy chủ vào:

~/.openclaw/openclaw.json

dưới mục:

mcp.servers

OpenClaw hỗ trợ các cờ MCP qua stdio như --command và --arg. Xem tài liệu MCP của OpenClaw.

Máy chủ Apidog MCP cho phép agent truy cập đặc tả API qua MCP. Cách phân chia trách nhiệm nên rõ ràng:

• Apidog CLI: chạy kiểm thử API.
• Apidog MCP: cung cấp đặc tả API cho agent khi viết hoặc sửa mã.

Khắc phục lỗi thường gặp

OpenClaw bỏ qua AGENTS.md

Nếu OpenClaw chạy lệnh chung chung hoặc không chạy gì, AGENTS.md có thể không nằm trong ngữ cảnh hiện tại.

Kiểm tra:

1. Tệp nằm trong workspace thực tế của agent.
2. Quy tắc không bị đặt nhầm trong thư mục con không liên quan.
3. Agent đang dùng đúng agents.list[].workspace.
4. Khởi động lại phiên để buộc OpenClaw đọc lại hướng dẫn.

exec bị chặn

Nếu OpenClaw không chạy lệnh hoặc yêu cầu phê duyệt liên tục, kiểm tra tools.exec trong openclaw.json.

Các cách xử lý:

• Chuyển sang auto.
• Thêm apidog vào allowlist.
• Dùng ask nếu cần phê duyệt thủ công từng lần.

Xem hướng dẫn cài đặt OpenClaw an toàn để chỉ cho phép lệnh cần thiết mà không mở toàn bộ quyền shell.

Agent tự thêm --access-token

Nếu OpenClaw tự thêm --access-token, agent có thể đang suy đoán từ ví dụ công khai.

Hãy giữ quy tắc này trong AGENTS.md:

Máy đã được xác thực bằng `apidog login`. Không bao giờ thêm `--access-token`.

Không đặt token thật trong AGENTS.md. Xem xác thực Apidog CLI để dùng cơ chế xác thực phù hợp.

Agent tự tạo cờ CLI

Lỗi unknown option nghĩa là agent đã dùng cờ không tồn tại trong phiên bản CLI đang cài.

Yêu cầu agent chạy:

apidog run --help

Sau đó chỉ dùng các cờ được hiển thị trong đầu ra đó.

Agent báo thành công khi kiểm thử thất bại

Đây là lỗi nghiêm trọng nhất. Luôn ưu tiên mã thoát hơn phần tóm tắt bằng ngôn ngữ tự nhiên.

Nếu:

Tóm tắt: kiểm thử đạt
Mã thoát: 1

thì kết quả thực tế là thất bại.

Cách kiểm tra này cũng áp dụng cho các coding agent khác. Xem thêm Apidog CLI trong Codex và Claude Code vs OpenClaw.

Từ agent hằng ngày đến vòng lặp được kiểm thử

Thiết lập gồm bốn phần:

1. Cài apidog-cli.
2. Đăng nhập bằng apidog login.
3. Thêm lệnh apidog run vào AGENTS.md.
4. Cấu hình quyền tools.exec để OpenClaw có thể chạy lệnh.

Sau đó, OpenClaw có thể chạy kiểm thử API và đọc kết quả trong cùng vòng lặp mà nó dùng để chỉnh sửa mã. Lỗi endpoint sẽ được phát hiện khi agent còn đang làm việc trên thay đổi, thay vì sau khi triển khai.

Kiểm thử nằm sau GUI chỉ chạy khi có người nhấp. Một lệnh CLI trong AGENTS.md có thể được OpenClaw chạy khi quy trình cần xác minh thay đổi.

Tiếp tục xây dựng kịch bản trực quan trong Apidog, sau đó đặt lệnh apidog run tương ứng vào AGENTS.md.

Tải Apidog, tạo kịch bản đầu tiên và tích hợp nó vào vòng lặp OpenClaw. Nếu cần đưa cùng cổng kiểm tra này vào CI mà không cần agent, xem Apidog CLI trong GitHub Actions.