How to Gate an OpenAI Plugin to Specific Products: Manifest Configuration Guide

OpenAI plugins restrict execution to designated products by declaring a products array in the .codex-plugin/plugin.json manifest, which the plugin-evaluator validates at runtime to deny requests from unsupported clients.

Plugin gating in the openai/plugins repository allows developers to restrict where their integrations run. By configuring the manifest file located at .codex-plugin/plugin.json, you ensure your plugin only executes within specific OpenAI products like ChatGPT Web or the Assistants API. This prevents incompatible code from running in environments that lack required UI components or API support.

Understanding the Gating Architecture

The gating mechanism relies on two core components: the manifest declaration and the runtime validator. The manifest defines an array of allowed product identifiers, while the evaluator enforces these constraints during request processing.

When a user invokes a plugin, the platform inspects the incoming request's product context (e.g., ChatGPTWeb, Assistants). It then checks this value against the products array defined in the plugin manifest. If the product is not listed, the plugin-evaluator aborts execution before any business logic runs.

According to the source code in plugins/plugin-eval/src/evaluators/plugin.js, the validation logic extracts the allowed products and performs a membership test:

// plugins/plugin-eval/src/evaluators/plugin.js (excerpt)
const allowedProducts = manifest.products || [];
if (!allowedProducts.includes(requestedProduct)) {
  throw new Error(`Plugin ${manifest.name} is not enabled for ${requestedProduct}`);
}

Configuring the Manifest File

To gate a plugin, you must add the products field to .codex-plugin/plugin.json. This field accepts an array of strings representing supported OpenAI products.

Single Product Gating

Restrict your plugin to a single product by specifying one identifier in the array. For example, to allow execution only in the ChatGPT Web interface:

{
  "name": "data-analytics",
  "version": "1.4.2",
  "description": "Analytics plugin for product-focused insights.",
  "products": ["ChatGPTWeb"]
}

In this configuration, requests originating from the desktop ChatGPT application or other clients receive an error because ChatGPTWeb is the sole permitted product.

Multiple Product Support

To support several environments simultaneously, list all applicable product identifiers:

{
  "name": "data-analytics",
  "version": "1.4.2",
  "description": "Analytics plugin for product-focused insights.",
  "products": ["ChatGPTWeb", "Assistants"]
}

The platform makes the plugin available in any listed environment. Common product identifiers include ChatGPTWeb for the browser interface, ChatGPT for the desktop application, and Assistants for the Assistants API.

Implementation Steps

Follow these steps to implement product gating for your plugin:

1. Locate your manifest at .codex-plugin/plugin.json in your plugin's root directory.
2. Add the products array containing the specific product strings your plugin supports.
3. Validate JSON syntax to ensure the array is properly formatted as strings in double quotes.
4. Deploy the updated manifest to your plugin's distribution channel.
5. Test across products by invoking the plugin from both allowed and disallowed clients to verify the gate functions correctly.

Key Files Reference

File	Purpose	Location
.codex-plugin/plugin.json	Declares plugin metadata and the products gating field	plugins/data-analytics/.codex-plugin/plugin.json
plugins/plugin-eval/src/evaluators/plugin.js	Contains runtime validation logic that enforces product restrictions	plugins/plugin-eval/src/evaluators/plugin.js
plugins/plugin-eval/README.md	Documents evaluator behavior and required manifest fields	plugins/plugin-eval/README.md

Summary

• Product gating uses the products array in .codex-plugin/plugin.json to whitelist permitted OpenAI products.
• Runtime enforcement occurs in plugins/plugin-eval/src/evaluators/plugin.js, which throws an error for unsupported products.
• Multiple products are supported by adding multiple strings to the array.
• Common identifiers include ChatGPTWeb, ChatGPT, and Assistants.

Frequently Asked Questions

What happens if I omit the products field from my manifest?

If the products field is missing, the plugin-evaluator defaults to an empty array, effectively blocking execution on all products. Always explicitly define your supported products to ensure availability.

Can I use the older product field instead of products?

The products array is the current standard. While some legacy implementations may reference a singular product string, the evaluator in openai/plugins expects an array format for multi-product support. Migrate to the array syntax for future compatibility.

How do I test gating without deploying to production?

Configure your local development environment to simulate different product contexts. The plugin-evaluator reads the product identifier from the request headers, so you can test gating by modifying the requestedProduct value in your test requests to verify that disallowed products trigger the appropriate error handling.

Which products support plugin gating?

As defined in the openai/plugins repository, supported products typically include ChatGPTWeb (browser interface), ChatGPT (desktop application), and Assistants (API). Consult the latest plugins/plugin-eval/README.md for the definitive list of valid product identifiers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}