Codex is a loop: it edits files, runs commands, reads the output, and decides what to do next. So why aren’t your API tests in that loop? They sit in Apidog behind a GUI, run when someone remembers to click. Your agent never touches them.
The fix is one config block. The Apidog CLI is an npm package, apidog-cli, that runs the test scenarios you built in Apidog straight from a terminal. Once the CLI is installed and Codex knows it exists, your agent runs an Apidog scenario the same way it runs your unit tests: fire the command, read the exit code, fix the code if it is red.
This guide covers the Codex-specific part the generic install guide skips: the exact line for your AGENTS.md, the prompt to hand Codex, how it runs apidog run inside its own loop, and how to read the result.
If you have not installed the CLI yet, do that first. How to install the Apidog CLI with an AI coding agent walks through the npm install, the access token, and the first run, with Codex doing the typing. This article assumes apidog --version prints a number and your Apidog account is authenticated.
Which Codex this is about
Both OpenAI Codex CLI and Codex App. It runs locally, reads your repository, edits files, and executes shell commands inside a sandbox, asking for approval based on your permission mode. It is not the old Codex code-completion API. If you run codex and get a full-screen interface showing diffs and command output, you are in the right place. The OpenAI Codex CLI guide covers the basics.
The distinction matters because Codex has its own way of learning project rules, and that mechanism turns a one-off “run my tests” into something Codex reaches for on its own. That mechanism is AGENTS.md.
The mechanism: AGENTS.md, not a chat reminder
Codex reads AGENTS.md files before it starts working. Think of it as CLAUDE.md for Claude Code: a plain Markdown file of project instructions that Codex loads into context at the start of every session. It builds the instruction set by walking from your Git root down to your current directory, concatenating each AGENTS.md root-first, so closer files win on conflicts. There is also a global ~/.codex/AGENTS.md. For our purpose, one file at the repo root is enough.
This is why you write the CLI into AGENTS.md instead of mentioning it in chat. A scenario ID typed into chat is gone when the session ends. One in AGENTS.md is there for every teammate and every Codex run from now on.
Step 1: Give Codex the prompt and watch it run
With the block in place, start Codex in your repo:
Codex loads AGENTS.md as it starts, so it already knows the CLI is there. Make a change that touches your API, or ask it to run the check:
Codex issues the apidog run command from your AGENTS.md. In its default Auto mode, it can read files, edit them, and run commands inside the working directory on its own, so a plain apidog run usually executes without a prompt. The -r cli reporter prints a step-by-step result and summary right in the terminal, where you watch each request and assertion as it happens.
You want to see the run executing and Codex reporting back both the summary and the exit code. If your permission mode is Read-only, Codex pauses and asks before running; approve it, or change the mode with /permissions inside the session. Auto is the sensible default, since a read-only test scenario against staging is exactly the kind of safe, in-workspace command that mode is built for.
Step 2: Codex testing inside its own loop
The point is what happens when you stop asking and Codex runs the scenario on its own because AGENTS.md told it to.
Picture Codex editing a handler that builds a checkout response. Its loop changes: it edits the code, then, instead of declaring victory, runs your Apidog scenario against staging, reads the exit code, and acts on it. Green, it moves on. Red, it opens the report, reads which assertion failed (the status code, the missing field, the wrong value), tries a fix, and re-runs. The API test becomes part of the same edit-test-fix loop Codex already runs your unit tests through. You wrote one instruction and Codex folded the command into how it already works.
This is the delegate-then-verify model that makes any agent workflow safe. Codex runs the command and reads the result; you keep authoring scenarios visually in Apidog and spot-check that the agent reads exit codes honestly. For the broader pattern, see how to use AI agents for API testing and the Apidog AI test harness.
Verify Codex is actually running the CLI
Agents report success they did not earn, and Codex is no exception. Three checks, in order of how often they catch problems.
First, confirm the command ran at all. The Codex interface shows the commands it executed and their output inline. Look for the literal apidog run ... line and a result under it. If Codex says it ran the tests but you do not see the command, it summarized something it never did. Ask it to run again and show raw output.
Second, confirm the exit code, the one that matters:
What was the exit code of that apidog run command?
apidog run exits 0 when every assertion passes and non-zero when anything fails. That single behavior lets Codex, or a pipeline, treat the run as a clean gate. When Codex’s prose says “tests passed” but the exit code is non-zero, the exit code is right.
Third, confirm it used the real scenario. If a run fails with “scenario not found,” Codex may have invented or misremembered an ID. Re-check the -t and -e values against AGENTS.md and the command Apidog generated in the CI/CD tab. The IDs in AGENTS.md are the truth.
Reading the test report
When a run goes red, the report has the answer. With -r cli, Codex gets a readable breakdown in the terminal: each request, each assertion, and which one failed with expected versus actual value. The failing assertion names the exact field or status code, which is usually enough for Codex to find the fix.
For a report you can open in a browser or hand to a teammate, add the HTML reporter
The html reporter writes a self-contained file to ./apidog-reports. Keep cli in the list so Codex still gets the inline output it reads to decide its next step. For every flag and reporter, including the JUnit format CI dashboards parse, see the complete Apidog CLI guide and the apidog run command reference.
Two ways to go deeper than shell commands
Running apidog run from AGENTS.md covers most of what you need. Two routes go further.
The first is MCP. Codex supports the Model Context Protocol, and you add servers with codex mcp add or by editing ~/.codex/config.toml with an [mcp_servers.NAME] block. The Apidog MCP server exposes your API specifications over MCP, so Codex can read your schema while it writes code, not just after the fact. The CLI runs the tests; MCP feeds the agent the spec.
The second is codex exec. Where plain codex opens the interactive interface, codex exec "..." runs Codex non-interactively and pipes the result to stdout, which is what you reach for in scripts and CI. To run apidog run in a pipeline without Codex present, Apidog CLI in GitHub Actions covers the secrets, reporters, and exit-code gating.
When Codex gets it wrong
A few failures show up often during setup.
It ignores the AGENTS.md block. If Codex runs a generic command or none at all, the block may not be loading. Confirm the file is named exactly AGENTS.md and sits at your Git root or a parent of your current directory. A typo in the filename means Codex never reads it; restarting the session forces a fresh read.
It passes an access token anyway. If Codex tries to add --access-token, it is guessing from public examples. The block already tells it not to, since the machine is authenticated via apidog login. Reinforce the line, and never put a real token in AGENTS.md.
It invents a flag. An “unknown option” error means Codex guessed a flag your version does not have. Tell it to run apidog run --help and copy the exact flag from there, which is always correct for your installed version.
It reports a pass on a failed run. The costliest one, and the reason the exit-code rule is in your AGENTS.md and your verification step. When the summary and the exit code disagree, the exit code wins.
From a daily agent to a tested loop
That is the setup. Install apidog-cli once following the install guide, add a short Apidog block to your repo’s AGENTS.md, and Codex knows how to run your API tests and read the result inside the same loop it already uses to edit code. A broken endpoint gets caught while Codex is still working on the change, not after it ships.
A test behind a GUI runs when a human clicks; a one-line command runs whenever Codex decides to. You keep building scenarios visually in Apidog, and your agent runs them where you are not watching. Download Apidog, build one scenario, drop its apidog run command into AGENTS.md, and watch Codex pick it up on the next change.
