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

# Cowork Setup

> See what Cowork does on your organization's computers, and check its tool calls before they run.

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

Cowork is Claude's agentic workspace in the Claude Desktop app. Cowork runs no hook, so Opal can't check or stop its tool calls from Cowork's own data. You have two ways to connect it to [tool call governance](https://docs.opal.dev/docs/tool-call-governance.md), and you can use both:

* **Telemetry** shows you what Cowork did. Opal reads Cowork's telemetry after each prompt, reply, and tool call, and shows it on the person's Claude agent. Opal can't stop a call this way.
* **Inference hooks** check each tool call before it runs. Anthropic sends Opal the call, Opal checks it against your rules, and a rule can stop it.

For Claude Code, which does run a hook, see [Claude Code Setup](https://docs.opal.dev/docs/tool-call-governance-claude-code.md).

## Requirements

Before you begin, you must:

* Be an Opal Admin. Only admins see the **Setup** tab.
* Be able to change your organization's settings in Claude, on a Team or Enterprise plan.
* Have an Opal organization key for telemetry. If your organization has none, go to **Agent Center** > **Setup** > **Anthropic**, find **Claude Code on Team and Enterprise plans**, and select **Create key**. The same key works for Claude Code and Cowork.
* Use a recent version of the Claude desktop app. Anthropic's [Cowork monitoring](https://claude.com/docs/cowork/monitoring) page lists the versions that Cowork telemetry needs. Claude sends the signed-in person's email with Cowork's telemetry on first-party deployments only. Without it, Opal can't match Cowork rows to a person.
* For inference hooks, have a Claude Enterprise plan and the Owner or Primary owner role in Claude. Only those roles can configure inference hooks.

## Install

### Record Cowork's activity

1. In Opal, go to **Agent Center** > **Setup** > **Anthropic** and find the **Cowork** section. It shows the three values to use.
2. In Claude, go to **Organization settings** > **Data and privacy**. Under **Monitoring**, find **Cowork and Cowork in the cloud**, and set:

   | Setting | Value |
   | - | - |
   | OTLP endpoint | `https://<your Opal>/v1/agent-activity/otlp` |
   | OTLP protocol | `http/protobuf` |
   | OTLP headers | `Authorization=Bearer <your organization key>` |

   The **Cowork** section has a **Copy** button for the endpoint and one for the headers. The page shows the key masked, and the button copies the real key.
3. Save. Cowork reads these settings when a session starts, so sessions that are already running keep their old settings.

### Check Cowork's tool calls before they run

Anthropic's inference hooks send Opal the tool calls that Claude makes before they run, and Opal answers allow or deny. Anthropic leaves out calls to some of claude.ai's own tools. The same setup covers Cowork, Claude Code, and Claude chat. Claude sends these calls on its own, so nothing is installed on any computer.

1. In Opal, go to **Agent Center** > **Setup** > **Anthropic** and find the **Inference hooks** section. Under **Create an Opal API key**, enter a name, choose when the key expires, and select **Create key**. Copy the key, because Opal doesn't show it again. The key has full access to the Opal API, so store it carefully. It's listed under **Settings** > **Personal Access Tokens**, where you can delete it. Renew the key before it expires. After it expires, requests fail, and Claude applies the failure handling that you chose in Claude. With **Block the request**, that blocks every request in your organization.
2. In Claude, go to **Organization settings** > **Data and privacy**, turn on Inference hooks for your organization, and set the endpoint to `https://<your Opal>/v1/inference-hooks/anthropic`. When you save the endpoint, Anthropic shows a signing secret once. Copy it.
3. In Opal, paste the secret into **Signing secret** in the **Inference hooks** section and select **Save**. Anthropic signs each request, and once the secret is saved, Opal rejects a tool call that isn't signed with it. Until you save it, Opal accepts unsigned requests.
4. In Claude, add a custom request header named `Authorization` with the value `Bearer <your API key>`.
5. In Claude, turn on **Enforce verdicts**, and keep **Validate tool calls** on, so that Claude sends tool calls to Opal before they run.

For the other settings in Claude, such as testing the connection, the verdict timeout, and what happens when Opal can't answer, see Anthropic's [Configure Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks-configuration).

Opal handles these calls as follows:

* Opal checks tool calls only. Anthropic also sends prompts to the same address, and Opal allows them without inspecting or recording them.
* Opal checks each tool call against your [rules](https://docs.opal.dev/docs/tool-call-governance-rules.md) and Tool defaults, and answers allow or deny with a reason. Blocked servers and flagged arguments work as they do for other calls.
* One answer covers every tool call in a request. If Opal blocks or holds any call, it denies all of them.
* A rule or Tool default that asks the developer to confirm denies the call, because an inference hook can't ask anyone.
* A rule's **Agent** condition matches the app by name: `cowork` for Cowork, `claude-code` for Claude Code, and `claude-ai` for Claude chat. A rule's **Session** condition never matches these calls, because they don't report a permission mode or a folder.
* A pause on one agent or one person applies only to calls that Opal can match to that agent or person.
* A rule that names a person matches by the email that Anthropic sends. Opal matches the call to a person's Claude agent by the Anthropic user ID that Anthropic sends, which works for agents that your Anthropic connection synced. For a person with no synced agent, the **Agent** column shows their ID or email with an **unknown** tag.
* The **Log** and **Enforce** switches under **Setup** > **Clients** don't apply to these calls. Opal checks and records them whatever those switches say.
* If Opal doesn't answer in time or returns an error, Claude applies the failure handling that you chose in Claude, which either runs the request or blocks it.

## Check that it works

1. Start a new Cowork session and ask it to do something that uses a tool, such as reading a file.
2. In Opal, go to **Agent Center** > **Activity**. Open the runtime filter, which shows **All runtimes**, and choose **Cowork**. After Cowork exports its telemetry, the prompt, the reply, and each tool call appear. The **Agent** column shows the person's Claude agent, with **Cowork** under it.
3. If you set up inference hooks, set the runtime filter back to **All runtimes**, because these rows show no runtime. Use the **Columns** button above the table to show the **Via** column, and look for rows with **inference hook** in that column and Opal's decision, such as **Allowed**.

A passing **Test connection** in Claude doesn't show that Opal checks tool calls, because Opal allows other requests without inspecting them. A tool call with **inference hook** in the **Via** column does.

If nothing appears, check the following:

| What you see | What it means | What to do |
| - | - | - |
| Nothing in **Activity** | The session started before you saved the settings. | Start a new session. |
| Nothing in **Activity** | Cowork's **Log** switch is off. | Turn it on under **Setup** > **Clients**. |
| Claude Code rows appear, but no Cowork rows | Cowork isn't sending telemetry to Opal. The endpoint, protocol, or headers in Claude may be wrong, or the key may have been rotated. | Copy the three values again from the **Cowork** section, save them in Claude, and start a new session. |
| No rows from any runtime | Tool call governance isn't turned on for your organization. | Contact Opal support. |
| No **inference hook** rows | In Claude, **Enforce verdicts** or **Validate tool calls** is off, or the rollout is under 100 percent. Or the API key or signing secret is wrong, so Opal refuses the request. Or the runtime filter is still set to **Cowork**, which hides these rows. | Check each setting in Claude and in the **Inference hooks** section. |
| **inference hook** rows appear, but a rule doesn't stop the call | In Claude, **Mode** under failure handling is **Shadow mode**, or the rollout is under 100 percent, so Claude doesn't enforce Opal's answer. | Check those settings in Claude. |
| An email or ID with an **unknown** tag in the **Agent** column | Opal can't match the row to a Claude agent. | See [Who made the call](https://docs.opal.dev/docs/tool-call-governance-claude-code.md#who-made-the-call). |

## What Opal records

### From telemetry

Opal records each prompt, each reply, and each tool call as its own row. For a tool call, Opal records:

* The tool's name. For an MCP tool, Cowork names the tool `mcp_tool`, and the server's and tool's names arrive only from computers whose `otlpContentCapture` setting lists `toolDetails`.
* How the call ended, **Ran** or **Failed**. The person's agent page shows how long it took, as **Took**.
* The call's arguments, when the computer sends them. Opal masks credentials and personal data, such as email addresses and phone numbers, in the copy it stores. Cowork cuts each string of the arguments at 512 characters and the whole of them at about 4,000 characters, so a long argument can be cut.
* The time of the call.

Opal doesn't store the error text of a failed call.

Opal matches each row to a person by the email of the Claude account that the session is signed in with, and shows it on that person's Claude agent. If a person has no Claude agent, Opal creates one from their first row when your organization has that turned on. Contact Opal support to turn it on.

### From inference hooks

For each tool call that Anthropic sends, Opal records the tool's name and arguments, the MCP server's name when Anthropic gives one, the person Anthropic names, the session, the time, and Opal's decision and reason. Opal masks credentials and personal data in the copy of the arguments that it stores, and your rules match the arguments as sent. These rows carry Opal's decision, not how the call ended, and they show no runtime. Your organization's activity retention period doesn't apply to them.

### Conversation content

The text of prompts and replies is optional. Opal stores it only when both of these are true:

* The person's Claude Desktop sends it. Prompt text arrives from computers whose `otlpContentCapture` setting lists `userPrompts`. Reply text arrives from computers that list `assistantResponses`, or that capture prompts. The `toolDetails` value adds a tool call's arguments and error text. Some older versions of Claude Desktop send content when the setting isn't set. Without content, Opal records each event without its text.
* Conversation content is turned on for your organization. Contact Opal support to turn it on.

Opal masks credentials and personal data in the text it stores, and it cuts long text to a size limit. Cowork has no **Store conversation content** setting, because each computer decides what it sends. If **Log** is off for Cowork, Opal stores nothing from its telemetry.

Admins and read-only admins can see all of this under **Agent Center** > **Activity**, and on the person's agent page. Other users can't.

## What isn't covered

* **Stopping a call from telemetry.** Opal reads Cowork's telemetry after the call, so it doesn't check those calls against your rules, and Cowork has no **Enforce** switch. Use inference hooks to check Cowork's calls before they run.
* **Inference hooks without a Claude Enterprise plan.** Anthropic offers inference hooks only to Claude Enterprise organizations. Anthropic also leaves out calls to some of claude.ai's own tools.
* **Calls that a person rejects in Cowork.** Opal doesn't record them.
* **Prompts that contain a secret.** Opal doesn't check Cowork prompts for secrets before they're sent. It masks the secrets it recognizes in the text it stores.
* **Text from computers that don't send it.** Without the `otlpContentCapture` settings above, Opal records each event without its text.

## Turn it off or remove it

* **Stop Opal recording Cowork's telemetry.** Under **Agent Center** > **Setup** > **Clients**, turn **Log** off for Cowork. Cowork keeps sending, and Opal stores nothing it receives.
* **Stop Cowork sending telemetry.** In Claude, go to **Organization settings** > **Data and privacy** > **Monitoring**, find **Cowork and Cowork in the cloud**, and remove the endpoint and headers you set.
* **Stop checking calls with inference hooks.** In Claude, turn off **Enforce verdicts** on the Inference hooks settings page, and wait about a minute for the change to reach Anthropic's servers. Then delete the API key in Opal if you want to. If you delete the key first and you chose **Block the request** for failure handling in Claude, Claude blocks requests that Opal refuses.
* **Cut off the organization key.** Under **Agent Center** > **Setup** > **Anthropic**, find **Claude Code on Team and Enterprise plans** and select **Rotate key**. The old key stops working at once, and everything that sends with it stops reporting until it gets the new key. This also affects Claude Code computers that send with the organization key. It doesn't affect inference hooks, which use their own API key.


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