Skip to main content
Tool call governance is currently in limited beta. Contact Opal support to enable it for your organization.
With Codex connected to tool call governance, Opal sees every tool call that Codex makes on your computers, before the call runs and after it succeeds. Each call appears in Opal on that person’s ChatGPT agent, or on their OpenAI agent if they have no ChatGPT agent. Opal can also stop a call before it runs, using your rules. If Opal is slow or can’t be reached, the call runs anyway. You install the hooks once on each computer, as Codex managed hooks. They cover the Codex command line (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 bash and curl on each computer. Linux computers also need jq. On a Mac, jq is optional, because the hook falls back to a built-in tool without it, but the hook is a little faster with it. brew install jq installs it on macOS. The installer warns you when curl or jq is 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 with https://.
  • 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.
The same organization key works on every computer, and it can only report agent activity. It ends up in files that every user on a computer can read, because Codex runs the hook as each person. Treat it as a reporting key, and keep the rendered kit out of shared drives and source control. If a computer already has /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 with read 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 the opal-codex-kit folder to the computer and run:
The script writes /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, run sudo ./install.sh from your configuration management tool. Running it again changes nothing. On Macs, use your device management tool:
  1. Upload com.openai.codex.mobileconfig as a custom configuration profile.
  2. Put the hook files in /etc/codex/opal/, owned by root. opal-codex-hook.sh has mode 755 and opal-codex-hook.conf has mode 644. Running sudo ./install.sh --hook-only from 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:
  1. The email you configure.
  2. The email of the ChatGPT account Codex is signed in with.
  3. The person’s git email.
  4. The user name on the computer.
If people sign in to Codex with their work ChatGPT account, that’s usually enough. Otherwise, have your device management tool add 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

  1. Start a new codex session. A session that was already running keeps the hooks it started with.
  2. Type /hooks and 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.
  3. Run codex exec "run: echo opal-check". The output shows hook: PreToolUse Completed and hook: PostToolUse Completed.
  4. In Opal, go to Agent Center > Activity. Within a few seconds, the call appears on the person’s agent.
  5. 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 run codex exec "run: echo opal-block-test". Codex prints Command blocked by PreToolUse hook: followed by Opal’s reason, and doesn’t run the command. Delete the rule afterwards. See Rules for Tool Calls.
The Codex desktop app’s Settings > Hooks page says “No hooks found” even while the managed hooks run, because it lists only personal and plugin hooks. Use /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.
The hook doesn’t send what a tool printed. With Codex’s telemetry on, which is the default, Codex’s own events also reach Opal. They include what a tool printed, but Opal reads only whether a command exited with an error, so that a failed command shows as failed, and doesn’t store the output. Opal also records a turn’s estimated cost and how Codex’s sandbox handled a call. Opal turns on conversation content storage for each organization. Until it is on for yours, Opal stores no prompts or replies, whatever you choose in Clients. Contact Opal support to turn it on. Once it is on, each client has its own setting. Go to Agent Center > Setup > Clients, find Codex, and set Store conversation content. If you don’t see Clients, contact Opal support. 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 @codex on 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_modes in requirements.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_ENV names (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.sh from the rendered folder. It removes /etc/codex/opal/, removes /etc/codex/requirements.toml if Opal wrote it, and removes each person’s ~/.opal-codex-hook folder. If you merged Opal’s sections into your own requirements.toml, remove Opal’s [[hooks.*]] entries and its [otel] block yourself.
  • Remove the Mac rollout. Remove the com.openai.codex profile 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.
New Codex sessions stop reporting at once. Running sessions stop when they restart.
Last modified on November 17, 2026