PluginDriver contract

Overview

PluginDriver supplies a curated catalog, policy capabilities, and policy validation for an Agent Harness. OpenClaw Control Plane (OCC) owns Agent selections, authorization, and Agent revisions. Compute owns native installation, runtime connections, readiness, activation, and retirement. Bundled startup code also translates selected policy into native configuration; those helpers are not methods on the exported Driver interface.

An Installation can enable both bundled Plugin Drivers. The Driver's harnessId identifies its catalog. OpenClaw uses occ-plugin in either execution mode. Dedicated Codex uses codex-plugin. Omitting the setting permits plugin-free deployments. External Plugin Driver packages are not selectable. See Driver selection and the Agent plugin reference.

Interface

Selection and catalogs

The shared interface exposes:

• policyCapabilities: supported default/tool enablement, approval modes, and reviewer arrays per scope, plus the JSON Schema for driverPolicy fields. An empty reviewer array means explicit selection is unsupported at that scope. For IDs marked enablement_only in policyScopeByPlugin, adding the plugin sets enabled: true. The next deployment applies that selection.
• validatePolicies(selections): validate requested policy without installation or authenticated discovery. OCC calls this before save and deployment admission.
• validatePlacement(selections, harness, computeImplementation, credentialRuntime) (optional): check whether the selected packages can run on this Harness and Compute Driver. credentialRuntime gives the implementations of the selected Sandbox Driver and Credential Gateway as {sandbox, gateway}; either can be undefined. A plugin that needs a bound credential can refuse an Installation that cannot deliver it. OCC checks placement before saving selections and again when it admits deployment.
• credentials (optional): credential slots for plugins that use an Agent's credential sources. The Driver receives only source metadata that OCC authorized, never credential values. choices(sources) returns each slot with the attached ready sources that match it. OCC returns them as credentialSlots in a dedicated Agent's plugin capabilities. validate(selections, sources, modelSourceId) refuses a binding that names no matching attached source, or the source that authenticates the model. OCC calls it at Agent create, update, provisioning, and deployment.
• validateAgentConfiguration(selections, configuration) (optional): check selections against the Agent's Configuration values at Agent create and update, provisioning, and deployment, which checks again because a Configuration save does not know its Agents. A ConfigurationHarnessError naming the setting becomes 400; other refusals get fixed text.
• listCatalog(context): read the catalog for a Namespace, Agent, Harness, native Configuration, and abort signal.

Catalog entries contain id, name, and tools. tools:null means unknown; tools:[] means the observed inventory was empty for that read. Each tool has an opaque id, name, and ownerId. Description, availability, and safe unavailability reasons are optional metadata; destructive and writes annotations are also optional. Missing classifications mean unknown. A Driver can set selectableWithoutTools when selection is allowed despite an unknown inventory. An entry does not grant access, select a plugin, or prove the policy can run.

Optional logoUrl supplies a public HTTPS presentation image. Bundled Codex reads release.interface.logo_url, then composer_icon_url; missing or invalid URLs are omitted. Console loads these images without PAT/account headers or referrers, and shows initials if an image fails. URLs may expire and are never copied into Agent selections. Console CSP permits HTTPS images while retaining same-origin scripts and connections.

Optional websiteUrl, privacyPolicyUrl, and termsOfServiceUrl provide public HTTPS links in plugin details. An unavailable entry can include unavailableHelp as {label, url}. Discovery pages can include setup: {message, links}, where each link has the same shape. The selected Driver owns these explanations and destinations; Console renders them without vendor-specific setup logic. This metadata never enters Agent selections and does not verify app connections, grant access, or configure credentials. Connection verification and deployment gates are not part of this metadata contract.

Authorized GET /installation exposes each enabled catalog's Harness, Driver identity and policy capabilities. See the capability response.

There is no exported install, enable, policy-translation, or preparation method. The optional backend reader in bundled Codex is different from the required listCatalog method: without that reader, an explicit catalog call fails, but saving Agent selections and deploying supported selections can still use the Agent runtime's discovery path.

