Configure Agent plugins

Use the console or OpenClaw Control Plane (OCC) CLI to change an existing Agent's plugin selections, then deploy a new version. The CLI example enables the bundled Diffs plugin on an embedded OpenClaw Agent running on Kubernetes. Dedicated Codex Agents use a different catalog and approval policy; see plugin support.

If an existing selection belongs to a different or unknown Driver, save an empty plugin map first. Then select the plugins offered for the Agent's Harness and deploy a new version. This also lets you correct an older embedded OpenClaw Agent whose selections belonged to the Codex Driver.

Use the console

Open Agents, select the Agent, then open Create new version → Plugins. Use Configure plugins to edit saved selections and tool policy. On a dedicated OpenClaw Agent on Kubernetes with the bundled OpenClaw Plugin Driver, choose Google Workspace and add it. Leave Install without an account selected to verify the installation with gog --version. To make Google API calls, choose a ready Google account, save the selection and deploy. The worker receives an OpenShell placeholder for that account. The Gateway loads the skill. The worker can use mapped operations within the account’s configured host, path and OAuth scopes. A command that calls multiple Google services may need more destinations than the selected source permits.

The picker lists compatible sources attached to the Agent. Other sources can stay attached with their own authority. OpenShell requires distinct placeholder names and refuses another credential on a host covered by the Google request guard. The caller needs read and operate on the source, and the Agent needs operate. If the package digest changes, select the account again. Clearing the slot or removing the plugin takes effect on the next deployment. The Agent keeps its separately attached credentials. To stop a running version from using a credential, withdraw the source. Enable the Google request guard

Dedicated Codex Agents with a supported login can browse their app catalog. For other Agents, use Plugin selections JSON to enter a known plugin ID. The CLI example below uses Diffs. For dedicated Codex browsing, the curated catalog needs no Secret. Hosted discovery requires a bound Service Accounts token Secret under Credentials and uses it server-side; other authentication methods cannot browse the hosted catalog. Select Save plugin selections, then Deploy new version. The prior version keeps its original selections. On its Plugins tab, you can inspect that immutable snapshot. See the Plugins tab guide for the controls and deployment status for the result. Catalog visibility alone does not prove that the plugin is installed or available to the running Agent. Hosted discovery uses the Agent's current draft credential, which may differ from its running version's.

For an unavailable plugin, use the information button beside its row to open the reason and any setup link. Press Escape or click outside to dismiss the popover. Selecting the row also shows this guidance in the detail pane; Add stays disabled.

The default approval menu follows the selected Driver's capabilities. Codex offers all four choices; embedded OpenClaw disables all_actions and write_actions. The API rejects those unsupported values as well.

For a selected Codex app, choose write_actions as its default approval and human as its default reviewer to request operator approval for actions Codex does not mark read-only. New app actions inherit that default. Deploy, then check the effective policy and a normal Agent turn; a saved selection alone does not prove approval routing. See the approval policy and runtime proof limits.

Configure a hosted MCP plugin

A hosted MCP package pins its server endpoint and declares a credential slot. OCE discovers available tools using the selected account. On a dedicated OpenClaw Agent, select an attached credential for that slot and the upstream tool names the Agent may call. The worker advertises those tools; the Sandbox enforces the selection for both worker and script calls. See Get started with managed OpenClaw plugins for a complete walkthrough. Managed MCP plugins

The bundled credentialed path uses the OpenShell Sandbox and Credential Gateway Drivers. Configure /usr/local/bin/node in toolBinaries, then register a bearer-token source with the package's MCP host, port, path and placeholder name. Reference the saved access token as its token Secret and set protocol: mcp. Attach the source to the Agent draft and grant the operator and Agent service principal credential_source:operate on it. OpenShell Credential Gateway · Bind a source to an Agent

Allow the OCE API to reach the MCP endpoint for Load tools. For HTTPS port 443, set Helm api.pluginDiscoveryCidrs to the endpoint's IPv4 /32 hosts and refresh them when DNS changes. Other ports need the Installation's managed egress policy. This setting is separate from model discovery. Worker calls use the Sandbox policy.

