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
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 alone flips the plugin into self-hosted mode — no env var is required. 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, audit retention, the custom-policy and HITL-approval limits, or the lack of LLM cost pre-flight — Plugin Pro removes them:
- 30-day audit retention (10× Free)
- 2,000 governed events per day (10× Free)
- Unlimited custom tenant policies (Free: 2 active max)
- Unlimited HITL approvals (Free: 1 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_commandcalls can carrydecision_id,risk_level, and override hints, so shell enforcement failures have enough context to investigate - Codex can use
explain_decision,create_override,delete_override, andlist_overridesthrough 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 operator 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.
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_SECONDSapplies 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/*.jsonand.mcp.jsonwrite 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.
Related Resources
- 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.4.0 | Platform: v7.9.0 | SDKs: Python v8.0.0, TypeScript v8.0.0, Go v8.0.0, Java v8.0.0, Rust v0.2.0 (preview)
