How to Use the Apidog CLI in OpenClaw

OpenClaw is a loop: it reads your workspace, runs shell commands through its exec tool, reads the output, and decides what to do next. If your API tests only run from the Apidog GUI, they are outside that loop. The goal is to make them a normal command OpenClaw can execute, inspect, and use as a pass/fail gate.

Try Apidog today

The fix is a small workspace rule. The Apidog CLI, apidog-cli, runs the test scenarios you build in Apidog from the terminal. Once installed and documented in your OpenClaw workspace, the agent can run an Apidog scenario like any other test command: execute it, inspect the output and exit code, then fix failures.

This guide focuses on the OpenClaw-specific setup:

• Add persistent Apidog instructions to AGENTS.md.
• Configure exec permissions so OpenClaw can run apidog run.
• Use CLI output and exit codes as the API-test gate.

If you have not installed the CLI, do that first. How to install the Apidog CLI with an AI coding agent covers npm installation, authentication, and the first run.

This article assumes the following works and your account is signed in:

apidog --version

Which OpenClaw this is about

OpenClaw is an open-source, local-first AI agent that runs on your machine. It has a workspace, skills, and an exec tool for running shell commands. It is not a code-completion plugin or hosted chatbot.

If you have run openclaw locally, watched it edit files, and seen it execute commands, this setup applies to you. For broader setup guidance, review OpenClaw development workflow automation and secure OpenClaw installation before granting command access.

The important detail is that OpenClaw learns project rules from workspace files. Put the test command in those rules and it becomes a reusable instruction instead of a one-off chat request.

That rule file is AGENTS.md.

Step 1: Add Apidog rules to AGENTS.md

OpenClaw reads workspace files as standing instructions and adds them to the agent context. Use AGENTS.md as the procedural rulebook for your project.

The default workspace is ~/.openclaw/workspace, but you can point an agent at a project directory with agents.list[].workspace. OpenClaw also supports scoped AGENTS.md files in subdirectories. See OpenClaw’s AGENTS.md reference.

Add a block like this to the AGENTS.md in your active project workspace:

## 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.

Replace <scenario_id> and <env_id> with the IDs from your Apidog scenario.

Why put this in AGENTS.md instead of chat?

• Chat instructions disappear when the session ends.
• Workspace instructions apply to future OpenClaw runs.
• Teammates can review and reuse the same test command.
• OpenClaw can treat the API test as part of its normal edit-test-fix workflow.

Step 2: Copy the generated command from Apidog

You do not need to manually construct scenario IDs.

1. Open the test scenario in Apidog.
2. Go to the CI/CD tab.
3. Copy the generated command.

It looks like this:

apidog run -t 1234567 -e 890123 -r cli

The flags are:

Flag	Purpose
-t	Test scenario ID
-e	Environment ID
-r cli	CLI reporter for terminal output

Paste the real command, or its IDs, into the AGENTS.md rule from Step 1. This ensures OpenClaw runs the intended scenario against the intended environment.

For more options, see the complete Apidog CLI guide and the apidog run command reference.

Step 3: Let OpenClaw run the API test

Start OpenClaw in your project workspace, then either:

• Make a change that affects the API, or
• Ask the agent to run the API test explicitly.

Because AGENTS.md is already loaded, OpenClaw knows that apidog run is the required test command.

For example, you can prompt it with:

Update the checkout response handler, then run the configured Apidog API test and report the exit code.

OpenClaw executes commands through its exec tool. Exec behavior is controlled by permission modes:

• deny
• allowlist
• ask
• auto
• full

See OpenClaw’s permission modes documentation.

For coding workflows, auto is typically the practical option: allowlisted commands run without prompting, while other commands go through review.

Configure the mode under tools.exec in openclaw.json.

If you use ask, OpenClaw pauses before running:

apidog run -t 1234567 -e 890123 -r cli

Approve the command when prompted, or add apidog to the allowlist if this read-only staging test should run without repeated approval.

Step 4: Read the report and exit code

The -r cli reporter prints results directly to the terminal, including:

• Requests executed
• Assertions evaluated
• Failed assertions
• Expected versus actual values

OpenClaw can read that inline output and use it to decide what to do next. Keep cli in the reporter list even if you also generate a file-based report.

To generate an HTML report as well:

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

The html reporter writes a self-contained report to:

./apidog-reports

Keep cli alongside html so OpenClaw still receives readable terminal output.

For JUnit output and other reporter formats, see the Apidog CLI test reports guide.

Make API tests part of OpenClaw’s loop