Open Plugins, add the plugin, choose the account, and choose Load tools. Choose the tools to enable, then save and deploy. Loading tools again refreshes the inventory. Additional tools require selection and deployment before the Agent can use them. An empty selection leaves the worker server disabled. Removing the plugin keeps its independently attached credential; withdraw the source to revoke a running version's credential access.

For example, Slack uses host: mcp.slack.com, port: "443", path: /mcp and env_var: SLACK_MCP_TOKEN. Select slack_search_public if the account advertises it. Inspect its worker server and tool filter:

OPENCLAW_CONFIG_PATH="$OPENCLAW_NODE_STATE_DIR/openclaw.json" openclaw config get nodeHost.mcp.servers.oce_mcp_slack --json

Before you start

Connect the OCC CLI to your Installation. The examples also use Node.js and a protected service-key file.
Choose an Agent configured for embedded OpenClaw on Kubernetes and an Installation that explicitly selects the bundled OpenClaw Plugin Driver (an occ-plugin entry under drivers.plugin); no Plugin Driver is selected by default. See Driver selection. SSH Compute rejects Agents with plugin selections or an Agent default plugin approver policy.
You need permission to read, update, and deploy the Agent, read its Configuration, and read the new Agent revision. Every Agent update, including a plugin-only change, also needs operate on the Agent's Harness authentication Secret or credential source and on each Secret its Configuration binds; without them the update returns 403. Agent revision read is bound per AgentRevision, so a member with only exact grants cannot read the status of an Agent revision that did not exist when the grants were made; an administrator can check it or grant read on that Agent revision. Existing model credential requirements still apply when deploying.
Check the Agent Configuration's tool policy. Selecting Diffs adds it to the tool allowlist. If the Configuration's tools.deny blocks every Diffs tool, for example with "*", "diffs" or "group:plugins", Agent create, update, provisioning and deployment return 400 naming tools.deny and the plugin. A deny-all list would leave no callable tool, so every turn would fail. Remove the matching deny item before selecting Diffs. Create Agent checks the pair before it saves anything, so after this refusal every field stays editable, the Configuration included. If Agent create refuses after the console saved the Configuration, the console names the fix it allows: deselect the plugin and create the Agent, then fix the setting on the Agent's Configuration tab and select the plugin again. With one Agent under agents.entries, its own tools.deny counts too, and the error names it. With several, the error names an Agent whose tools.deny denies all tools with "*", because all of its turns would fail once a plugin is selected. To keep a tool-less Agent, move it to a Configuration without plugins. Denying only Diffs to some Agents is allowed. The deny list under tools.byProvider.<provider> for the primary model's provider counts the same way, at the top level and under an Agent entry. A tools.byProvider object that also has a <provider>/<model> key for that provider is not checked, because OpenClaw may rewrite the model ID it matches.
Check the Configuration's plugin settings. With Diffs enabled, the Gateway does not start when plugins.enabled is false, plugins.deny lists diffs, or a non-empty plugins.allow leaves it out. Configuration save refuses an item in either list that is not text, such as 1. OCE writes the plugins.entries.diffs entry from the selection. The Configuration can hold only an exact copy: {"enabled": true} with Diffs enabled, or {"enabled": false} with it disabled. With an HTTPS gateway.publicOrigin listed in gateway.controlUi.allowedOrigins and Diffs enabled, it must not hold one. Agent create, update, provisioning and deployment return 400 naming the setting.
With one Agent under agents.entries and a minimal, coding or messaging tool profile, the Agent's own tools.alsoAllow replaces the top-level list that grants Diffs, so the request returns 400 unless that list names Diffs, for example "diffs".

Set the Namespace and Agent IDs from your Installation:

bash

export OCC_NAMESPACE='<namespace-id>'export AGENT_ID='<agent-id>'

Select Diffs

Read the Agent's current selections and create an update that keeps them. The API requires configurationId on every Agent update and replaces the whole plugin map; sending only Diffs would remove any other saved selections.

bash

