Codex Setup

Agent Keeper integrates with Codex through Codex command hooks. The adapter normalizes Codex tool events into the same Runtime Shield policy engine used by Claude Code, Cursor, Windsurf, Copilot, and Cowork.

What gets monitored

Surface	Enforcement
Shell commands (`bash`, `exec_command`, `shell`)	Block or warn before execution
File reads	Block, warn, or audit based on read-path policy
File writes and patches (`write_file`, `apply_patch`)	Block or warn before execution
Prompts	Block or warn before the agent continues
MCP tool calls (`mcp__server__tool`)	Block, warn, allow-list, or audit
Web fetch/search	Enforced when Codex emits the tool event

Installation

Get your API key from Settings > API Keys, then run the public installer:

export AGENTKEEPER_API_URL="https://YOUR_AGENTKEEPER_URL"
export AGENTKEEPER_API_KEY="ak_live_..."
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide codex

The installer stores the API key in ~/.agentkeeper/config, installs ~/.agentkeeper/hooks/codex/agentkeeper-hook.sh, and updates ~/.codex/config.toml.

Generated config

[features]
codex_hooks = true

[[hooks.PreToolUse]]
matcher = "*"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "bash \"$HOME/.agentkeeper/hooks/codex/agentkeeper-hook.sh\""
timeout = 5

[[hooks.PostToolUse]]
matcher = "*"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "bash \"$HOME/.agentkeeper/hooks/codex/agentkeeper-hook.sh\""
timeout = 5

[[hooks.UserPromptSubmit]]
matcher = "*"

[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "bash \"$HOME/.agentkeeper/hooks/codex/agentkeeper-hook.sh\""
timeout = 5

Codex reads hooks from the user-level config above. For managed rollout, deploy the same ~/.codex/config.toml block and hook script through device management.

Tool name mapping

Codex tool name	Agent Keeper canonical name
`bash`, `shell`, `exec_command`	`Bash`
`read_file`	`Read`
`write_file`	`Write`
`apply_patch`, `edit`	`Edit`
`grep`, `search`	`Grep`
`glob`, `list_files`	`Glob`
`web_fetch`	`WebFetch`
`mcp__server__tool`	MCP skill policy

Verify coverage

Open the project in Codex after installing hooks.
Ask Codex to run ls.
Check Activity for a codex event.
Toggle Team → Policies → AI Coding Agents → Access Control → Codex to disable or re-enable org-wide access.

Notes

Codex hooks are fail-open by design. If Agent Keeper is unreachable, the adapter returns allow so developers are not blocked by local network or dashboard outages. Codex hook support requires the codex_hooks feature flag; the installer enables it and the E2E suite verifies the generated config with the local Codex CLI.