> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex Setup

> See and control the tool calls that OpenAI Codex makes on your organization's computers.

> [!NOTE]
>
> Tool call governance is currently in limited beta. Contact Opal support to enable it for your organization.

With Codex connected to [tool call governance](https://docs.opal.dev/docs/tool-call-governance.md), 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](https://docs.opal.dev/docs/tool-call-governance-rules.md). 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](https://docs.opal.dev/docs/openai-chatgpt-setup.md).

## 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](#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.

```bash theme={null}
read -rs OPAL_API_KEY && export OPAL_API_KEY   # paste the key, press Enter
OPAL_URL=https://<your Opal> ./render.sh --out=./opal-codex-kit
```

`render.sh` writes the folder `opal-codex-kit`, which holds your key, and makes it readable only by you. You can add these options:

| Option | What it does |
| - | - |
| `--no-otel` | Sends hook events only, without Codex's own telemetry. |
| `--no-prompts` | Keeps prompts and Codex's replies on the computer. |
| `--managed-only` | Makes Codex ignore every user, project, and plugin hook. This stops a person from adding a hook that changes a call before Opal sees it, but it also stops hooks your developers already use. |

### Install on one Mac or Linux computer

Copy the `opal-codex-kit` folder to the computer and run:

```bash theme={null}
cd opal-codex-kit
sudo ./install.sh
```

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](https://docs.opal.dev/docs/tool-call-governance-rules.md#create-a-rule).

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 you see | What it means | What to do |
| - | - | - |
| `/hooks` shows no Opal hook, or says **Untrusted** | Codex didn't load the requirements. | Check `/etc/codex/requirements.toml`. With a profile on macOS, run `defaults read com.openai.codex`. |
| Nothing in **Activity** | **Log** and **Enforce** are both off for Codex. | Turn one on under **Setup** > **Clients**. |
| Nothing in **Activity**, and no errors in the error log | Tool call governance isn't turned on for your organization. Opal accepts what computers send and doesn't store it. | Contact Opal support. |
| Nothing in **Activity**, and the error log shows 401 or 403 | Opal refused the key. | Check whether someone rotated the organization key. Render the kit again with the current key and reinstall it. |
| A call isn't on the person you expect | None of the emails the computer sent match that person in Opal. | Add `OPAL_HOOK_EMAIL=<their work email>` to `opal-codex-hook.conf` on that computer. |
| A block is ignored | A shell startup file prints text or runs slowly. | Keep `~/.zshenv` and the file that `$BASH_ENV` names quiet and fast. |

## 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.

| Choice | What happens |
| - | - |
| Always (the default) | Opal stores each prompt and each reply that Codex sends. |
| Each person decides | Codex has no option for each person to choose, so Opal stores what the computers send, the same as Always. |
| Never | Opal stores no prompts or replies, whatever the computers send. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.