OpenAI Codex + AxonFlow Integration

AxonFlow adds governance to OpenAI Codex through a hybrid model: enforcement on Bash tool calls via PreToolUse hooks, and advisory governance for other tools via skills that instruct the agent to check policies before acting.

Prerequisites: OpenAI Codex CLI plus an AxonFlow agent gateway. Self-host via Docker Compose (Getting Started) for any real workload — see Privacy notice below for why.

Plugin repo: getaxonflow/axonflow-codex-plugin

Governance coverage

Interception point: Codex hooks — PreToolUse / PostToolUse with the matcher Bash | exec_command | shell (per the plugin's hooks.json), backed by advisory skills for other tools.
Governs (enforced): terminal/shell command execution — blocked before it runs when policy denies — plus an audit record.
Does not enforce: file edits, MCP tools, or prompt content. Non-shell tools are covered only advisorily, through skills that instruct the agent to check policy before acting — that is guidance, not a hard pre-execution gate.

See Governance Architecture & Coverage for how this fits the five runtime modes.

Privacy notice

Read before installing. AxonFlow Community SaaS at try.getaxonflow.com is the zero-config endpoint the plugin uses if neither AXONFLOW_ENDPOINT nor AXONFLOW_AUTH is configured. In that mode, governed tool inputs (tool name + arguments) and outbound message bodies are checked by AxonFlow's policy enforcement endpoint and recorded for audit. Community SaaS is offered in two tiers — Free (3-day audit retention, 200 events/day) and Plugin Pro ($9.99 / 90 days, 30-day retention, 2,000 events/day). Both tiers are suitable for individual use within their documented limits. Neither tier is designed for regulated industries, real user data of third parties, or workloads requiring contractual SLOs — see the Privacy Policy for the full scope of what we commit to and what we don't.

For any serious use, choose one of the following instead:

Self-host AxonFlow Community Edition — runs entirely on your infrastructure and keeps data within your boundary. Recommended for any real workload.
Community Edition with an Evaluation License — for production use with real users or clients on the open core; adds production-fit limits and license-gated features. Free 90-day evaluation license.
AxonFlow Enterprise — production-grade governance, regulatory-grade controls, SLOs, and contractual commitments suitable for regulated industries. Contact [email protected].

Setting AXONFLOW_ENDPOINT to a self-hosted AxonFlow URL flips the plugin into self-hosted mode. For a Community Edition self-hosted agent that is enough — no credential is required. For an Enterprise / in-VPC agent you must also authenticate (see Self-hosted / Enterprise authentication), or the agent rejects every call. For air-gapped operation, set AXONFLOW_COMMUNITY_SAAS=0 to suppress the bootstrap attempt and AXONFLOW_TELEMETRY=off to disable the anonymous 7-day heartbeat.

Plugin Pro — paid upgrade for individual developers

$9.99 USD for 90 days. One-time payment, no auto-renewal.

If you're using this plugin against try.getaxonflow.com and outgrowing the Free tier's caps — daily quota, burst limit, audit retention, the custom-policy and HITL-approval limits, or the lack of LLM cost pre-flight — Plugin Pro raises them:

30-day audit retention (10× Free)
2,000 governed events per day (10× Free)
200 governed write events per minute (Free: 25/min)
50 active custom tenant policies (Free: 4 active max)
20 HITL approvals per rolling 7 days (Free: 2 per rolling 7d)
LLM cost pre-flight — see what a multi-step plan costs before it runs (Pro only)
Email support, 2 business-day response
14-day refund window — no questions asked

Buy at getaxonflow.com/pricing → paste your cs_<uuid> tenant ID at Stripe Checkout → receive your AXON-… token by email → install with export AXONFLOW_LICENSE_TOKEN='AXON-...' in your shell profile, or write the token to ~/.config/axonflow/license-token (mode 0600). The next tool-using prompt through codex picks up the token and surfaces Pro tier. Full guide: Plugin Pro install.

Pro is for individual-developer use only. For team/production workloads, self-host Community Edition or contact us about Enterprise.

What This Integration Enables In The Hybrid Governance Model

Codex still uses a hybrid model, but the governed workflow around it is much more usable now. That distinction matters because Codex does not enforce every tool the same way. Terminal execution is hook-enforced, while other actions rely on skills and MCP guidance. Without a common explainability and override model, the user experience after a block can feel fragmented across those two governance paths.

blocked exec_command calls can carry decision_id, risk_level, and override hints, so shell enforcement failures have enough context to investigate
Codex can use explain_decision, create_override, delete_override, and list_overrides through the agent MCP server when a task needs explanation or a short-lived exception
that means the enforced path for terminal work and the advisory path for skills now converge on the same explainability and override model instead of diverging after a deny

The core split is unchanged: Bash and terminal-style tools are still enforced through hooks, while other tools remain advisory through skills. What improves is the unblock experience after a block, especially for teams that want a documented route through Decision Explainability and Session Overrides.

For a senior engineer assessing Codex for governed software delivery, this matters because the same reasoning and exception workflow now spans both sides of the hybrid model. A blocked terminal action can be explained and, if permitted, temporarily unblocked with a visible audit trail. Advisory skills can also steer non-terminal actions through the same explanation and override tools, even though those paths are not enforced the same way. That distinction is important: Codex is strict on the hook side and guidance-driven on the skill side. Making that explicit is what turns the plugin into something a platform team can reason about instead of a fuzzy "guardrails" story.

What Codex Does Well

OpenAI Codex is a cloud-based agentic coding platform with strong execution capabilities:

Cloud-hosted agentic coding with sandboxed execution
MCP server support for external data and tool access
Skill system for composable, reusable agent instructions
Git-integrated development workflows
Task-based asynchronous execution

What Codex Doesn't Provide

Production Requirement	Codex's Position
Policy enforcement before Bash execution	PreToolUse hooks available — governance logic not provided
Policy checks for non-Bash tools	Skills can advise — cannot enforce
PII detection in tool outputs	Not addressed
Audit trails for compliance	Execution logs exist — not compliance-formatted
SQL injection prevention for MCP queries	Not provided
Approval gates for sensitive operations	Not provided

Governance Model

AxonFlow uses a hybrid approach on Codex:

Governance Type	Tool	Mechanism	Enforcement
Enforcement	Bash/exec_command	PreToolUse hook (exit code 2 = block)	Yes — dangerous commands blocked before execution
Advisory	Write, Edit, MCP tools	Skills instruct agent to call `check_policy`	Agent decides — skills guide but cannot force
Audit	All governed tools	PostToolUse hook (Bash) + skills (others)	Automatic for Bash, skill-guided for others

Enforcement (Bash/exec_command): The PreToolUse hook fires on every terminal command (Codex reports these as exec_command), evaluates the command against AxonFlow policies, and blocks it (exit code 2) if it violates policy. This is automatic and cannot be bypassed.

Advisory (other tools): For Write, Edit, and MCP tool calls, governance skills instruct the Codex agent to call check_policy before proceeding. Skills support implicit activation — Codex invokes them automatically when the task matches the skill description. However, the agent ultimately decides whether to follow the skill's guidance.

How AxonFlow Plugs In

Terminal commands (enforced):

Codex selects exec_command tool
    │
    ▼
PreToolUse hook fires automatically
    │ → check_policy("codex.exec_command", "curl 169.254.169.254")
    │
    ├─ BLOCKED (exit 2) → command never runs
    └─ ALLOWED (exit 0) → command executes → PostToolUse audits + PII scans

Other tools (advisory):

Codex selects Write/Edit/MCP tool
    │
    ▼
Governance skill activates (implicit or explicit)
    │ → agent calls check_policy("codex.Write", file content)
    │
    ├─ Policy says blocked → agent should not proceed (advisory)
    └─ Policy says allowed → agent proceeds → audit skill records action

Quick Start: Plugin Installation

# 1. Start AxonFlow (if not already running)
git clone https://github.com/getaxonflow/axonflow.git
cd axonflow && docker compose up -d

# 2. Clone the plugin
git clone https://github.com/getaxonflow/axonflow-codex-plugin.git

# 2a. Optional: increase hook HTTP timeout for remote deployments
export AXONFLOW_TIMEOUT_SECONDS=12

# 3. Configure MCP server in Codex (TOML format in ~/.codex/config.toml)
cat >> ~/.codex/config.toml << 'EOF'

[mcp_servers.axonflow]
url = "http://localhost:8080/api/v1/mcp-server"
EOF

# 4. Enable hooks and place hooks.json
cat >> ~/.codex/config.toml << 'EOF'

[features]
codex_hooks = true
EOF
cp axonflow-codex-plugin/hooks/hooks.json ~/.codex/hooks.json

# 5. Create local marketplace entry (from the directory where you'll run codex)
mkdir -p .agents/plugins
cat > .agents/plugins/marketplace.json << 'EOF'
{
  "name": "axonflow-local",
  "plugins": [{
    "name": "axonflow",
    "source": { "source": "local", "path": "./axonflow-codex-plugin" },
    "policy": { "installation": "INSTALLED_BY_DEFAULT" },
    "category": "Security"
  }]
}
EOF

# 6. Launch Codex and install the plugin via /plugins
codex

In community mode, no auth is needed. The MCP server config must be in ~/.codex/config.toml (TOML format) — Codex does not read .mcp.json from the plugin directory for MCP server connections.

Self-hosted / Enterprise authentication

Community Edition self-hosted — the agent accepts unauthenticated calls; leave AXONFLOW_AUTH unset.
Enterprise / in-VPC agents — the agent requires HTTP Basic auth on every call, including the MCP server connection. Add an env_http_headers block to your [mcp_servers.axonflow] entry so Codex attaches the credential, and point the url at your agent:

[mcp_servers.axonflow]
url = "https://your-agent.internal:8080/api/v1/mcp-server"

[mcp_servers.axonflow.env_http_headers]
"Authorization" = "AXONFLOW_AUTH"
"X-License-Token" = "AXONFLOW_LICENSE_TOKEN"

Codex's env_http_headers maps a header name to the name of an environment variable whose value it sends verbatim. Because Codex does not add the Basic prefix for you, AXONFLOW_AUTH must include it for Codex (unlike the Claude Code and Cursor plugins, where it is the bare base64):

# NOTE the leading "Basic " — required for Codex's verbatim env_http_headers.
export AXONFLOW_AUTH="Basic $(printf '%s:%s' "<org_id>" "<license_key>" | base64 | tr -d '\n')"

Without this, codex mcp get axonflow will connect but every tool call returns an authentication error and governed tools are blocked.

Timeout Tuning

Use AXONFLOW_TIMEOUT_SECONDS when Codex needs to reach AxonFlow over a slower network path, VPN, or remote deployment.

PreToolUse defaults to 8 seconds when unset
PostToolUse defaults to 5 seconds when unset
setting AXONFLOW_TIMEOUT_SECONDS applies the same timeout to all hook HTTP calls

MCP Tools

10 MCP tools are served by the agent's MCP server at /api/v1/mcp-server. The plugin's .mcp.json points Codex at the agent endpoint; the plugin itself doesn't define the tools. Platform-side tool additions are immediately available to Codex.

Governance (6):

Tool	Purpose
`check_policy`	Evaluate specific inputs against policies
`check_output`	Scan specific content for PII/secrets
`audit_tool_call`	Record additional audit entries
`list_policies`	List active governance policies
`get_policy_stats`	Get governance activity summary
`search_audit_events`	Search individual audit records

Session overrides and explainability (4):

Tool	Purpose
`explain_decision`	Return the full DecisionExplanation for a decision ID
`create_override`	Create a time-bounded, audit-logged session override (mandatory justification)
`delete_override`	Revoke an active session override
`list_overrides`	List active overrides scoped to the caller's tenant

When Codex stderr prints a governance block on an exec_command call, the decision ID is included. The agent can call explain_decision with that ID and, if the decision is overridable, create_override to unblock. For non-exec_command tools, the hybrid governance model still applies — the advisory skills will guide Codex to consult these same MCP tools.

Skills

Skill	When Used	Activation
`pre-execute-check`	Before non-Bash tool calls that modify state	Implicit (task matches) or explicit (@axonflow)
`post-execute-audit`	After non-Bash tool calls complete	Implicit or explicit
`pii-scan`	After tool calls that return data	Implicit or explicit
`governance-status`	When checking governance posture	Explicit
`audit-search`	When searching compliance evidence	Explicit
`policy-list`	When listing active policies	Explicit

Skills support implicit activation: Codex invokes them automatically when the current task matches the skill description. For example, if a user asks "write this data to a file", the pre-execute-check skill may activate automatically because the task involves state modification.

Integration-Specific Policies

Set AXONFLOW_INTEGRATIONS=codex or let auto-detection handle it:

.codex-plugin/*.json and .mcp.json write protection (block)

Latency Considerations

Operation	Typical Latency
Policy pre-check (hook)	2-5ms
PII detection	1-3ms
Audit write (async)	0ms (non-blocking)
Total overhead	3-10ms

Troubleshooting

MCP Server Connection Failed

Codex reads MCP config from ~/.codex/config.toml (TOML format), not from .mcp.json in the plugin directory. Add [mcp_servers.axonflow] with url = "http://localhost:8080/api/v1/mcp-server" to your config.toml.

Hooks Not Firing on Bash

Hooks must be at ~/.codex/hooks.json (not inside the plugin directory). Enable hooks with [features] codex_hooks = true in ~/.codex/config.toml. The hook matcher should include exec_command — Codex uses this tool name for terminal commands, not Bash.

Skills Not Activating

Skills activate implicitly when the task matches the description. For explicit invocation, use @axonflow. Ensure the plugin is installed via /plugins in Codex and the MCP server is reachable.

Plugin Not Visible in /plugins

The marketplace.json must be at $CWD/.agents/plugins/marketplace.json relative to where you launch codex. The source.path must be relative (start with ./) and point to a directory inside the same root.

PII in File Writes Not Detected

Codex hooks currently only support Bash (exec_command). Write and Edit operations cannot be hooked. PII detection for file writes depends on advisory skills — the pre-execute-check and pii-scan skills instruct the agent to call check_output before writing, but this is not enforced.

AxonFlow Codex Plugin — Plugin source code (MIT)
Claude Code Integration — Sister plugin with full hook enforcement
Cursor IDE Integration — Sister plugin with same hook architecture
OpenClaw Integration — Plugin for OpenClaw agents
Policy Enforcement — How policies are evaluated
Audit Logging — Compliance audit trails

Telemetry

This plugin sends an anonymous heartbeat at most once every 7 days during activity. Under the v1 telemetry schema, the ping carries telemetry_type=plugin, sdk=codex-plugin, and stream=heartbeat. The payload also includes plugin version, OS, architecture, bash version, and AxonFlow platform version. No PII, no tool arguments, no policy data.

The cadence is gated by a stamp file at $HOME/.cache/axonflow/codex-plugin-telemetry-sent; delete it to force one fresh ping on the next hook invocation.

Opt out with AXONFLOW_TELEMETRY=off. DO_NOT_TRACK is not honored — the Codex CLI injects DO_NOT_TRACK=1 into every hook subprocess regardless of user intent, so it cannot represent a real opt-out signal in this context. See Telemetry for the full wire-level field reference and the scope of AXONFLOW_TELEMETRY=off on Community SaaS vs self-hosted.

Plugin: v1.5.2 | Platform: v9.2.0 | SDKs: Python v8.5.0, TypeScript v8.5.0, Go v8.5.0, Java v8.5.1, Rust v0.7.0 (preview)

Implementation Checklist

Before you put this integration in front of real users, connect it back to the core runtime docs:

choose the request path in Choosing a Mode and Runtime Request Paths
map the policies that should apply in Policy Hierarchy
decide whether tool access belongs behind MCP Policy Enforcement
use Community vs Evaluation vs Enterprise when approval queues, evidence export, SSO, SCIM, or longer retention become rollout requirements

Privacy notice​

Plugin Pro — paid upgrade for individual developers​

What This Integration Enables In The Hybrid Governance Model​

What Codex Does Well​

What Codex Doesn't Provide​

Governance Model​

How AxonFlow Plugs In​

Quick Start: Plugin Installation​

Self-hosted / Enterprise authentication​

Timeout Tuning​

MCP Tools​

Skills​

Integration-Specific Policies​

Latency Considerations​

Troubleshooting​

MCP Server Connection Failed​

Hooks Not Firing on Bash​

Skills Not Activating​

Plugin Not Visible in /plugins​

PII in File Writes Not Detected​

Related Resources​

Telemetry​

Implementation Checklist​