How to Integrate with OpenAI's API Using a Plugin: Complete Implementation Guide

You integrate with OpenAI's API using a plugin by leveraging the openai-developers plugin as a credential gate, which automatically provisions API keys and handles error recovery before your custom skills execute HTTP calls to https://api.openai.com/v1/*.

The openai/plugins repository provides a declarative framework for building Codex plugins that connect to external services. Instead of writing boilerplate authentication logic, you compose skills—markdown-driven actions defined by YAML agents—that reuse the openai-platform-api-key and openai-api-troubleshooting utilities to securely manage API access.

Understanding the Plugin Architecture

Every plugin in the repository follows a strict directory layout that separates configuration from implementation.

Plugin Manifest (plugins/<plugin-name>/.codex-plugin/plugin.json): Declares the plugin metadata, version, and skill directory path. This is the entry point Codex reads to load your plugin.

App Manifest (plugins/<plugin-name>/.app.json): Defines the bridge to the OpenAI Platform, including authentication flows and endpoint configurations.

Skills (plugins/<plugin-name>/skills/<skill-name>/): Contain the actual functionality. Each skill includes:

• SKILL.md: Markdown documentation describing inputs, outputs, and behavior.
• agents/openai.yaml: Configuration specifying the model, temperature, and tools (including HTTP endpoints).

Agents (agents/openai.yaml): These YAML files instruct Codex how to invoke the skill. They reference environment variables like {{ env.OPENAI_API_KEY }} and define HTTP tools for POST requests to the OpenAI API.

The OpenAI Developers Plugin

The plugins/openai-developers directory houses two critical skills that form a credential gate for any integration:

openai-platform-api-key: As implemented in plugins/openai-developers/skills/openai-platform-api-key/SKILL.md, this skill checks for an existing OPENAI_API_KEY environment variable. If missing, it prompts the user through the OpenAI Platform picker and writes the key to a local .env file.

openai-api-troubleshooting: Located at plugins/openai-developers/skills/openai-api-troubleshooting/SKILL.md, this skill intercepts API failures (401 authentication errors, quota limits, or network blocks) and routes users to appropriate remediation flows.

When you build a plugin that calls OpenAI endpoints, you declare a dependency on these skills rather than handling credentials manually.

Implementing Your OpenAI API Integration

Follow these steps to create a new plugin that securely calls the OpenAI API.

Scaffolding a New Plugin

Use the provided helper script to generate the correct directory structure:

python .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
    --name my-openai-assistant \
    --description "A simple chat assistant powered by the OpenAI API"

This creates the standard layout including plugins/my-openai-assistant/.codex-plugin/plugin.json and the skills/ directory.

Configuring the Plugin Manifest

Edit the generated plugins/my-openai-assistant/.codex-plugin/plugin.json to declare your plugin metadata:

{
  "name": "my-openai-assistant",
  "version": "0.1.0",
  "description": "A simple chat assistant powered by the OpenAI API",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://github.com/yourname"
  },
  "skills": "./skills/",
  "interface": {
    "displayName": "My OpenAI Assistant",
    "shortDescription": "Chat with GPT-4 in a custom UI",
    "brandColor": "#3B82F6",
    "composerIcon": "./assets/icon.png"
  }
}

Defining the Agent and Skills

Create the skill directory structure at plugins/my-openai-assistant/skills/chat/ and add the agent configuration in agents/openai.yaml:

model: gpt-4
temperature: 0.7
tools:
  - name: openai_chat
    type: http
    method: POST
    url: https://api.openai.com/v1/chat/completions
    headers:
      Authorization: "Bearer {{ env.OPENAI_API_KEY }}"
    body:
      model: gpt-4
      messages: "{{ messages }}"

Then document the skill in SKILL.md:

# Chat with GPT-4

Use this skill to send a list of messages to `chat/completions` and receive the model's reply.

## Input

- `messages` – an array of `{role, content}` objects.

## Output

- The `assistant` message returned by the API.

Place any UI assets (icons, logos) in plugins/my-openai-assistant/assets/ to ensure marketplace compatibility.

How the Credential Flow Works

When a user invokes your plugin, the execution follows this sequence:

1. Invocation: ChatGPT loads your plugin and reads the plugin.json manifest.
2. Credential Check: The openai-platform-api-key skill verifies OPENAI_API_KEY exists. If absent, it executes the provisioning flow before your skill runs.
3. API Execution: Your agent makes the HTTP POST to https://api.openai.com/v1/chat/completions using the stored key.
4. Error Handling: If the API returns a 401 or 429 error, the openai-api-troubleshooting skill parses the response, distinguishes between authentication and quota issues, and either retries or redirects to the credential gate.

This declarative approach means you can add new OpenAI endpoints (embeddings, fine-tuning, or image generation) by writing new SKILL.md files and updating the agents/openai.yaml tools array, without modifying the underlying authentication infrastructure.

Summary

• Reuse the credential gate: Always depend on plugins/openai-developers skills to handle OPENAI_API_KEY provisioning rather than implementing custom key management.
• Follow the manifest structure: Place your configuration in .codex-plugin/plugin.json and .app.json to ensure Codex recognizes your plugin.
• Define agents in YAML: Use agents/openai.yaml to declare HTTP tools that reference {{ env.OPENAI_API_KEY }} for secure API calls.
• Document in markdown: Write SKILL.md files to describe inputs and outputs, making your skills discoverable and maintainable.
• Use scaffolding tools: Run create_basic_plugin.py from .agents/skills/plugin-creator/scripts/ to ensure correct file layouts.

Frequently Asked Questions

What is the purpose of the .codex-plugin/plugin.json file?

The plugin.json file serves as the entry point that Codex reads to load your plugin. It declares the plugin name, version, author information, and the path to the skills directory, as specified in the repository's plugin JSON specification.

How does the OpenAI Developers plugin handle API key security?

The openai-platform-api-key skill securely creates or reuses an OPENAI_API_KEY and writes it to a local .env file. It prompts the user about existing keys and stores them safely, ensuring downstream skills never handle raw credentials in code.

Can I integrate with OpenAI endpoints other than chat completions?

Yes. You can integrate with any OpenAI endpoint (embeddings, fine-tuning, image generation) by creating a new skill with a SKILL.md description and an agents/openai.yaml that defines an HTTP tool pointing to the specific endpoint URL, such as https://api.openai.com/v1/embeddings.

What happens when an API call fails?

The openai-api-troubleshooting skill detects common failure modes including network blocks, invalid keys, and quota limits. It parses the error response and routes the user to the appropriate remediation flow, either retrying with escalated permissions or redirecting to the credential gate for key regeneration.

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