Can I Use Relative Paths in My OpenAI Plugin Configuration? A Complete Guide

Yes, the OpenAI plugin system resolves file paths in plugin.json and .app.json relative to the plugin's root directory, using the relativePath helper function in plugins/plugin-eval/src/lib/files.js to ensure portability across environments.

The openai/plugins repository demonstrates that all asset references—from icons to secondary configuration files—should use relative notation. Whether you are pointing to a logo asset or importing data within a skill script, relative paths ensure your plugin functions correctly regardless of where it is installed on the host filesystem.

How Path Resolution Works in OpenAI Plugins

When the plugin loader encounters a file reference in your configuration, it computes the path relative to the plugin's installation directory. This prevents the brittleness of absolute system paths (like /home/user/...) that break when the plugin is deployed to different environments.

The resolution logic lives in plugins/plugin-eval/src/lib/files.js. The relativePath function calculates the relative path between two locations, ensuring clean path formatting:

// plugins/plugin-eval/src/lib/files.js
export function relativePath(fromPath, toPath) {
  const value = path.relative(fromPath, toPath) || ".";
  // …additional logic for home‑dir and cwd shortcuts…
  return value;
}

This utility guarantees that paths like ./assets/logo.png are interpreted correctly against the plugin root, not the current working directory of the host process.

Configuration Examples Using Relative Paths

Referencing Static Assets in plugin.json

Asset paths for icons and logos must start with ./ to indicate they reside within the plugin folder. The quartr plugin demonstrates this pattern in plugins/quartr/.codex-plugin/plugin.json:

{
  "name": "quartr",
  "version": "1.0.3",
  "description": "Public company IR data and earnings research",
  "interface": {
    "displayName": "Quartr",
    "composerIcon": "./assets/logo.png",
    "logo": "./assets/logo.png",
    "logoDark": "./assets/logo-dark.png"
  },
  "apps": "./.app.json"
}

In this manifest, "composerIcon": "./assets/logo.png" resolves to {plugin_root}/assets/logo.png. Similarly, "apps": "./.app.json" points to a secondary configuration file in the plugin's root directory.

Accessing Files from Skill Scripts

Within skill scripts, you can resolve relative paths from the script's location using Node.js path utilities. This pattern works because the plugin loader maintains the relative structure of the source files:

import path from "node:path";
import fs   from "node:fs";

/* Resolve a file that lives next to this script */
const dataPath = path.resolve(import.meta.url, "../data/sample.json");
const data = JSON.parse(fs.readFileSync(dataPath, "utf‑8"));
console.log(data);

Here, ../data/sample.json navigates up one directory from the script's location to locate the data file, maintaining portability across different installation contexts.

Best Practices for OpenAI Plugin Path Configuration

When authoring plugins in the openai/plugins ecosystem, follow these guidelines to ensure robust path resolution:

• Always use the ./ prefix for files in the plugin root or subdirectories, such as "./assets/icon.png".
• Avoid absolute paths like /Users/name/... or /opt/... which fail when the plugin is copied to different systems.
• Reference secondary configs relatively: Point to .app.json using "./.app.json" rather than assuming file system structure.
• Leverage the relativePath utility if building custom tooling that processes plugin files, ensuring consistency with the core loader's behavior.

Summary

• Relative paths are fully supported in OpenAI plugin configuration files, including plugin.json and .app.json.
• Resolution base: All paths resolve against the plugin's root installation directory.
• Key implementation: The relativePath function in plugins/plugin-eval/src/lib/files.js handles the underlying path computation.
• Best practice: Use ./ or ../ prefixes for all file references to ensure cross-environment compatibility.

Frequently Asked Questions

Can I use absolute paths in my OpenAI plugin configuration?

No, you should avoid absolute paths. The OpenAI plugin system expects portable relative paths (starting with ./ or ../) so that assets resolve correctly regardless of where the plugin is installed on the host filesystem. Absolute paths like /home/user/plugins/... will break when the plugin runs in different environments.

What base directory are relative paths resolved against?

Relative paths in plugin.json and .app.json resolve against the plugin's root directory—the folder containing the configuration file. For example, "./assets/logo.png" in plugins/quartr/.codex-plugin/plugin.json points to plugins/quartr/.codex-plugin/assets/logo.png.

Are parent directory references (../) supported in plugin configurations?

Yes, parent directory references using ../ are supported, though less common for static assets. They resolve relative to the plugin root. Within skill scripts, ../ works as standard Node.js path resolution relative to the executing script's location.

Does relative path resolution apply to both plugin.json and .app.json files?

Yes, the same resolution rules apply to both files. The apps field in plugin.json typically points to "./.app.json", and all paths within .app.json are also resolved relative to the plugin's root directory using the same relativePath utility in plugins/plugin-eval/src/lib/files.js.

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