Once the command is in AGENTS.md, OpenClaw can use API tests as part of its existing workflow:

1. Edit application code.
2. Run the Apidog scenario against staging.
3. Read the CLI output and exit code.
4. If the run passes, continue.
5. If the run fails, inspect the failed assertion.
6. Apply a fix and rerun the scenario.

For example, when editing a checkout-response handler, OpenClaw can detect a missing field, incorrect status code, or unexpected response value from the scenario output. Rather than declaring success after changing code, it can rerun the API test until the exit code is 0.

This is a delegate-then-verify workflow:

• You design and maintain test scenarios visually in Apidog.
• OpenClaw executes the scenario during implementation.
• The CLI exit code provides the pass/fail signal.
• You can still review the agent’s commands and output.

For the broader approach, see how to use AI agents for API testing and the Apidog AI test harness.

Verify OpenClaw actually ran the CLI

Do not rely only on an agent summary. Verify the command, output, and exit code.

1. Confirm the command was executed

OpenClaw’s transcript shows exec commands and their output. Look for the literal command:

apidog run ...

There should be output immediately after it.

If OpenClaw says tests passed but the transcript does not show the command, ask it to rerun the test and provide raw output.

2. Confirm the exit code

Ask directly:

What was the exit code of that apidog run command?

Interpret it as follows:

• Exit code 0: every assertion passed.
• Non-zero exit code: one or more assertions failed.

If an agent says “tests passed” but reports a non-zero exit code, treat the run as failed. The exit code is the gate.

3. Confirm the real scenario and environment were used

If Apidog returns a “scenario not found” error, OpenClaw may have used an incorrect or invented ID.

Check:

• The -t value in AGENTS.md
• The -e value in AGENTS.md
• The command generated in the Apidog CI/CD tab

The command stored in your workspace rules should be the source of truth.

Optional: Connect the Apidog MCP server

Running apidog run through exec covers the testing workflow. MCP adds specification context.

OpenClaw supports MCP servers. Add one with:

openclaw mcp add <name>

This writes the server definition to ~/.openclaw/openclaw.json under mcp.servers. It supports stdio options such as --command and --arg. See OpenClaw’s MCP documentation.

The Apidog MCP server exposes API specifications over MCP. This gives OpenClaw access to schema information while it writes code.

Use the two integrations for separate jobs:

• Apidog CLI: run scenarios and enforce test results.
• Apidog MCP server: provide API specification context to the agent.

Troubleshooting common setup failures

OpenClaw ignores the AGENTS.md block

If it runs a generic command or does not run API tests:

1. Confirm AGENTS.md belongs to the active agent workspace.
2. Check whether the rule is in the correct directory scope.
3. Remember that OpenClaw can load scoped AGENTS.md files by directory.
4. Restart the session to force a fresh workspace read.

A rule in the wrong subtree may not apply to the files OpenClaw is editing.

Exec is blocked

If OpenClaw never runs apidog run, inspect tools.exec permissions.

Possible fixes:

• Switch to auto.
• Add apidog to the exec allowlist.
• Approve the command when using ask.

See the secure OpenClaw installation guide for guidance on granting narrow command access without opening everything.

OpenClaw adds --access-token

Do not put tokens in AGENTS.md.

If the machine is already authenticated with:

apidog login

the agent should run the configured command without --access-token. Reinforce that instruction in the workspace rule if necessary.

For the supported authentication workflow, see Apidog CLI authentication.

OpenClaw invents a CLI flag

An unknown option error means the agent guessed a flag that your installed CLI version does not support.

Run:

apidog run --help

Then use the exact syntax shown by your installed version.

OpenClaw reports success after a failed run

This is the failure mode that matters most.

When the agent summary and exit code disagree:

The exit code wins.

Keep the exit-code rule in AGENTS.md, and always verify it after important runs. The same approach applies to other coding agents; see Apidog CLI in Codex and Claude Code vs OpenClaw.

From a daily agent to a tested loop

The setup is straightforward:

1. Install apidog-cli using the install guide.
2. Add the Apidog test command and exit-code rules to your workspace AGENTS.md.
3. Configure tools.exec so OpenClaw can run the command.
4. Verify the command, output, and exit code in the OpenClaw transcript.

Now OpenClaw can run API tests in the same loop it uses to edit and test code. Broken endpoints are caught while the agent is working on the change, rather than after deployment.

Build scenarios visually in Apidog, then put the generated apidog run command into AGENTS.md so OpenClaw can execute it automatically. Download Apidog to create your first scenario. For running the same gate in CI without an agent, see Apidog CLI in GitHub Actions.