Two optional methods serve pre-Agent discovery: discoverCatalog({accessToken?, cursor?, q?}, signal?) returns {plugins, nextCursor, setup?}, and getCatalogPlugin({accessToken?, pluginId}, signal?) returns plugin details. Here pluginId is the opaque remoteId from a discovery entry; the entry's id is the stable selection key. The HTTP routes are POST /namespaces/:namespaceId/agents/plugins and its /details child. Include the target harnessId in each request. OCC resolves the catalog before it reads a credential. The selected Driver reports pluginDiscovery.credential in Installation capabilities as required or none. When required, supply exactly one of accessToken, secretRef, or credentialSource. Stored references use {kind, namespaceId, id} with kind secret or credential_source. For credential-free discovery, omit all three. For details also provide pluginId; for discovery you can provide q (up to 1,024 characters) and cursor. The Driver searches the complete catalog; an empty query lists it. Keep the same query while paging and omit the cursor when changing the query. Both routes require Agent create in the Namespace. Stored references must belong to that Namespace and require caller operate on the exact source. OCC uses SecretDriver withValue for Secrets. For CredentialSources, the trusted bundled OpenShell Backend reader performs ordinary metadata lookup and operator-mTLS export; an external Credential Gateway retains its optional withSourceToken callback. Both paths require the same exact Gateway owner match and Namespace checks, with no fallback to another Gateway or tenant. OCC checks authorization, source readiness, attachment where required, and the selected catalog before retrieval, then rechecks before catalog dispatch. Credentials pass to the PluginDriver in server memory; refresh remains with its owner. For PAT discovery, the bundled Codex Driver derives the account ID from the PAT. Clients do not provide an account ID. A Secret reference to another Namespace returns 400 INVALID_REQUEST. After caller authorization, a missing Secret returns 404. A missing or non-ready explicitly selected CredentialSource returns 409 RESOURCE_CONFLICT. A Secret backend ownership mismatch returns 404, a denied grant returns 403, and an unavailable backend returns a safe dependency error. A rejected PAT returns PLUGIN_DISCOVERY_CREDENTIALS_REJECTED; rotate the Secret and retry. For details of an ID that a bundled catalog (occ-plugin or the curated codex-plugin catalog) does not offer, the Driver throws the unknownPlugin refusal that admission uses. OCC returns 400 INVALID_REQUEST that names the ID and, if the ID only omits the version, the versioned ID. Hosted Codex discovery does not recognize unknown IDs: a provider error returns the unavailable discovery error.

Discovery does not store catalog results and returns Cache-Control: no-store. Authorization denials emit authorization_denial audit events. The controller signals the selected Plugin Driver when the HTTP client disconnects during a catalog or detail request for a new or saved Agent. Credential values do not appear in catalog responses or audit events; responses that echo a credential are rejected. A missing PluginDriver method reports unsupported discovery, and a SecretDriver without transient value use cannot serve Secret-backed requests. These methods do not require an existing Agent, plugin installation, or runtime connection. See bundled selection and catalog setup.

IAM

OCC authorizes the exact Agent operation. Reading or changing Agent selections does not grant provider access, plugin permissions, or approval to perform a plugin action. Plugin approval settings are separate from platform IAM, workload isolation, and the external provider's authentication. Runtime credentials use the existing Harness and ServiceAccount path; never put credential values or native command output in startup diagnostics. The Driver supplies no sandbox, egress grant, filesystem grant, approval service, OAuth interface, or IAM hook. See Agent plugin permissions and authorization.

Lifecycle

Preparation and security

Trusted startup creates the selected bundled Driver and validates its configuration. The shared interface has no startup, shutdown, or uninstall operation. Saving an Agent's requested plugin map validates supported policy, but does not perform authenticated catalog discovery; saved entries remain readable even if the original Driver is unavailable. An Agent revision with nonempty selections records the selected Driver's ID and implementation and the requested IDs and policies, not credential values or native release metadata.

At runtime, Compute and the bundled preparation helpers resolve current native metadata, translate supported policy, and apply it to the specified Agent revision before declaring readiness. Nonempty selections cannot start with a missing, changed, or Harness-incompatible Driver. Agent save, provisioning and deployment refuse a Harness the Driver cannot run (400): bundled OpenClaw plugins need an OpenClaw Harness, bundled Codex plugins require a dedicated Codex Harness. An unsupported policy or unsafe native configuration prevents startup or leaves the version unready. Retries reuse the requested IDs and policy; they may resolve a newer curated release at that later startup. Saving a selection is not evidence that it can start.

Only two recognized native outcomes can become optional plugin warnings: PLUGIN_INSTALL_FAILED and PLUGIN_AUTH_REQUIRED, attributed to the requested pluginId. They contain no native output or credentials. Other discovery, configuration, policy, transport, cancellation, or malformed-response errors remain startup failures. See bundled preparation and security and Compute startup warnings.

Limits

Native mappings and limits

• A catalog entry does not guarantee that its policy can be enforced by a given Harness. The current bundles reject policy they cannot represent; see the native support table.
• Callers cannot choose arbitrary sources or versions. SSH Compute rejects every nonempty plugin map; an empty selection remains supported for its embedded Harness.
• Agent enablement does not manage account-wide installation. A disabled selection can remain installed while its execution is blocked locally.
• A catalog response, rendered configuration, or direct MCP call does not prove native Agent execution. See current mappings; the feature matrix preserves an older review snapshot.

Troubleshooting

Implementations

• Bundled OpenClaw and Codex Drivers: occ-plugin serves OpenClaw in either mode and codex-plugin serves dedicated Codex.
• PluginDriver feature matrix: historical capability review with pinned source evidence.

Related

Source and verification

• Bundled Driver source, runtime translator, and trusted selection
• Agent plugin runtime flow, deployment, and verification guide
• Implementation proof requirements