OpenClaw là một vòng lặp: nó đọc không gian làm việc của bạn, chạy các lệnh shell thông qua công cụ exec của nó, đọc đầu ra và quyết định phải làm gì tiếp theo. Vậy tại sao các bài kiểm thử API của bạn không nằm trong vòng lặp đó? Chúng nằm trong Apidog phía sau giao diện người dùng đồ họa (GUI), chỉ chạy khi ai đó nhớ nhấp vào. Agent của bạn không bao giờ chạm đến chúng.
Giải pháp là một khối cấu hình. Apidog CLI là một gói npm, apidog-cli, chạy các kịch bản kiểm thử bạn đã xây dựng trong Apidog trực tiếp từ một terminal. Sau khi CLI được cài đặt và OpenClaw biết nó tồn tại, agent của bạn sẽ chạy một kịch bản Apidog theo cách tương tự như cách nó chạy các bài kiểm thử đơn vị của bạn: thực thi lệnh, đọc mã thoát, sửa mã nếu nó báo lỗi (màu đỏ).
Hướng dẫn này bao gồm phần dành riêng cho OpenClaw mà hướng dẫn cài đặt chung bỏ qua: nơi đặt các quy tắc Apidog để agent lưu giữ chúng, cách công cụ exec của OpenClaw thực sự chạy apidog run và cách đọc kết quả.
Nếu bạn chưa cài đặt CLI, hãy làm điều đó trước. Cách cài đặt Apidog CLI với một AI coding agent sẽ hướng dẫn qua việc cài đặt npm, xác thực và lần chạy đầu tiên. Bài viết này giả định rằng apidog --version in ra một số và tài khoản Apidog của bạn đã đăng nhập.
Bài viết này nói về OpenClaw nào
OpenClaw là một AI agent mã nguồn mở, ưu tiên chạy cục bộ trên máy của bạn. Nó có một không gian làm việc, một bộ kỹ năng và một công cụ exec để chạy các lệnh shell thực. Nó không phải là một plugin hoàn thành mã hay một chatbot được lưu trữ. Nếu bạn đã chạy openclaw cục bộ và theo dõi nó chỉnh sửa tệp và thực thi lệnh, bạn đang ở đúng nơi. Để thiết lập tổng thể hơn, hãy xem tự động hóa quy trình làm việc phát triển OpenClaw và hướng dẫn về cài đặt OpenClaw an toàn trước khi bạn giao bất kỳ lệnh nào cho nó.
Sự khác biệt này quan trọng vì OpenClaw học các quy tắc dự án từ các tệp trong không gian làm việc, và cơ chế đó biến một lần "chạy kiểm thử của tôi" thành một thứ mà OpenClaw tự động thực hiện. Cơ chế đó là AGENTS.md.
Bước 1: Thêm các quy tắc Apidog vào AGENTS.md
OpenClaw đọc các tệp trong không gian làm việc như các hướng dẫn cố định và đưa chúng vào ngữ cảnh của agent. Tệp bạn muốn là AGENTS.md, sổ tay quy tắc thủ tục cho biết agent phải làm gì và như thế nào. Hãy coi nó như CLAUDE.md cho Claude Code; OpenClaw thậm chí còn đi kèm một mẫu mặc định mà bạn sao chép vào không gian làm việc của mình, và nó coi một symlink CLAUDE.md cùng cấp là cùng một tệp. Không gian làm việc mặc định là ~/.openclaw/workspace, nhưng bạn có thể chỉ định một agent vào thư mục dự án của mình bằng agents.list[].workspace, và OpenClaw hỗ trợ các tệp AGENTS.md có phạm vi cho mỗi thư mục con (xem tài liệu tham khảo AGENTS.md của OpenClaw).
Thêm một khối ngắn vào AGENTS.md của bạn:
## 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.
Đây là lý do tại sao bạn viết CLI vào AGENTS.md thay vì đề cập nó trong cuộc trò chuyện. Một ID kịch bản được gõ vào phiên sẽ biến mất khi phiên kết thúc. Một ID trong AGENTS.md sẽ có mặt cho mọi thành viên trong nhóm và mọi lần chạy OpenClaw từ bây giờ.
Bước 2: Lấy lệnh từ Apidog
Bạn không cần phải viết ID kịch bản bằng tay. Mở kịch bản kiểm thử trong Apidog, chuyển đến tab CI/CD của nó và sao chép lệnh đã tạo. Nó trông như thế này:
apidog run -t 1234567 -e 890123 -r cli
-t là kịch bản kiểm thử, -e là môi trường, và -r cli là bộ báo cáo. Dán các ID thực vào khối AGENTS.md từ Bước 1 để OpenClaw luôn gọi đúng kịch bản với đúng môi trường. Hướng dẫn đầy đủ về Apidog CLI và tài liệu tham khảo lệnh apidog run bao gồm mọi cờ nếu bạn muốn điều chỉnh nó.
Bước 3: Yêu cầu agent chạy kiểm thử
Khi khối đã được đặt đúng chỗ, hãy khởi động OpenClaw cho dự án của bạn và thực hiện một thay đổi liên quan đến API của bạn, hoặc chỉ yêu cầu nó chạy kiểm tra. Vì AGENTS.md đã nằm trong ngữ cảnh, agent biết CLI tồn tại và sẽ phát lệnh apidog run thông qua công cụ exec của nó.
Công cụ exec chạy các lệnh shell trong không gian làm việc và OpenClaw kiểm soát nó bằng một chế độ quyền. Các chế độ là deny, allowlist, ask, auto và full (được ghi lại trên trang chế độ quyền của OpenClaw). Đối với một coding agent, auto là cài đặt hợp lý: các lệnh trong danh sách cho phép (allowlist) chạy mà không cần nhắc, và bất kỳ lệnh nào khác đều phải trải qua xem xét trước khi nó hỏi bạn. Nếu chế độ của bạn là ask, OpenClaw sẽ tạm dừng và yêu cầu phê duyệt trước khi chạy apidog run; hãy phê duyệt một lần, hoặc thêm lệnh vào danh sách cho phép của bạn để một kiểm thử chỉ đọc đối với môi trường staging tự động chạy. Đặt chế độ dưới tools.exec trong openclaw.json.
Bước 4: Đọc báo cáo bên trong OpenClaw
Bộ báo cáo -r cli in ra kết quả từng bước trong terminal: mỗi yêu cầu, mỗi xác nhận và xác nhận nào đã thất bại với giá trị mong đợi so với giá trị thực tế. Phân tích chi tiết đó là những gì OpenClaw đọc để quyết định bước tiếp theo, vì vậy hãy giữ cli trong danh sách.
Khi bạn muốn một báo cáo có thể mở trong trình duyệt hoặc gửi cho đồng đội, hãy thêm bộ báo cáo HTML:
apidog run -t 1234567 -e 890123 -r cli,html
Bộ báo cáo html ghi một tệp độc lập vào ./apidog-reports. Giữ cli cùng với nó để OpenClaw vẫn nhận được đầu ra trực tiếp. Đối với định dạng JUnit mà các bảng điều khiển CI phân tích và mọi bộ báo cáo khác, hãy xem hướng dẫn báo cáo kiểm thử Apidog CLI.
Kiểm thử OpenClaw trong vòng lặp của chính nó
Điểm mấu chốt là điều gì xảy ra khi bạn ngừng yêu cầu và OpenClaw tự chạy kịch bản vì AGENTS.md đã hướng dẫn nó làm vậy.
Hãy hình dung OpenClaw chỉnh sửa một bộ xử lý xây dựng phản hồi thanh toán. Vòng lặp của nó thay đổi: nó chỉnh sửa mã, sau đó, thay vì tuyên bố thành công, nó chạy kịch bản Apidog của bạn trên môi trường staging, đọc mã thoát và hành động dựa trên đó. Xanh lá cây (đạt), nó tiếp tục. Đỏ (lỗi), nó mở báo cáo, đọc xác nhận nào đã thất bại (mã trạng thái, trường bị thiếu, giá trị sai), thử sửa lỗi và chạy lại. Kiểm thử API trở thành một phần của cùng một vòng lặp chỉnh sửa-kiểm thử-sửa lỗi mà OpenClaw đã chạy các kiểm thử đơn vị của bạn. Bạn đã viết một hướng dẫn và agent đã tích hợp lệnh vào cách nó hoạt động.
Đây là mô hình ủy quyền-sau đó-xác minh giúp mọi quy trình làm việc của agent an toàn. OpenClaw chạy lệnh và đọc kết quả; bạn tiếp tục tạo kịch bản trực quan trong Apidog và kiểm tra ngẫu nhiên xem agent có đọc mã thoát một cách trung thực hay không. Để biết mẫu rộng hơn, hãy xem cách sử dụng AI agent cho kiểm thử API và bộ công cụ kiểm thử AI Apidog.
Xác minh OpenClaw có thực sự đang chạy CLI
Các agent báo cáo thành công mà chúng không thực sự đạt được, và OpenClaw cũng không ngoại lệ. Có ba cách kiểm tra, theo thứ tự mức độ thường xuyên chúng phát hiện vấn đề.
Đầu tiên, hãy xác nhận rằng lệnh đã chạy. Bản ghi của OpenClaw hiển thị các lệnh exec mà nó đã thực thi và đầu ra của chúng. Tìm dòng apidog run ... theo nghĩa đen và kết quả bên dưới nó. Nếu OpenClaw nói nó đã chạy các bài kiểm thử nhưng bạn không thấy lệnh, thì nó đã tóm tắt một cái gì đó mà nó chưa bao giờ làm. Yêu cầu nó chạy lại và hiển thị đầu ra thô.
Thứ hai, xác nhận mã thoát, cái quan trọng. Hỏi trực tiếp nó:
What was the exit code of that apidog run command?
Lệnh apidog run thoát với mã 0 khi mọi xác nhận đều vượt qua và mã khác 0 khi có bất kỳ lỗi nào. Hành vi đơn giản đó cho phép OpenClaw, hoặc một pipeline, coi lần chạy là một cổng kiểm tra rõ ràng. Khi văn bản nói "các bài kiểm thử đã vượt qua" nhưng mã thoát khác 0, thì mã thoát mới là đúng.
Thứ ba, xác nhận nó đã sử dụng kịch bản thực. Nếu một lần chạy thất bại với lỗi "scenario not found" (không tìm thấy kịch bản), OpenClaw có thể đã tự tạo hoặc nhớ sai một ID. Hãy kiểm tra lại các giá trị -t và -e so với AGENTS.md và lệnh mà Apidog đã tạo trong tab CI/CD. Các ID trong AGENTS.md là sự thật.
Tùy chọn: Kết nối máy chủ Apidog MCP
Chạy apidog run thông qua công cụ exec đáp ứng hầu hết những gì bạn cần. Một lộ trình khác đi xa hơn: Giao thức Ngữ cảnh Mô hình (Model Context Protocol).
OpenClaw hỗ trợ các máy chủ MCP. Bạn thêm một máy chủ bằng lệnh openclaw mcp add <name>, lệnh này ghi định nghĩa máy chủ vào ~/.openclaw/openclaw.json dưới mục mcp.servers và chấp nhận các cờ stdio như --command và --arg (xem tài liệu MCP của OpenClaw). Máy chủ Apidog MCP hiển thị các đặc tả API của bạn qua MCP, để OpenClaw có thể đọc lược đồ của bạn trong khi nó viết mã, chứ không chỉ sau khi thực hiện. Việc phân chia công việc rõ ràng: CLI chạy các kiểm thử, và MCP cung cấp đặc tả cho agent.
Khi OpenClaw mắc lỗi
Một vài lỗi thường xuất hiện trong quá trình thiết lập.
Nó bỏ qua khối AGENTS.md. Nếu OpenClaw chạy một lệnh chung chung hoặc không chạy gì cả, tệp có thể không được tải vào ngữ cảnh. Xác nhận khối nằm trong AGENTS.md thuộc không gian làm việc đang hoạt động của agent, và nhớ rằng OpenClaw duyệt các tệp AGENTS.md có phạm vi theo thư mục, vì vậy một quy tắc bị chôn vùi trong cây con sai sẽ bị bỏ qua. Khởi động lại phiên sẽ buộc đọc lại từ đầu.
Nó không bao giờ chạy bất cứ thứ gì vì exec bị chặn. Kể từ khi chính sách mặc định của OpenClaw thắt chặt, exec có thể bị từ chối hoặc bị giữ lại sau một danh sách cho phép (allowlist). Nếu apidog run bị bỏ qua một cách âm thầm, hãy kiểm tra chế độ quyền của bạn dưới tools.exec và chuyển sang auto hoặc thêm apidog vào allowlist. Xem hướng dẫn cài đặt OpenClaw an toàn để biết cách chỉ cho phép lệnh này mà không mở mọi thứ.
Nó vẫn truyền một mã thông báo truy cập. Nếu OpenClaw cố gắng thêm --access-token, nó đang đoán từ các ví dụ công khai. Khối đã nói với nó không làm vậy, vì máy đã được xác thực qua apidog login. Hãy củng cố dòng đó và không bao giờ đặt một mã thông báo thực vào AGENTS.md; để biết mẫu đúng, hãy xem xác thực Apidog CLI.
Nó tự tạo ra một cờ. Lỗi "unknown option" (tùy chọn không xác định) có nghĩa là OpenClaw đã đoán một cờ mà phiên bản của bạn không có. Hãy bảo nó chạy apidog run --help và sao chép cờ chính xác từ đó, cờ này luôn đúng cho phiên bản đã cài đặt của bạn.
Nó báo cáo thành công trên một lần chạy thất bại. Đây là lỗi tốn kém nhất và là lý do quy tắc mã thoát nằm trong AGENTS.md của bạn và bước xác minh của bạn. Khi tóm tắt và mã thoát không khớp, mã thoát sẽ thắng. Nếu bạn đã sử dụng một agent khác cho việc này, quy tắc tương tự vẫn đúng; cách tiếp cận này phản ánh những gì chúng tôi trình bày trong Apidog CLI trong Codex và sự khác biệt trong Claude Code vs OpenClaw.
Từ một agent hàng ngày đến một vòng lặp được kiểm thử
Đó là thiết lập. Cài đặt apidog-cli một lần theo hướng dẫn cài đặt, thêm một khối Apidog ngắn vào AGENTS.md trong không gian làm việc của bạn, đặt chế độ quyền exec để lệnh có thể chạy, và OpenClaw sẽ biết cách chạy các bài kiểm thử API của bạn và đọc kết quả bên trong cùng một vòng lặp mà nó đã sử dụng để chỉnh sửa mã. Một điểm cuối bị hỏng sẽ được phát hiện khi OpenClaw vẫn đang làm việc trên thay đổi, chứ không phải sau khi nó được triển khai.
Một kiểm thử phía sau giao diện người dùng đồ họa (GUI) chạy khi một người nhấp; một lệnh một dòng chạy bất cứ khi nào OpenClaw quyết định. Bạn tiếp tục xây dựng các kịch bản một cách trực quan trong Apidog, và agent của bạn sẽ chạy chúng mà bạn không cần phải theo dõi. Tải Apidog, xây dựng một kịch bản, đặt lệnh apidog run của nó vào AGENTS.md, và xem OpenClaw sẽ nhận diện nó trong lần thay đổi tiếp theo. Khi bạn muốn cùng một cổng kiểm tra trong một pipeline mà không cần agent có mặt, Apidog CLI trong GitHub Actions sẽ bao gồm các bí mật, bộ báo cáo và cơ chế cổng mã thoát.