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, AxonFlow v6.0.0+ running (docker compose up -d)

Plugin repo: getaxonflow/axonflow-codex-plugin

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_SECONDS applies the same timeout to all hook HTTP calls

MCP Tools

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

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

Plugin: v0.1.0 | Platform: v6.0.0

What Codex Does Well​

What Codex Doesn't Provide​

Governance Model​

How AxonFlow Plugs In​

Quick Start: Plugin Installation​

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​