occ agent get "$AGENT_ID" --output json > agent-before-plugins.json node --input-type=module <<'JS'import { readFileSync, writeFileSync } from "node:fs";const agent = JSON.parse(readFileSync("agent-before-plugins.json", "utf8"));const plugins = {  ...agent.plugins,  "occ-plugin:diffs": { enabled: true, toolDefaults: { approval: "provider_default" } },};writeFileSync("agent-plugin-update.json",  JSON.stringify({ configurationId: agent.configurationId, plugins }, null, 2) + "\n");JS occ agent update "$AGENT_ID" --file agent-plugin-update.json --output json

The returned plugins map should contain occ-plugin:diffs with enabled: true. The provider_default policy uses Diffs' existing execution behavior without an added approval step. Agent authorization and sandbox restrictions still apply. The running Agent has not changed yet.

If other people are updating the same Agent, coordinate before submitting: a newer plugin map can be overwritten by the one you read.

Deploy the change

Deploy the Agent and keep the returned version ID:

bash

occ agent deploy "$AGENT_ID" --output json > agent-plugin-revision.jsonDEPLOYMENT_ID="$(node -p "require('./agent-plugin-revision.json').id")"export DEPLOYMENT_ID

Check the result

Use the same protected CLI connection to read the durable deployment result:

bash

occ agent deployment-status "$AGENT_ID" "$DEPLOYMENT_ID" --output json

Repeat the status lookup while the result is queued or running. A succeeded deployment with no warning for Diffs means startup did not report disabling it. It does not prove the plugin is still healthy or that an Agent has used it. A PLUGIN_INSTALL_FAILED warning means that selection was disabled for this startup even if the Agent deployed. Dedicated Codex can also report PLUGIN_AUTH_REQUIRED when a selected app still needs authentication, and for every selected plugin when the Agent authenticates with an API key: Codex plugins need a ChatGPT login, so the Console does not offer plugin browsing for API-key Agents.

To verify that Diffs actually ran, use an Agent client that displays native tool results. An operator can attach with the OpenClaw TUI using the gateway's optional loopback password. Ask the deployed Agent to compare two harmless lines:

text

Call the Diffs tool with before: "old line", after: "new line",path: "example.txt", and mode: "view".

In the client's tool activity, check the actual diffs call and a successful result for the requested file and view mode. Runtime versions may return a structured result rather than Diff viewer ready. A model reply alone does not prove it called the tool. In view mode, Diffs returns a viewer link. It opens in a browser only when the Agent uses native admin access with gateway.publicOrigin set to the Agent's native admin origin; otherwise the link points at the Gateway's private loopback address. Use mode: "file" when you need the rendered diff without a link. The Chat Completions check reads only assistant text; it cannot verify that Diffs ran. The OCC console has no chat. Use the TUI's tool activity for this verification.

For failed, use the returned error and the deployment status reference. Check the plugin ID and supported approval policies before deploying a corrected update.

Verify Linear and approval behavior

For dedicated Codex with the curated Linear app enabled, verify a direct issue read and a separate search/list call through the Agent's actual plugin tools. Use an authorized issue and do not modify it. Record the discovered tool name, arguments, native result and any error code for each call. A successful direct lookup or linear_list_issues call does not establish that an advertised linear_search tool works.

Distinguish missing authentication, missing tool discovery, invalid arguments and backend dispatch errors. For example, Tool search not found with INVALID_ARGUMENT and JSON-RPC -32602 is a failed search dispatch; do not summarize it as no Linear access when another authenticated Linear call succeeds. Do not substitute another API and label the advertised tool successful.

To check write approval, use a uniquely named disposable issue with toolDefaults.approval: write_actions and reviewer: human. Confirm the native UI presents the request, select Deny, and verify the native result records that denial. Do not retry the mutation through another tool. In contrast, toolDefaults.enabled: false disables the plugin's tools; it blocks the write without offering an approval prompt. These are distinct policies, as defined in Agent plugin approval.

Disable or remove a plugin

Read the Agent again before editing its map. Set Diffs to enabled: false to keep the selection but block it, or remove its key to clear the selection. To clear every selection, set plugins to {}. Save and deploy as above. These changes do not interrupt an active turn or immediately revoke a tool; they apply on the next successful deployment.