Codex CLI 0.146 Agent Plugins: migrate manifests and publish safely
Quick answer
OpenAI released Codex CLI 0.146.0 on July 29, 2026. The release adds Agent Plugins manifest support, exposes workspace plugin publishing capability, and expands marketplace compatibility. The safe rollout is not “upgrade and publish”:
- Decide whether the workflow should remain one skill or become an installable plugin.
- Choose one manifest authority and document any Codex-specific overlay.
- Test the package through a local marketplace in a new Codex session.
- Publish to a workspace only when the server explicitly reports that capability.
- Verify installation, skill discovery, MCP authentication, hooks, connector actions, sandbox policy, and rollback separately.
The most important boundary is that package availability does not grant connector access or runtime permission. A plugin can install correctly while its MCP server, external identity, write actions, or local commands remain unavailable—and that separation is a safety feature.
Who this is for
This guide is for developers maintaining Codex skills, MCP servers, or team workflows that need to move from a personal folder into a repeatable package. It is especially useful when the same capability should work across Codex and ChatGPT-supported surfaces without giving every user the same external permissions.
If one focused workflow already works as a skill, keep it there until installation, sharing, or server-backed tools create a real packaging need. The AI coding sandbox checklist remains the authority baseline: distribution does not widen what the workflow is allowed to read, execute, or publish.
What changed in Codex CLI 0.146
The official changelog groups several plugin changes in 0.146.0. Codex can now recognize a root plugin.json using the Agent Plugins 1.0 schema, map portable metadata plus skills/ and mcp.json, and apply Codex-specific apps, hooks, and interface settings from the com.openai extension. A legacy .codex-plugin/plugin.json can act as a fallback overlay.
The implementation deliberately rejects unsupported Agent Plugins schema versions. It also limits portable skill discovery to direct child folders and excludes paths that resolve outside the plugin root. Those rules turn path layout and schema version into release gates, not cosmetic conventions.
Workspace publishing is separately capability-gated. The app-server can return nullable canPublishToWorkspace metadata; clients are expected to fail closed when the capability is absent or unavailable. Do not infer permission from a visible workspace name, a successful personal install, or an administrator role.
Choose the smallest package shape
| Need | Start with | Add later only when needed |
|---|---|---|
| Repeatable instructions using existing tools | One skill | Package it when sharing and installation become necessary |
| Controlled calls to an external service | MCP server | Add a skill to guide multi-step use |
| Workflow instructions plus service tools | Skill + MCP server plugin | Add UI only for inspection or confirmation |
| Structured comparison, editing, or navigation | MCP server with optional UI | Keep headless tool results useful |
For a skills-only plugin, OpenAI's builder documentation shows a minimal package with .codex-plugin/plugin.json and direct child skill folders:
release-review/
├── .codex-plugin/
│ └── plugin.json
└── skills/
└── release-review/
└── SKILL.md
Codex 0.146.0 also understands the portable root Agent Plugins manifest. Do not create two independent sources of truth. Record which manifest is authoritative, which fields are portable, and which Codex-only behavior comes from com.openai or the fallback overlay.
Migration workflow
1. Inventory capability and authority
List every skill, script, MCP tool, connector, hook, UI resource, scheduled template, and external write action. For each item, record its input, output, authentication identity, filesystem or network reach, and rollback method.
2. Normalize the package boundary
Keep skills as direct children of the configured skills directory. Reject nested discovery, symlink escapes, undeclared executables, secrets, generated build output, and paths outside the plugin root. Validate the schema version before copying or publishing the package.
3. Separate portable and Codex-only behavior
Portable metadata, skills, and MCP configuration belong in the Agent Plugins package. Apps, hooks, or interface settings that only Codex understands need an explicit Codex boundary. A reviewer should be able to remove the Codex extension and predict what remains.
4. Test through a local marketplace
Install the package from a local marketplace, inspect its details, enable it, and start a new Codex session. Installed skills and tools are loaded for new sessions; an already-running session is not reliable acceptance evidence.
Run one positive case, one missing-auth case, one denied-action case, and one uninstall/reinstall case. If the plugin uses MCP, verify both tool schemas and the external service identity rather than accepting a successful connection screen.
5. Gate workspace publication
Only show or use workspace publishing when canPublishToWorkspace is explicitly available. Treat null, missing metadata, API errors, or stale catalogs as “not allowed.” A personal marketplace remains the safe fallback while capability or policy is unresolved.
6. Recheck the permission chain
Workspace plugin availability, bundled skills, connector access, connector actions, source-system authorization, and runtime sandbox policy are separate controls. Start with read actions. Add writes only after reviewing scopes, confirmation behavior, external effects, and recovery.
Eight rollout gates
| Gate | Passing evidence |
|---|---|
| Package purpose | One bounded job and one named owner |
| Manifest authority | Portable fields and Codex overlay have no conflicting source of truth |
| Path boundary | Only intended direct-child skills resolve inside the plugin root |
| Local install | Fresh session discovers the expected skills and tools |
| MCP and auth | Tool schema, identity, scopes, and denied state are verified |
| Workspace capability | Publication is offered only when explicitly supported |
| Runtime policy | Hooks, connector actions, sandbox, and approvals match the threat model |
| Rollback | Disable, uninstall, connector revocation, and previous package restore are tested |
Pair release claims with evidence in the same way as the Qwen Code Goal verification checklist. “The plugin appeared in the catalog” proves discovery, not that its workflow, permissions, or rollback work.
Copyable rollout record
plugin_rollout:
codex_version: "0.146.0"
purpose: "one bounded workflow"
shape: "skills-only | mcp-only | skills-and-mcp | mcp-with-ui"
manifest_authority: "root plugin.json | .codex-plugin/plugin.json"
codex_extension: "none | reviewed com.openai boundary"
marketplace: "local | personal | workspace | public"
workspace_capability: "explicit true | unavailable"
identities: ["Codex user", "connector user", "service account if any"]
write_actions: ["none by default"]
acceptance: ["fresh-session discovery", "denied state", "rollback"]
rollback: "disable, uninstall, revoke connector, restore prior package"
This is an operating record, not an OpenAI manifest schema.
Common mistakes
Turning every skill into a plugin. Packaging adds installation, versioning, permissions, and support work. Keep a personal workflow as a skill until sharing or tools justify the bundle.
Maintaining two competing manifests. A portable manifest and Codex overlay need explicit precedence. Duplicated fields that drift create ambiguous releases.
Testing in the session used for installation. Start a new session before checking skill or tool availability.
Treating workspace visibility as publish permission. Workspace publishing must fail closed unless the capability is explicitly reported.
Equating installation with authorization. Connector login, source-system access, action permissions, and the Codex sandbox still apply independently.
Shipping hooks without reviewing side effects. Hooks can execute around lifecycle events. Apply the same command, network, and secret review used for a strict egress allowlist.
FAQ
Does Codex CLI 0.146 require migrating every existing plugin?
No. The release preserves the legacy .codex-plugin/plugin.json path as a fallback overlay. Migrate when portable Agent Plugins compatibility provides a concrete sharing benefit, and validate precedence before switching.
Can one plugin work in both ChatGPT and Codex?
OpenAI documents one universal public plugin directory for supported surfaces. Individual capabilities can still be surface-specific, and plugins are not available in every ChatGPT or Codex surface.
Can an installed plugin write to an external service automatically?
Not merely because it is installed. Connector access, action controls, source-system authorization, and runtime approval policy remain separate.
Top comments (0)