Tool call governance is currently in limited beta. Contact Opal support to enable it for your organization.
codex and codex exec), the desktop app, the IDE extensions for VS Code, Cursor, and Windsurf, the Codex SDKs, and the GitHub Action on a self-hosted runner. People can’t switch them off.
To sync your OpenAI organization’s agents into Opal instead, see OpenAI and ChatGPT.
Requirements
Before you begin, you must:- Be an Opal Admin. Only admins see the Setup tab.
- Have Mac or Linux computers with Codex CLI 0.166.0. Opal tested Codex CLI 0.166.0 on Linux, where hooks are on by default. Other versions haven’t been tested, and Windows isn’t supported yet.
- Have admin rights (
sudo) on each computer, or a device management tool such as Jamf, Kandji, or Intune. - Have
bashandcurlon each computer. Linux computers also needjq. On a Mac,jqis optional, because the hook falls back to a built-in tool without it, but the hook is a little faster with it.brew install jqinstalls it on macOS. The installer warns you whencurlorjqis missing. - Have the Codex kit, a folder with
render.sh,install.sh, and the hook files. Contact Opal support to get it. - Know your Opal address, for example
https://app.opal.dev. It must start withhttps://. - Have your organization key. In Opal, go to Agent Center > Setup > Anthropic and create the organization key if your organization has none. Select Copy settings and paste the settings somewhere private. The key is the value of
OPAL_HOOK_TOKEN. Opal doesn’t display the key on the page, so copying the settings is how you get it. - Decide whether Opal may store conversations. Opal turns on conversation content storage for each organization, and until it is on for yours, Opal stores no prompts or replies. See What Opal records.
/etc/codex/requirements.toml or a com.openai.codex profile, you merge Opal’s sections into it instead of replacing it.
Install
Render the kit
Run this in the kit folder on your admin computer. Reading the key withread keeps it out of your shell history.
render.sh writes the folder opal-codex-kit, which holds your key, and makes it readable only by you. You can add these options:
Install on one Mac or Linux computer
Copy theopal-codex-kit folder to the computer and run:
/etc/codex/opal/opal-codex-hook.sh, /etc/codex/opal/opal-codex-hook.conf, and /etc/codex/requirements.toml. If a requirements.toml that Opal didn’t write is already there, the script stops. Merge the [hooks], [features], and [otel] sections of Opal’s file into yours, then run sudo ./install.sh --hook-only.
New Codex sessions pick up the hooks. Sessions that were already running need a restart.
Roll out to every computer
On Linux, runsudo ./install.sh from your configuration management tool. Running it again changes nothing.
On Macs, use your device management tool:
- Upload
com.openai.codex.mobileconfigas a custom configuration profile. - Put the hook files in
/etc/codex/opal/, owned by root.opal-codex-hook.shhas mode 755 andopal-codex-hook.confhas mode 644. Runningsudo ./install.sh --hook-onlyfrom the rendered folder does exactly that.
Tell Opal who each person is
The key doesn’t say who made a call. Opal uses the first of these emails that matches a person it knows:- The email you configure.
- The email of the ChatGPT account Codex is signed in with.
- The person’s git email.
- The user name on the computer.
OPAL_HOOK_EMAIL=<their work email> to opal-codex-hook.conf on each computer.
If a person has neither a ChatGPT agent nor an OpenAI agent in Opal, Opal can create one from their first call when your organization has that turned on. Ask Opal support about it.
Check that it works
- Start a new
codexsession. A session that was already running keeps the hooks it started with. - Type
/hooksand pick PreToolUse. Opal’s hook shows Source: Admin config and Trust: Managed, and the footer says Managed (always on). Check PostToolUse and PermissionRequest the same way. - Run
codex exec "run: echo opal-check". The output showshook: PreToolUse Completedandhook: PostToolUse Completed. - In Opal, go to Agent Center > Activity. Within a few seconds, the call appears on the person’s agent.
- To test a block, make sure Enforce is on for Codex under Setup > Clients. Create a rule that blocks calls with arguments matching
*opal-block-test*, then runcodex exec "run: echo opal-block-test". Codex printsCommand blocked by PreToolUse hook:followed by Opal’s reason, and doesn’t run the command. Delete the rule afterwards. See Rules for Tool Calls.
/hooks in the command line instead.
If the call doesn’t appear, the error log lists the time, address, and HTTP status of each failed send. It never holds the key or the call. On Mac and Linux it’s ~/.opal-codex-hook/errors.log. Then check the following:
What Opal records
For every call, Opal receives:- The tool’s name and arguments, for example the shell command, the patch text, file paths, or the arguments of an MCP tool. Arguments are sent as they are, so a secret pasted into a command is in them. Opal masks credentials and personal data, such as email addresses and phone numbers, in the copy it stores. Your rules match the arguments as sent.
- Who the person is, as labels: the email you configure, the email of the ChatGPT account Codex is signed in with, the git email, the user name on the computer, and the computer’s name. If a person signed in to Codex with a personal account, that address is sent.
- When sessions, turns, and sub-agents start and end, the model, and the permission mode.
- For each request to the model, the model, how the request ended, and the token counts.
- With Log on, whether a prompt held a secret and which kinds. Opal never receives the secret. This check runs on Mac and Linux computers.
- The time of the call.
Opal masks secrets and personal data in the text and cuts long text to a size limit. The setting changes what Opal stores. It doesn’t stop Codex from sending prompts and replies, so the computers still send them when Opal stores none. To keep them on the computer, render the kit with
--no-prompts. These settings apply to your whole organization, and Opal picks up a change within a few minutes without a reinstall.
Next to it, Log decides what Opal records, and Enforce decides whether rules can block a call. With Log off and Enforce on, Opal records only the calls that a rule acted on, and stores no conversation content.
What isn’t covered
- Codex cloud tasks (chatgpt.com/codex, and
@codexon GitHub) run in OpenAI’s containers, so the hooks don’t run for them. - Windows isn’t supported yet.
- Delivery through Codex’s cloud-managed requirements. Opal hasn’t tested it. Use the install script or your device management tool.
- Typing into a shell that’s already open. Opal checks the call that opens an interactive shell, but not what is typed into it afterwards. Add a rule that blocks interactive interpreters, or limit
allowed_sandbox_modesinrequirements.toml. - Rules that ask the developer to confirm. Codex can’t ask, so it refuses a call that such a rule matches, with a message that says so.
- A noisy shell startup file. Codex runs the hook through the session’s shell. If
~/.zshenv(zsh) or the file that$BASH_ENVnames (bash) prints text or runs slowly, Codex can ignore Opal’s block. - A determined person. The hooks run as the person using the computer. They monitor computers that cooperate, and they aren’t a barrier against someone who is set on getting around them.
- When Opal is slow or down. Codex runs the call without Opal’s check. Opal waits 3 seconds, and Codex itself gives up on a hook after 5.
Turn it off or remove it
- Switch Codex off for everyone. Under Agent Center > Setup > Clients, turn Log and Enforce off for Codex. A client with both off sends nothing that Opal stores, and its tool calls run without Opal’s check. Opal picks up the change within a few minutes, with no reinstall.
- Stop Opal storing conversations. Set Store conversation content to Never for Codex.
- Remove it from one Mac or Linux computer. Run
sudo ./uninstall.shfrom the rendered folder. It removes/etc/codex/opal/, removes/etc/codex/requirements.tomlif Opal wrote it, and removes each person’s~/.opal-codex-hookfolder. If you merged Opal’s sections into your ownrequirements.toml, remove Opal’s[[hooks.*]]entries and its[otel]block yourself. - Remove the Mac rollout. Remove the
com.openai.codexprofile in your device management tool, and run the uninstall script on each Mac to remove the hook files. - Replace the key. Rotating the organization key under Setup > Anthropic stops every computer that has the old key from reporting, including Codex computers. Render the kit again with the new key and install it again.