OpenAI Codex Setup

Omnodex traces OpenAI Codex in the Codex mode of ChatGPT Desktop, the Codex CLI, and the Codex IDE extension.

What gets installed

There are two independent parts. You can use either one, and the full setup uses both.

Part	What it does	How you install it
Hooks	Record Codex session lifecycle and the tool calls Codex runs locally, such as shell commands and file edits	omnodex install codex in each project
Omnodex MCP server	Routes the MCP servers you choose through the Omnodex proxy, records each call at the MCP protocol layer, and adds the omnodex_status, omnodex_connect, and omnodex_connection_status tools	Register it once per host in Codex settings

omnodex install codex installs hooks only. It does not register the MCP server.

Choose where Codex runs

Codex reads its configuration from the Codex home on the host where it runs. Desktop, CLI, and IDE share configuration only when they run on the same host.

Where Codex runs	Codex config	Omnodex home	Path style
Native Windows (ChatGPT Desktop, or the CLI in PowerShell)	C:\Users\<you>\.codex\config.toml	C:\Users\<you>\.omnodex\	Backslashes
WSL	/home/<you>/.codex/config.toml	/home/<you>/.omnodex/	Forward slashes
macOS	/Users/<you>/.codex/config.toml	/Users/<you>/.omnodex/	Forward slashes
Linux	/home/<you>/.codex/config.toml	/home/<you>/.omnodex/	Forward slashes

ChatGPT Desktop on Windows runs Codex natively; WSL is not required. If you also run the Codex CLI inside WSL, that is a second host with its own configuration and its own Omnodex data. Set up each host you use. Windows and WSL covers running both.

Never mix path styles: do not put C:\... paths in WSL configuration, or /mnt/c/... or ~ in configuration used by native Windows.

Before you start

On the host where Codex runs:

1. Install Omnodex from source, including the omnodex-config.json step for hooks.
2. Find the absolute path of Node.js. Desktop apps may not see the same PATH as your terminal, so the MCP server entry below uses an absolute path.

Windows (PowerShell)

where.exe node
node --version

macOS / Linux / WSL

which node
node --version

On macOS, Homebrew installs Node under /opt/homebrew/bin on Apple Silicon and /usr/local/bin on Intel. Use the path which node prints.

Register the Omnodex MCP server

1. Create the proxy configuration.

   List the upstream MCP servers to route in omnodex-proxy.json in your Omnodex home. The file may list none, in which case the proxy serves only its built-in omnodex_* tools:

   Windows

   C:\Users\<you>\.omnodex\omnodex-proxy.json:

   {
     "version": 1,
     "redact_parameters": false,
     "upstream_servers": [
       {
         "name": "filesystem",
         "transport": "stdio",
         "command": "C:\\Program Files\\nodejs\\npx.cmd",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\<you>\\Documents\\project"]
       }
     ]
   }

   Use the npx.cmd path that where.exe npx prints.

   macOS / Linux / WSL

   ~/.omnodex/omnodex-proxy.json:

   {
     "version": 1,
     "redact_parameters": false,
     "upstream_servers": [
       {
         "name": "filesystem",
         "transport": "stdio",
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/<you>/project"]
       }
     ]
   }

   Replace the example with the MCP servers you want Omnodex to see. Put secrets in environment variables and reference them as ${VAR} in an upstream’s env, never as literal values. See Configuration.

2. Add the server in ChatGPT Desktop.

   Open Settings > MCP servers > Add server, choose STDIO, and enter:

   Field	Value
   Name	omnodex
   Command	Absolute path to Node.js
   Arguments	<repo>/packages/mcp-proxy/dist/bin/omnodex-mcp-proxy.js, --config, and the path to your omnodex-proxy.json

   Use the path style of the host (for example C:\path\to\omnodex\packages\mcp-proxy\dist\bin\omnodex-mcp-proxy.js on Windows). Save, then restart Codex.

