Connect Codex

Codex has three integration paths, from lightest to strongest. They differ in one crucial way: what a phone approval can do. The CLI hook can only block; the bridge and proxy can both allow and deny.

Path	Command	Can grant?	Fail-closed?	Status
PreToolUse hook	ony hooks codex	No (deny only)	Yes, to deny	Beta, verified live against codex-cli 0.144.5
App-server bridge	ony hooks codex-app-server	Yes	Yes, to denied	Experimental (pinned to codex-cli 0.142.x)
Forwarding proxy	ony hooks codex-app-server-proxy	Yes	Yes, to denied	Experimental (pinned to codex-cli 0.142.x)

All three share the same connector and the same server-authoritative policy as the Claude Code plugin. Enroll first:

pip install ony
ony enroll --url <your-ony-url> --email <you>

You are prompted for the password; it is never accepted on the command line.

Path 1: the deny-only hook (beta)

ony hooks codex is a PreToolUse guardrail that uses Codex’s own hook contract. Its semantics are narrower than Claude’s, because Codex’s PreToolUse hook honors only a deny decision:

• A phone denial blocks the action.
• A gate Ony.ai cannot resolve (server unreachable, unverifiable verdict) also fails closed to deny.
• A phone approval does not grant. Codex hooks cannot grant permission, so on approval Ony.ai stands aside and Codex’s own approval flow proceeds.

That is a real guardrail, but not the full fail-closed gate the Claude Code plugin provides. Requires Codex CLI with hooks, version 0.117.0 or newer (verified live against 0.144.5: the hook fires with the expected payload, stands aside for pre-authorized routine work, and blocks a destructive command fail-closed when the gate cannot be resolved).

Codex must trust the hook first

Codex only runs hooks it trusts. After adding or changing the hook, run Codex interactively once and accept the hook trust prompt; headless runs (codex exec) silently skip untrusted hooks. Automation that already vets its hook sources can pass --dangerously-bypass-hook-trust. If the hook never seems to fire, unapproved hook trust is the first thing to check.

One composition note for full-auto sessions: codex exec with approvals disabled (approval: never, for example trusted projects or --full-auto) reports permission_mode: bypassPermissions, and Ony.ai composes with it - in away mode, pre-authorized routine work passes while actionable/high-risk commands (file deletes, cloud teardown, and similar) still gate. With approvals on (the interactive default), away gates every actionable step.

Install the hook by copying clients/codex/hooks.json to ~/.codex/hooks.json (all projects) or to .codex/hooks.json in a single project, or by merging the equivalent [hooks] table into ~/.codex/config.toml:

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

[[hooks.PreToolUse.hooks]]
type = "command"
command = "ony hooks codex"
timeout = 600
statusMessage = "Checking with Ony..."

Project-local .codex/ hooks load only when the project layer is trusted.

Path 2: the app-server bridge

ony hooks codex-app-server is a codex app-server-compatible stdio endpoint that answers approval requests over JSON-RPC. Unlike the hook, it can grant as well as deny, and any decision Ony.ai cannot resolve fails closed to denied. It honors the live /ony mode and uses the same signed-verdict verification as the hook. In-flight approvals are settled as denied on teardown.

Use it where you (or a tool) can point an app-server client directly at a command. Framing and method names are pinned against codex-cli 0.142.x, so treat it as experimental until the app-server protocol stabilizes.

Path 3: the forwarding proxy (VS Code and the desktop app)

The Codex IDE extension and desktop app talk to a codex app-server process over JSON-RPC. ony hooks codex-app-server-proxy sits in that seam: it launches the real codex app-server as a child, passes the whole session through untouched, and intercepts only approval reverse-requests, routing them through Ony.ai. Like the bridge, it can grant as well as deny and fails closed to denied.

• VS Code: point the extension’s chatgpt.cliExecutable setting at a small wrapper script that runs ony hooks codex-app-server-proxy. Extra args are forwarded to the real server. Set ONY_CODEX_BIN if the real codex binary is not on PATH.
• Desktop app: wrap its managed codex binary (WSL on Windows) so it launches the proxy instead.

Caution

Attaching an approval delegate is opting into remote decisions: there is no fallback terminal prompt behind it, so every approval is answered by your phone or fails closed. The proxy honors the live /ony mode. Protocol pinned against codex-cli 0.142.x; treat it as experimental until the app-server protocol stabilizes.

Modes

Control how much Ony.ai gates Codex from any terminal (see the modes page):

ony away     # remote control: phone me for every actionable step
ony on       # at the keyboard: phone me only for high-risk actions
ony off      # do nothing; use Codex's normal approvals
ony status   # show the current mode

For the bridge and proxy, off approves so Codex’s own flow governs, on phones only for high-risk actions, and away phones for everything. Risk is always classified by the Ony.ai server; the client’s hint is ignored, and you decide on the phone keypad, never by voice.

If Ony.ai never calls, run ony doctor and see troubleshooting.