3. Or add it from the CLI or a config file.

   codex mcp add writes the same entry to the host’s config.toml, so the Desktop app, CLI, and IDE extension on that host all see it.

   Windows (PowerShell)

   codex mcp add omnodex -- "C:\Program Files\nodejs\node.exe" "C:\path\to\omnodex\packages\mcp-proxy\dist\bin\omnodex-mcp-proxy.js" --config "C:\Users\<you>\.omnodex\omnodex-proxy.json"
   codex mcp list

   In config.toml, TOML literal strings (single quotes) keep backslashes as they are:

   [mcp_servers.omnodex]
   command = 'C:\Program Files\nodejs\node.exe'
   args = [
     'C:\path\to\omnodex\packages\mcp-proxy\dist\bin\omnodex-mcp-proxy.js',
     '--config',
     'C:\Users\<you>\.omnodex\omnodex-proxy.json',
   ]

   macOS / Linux / WSL

   codex mcp add omnodex -- /absolute/path/to/node /path/to/omnodex/packages/mcp-proxy/dist/bin/omnodex-mcp-proxy.js --config /home/<you>/.omnodex/omnodex-proxy.json
   codex mcp list

   In config.toml:

   [mcp_servers.omnodex]
   command = "/absolute/path/to/node"
   args = [
     "/path/to/omnodex/packages/mcp-proxy/dist/bin/omnodex-mcp-proxy.js",
     "--config",
     "/home/<you>/.omnodex/omnodex-proxy.json",
   ]

   To remove it: codex mcp remove omnodex.

4. Verify.

   Start a new conversation, enter /mcp, and confirm omnodex is connected. Ask Codex to call omnodex_status, then to call one of the routed tools. Routed tools appear as <server>__<tool>, for example filesystem__list_allowed_directories.

   Start a new conversation after changing MCP servers. Existing conversations keep the tool list they started with.

Install the hooks

1. Install into the project.

   From the project directory, in the shell of the host where Codex runs:

   omnodex install codex

   This writes Omnodex entries to <project>/.codex/hooks.json. Hooks are enabled by default in Codex; there is no feature flag to set. If hooks do not run at all, check that your config.toml does not contain hooks = false under [features].

   When it finishes, the command offers to connect this host to the hosted dashboard. Press Ctrl+C to skip; the hooks are already installed.

2. Trust the hooks in Codex.

   Codex does not run new project hooks until you trust them. When Codex prompts you to review the hooks for the project, approve the Omnodex entries.

   Codex may report that it clamps the SessionEnd hook timeout to 3 seconds. That is expected; the hook finishes well within it.

3. Verify.

   Start a new conversation in the project and have Codex run a shell command. A session file for it appears under event-log/sessions/ in your Omnodex home.

What gets traced

Activity	Recorded by	Notes
Session start and end	Hooks
Shell commands	Hooks	tool.invoked and tool.completed with timing and status
File edits (apply_patch)	Hooks	Recorded as tool calls, not yet as file.written events
MCP tool calls routed through Omnodex	Omnodex MCP server	Parameters (unless redacted), timing, status, and response size
MCP server sessions	Omnodex MCP server	See the note below about session end
Hosted tools such as web search	Not visible	These run on OpenAI’s side, outside local hooks

Hooks and the MCP server record different layers. A call routed through Omnodex can appear once from each. Use redact_parameters in omnodex-proxy.json to keep parameter values out of the log for any upstream.

When ChatGPT Desktop quits, it may stop the Omnodex MCP server without closing its connection, so the proxy session can be missing its end event. Tool call records are not affected.

Connect to the hosted dashboard

On each host, run:

omnodex connect

This starts a device code flow: the CLI shows a short code and a URL. Open the URL, sign in or create an account, and enter the code. The API token and sync passphrase are stored in stream-config.json in that host’s Omnodex home. The passphrase is transferred end-to-end encrypted.

You can also connect from inside Codex by asking it to call omnodex_connect from the Omnodex MCP server.

If a stream is disconnected or revoked in the dashboard, run omnodex connect again.

View results

omnodex dashboard

Codex events carry interceptor: "codex-hook" (hooks) or interceptor: "mcp-proxy" (MCP server), so you can tell the sources apart in the dashboard.

Troubleshooting

omnodex does not show as connected in /mcp:

• Run the command from the server entry yourself in the host’s shell. It should start and wait for input; press Ctrl+C to stop it. If it exits with a config error, fix omnodex-proxy.json.
• Check that every path in the entry is absolute and uses the host’s path style.
• Restart Codex after any change to MCP servers.

No hook events:

• Run omnodex status in the project to confirm the hooks are installed.
• Confirm you trusted the hooks in Codex for this project.
• Check launcher.log in your Omnodex home. Could not locate codex hook shim means omnodex-config.json is missing or has the wrong codex path.
• The conversation must be in the project where you installed the hooks.

ChatGPT on the web: web sessions, including Codex on the web, do not use the Codex configuration on your machine, so local hooks and the Omnodex MCP server do not see them.

Plugin install: the Omnodex Codex plugin bundles the same MCP server. On native Windows, register the server directly as shown above instead of using the plugin.

Next steps

• Windows and WSL - Running Codex and other agents on both
• Running Detection - Risk detection works the same across all interceptors
• Events and Traces - The event model